GeoJSON Modelica Translator (GMT)
---------------------------------
.. image:: https://github.com/urbanopt/geojson-modelica-translator/actions/workflows/ci.yml/badge.svg?branch=develop
:target: https://github.com/urbanopt/geojson-modelica-translator/actions/workflows/ci.yml
.. image:: https://coveralls.io/repos/github/urbanopt/geojson-modelica-translator/badge.svg?branch=develop
:target: https://coveralls.io/github/urbanopt/geojson-modelica-translator?branch=develop
.. image:: https://badge.fury.io/py/geojson-modelica-translator.svg
:target: https://badge.fury.io/py/geojson-modelica-translator
Description
-----------
The GeoJSON Modelica Translator (GMT) is a one-way trip from GeoJSON in combination with a well-defined instance of the system parameters schema to a Modelica package with multiple buildings loads, energy transfer stations, distribution networks, and central plants. The project will eventually allow multiple paths to build up different district heating and cooling system topologies; however, the initial implementation is limited to 1GDH and 4GDHC.
The project is motivated by the need to easily evaluate district energy systems. The goal is to eventually cover the various generations of heating and cooling systems as shown in the figure below. The need to move towards 5GDHC systems results in higher efficiencies and greater access to additional waste-heat sources.
.. image:: https://raw.githubusercontent.com/urbanopt/geojson-modelica-translator/develop/docs/images/des-generations.png
Getting Started
---------------
It is possible to test the GeoJSON to Modelica Translator (GMT) by simply installing the Python package and running the
command line interface (CLI) with results from and URBANopt SDK set of results. However, to fully leverage the
functionality of this package (e.g., running simulations), then you must also install the Modelica Buildings
library (MBL) and Docker. Instructions for installing and configuring the MBL and Docker are available
`here <docs/getting_started.rst>`_.
To simply scaffold out a Modelica package that can be inspected in a Modelica environment (e.g., Dymola) then
run the following code below up to the point of run-model. The example generates a complete 4th Generation District
Heating and Cooling (4GDHC) system with time series loads that were generated from the URBANopt SDK using
OpenStudio/EnergyPlus simulations.
.. code-block:: bash
pip install geojson-modelica-translator
# from the simulation results within a checkout of this repository
# in the ./tests/management/data/sdk_project_scraps path.
# generate the system parameter from the results of the URBANopt SDK and OpenStudio Simulations
uo_des build-sys-param sys_param.json baseline_scenario.csv example_project.json
# create the modelica package (requires installation of the MBL)
uo_des create-model sys_param.json example_project.json model_from_sdk
# test running the new Modelica package (requires installation of Docker)
uo_des run-model model_from_sdk
More example projects are available in an accompanying
`example repository <https://github.com/urbanopt/geojson-modelica-translator-examples>`_.
Architecture Overview
---------------------
The GMT is designed to enable "easy" swapping of building loads, district systems, and network topologies. Some
of these functionalities are more developed than others, for instance swapping building loads between Spawn and
RC models (using TEASER) is fleshed out; however, swapping between a first and fifth generation heating system has
yet to be fully implemented.
The diagram below is meant to illustrate the future proposed interconnectivity and functionality of the
GMT project.
.. image:: https://raw.githubusercontent.com/urbanopt/geojson-modelica-translator/develop/docs/images/des-connections.png
As shown in the image, there are multiple building loads that can be deployed with the GMT and are described in the `Building Load Models`_ section below. These models, and the associated design parameters, are required to create a fully runnable Modelica model. The GMT leverages two file formats for generating the Modelica project and are the GeoJSON feature file and a System Parameter JSON file. See the more `comprehensive
documentation on the GMT <https://docs.urbanopt.net/geojson-modelica-translator/>`_ or the `documentation on
URBANopt SDK <https://docs.urbanopt.net/>`_.
Building Load Models
++++++++++++++++++++
The building loads can be defined multiple ways depending on the fidelity of the required models. Each of the building load models are easily replaced using configuration settings within the System Parameters file. The 4 different building load models include:
#. Time Series in Watts: This building load is the total heating, cooling, and domestic hot water loads represented in a CSV type file (MOS file). The units are Watts and should be reported at an hour interval; however, finer resolution is possible. The load is defined as the load seen by the ETS.
#. Time Series as mass flow rate and delta temperature: This building load is similar to the other Time Series model but uses the load as seen by the ETS in the form of mass flow rate and delta temperature. The file format is similar to the other Time Series model but the columns are mass flow rate and delta temperature for heating and cooling separately.
#. RC Model: This model leverages the TEASER framework to generate an RC model with the correct coefficients based on high level parameters that are extracted from the GeoJSON file including building area and building type.
#. Spawn of EnergyPlus: This model uses EnergyPlus models to represent the thermal zone heat balance portion of the models while using Modelica for the remaining components. Spawn of EnergyPlus is still under development and currently only works on Linux-based systems.
Raw data
{
"_id": null,
"home_page": "https://docs.urbanopt.net",
"name": "geojson-modelica-translator",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<3.13",
"maintainer_email": "",
"keywords": "URBANopt,Modelica,GeoJSON,Physics-based Modeling",
"author": "URBANopt DES Team",
"author_email": "nicholas.long@nrel.gov",
"download_url": "https://files.pythonhosted.org/packages/fa/21/b6c9ac1aebee5471edebda65990dd13c94d9263565d18218a7677fd85ce6/geojson_modelica_translator-0.6.0.tar.gz",
"platform": null,
"description": "GeoJSON Modelica Translator (GMT)\n---------------------------------\n\n.. image:: https://github.com/urbanopt/geojson-modelica-translator/actions/workflows/ci.yml/badge.svg?branch=develop\n :target: https://github.com/urbanopt/geojson-modelica-translator/actions/workflows/ci.yml\n\n.. image:: https://coveralls.io/repos/github/urbanopt/geojson-modelica-translator/badge.svg?branch=develop\n :target: https://coveralls.io/github/urbanopt/geojson-modelica-translator?branch=develop\n\n.. image:: https://badge.fury.io/py/geojson-modelica-translator.svg\n :target: https://badge.fury.io/py/geojson-modelica-translator\n\nDescription\n-----------\n\nThe GeoJSON Modelica Translator (GMT) is a one-way trip from GeoJSON in combination with a well-defined instance of the system parameters schema to a Modelica package with multiple buildings loads, energy transfer stations, distribution networks, and central plants. The project will eventually allow multiple paths to build up different district heating and cooling system topologies; however, the initial implementation is limited to 1GDH and 4GDHC.\n\nThe project is motivated by the need to easily evaluate district energy systems. The goal is to eventually cover the various generations of heating and cooling systems as shown in the figure below. The need to move towards 5GDHC systems results in higher efficiencies and greater access to additional waste-heat sources.\n\n.. image:: https://raw.githubusercontent.com/urbanopt/geojson-modelica-translator/develop/docs/images/des-generations.png\n\nGetting Started\n---------------\n\nIt is possible to test the GeoJSON to Modelica Translator (GMT) by simply installing the Python package and running the\ncommand line interface (CLI) with results from and URBANopt SDK set of results. However, to fully leverage the\nfunctionality of this package (e.g., running simulations), then you must also install the Modelica Buildings\nlibrary (MBL) and Docker. Instructions for installing and configuring the MBL and Docker are available\n`here <docs/getting_started.rst>`_.\n\nTo simply scaffold out a Modelica package that can be inspected in a Modelica environment (e.g., Dymola) then\nrun the following code below up to the point of run-model. The example generates a complete 4th Generation District\nHeating and Cooling (4GDHC) system with time series loads that were generated from the URBANopt SDK using\nOpenStudio/EnergyPlus simulations.\n\n.. code-block:: bash\n\n pip install geojson-modelica-translator\n\n # from the simulation results within a checkout of this repository\n # in the ./tests/management/data/sdk_project_scraps path.\n\n # generate the system parameter from the results of the URBANopt SDK and OpenStudio Simulations\n uo_des build-sys-param sys_param.json baseline_scenario.csv example_project.json\n\n # create the modelica package (requires installation of the MBL)\n uo_des create-model sys_param.json example_project.json model_from_sdk\n\n # test running the new Modelica package (requires installation of Docker)\n uo_des run-model model_from_sdk\n\nMore example projects are available in an accompanying\n`example repository <https://github.com/urbanopt/geojson-modelica-translator-examples>`_.\n\nArchitecture Overview\n---------------------\n\nThe GMT is designed to enable \"easy\" swapping of building loads, district systems, and network topologies. Some\nof these functionalities are more developed than others, for instance swapping building loads between Spawn and\nRC models (using TEASER) is fleshed out; however, swapping between a first and fifth generation heating system has\nyet to be fully implemented.\n\nThe diagram below is meant to illustrate the future proposed interconnectivity and functionality of the\nGMT project.\n\n.. image:: https://raw.githubusercontent.com/urbanopt/geojson-modelica-translator/develop/docs/images/des-connections.png\n\nAs shown in the image, there are multiple building loads that can be deployed with the GMT and are described in the `Building Load Models`_ section below. These models, and the associated design parameters, are required to create a fully runnable Modelica model. The GMT leverages two file formats for generating the Modelica project and are the GeoJSON feature file and a System Parameter JSON file. See the more `comprehensive\ndocumentation on the GMT <https://docs.urbanopt.net/geojson-modelica-translator/>`_ or the `documentation on\nURBANopt SDK <https://docs.urbanopt.net/>`_.\n\nBuilding Load Models\n++++++++++++++++++++\n\nThe building loads can be defined multiple ways depending on the fidelity of the required models. Each of the building load models are easily replaced using configuration settings within the System Parameters file. The 4 different building load models include:\n\n#. Time Series in Watts: This building load is the total heating, cooling, and domestic hot water loads represented in a CSV type file (MOS file). The units are Watts and should be reported at an hour interval; however, finer resolution is possible. The load is defined as the load seen by the ETS.\n#. Time Series as mass flow rate and delta temperature: This building load is similar to the other Time Series model but uses the load as seen by the ETS in the form of mass flow rate and delta temperature. The file format is similar to the other Time Series model but the columns are mass flow rate and delta temperature for heating and cooling separately.\n#. RC Model: This model leverages the TEASER framework to generate an RC model with the correct coefficients based on high level parameters that are extracted from the GeoJSON file including building area and building type.\n#. Spawn of EnergyPlus: This model uses EnergyPlus models to represent the thermal zone heat balance portion of the models while using Modelica for the remaining components. Spawn of EnergyPlus is still under development and currently only works on Linux-based systems.\n\n",
"bugtrack_url": null,
"license": "BSD-4-Clause",
"summary": "Package for converting GeoJSON to Modelica models for Urban Scale Analyses.",
"version": "0.6.0",
"project_urls": {
"Documentation": "https://docs.urbanopt.net/geojson-modelica-translator/",
"Homepage": "https://docs.urbanopt.net",
"Repository": "https://github.com/urbanopt/geojson-modelica-translator"
},
"split_keywords": [
"urbanopt",
"modelica",
"geojson",
"physics-based modeling"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d796fbd43dc1cb4b68b87c4d4fc0e7a97215f4f6fd4fb586763294c6b5403926",
"md5": "fa309c08306be403d80d63f0813226f5",
"sha256": "a83ed4d0cb004c30de202965980f5c7368151453762363081254c0bfdc51285c"
},
"downloads": -1,
"filename": "geojson_modelica_translator-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa309c08306be403d80d63f0813226f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<3.13",
"size": 532811,
"upload_time": "2024-01-12T15:31:17",
"upload_time_iso_8601": "2024-01-12T15:31:17.988849Z",
"url": "https://files.pythonhosted.org/packages/d7/96/fbd43dc1cb4b68b87c4d4fc0e7a97215f4f6fd4fb586763294c6b5403926/geojson_modelica_translator-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fa21b6c9ac1aebee5471edebda65990dd13c94d9263565d18218a7677fd85ce6",
"md5": "47cf7a059658375989c984af35ecac3a",
"sha256": "92e0e9099bd75c984603547a3440071b47cfd9d35e159c55e4b371e844293a4c"
},
"downloads": -1,
"filename": "geojson_modelica_translator-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "47cf7a059658375989c984af35ecac3a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<3.13",
"size": 397008,
"upload_time": "2024-01-12T15:31:21",
"upload_time_iso_8601": "2024-01-12T15:31:21.774348Z",
"url": "https://files.pythonhosted.org/packages/fa/21/b6c9ac1aebee5471edebda65990dd13c94d9263565d18218a7677fd85ce6/geojson_modelica_translator-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-12 15:31:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "urbanopt",
"github_project": "geojson-modelica-translator",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "geojson-modelica-translator"
}
JSON
