units¶
Manage units and units conversions.
Used for model and data unit conversions.
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
|
the unit registry of the expressions. |
required |
*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 |
None
|
**kwargs
|
str
|
further units, as the arguments of a dict. |
{}
|
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. |
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. |
staticmethod
¶
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. |
staticmethod
¶
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.
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. |
staticmethod
¶
Normalize all changes to units in given units dictionary.
This is a major helper function allowing to convert changes to the requested units.
Units class.
Container for unit related functionality. Allows to read the unit information from SBML models and provides helpers for the unit conversion.
classmethod
¶
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.
staticmethod
¶
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. |
required |
denominator
|
str
|
expression of the denominator, e.g. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The expression of the quotient, e.g. |
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 |
str | None
|
|
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. |
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; a unit which is one unit id is its expression,
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. |