Transfer function in python

Since v11 it is possible to write the transfer functions in python (@see #165). The great advantage is that the developer can take advantage of the simplicity of this language and the great number of python libraries to write their preferred transfer function.

Internally a java object loads the python code and delegates to it the execution of the transfer function. The python code is a class that extends TransferFunction. An example is provided by the MinMaxThreshold.

The developer optionally overrides

• initialize that is called by the ASCE before running any TF and provides the IDs and types of the inputs and the output; in this method the developer usually allocates the resource
• shutdown is called when the TF is ready to be shut down; the developer usually frees here the resources allocated

The developer must always implement the eval method that finally returns the output generated by the inputs to the computing element.

At run-time, the computing element loads a special java transfer function, PythonExecutorTF that delegates each call to the python code. Before running each method, the java parameters are translated into proper python object and when the python code returns a value, it is translated back to a java object before being communicated to the computing element. For this reason execution of the python TF is the less performant method provided by the IAS: the most performant is the native scala, java is a bit slower due to the traqnslation of scala data structures into java; python is even slower because of the translation of java data structures in python data structures.

HowTo

In the actual implementation the python TF is executed by java by means of jep (v3.9.0): the folder that contains libjep.so must be in the path of the libraries to load (for example in LD_LIBRARY_PATH)

PYTHON_PATH must point (among the others) to the folder where the python transfer functions have been stored. The ones provided by the core are in $IAS_ROOT/lib/python that is already set in the path.

In the CDB, the ASCE has the full name of the python class of the TF function, as usual. The definition of the transfer function in tfs.json must report the name of the name of the python class to run and python as programming language. For example

tfs.json
[
        { "className" : "IasTransferFunction.Impls.MinMaxThreshold", "implLang" : "PYTHON" }
]

Java/scala data types mapping to python

The IAS supports a definite set of data types as defined in IASTypes. The following table explains how scala and java datatype are mapped to python

IAS type	python
LONG, INT, SHORT, BYTE, TIMESTAMP	int
DOUBLE, FLOAT	float
BOOLEAN	True, False
CHAR, STRING	str
ARRAYOFLONGS	List[int]
ARRAYOFDOUBLES	List[float]
ALARM	Alarm

The TIMESTAMP is a long with the same meaning of java: the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

The python Alarm is an enumerated.

Templates

If the component where the python TF runs is templated, the number of the instance is available in the self.instance property: it is an int if the component is templated, None otherwise. The method getValue(inputs, id, instance) helps getting an input of the passed instance