Description: "User's Guide"

- Home > Modelica

## Buildings.Utilities.IO.Python27.UsersGuide

User's Guide

### Information

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.

#### Software configuration to use classes from this package

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/lib
with
      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`.

#### Number of values to read to Python and write from Python

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.

#### Arguments of the Python function

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"]

#### Returns values of the Python function

The Python function must return their values in the following order:

1. If the function returns one or multiple double values, then the first return value must be a double (if `nDblRea=1`) or a list of doubles (if `nDblRea > 1`).
2. If the function returns one or multiple integer values, then the next return value must be an integer (if `nIntRea=1`) or a list of integers (if `nIntRea > 1`).
3. If `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]

#### Pure Modelica functions (functions without side effects)

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.

#### Examples

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.

#### Implementation notes

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.)

#### Known Issues

The Python installation of Ubuntu 14.04 has a bug that causes Dymola to produce output of the following form:

    Traceback (most recent call last):
      File "/usr/lib/python2.7/site.py", line 563, in <module>
        main()
      File "/usr/lib/python2.7/site.py", line 545, in main
        known_paths = addusersitepackages(known_paths)
      File "/usr/lib/python2.7/site.py", line 272, in addusersitepackages
        user_site = getusersitepackages()
      File "/usr/lib/python2.7/site.py", line 247, in getusersitepackages
        user_base = getuserbase() # this will also set USER_BASE
      File "/usr/lib/python2.7/site.py", line 237, in getuserbase
        USER_BASE = get_config_var('userbase')
      File "/usr/lib/python2.7/sysconfig.py", line 578, in get_config_var
        return get_config_vars().get(name)
      File "/usr/lib/python2.7/sysconfig.py", line 524, in get_config_vars
        _init_posix(_CONFIG_VARS)
      File "/usr/lib/python2.7/sysconfig.py", line 408, in _init_posix
        from _sysconfigdata import build_time_vars
      File "/usr/lib/python2.7/_sysconfigdata.py", line 6, in <module>
        from _sysconfigdata_nd import *
    ImportError: No module named _sysconfigdat
    ...(message truncated)

As a work-around, type in a shell the commands

    $ cd /usr/lib/python2.7
    $ sudo ln -s plat-x86_64-linux-gnu/_sysconfigdata_nd.py .

See also https://bugs.launchpad.net/ubuntu/+source/python2.7/+bug/1115466.

Extends from Modelica.Icons.Information (Icon for general information packages).