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 automatically when import myokit is run:

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

Represents a unit.

Most users won’t want to create units, but instead use e.g. myokit.parse_unit('kg/mV') or myokit.units.mV.

Each Unit consists of

  • A list of seven floats: 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, e.g. to create an inch use the multiplier log10(2.54).

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]. This method is an alias of close_exponent().

clarify()

Returns a string showing this unit’s representation using both the short syntax of str(unit), and the long syntax of repr(unit).

For example:

>>> from myokit import Unit
>>> print(str(myokit.units.katal))
[kat]
>>> print(repr(myokit.units.katal))
[mol/s]
>>> print(myokit.units.katal.clarify())
[kat] (or [mol/s])

If both representations are equal, the second part is omitted””

>>> print(myokit.units.m.clarify())
[m]
static close(unit1, unit2, reltol=1e-09, abstol=1e-09)

Checks whether the given units are close enough to be considered equal.

Note that this differs from unit1 is unit2 (which checks if they are the same object) and unit1 == unit2 (which will check if they are the same unit to machine precision).

The check for closeness is made with a relative tolerance of reltol and absolute tolerance of abstol, using:

abs(a - b) < max(reltol * max(abs(a), abs(b)), abstol)

Unit exponents are stored as floating point numbers and compared directly. Unit multipliers are stored as log10(multiplier), and compared without transforming back. As a result, units such as [nF]^2 won’t be considered close to [pF]^2, but units such as [F] will be considered close to [F] * (1 + 1e-12).

static close_exponent(unit1, unit2, reltol=1e-09, abstol=1e-09)

Returns True if the exponent of unit1 is close to that of unit2.

Exponents are stored internally as floating point numbers, and the check for closeness if made with a relative tolerance of reltol and absolute tolerance of abstol, using:

abs(a - b) < max(reltol * max(abs(a), abs(b)), abstol)
static conversion_factor(unit1, unit2, helpers=None)

Returns a myokit.Quantity c to convert from unit1 to unit2, such that 1 [unit1] * c = 1 [unit2].

For example:

>>> import myokit
>>> myokit.Unit.conversion_factor('m', 'km')
0.001 [1 (1000)]

Where:

1 [m] = 0.001 [km/m] * 1 [km]

so that c = 0.001 [km/m], and the unit [km/m] can be written as [km/m] = [ kilo ] = [1 (1000)].

Note that this method uses the close() and close_exponent() comparisons to see if units are equal.

Conversions between incompatible units can be performed if one or multiple helper Quantity objects are passed in. For example, to convert from g to mol a helper with units g/mol could be passed in. Conversion will be attempted with the helper and the inverse of the helper, and with any (dimensionless) scaling. For example, a g to mol conversion can also be facilitated by a helper in mol/g or mol/kg. If multiple helpers are given each will be tried individually: helpers are not combined. If used, a helper (possibly scaled and/or inverted) will be included in the returned conversion factor c.

A common example in cell electrophysiology is:

>>> import myokit
>>> myokit.Unit.conversion_factor(
...     'uA/cm^2', 'uA/uF', ['1 [uF/cm^2]'])
1.0 [cm^2/uF]

Where:

1 [uA/cm^2] = 1 [cm^2/uF] * 1 [uA/uF]

Arguments:

unit1
The new unit to convert from, given as a myokit.Unit or as a string that can be converted to a unit with myokit.parse_unit().
unit2
The new unit to convert to.
helpers=None
An optional list of conversion factors, which the method will attempt to use if the new and old units are incompatible. Each factor should be specified as a myokit.Quantity or something that can be converted to a Quantity e.g. a string 1 [uF/cm^2].

Returns a myokit.Quantity.

Raises a myokit.IncompatibleUnitError if the units cannot be converted.’

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 a list containing 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).

multiplier_log_10()

Returns the base 10 logarithm of this unit’s multiplier.

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.

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.

For people who don’t like units

myokit.strip_expression_units(model_text, skip_literals=True)

Takes the text of a valid model as input and returns a version stripped of any expression units. Variable units defined with in are preserved. Only the model part should be passed in, no script or protocol segments.

By default, constants defined for variables whose RHS is a single number will keep their units. To disable this, set skip_literals=False.

This method will raise a myokit.ParseError if the given code cannot be parsed to a valid model.