This package contains classes that call Python functions. The classes can be used to send data to Python functions, and to obtain data from Python functions. This allows for example to use Python to communicate with web services, with hardware, or to do other computations inside a Python module.
The code has been tested with Python 2.7 on Linux 32 bit, Linux 64 bit, and Windows 32 bit. Windows 64 bit is currently supported if Dymola is run as a 32 bit application.
To use classes from this package, a Python 2.7
runtime environment must be installed.
Also, the system environment variable
PYTHONPATH must be set in order for Python
to find the modules that contain the functions.
These modules are stored in the directory
Buildings/Resources/Python-Sources.
In addition, an environment variable (LD_LIBRARY_PATH on Linux
and PATH on Windows) must be set in order for a simulation
environment to find the dynamically linked libraries.
The next sections explain how to set these variables for the
following system configurations:
| System | Settings |
|---|---|
| Linux 32 bit, Dymola 2014 |
Enter on a console the command
export PYTHONPATH=${PYTHONPATH}:"Path_To_Buildings_Library"/Resources/Python-Sources
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:"Path_To_Buildings_Library"/Resources/Library/linux32
Alternatively, these lines could be added to the file ~/.bashrc.
|
| Linux 64 bit, Dymola 2014 | Use the same commands as for Linux 64 bit, Dymola 2014 because Dymola 2014 only generates 32 bit code. |
| Linux 32 bit, Dymola 2013 FD01 |
Enter on a console the command
export PYTHONPATH=${PYTHONPATH}:"Path_To_Buildings_Library"/Resources/Python-Sources
Alternatively, these lines could be added to the file ~/.bashrc.Next, modify /opt/dymola/bin/dymola.sh by replacing the line
export LD_LIBRARY_PATH=$DYMOLA/bin/libwith export LD_LIBRARY_PATH=$DYMOLA/bin/lib:"Path_To_Buildings_Library"/Resources/Library/linux32 export LD_LIBRARY_PATH=$DYMOLA/bin/lib:Resources/Library/linux32 |
| Linux 64 bit, Dymola 2013 FD01 | Use the same commands as for Linux 32 bit, Dymola 2013 FD01 because Dymola 2013 FD01 only generates 32 bit code. |
| Windows 32 bit, Dymola 2014
Windows 64 bit, Dymola 2014 Windows 32 bit, Dymola 2013 FD01 Windows 64 bit, Dymola 2013 FD01 |
Add to the system environment variable PYTHONPATH the directory
"Path_To_Buildings_Library"\Resources\Python-Sources.
|
The parameters nDblWri (or nIntWri or nStrWri)
and nDblRea (or nIntRea) declare
how many double (integer or string) values should be written to, or read from, the Python function.
These values can be zero, in which case the Python function receives no
arguments for this data type, or it must return a list with zero elements.
However, because Modelica does not allow arrays with
zero elements, the arrays
dblWri and dblRea, respectively, must contain exactly one element
if nDblWri=0 or nDblRea=0.
In this situation, dblWri is a dummy argument that will not be written to Python,
and dblRea contains a number that must not be used in any model.
The arguments of the python functions are, in this order,
floats, integers and strings.
If there is only one element of each data type, then a single value is passed.
If there are multiple elements of each data type, then they are stored in a list.
If there is no value of a data type (such as if nDblWri=0), then the argument is not present.
Thus, if a data type is not present, then the function will not receive an empty list of this data type.
If there are no arguments at all, then the function takes no arguments.
The table below shows the list of arguments for various combinations where no, one or two double values, integers and strings are passed as an argument to a Python function.
| nDblWri | nIntWri | nStrWri | Arguments |
|---|---|---|---|
| 1 | 0 | 0 | 1. |
| 0 | 1 | 1 | 1, "a" |
| 2 | 0 | 2 | [1.0, 2.0], ["a", "b"] |
| 1 | 1 | 1 | 1.0, 2, "a" |
| 1 | 2 | 0 | 1.0 , [1, 2] |
| 2 | 1 | 0 | [1.0, 2.0], 1 |
| 2 | 2 | 2 | [1.0, 2.0], [1, 2], ["a", "b"] |
The Python function must return their values in the following order:
nDblRea=1) or a list of doubles
(if nDblRea > 1).
nIntRea=1) or a list of integers
(if nIntRea > 1).
nDblRea = nIntRea = 0, then the return values of the function, if any, are
ignored.
The table below shows valid return types for various combinations where no, one or two double values and integer values are returned.
| nDblRea | nIntRea | Return value |
|---|---|---|
| 1 | 0 | 1. |
| 0 | 1 | 1 |
| 2 | 0 | [1.0, 2.0] |
| 1 | 1 | 1.0, 2 |
| 1 | 2 | 1.0 , [1, 2] |
| 2 | 1 | [1.0, 2.0], 1 |
| 2 | 2 | [1.0, 2.0], [1, 2] |
The functions that exchange data with Python are implemented as pure
Modelica functions.
Pure functions always return the same value if called repeatedly.
If these functions are used to call hardware sensors or web services,
they need to be called from a when-equation.
See the Modelica language specification for an explanation of pure and impure functions.
The example
Buildings.Utilities.IO.Python27.Functions.Examples.Exchange
contains various calls to different Python functions.
The Python functions are stored in the directory
Buildings/Resources/Python-Sources.
The example Buildings.Utilities.IO.Python27.Examples.KalmanFilter shows how to implement in a Modelica block a call to a Python function.
String values cannot be returned from a Python function.
The reason is that Dymola 2013 FD01 generates a compile time error
if a Modelica function returns (Real[nR], Integer[nI], String).
This will be fixed in Dymola 2014.
(Support request #14983.)