Merge pull request #455 from urbanopt/develop

Prep 0.2.3 release

.coveragerc

@@ -11,6 +11,7 @@ omit =
     .tox/*
     management/update_schemas.py
     management/update_licenses.py
+    management/check_sys_params.py
     geojson_modelica_translator/model_connectors/load_connectors/templates/RunSpawnCouplingBuilding.most
     geojson_modelica_translator/modelica/lib/runner/__init__.py
     geojson_modelica_translator/modelica/lib/runner/jmodelica.py

.github/workflows/ci.yml

@@ -3,15 +3,34 @@ name: CI
 on:
   pull_request:
   push:
+    branches:
+      - 'develop'
+      - 'main'
+
+defaults:
+  run:
+    shell: bash
 
 jobs:
   test:
-    runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
+        os: [ubuntu-latest, windows-latest]
         # 3.9 does not work as of 2020-02-01
         python-version: [3.7]
         test_env: [python, precommit, docs]
+        mbl_branch: [issue2204_gmt_mbl]
+        include:
+          - os: ubuntu-latest
+            python-version: 3.7
+            test_env: python
+            mbl_branch: master
+          - os: ubuntu-latest
+            python-version: 3.7
+            test_env: check_sys_params
+            mbl_branch: issue2204_gmt_mbl
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v2
       -
@@ -36,41 +55,67 @@ jobs:
         name: Print Environment
         run: poetry --version
       -
-        name: Install dependencies
-        env:
-          MODELICAPATH: /home/runner/work/modelica-buildings
+        name: Install modelicafmt
         run: |
-          # Install modelicafmt (hard code the version for now)
-          curl -SLO https://github.com/urbanopt/modelica-fmt/releases/download/v0.2-pr.1/modelica-fmt_0.2-pr.1_Linux_x86_64.tar.gz
-          tar xzf modelica-fmt_0.2-pr.1_Linux_x86_64.tar.gz
+          RUNNER_SYSTEM=$(python -c 'import platform; print(platform.system())')
+          curl -SLO "https://github.com/urbanopt/modelica-fmt/releases/download/v0.2-pr.2/modelica-fmt_0.2-pr.2_${RUNNER_SYSTEM}_x86_64.tar.gz"
+          tar xzf modelica-fmt_0.2-pr.2_${RUNNER_SYSTEM}_x86_64.tar.gz
           chmod +x modelicafmt
-          sudo mv modelicafmt /usr/local/bin/
-          # Install MBL
-          git clone --single-branch --branch issue2204_gmt_mbl https://github.com/lbl-srg/modelica-buildings.git $MODELICAPATH
-          cd $MODELICAPATH
+          if [[ $RUNNER_SYSTEM == 'Linux' ]]; then
+            sudo mv modelicafmt /usr/local/bin/
+          else
+            mv modelicafmt '/c/Program Files/'
+          fi
+      -
+        name: Install MBL
+        env:
+          MATRIX_OS: ${{ matrix.os }}
+          MBL_BRANCH: ${{ matrix.mbl_branch }}
+        run: |
+          if [[ "${MATRIX_OS}" == 'ubuntu-latest' ]]; then
+            MODELICAPATH='/home/runner/work/modelica-buildings'
+          else
+            echo $GITHUB_WORKSPACE
+            MODELICAPATH='/c/Program Files/modelica-buildings'
+          fi
+          git clone --single-branch --branch ${MBL_BRANCH} https://github.com/lbl-srg/modelica-buildings.git "${MODELICAPATH}"
+          cd "${MODELICAPATH}"
           echo "Git branch is $(git branch)"
+          # export MODELICAPATH for subsequent steps
+          echo "MODELICAPATH=${MODELICAPATH}" >> $GITHUB_ENV
       -
         name: Tox ${{ matrix.test_env }}
         env:
-          MODELICAPATH: /home/runner/work/modelica-buildings
           COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
-        run: poetry run tox -e ${{ matrix.test_env }}
+        run: |
+          if [ '${{ matrix.test_env }}' == 'python' ]; then
+            # !! Ugh, this is ugly but necessary (poetry + tox were not passing our args correctly to pytest)
+            if [ '${{ matrix.os }}' == 'windows-latest' ]; then
+              # for windows, skip python tests that require simulation (currently broken)
+              poetry run tox -e ${{ matrix.test_env }} -- -m 'not simulation' ./tests
+            elif [ '${{ matrix.mbl_branch }}' == 'master' ]; then
+              poetry run tox -e ${{ matrix.test_env }} -- -m 'mbl_v9 and not msl_v4_simulation' ./tests
+            else
+              poetry run tox -e ${{ matrix.test_env }} -- -m 'not mbl_v9' ./tests
+            fi
+          else
+            poetry run tox -e ${{ matrix.test_env }}
+          fi
+      -
+        name: Coveralls
+        env:
+          COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
+        if: ${{ matrix.os == 'ubuntu-latest' && matrix.test_env == 'python' && matrix.mbl_branch == 'issue2204_gmt_mbl' }}
+        run: |
+          poetry run coveralls
       -
         name: Job Failed
         if: ${{ failure() }}
         run: |
           echo "Maybe these logs will help?"
-          free -tm
           ls -alt $GITHUB_WORKSPACE
           echo "============================================ stdout.log ========================================="
           find $GITHUB_WORKSPACE -type f -name 'stdout.log' -print | while read filename; do
             echo "$filename"
             cat "$filename"
           done
-      -
-        name: Store test output
-        if: ${{ always() }}
-        uses: actions/upload-artifact@v2
-        with:
-          name: test-output
-          path: tests/model_connectors/output

.gitignore

@@ -2,6 +2,7 @@
 .idea
 .DS_Store
 .vscode/
+.ruby-version
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -100,6 +101,7 @@ ENV/
 
 # Test outputs
 tests/output
+tests/*/microgrid_output
 tests/output_ets
 tests/*/output
 /geojson_modelica_translator/modelica/buildingslibrary/

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ exclude: |
   )
 
 repos:
-  - repo: git://github.com/pre-commit/pre-commit-hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v2.2.3
     hooks:
       - id: trailing-whitespace

CHANGELOG.rst

@@ -1,6 +1,13 @@
 Change Log
 ==========
 
+Version 0.2.3 (Unreleased)
+--------------------------
+* Add GMT Lib methods for Level 1 translation of Modelica-templated objects
+* 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
+
 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.

LICENSE

@@ -1,4 +1,4 @@
-URBANopt, Copyright (c) 2019-2021, Alliance for Sustainable Energy, LLC, and other contributors.
+URBANopt, Copyright (c) 2019-2022, Alliance for Sustainable Energy, LLC, and other contributors.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted

README.rst

@@ -7,8 +7,8 @@ GeoJSON Modelica Translator (GMT)
 .. 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://pypi.org/project/GeoJSON-Modelica-Translator/
+.. image:: https://badge.fury.io/py/geojson-modelica-translator.svg
+    :target: https://badge.fury.io/py/geojson-modelica-translator
 
 Description
 -----------
@@ -26,7 +26,7 @@ It is possible to test the GeoJSON to Modelica Translator (GMT) by simpling inst
 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>`_
+`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
@@ -44,7 +44,7 @@ OpenStudio/EnergyPlus 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
+    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
@@ -65,34 +65,16 @@ GMT project.
 
 .. image:: https://raw.githubusercontent.com/urbanopt/geojson-modelica-translator/develop/docs/images/des-connections.png
 
-There are various models that exist in the GMT and are described in the subsections below. See the more `comprehensive
+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/>`_.
 
-GeoJSON and System Parameter Files
-++++++++++++++++++++++++++++++++++
+Building Load Models
+++++++++++++++++++++
 
-This module manages the connection to the GeoJSON file including any calculations that are needed. Calculations
-can include distance calculations, number of buildings, number of connections, etc.
+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:
 
-The GeoJSON model should include checks for ensuring the accuracy of the area calculations, non-overlapping building
-areas and coordinates, and various others.
-
-Load Model Connectors
-+++++++++++++++++++++
-
-The Model Connectors are libraries that are used to connect between the data that exist in the GeoJSON with a
-model-based engine for calculating loads (and potentially energy consumption). Examples includes, TEASER,
-Data-Driven Model (DDM), CSV, Spawn, etc.
-
-Simulation Mapper Class / Translator
-++++++++++++++++++++++++++++++++++++
-
-The Simulation Mapper Class can operate at mulitple levels:
-
-1. The GeoJSON level -- input: geojson, output: geojson+
-2. The Load Model Connection -- 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.
-
-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.
+#. 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.

docs/_static/custom_sphinx_styles.css

@@ -27,6 +27,9 @@ div.sphinxsidebar ul, div.sphinxsidebar ul ul {
     list-style-type: none;
 }
 
+div.body {
+    max-width: 1600px;
+}
 div.footer, div.footer a {
     color: #2c3e50;
 }

docs/conf.py

@@ -51,7 +51,7 @@
 
 # General information about the project.
 project = u"GeoJSON Modelica Translator"
-copyright = u"2019-2021, Alliance for Sustainable Energy, LLC"
+copyright = u"2019-2022, Alliance for Sustainable Energy, LLC"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/developer_resources.rst

@@ -9,6 +9,28 @@
 Developer Resources
 ===================
 
+Tests
+-----
+
+Tests are run with pytest, e.g.
+
+.. code-block:: bash
+
+    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).
+
+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.
+
+.. code-block:: bash
+
+    poetry run pytest --snapshot-update
+
+
 Design Overview
 ---------------
 
@@ -141,23 +163,27 @@ Model Definition
 
 Each model generates one or more Modelica files to define its model. The templating context is implementation dependent, so refer to its :code:`to_modelica()` method.
 
-Component Definitions
-^^^^^^^^^^^^^^^^^^^^^
+Coupling Component Definitions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This is the template which defines new components/variables necessary for a coupling. It has 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/<coupling name>/ComponentDefinitions.mopt. These templates have access to:
 
 - :code:`globals`: global variables (those defined in the district.py, such as medium_w = MediumW)
 - :code:`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 :code:`coupling.id` to any variable identifiers to prevent name collisions. For example, instead of just writing :code:`parameter Modelica.SIunits.MassFlowRate mDis_flow_nominal` you should do :code:`parameter Modelica.SIunits.MassFlowRate mDis_flow_nominal_{{ coupling.id }}` as well as any place where you would reference that variable.
 - :code:`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.
+- :code:`sys_params`: an object containing data from the system parameters file
+  - :code:`district_system`: contains the data from the district_system portion of the system parameters file
+  - :code:`building`:if the coupling includes a load, this object will be included as well -- if there's no as part of the coupling this object will NOT be present. It contains the building-specific system parameters pulled from the system parameters JSON file.
 
-Connect Statements
-^^^^^^^^^^^^^^^^^^
+Coupling Connect Statements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This is the template which defines connect statements to be inserted into the equation section.
+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/<coupling name>/ConnectStatements.mopt. These templates have access to:
 
-- :code:`globals`
-- :code:`coupling`: just like with the component definitions template, you should use the coupling.id to avoid variable name collisions.
-- :code:`graph`
+- :code:`globals`: same as Coupling Component Definitions context
+- :code:`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.
+- :code:`graph`: same as Coupling Component Definitions context
+- :code:`sys_params`: same as Coupling Component Definitions context
 
 Model Instance
 ^^^^^^^^^^^^^^
@@ -168,6 +194,19 @@ This template is used to declare a model instance.
 - :code:`graph`
 - :code:`couplings`: contains each coupling the model is associated with. For example, if our ETS was coupled to a load and network, couplings would look like :code:`{ load_couplings: [<load coupling>], network_couplings: [<network coupling>] }`. This can be used to access coupling and model ids.
 - :code:`model`: contains info about the model instance, including :code:`modelica_type` and :code:`id`. These should be used to define the model, for example :code:`{{ model.modelica_type }} {{ model.id }}(...)`
+- :code:`sys_params`: same as Coupling Component Definitions context
+
+Simulation Mapper Class / Translator
+************************************
+
+The Simulation Mapper Class can operate at multiple levels:
+
+1. The GeoJSON level -- input: geojson, output: geojson+
+2. The Load Model Connection -- 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.
+
+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
 -------------------

docs/getting_started.rst

@@ -62,11 +62,14 @@ Once the MBL is installed, then the CLI can be used to create the model with the
 
     # 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
-    uo_des create-model sys_param.json
+    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 :code:`package.mo` file in the root directory of the generated package. You will also need to
 load the MBL into your Modelica editor.
 
+NOTE: The developers of the GMT are currently working on updating the MBL version used. If you are also a developer and need to run the unit tests in this repo, you can instruct pytest to ignore the v8 tests with :code:`poetry run pytest -m 'not mbl_v9'`, which assumes you have the MBL version documented above. To run the MBL v9 tests, you need to checkout :code:`master` and run :code:`poetry run pytest -m mbl_v9`, however several MBL v9 components now require MSL 4.0, which doesn't work within JModelica.
+
+
 Docker Installation
 -------------------