API Reference for Enthought Tool Suite 3.0.1

Function summary

• has_units(func = None, summary = '', doc = '', inputs = None, outputs = None)

Functions

• has_units(func = None, summary = '', doc = '', inputs = None, outputs = None)

  Function decorator: Wrap a standard python function for unit conversion.

  Parameters

  func : function, optional

  The function to wrap. Usually, has_units will be used as a bare "@has_units" decorator, so this argument will usually be supplied by the interpreter as it interprets that syntax.

  summary : str, optional

  A short string describing the function.

  doc : str, optional

  A longer string describing the function in detail.

  inputs : str, optional

  A string containing information about unit conversion, etc. for arguments in the function. The argument names in this string must match those in the python signature. The order the arguments are specified in does not matter as the order of arguments from the wrapped function is always used. The format of the string is a as follows:

     "a: notes on a:units=m/s;b: notes on b:units=m/s"
  
  That is, information about each argument is separated by
  a semi-colon (';').  Each argument has three fields that are
  separated by colons (':').  The first is the name of the variable.
  The 2nd is a string.  The 3rd specified the units.  Other fields
  may be added later.
  

  outputs : str, optional

  A string with the same format as the 'inputs' string that specifies the output variables. This is an ordered list as there is no way to determine the functions outputs from the function object.

  Description

  This decorator adds a unit conversion step to input and output variables of a python function. The resulting function can be used as a standard python function and has an identical calling signature to the wrapped function. If passed standard scalars and arrays as input, it will behave identically. If "unitted" objects, such as UnitArray, are handed in, however, they will be unit converted from their given units to the units expected by the function. In this case, output variables are converted from arrays or scalars to UnitArray or UnitScalar so that the results carry the units with them. Note that these objects are derived from standard numpy.ndarray and float objects, so they will behave exactly like them. The only caveat to this is that you should use isinstance(value, ndarray) instead of "type(array) is ndarray" when testing for their type, but you should be doing that anyways.

  Regardless of whether the inputs have units or not, the actual values passed to the function will be stripped of units. The wrapped function will only deal with regular numpy arrays and scalars.

  If units are not assigned to a variable, absolutely no conversion is applied to that variable.

  Example definition of a unitted addition function:

  >>> from enthought.numerical_modeling.units.api import has_units, UnitArray
  >>> @has_units
  ... def add(a,b):
  ...     ''' Add two arrays in ft and convert them to m.
  ...
  ...         Parameters
  ...         ----------
  ...         a : array : units=ft
  ...             An array
  ...         b : array : units=ft
  ...             Another array
  ...
  ...         Returns
  ...         -------
  ...         c : array : units=m
  ...             c = a + b
  ...     '''
  ...     return (a+b)*0.3048
  

  >>> from numpy import array
  >>> a = array((1,2,3))
  >>> add(a,a)
  array([ 0.6096,  1.2192,  1.8288])
  

  >>> from enthought.units.length import m
  >>> a = UnitArray((1,2,3), units=m)
  >>> add(a,a) # (Converts m -> ft -> m)
  UnitArray([ 2.,  4.,  6.])
  >>> add(a,a).units
  1.0*m
  

  Alternatively, parameter information can be specified in the decorator:

  >>> from numpy import array
  >>> from enthought.numerical_modeling.units.api import has_units
  >>> @has_units(inputs="a:an array:units=ft;b:array:units=ft",
  ...            outputs="result:an array:units=m")
  ... def add(a,b):
  ...     " Add two arrays in ft and convert them to m. "
  ...     return (a+b)*0.3048
  

  The returned function has several attributes attached to it:

  summary: A short description of the function. This is taken from the

  'summary' argument to the decorator.

  doc: A longer description of the function. This is taken from the

  'doc' argument to the decorator.

  inputs: A list of Variable objects, for each argument to the function

  in the order they are defined in the python function signature. If you did not supply any information about the argument in "inputs", then a default Variable object is created.

  outputs: A list of Variable objects, for each output of the function

  in the order they you specify them in the "outputs" variable in the argument list.

Imported Names

© Copyright 2002-2008 Enthought, Inc.