Skip to content

Commit

Permalink
read content from other files
Browse files Browse the repository at this point in the history
  • Loading branch information
@nllong
nllong committed Mar 20, 2021
1 parent 8a2179c commit fcc6b3e
Show file tree
Hide file tree
Showing 12 changed files with 302 additions and 196 deletions.
6 changes: 3 additions & 3 deletions AUTHORS.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ Contributors

* Nicholas Long, NREL <https://github.com/nllong>
* Hagar Elarga, NREL <https://github.com/helarga>
* Amy Allen, NREL <https://github.com/>
* Amy Allen, NREL <https://github.com/amyeallen1>
* Nathan Moore, NREL <https://github.com/vtnate>
* Ted Summer, Devetry <https://github.com/macintoshpie>
* Antoine Gautier, LBNL <https://github.com/>
* Yanfei Li, NREL <https://github.com/>
* Antoine Gautier, LBNL <https://github.com/AntoineGautier>
* Yanfei Li, NREL <https://github.com/YanfeiNREL>
4 changes: 4 additions & 0 deletions CHANGELOG.rst
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
Change Log
==========

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.

Version 0.2.1
-------------
* New command line interface (CLI) for scaffolding project using results of URBANopt SDK's OpenStudio results
Expand Down
Binary file removed ConnectionTemplate.png
View file
Binary file not shown.
206 changes: 42 additions & 164 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,70 +22,66 @@ The project is motivated by the need to easily evaluate district energy systems.
Getting Started
---------------

:code:`pip install geojson-modelica-translator`
It is possible to test the GeoJSON to Modelica Translator by simpling 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.

* Install `Docker <https://docs.docker.com/get-docker/>`_ for your platform
* Configure Docker on your local desktop to have at least 4 GB Ram and 2 cores. This is configured under the Docker Preferences.
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.

For help and command documentation in the terminal: :code:`uo_des -h`

Documentation for each command can be found at:
.. code-block:: bash
* :code:`uo_des build-system-param -h`
* :code:`uo_des create-model -h`
* :code:`uo_des run-model -h`
pip install geojson-modelica-translator
Developer Installation
----------------------
# from the simulation results within a checkout of this repository
# in the ./tests/management/data/sdk_project_scraps path.
The GeoJSON Modelica Translator is in alpha-phase development and the functionality is limited. Currently, the proposed approach for getting started is outlined in this readme. You need Python 3, pip 3, and Poetry to install/build the packages. Note that the best approach is to use Docker to run the Modelica models as this approach does not require Python 2.
# 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
* Clone this repo into a working directory
* (optional/as-needed) Add Python 3 to the environment variables
* Install Poetry (:code:`pip install poetry`). More information on Poetry can be found `here <https://python-poetry.org/docs/>`_.
* Install `Docker <https://docs.docker.com/get-docker/>`_ for your platform
* Configure Docker on your local desktop to have at least 4 GB Ram and 2 cores. This is configured under the Docker Preferences.
* Install the Modelica Buildings Library from GitHub
* Clone https://github.com/lbl-srg/modelica-buildings/ into a working directory outside of the GMT directory
* Change to the directory inside the modelica-buildings repo you just checked out. (:code:`cd modelica-buildings`)
* Install git-lfs
* Mac: :code:`brew install git-lfs; git lfs install`
* Ubuntu: :code:`sudo apt install git-lfs; git lfs install`
* Pull the correct staging branch for this project with: :code:`git checkout issue2204_gmt_mbl`
* Add the Modelica Buildings Library path to your MODELICAPATH environment variable (e.g., export MODELICAPATH=${MODELICAPATH}:$HOME/path/to/modelica-buildings).
* Return to the GMT root directory and run :code:`poetry install`
* Test if everything is installed correctly by running :code:`poetry run tox`
* This should run all unit tests, pre-commit, and build the docs.
# create the modelica package
uo_des create-model sys_param.json
The tests should all pass assuming the libraries are installed correctly on your computer. Also, there will be a set of Modelica models that are created and persisted into the :code:`tests/output` folder and the :code:`tests/model_connectors/output` folder. These files can be inspected in your favorite Modelica editor.
# test running the new Modelica package - This requires installing Docker and the MBL!
uo_des run-model model_from_sdk
Developers
**********
Instructions for installing and configuring the MBL and Docker are available `here <docs/getting_started.rst>`_

This project used `pre-commit <https://pre-commit.com/>`_ to ensure code consistency. To enable pre-commit, run the following from the command line.
Architecture Overview
---------------------

.. code-block:: bash
The GMT is designed to enable "easy" swapping of building loads, district systems, and newtork 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.

pip install pre-commit
pre-commit install
The diageram below is meant to illustrate the future proposed interconnectivity and functionality of the
GMT project.

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.

.. code-block:: bash
.. image:: https://raw.githubusercontent.com/urbanopt/geojson-modelica-translator/develop/docs/images/des-connections.png

pre-commit run --all-files
There are various models that exist in the GMT and are described in the subsections below. More comprehensive
documentation on the GMT is `here <https://docs.urbanopt.net/geojson-modelica-translator/`_. Documentation on
URBANopt SDK is `here <https://docs.urbanopt.net/>`_.

GeoJSON
+++++++
GeoJSON and System Parameter Files
++++++++++++++++++++++++++++++++++

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.
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 GeoJSON model should include checks for ensuring the accuracy of the area calculations, non-overlapping building areas and coordinates, and various others.
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.
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
Expand All @@ -97,123 +93,5 @@ The Simulation Mapper Class can operate at mulitple levels:
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
-------------------

The GeoJSON to Modelica Translator contains a :code:`ModelicaRunner.run_in_docker(...)` method. It is recommended
to use this method in a python script if needed as it will copy the required files into the correct location. If
desired, a user can run the simulations manually using JModelica (via Docker). Follow the step below to configure
the runner to work locally.

* Make sure jm_ipython.sh is in your local path.
* After running the :code:`py.test`, go into the :code:`geojson_modelica_translator/modelica/lib/runner/` directory.
* Copy :code:`jmodelica.py` to the :code:`tests/model_connectors/output` directory.
* From the :code:`tests/model_connectors/output` directory, run examples using either of the the following:
* :code:`jm_ipython.sh jmodelica.py spawn_single.Loads.B5a6b99ec37f4de7f94020090.coupling`
* :code:`jm_ipython.sh jmodelica.py spawn_single/Loads/B5a6b99ec37f4de7f94020090/coupling.mo`
* The warnings from the simulations can be ignored. A successful simulation will return Final Run Statistics.
* Install matplotlib package. :code:`pip install matplotlib`
* Visualize the results by inspecting the resulting mat file using BuildingsPy. Run this from the root directory of the GMT.

.. code-block:: python
%matplotlib inline
import os
import matplotlib.pyplot as plt
from buildingspy.io.outputfile import Reader
mat = Reader(os.path.join(
"tests", "model_connectors", "output", "spawn_single_Loads_B5a6b99ec37f4de7f94020090_coupling_result.mat"),
"dymola"
)
# List off all the variables
for var in mat.varNames():
print(var)
(time1, zn_1_temp) = mat.values("bui.znPerimeter_ZN_3.TAir")
(_time1, zn_4_temp) = mat.values("bui.znPerimeter_ZN_4.TAir")
plt.style.use('seaborn-whitegrid')
fig = plt.figure(figsize=(16, 8))
ax = fig.add_subplot(211)
ax.plot(time1 / 3600, zn_1_temp - 273.15, 'r', label='$T_1$')
ax.plot(time1 / 3600, zn_4_temp - 273.15, 'b', label='$T_4$')
ax.set_xlabel('time [h]')
ax.set_ylabel(r'temperature [$^\circ$C]')
# Simulation is only for 168 hours?
ax.set_xlim([0, 168])
ax.legend()
ax.grid(True)
fig.savefig('indoor_temp_example.png')
Managed Tasks
-------------

Updating Schemas
****************

There is managed task to automatically pull updated GeoJSON schemas from the :code:`urbanopt-geojson-gem` GitHub project. A developer can run this command by calling

.. code-block:: bash
poetry run update_schemas
The developer should run the test suite after updating the schemas to ensure that nothing appears to have broken. Note that the tests do not cover all of the properties and should not be used as proof that everything works with the updated schemas.


Updating Licenses
*****************

To apply the copyright/license to all the files, run the following managed task

.. code-block:: bash
poetry run update_licenses
Templating Diagram
------------------
.. image:: https://raw.githubusercontent.com/urbanopt/geojson-modelica-translator/develop/docs/images/des-connections.png

Release Instructions
--------------------

* Bump version to <NEW_VERSION> in setup.py (use semantic versioning as much as possible).
* Run `autopep8` to nicely format the code (or run `pre-commit --all-files`).
* Create a PR against develop into main.
* After main branch passes, then merge and checkout the main branch. Build the distribution using the following code:

.. code-block:: bash
# Remove old dist packages
rm -rf dist/*
poetry build
* Run `git tag <NEW_VERSION>`. (Note that `python setup.py --version` pulls from the latest tag.)
* Verify that the files in the dist/* folder have the correct version (no dirty, no sha)
* Run the following to release

.. code-block:: bash
poetry publish
* Build and release the documentation

.. code-block:: bash
# Build and verify with the following
cd docs
poetry run make html
cd ..
# release using
./docs/publish_docs.sh
* Push the tag to GitHub after everything is published to PyPi, then go to GitHub and add in the CHANGELOG.rst notes into the tagged release and officially release.

.. code-block:: bash
git push origin <NEW_VERSION>
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.
2 changes: 1 addition & 1 deletion docs/changelog.rst
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
.. _changes:
.. _changelog:
.. include:: ../CHANGELOG.rst
Loading

0 comments on commit fcc6b3e

Please sign in to comment.