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 an 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 behavior: 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.