pulse2percept.units.base

Dimension, Unit, Quantity, DimensionMismatchError, as_value()

Module Attributes

DIMENSIONLESS	The dimension of a plain number
dimensionless	The unit of a plain number, used for image intensities and other dimensionless data
s	Second
ms	Millisecond
us	Microsecond
ns	Nanosecond
Hz	Hertz
kHz	Kilohertz
m	Meter
cm	Centimeter
mm	Millimeter
um	Micrometer (micron)
nm	Nanometer
A	Ampere
mA	Milliampere
uA	Microampere
nA	Nanoampere
V	Volt
mV	Millivolt
uV	Microvolt
W	Watt
mW	Milliwatt
uW	Microwatt
C	Coulomb
mC	Millicoulomb
uC	Microcoulomb
nC	Nanocoulomb
rad	Radian, the base scale of ordinary angle
deg	Degree of ordinary (geometric) angle.
dva	converting dva to a distance on the retina or cortex requires a visual field map, not a scale factor, so dva and deg are deliberately incompatible.
xTh	Multiple of perceptual threshold ("times threshold").

Functions

as_value(value, unit[, name])	Convert a value to a bare number expressed in unit
has_units(value)	Whether a value carries a physical unit

Classes

Dimension(**exponents)	Physical dimensionality of a unit or quantity.
Quantity(magnitude, unit)	A number (or array of numbers) with a unit
Unit(dimension, scale, symbol)	A physical unit.

Exceptions

DimensionMismatchError

Raised when quantities have incompatible physical dimensions.

exception pulse2percept.units.base.DimensionMismatchError

Raised when quantities have incompatible physical dimensions.

Added in version 0.10.0.

add_note(object, /)

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

with_traceback(object, /)

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

class pulse2percept.units.base.Dimension(**exponents)

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'

pulse2percept.units.base.DIMENSIONLESS = Dimension('dimensionless')

The dimension of a plain number

class pulse2percept.units.base.Unit(dimension, scale, symbol)

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'

class pulse2percept.units.base.Quantity(magnitude, unit)

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)

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)

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

pulse2percept.units.base.as_value(value, unit, name=None)

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

pulse2percept.units.base.has_units(value)

Whether a value carries a physical unit

True for a Quantity or Unit, and for a list or tuple containing one. Cheap enough to call before every attribute assignment, which is what Parametrized does.

pulse2percept.units.base.dimensionless = dimensionless

The unit of a plain number, used for image intensities and other dimensionless data

pulse2percept.units.base.s = s

Second

pulse2percept.units.base.ms = ms

Millisecond

pulse2percept.units.base.us = us

Microsecond

pulse2percept.units.base.ns = ns

Nanosecond

pulse2percept.units.base.Hz = Hz

Hertz

pulse2percept.units.base.kHz = kHz

Kilohertz

pulse2percept.units.base.m = m

Meter

pulse2percept.units.base.cm = cm

Centimeter

pulse2percept.units.base.mm = mm

Millimeter

pulse2percept.units.base.um = um

Micrometer (micron)

pulse2percept.units.base.nm = nm

Nanometer

pulse2percept.units.base.A = A

Ampere

pulse2percept.units.base.mA = mA

Milliampere

pulse2percept.units.base.uA = uA

Microampere

pulse2percept.units.base.nA = nA

Nanoampere

pulse2percept.units.base.V = V

Volt

pulse2percept.units.base.mV = mV

Millivolt

pulse2percept.units.base.uV = uV

Microvolt

pulse2percept.units.base.W = W

Watt

pulse2percept.units.base.mW = mW

Milliwatt

pulse2percept.units.base.uW = uW

Microwatt

pulse2percept.units.base.C = C

Coulomb

pulse2percept.units.base.mC = mC

Millicoulomb

pulse2percept.units.base.uC = uC

Microcoulomb

pulse2percept.units.base.nC = nC

Nanocoulomb

pulse2percept.units.base.rad = rad

Radian, the base scale of ordinary angle

pulse2percept.units.base.deg = deg

Degree of ordinary (geometric) angle. p2p’s angle-valued APIs are spelled in degrees, so this is the unit their bare numbers are read in.

pulse2percept.units.base.dva = dva

converting dva to a distance on the retina or cortex requires a visual field map, not a scale factor, so dva and deg are deliberately incompatible.

Type:

Degree of visual angle. Not an ordinary angle

pulse2percept.units.base.xTh = xTh

Multiple of perceptual threshold (“times threshold”). Becomes a current only once a threshold is known; see BiphasicPulseTrain.