units¶

Manage units and units conversions.

Used for model and data unit conversions.

UnitsInformation ¶

UnitsInformation(
    udict, ureg=None, *args, unit_ids=None, **kwargs
)

Bases: MutableMapping

Storage of units information.

Used for models or datasets. The units information of a model also has the unit ids of the model, which quantity resolves.

Initialize UnitsInformation.

Behaves like a dict which allows to lookup units by id.

Parameters:

Name	Type	Description	Default
`udict`	`UdictType`	the unit of every identifier, an expression of pint.	required
`ureg`	`UnitRegistry \| None`	the unit registry of the expressions, the one of the package by default.	`None`
`*args`	`Any`	further units, as the arguments of a dict.	`()`
`unit_ids`	`Mapping[str, str] \| None`	the unit ids of the model and their expressions of pint, see `model_uid_dict`; none for the units of a dataset.	`None`
`**kwargs`	`str`	further units, as the arguments of a dict.	`{}`

Q_ `property` ¶

Q_

Get quantity for generating quantities.

copy ¶

copy()

Get a copy with its own dicts and the registry of the original.

resolve_unit ¶

resolve_unit(unit)

Get a unit with every unit id of the model replaced by its expression.

See replace_unit_ids, e.g. mg_per_min/kg is (mg/min)/kg and mg_per_min is mg/min for a model whose unit definition mg_per_min is a milligram per minute.

Parameters:

Name	Type	Description	Default
`unit`	`str`	a unit of pint and of the unit ids of the model.	required

Returns:

Type	Description
`str`	The unit in the units of pint.

quantity ¶

quantity(value, unit=None)

Create a quantity in a unit of pint and of the unit ids of the model.

Every identifier of a unit string which is a unit id of the model is its expression, see resolve_unit, so mg_per_min/kg is a unit as well as mg/min/kg; a unit id wins over a unit of pint of the same name, the model defines what its id means. A unit of pint, e.g. the units of a quantity, is taken as it is.

Parameters:

Name	Type	Description	Default
`value`	`Any`	the magnitude, a number or an array.	required
`unit`	`str \| PlainUnit \| None`	the unit, a string or a unit of pint, dimensionless without one.	`None`

Returns:

Type	Description
`Quantity`	The quantity of the registry of the units information.

Raises:

Type	Description
`UndefinedUnitError`	for a unit which is neither a unit of pint nor a unit id of the model.

from_sbml `staticmethod` ¶

from_sbml(sbml, ureg=None)

Get pint UnitsInformation for model.

model_uid_dict `staticmethod` ¶

model_uid_dict(model, ureg)

Get the expression of every unit id a model can use.

The expression is a unit pint parses: the id itself for a unit kind of SBML pint knows and for a unit definition whose id pint parses as the same unit, the expression of the unit definition (Units.udef_to_str) otherwise. The registry gets a definition only for a unit definition with a factor which is no prefix, e.g. the 133.322 of a mmHg, which pint cannot parse: _define defines it under its id, or under a collision free name when the registry has the id as another unit, and the definition holds for the whole process, also for sbmlsim.Q.

Parameters:

Name	Type	Description	Default
`model`	`Model`	the model.	required
`ureg`	`UnitRegistry`	the registry the expressions are checked with.	required

Returns:

Type	Description
`dict[str, str]`	unit id -> expression.

from_sbml_doc `staticmethod` ¶

from_sbml_doc(doc, ureg=None)

Get pint UnitsInformation for model in document.

The units information has the unit ids of the model, see model_uid_dict, which UnitsInformation.quantity resolves.

In SBML Level 1 and 2 an entity without units has the predefined unit of its kind, which a unit definition of the same id redefines: the time time, a species substance and a compartment volume, area or length by its spatial dimensions (none for zero dimensions); the concentration of a species is per the spatialSizeUnits of the species (Level 2 Version 1 and 2) or the units of its compartment. Level 3 has no predefined units, its entities have the units they set.

An entity without units, i.e. the time without time units, a species without the units of its substance or its compartment, or an entity whose derived unit is no unit definition of the model, is logged at the level DEBUG, and the model once at INFO with their number.

Raises:

Type	Description
`ValueError`	if the document has no model.

normalize_changes `staticmethod` ¶

normalize_changes(changes, uinfo)

Normalize the changes to the units of a model.

A quantity is converted into the unit of its target, a number is in the unit of its target and becomes a quantity of it.

Parameters:

Name	Type	Description	Default
`changes`	`dict[str, Quantity \| float]`	target -> value, a quantity or a number.	required
`uinfo`	`UnitsInformation`	the units of the model.	required

Returns:

Type	Description
`dict[str, Quantity \| float]`	target -> the value as a quantity in the unit of the target.

Raises:

Type	Description
`ValueError`	if a target has no unit in the model, i.e. is no entity of it, or a quantity cannot be converted into the unit of its target.

Units ¶

Units class.

Container for unit related functionality. Allows to read the unit information from SBML models and provides helpers for the unit conversion.

udef_to_str `classmethod` ¶

udef_to_str(udef)

Format SBML unitDefinition as string.

Units have the general format (multiplier * 10^scale *ukind)^exponent (m * 10^s *k)^e

The string is a unit pint parses, with the prefixes and names of pint where there are some, e.g. mmol/min for a millimole per minute.

Returns the string "None" in case no UnitDefinition was provided.

quotient `staticmethod` ¶

quotient(numerator, denominator)

Get the quotient of two unit expressions, with the brackets it needs.

Parameters:

Name	Type	Description	Default
`numerator`	`str`	expression of the numerator, e.g. `mmol`.	required
`denominator`	`str`	expression of the denominator, e.g. `l` or `m^3`.	required

Returns:

Type	Description
`str`	The expression of the quotient, e.g. `mmol/l`. An empty expression
`str`	is dimensionless: `item` over a dimensionless volume is `item`,
`str`	not `item/`, which pint does not read.

cache_folder ¶

cache_folder()

Get the directory of the cache of the parsed definitions of pint.

Returns:

Type	Description
`Path \| None`	`SBMLSIM_UNITS_CACHE` if it is set (`None` for an empty value), else
`Path \| None`	`sbmlsim/units` in the user cache, i.e. in `XDG_CACHE_HOME` or `~/.cache`.
`Path \| None`	The directory below it is named by the version of pint and of python and
`Path \| None`	`CACHE_FORMAT`; pint keys every entry by the content of the file it parsed.

setup_matplotlib ¶

setup_matplotlib()

Let matplotlib plot the quantities of the package with their units.

A quantity of a result, ScanResult.q, or of Q is plotted in the unit of the first quantity of an axis, every other one is converted into it, and the axis is labelled with the unit, which sbmlsim.plot.label_axes puts next to a name. ScanResult.q and sbmlsim.plot call it, so it is rarely called directly. It imports matplotlib, which the simulations do not need, and is called once.

international_unit_note ¶

international_unit_note(err)

Get the note how to define an international unit for an error of one.

Parameters:

Name	Type	Description	Default
`err`	`Exception`	the error of reading a unit.	required

Returns:

Type	Description
`str \| None`	The note for an `UndefinedUnitError` of a name which is `IU`, ends in
`str \| None`	`IU` (`µIU`, `mIU`) or starts with `IU_` (`IU_per_ml`), else `None`.

define_unit ¶

define_unit(definition, ureg=None)

Define a unit in a registry once, e.g. the international unit of a substance.

The registry of the package ignores a redefinition, so a second model which defined a name with another value would silently get the first one. A name which is defined already must therefore have the same value (compared in base units); a name of the model and the substance, e.g. IU_ramipril_renin, keeps the models apart.

Parameters:

Name	Type	Description	Default
`definition`	`str`	`"<name> = <expression>"` in the syntax of pint, e.g. `"IU_ramipril_renin = 0.6 * microgram"` or `"IU_apixaban_antixa = count"`.	required
`ureg`	`UnitRegistry \| None`	the unit registry, the one of the package by default, `sbmlsim.units.ureg`; only a registry of your own is passed.	`None`

Returns:

Type	Description
`str`	The name of the unit.

Raises:

Type	Description
`ValueError`	if the definition is not `<name> = <expression>` with an identifier as the name, pint cannot evaluate the expression (e.g. an unknown unit in it, pint's `UndefinedUnitError`) or the name is defined with another value.

unit_identifiers ¶

unit_identifiers(unit)

Get the identifiers of a unit string in their order.

An identifier is a whole word of the string: mg is no identifier of mg_per_min/kg, and the e of the number 1e-3 none of 1e-3*mg.

Parameters:

Name	Type	Description	Default
`unit`	`str`	the unit string.	required

Returns:

Type	Description
`list[str]`	The identifiers, e.g. `["mg_per_min", "kg"]` of `mg_per_min/kg`.

replace_unit_ids ¶

replace_unit_ids(unit, unit_ids)

Replace every identifier of a unit string which is a unit id by its expression.

The expression is put in brackets, so a power or a quotient applies to all of it: mg_per_min^2/kg with mg_per_min = mg/min is (mg/min)^2/kg; an expression which is a single name and a unit which is one unit id are not put in brackets, mg_per_min is mg/min, mg_per_min is mg/min. Only whole identifiers are replaced, see unit_identifiers, and only once: the expression of a unit id is a unit of pint, whose names are not replaced again. A unit id wins over a unit of pint of the same name.

Parameters:

Name	Type	Description	Default
`unit`	`str`	the unit string.	required
`unit_ids`	`Mapping[str, str]`	unit id -> expression of pint.	required

Returns:

Type	Description
`str`	The unit string with the expressions of its unit ids.

unit_signature ¶

unit_signature(udef)

Get the base units of a unit definition with their exponents and its factor.

The units of one kind are merged, their exponents summed (a kind whose exponents cancel is left out), and the multipliers and scales of all units are one factor, prod((multiplier * 10**scale) ** exponent). Two unit definitions with the same signature are the same unit.

It replaces libsbml.UnitDefinition.areIdentical, which keeps memory on every call for a unit with a multiplier other than 1 (libsbml 5.21.2, sbmlteam/libsbml#503): about 13 MB per model when the derived units of a model are matched with its unit definitions. Unlike areIdentical the same factor written as a multiplier or as a scale is the same unit.

Parameters:

Name	Type	Description	Default
`udef`	`UnitDefinition`	the unit definition.	required

Returns:

Type	Description
`UnitSignature`	The kinds with their exponents, sorted by kind, and the factor.

short_unit ¶

short_unit(unit)

Get a unit in the short form of pint, e.g. ng/ml for nanogram / milliliter.

A result keeps its units in the long form of pint; the labels of plots and of probability statements show the short form.

Parameters:

Name	Type	Description	Default
`unit`	`str \| None`	the unit as a result keeps it.	required

Returns:

Type	Description
`str`	The short form, empty for no unit and for a dimensionless one, and the
`str`	unit as given if pint does not parse it as a unit, e.g. one with a
`str`	factor or a unit of a model only.

unit_label ¶

unit_label(name, unit)

Get the label of a quantity, with [unit] in its short form only for a unit.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the quantity.	required
`unit`	`str \| None`	its unit, see `short_unit`.	required

Returns:

Type	Description
`str`	The label, e.g. `cp [ng/ml]`, or the name without a unit.

units¶

UnitsInformation ¶

Q_ property ¶

copy ¶

resolve_unit ¶

quantity ¶

from_sbml staticmethod ¶

model_uid_dict staticmethod ¶

from_sbml_doc staticmethod ¶

normalize_changes staticmethod ¶

Units ¶

udef_to_str classmethod ¶

quotient staticmethod ¶

cache_folder ¶

setup_matplotlib ¶

international_unit_note ¶

define_unit ¶

unit_identifiers ¶

replace_unit_ids ¶

unit_signature ¶

short_unit ¶

unit_label ¶

Q_ `property` ¶

from_sbml `staticmethod` ¶

model_uid_dict `staticmethod` ¶

from_sbml_doc `staticmethod` ¶

normalize_changes `staticmethod` ¶

udef_to_str `classmethod` ¶

quotient `staticmethod` ¶