Unit

Unit#

class saiunit.Unit(dim=None, scale=0, base=10.0, factor=1.0, name=None, dispname=None, is_fullname=True, display_parts=None)#

A physical unit.

Basically, a unit is just a number with given dimensions, e.g. mvolt = 0.001 with the dimensions of voltage. The units module defines a large number of standard units, and you can also define your own (see below).

Mathematically, a unit represents:

\[\text{{factor}} \times \text{{base}}^{\text{{scale}}} \times \text{{dimension}}\]

where the factor is the conversion factor of the unit (e.g. 1 calorie = 4.18400 Joule, so the factor is 4.18400), the base is the base of the exponent (e.g. 10 for the kilo prefix), the scale is the exponent of the base (e.g. 3 for the kilo prefix), and the dimension is the physical dimensions of the unit (e.g. joule for energy).

The unit class also keeps track of various things that were used to define it so as to generate a nice string representation of it. See below.

Parameters:

dim (saiunit.Dimension | str) – The physical dimensions of the unit. Defaults to DIMENSIONLESS.
scale (Array | ndarray | bool | number | bool | int | float | complex) – The scale exponent, e.g. 3 for a “k” (kilo) prefix. Defaults to 0.
base (Array | ndarray | bool | number | bool | int | float | complex) – The base of the exponent, e.g. 10 for SI prefixes. Defaults to 10.
factor (Array | ndarray | bool | number | bool | int | float | complex) – The conversion factor of the unit. Defaults to 1.
name (str) – The full name of the unit, e.g. 'volt'.
dispname (str) – The display name, e.g. 'V'.
is_fullname (bool) – Whether name is the canonical full name. Defaults to True.
display_parts (list of tuple, optional) – Canonical display components for compound units.

Notes

When creating scaled units, you can use the following prefixes:

Factor	Name	Prefix
10^24	yotta	Y
10^21	zetta	Z
10^18	exa	E
10^15	peta	P
10^12	tera	T
10^9	giga	G
10^6	mega	M
10^3	kilo	k
10^2	hecto	h
10^1	deka	da
1
10^-1	deci	d
10^-2	centi	c
10^-3	milli	m
10^-6	micro	u (mu in SI)
10^-9	nano	n
10^-12	pico	p
10^-15	femto	f
10^-18	atto	a
10^-21	zepto	z
10^-24	yocto	y

Defining your own

It can be useful to define your own units for printing purposes. So for example, to define the newton metre, you write:

>>> import saiunit as u
>>> Nm = u.newton * u.metre

You can then do:

>>> (1 * Nm).in_unit(Nm)
'1. N m'

New “compound units”, i.e. units that are composed of other units will be automatically registered and from then on used for display. For example, imagine you define total conductance for a membrane, and the total area of that membrane:

>>> import saiunit as u
>>> conductance = 10. * u.nS
>>> area = 20000 * u.um ** 2

If you now ask for the conductance density, you will get an “ugly” display in basic SI dimensions, as saiunit does not know of a corresponding unit:

>>> conductance / area
0.5 * metre ** -4 * kilogram ** -1 * second ** 3 * amp ** 2

By using an appropriate unit once, it will be registered and from then on used for display when appropriate:

>>> u.usiemens / u.cm ** 2
usiemens / (cmetre ** 2)
>>> conductance / area  # same as before, but now knows about uS/cm^2
50. * usiemens / (cmetre ** 2)

Note that user-defined units cannot override the standard units (volt, second, etc.) that are predefined. For example, the unit Nm has the dimensions “length^2 * mass / time^2”, and therefore the same dimensions as the standard unit joule. The latter will be used for display purposes:

>>> 3 * u.joule
3. * joule
>>> 3 * Nm
3. * joule

Examples

Create a simple unit:

>>> import saiunit as u
>>> u.volt
Unit("V")
>>> u.mvolt
Unit("mV")

Combine units:

>>> import saiunit as u
>>> u.volt / u.amp
Unit("V / A")

property base: float#

Return the base of the unit’s scale exponent.

The base is the number that is raised to the scale power to produce the unit’s magnitude. For SI-prefixed units this is 10 (e.g. kilo means 10 ** 3).

Returns:: The base of the exponent.
Return type:: float

Examples

>>> import saiunit as u
>>> u.kvolt.base
10.0

copy()[source]#

Return a copy of this Unit.

Returns:: A new Unit object with the same attributes.
Return type:: Unit

Examples

>>> import saiunit as u
>>> u = u.volt.copy()
>>> u == u.volt
True
>>> u is u.volt
False

static create(dim, name, dispname, scale=0, base=10.0, factor=1.0)[source]#

Create a new named unit.

Parameters:

dim (Dimension) – The dimensions of the unit.
name (str) – The full name of the unit, e.g. 'volt'
dispname (str) – The display name, e.g. 'V'
scale (int) – The scale of this unit as an exponent of 10, e.g. -3 for a unit that is 1/1000 of the base scale. Defaults to 0 (i.e. a base unit).
base (float) – The base for this unit (as the base of the exponent), i.e. a base of 10 means 10^3, for a “k” prefix. Defaults to 10.
factor (float) – The factor for this unit (as the conversion factor), e.g. a factor of 1 cal = 4.18400 J, where 4.18400 is the factor. Defaults to 1.

Returns:

u – The new unit.

Return type:

Unit

Examples

>>> import saiunit as u
>>> from saiunit import Dimension
>>> energy_dim = u.joule.dim
>>> cal = u.Unit.create(energy_dim, 'calorie', 'cal', factor=4.184)
>>> cal
Unit("cal")

static create_scaled_unit(baseunit, scalefactor)[source]#

Create a scaled unit from a base unit.

Parameters:

baseunit (Unit) – The unit of which to create a scaled version, e.g. volt, amp.
scalefactor (str) – The scaling factor, e.g. "m" for mvolt, mamp

Returns:

u – The new unit.

Return type:

Unit

Examples

>>> import saiunit as u
>>> uvolt = u.Unit.create_scaled_unit(u.volt, 'u')
>>> uvolt.name
'uvolt'
>>> uvolt.scale
-6

property dim: Dimension#

Return the physical unit dimensions of this unit.

Returns:: The Dimension instance describing the physical dimensions (e.g. length, mass, time, …).
Return type:: Dimension

Examples

>>> import saiunit as u
>>> u.volt.dim
metre ** 2 * kilogram * second ** -3 * amp ** -1

property dispname#

Return the display name of the unit.

The display name is the short symbol used when rendering the unit in string output (e.g. 'V' for volt, 'mV' for millivolt).

Returns:: The display name of the unit.
Return type:: str or None

Examples

>>> import saiunit as u
>>> u.volt.dispname
'V'
>>> u.mvolt.dispname
'mV'

property factor: float#

Return the conversion factor of the unit.

The factor represents a multiplicative constant that converts a quantity expressed in this unit to its base-unit equivalent. For example, 1 calorie = 4.184 joule, so calorie.factor == 4.184.

Returns:: The conversion factor.
Return type:: float

Examples

>>> import saiunit as u
>>> u.volt.factor
1.0

factorless()[source]#

Return a copy of this Unit with the factor set to 1.

Returns:: A new Unit object with the factor set to 1.
Return type:: Unit

Examples

>>> import saiunit as u
>>> u = u.Unit.create(u.Dimension(kg=1), 'pound', 'lb', factor=0.453592)
>>> u.factor
0.453592
>>> u.factorless().factor
1.0

has_same_base(other)[source]#

Whether this Unit has the same base as another Unit.

Parameters:: other (Unit) – The other Unit to compare with.
Returns:: Whether the two Units have the same base.
Return type:: bool

Examples

>>> import saiunit as u
>>> u.volt.has_same_base(u.amp)
True
>>> u.volt.has_same_base(u.mvolt)
True

has_same_dim(other)[source]#

Whether this Unit has the same unit dimensions as another Unit.

Parameters:: other (Unit) – The other Unit to compare with.
Returns:: Whether the two Units have the same unit dimensions.
Return type:: bool

Examples

>>> import saiunit as u
>>> u.volt.has_same_dim(u.mvolt)
True
>>> u.volt.has_same_dim(u.amp)
False

has_same_magnitude(other)[source]#

Whether this Unit has the same magnitude as another Unit.

Two units have the same magnitude when they share the same scale, base, and factor.

Parameters:: other (Unit) – The other Unit to compare with.
Returns:: Whether the two Units have the same magnitude.
Return type:: bool

Examples

>>> import saiunit as u
>>> u.mvolt.has_same_magnitude(u.mamp)
True
>>> u.mvolt.has_same_magnitude(u.volt)
False

property is_unitless: bool#

Whether the unit is dimensionless with no scaling.

A unit is considered unitless when its dimension is dimensionless, its scale exponent is 0, and its factor is 1.0.

Returns:: True if the unit is unitless, False otherwise.
Return type:: bool

Examples

>>> import saiunit as u
>>> u.UNITLESS.is_unitless
True
>>> u.volt.is_unitless
False

property magnitude: float#

Return the absolute magnitude of the unit.

The magnitude is computed as factor * base ** scale and represents the overall multiplicative factor that converts a value in this unit to the corresponding base-unit value.

Returns:: The absolute magnitude of the unit.
Return type:: float

Examples

>>> import saiunit as u
>>> u.mvolt.magnitude
0.001
>>> u.kvolt.magnitude
1000.0

property name#

Return the full name of the unit.

Returns:: The full name of the unit (e.g. 'volt', 'mvolt'), or None if no name was assigned.
Return type:: str or None

Examples

>>> import saiunit as u
>>> u.volt.name
'volt'
>>> u.mvolt.name
'mvolt'

reverse()[source]#

Return the multiplicative inverse of this unit.

Computes 1 / self, producing a new unit with negated scale, inverted factor, and reciprocal dimensions.

Returns:: A new Unit representing the reciprocal of this unit.
Return type:: Unit

Examples

>>> import saiunit as u
>>> u.second.reverse()
Unit("Hz")
>>> u.metre.reverse()
Unit("1 / m")

property scale: float | int#

Return the scale exponent of the unit.

The scale is the integer exponent applied to base to produce the unit’s magnitude relative to the base unit. For example, mvolt has scale == -3 (i.e. 10 ** -3).

Returns:: The scale exponent.
Return type:: float or int

Examples

>>> import saiunit as u
>>> u.mvolt.scale
-3

property should_display_unit: bool#

Whether the unit should be shown in formatted output.

Returns True for all non-unitless units, and also for dimensionless units that carry a meaningful registered name (e.g. radian, steradian).

Returns:: True if the unit should be displayed, False otherwise.
Return type:: bool

Examples

>>> import saiunit as u
>>> u.volt.should_display_unit
True
>>> u.UNITLESS.should_display_unit
False

Unit

Contents

Unit#