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
C	Coulomb
mC	Millicoulomb
uC	Microcoulomb
nC	Nanocoulomb
dva	converting dva to a distance on the retina or cortex requires a visual field map, not a scale factor.

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 unit of measurement

Exceptions

DimensionMismatchError

Raised when quantities of incompatible dimensions are combined

exception pulse2percept.units.base.DimensionMismatchError

Raised when quantities of incompatible dimensions are combined

Subclasses TypeError because a dimension mismatch is a type error in the physical sense: microamps are simply not a kind of millisecond.

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.base.Dimension(**exponents)

Physical dimensionality of a unit or quantity

A dimension is a vector of integer exponents over the primitive dimensions in BASE_DIMENSIONS. Dimensions are immutable, hashable, and support multiplication, division, and integer powers.

Added in version 0.10.0.

Parameters:

**exponents (int) – Exponent for each primitive dimension, e.g. Dimension(current=1, length=-2) for a current density. Omitted dimensions have exponent 0.

Examples

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

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 unit of measurement

A unit is a dimension plus a scale factor relative to the base unit of that dimension (seconds, meters, amperes, volts, or degrees of visual angle) plus a symbol used for display.

Multiplying a number, list, or NumPy array by a unit produces a Quantity. Multiplying, dividing, or exponentiating units produces another unit, so derived units such as uA / mm ** 2 need not be predefined.

Units are immutable. p2p does not maintain a unit registry, parse unit strings, or generate SI prefixes automatically: the vocabulary exported by pulse2percept.units is the whole of it.

Added in version 0.10.0.

Parameters:

• dimension (Dimension) – The dimensionality of the unit.

• scale (float) – Size of the unit relative to the base unit of its dimension. For example, ms has scale=1e-3 because the base unit of time is the second.

• symbol (str) – Short symbol used when printing quantities, e.g. 'uA'.

Examples

>>> from pulse2percept.units import uA, mm, ms
>>> uA / mm ** 2
uA/mm^2
>>> 50 * uA
50 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 used for display

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.C = C

Coulomb

pulse2percept.units.base.mC = mC

Millicoulomb

pulse2percept.units.base.uC = uC

Microcoulomb

pulse2percept.units.base.nC = nC

Nanocoulomb

pulse2percept.units.base.dva = dva

converting dva to a distance on the retina or cortex requires a visual field map, not a scale factor.

Type:

Degree of visual angle. Not an ordinary angle