Quantity class

(Shortest import: from brian2 import Quantity)

class brian2.units.fundamentalunits.Quantity(arr, dim=None, dtype=None, copy=False, force_quantity=False)[source]

Bases: numpy.ndarray, object

A number with an associated physical dimension. In most cases, it is not necessary to create a Quantity object by hand, instead use multiplication and division of numbers with the constant unit names second, kilogram, etc.

See also

Unit

Notes

The Quantity class defines arithmetic operations which check for consistency of dimensions and raise the DimensionMismatchError exception if they are inconsistent. It also defines default and other representations for a number for printing purposes.

See the documentation on the Unit class for more details about the available unit names like mvolt, etc.

Casting rules

The rules that define the casting operations for Quantity object are:

  1. Quantity op Quantity = Quantity Performs dimension checking if appropriate

  2. (Scalar or Array) op Quantity = Quantity Assumes that the scalar or array is dimensionless

There is one exception to the above rule, the number 0 is interpreted as having “any dimension”.

Examples

>>> from brian2 import *
>>> I = 3 * amp # I is a Quantity object
>>> R = 2 * ohm # same for R
>>> I * R
6. * volt
>>> (I * R).in_unit(mvolt)
'6000. mV'
>>> (I * R) / mvolt
6000.0
>>> X = I + R  
Traceback (most recent call last):
    ...
DimensionMismatchError: Addition, dimensions were (A) (m^2 kg s^-3 A^-2)
>>> Is = np.array([1, 2, 3]) * amp
>>> Is * R
array([ 2.,  4.,  6.]) * volt
>>> np.asarray(Is * R) # gets rid of units
array([ 2.,  4.,  6.])

Attributes

dimensions

The physical dimensions of this quantity.

is_dimensionless

Whether this is a dimensionless quantity.

dim

The physical dimensions of this quantity.

Methods

with_dimensions(value, *args, **keywords)

Create a Quantity object with dim.

has_same_dimensions(other)

Return whether this object has the same dimensions as another.

in_unit(u[, precision, python_code])

Represent the quantity in a given unit.

in_best_unit([precision, python_code])

Represent the quantity in the “best” unit.

Details

dimensions

The physical dimensions of this quantity.

is_dimensionless

Whether this is a dimensionless quantity.

dim
static with_dimensions(value, *args, **keywords)[source]

Create a Quantity object with dim.

Parameters

value : {array_like, number}

The value of the dimension

args : {Dimension, sequence of float}

Either a single argument (a Dimension) or a sequence of 7 values.

kwds :

Keywords defining the dim, see Dimension for details.

Returns

q : Quantity

A Quantity object with the given dim

Examples

All of these define an equivalent Quantity object:

>>> from brian2 import *
>>> Quantity.with_dimensions(2, get_or_create_dimension(length=1))
2. * metre
>>> Quantity.with_dimensions(2, length=1)
2. * metre
>>> 2 * metre
2. * metre
has_same_dimensions(other)[source]

Return whether this object has the same dimensions as another.

Parameters

other : {Quantity, array-like, number}

The object to compare the dimensions against.

Returns

same : bool

True if other has the same dimensions.

in_unit(u, precision=None, python_code=False)[source]

Represent the quantity in a given unit. If python_code is True, this will return valid python code, i.e. a string like 5.0 * um ** 2 instead of 5.0 um^2

Parameters

u : {Quantity, Unit}

The unit in which to show the quantity.

precision : int, optional

The number of digits of precision (in the given unit, see Examples). If no value is given, numpy’s get_printoptions() value is used.

python_code : bool, optional

Whether to return valid python code (True) or a human readable string (False, the default).

Returns

s : str

String representation of the object in unit u.

See also

in_unit()

Examples

>>> from brian2.units import *
>>> from brian2.units.stdunits import *
>>> x = 25.123456 * mV
>>> x.in_unit(volt)
'0.02512346 V'
>>> x.in_unit(volt, 3)
'0.025 V'
>>> x.in_unit(mV, 3)
'25.123 mV'
in_best_unit(precision=None, python_code=False, *regs)[source]

Represent the quantity in the “best” unit.

Parameters

python_code : bool, optional

If set to False (the default), will return a string like 5.0 um^2 which is not a valid Python expression. If set to True, it will return 5.0 * um ** 2 instead.

precision : int, optional

The number of digits of precision (in the best unit, see Examples). If no value is given, numpy’s get_printoptions() value is used.

regs : UnitRegistry objects

The registries where to search for units. If none are given, the standard, user-defined and additional registries are searched in that order.

Returns

representation : str

A string representation of this Quantity.

See also

in_best_unit()

Examples

>>> from brian2.units import *

>>> x = 0.00123456 * volt

>>> x.in_best_unit()
'1.23456 mV'

>>> x.in_best_unit(3)
'1.235 mV'