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.25984749065e07)]
A class myokit.Quantity
is provided that can perform unitsafe
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')
ormyokit.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 ofclose_exponent()
.

clarify
()¶ Returns a string showing this unit’s representation using both the short syntax of
str(unit)
, and the long syntax ofrepr(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=1e09, abstol=1e09)¶ 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) andunit1 == 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 ofabstol
, 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 + 1e12)
.

static
close_exponent
(unit1, unit2, reltol=1e09, abstol=1e09)¶ Returns
True
if the exponent ofunit1
is close to that ofunit2
.Exponents are stored internally as floating point numbers, and the check for closeness if made with a relative tolerance of
reltol
and absolute tolerance ofabstol
, 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 fromunit1
tounit2
, such that1 [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()
andclose_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 fromg
tomol
a helper with unitsg/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, ag
tomol
conversion can also be facilitated by a helper inmol/g
ormol/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 factorc
.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 withmyokit.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 string1 [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 unitsunit1
to a new amount in unitsunit2
.>>> 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
andkm
will be accepted, whilem/s
orm^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')) # millimole 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). Havingoutput
set toFalse
will cause oneway behaviour: Myokit will recognise the unit name but never use it in output. Setting this toTrue
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.
 A list of seven floats: these are the exponents for the basic SI
units:
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 unitsafe 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 inmmt
syntax such as4
or2 [mV]
. Quantities are immutable so no clone constructor is provided. If amyokit.Expression
is provided its value and unit will be converted. In this case, the unit argument should beNone
. 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
 Quantities with any units can be multiplied or divided by each other
 Quantities with exactly equal units can be added and subtracted.
 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.
 Quantities with the same value and exactly the same unit are equal.
 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 anothermyokit.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.