OpenModelicaCompiler 0.0.0.dev2

OpenModelica compiler (omc) interface for Python>=3.6

OpenModelicaCompilerForPython

OpenModelica compiler (omc) interface for Python>=3.6

Quick tour

Setup

Make sure that OpenModelica is installed on your system.

$ omc --version

OpenModelica official page https://openmodelica.org/

Install OpenModelicaCompiler with pip.

$ python3 -m pip install OpenModelicaCompiler

omc4py is acutual package name. omc4py.open_session() will return session object which interfaces to omc.

#!/usr/bin/env python3
import omc4py

with omc4py.open_session() as session:
    print(session.getVersion())

More usage about open_session(...)

If omc4py.open_session cannot find omc, such as if you have not added OpenModelica to your PATH environment variable, you can specify a valid omc command name or omc executable path by str.

import omc4py

with omc4py.open_session(
    "C:/OpenModelica1.13.0-64bit/bin/omc.exe"
) as session:
    print(session.getVersion())

It is also possible to open multiple sessions with different versions of omc at the same time by explicitly specifying omc.

from contextlib import ExitStack
import omc4py

with ExitStack() as stack:
    session_13 = stack.enter_context(
        omc4py.open_session("C:/OpenModelica1.13.0-64bit/bin/omc.exe")
    )
    session_14 = stack.enter_context(
        omc4py.open_session("C:/Program Files/OpenModelica1.14.0-64bit/bin/omc.exe")
    )

    print("v1.13.0:", session_13.getVersion())
    print("v1.14.0:", session_14.getVersion())

As shown above, it is recommended to ensure that session is closed by calling omc4py.open_session() via with-statement.

However, sometimes you want to use session interactively, like OMShell. omc4py closes all unclosed sessions when exiting the python interpreter.

>>> from omc4py import *
>>> session = open_session()
>>> session.loadString("""
... package A
...     package B
...             package C
...             end C;
...     end B;
... end A;
... """)
True
>>> list(session.getClassNames("A", recursive=True))
[TypeName('A'), TypeName('A.B'), TypeName('A.B.C')]
>>>
>>>
>>> exit()  # session will be closed internally

Besides, session object has __close__ method to explicitly close session.

>>> from omc4py import *
>>> session = open_session()
>>> session.__close__()
>>>
>>> exit()

About session API

All session methods are OpenModelica.Scripting.* functions. The names and types of arguments and return values are the same as the original modelica function, and session internally converts between the python class and the modelica class.

If you want to know more about each session method, you can display it with the help () function.

• UserGuide for OpenModelica Scripting API (v1.14)

• UserGuide for OpenModelica Scripting API (v1.15)

• UserGuide for OpenModelica Scripting API (v1.16)

• UserGuide for OpenModelica Scripting API (latest)

Documentation in OpenModelica build server shows exhaustive information about OpenModelica.Scripting. You will find sub-packages not explained user guide.

• OpenModelica.Scripting.Internal.*
• OpenModelica.Scripting.Experimental.*

They are available from absolute reference

# Example for "timerTick" and "timerTock"
# in "OpenModelica.Scripting.Internal.Time"
from omc4py import open_session
from time import sleep

timer_index: int = 1

with open_session() as session:
    session.OpenModelica.Scripting.Internal.Time.timerTick(timer_index)

    sleep(0.1)

    # show elapsed time from last timerTick
    print(session.OpenModelica.Scripting.Internal.Time.timerTock(timer_index))

Typical API

loadModel

Load library and returns True if success. You can specify versions by second argument

import omc4py

with omc4py.open_session() as session:
    assert(session.loadModel("Modelica"))  # load MSL

import omc4py

with omc4py.open_session() as session:
    assert(session.loadModel("Modelica", ["3.2.3"]))  # load MSL 3.2.3

getClassNames

Returns array of class names in the given class

import omc4py

with omc4py.open_session() as session:
    assert(session.loadModel("Modelica"))
    for className in session.getClassNames("Modelica"):
        print(className)

By default, getClassNames() only returns "sub" classes. If you want to know all classes belongs to the class set recursive=True.

import omc4py

with omc4py.open_session() as session:
    assert(session.loadModel("Modelica"))
    for className in session.getClassNames("Modelica", recursive=True):
        print(className)  # many class names will be printed

getComponents

Returns array of component (variable, parameter, constant, ...etc) profiles

import omc4py

with omc4py.open_session() as session:
    assert(session.loadModel("Modelica", ["3.2.3"]))
    for component in session.getComponents("Modelica.Constants"):
        print(
            f"{component.className.last_identifier!s:<20}"
            f"{component.name!s:<15}"
            f"{component.comment!r}"
        )

Exception handling

• OMCNotification, OMCWarning, OMCError are raised from omc
• OMCRuntimeError is raised from omc4py python implementation (not from omc)

We are not sure about whole OpenModelica's exception handling policy. Through omc4py project, We found that there are 4 situation for expection caused by function calls.

omc behavior

1. Function returns "\n" instead of valid value (no exception info)
2. Function returns formatted error messages (contains sourceInfo, level, kind, message) instead of valid value
3. Function returns unformatted error message (typically, startswith "* Error") instead of valid value
4. Function returns valid value and set exception messages internally

omc4py behavior

1. function returns None instead of valid result (no exception will be sent)
2. function send OMCNotification or OMCWarning, or raise OMCError
3. function raise OMCRuntimeError with the message returned by the omc
4. function returns valid value. You can check exceptions explicitly by session.__check__()

Normally, 4th case seems to be notification or warning. If you want to be sure to check for exceptions, call session.__check__() before exit doubtful context.

from omc4py import open_session

def doubtful_task(session):
    # session.doubtful_API1(...)
    # session.doubtful_API2(...)
    # session.doubtful_API3(...)
    session.__check__()

with open_session() as session:
    doubtful_task(session)