brainunit.UNITLESS

Contents

brainunit.UNITLESS#

brainunit.UNITLESS = Unit("1")#

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 the named units it was composed from, to generate a readable string representation. See below.

Parameters:
  • dim (Dimension, optional) – The physical dimensions of the unit. Defaults to DIMENSIONLESS.

  • scale (array_like, optional) – The scale exponent, e.g. 3 for a “k” (kilo) prefix. Defaults to 0.

  • base (array_like, optional) – The base of the exponent. Must be 10 (the only supported base); other values raise ValueError.

  • factor (array_like, optional) – The conversion factor of the unit. Must be positive. Defaults to 1.

  • name (str, optional) – The full name of the unit, e.g. 'volt'.

  • dispname (str, optional) – The display name, e.g. 'V'.

  • is_fullname (bool, optional) – Whether name is the canonical full name. Defaults to True.

  • display_parts (list of tuple, optional) – Legacy (name, dispname, exponent) display components, accepted for backward compatibility (old pickles).

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

Display

A unit keeps the named units it was composed from, so composites display the way they were written: u.mS * u.nA / u.cm ** 2 is mS * nA / cm^2 and u.mV * u.ms is ms * mV. Terms are ordered canonically (numerator first, then by symbol), so a * b and b * a display identically. A composite collapses automatically only onto a curated set of units (SI base units, N, Pa, J, W, C, V, F, ohm, S, Hz and their prefixed forms):

>>> import saiunit as u
>>> u.kilogram * u.metre / u.second ** 2
Unit("N")
>>> u.volt * u.second
Unit("s * V")
>>> (u.volt * u.second).simplify()
Unit("Wb")

str(unit) is canonical ASCII that parse_unit() reads back; to_string() also renders Unicode (µF / cm²) and LaTeX.

Defining your own

>>> import saiunit as u
>>> cal = u.Unit.create(u.joule.dim, 'calorie', 'cal', factor=4.184)
>>> cal / u.gram
Unit("cal / g")

Comparison and arithmetic treat a bare Unit operand differently. Comparing a Quantity against a bare Unit implicitly reads the unit as “one of that unit” (1 * unit), so Quantity(1, mV) == mV is True. Addition/subtraction, by contrast, reject a bare Unit operand outright (Quantity(1, mV) + mV raises TypeError), since there is no natural mantissa to add. Both behaviours are intentional; see __eq__ for the comparison side.

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")