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

m, metre, meter 
Second 

s, second 
Ampere 

A, ampere 
Kelvin 

K, kelvin 
Candela 

cd, candela 
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 

dimensionless 
Radian 

rad 

radian 

Steradian 

sr 

sterradian 
Derived SI units 


Hertz 

Hz, hertz 
Frequency 
Newton 

N, newton 
Force 
Pascal 

Pa, pascal 
Pressue 
Joule 

J, joule 
Energy 
Watt 

W, watt 
Power 
Coulomb 

C, coulomb 
Charge 
Volt 

V, volt 
Electrical potential 
Farad 

F, farad 
Electrical capacitance 
Ohm 

R, ohm 
Electrical resistance 
Siemens 

S, siemens 
Electrical conductance 
Weber 

Wb, weber 
Magnetic flux 
Tesla 

T, tesla 
Magnetic flux density 
Henry 

H, henry 
Magnetic field strength 
Lumen 

lm, lumen 
Luminous flux 
Lux 

lx, lux 
Illuminance 
Bequerel 

Bq, bequerel 
Radiocative decay 
Gray 

Gy, gray 
Absorbed ion. rad. 
Sievert 

Sv, sievert 
Equivalent rad. dose 
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.