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