Skip to content

Latest commit

 

History

History
100 lines (66 loc) · 4.93 KB

getting_started.rst

File metadata and controls

100 lines (66 loc) · 4.93 KB
Raw

Getting Started

There are three major steps to running the GeoJSON to Modelica Translator (GMT):

  1. generating the GeoJSON and System Parameter JSON files,
  2. creating of the Modelica package containing the district system, and
  3. running the Modelica package.

Depending on the use case, the need to run all the steps above may not be needed. For example: it may be desirable to only generate the Modelica package and then open and run the model in a Modelica user interface such as Dymola. Or, there may be a case to simply generate the GeoJSON and System Parameter file from results of an URBANopt SDK simulation result set.

This Getting Started guide is broken up into three major setup steps:

  1. Installing the GMT from PyPi
  2. Installing and configuring the Modelica Buildings Library (MBL)
  3. Installing and configuring Docker in order to run simulations using JModelica

GMT Installation

You must have PIP and Python 3.7 or later installed (run python --version to see what version you're using). After installing Python and PIP run the following in a terminal (requires Python 3):

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 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:

uo_des -h
uo_des build-system-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
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. Installation of the MBL is done through Git and GitHub. Follow the instructions below to install the MBL needed for the GMT:

  • Clone the MBL into a working directory outside of the GMT directory
  • Change to the directory inside the modelica-buildings repo you just checked out. (cd modelica-buildings)
  • Install git-lfs
    • Mac: brew install git-lfs; git lfs install
    • Ubuntu: sudo apt install git-lfs; git lfs install
  • Pull the correct staging branch for this project with: 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). Restart your terminal to ensure that 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:

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
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 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 poetry run pytest -m 'not mbl_v8', which assumes you have the MBL version documented above. To run the MBL v8 tests, you need to checkout v8.1.0 and run poetry run pytest -m mbl_v8.

Docker Installation

The preferred method of running the simulations would be within Dymola; however, that is not a practical solution for many based on the license requirement. The GMT enables the running of the models using JModelica which requires the installation of Docker. To configure Docker, do the following:

  • Install Docker for your system.
  • Configure Docker Desktop to have at least 4 GB Ram and 2 cores. This is configured under the Docker Preferences.
  • It is recommended to test the installation of Docker by simply running docker run hello-world in a terminal.

After Docker is installed and configured, you can use the CLI to run the model using the following command:

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
uo_des run-model model_from_sdk