Units system

brian.have_same_dimensions(obj1, obj2)

Tests if two scalar values have the same dimensions, returns a bool.

Note that the syntax may change in later releases of Brian, with tighter integration of scalar and array valued quantities.

brian.is_dimensionless(obj)

Tests if a scalar value is dimensionless or not, returns a bool.

Note that the syntax may change in later releases of Brian, with tighter integration of scalar and array valued quantities.

exception brian.DimensionMismatchError(description, *dims)

Exception class for attempted operations with inconsistent dimensions

For example, 3*mvolt + 2*amp raises this exception. The purpose of this class is to help catch errors based on incorrect units. The exception will print a representation of the dimensions of the two inconsistent objects that were operated on. If you want to check for inconsistent units in your code, do something like:

try:
    ...
    your code here
    ...
except DimensionMismatchError, inst:
    ...
    cleanup code here, e.g.
    print "Found dimension mismatch, details:", inst
    ...

brian.check_units(**au)

Decorator to check units of arguments passed to a function

Sample usage:

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

would fail, but:

getvoltage(1*amp,1*ohm,wibble=1*metre)

would pass. String arguments are not checked (e.g. getvoltage(wibble='hello') would pass).

The special name result is for the return value of the function.

An error in the input value raises a DimensionMismatchError, and an error in the return value raises an AssertionError (because it is a code problem rather than a value problem).

Notes

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.

Typically, you shouldn’t need to use any details about the following two classes, and their implementations are subject to change in future releases of Brian.

class brian.Quantity(value)

A number with an associated physical dimension.

In most cases, it is not necessary to create a Quantity object by hand, instead use the constant unit names second, kilogram, etc. The details of how Quantity objects work is subject to change in future releases of Brian, as we plan to reimplement it in a more efficient manner, more tightly integrated with numpy. The following can be safely used:

• Quantity, this name will not change, and the usage isinstance(x,Quantity) should be safe.
• The standard unit objects, second, kilogram, etc. documented in the main documentation will not be subject to change (as they are based on SI standardisation).
• Scalar arithmetic will work with future implementations.

class brian.Unit(value)

A physical unit

Normally, you do not need to worry about the implementation of units. They are derived from the Quantity object with some additional information (name and string representation). You can define new units which will be used when generating string representations of quantities simply by doing an arithmetical operation with only units, for example:

Nm = newton * metre

Note that operations with units are slower than operations with Quantity objects, so for efficiency if you do not need the extra information that a Unit object carries around, write 1*second in preference to second.