Simplified interface function specification¶
In addition to the specification of remote interface functions by using
the @legacy_function
decorator, a simplified method is available,
which can handle most cases of interface functions. Here we will
describe the simplified interface function specification.
Example¶
Let’s start with a simple example specification:
@legacy_function
def sum():
function = LegacyFunctionSpecification()
function.addParameter('x', 'd', function.IN)
function.addParameter('y', 'd', function.IN)
function.addParameter('sum', 'd', function.OUT)
function.result_type = 'i'
function.can_handle_array = True
return function
This can be converted to:
@remote_function(can_handle_array=True)
def sum(x='d',y='d'):
returns (sum='d')
As can be seen the parameters are specified in keyword/value style.
can_handle_array
and must_handle_array
are supplied, if
necessary, as keywords to the decorator. A default integer return value
(for the error code) is implied (but can be overridden, see below). The
following table lists the options for the parameter specifications:
data type | no default value | default value (for input) |
---|---|---|
boolean | “b”, “bool” | True, False |
integer | “i”, “int32” | <int>, numpy.int32(<value>) |
long | “l”, “int64” | numpy.int64(<value>) |
float | “f”, “float32” | numpy.float32(<value>) |
double | “d”, “float64” | <float>, numpy.float64(<value>) |
string | “s”, “string” | “any other string” |
A unit specification can be added. Remember that parameters without default cannot follow parameters with default. So the following will generate an error:
@remote_function(can_handle_array=True)
def sum(x=0.,y='d'):
returns (sum='d')
Below are some more examples of valid specifications:
@remote_function
def initialize_code():
pass
@remote_function
def get_time():
returns (time=0. | units.s)
@remote_function(must_handle_array=True)
def inout_sum(x='d',y='d', sum=0.):
returns (sum=0.)
@remote_function
def function_with_float_return():
return (__result=0.)
One limitation of this type of specification is that they won’t work if generated dynamically (so don’t try, for example, to generate a bunch of functions based on a list of parameter names).