pulse2percept.units

Physical units used by pulse2percept.

Bare numbers retain their documented units. Unitful values are checked for dimensional compatibility and converted at API boundaries.

base

Dimension, Unit, Quantity, DimensionMismatchError, as_value()

pulse2percept.units.as_value(value, unit, name=None)[source]

Convert a value to a bare number expressed in unit

This is p2p’s standard Python-to-numerics boundary. A Quantity is dimension-checked and rescaled to unit; a bare number is assumed to already be expressed in unit and is passed through untouched (including None).

Parameters:

value (float, array_like, Quantity, or None) – The value to normalize.
unit (Unit) – The unit the numerical code expects.
name (str, optional) – Name of the parameter, used to make the error message point at the offending argument.

Returns:

value – The bare numerical value, expressed in unit.

Return type:

float, np.ndarray, or None

Examples

>>> from pulse2percept.units import as_value, ms, s
>>> as_value(20, ms)
20
>>> as_value(0.02 * s, ms)
20.0

class pulse2percept.units.Dimension(**exponents)[source]

Physical dimensionality of a unit or quantity.

Dimensions are immutable vectors of integer exponents over BASE_DIMENSIONS.

Added in version 0.10.0.

Parameters:: **exponents (int) – Exponents of the primitive dimensions. Omitted dimensions have exponent zero.

Examples

>>> from pulse2percept.units import Dimension
>>> Dimension(current=1) * Dimension(time=1)
Dimension('charge')

property exponents: Tuple of exponents, aligned with BASE_DIMENSIONS

property is_dimensionless: Whether all exponents are zero

property name: Human-readable name, e.g. 'electric current'

exception pulse2percept.units.DimensionMismatchError[source]

Raised when quantities have incompatible physical dimensions.

Added in version 0.10.0.

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pulse2percept.units.Quantity(magnitude, unit)[source]

A number (or array of numbers) with a unit

Quantities are what users build by multiplying a number by a unit, and they exist to be checked and converted at p2p’s public API boundaries. They are deliberately not NumPy arrays: p2p strips units before any numerical work, so quantities never reach a Cython kernel and never impose per-element overhead on a simulation.

For the same reason, np.asarray(5 * uA) does not silently yield 5. Removing a unit is something you write down, using to_value().

Equivalent unit choices convert consistently up to floating-point precision, and quantities compare accordingly: 0.0041 * mA == 4.1 * uA is True even though rescaling the former gives 4.1000000000000005.

Added in version 0.10.0.

Parameters:

magnitude (float or array_like) – The numerical value(s), expressed in unit.
unit (Unit) – The unit of magnitude.

Examples

>>> from pulse2percept.units import uA, mA
>>> 500 * uA == 0.5 * mA
True
>>> (500 * uA).to(mA)
0.5 mA
>>> (500 * uA).to_value(mA)
0.5

property magnitude: The numerical value(s), expressed in self.unit

property unit: The Unit of this quantity

property dimension: The Dimension of this quantity

to(unit, name=None)[source]

Convert to another unit of the same dimension

Parameters:

unit (Unit) – The target unit.
name (str, optional) – Name of the parameter being converted, used to make the error message point at the offending argument.

Returns:

quantity – The same physical quantity expressed in unit.

Return type:

Quantity

to_value(unit, name=None)[source]

Convert to another unit and return the bare number(s)

This is the explicit way to remove a unit: after calling it you have an ordinary float or NumPy array, expressed in unit.

Parameters:

unit (Unit) – The target unit.
name (str, optional) – Name of the parameter being converted, used to make the error message point at the offending argument.

Returns:

value – The magnitude of this quantity expressed in unit.

Return type:

float or np.ndarray

class pulse2percept.units.Unit(dimension, scale, symbol)[source]

A physical unit.

A unit combines a Dimension, a scale relative to its base unit, and a display symbol. Multiplying a value by a unit produces a Quantity; units may also be multiplied, divided, and raised to integer powers.

Units are immutable.

Added in version 0.10.0.

Parameters:

dimension (Dimension) – Physical dimension.
scale (float) – Scale relative to the base unit of that dimension.
symbol (str) – Display symbol, e.g. 'uA'.

property dimension: The Dimension of this unit

property scale: Size of this unit relative to the base unit of its dimension

property symbol: Short symbol this unit was built with, e.g. 'uA*ms'