How to: Dymola Python Interface

This page gives a quick overview of how to use the Python interface of Dymola. This assumes you're running Dymola 2018 and Python 3 on Windows.

Use Case

You want to automate Modelica simulations with Python, e.g. for parameter studies, optimization, unit testing, ...

How to get started using Dymola's Python interface

Location and documentation of the source files

The Dymola Python Interface comes in the form of a few modules at \Dymola 2018\Modelica\Library\python_interface\. The modules are bundled within the dymola.egg file. You can unzip this file to have a look inside. In addition, you can open Dymola 2018\Modelica\Library\python_interface\doc\index.html for some rendered html documentation of the available functions.

In addition, there is a section explaining the Dymola Python Interface in the Dymola User Manual Volume 2 (click Help > Documentation in Dymola for the Link) starting on page 289.

"Installing" the Python package dymola

The Dymola Python Interface is supposed to be imported as a Python package named dymola. Unfortunately, this is not available via pip. The recommended way to use the package is to append the \Dymola 2018\Modelica\Library\python_interface\dymola.egg file to your PYTHONPATH environment variable. You can do so from the Windows command line via set PYTHONPATH=%PYTHONPATH%;D:\Program Files (x86)\Dymola 2018\Modelica\Library\python_interface\dymola.egg. Make sure to replace the D:\Program Files (x86)\Dymola 2018 part with your actual installation path. Alternatively, you can append the dymola.egg file to your PYTHONPATH within your Python script with

import os
import sys
sys.path.insert(0, os.path.join('C:\\',
                                'Program Files (x86)',
                                'Dymola 2018',
                                'Modelica',
                                'Library',
                                'python_interface',
                                'dymola.egg'))

That may not be the best option, though.

If you are using conda, you can add the dymola package via a .pth file. This follows the recommendation given at StackOverflow - Anaconda: Permanently include external packages (like in PYTHONPATH). Simply add a file with any name of your choice ending in .pth (e.g. dymola-python-interface.pth) to the site-packages folder in your conda environment (e.g. at D:\Python\Miniconda\envs\<my-environment>\Lib\site-packages\<dymola-python-interface>.pth). In this file, just include the path to your local dymola.egg file, e.g. c:\Program Files (x86)\Dymola 2018\Modelica\Library\python_interface\dymola.egg. With your next activation of your environment, you should be able to use import dymola.

Usage

Now you can use the Interface to simulate models from Python. Here is a quick example to help you along:

# Import dymola package
from dymola.dymola_interface import DymolaInterface

# Start the interface
dymola = DymolaInterface()

# Location of your local AixLib clone
dir_aixlib = <path/to/your/AixLib/AixLib>

# Location where to store the results
dir_result = <path/to/where/you/want/it>

# Open AixLib
dymola.openModel(path=os.path.join(dir_aixlib, 'package.mo'))

# Translate any model you'd like to simulate
dymola.translateModel('AixLib.ThermalZones.ReducedOrder.Examples.ThermalZone')

# Simulate the model
output = dymola.simulateExtendedModel(
    problem='AixLib.ThermalZones.ReducedOrder.Examples.ThermalZone',
    startTime=0.0,
    stopTime=3.1536e+07,
    outputInterval=3600,
    method="Dassl",
    tolerance=0.0001,
    resultFile=os.path.join(dir_result, 'demo_results'),
    finalNames=['thermalZone.TAir' ],
)

dymola.close()

After this, you can work with the results stored in output. The variable output returns a list of the format [True, []], where output[0] is True for a successful simulation. output[1] is a list returning the values of the variables you requested with the parameter finalNames when running dymola.simulateExtendedModel(). For more information see the Dymola User Manual Vol. 2 as mentioned above.

Further information

Setting experiment outputs

If you would like to set experiment output flags, you can use dymola.experimentSetupOutput() (See https://stackoverflow.com/questions/48202469). This can be useful to e.g. stop Dymola from saving variables at events with dymola.experimentSetupOutput(events=False). Be aware that all output flags must be set in exactly one of these function calls. If you would set two flags in two calls as in:

# Warning - Don't do this:
dymola.experimentSetupOutput(textual=True)
dymola.experimentSetupOutput(events=False)

the second call overwrites the first call's value with the default. Instead, use

# Instead do this:
dymola.experimentSetupOutput(textual=True, events=False)

Call to action

If

• anything on this page is not clear to you,
• you found an error on this page,
• you have a suggestion for improvement,
• you experience a problem with this approach in your work,
• you have a better solution for using the Dymola Python Interface,
• ...

Make sure to raise the issue on our Issue Tracker!