Units

class strengths.UnitsSystem(space='µm', time='s', quantity='molecule')

descibes a system of fundamental units, one for time (h, min, s, etc.), one for space (m, mm, µm, etc.) and one for quantity (moleclue, mol, etc.).

Parameters:

• space (str) – space distance units

• time (str) – time distance units

• quantity (str) – units of quantity of matter

class strengths.UnitsDimensions(space=0, time=0, quantity=0)

descibes the dimensions associated with a system of units.

Parameters:

• space (str) – space distance exponent

• time (str) – time distance exponent

• quantity (str) – exponent of quantity of matter

class strengths.Units(sys, dim=None)

describe the units of a variable. there is two ways to initialize a Units object :

1. by specifying both sys and dim, respecitvely with UnitsSystem and UnitsDimensions objects, or dicts that can be converted to

   such objects. ie.

   Units(UnitSystem(space="m"), UnitsDimensions(space=1))         # OK, "m"
   Units({"space":"m", "time":"s", "quantity":"molecule"},
             {"space":1, "time":0, "quantity":0 })                # OK, "m"
   Units(sys=UnitSystem(space="m"), dim=UnitsDimensions(space=1)) # OK, "m"
   Units(sys={"space":"m", "time":"s", "quantity":"molecule"},
             dim={"space":1, "time":0, "quantity":0 })            # OK, "m"
   Units(1, 2)                                                    # error, 1 and 2 cannot be converted to
                                                                  # UnitsSystem and UnitsValues objects
   Units("1 s", UnitsDimensions(time=1))                          # error, dim is not None, and "1 s" cannot
   

2. by specifying only sys or setting dim to None. sys must then be a characted string that can be parsed by parse_units.

   ie.

   Units("1 m")                     # OK, "m"
   Units("1 m", None)               # OK, "m"
   Units(sys="1 m")                 # OK, "m"
   Units(sys="1 m", dim=None)       # OK, "m"
   
   Units(1)                         # error, as dim=None, sys must be a string.
   Units(sys=UnitSystem(space="m")) # error, same reason as above
   

Parameters:

• sys (str, UnitSystem or dict) – string representation of the units if dim is None/unspecified, UnitsSystem or equivalent dictonnary otherwise

• dim (None, UnitsDimensions or dict) – None or UnitsDimensions or equivalent dictionnary

copy()

Returns a deepcopy of the instance.

instance.copy()

# is equivalent to
# import copy

copy.deepcopy(instance)

property dim

dimensions associated with time, space, etc.

invert()

return inverted units. ie. µm2/s -> s/µm-2

multiply(u)

return the product of the instance units by the Units u. ie. m2/s * m-1 -> m/s

raiseto(e)

return the product of the instance units raise to the power of e. e doesnt have to be an integer, but dimensions raised to the power of e have to. ie. (m/s)^3 = m3/s3

property sys

units associated with space, time, etc.

class strengths.UnitValue(value, units=None, convert=True)

Describes a physical value with its units. there is two ways to initialize a UnitValue :

1. by specifying separately its numerical value and its units :

   value must then be a number, and units a Units obect or a string that can be parsed as such : ie.

   UnitValue(1, "m")                           # ok, 1 m
   UnitValue(1, Units("m"))                    # ok, 1 m
   UnitValue(1, Units(UnitsSystem(space="m"),
                UnitsDimensions(space=1)))     # ok, 1 m
   
   UnitValue("1", "m"))                        # error : "1" is not a number
   UnitValue(1, []))                           # error : [] is not a Units obect nor a string
   

2. by specifying only value or setting units to None. value must then be a string that can be parsed to

   a UnitValue by parse_unitvalue : ie.

   UnitValue("1 m")         # ok, 1 m
   UnitValue("1 m", None)   # ok, 1 m
   UnitValue(1)             # wrong, 1 is not a string
   UnitValue("a")           # wrong, "a" cannot be parsed into a UnitValue.
   

Parameters:

• value (number or str) – if units are defined (not None), the numerical value of the UnitValue, otherwise, a string that can be parsed as a UnitValue.

• units (Units, str or None) – units of the variable or None (default : None)

• convert (bool) – tells is the value, if it is already a UnitValue (or a string representing one), should be converted to the specified units (default : True)

__abs__()

defines abs(self). simply returns UnitValue(abs(self.value), self.units). ie.

abs(UnitValue("-2 µm")) # ok, == UnitValue("2 µm")
abs(UnitValue("2 µm"))  # ok, == UnitValue("2 µm")

__add__(v)

defines self+v. Addition must be operated betwen UnitValue/UnitArray objects with the same units dimension. if v is not a UnitValue/UnitArray, is is conseidered to be in the same units than self. if v is a UnitArray, self is added to v to everyelement of v. Conversion of v is implicitely done if required.

ie.

UnitValue(1, "m") + 1                     # ok, == UnitValue(2, "m")
UnitValue(1, "m") + UnitValue(1000, "mm") # ok, == UnitValue(2, "m")
UnitValue(1, "m") + UnitArray([1,2], "m") # ok, == UnitArray([2,3], "m")
UnitValue(1, "m") + UnitValue(1, "m/s")   # ValueError

__eq__(v)

defines self == v or v == self.

if v is not a UnitValue, self.value == v is returned. if v is a UnitValue, values are considered equal if they can be expressed with the same value and units through conversion.

ie.

UnitValue(1, "µm") == 1                     # True
UnitValue(1, "µm") == UnitValue(1, "µm")    # True
UnitValue(1, "µm") == UnitValue(1e-3, "mm") # True

UnitValue(1, "µm") == UnitValue(1e-6, "mm") # False
UnitValue(1, "µm") == UnitValue(1, "µm/s")  # False

__ge__(v)

defines self >= v or v <= self.

if v is not a UnitValue, self.value >= v is returned. if v is a UnitValue, numerical value converted to the same units system are compared. A ValueError is raised if self and v have different units dimensions. a TypeError is raised if v is not a UnitValue or a number.

ie.

UnitValue(1, "µm") >= UnitValue(1, "µm")   # True
UnitValue(1, "µm") >= UnitValue(1, "mm")   # True
UnitValue(1, "µm") >= 0.5                  # True
UnitValue(1, "µm") >= UnitValue(1, "µm/s") # ValueError

__gt__(v)

defines self > v or v < self.

if v is not a UnitValue, self.value > v is returned. if v is a UnitValue, numerical value converted to the same units system are compared. A ValueError is raised if self and v have different units dimensions. a TypeError is raised if v is not a UnitValue or a number.

ie.

UnitValue(1, "µm") > UnitValue(1, "µm")   # False
UnitValue(1, "µm") > UnitValue(1, "mm")   # True
UnitValue(1, "µm") > 0.5                  # True
UnitValue(1, "µm") > UnitValue(1, "µm/s") # ValueError

__le__(v)

defines self <= v or v >= self.

if v is not a UnitValue, self.value <= v is returned. if v is a UnitValue, numerical value converted to the same units system are compared. A ValueError is raised if self and v have different units dimensions. a TypeError is raised if v is not a UnitValue or a number.

ie.

UnitValue(1, "µm") <= UnitValue(1, "µm")   # True
UnitValue(1, "µm") <= UnitValue(1, "mm")   # False
UnitValue(1, "µm") <= 0.5                  # False
UnitValue(1, "µm") <= UnitValue(1, "µm/s") # ValueError

__lt__(v)

defines self < v or v > self.

if v is not a UnitValue, self.value < v is returned. if v is a UnitValue, numerical value converted to the same units system are compared. A ValueError is raised if self and v have different units dimensions. a TypeError is raised if v is not a UnitValue or a number.

ie.

UnitValue(1, "µm") < UnitValue(1, "µm")   # False
UnitValue(1, "µm") < UnitValue(1, "mm")   # False
UnitValue(1, "µm") < 0.5                  # False
UnitValue(1, "µm") < UnitValue(1, "µm/s") # ValueError

__mod__(v)

defines self%v. if v is not a UnitValue/UnitArray, self.value%v is returned. if v is a UnitValue or a UnitArray, v and self must have the same units dimensions, a ValueError is returned otherwise. if v is a UnitArray, the modulo is operated element wise. The operation is applied to the numeric values after conversion in the same units system.

ie.

UnitValue("3 µm") % 2                      #ok, == UnitValue("1 µm")
UnitValue("3 µm") % UnitValue("2 µm")      #ok, == UnitValue("1 µm")
UnitValue("3 µm") % UnitArray([2,3], "µm") #ok, == UnitArray([1,0], "µm")

UnitValue("3 µm") % UnitValue(1, "s")      #wrong, different units dimensions

__mul__(v)

defines self*v. if v is not a UnitValue/UnitArray, is is conseidered to be a unitless factor. if v is a UnitArray, self multiplies every element of v. Conversion of v is implicitely done if required.

ie.

UnitValue(1, "µm") * UnitValue(1, "µm")    # ok == UnitValue(1, "µm2")
UnitValue(1, "µm") * UnitValue(1, "µm-1")  # ok == UnitValue(1, "")
UnitValue(1, "µm") * 2                     # ok == UnitValue(2, "µm")
UnitValue(1, "µm") * UnitValue(1, "mol/s") # ok == UnitValue(1, "µm.mol/s")
UnitValue(1, "µm") * UnitArray([1,2], "s") # ok == UnitArray([1,2], "µm.s")

__neg__()

defines the unary operation -self. returns a copy of self, but with an opposed value. ie.

-UnitValue("2 µm")  # ok, == UnitValue("-2 µm")
-UnitValue("-2 µm") # ok, == UnitValue("2 µm")

__neq__(v)

defines self != v or v != self. defined as not self.__eq__(v), see the __eq__ method for more information.

__pos__()

defines the unary operation +self. returns a copy of self. ie.

+UnitValue("2 µm")  # ok, == UnitValue("2 µm")
+UnitValue("-2 µm") # ok, == UnitValue("-2 µm")

__pow__(v)

defines self**v. v must be a number. pow is valid as long as the resluting units dimensions are integers.

ie.

__radd__(v)

defines v+self. same as self.__add__(v).

__rmod__(v)

defines v%self. type and units requirements are the same than for __mod__.

ie.

3 % UnitValue("2 µm")                      #ok, == UnitValue("1 µm")

__rmul__(v)

defines v*self. same as self.__mul__(v).

__rpow__(v)

defines v**self is an, invalid opeartion. raising something to the power of a UnitValue is not a supported opeartion. raise a ValueError.

__rsub__(v)

defines v-self. sames as -self.__sub__(v).

__rtruediv__(v)

defines v/self. same as self.invert()*v.

__sub__(v)

defines self-v. same as self.__add__(-v).

__truediv__(v)

defines self/v. if v is not a UnitValue/UnitArray, is is conseidered to be a unitless factor. Conversion is implicitely done if required.

ie.

UnitValue(1, "µm") / UnitValue(1, "µm")    # ok == UnitValue(1, "")
UnitValue(1, "µm") / UnitValue(1, "µm-1")  # ok == UnitValue(1, "µm2")
UnitValue(1, "µm") / 2                     # ok == UnitValue(0.5, "µm")
UnitValue(1, "µm") / UnitValue(1, "mol/s") # ok == UnitValue(1, "µm.s/mol")
UnitValue(1, "µm") / UnitArray([1,2], "s") # ok == UnitArray([1,0.5], "µm/s")

convert(u)

Return the UnitValue converted into the units u. u must have compatible dimensions. same as convert_value(v, u), where v is the UnitValue instance.

copy()

Returns a deepcopy of the instance.

instance.copy()

# is equivalent to
# import copy

copy.deepcopy(instance)

invert()

Invert the variable (returns 1/v).

property units

Units of the physical quantity (Units). can be set with a string or an instance of Units.

property value

Numerical value of the pysical quantity (float).

class strengths.UnitArray(value, units=None, check_value=True, convert=True)

Array of values with the same units. this is not a conventionnal array per se, as it does not expose a proper arrya interface. instread, it should rather be seen as an array wrapper, proposed for conveinience, especially for bulk unit conversions.

Parameters:

• value (array of number and/or UnitArray with the same unit dimensions) – array of values

• units (Units or str) – units of the variable

convert(u)

Returns the variable converted the units u. Same as convert_value(v, u), wher v is the UnitValue instance.

copy()

Returns a deepcopy of the instance.

instance.copy()

# is equivalent to
# import copy

copy.deepcopy(instance)

get_at(i)

Return the element of self.value at i as a UnitValue.

invert()

Invert the variable (returns 1/v).

ie.

UnitArray([1,2], "m").invert() # and
UnitArray([1,0.5], "m-1")      # are equivalent

set_at(i, v)

Sets the element of v.value at i as a the UnitValue v. units dimensions must be compatible.

set_value(v, check=True)

Sets the value property of the UnitArray.

Parameters:

• v (array of numbers and/or UnitValues and/or str.) –

  new value for the value property. it must be an array. If check=True, array elements can be string and/or numbers and/or UnitValues.

  • numbers will be accepted as such.

  • for UnitValue objects, the value is taken after proper conversion to match self.units.

    a ValueError is raise if the UnitValue’s units dimensions does not match self.units.dim.

  • strings are parsed as UnitValues then processed as such.

  However, if check=False, all elements should be numbers, as any element that is not a number may result in unexpected behaviours.

• check (bool) – tells if v should be checked or not. Can be set to False if one is sure that v is an array of numbers, without UnitValues or strings.

property units

Units of the physical values (Units). Can be set by a string or a Units instance.

property value

an array of numerical values, all associated with the same units. (numpy.ndarray [1] of number). Setting the attribute is equivalent to calling self.set_value with check=True. You may reffer to the latter for more information on accepted values for the property.

strengths.density_units_dimensions()

returns the units dimensions associated with a density (space^-3, time^0, quantity^1).

strengths.volume_units_dimensions()

returns the units dimensions associated with a volume (space^3, time^0, quantity^0).

strengths.quantity_units_dimensions()

returns the units dimensions associated with a quantity of matter (space^0, time^0, quantity^1).

strengths.space_units_dimensions()

returns the units dimensions associated with a space distance (space^1, time^0, quantity^0).

strengths.time_units_dimensions()

returns the units dimensions associated with a time distance (space^0, time^1, quantity^0).

strengths.parse_units(s)

Create Units from the character string s. ie. “µM/s” -> µmol/dm3/s

syntax is simple : integral units exponent, positive or negative, must be appended to the units ie. µm2 or m-3 each units is separated by “.” or “/” ie. m/s/mol -> m.s-1.mol-1 non fundamental units are automatically translated into fundamental units : ie. L -> dm3, µM/s -> µmol/dm3/s

strengths.parse_unitvalue(s='')

Create a UnitValue from the character string s. the value and the units must be separated by one or more whitespace : ie. “1e3 µmol/L.s-1” ok “2m” wrong

strengths.convert_value(value, su_src, su_dst, sdim)

Converts a value expressed in a given units system (su_src) into another units system (su_dst).

Parameters:

• value (number) – numerical value of the quantity to be converted

• su_src (UnitsSystem) – units system assocuated with value

• su_dst (UnitsSystem) – units system in which value should be converted

• sdim (UnitsDimensions) – units dimensions associated with value.

Returns:

converted value

Return type:

number

strengths.unitssystem_from_dict(d)

Creates a UnitsSystem from the dictionary d.

Parameters:

d (dict) – dict from which the instance qhould be created

Returns:

UnitsSystem created from d

Return type:

UnitsSystem

strengths.unitsdimensions_from_dict(d)

Creates a UnitsDimensions from the dictionary d.

Parameters:

d (dict) – dict from which the instance should be created

Returns:

UnitsDimensions created from d

Return type:

UnitsDimensions

strengths.convert_unitvalue(v, u)

Converts the UnitValue v to the Units u.

Parameters:

• v (UnitValue) – UnitValue to be converted

• u (str, dict, UnitValue, Units or UnitsSystem) – target units

Returns:

converted UnitValue

Return type:

UnitValue

strengths.unitarray_from_dict(d, base_path=None)

Returns a the UnitArray represented by the dict d.

Parameters:

v (dict) – dict represented a UnitArray

Returns:

UintArray represented by d.

Return type:

UnitArray

strengths.unitarray_to_dict(v)

Returns a dict representing the UnitArray v.

Parameters:

v (UnitArray) – unit array to be represented as a dict

Returns:

dict representing v.

Return type:

dict

References

[1]

Numpy Developers. numpy 1.25 API reference : numpy.ndarray. (consulted on september 04, 2023). https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html