API for Accessing OpenModelica Models From Python B. Lie S. Bajracharya, A. Mengist, L. Buffoni, A. Kumar University College of Southeast Norway M. Sjolund,¨ A. Asghar, A. Pop, P. Fritzson Porsgrunn, Norway Linkoping¨ University Email: [email protected] Sweden Email: [email protected] Abstract—This paper describes a new API for operating packages in Python, or freely develop one’s own analysis on Modelica models in Python, through OpenModelica. routines in Python. Modelica is an object oriented, acausal language for describ- ing dynamic models in the form of Differential Algebraic Modelica and OpenModelica Shell in themselves have Equations. Modelica and various implementations such as relatively little support for advanced analysis of models. OpenModelica have limited support for model analysis, and Examples of such desirable analysis capabilities could it is of interest to integrate Modelica code with scripting lan- be (i) study of model sensitivity, (ii) random number guages such as Python, which facilitate the needed analysis possibilities. The API is based on a new class ModelicaSystem generation and statistical analysis, (iii) Monte Carlo sim- within package OMPython of OpenModelica, with methods ulation, (iv) advanced plotting capabilities, (v) general that operate on instantiated models. Emphasis has been put optimization capabilities, (vi) linear analysis and control on specification of a systematic structure for the various synthesis, etc. Scripting languages such as MATLAB and methods of the class. A simple case study involving a water Python hold most of these desirable analysis capabilities, tank is used to illustrate the basic ideas. and it is of interest to integrate Modelica models with such Keywords-OpenModelica, Modelica, Python, Python API script languages. The free JModelica.org tool includes a Python package for converting Modelica models to FMUs, I. INTRODUCTION and then for importing the FMU as a Python object. This Modelica is a modern, equation based, acausal language way, Modelica models can essentially be simulated from for encoding models of dynamic systems in the form Python — Optimica is also supported. It is possible to do of differential algebraic equations (DAEs), see e.g. [3] more advanced analysis with JModelica.org3 via CasADi, on Modelica and e.g. [2] on DAEs. OpenModelica1 [4] see e.g. [7] and [8]. However, the possibilities in the work is a mature, freely available toolset that includes Open- of Perera et al. use an old version of JModelica.org. It Modelica Connection Editor (flow sheeting, textual editor would be more ideal if these possibilities were supported with debugging facilities, and simulation environment) by the tool developer. and the OMShell (command line execution, script based It is thus of interest to develop an extension of execution). OpenModelica Shell supports commands for OMPython which enables simulation and analysis of Mod- simulation of Modelica models, for use of the Modelica elica models with a better integration with the Python extension Optimica, for carrying out analytic linearization language, and in particular that such an extension is pro- via the Modelica package Modelica LinearSystem2, and vided by the OpenModelica developers. A Python API4 for for converting Modelica models into Functional Mock-Up controlling Modelica simulation and analysis from Python Units (FMUs) as well as for converting FMUs back to was proposed in February 20155. Based on this proposal, Modelica models. A tool OMPython has been developed a first version of a Python API has been implemented [1], and communicates with OpenModelica via CORBA, [5], and has then been further revised. This paper discusses [6]. Essentially, OMPython is a Python package which the API, and illustrates how it can be used for automatic makes it possible to pass OpenModelica Shell commands analysis of Modelica models from Python, exemplified by as strings to a Python function, and then receive the results a simple water tank model. The paper is organized as back into Python. This possibility does, however, require follows. In Section 2, an overview of the API is given. good knowledge of OpenModelica Shell commands and In Section 3, use of the API is illustrated through simple syntax. A tool, PySimulator,2 has been developed to ease analysis of a nonlinear reactor model. In Section 4, the API the use of Modelica from Python, [9], [6]. Essentially, is discussed, some conclusions are drawn, and future work PySimulator provides a GUI based on Python, where Mod- is discussed. Appendices hold details of the nonlinear elica models can be run and results can presented. It is also reactor model. possible to analyze the results using various packages in Python, e.g. FFT analysis. However, PySimulator currently does not give the user full freedom to integrate Modelica models with Python and use the full available set of 3www.JModelica.org 4API = Application Programming Interface 1www.openmodelica.org 5Python API for Accessing OpenModelica Models, by B. Lie, February 2https://pypi.python.org/pypi/PySimulator 20, 2015, communicated to P. Fritzson at Linkoping¨ University. II. OVERVIEW OF PYTHON API In this subsection, we discuss how to import the class, A. Goal and how to use the constructor to instantiate an object. The object is imported from package OMPython, i.e. Modeling and the use of Modelica with Python is of with Python commands8: interest to a wide range of engineering disciplines. The computer science threshold of using Modelica with Python >>> from OMPython import ModelicaSystem should be low. Ideally, the OMPython extension should Other Python packages to be used such as numpy, work with simple one-click Python installations such 6 7 matplotlib, pandas, etc. must be imported in a as Anaconda and Canopy . Furthermore, the extension similar manner. should support both 32 bit and 64 bit OpenModelica, The object constructor requires a minimum of 2 input work with both 32 bit and 64 bit Python, with Python arguments which are strings, and may need a third string 2.7 and Python 3.X, and on platforms Windows, OSX and input argument. Linux. These requirements e.g. imply that results should be returned as standard Python structures. However, it is • The first input argument must be a string with the reasonable that the OMPython extension depends on the file name of the Modelica code, with Modelica file NumPy package. Because Python has excellent plotting extension .mo. If the Modelica file is not in the capabilities e.g. via Matplotlib, the OpenModelica Shell current directory of Python, then the file path must facility for plotting results should not be implemented — also be included. this is more naturally handled directly in Python. • The second input argument must be a string with the name of the Modelica model, including the names- B. Installing the OMPython extension pace if the model is wrapped within a Modelica Under Windows, the new OMPython package. extension will be automatically installed • A third input argument is used if the Modelica model in a file __init__.py in directory builds on other Modelica code, e.g. the Modelica sharenomcnscriptsnPythonInterfacenOMPython Standard Library. in the OpenModelica directory when OpenModelica The result of using the object constructor is a Python is downloaded and installed. In order to activate the object. extension, the user must next run the command python Example 1: Use of constructor. setup.py install from the command line in Suppose we have a Modelica model with name CSTR the directory of the setup.py file, which is in the wrapped in a Modelica package Reactors — stored in file PythonInterface subdirectory. It follows that in Reactor.mo: order to activate the extension, the user must first install package Reactors Python on the relevant computer. Under Linux/OSX, // ... pip pypi OMPython is part of ( ) and is not shipped model CSTR with the OpenModelica installer. /// ... C. Status end CSTR; // Currently, the Python API is in a development status end Reactors; and has been tested with 32 bit Python 2.7 from the Anaconda installation in tandem with 32 bit OpenMod- If this model does not use any external Modelica code elica v. 1.9.4 under Windows 8.1 and OpenModelica v. and the file is located in the current Python directory, the 1.9.6 under Windows 10, and a modified __init__.py following Python code instantiates a Python object mod: file. OpenModelica uses CORBA for communication, and >>> mod = ModelicaSystem(’Reactors.mo’, CORBA compatibility needs some refinement. The code ’Reactors.CSTR’) is somewhat unstable when run from the Spyder IDE used with the Anaconda installation, but runs fine from Jupyter The user is free to choose any valid Python label name notebooks. for the Python object. All methods of class ModelicaSystem refers to the D. Description of the API instantiated object, in standard Python fashion. Thus, The API is described in the subsections below. method simulate() is invoked with the Python com- 1) Python Class and Constructor: The name of the mand: Python class which is used for operation on Modelica >>> mod.simulate() models, is ModelicaSystem. This class is equipped with an object constructor of the same name as the class. In In the subsequent overview of methods, the object name addition, the class is equipped with a number of methods is not included. In practice, of course, it must be included for manipulating the instantiated objects. in order to operate on the object in question. 6www.continuum.io/downloads 8The Python prompt >>> is not typed, and does not appear in script 7www.enthought.com/products/canopy files, in iPython or in Jupyter notebooks. Methods may have no input arguments, one, or several • Variability — ’continuous’, input arguments. Methods may or may not return results ’parameter’. — if the methods do not return results, the results are When applying the Pandas method DataFrame to the stored within the object. returned list of dictionaries, the result is a conveniently 2) Utility routines, converting Modelica $ FMU: Two typeset table in Jupyter notebooks.