Units

Model variables can declare their units using the syntax explained in Units. Internally, units are represented as Unit objects.

A large number of units can be accessed through myokit.units, this module is imported as part of the main myokit package:

>>> import myokit
>>> print myokit.units.m
[m]
>>> print myokit.units.mol / myokit.units.L
[M]
>>> print myokit.units.gallons / myokit.units.furlongs
[m^2 (2.25984749065e-07)]

A class myokit.Quantity is provided that can perform unit-safe arithmetic.

Quantifiers

Basic units (indicated by a shorthand such as m, s or mol are quantifiable. Standard SI quantifiers are used (with the exception of the quantifier Deca/da for 10^1, which is omitted).

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

Quantifiers can be used in mmt syntax to quantify the abbreviated unit names. For example the unit [ms] will be recognized as a millisecond. Full unit names are not quantifiable: [msecond] will not be recognized.

Unit class

class myokit.Unit(exponents=None, multiplier=0)

Defines a unit.

Each unit consists of

  • A list of seven integers: these are the exponents for the basic SI units: [g, m, s, A, K, cd, mol]. Gram is used instead of the SI defined kilogram to create a more coherent syntax.
  • A multiplier. This includes both quantifiers (such as milli, kilo, Mega etc) and conversion factors (for example 1inch = 2.54cm). Multipliers are specified in powers of 10.

There are two ways to create a unit:

>>> # 1. By explicitly setting the exponent and multiplier
>>> import myokit
>>> km_per_s = myokit.Unit([0, 1, -1, 0, 0, 0, 0], 3)
>>> print(km_per_s) # Here
[m/s (1000)]
>>> # 2. Creating a blank unit
>>> dimless = myokit.Unit()
>>> print(dimless)
[1]

Units can be manipulated using * and / and **. A clear representation can be obtained using str().

>>> s = myokit.Unit([0, 0, 1, 0, 0, 0, 0])
>>> km = myokit.Unit([0, 1, 0, 0, 0, 0, 0], 3)
>>> m_per_s = (km / 1000) / s
>>> print(m_per_s)
[m/s]

Units that require offsets (aka celsius and fahrenheit) are not supported.

static can_convert(unit1, unit2)

Returns true if the given units differ only by a multiplication. For example, [m/s] can be converted to [miles/hour] but not to [kg].

static convert(amount, unit1, unit2)

Converts a number amount in units unit1 to a new amount in units unit2.

>>> import myokit
>>> myokit.Unit.convert(3000, 'm', 'km')
3.0
exponents()

Returns the list of this unit’s exponents.

static list_exponents()

Returns a list of seven units, corresponding to the exponents used when defining a new Unit.

multiplier()

Returns this unit’s multiplier (as an ordinary number, not as its base 10 logarithm).

static parse_simple(name)

Converts a single unit name (+ optional quantifier) to a Unit object.

For example m and km will be accepted, while m/s or m^2 will not.

>>> from myokit import Unit
>>> print(Unit.parse_simple('km'))
[km]
>>> N = Unit.parse_simple('N')
>>> print(repr(N))
[g*m/s^2 (1000)]
>>> print(str(N))
[N]
>>> print(Unit.parse_simple(''))       # Dimensionless
[1]
>>> print(Unit.parse_simple('mm'))     # millimeters
[mm]
>>> print(Unit.parse_simple('mM'))     # milli-mole per liter
[mM]
static register(name, unit, quantifiable=False, output=False)

Registers a unit name with the Unit class. Registered units will be recognised by the parse() method.

Arguments:

name
The unit name. A variable will be created using this name.
unit
A valid unit object
quantifiable
True if this unit should be registered with the unit class as a quantifiable unit. Typically this should only be done for the unquantified symbol notation of SI or SI derived units. For example m, g, Hz, N but not meter, kg, hertz or forthnight.
output
True if this units name should be used to display this unit in. This should be set for all common units (m, kg, nm, Hz) but not for more obscure units (furlong, parsec). Having output set to False will cause one-way behaviour: Myokit will recognise the unit name but never use it in output. Setting this to True will also register the given name as a preferred representation format.
static register_preferred_representation(rep, unit)

Registers a preferred representation for the given unit without registering it as a new type. This method can be used to register common representations such as “umol/L” and “km/h”.

Arguments:

rep
A string, containing the preferred name for this unit. This should be something that Myokit can parse.
unit
The unit to register a notation for.

Existing entries are overwritten without warning.

Known units

A list of common units recognized by Myokit is given below. For each unit, the appropriate mmt syntax is given as well as the unit’s object’s name in the myokit.units module.

SI units
Kilogram [kg], [kilogram] kg, kilogram
Meter [m], [metre], [meter] m, metre, meter
Second [s], [second] s, second
Ampere [A], [ampere] A, ampere
Kelvin [K], [kelvin] K, kelvin
Candela [cd], [candela] cd, candela
Mole [mol], [mole]] mol, mole

The short form of the SI units is quantifiable in mmt syntax: [ms], [kmol], etc. The exception is [kg], which in Myokit is implemented as the quantified form of [g]: [mg], [kg] etc.

Dimensionless units
Dimensionless [1] dimensionless
Radian [rad] rad
  [radian] radian
Steradian [sr] sr
  [sterradian] sterradian
Derived SI units
Hertz [Hz], [hertz] Hz, hertz Frequency
Newton [N], [newton] N, newton Force
Pascal [Pa], [pascal] Pa, pascal Pressue
Joule [J], [joule] J, joule Energy
Watt [W], [watt] W, watt Power
Coulomb [C], [coulomb] C, coulomb Charge
Volt [V], [volt] V, volt Electrical potential
Farad [F], [farad] F, farad Electrical capacitance
Ohm [R], [ohm] R, ohm Electrical resistance
Siemens [S], [siemens] S, siemens Electrical conductance
Weber [Wb], [weber] Wb, weber Magnetic flux
Tesla [T], [tesla] T, tesla Magnetic flux density
Henry [H], [henry] H, henry Magnetic field strength
Lumen [lm], [lumen] lm, lumen Luminous flux
Lux [lx], [lux] lx, lux Illuminance
Bequerel [Bq], [bequerel] Bq, bequerel Radiocative decay
Gray [Gy], [gray] Gy, gray Absorbed ion. rad.
Sievert [Sv], [sievert] Sv, sievert Equivalent rad. dose
Katal [kat], [katal] kat, katal Catalytic activity

The short version of each dervied SI unit is quantifiable in mmt syntax, allowing constructs like [mS/uF].

In addition, Myokit recognises a host of other units such as [L] for liter, [M] for mole/liter (quantifiable), bar and atm, [minute] and [year] and even [parsec], [angstrom], [gallons] and [dog_year].

Unit arithmetic

class myokit.Quantity(value, unit=None)

Represents a quantity with a unit. Can be used to perform unit-safe arithmetic with Myokit.

Example:

>>> from myokit import Quantity as Q
>>> a = Q('10 [pA]')
>>> b = Q('5 [mV]')
>>> c = a / b
>>> print(c)
2 [uS]

>>> from myokit import Number as N
>>> d = myokit.Number(4)
>>> print(d.unit())
None
>>> e = myokit.Quantity(d)
>>> print(e.unit())
[1]

Arguments:

value
Either a numerical value (something that can be converted to float) or a string representation of a number in mmt syntax such as 4 or 2 [mV]. Quantities are immutable so no clone constructor is provided. If a myokit.Expression is provided its value and unit will be converted. In this case, the unit argument should be None. Myokit expressions with an undefined unit will be treated as dimensionless.
unit
An optional unit. Only used if the given value did not specify a unit. If no unit is given the quantity will be dimensionless.

Quantities support basic arithmetic, provided they have compatible units. Quantity arithmetic uses the following rules

  1. Quantities with any units can be multiplied or divided by each other
  2. Quantities with exactly equal units can be added and subtracted.
  3. Quantities with units that can be converted to each other (such as mV and V) can not be added or subtracted, as the output unit would be undefined.
  4. Quantities with the same value and exactly the same unit are equal.
  5. Quantities that would be equal after conversion are not seen as equal.

Examples:

>>> a = Q('10 [mV]')
>>> b = Q('0.01 [V]')
>>> print(a == b)
False
>>> print(a.convert('V') == b)
True
cast(unit)

Returns a new Quantity with this quantity’s value and a different, possibly incompatible, unit.

Example:

>>> from myokit import Quantity as Q
>>> a = Q('10 [A/F]')
>>> b = a.cast('uA/cm^2')
>>> print(str(b))
10.0 [uA/cm^2]
convert(unit)

Returns a copy of this Quantity, converted to another myokit.Unit.

unit()

Returns this Quantity’s unit.

value()

Returns this Quantity’s unitless value.