OpenModelica Python Interface — OpenModelica User's Guide v1.28.0-dev-328-gff8123cd7d7 documentation

# OpenModelica Python Interface

This chapter describes the OpenModelica Python integration facilities.

- OMPython - the OpenModelica Python scripting interface, see OMPython - OpenModelica Python Interface.

- EnhancedOMPython - Enhanced OMPython scripting interface, see Enhanced OMPython Features.

## OMPython - OpenModelica Python Interface

OMPython - OpenModelica Python API is a free, open source, highly portable Python based interactive session handler for Modelica scripting. It provides the modeler with components for creating a complete Modelica modeling, compilation and simulation environment based on the latest OpenModelica library standard available. OMPython is architectured to combine both the solving strategy and model building. So domain experts (people writing the models) and computational engineers (people writing the solver code) can work on one unified tool that is industrially viable for optimization of Modelica models, while offering a flexible platform for algorithm development and research. OMPython is not a standalone package, it depends upon the OpenModelica installation.

OMPython is implemented in Python and depends on ZeroMQ - high performance asynchronous messaging library.

To install OMPython follow the instructions at https://github.com/OpenModelica/OMPython

### Features of OMPython

OMPython provides user friendly features like:

- Interactive session handling, parsing, interpretation of commands and Modelica expressions for evaluation, simulation, plotting, etc.

- Interface to the latest OpenModelica API calls.

- Optimized parser results that give control over every element of the output.

- Helper functions to allow manipulation on Nested dictionaries.

- Easy access to the library and testing of OpenModelica commands.

### Test Commands

OMPython provides a OMCSessionZMQ class that uses ZeroMQ to communicate with OpenModelica.

To test the command outputs, simply create an OMCSessionZMQ object by importing from the OMPython library within Python interepreter. The module allows you to interactively send commands to the OMC server and display their output.

To get started, create an OMCSessionZMQ object:

    >>> from OMPython import OMCSessionZMQ
    >>> omc = OMCSessionZMQ()

    >>> omc.sendExpression("getVersion()")
    OMCompiler v1.28.0-dev.328+g726deb07d63
    >>> omc.sendExpression("cd()")
    «DOCHOME»
    >>> omc.sendExpression("loadModel(Modelica)")
    True
    >>> omc.sendExpression("loadFile(getInstallationDirectoryPath() + \"/share/doc/omc/testmodels/BouncingBall.mo\")")
    True
    >>> omc.sendExpression("instantiateModel(BouncingBall)")
    class BouncingBall
      parameter Real e = 0.7 "coefficient of restitution";
      parameter Real g = 9.81 "gravity acceleration";
      Real h(start = 1.0, fixed = true) "height of ball";
      Real v(fixed = true) "velocity of ball";
      Boolean flying(start = true, fixed = true) "true, if ball is flying";
      Boolean impact;
      Real v_new(fixed = true);
      Integer foo;
    equation
      impact = h <= 0.0;
      foo = if impact then 1 else 2;
      der(v) = if flying then -g else 0.0;
      der(h) = v;
      when {h <= 0.0 and v <= 0.0, impact} then
        v_new = if edge(impact) then -e * pre(v) else 0.0;
        flying = v_new > 0.0;
        reinit(v, v_new);
      end when;
    end BouncingBall;

We get the name and other properties of a class:

    >>> omc.sendExpression("getClassNames()")
    ('BouncingBall', 'ModelicaServices', 'Complex', 'Modelica')
    >>> omc.sendExpression("isPartial(BouncingBall)")
    False
    >>> omc.sendExpression("isPackage(BouncingBall)")
    False
    >>> omc.sendExpression("isModel(BouncingBall)")
    True
    >>> omc.sendExpression("checkModel(BouncingBall)")
    Check of BouncingBall completed successfully.
    Class BouncingBall has 6 equation(s) and 6 variable(s).
    1 of these are trivial equation(s).
    >>> omc.sendExpression("getClassRestriction(BouncingBall)")
    model
    >>> omc.sendExpression("getClassInformation(BouncingBall)")
    ('model', '', False, False, False, '/var/lib/jenkins1/ws/OpenModelica_PR-16191/build/share/doc/omc/testmodels/BouncingBall.mo', False, 1, 1, 26, 17, (), False, False, '', '', False, '', '', '', '', '')
    >>> omc.sendExpression("getConnectionCount(BouncingBall)")
    0
    >>> omc.sendExpression("getInheritanceCount(BouncingBall)")
    0
    >>> omc.sendExpression("getComponentModifierValue(BouncingBall,e)")
    0.7
    >>> omc.sendExpression("checkSettings()")
    {'OPENMODELICAHOME': '«OPENMODELICAHOME»', 'OPENMODELICALIBRARY': '«OPENMODELICAHOME»/lib/omlibrary', 'OMC_PATH': '«OPENMODELICAHOME»/bin/omc', 'SYSTEM_PATH': '/var/lib/jenkins1/ws/OpenModelica_PR-16191/build/bin:/opt/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', 'OMDEV_PATH': '', 'OMC_FOUND': True, 'MODELICAUSERCFLAGS': '', 'WORKING_DIRECTORY': '«DOCHOME»', 'CREATE_FILE_WORKS': True, 'REMOVE_FILE_WORKS': True, 'OS': 'linux', 'SYSTEM_INFO': 'Linux 529085ccd77d 6.8.0-136-generic #136-Ubuntu SMP PREEMPT_DYNAMIC Wed Jul  1 21:53:05 UTC 2026 x86_64 x86_64 x86_64 GNU/Linux\n', 'RTLIBS': ' -Wl,--no-as-needed -Wl,--disable-new-dtags -lOpenModelicaRuntimeC -llapack -lblas -lm -lomcgc -lryu -lpthread -rdynamic', 'C_COMPILER': 'clang', 'C_COMPILER_VERSION': 'Ubuntu clang version 14.0.0-1ubuntu1.1\nTarget: x86_64-pc-linux-gnu\nThread model: posix\nInstalledDir: /usr/bin\n', 'C_COMPILER_RESPONDING': True, 'HAVE_CORBA': True, 'CONFIGURE_CMDLINE': "Configured 2026-08-07 12:52:33 using arguments:  '--disable-option-checking' '--prefix=/var/lib/jenkins1/ws/OpenModelica_PR-16191/install' 'CC=clang' 'CXX=clang++' 'FC=gfortran' 'CFLAGS=-Os' '--with-cppruntime' '--without-omc' '--without-omlibrary' '--with-omniORB' '--enable-modelica3d' '--without-hwloc' '--with-ombuilddir=/var/lib/jenkins1/ws/OpenModelica_PR-16191/build' '--cache-file=/dev/null' '--srcdir=.'"}

The common combination of a simulation followed by getting a value and doing a plot:

    >>> omc.sendExpression("simulate(BouncingBall, stopTime=3.0)")
    {'resultFile': '«DOCHOME»/BouncingBall_res.mat', 'simulationOptions': "startTime = 0.0, stopTime = 3.0, numberOfIntervals = 500, tolerance = 1e-6, method = 'dassl', fileNamePrefix = 'BouncingBall', options = '', outputFormat = 'mat', variableFilter = '.*', cflags = '', simflags = ''", 'messages': 'LOG_SUCCESS       | info    | The initialization finished successfully without homotopy method.\nLOG_SUCCESS       | info    | The simulation finished successfully.\n', 'timeFrontend': 0.001003042, 'timeBackend': 0.002497687, 'timeSimCode': 0.0007543360000000001, 'timeTemplates': 0.002119057, 'timeCompile': 0.35211555799999994, 'timeSimulation': 0.011974269000000001, 'timeTotal': 0.37055185199999996}
    >>> omc.sendExpression("val(h , 2.0)")
    0.04239430772884106

#### Import As Library

To use the module from within another python program, simply import OMCSessionZMQ from within the using program.

For example:

    # test.py
    from OMPython import OMCSessionZMQ
    omc = OMCSessionZMQ()
    cmds = [
      'loadFile(getInstallationDirectoryPath() + "/share/doc/omc/testmodels/BouncingBall.mo")',
      "simulate(BouncingBall)",
      "plot(h)"
      ]
    for cmd in cmds:
      answer = omc.sendExpression(cmd)
      print("\n{}:\n{}".format(cmd, answer))

### Implementation

#### Client Implementation

The OpenModelica Python API Interface - OMPython, attempts to mimic the OMShell's style of operations.

OMPython is designed to,

- Initialize the ZeroMQ communication.

- Send commands to the OMC server via the ZeroMQ interface.

- Receive the string results.

- Use the Parser module to format the results.

- Return or display the results.

## Enhanced OMPython Features

Some more improvements are added to OMPython functionality for querying more information about the models and simulate them. A list of new user friendly API functionality allows user to extract information about models using python objects. A list of API functionality is described below.

To get started, create a ModelicaSystem object:

    >>> from OMPython import OMCSessionZMQ
    >>> omc = OMCSessionZMQ()
    >>> model_path=omc.sendExpression("getInstallationDirectoryPath()") + "/share/doc/omc/testmodels/"
    >>> from OMPython import ModelicaSystem
    >>> mod=ModelicaSystem(model_path + "BouncingBall.mo","BouncingBall")

The object constructor requires a minimum of 2 input arguments which are strings, and may need a third string input argument.

- The first input argument must be a string with the file name of the Modelica code, with Modelica file extension ".mo". If the Modelica file is not in the current directory of Python, then the file path must also be included.

- The second input argument must be a string with the name of the Modelica model including the namespace if the model is wrapped within a Modelica package.

- The third input argument (optional) is used to specify the list of dependent libraries or dependent Modelica files e.g.,

    >>> mod=ModelicaSystem(model_path + "BouncingBall.mo","BouncingBall",["Modelica"])

- The fourth input argument (optional), is a keyword argument which is used to set the command line options e.g.,

    >>> mod=ModelicaSystem(model_path + "BouncingBall.mo","BouncingBall",commandLineOptions="-d=newInst")

### BuildModel

The buildModel API can be used after ModelicaSystem(), in case the model needs to be updated or additional simulationflags needs to be set using sendExpression()

    >>> mod.buildModel()

### Standard get methods

- getQuantities()

- getContinuous()

- getInputs()

- getOutputs()

- getParameters()

- getSimulationOptions()

- getSolutions()

Three calling possibilities are accepted using getXXX() where "XXX" can be any of the above functions (eg:) getParameters().

- getXXX() without input argument, returns a dictionary with names as keys and values as values.

- getXXX(S), where S is a string of names.

- getXXX(["S1","S2"]) where S1 and S1 are list of string elements

### Usage of getMethods

    >>> mod.getQuantities() // method-1, list of all variables from xml file
    [{'aliasvariable': None, 'Name': 'height', 'Variability': 'continuous', 'Value': '1.0', 'alias': 'noAlias', 'Changeable': 'true', 'Description': None}, {'aliasvariable': None, 'Name': 'c', 'Variability': 'parameter', 'Value': '0.9', 'alias': 'noAlias', 'Changeable': 'true', 'Description': None}]

    >>> mod.getQuantities("height") // method-2, to query information about single quantity
    [{'aliasvariable': None, 'Name': 'height', 'Variability': 'continuous', 'Value': '1.0', 'alias': 'noAlias', 'Changeable': 'true', 'Description': None}]

    >>> mod.getQuantities(["c","radius"]) // method-3, to query information about list of quantity
    [{'aliasvariable': None, 'Name': 'c', 'Variability': 'parameter', 'Value': '0.9', 'alias': 'noAlias', 'Changeable': 'true', 'Description': None}, {'aliasvariable': None, 'Name': 'radius', 'Variability': 'parameter', 'Value': '0.1', 'alias': 'noAlias', 'Changeable': 'true', 'Description': None}]

    >>> mod.getContinuous() // method-1, list of continuous variable
    {'velocity': -1.825929609047952, 'der(velocity)': -9.8100000000000005, 'der(height)': -1.825929609047952, 'height': 0.65907039052943617}

    >>> mod.getContinuous(["velocity","height"]) // method-2, get specific variable value information
    (-1.825929609047952, 0.65907039052943617)

    >>> mod.getInputs()
    {}

    >>>  mod.getOutputs()
    {}

    >>> mod.getParameters()  // method-1
    {'c': 0.9, 'radius': 0.1}

    >>> mod.getParameters(["c","radius"]) // method-2
    [0.9, 0.1]

    >>> mod.getSimulationOptions()  // method-1
    {'stepSize': 0.002, 'stopTime': 1.0, 'tolerance': 1e-06, 'startTime': 0.0, 'solver': 'dassl'}

    >>> mod.getSimulationOptions(["stepSize","tolerance"]) // method-2
    [0.002, 1e-06]

The getSolution method can be used in two different ways.

  1. using default result filename

  2. use the result filenames provided by user

This provides a way to compare simulation results and perform regression testing

    >>> mod.getSolutions() // method-1 returns list of simulation variables for which results are available
    ['time', 'height', 'velocity', 'der(height)', 'der(velocity)', 'c', 'radius']

    >>> mod.getSolutions(["time","height"])  // return list of numpy arrays

    >>> mod.getSolutions(resultfile="c:/tmpbouncingBall.mat") // method-2 returns list of simulation variables for which results are available , the resulfile location is provided by user

    >>> mod.getSolutions(["time","height"],resultfile="c:/tmpbouncingBall.mat") // return list of array

### Standard set methods

- setInputs()

- setParameters()

- setSimulationOptions()

Two setting possibilities are accepted using setXXXs(),where "XXX" can be any of above functions.

- setXXX("Name=value") string of keyword assignments

- setXXX(["Name1=value1","Name2=value2","Name3=value3"]) list of string of keyword assignments

### Usage of setMethods

    >>> mod.setInputs(["cAi=1","Ti=2"]) // method-2

    >>> mod.setParameters("radius=14") // method-1 setting parameter value

    >>> mod.setParameters(["radius=14","c=0.5"]) // method-2 setting parameter value using second option

    >>> mod.setSimulationOptions(["stopTime=2.0","tolerance=1e-08"]) // method-2

### Simulation

An example of how to get parameter names and change the value of parameters using set methods and finally simulate the "BouncingBall.mo" model is given below.

    >>>  mod.getParameters()
    {'c': 0.9, 'radius': 0.1}

    >>>  mod.setParameters(["radius=14","c=0.5"]) //setting parameter value

To check whether new values are updated to model , we can again query the getParameters().

    >>> mod.getParameters()
    {'c': 0.5, 'radius': 14}

The model can be simulated using the simulate API in the following ways,

  1. without any arguments

  2. resultfile (keyword argument) - (only filename is allowed and not the location)

  3. simargs (keyword argument) - runtime simulationflags supported by OpenModelica

    >>> mod.simulate() // method-1 default result file name will be used
    >>> mod.simulate(resultfile="tmpbouncingBall.mat")  // method-2 resultfile name provided by users
    >>> mod.simulate(simargs={"noEventEmit": None, "noRestart": None, "override": {"e": 0.3, "g": 10}}) // method-3 simulationflags provided by users

### Linearization

The following methods are proposed for linearization.

- linearize()

- getLinearizationOptions()

- setLinearizationOptions()

- getLinearInputs()

- getLinearOutputs()

- getLinearStates()

### Usage of Linearization methods

    >>> mod.getLinearizationOptions()  // method-1
    {'simflags': ' ', 'stepSize': 0.002, 'stopTime': 1.0, 'startTime': 0.0, 'numberOfIntervals': 500.0, 'tolerance': 1e-08}

    >>> mod.getLinearizationOptions("startTime","stopTime") // method-2
    [0.0, 1.0]

    >>> mod.setLinearizationOptions(["stopTime=2.0","tolerance=1e-06"])

    >>> mod.linearize()  //returns a tuple of 2D numpy arrays (matrices) A, B, C and D.

    >>> mod.getLinearInputs()  //returns a list of strings of names of inputs used when forming matrices.

    >>> mod.getLinearOutputs() //returns a list of strings of names of outputs used when forming matrices

    >>> mod.getLinearStates() // returns a list of strings of names of states used when forming matrices.