diff --git a/.cspell.json b/.cspell.json index 81a8d98f9..eef542024 100644 --- a/.cspell.json +++ b/.cspell.json @@ -2,9 +2,12 @@ "version": "0.2", "language": "en", "words": [ + "ambr", "armhf", "autoload", + "blackbox", "borefield", + "buildingslibrary", "buildingspy", "buildx", "Combi", @@ -19,23 +22,36 @@ "HVAC", "IBPSA", "interconnectivity", + "IWEC", "Jing", "levelname", "libfortran", "linecount", + "markdownlint", + "massflow", "maxdepth", "mfrt", "microgrid", + "miniconda", + "mkdocs", + "mkdocstrings", "Modelica", "MODELICAPATH", "mofile", + "mopt", "nllong", "nrel", "openstudio", "Optimica", "oversizing", + "pycache", + "pyenv", + "pylint", + "pyproject", + "pytest", "redeclarations", "Reparse", + "searchpath", "setpoint", "tanushree", "Templatized", @@ -43,7 +59,10 @@ "timestep", "timesteps", "urbanopt", - "vtnate" + "venv", + "virtualenv", + "vtnate", + "weatherfile" ], "flagWords": [ "hte" diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e47cd976a..77fa7637a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,5 +1,9 @@ #### Any background context you want to provide? + #### What does this PR accomplish? + #### How should this be manually tested? + #### What are the relevant tickets? + #### Screenshots (if appropriate) diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 000000000..79ec5bf89 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,9 @@ +{ + "default": true, + "MD013": false, + "MD003": { + "style": "atx" + }, + "MD041": false, + "MD024": false +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index eec19b4b9..b59272af6 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -44,7 +44,7 @@ repos: pass_filenames: false # https://docs.astral.sh/ruff/integrations/#pre-commit - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.6.9 + rev: v0.8.3 hooks: # Run the linter - id: ruff @@ -52,3 +52,14 @@ repos: args: [--fix, --exit-non-zero-on-fix, --output-format=full, --unsafe-fixes] # Run the formatter - id: ruff-format + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.43.0 + hooks: + - id: markdownlint + name: markdownlint + entry: markdownlint --fix + language: node + types: [markdown] + args: [ + "--config", ".markdownlint.json" + ] diff --git a/CHANGELOG.md b/CHANGELOG.md index 270e4a020..db0e12a2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,92 +3,96 @@ ## Version 0.8.0 ### Exciting New Features 🎉 -* Add default cop values for 5G district heat pump efficiencies by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/640 -* Support international weather locations by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/654 -* Support multiple GHEs in a single district by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/644 -* Adds method to process modelica results by @tanushree04 in https://github.com/urbanopt/geojson-modelica-translator/pull/646 -* Simplify sys params to closer match reality by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/659 -* Templates and tests for horizontal piping modeling by @JingWang-CUB in https://github.com/urbanopt/geojson-modelica-translator/pull/627 -* Support single building DES templates by @nllong in https://github.com/urbanopt/geojson-modelica-translator/pull/670 + +* Add default cop values for 5G district heat pump efficiencies by @vtnate in +* Support international weather locations by @vtnate in +* Support multiple GHEs in a single district by @vtnate in +* Adds method to process modelica results by @tanushree04 in +* Simplify sys params to closer match reality by @vtnate in +* Templates and tests for horizontal piping modeling by @JingWang-CUB in +* Support single building DES templates by @nllong in ### Other Changes -* Improve cli typing & validation by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/662 -* Add detail to Docker setup docs for Windows users by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/643 -* Use the correct ETS heat pump COP by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/642 -* Use feature ids in load names instead of simple_uuid by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/652 -* Remove alfalfa from conftest.py by @nllong in https://github.com/urbanopt/geojson-modelica-translator/pull/665 -* Update version of Jinja by @nllong in https://github.com/urbanopt/geojson-modelica-translator/pull/667 -* Clean up sys-param code that reads parameters by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/668 -**Full Changelog**: https://github.com/urbanopt/geojson-modelica-translator/compare/v0.7.0...v0.8.0 +* Improve cli typing & validation by @vtnate in +* Add detail to Docker setup docs for Windows users by @vtnate in +* Use the correct ETS heat pump COP by @vtnate in +* Use feature ids in load names instead of simple_uuid by @vtnate in +* Remove alfalfa from conftest.py by @nllong in +* Update version of Jinja by @nllong in +* Clean up sys-param code that reads parameters by @vtnate in + +**Full Changelog**: ## Version 0.7.0 ### Exciting New Features 🎉 -* Rename new modelica models to clarify MBL version by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/618 -* Minor improvements to the CLI by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/620 -* Enable more detail when specifying district types by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/622 -* Force a dummy value for SHW in modelica loads even if not present by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/626 + +* Rename new modelica models to clarify MBL version by @vtnate in +* Minor improvements to the CLI by @vtnate in +* Enable more detail when specifying district types by @vtnate in +* Force a dummy value for SHW in modelica loads even if not present by @vtnate in ### Other Changes -* Move README and CHANGELOG to markdown and update deployment notes by @nllong in https://github.com/urbanopt/geojson-modelica-translator/pull/615 -* Update instructions for releasing documentation publicly by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/617 -* Specify units of GHE flow_rate by @vtnate in https://github.com/urbanopt/geojson-modelica-translator/pull/623 -* Code documentation cleanup by @nllong in https://github.com/urbanopt/geojson-modelica-translator/pull/631 -* Expose borehole variables by @nllong in https://github.com/urbanopt/geojson-modelica-translator/pull/630 -**Full Changelog**: https://github.com/urbanopt/geojson-modelica-translator/compare/v0.6.0...v0.7.0 +* Move README and CHANGELOG to markdown and update deployment notes by @nllong in +* Update instructions for releasing documentation publicly by @vtnate in +* Specify units of GHE flow_rate by @vtnate in +* Code documentation cleanup by @nllong in +* Expose borehole variables by @nllong in + +**Full Changelog**: ## Version 0.6.0 ### Exciting New Features 🎉 -- Python 311 by \@vtnate in -- add max_electrical_load to building sys-param data by \@vtnate in -- Modifications for GHE by \@tanushree04 in -- Add Level 1 5G DES system by \@nllong in -- Set SWH peak to 1/10th of space heating or min 5000W by \@nllong in -- Added GHE templates - Issue511 by \@JingWang-CUB in -- Add MOS file wrapper and size the 5G mass flow rate by \@nllong in -- Add OpenModelica compatibility by \@vtnate in -- Modify GHE params by \@tanushree04 in -- Fixing borefield test breaks due to schema changes by \@JingWang-CUB in -- Updating GHE Parameters: Modifying GHE Parameters schema and example files by \@tanushree04 in -- Enable compile & simulate with OpenModelica in Docker by \@vtnate in -- Enhance and expand microgrid templates and code by \@vtnate in -- Enable numberOfIntervals run option by \@nllong in -- Breakout package parser class by \@nllong in -- Add a new GHE district test with new network template models by \@JingWang-CUB in -- Add GHE Properties to System Parameter File by \@tanushree04 in -- Use `filNam` parameter for TEASER loads and add within parsing to PackageParser by \@nllong in -- Add new `ModelicaProject` class by \@nllong in -- Add Dymola runner by \@nllong in -- Template initial microgrid subsystem example by \@vtnate in -- Microgrid heating by \@vtnate in -- Change how ModelicaPaths are built so they also work on Windows computers by \@vtnate in -- Refactoring and enhancing to support multiple GHEs in a single district by \@vtnate in -- Replace shell script with call directly to docker by \@vtnate in -- Implement a PyPI release workflow by \@vtnate in -- Support Python 3.12 by \@vtnate in -- Add district nominal pump head to system parameters file by \@JingWang-CUB in +* Python 311 by \@vtnate in +* add max_electrical_load to building sys-param data by \@vtnate in +* Modifications for GHE by \@tanushree04 in +* Add Level 1 5G DES system by \@nllong in +* Set SWH peak to 1/10th of space heating or min 5000W by \@nllong in +* Added GHE templates - Issue511 by \@JingWang-CUB in +* Add MOS file wrapper and size the 5G mass flow rate by \@nllong in +* Add OpenModelica compatibility by \@vtnate in +* Modify GHE params by \@tanushree04 in +* Fixing borefield test breaks due to schema changes by \@JingWang-CUB in +* Updating GHE Parameters: Modifying GHE Parameters schema and example files by \@tanushree04 in +* Enable compile & simulate with OpenModelica in Docker by \@vtnate in +* Enhance and expand microgrid templates and code by \@vtnate in +* Enable numberOfIntervals run option by \@nllong in +* Breakout package parser class by \@nllong in +* Add a new GHE district test with new network template models by \@JingWang-CUB in +* Add GHE Properties to System Parameter File by \@tanushree04 in +* Use `filNam` parameter for TEASER loads and add within parsing to PackageParser by \@nllong in +* Add new `ModelicaProject` class by \@nllong in +* Add Dymola runner by \@nllong in +* Template initial microgrid subsystem example by \@vtnate in +* Microgrid heating by \@vtnate in +* Change how ModelicaPaths are built so they also work on Windows computers by \@vtnate in +* Refactoring and enhancing to support multiple GHEs in a single district by \@vtnate in +* Replace shell script with call directly to docker by \@vtnate in +* Implement a PyPI release workflow by \@vtnate in +* Support Python 3.12 by \@vtnate in +* Add district nominal pump head to system parameters file by \@JingWang-CUB in ### Other Changes -- specify ports for each time series building in instance template by \@vtnate in -- Update license language by \@nllong in -- Read correct data from sys-param for microgrid electrical load by \@vtnate in -- Prep for prerelease 0.6.0 by \@nllong in -- initialize empty variable before potential use by \@vtnate in -- Include 5G partial model in generation by \@nllong in -- Allow skipping of specific files when cloning a modelica project by \@nllong in -- Add a quick fix for reading gfunction.csv from ghe_id subfolder by \@JingWang-CUB in -- Move modelica methods from GMT to modelica-builder by \@nllong in -- Add model for controlled distribution loop mass flow rate by \@nllong in -- Allow user to specify Modelica load filename by \@nllong in -- Decouple gain for distribution and ghx mass flow rates by \@nllong in -- Closed-loop changes to existing test_single_ghe test by \@JingWang-CUB in -- Update documentation for version 0.6.0 by \@vtnate in -- Use Ubuntu 20 and fix CHP model by \@vtnate in +* specify ports for each time series building in instance template by \@vtnate in +* Update license language by \@nllong in +* Read correct data from sys-param for microgrid electrical load by \@vtnate in +* Prep for prerelease 0.6.0 by \@nllong in +* initialize empty variable before potential use by \@vtnate in +* Include 5G partial model in generation by \@nllong in +* Allow skipping of specific files when cloning a modelica project by \@nllong in +* Add a quick fix for reading gfunction.csv from ghe_id subfolder by \@JingWang-CUB in +* Move modelica methods from GMT to modelica-builder by \@nllong in +* Add model for controlled distribution loop mass flow rate by \@nllong in +* Allow user to specify Modelica load filename by \@nllong in +* Decouple gain for distribution and ghx mass flow rates by \@nllong in +* Closed-loop changes to existing test_single_ghe test by \@JingWang-CUB in +* Update documentation for version 0.6.0 by \@vtnate in +* Use Ubuntu 20 and fix CHP model by \@vtnate in **Full Changelog**: @@ -97,28 +101,28 @@ ### Exciting New Features 🎉 -- Python 3.11 support by \@vtnate in -- Add max_electrical_load to building sys-param data by \@vtnate in -- Modifications for GHE by \@tanushree04 in -- Add Level 1 - 5G DES system by \@nllong in -- Set SWH peak to 1/10th of space heating or min 5000W by \@nllong in -- Added GHE templates by \@JingWang-CUB in -- Add OpenModelica compatibility by \@vtnate in -- Modify GHE params by \@tanushree04 in -- Enable compile & simulate with OpenModelica in Docker by \@vtnate in +* Python 3.11 support by \@vtnate in +* Add max_electrical_load to building sys-param data by \@vtnate in +* Modifications for GHE by \@tanushree04 in +* Add Level 1 - 5G DES system by \@nllong in +* Set SWH peak to 1/10th of space heating or min 5000W by \@nllong in +* Added GHE templates by \@JingWang-CUB in +* Add OpenModelica compatibility by \@vtnate in +* Modify GHE params by \@tanushree04 in +* Enable compile & simulate with OpenModelica in Docker by \@vtnate in ### Other Changes -- Specify ports for each time series building in instance template by \@vtnate in -- Update license language by \@nllong in -- Add MOS file wrapper and size the 5G mass flow rate by \@nllong in -- Fixing borefield test breaks due to schema changes by \@JingWang-CUB in -- Updating GHE Parameters: Modifying GHE Parameters schema and example files by \@tanushree04 in -- Enhance and expand microgrid templates and code by \@vtnate in +* Specify ports for each time series building in instance template by \@vtnate in +* Update license language by \@nllong in +* Add MOS file wrapper and size the 5G mass flow rate by \@nllong in +* Fixing borefield test breaks due to schema changes by \@JingWang-CUB in +* Updating GHE Parameters: Modifying GHE Parameters schema and example files by \@tanushree04 in +* Enhance and expand microgrid templates and code by \@vtnate in ### New Contributors -- \@tanushree04 made their first contribution in +* \@tanushree04 made their first contribution in **Full Changelog**: @@ -127,11 +131,11 @@ ### What\'s Changed -- Cli bug fixes -- Detailed models -- End-of-year updates to GMT docs -- Remove support for 3.7 in development, update development dependencies -- Update copyrights to 2023 +* Cli bug fixes +* Detailed models +* End-of-year updates to GMT docs +* Remove support for 3.7 in development, update development dependencies +* Update copyrights to 2023 ## Version 0.4.0 @@ -139,76 +143,76 @@ As of version 0.4.0 changes will be published using Github automated formatting ### Exciting New Features 🎉 -- Redeclare the teaser model to use buildings.media.air medium -- Fmu runner -- Spawn docker named args -- Compile & run with Spawn & Optima -- Microgrid lines -- Add 5G to System Parameters file -- Weather file at top level -- Test with 3.10 -- 4G or 5G timeseries in Dymola +* Redeclare the teaser model to use buildings.media.air medium +* Fmu runner +* Spawn docker named args +* Compile & run with Spawn & Optima +* Microgrid lines +* Add 5G to System Parameters file +* Weather file at top level +* Test with 3.10 +* 4G or 5G timeseries in Dymola ### Other Changes -- Breakout run in docker command -- Better error message if modelica timeseries files from sdk are not found -- Break out build and simulate tests -- Use Modelica Buildings Library (MBL) v9.0.0 -- Point tests to latest mbl release -- Cli less brittle -- Run compilation tasks on CI using spawn Modelica and Optimica -- Update schema.json +* Breakout run in docker command +* Better error message if modelica timeseries files from sdk are not found +* Break out build and simulate tests +* Use Modelica Buildings Library (MBL) v9.0.0 +* Point tests to latest mbl release +* Cli less brittle +* Run compilation tasks on CI using spawn Modelica and Optimica +* Update schema.json ## Version 0.3.0 -- Use MBL v9 (current master branch) for all models. Note that JModelica no longer works with this version. User must now use either Dymola or Optimica. A new solution is forthcoming. -- Update unit tests to break out building the tests and running the tests. +* Use MBL v9 (current master branch) for all models. Note that JModelica no longer works with this version. User must now use either Dymola or Optimica. A new solution is forthcoming. +* Update unit tests to break out building the tests and running the tests. ## Version 0.2.3 -- Add GMT Lib methods for Level 1 translation of Modelica-templated objects (for microgrid). -- Use MBL v9 (current master branch) for GMT Lib. The DES models still require the usage of the `issue2204_gmt_mbl` branch. -- Updated Jinja and Sphinx dependencies. Jinja is now a required dependency (no longer a testing dependency). -- Fix bug in CLI where commands only work in Unix-like operating systems, not Windows -- Fix bug in TEASER model for four-element RC models. -- Fix bug in TEASER infinite heating/cooling coupling template. +* Add GMT Lib methods for Level 1 translation of Modelica-templated objects (for microgrid). +* Use MBL v9 (current master branch) for GMT Lib. The DES models still require the usage of the `issue2204_gmt_mbl` branch. +* Updated Jinja and Sphinx dependencies. Jinja is now a required dependency (no longer a testing dependency). +* Fix bug in CLI where commands only work in Unix-like operating systems, not Windows +* Fix bug in TEASER model for four-element RC models. +* Fix bug in TEASER infinite heating/cooling coupling template. ## Version 0.2.2 -- Fix bug in CLI which required the user to be in a specific directory to run. Updated CLI is more flexible. -- Update documentation. +* Fix bug in CLI which required the user to be in a specific directory to run. Updated CLI is more flexible. +* Update documentation. ## Version 0.2.1 -- New command line interface (CLI) for scaffolding project using results of URBANopt SDK\'s OpenStudio results -- New script for converting CSV file into Modelica mos file. -- Cleanup of System Parameter Schema including renaming elements, adding definitions, and adding units -- Redesign the couplings and remove redundant model connector files -- Promote DES configuration variables to be accessible in the System Parameter file -- Extended flexibility of setting parameter values programmatically for Teaser, TimeSeries, and Spawn building load models models -- Upgrade to TEASER 0.7.5 -- Upgrade to MBL 2.1.0 -- Migrate to Poetry for development -- Add regression testing to full district energy system -- Auto-layout of templated components. This is a work in progress and the next version will include \"pooling\" of components. +* New command line interface (CLI) for scaffolding project using results of URBANopt SDK\'s OpenStudio results +* New script for converting CSV file into Modelica mos file. +* Cleanup of System Parameter Schema including renaming elements, adding definitions, and adding units +* Redesign the couplings and remove redundant model connector files +* Promote DES configuration variables to be accessible in the System Parameter file +* Extended flexibility of setting parameter values programmatically for Teaser, TimeSeries, and Spawn building load models models +* Upgrade to TEASER 0.7.5 +* Upgrade to MBL 2.1.0 +* Migrate to Poetry for development +* Add regression testing to full district energy system +* Auto-layout of templated components. This is a work in progress and the next version will include \"pooling\" of components. ## Version 0.2.0 -- Add ETS data for indirect cooling to system parameters schema -- Add district system example -- Add time series model using mass flow rates and temperatures -- Add district heating (1GDH and 4GDH) and heating indirect ETS -- Add district cooling (4GDC) and cooling indirect ETS -- Add distribution network -- Update scaffolding to allow for mixed models -- Create initial documentation +* Add ETS data for indirect cooling to system parameters schema +* Add district system example +* Add time series model using mass flow rates and temperatures +* Add district heating (1GDH and 4GDH) and heating indirect ETS +* Add district cooling (4GDC) and cooling indirect ETS +* Add distribution network +* Update scaffolding to allow for mixed models +* Create initial documentation ## Version 0.1.0 This is the initial release of the package and includes the following functionality: -- Initial implementation of a ModelicaRunner to call a Docker container to run the model. -- Create an RC model using Modelica 3.2.x, Modelica Buildings Library 7.0 and TEASER 0.7.2. -- Create a Spawn-based models which loads an IDF file. +* Initial implementation of a ModelicaRunner to call a Docker container to run the model. +* Create an RC model using Modelica 3.2.x, Modelica Buildings Library 7.0 and TEASER 0.7.2. +* Create a Spawn-based models which loads an IDF file. diff --git a/README.md b/README.md index d90bbfd02..d04163b9b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ 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 4GDHC and 5GDHC. -Documentation can be found at [https://nrel.github.io/geojson-modelica-translator]() +Documentation can be found at [https://nrel.github.io/geojson-modelica-translator](https://nrel.github.io/geojson-modelica-translator) 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. @@ -59,12 +59,12 @@ The building loads can be defined multiple ways depending on the fidelity of the 1. Create a branch named `Release 0.x.` 1. Update version in pyproject.toml -2. Update CHANGELOG using GitHub's "Autogenerate Change Log" feature, using `develop` as the target -3. After tests pass, merge branch into develop -4. From local command line, merge develop into main with: `git checkout main; git pull; git merge --ff-only origin develop; git push` -5. In GitHub, tag the release against main. Copy and paste the changelog entry into the notes. Verify the release is posted to PyPI. +1. Update CHANGELOG using GitHub's "Autogenerate Change Log" feature, using `develop` as the target +1. After tests pass, merge branch into develop +1. From local command line, merge develop into main with: `git checkout main; git pull; git merge --ff-only origin develop; git push` +1. In GitHub, tag the release against main. Copy and paste the changelog entry into the notes. Verify the release is posted to PyPI. -### Build and release the documentation: +### Build and release the documentation During development we can [serve docs locally](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write) and view updates as they are made. diff --git a/docs/changelog.md b/docs/changelog.md index 33ca380a5..f4d16fd97 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,3 +1 @@ -# Changelog - {!CHANGELOG.md!} diff --git a/docs/developer_resources.md b/docs/developer_resources.md index 3b8a3ae75..c2cf72d79 100644 --- a/docs/developer_resources.md +++ b/docs/developer_resources.md @@ -2,13 +2,12 @@ ## Tests -Tests are run with pytest, e.g. +Tests are run with pytest, e.g., ```bash - poetry run pytest +poetry run pytest ``` - ## Snapshot Testing Some tests use [syrupy](https://github.com/tophat/syrupy) to compare generated modelica models to saved "snapshots" of the models (saved as .ambr files). @@ -16,25 +15,24 @@ Some tests use [syrupy](https://github.com/tophat/syrupy) to compare generated m Snapshots should only be updated if we have changed how a model is generated, and we *know* the new version of the model is the correct version. To update all snapshots, you can run the following and commit the new snapshot files. ```bash - poetry run pytest --snapshot-update +poetry run pytest --snapshot-update ``` - ## Design Overview The GMT is designed to create an arbitrary number of user-configured models attached to other user-configured models to represent a district energy system. GMT has "building blocks" that it uses to define and attach models, which currently include: Energy Transfer Stations (ETSs), Loads, Networks, and Plants. -Each block type is a collection of models, e.g. the Loads includes time series and spawn models. A model in GMT refers to an abstracted Modelica model. It generates Modelica code (the Modelica model) and is used to define attachments to other models. +Each block type is a collection of models, e.g., the Loads includes time series and spawn models. A model in GMT refers to an abstracted Modelica model. It generates Modelica code (the Modelica model) and is used to define attachments to other models. -Each block type can attach to other specific block types. For example, you can attach a load to an ETS, but you cannot attach a load to a network. However, some models (i.e. 5G) have an ETS embedded in them. +Each block type can attach to other specific block types. For example, you can attach a load to an ETS, but you cannot attach a load to a network. However, some models (i.e., 5G) have an ETS embedded in them. -Each block type has a corresponding directory inside of `geojson_modelica_translator/model_connectors`, which contains its different model types (e.g. for Loads it contains the Time Series model and others). +Each block type has a corresponding directory inside of `geojson_modelica_translator/model_connectors`, which contains its different model types (e.g., for Loads it contains the Time Series model and others). Because models are different, even within a block type (e.g., different properties and maybe even ports), the GMT uses the concept of couplings for attaching models. Couplings define how two *specific* models attach in modelica. For example, a coupling could define how the time series load actually attaches to the heating indirect ETS. - As an aside, if the GMT reached a point where all models within a block type implemented the same interface then couplings would not be necessary. +As an aside, if the GMT reached a point where all models within a block type implemented the same interface then couplings would not be necessary. ## Getting Started as a Developer @@ -46,20 +44,20 @@ Follow the instructions below in order to configure your local environment: - Get the Modelica Buildings Library. See the documentation at [MBL Installation](getting_started.md#mbl-installation) - Clone [the GMT repo](https://github.com/urbanopt/geojson-modelica-translator) into a working directory - - (optional/as-needed) Add Python 3 to the environment variables - - As general guidance, we recommend using virtual environments to avoid dependencies colliding between your Python projects. [venv](https://docs.python.org/3/library/venv.html) is the Python native solution that will work everywhere, though other options may be more user-friendly: - - [pyenv](https://github.com/pyenv/pyenv) and [the virtualenv plugin](https://github.com/pyenv/pyenv-virtualenv) work together nicely for Linux/Mac machines - - [virtualenv](https://virtualenv.pypa.io/en/latest/) - - [miniconda](https://docs.conda.io/projects/miniconda/en/latest/) + - (optional/as-needed) Add Python 3 to the environment variables + - As general guidance, we recommend using virtual environments to avoid dependencies colliding between your Python projects. [venv](https://docs.python.org/3/library/venv.html) is the Python native solution that will work everywhere, though other options may be more user-friendly: + - [pyenv](https://github.com/pyenv/pyenv) and [the virtualenv plugin](https://github.com/pyenv/pyenv-virtualenv) work together nicely for Linux/Mac machines + - [virtualenv](https://virtualenv.pypa.io/en/latest/) + - [miniconda](https://docs.conda.io/projects/miniconda/en/latest/) - For developers, dependency management is through [Poetry](https://python-poetry.org/docs/). Poetry can be acquired by running `pip install poetry`. - - If you haven't already installed a virtual environment, Poetry will automatically create a simplified environment for your project. + - If you haven't already installed a virtual environment, Poetry will automatically create a simplified environment for your project. - Move to the GMT root directory and run `poetry install` to install the dependencies. - Verify that everything is installed correctly by running `poetry run pytest -m 'not compilation and not simulation and not dymola'`. This will run all the unit and integration tests. - Follow the instructions below to install pre-commit. - To confirm that models will build and simulate, you can run ```bash - poetry run pytest -m 'not dymola' --cov-report term-missing --cov . +poetry run pytest -m 'not dymola' --cov-report term-missing --cov . ``` The tests should all pass assuming the libraries, Docker, and all dependencies are installed correctly on your computer. Also, there will be a set @@ -73,13 +71,13 @@ To enable pre-commit for your local development process, run the following from GMT: ```bash - pre-commit install +pre-commit install ``` To run pre-commit against the files without calling git commit, then run the following. This is useful when cleaning up the repo before committing. CI will fail if pre-commit hasn't been run locally. ```bash - pre-commit run --all-files +pre-commit run --all-files ``` ## Adding New Models @@ -88,22 +86,22 @@ To add a new model you have to do the following: 1. Define the model's python class: First, create a new python file and class under its respective directory in model_connectors. Follow the patterns of existing classes. -2. Create coupling files: For every model that can be linked to, create a _ directory in the couplings directory. The two files ComponentDefinitions.mopt and ConnectStatements.mopt must exist in this directory. See more information on the content of the coupling files below in the *Couplings* sections. +1. Create coupling files: For every model that can be linked to, create a `_` directory in the couplings directory. The two files ComponentDefinitions.mopt and ConnectStatements.mopt must exist in this directory. See more information on the content of the coupling files below in the *Couplings* sections. -3. Create the instance file: In the templates directory, you must define _Instance.mopt which is the template that instantiates the system in the district model. +1. Create the instance file: In the templates directory, you must define `_Instance.mopt` which is the template that instantiates the system in the district model. See the notes below for more information. ### Couplings -A coupling defines the Modelica code necessary for interfacing two specific models, e.g. a time series load and heating indirect ETS. +A coupling defines the Modelica code necessary for interfacing two specific models, e.g., a time series load and heating indirect ETS. Each coupling is unique in its requirements: - What additional components are necessary, for example there might be some sensor between system A and B, or maybe B requires a pump when A is a specific model type - What ports are connected, for example connecting ports of model A and model B -Thus each coupling must define two template files, ComponentDefinitions.mopt and ConnectStatements.mopt, respectively. These files must be placed in the directory `couplings/templates/_/`. -In general, the **order of the names** should **follow the order of system types** if you laid out the district system starting with loads on the far left and plants on the far right (e.g. load before ETS, ETS before network, network before plant). +Thus each coupling must define two template files, `ComponentDefinitions.mopt` and `ConnectStatements.mopt`, respectively. These files must be placed in the directory `couplings/templates/_/`. +In general, the **order of the names** should **follow the order of system types** if you laid out the district system starting with loads on the far left and plants on the far right (e.g., load before ETS, ETS before network, network before plant). ### District system @@ -130,10 +128,10 @@ Each model generates one or more Modelica files to define its model. The templat ### Coupling Component Definitions -This is the template which defines new components/variables necessary for a coupling. More specifically, these are the partial template files at model_connectors/couplings/templates//ComponentDefinitions.mopt. These templates have access to: +This is the template which defines new components/variables necessary for a coupling. More specifically, these are the partial template files at `model_connectors/couplings/templates//ComponentDefinitions.mopt`. These templates have access to: - `globals`: global variables (those defined in the district.py, such as medium_w = MediumW) -- `coupling`: contains the coupling id, as well as references to the coupled models under their respective types (e.g. coupling.load.id or coupling.network.id). You should append `coupling.id` to any variable identifiers to prevent name collisions. For example, instead of just writing `parameter Modelica.Units.SI.MassFlowRate mDis_flow_nominal` you should do `parameter Modelica.Units.SI.MassFlowRate mDis_flow_nominal_{{ coupling.id }}` as well as any place where you would reference that variable. +- `coupling`: contains the coupling id, as well as references to the coupled models under their respective types (e.g., coupling.load.id or coupling.network.id). You should append `coupling.id` to any variable identifiers to prevent name collisions. For example, instead of just writing `parameter Modelica.Units.SI.MassFlowRate mDis_flow_nominal` you should do `parameter Modelica.Units.SI.MassFlowRate mDis_flow_nominal_{{ coupling.id }}` as well as any place where you would reference that variable. - `graph`: an instance of the CouplingGraph class, where all couplings are located. It can provide useful methods for accessing couplings throughout the entire system. Refer to the python class to see what it can do. - `sys_params`: an object containing data from the system parameters file - `district_system`: contains the data from the district_system portion of the system parameters file @@ -141,7 +139,7 @@ This is the template which defines new components/variables necessary for a coup ### Coupling Connect Statements -This is the template which defines connect statements to be inserted into the equation section. More specifically, these are the partial template files at model_connectors/couplings/templates//ConnectStatements.mopt. These templates have access to: +This is the template which defines connect statements to be inserted into the equation section. More specifically, these are the partial template files at `model_connectors/couplings/templates//ConnectStatements.mopt`. These templates have access to: - `globals`: same as Coupling Component Definitions context - `coupling`: same as Coupling Component Definitions context. Just like with the component definitions template, you should use the coupling.id to avoid variable name collisions. @@ -164,9 +162,9 @@ The Simulation Mapper Class can operate at multiple levels: 1. The GeoJSON level -- input: geojson, output: geojson+ 2. The Load Model Attachment -- input: geojson+, output: multiple files related to building load models (spawn, rom, csv) -3. The Translation to Modelica -- input: custom format, output: .mo (example inputs: geojson+, system design parameters). The translators are implicit to the load model connectors as each load model requires different paramters to calculate the loads. +3. The Translation to Modelica -- input: custom format, output: .mo (example inputs: geojson+, system design parameters). The translators are implicit to the load model connectors as each load model requires different parameters to calculate the loads. -In some cases, the Level 3 case (translation to Modelica) is a blackbox method (e.g. TEASER) which prevents a +In some cases, the Level 3 case (translation to Modelica) is a blackbox method (e.g., TEASER) which prevents a simulation mapper class from existing at that level. ## Running Simulations @@ -176,13 +174,13 @@ The GeoJSON to Modelica Translator contains a `ModelicaRunner.run_in_docker(...) ## Release Instructions 1. Create a branch named `Release 0.x.` -1. Update version in pyproject.toml -2. Update CHANGELOG using GitHub's "Autogenerate Change Log" feature, using `develop` as the target -3. After tests pass, merge branch into develop -4. From local command line, merge develop into main with: `git checkout main; git pull; git merge --ff-only origin develop; git push` -5. In GitHub, tag the release against main. Copy and paste the changelog entry into the notes. Verify the release is posted to PyPI. +1. Update version in `pyproject.toml` +1. Update CHANGELOG using GitHub's "Autogenerate Change Log" feature, using `develop` as the target +1. After tests pass, merge branch into develop +1. From local command line, merge develop into main with: `git checkout main; git pull; git merge --ff-only origin develop; git push` +1. In GitHub, tag the release against main. Copy and paste the changelog entry into the notes. Verify the release is posted to PyPI. -### Build and release the documentation: +### Build and release the documentation During development we can [serve docs locally](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write) and view updates as they are made. diff --git a/docs/getting_started.md b/docs/getting_started.md index 05cd40941..21ea8e894 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -23,41 +23,42 @@ Therefore, this Getting Started guide is broken up into three major setup steps. You must have PIP and Python 3.10 or later installed (run `python --version` to see what version you're using). After installing Python and PIP run the following in a terminal: ```bash - pip install geojson-modelica-translator +pip install geojson-modelica-translator ``` After installation of the GMT, a new command line interface (called the URBANopt District Energy Systems [UO DES] CLI) can be used to run various commands. Without needing to install the [MBL](https://simulationresearch.lbl.gov/modelica/index.html) the user can use the CLI to build the system parameters file from the results of the URBANopt SDK. For more information run the following: ```bash - uo_des -h - uo_des build-sys-param -h +uo_des -h +uo_des build-sys-param -h ``` The command below is only an example; however, it will run if the repository is checked out and run in the following path: `./tests/management/data/sdk_project_scraps` ```bash - uo_des build-sys-param sys_param.json baseline_scenario.csv example_project.json +uo_des build-sys-param sys_param.json baseline_scenario.csv example_project.json ``` + ## MBL Installation The Modelica Buildings Library contains many models that are needed to assemble the district systems. Follow the instructions below to install the MBL needed for the GMT: -* Download and extract the appropriate version of the MBL from [https://simulationresearch.lbl.gov/modelica/downloads/archive/modelica-buildings.html]() - * The appropriate version can be found in the right-hand column of the [installer matrix](https://docs.urbanopt.net/developer_resources/compatibility_matrix.html#urbanopt-installer-matrix) (may need to scroll to show that column). +* Download and extract the appropriate version of the MBL from [https://simulationresearch.lbl.gov/modelica/downloads/archive/modelica-buildings.html](https://simulationresearch.lbl.gov/modelica/downloads/archive/modelica-buildings.html) + * The appropriate version can be found in the right-hand column of the [installer matrix](https://docs.urbanopt.net/developer_resources/compatibility_matrix.html#urbanopt-installer-matrix) (may need to scroll to show that column). * Add the Modelica Buildings Library path to your MODELICAPATH environment variable (e.g., `export MODELICAPATH=${MODELICAPATH}:$HOME/path/to/modelica-buildings`). - * For help setting env vars on Windows, this documentation may help: [https://www.howtogeek.com/787217/how-to-edit-environment-variables-on-windows-10-or-11/]() + * For help setting env vars on Windows, this documentation may help: [https://www.howtogeek.com/787217/how-to-edit-environment-variables-on-windows-10-or-11/](https://www.howtogeek.com/787217/how-to-edit-environment-variables-on-windows-10-or-11/) * Restart your terminal to ensure that the environment variable for the MBL library is exported correctly. Once the MBL is installed, then the CLI can be used to create the model with the following command: ```bash - uo_des create-model -h +uo_des create-model -h ``` The command below is only an example; however, it will run if the repository is checked out and run in the following path: `./tests/management/data/sdk_project_scraps` ```bash - uo_des create-model sys_param.json example_project.json model_from_sdk +uo_des create-model sys_param.json example_project.json model_from_sdk ``` The resulting Modelica package will be created and can be opened in a Modelica editor. Open the `package.mo` file in the root directory of the generated package. You will also need to @@ -67,27 +68,26 @@ Most models can be simulated for free using [OpenModelica](https://openmodelica. [Dymola](https://www.3ds.com/products/catia/dymola) is a commercial alternative to OpenModelica. Licenses for use can be purchased from them. - ## Docker Installation Version 0.5.0+ of the GMT enables running the models using OpenModelica which requires the installation of [Docker](https://docs.docker.com/get-docker/). To configure Docker, do the following: -- Install [Docker](https://docs.docker.com/get-docker/) for your system. -- Configure Docker Desktop to have at least 4 GB Ram and 2 cores. This is configured under the Docker Preferences. - - Windows users can refer to [these instructions](https://docs.docker.com/desktop/settings/windows/) for more detail on adjusting Docker resources and may also be helped by [this page](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#wslconfig), which documents how to change resources in WSL. - - Larger models (more buildings) may require more resources in Docker. -- We recommend testing the Docker installation by simply running `docker run hello-world` in a terminal to confirm it is working as intended. +* Install [Docker](https://docs.docker.com/get-docker/) for your system. +* Configure Docker Desktop to have at least 4 GB Ram and 2 cores. This is configured under the Docker Preferences. + * Windows users can refer to [these instructions](https://docs.docker.com/desktop/settings/windows/) for more detail on adjusting Docker resources and may also be helped by [this page](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#wslconfig), which documents how to change resources in WSL. + * Larger models (more buildings) may require more resources in Docker. +* We recommend testing the Docker installation by simply running `docker run hello-world` in a terminal to confirm it is working as intended. After Docker is installed and configured, you can use the CLI to run the model using the following command: ```bash - uo_des run-model -h +uo_des run-model -h ``` The command below is only an example; however, it will run if the repository is checked out and run in the following path: `./tests/management/data/sdk_project_scraps` ```bash - uo_des run-model model_from_sdk +uo_des run-model model_from_sdk ``` diff --git a/docs/index.md b/docs/index.md index 65c429833..5714541b5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,6 @@ The project is motivated by the need to easily evaluate district energy systems. ![Generations of district thermal systems, over time and efficiency](images/des-generations.png) - ## Architecture Overview The GMT is designed to enable "easy" swapping between building loads, district systems, and network topologies. Some of these functionalities are more developed than others, for instance swapping between building loads is currently fleshed out; however, swapping between a fourth generation and a fifth generation system has yet to be fully implemented. diff --git a/docs/input_file_documentation.md b/docs/input_file_documentation.md index 8553529a1..9b61ba89c 100644 --- a/docs/input_file_documentation.md +++ b/docs/input_file_documentation.md @@ -3,7 +3,7 @@ There are two key input files that need to be defined to use the GeoJSON to Modelica Translator: a GeoJSON file and a System Parameters file. - As an aside, 5GDHC systems also require a `loop_order` JSON file, which is automatically generated by the [ThermalNetwork](https://nrel.github.io/ThermalNetwork/) package and used without any human input. +As an aside, 5GDHC systems also require a `loop_order` JSON file, which is automatically generated by the [ThermalNetwork](https://nrel.github.io/ThermalNetwork/) package and used without any human input. ## GeoJSON Documentation @@ -11,8 +11,8 @@ Presently only the building_properties.json of URBANopt's GeoJSON schemas is lev ### Building Properties -The building properties for the geojson file can be found in the `Schema` section of this documenation +The building properties for the geojson file can be found in the `Schema` section of this documentation ## System Parameters Schema -The system parameter properties can be found in the `Schema` section of this documenation +The system parameter properties can be found in the `Schema` section of this documentation diff --git a/geojson_modelica_translator/model_connectors/couplings/utils.py b/geojson_modelica_translator/model_connectors/couplings/utils.py index d36ef51d1..1f04970ea 100644 --- a/geojson_modelica_translator/model_connectors/couplings/utils.py +++ b/geojson_modelica_translator/model_connectors/couplings/utils.py @@ -37,7 +37,7 @@ def parse_diagram_command(str_cmd): def parse_diagram_commands(template_contents): """Returns a list of diagram commands parsed from the template modelica contents - i.e. it will find any instances of {{ diagram..* }} in the template + i.e., it will find any instances of {{ diagram..* }} in the template :param template_contents: str, modelica template code :return: list[DiagramCommand] diff --git a/geojson_modelica_translator/model_connectors/networks/templates/Connection1PipePlugFlow_v.mo b/geojson_modelica_translator/model_connectors/networks/templates/Connection1PipePlugFlow_v.mo index 52fe30984..d065468e4 100644 --- a/geojson_modelica_translator/model_connectors/networks/templates/Connection1PipePlugFlow_v.mo +++ b/geojson_modelica_translator/model_connectors/networks/templates/Connection1PipePlugFlow_v.mo @@ -60,7 +60,7 @@ First implementation. info="

This model represents the supply and return lines to connect an -agent (e.g. an energy transfer station) to a one-pipe main distribution +agent (e.g., an energy transfer station) to a one-pipe main distribution system. A plug flow pipe model Buildings.Fluid.FixedResistances.PlugFlowPipe that includes pressure drop, heat transfer, and transport delays is used in the main distribution line, diff --git a/geojson_modelica_translator/modelica/input_parser.py b/geojson_modelica_translator/modelica/input_parser.py index 77a81c9fc..60b79089e 100644 --- a/geojson_modelica_translator/modelica/input_parser.py +++ b/geojson_modelica_translator/modelica/input_parser.py @@ -2,7 +2,7 @@ # See also https://github.com/urbanopt/geojson-modelica-translator/blob/develop/LICENSE.md from pathlib import Path -from typing import Any, List, Tuple, Union +from typing import Any, Union # TODO: This needs to be removed. It is not used anywhere in the codebase. @@ -155,7 +155,7 @@ def replace_within_string(self, new_string: str) -> None: """ self.within = new_string - def find_model_object(self, obj_name: str) -> Tuple[Union[int, None], Union[str, None]]: + def find_model_object(self, obj_name: str) -> tuple[Union[int, None], Union[str, None]]: """Find a model object in the list of parsed objects Args: @@ -191,7 +191,7 @@ def replace_model_string(self, model_name: str, model_instance: str, old_string: if index is not None: self.model["objects"][index] = self.model["objects"][index].replace(old_string, new_string) - def add_model_object(self, model_name: str, model_instance: str, data: List[str]) -> None: + def add_model_object(self, model_name: str, model_instance: str, data: list[str]) -> None: """Add a new model object to the model Args: @@ -231,7 +231,7 @@ def add_connect(self, a: str, b: str, annotation: str) -> None: """ self.connections.append(f" connect({a}, {b})\n {annotation};\n") - def find_connect(self, port_a: str, port_b: str) -> Tuple[Union[int, None], Union[str, None]]: + def find_connect(self, port_a: str, port_b: str) -> tuple[Union[int, None], Union[str, None]]: """Find an existing connection that has port_a and/or port_b. If there are more than one, then it will only return the first. diff --git a/geojson_modelica_translator/system_parameters/system_parameter_properties.json b/geojson_modelica_translator/system_parameters/system_parameter_properties.json index 3e61c6b81..b15bf6a19 100644 --- a/geojson_modelica_translator/system_parameters/system_parameter_properties.json +++ b/geojson_modelica_translator/system_parameters/system_parameter_properties.json @@ -1447,7 +1447,7 @@ "default": 0.0334 }, "shank_spacing": { - "description": "The spacing between the U-tube legs, as referenced from outer surface of the pipes (i.e. not referenced from each pipes respective centerline), in meters.", + "description": "The spacing between the U-tube legs, as referenced from outer surface of the pipes (i.e., not referenced from each pipes respective centerline), in meters.", "type": "number", "minimum": 0, "default": 0.0277 diff --git a/mkdocs.yml b/mkdocs.yml index d8598670d..a2666f6c0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,7 +29,7 @@ nav: - Input File Documentation: input_file_documentation.md - Developer Resources: developer_resources.md - Contributors: authors.md - - Changelog: changelog.md + - Change Log: changelog.md - License: license.md # Add these dirs/files to live updating during development (in addition to docs & this file) # https://www.mkdocs.org/user-guide/configuration/#watch diff --git a/poetry.lock b/poetry.lock index b9aa4abd4..c90088e18 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1681,7 +1681,7 @@ xmp = ["defusedxml"] [[package]] name = "platformdirs" version = "4.3.6" -description = "A small Python package for determining appropriate platform-specific dirs, e.g. a `user data dir`." +description = "A small Python package for determining appropriate platform-specific dirs, e.g., a `user data dir`." optional = false python-versions = ">=3.8" files = [