check_units function

(Shortest import: from brian2 import check_units)


Decorator to check units of arguments passed to a function


In case the input arguments or the return value do not have the expected dimensions.


This decorator will destroy the signature of the original function, and replace it with the signature (*args, **kwds). Other decorators will do the same thing, and this decorator critically needs to know the signature of the function it is acting on, so it is important that it is the first decorator to act on a function. It cannot be used in combination with another decorator that also needs to know the signature of the function.


>>> from brian2.units import *
>>> @check_units(I=amp, R=ohm, wibble=metre, result=volt)
... def getvoltage(I, R, **k):
...     return I*R

You don’t have to check the units of every variable in the function, and you can define what the units should be for variables that aren’t explicitly named in the definition of the function. For example, the code above checks that the variable wibble should be a length, so writing

>>> getvoltage(1*amp, 1*ohm, wibble=1)  
Traceback (most recent call last):
DimensionMismatchError: Function "getvoltage" variable "wibble" has wrong dimensions, dimensions were (1) (m)

fails, but

>>> getvoltage(1*amp, 1*ohm, wibble=1*metre)
1. * volt

passes. String arguments or None are not checked

>>> getvoltage(1*amp, 1*ohm, wibble='hello')
1. * volt

By using the special name result, you can check the return value of the function.