# Quantity class

(Shortest import: `from brian2 import Quantity)`

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

  Bases: `ndarray`

  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)

    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)

    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)

    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)

    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'

## Tutorials and examples using this

- Example frompapers/Destexhe_et_al_1998

- Example frompapers/Platkiewicz_Brette_2011

- Example frompapers/Stimberg_et_al_2018/example_1_COBA