Skip to content

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 System Parameter file from results of an URBANopt SDK simulation. These files can then be customized by hand to build a district system to meet your needs.

Therefore, this Getting Started guide is broken up into three major setup steps. Each one requires all previous steps to be completed first.

  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 OpenModelica.

GMT Installation

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:

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

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:

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.

Most models can be simulated for free using OpenModelica, which is included via Docker.

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. 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.
  • Windows users can refer to these instructions for more detail on adjusting Docker resources and may also be helped by this page, 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:

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