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