Quantity
- class pydsol.core.units.Quantity(value, unit: str | None = None, **kwargs)[source]
Bases:
Generic[Q],ABC,float- Attributes:
_baseunit (dict) – Defines the baseunit for this quantity, preferably an SI unit. The baseunit is coded as a string, and should be present in the units dictionary with a conversion factor of 1.
_units (dict[str, float]:) – Defines the available units for this quantity with a conversion factor to the baseunit. The units are specified in a dictionary, mapping each string descriptor for the unit onto the conversion factor to the baseunit.
_displayunits (dict[str, str]:) – Defines a dictionary with a translation of the unit as it is entered in the code and the way the unit will be displayed in the str(..) and repr(..) methods. An example is the ‘micro’ sugn, which is entered as ‘mu’ in the units, but should be displayed as a real mu sign (μ). To make this translation for, for instance, a micrometer, the displayunits method should return a dict {‘mum’, ‘BCm’}. Another examples is the Angstrom sign for length. In case no transformations are necessary for the units in the quantity, an empty dict {} can be returned.
_descriptions (dict[str, str]:) – Defines a dictionary that maps each unit name onto a more descriptive string, e.g., ‘ms’ to ‘millisecond’.
_sidict (dict[str, int]:) – Defines dictionary with the SI signature of the quantity. The symbols that can be used are ‘1’, ‘kg’, ‘m’, ‘s’, ‘A’, ‘K’, ‘mol’, and ‘cd’. For force (Newton), the SI signature would be given as {‘kg’: 1, ‘m’: 1, ‘s’: -2} equivalent to kg.m/s^2. In addition to the SI-units, we allow ‘rad’ (m/m) and ‘sr’ (m^2/m^2) as well for reasons of clarity.
_mul (dict[Quantity, Quantity]) – Defines with which quantities the defined quantity can be multiplied, and what the resulting quantity will be. Multiplication with Dimensionless does not have to be added. It will be automatically computed at the end of the module.
_div (dict[Quantity, Quantity]) – Defines by which quantities the defined quantity can be divided, and what the resulting quantity will be. Division byDimensionless does not have to be added. It will be automatically computed at the end of the module.
- Terminology:
si (float) – The si-value of a quantity.
sidict (dict[str, int]) – Dictionary that maps SI-units onto the exponents of the signature, e.g., {‘m’: 1, ‘s’: -2} for Acceleration.
sisig (list[int]) – List with a length of 9, mapping the 2 plus 7 SI units onto the exponents of the signature, e.g., [0, 0, 0, 1, -2, 0, 0, 0, 0] for Acceleration.
siunit (str) – String representation of the unit using the SI units, e.g., ‘m/s2’ for Acceleration.
- __init__(value: float, unit: str | None = None, **kwargs)[source]
Create a Quantity instance of the right type. The si-value of the quantity is stored in the float that Quantity subclasses, so internally all values are stored in their base-unit, which is most often the si-unit.
- Raises:
ValueError – when the provided unit is not defined for this quantity, or when value is not a number
- property displayvalue: float
Return the display value of the quantity. So, for Length(14, ‘cm’) the displayvalue is 14.
- property si: float
Return the internal unit (often, but not always, si) value of the quantity. So, for Length(14, ‘cm’) si is 0.14, since the base si unit is meters.
- property unit: str
Return the unit with which the quantity was defined. So, for Length(14, ‘cm’) the unit is ‘cm’. Note that the unit is different from the displayunit. For Length(14, ‘mum’), the unit is ‘mum’, but the displayunit is μm where μ stands for mu (micro).
- as_unit(newunit: str) Q[source]
Return a new quantity that has been transformed to the new unit. The instantiation avoids multiplication and division for the allocation to the new unit as would be the case in: return self.instantiate(float(self) / self.units()[newunit], newunit). Instead, the internal si-value is copied into the return value and the unit is adapted to the new unit. This means that the two quantities Length(3.4, ‘mi’).si and Length(3.4, ‘mi’).as_unit(‘mm’).si are exactly the same without rounding errors.
- Raises:
ValueError – when newunit is not defined for this quantity
- classmethod siunit(div: bool = True, hat: str = '', dot: str = '') str[source]
Return a string with the SI-signature of this quantity, independent of the actual unit. Speed will, e.g., return m/s;
- Parameters:
div – Defines whether to use a divisor (when div == True) or negative indices for the SI units (when div == False). When div is true, Force returns kgm/s2; when it is false, it returns kgms-2.
hat – Defines the hat sign to use for indices larger than 1. When set to ‘^’, Energy would return kgm^2/s^2. When left blank, kgm2/s2.
dot – Defines the dot sign to use between quantities. When set to ‘.’, ElectricalResistance would return kg.m2/s3.A2. When left blank, kgm2/s3A2. Combined with hat=’^’: kg.m^2/s^3.A^2
- classmethod sisig() List[int][source]
Return a list with the SI-exponents of this quantity, independent of the unit. Speed will, e.g., return [0, 0, 0, 1, -1, 0, 0, 0, 0]. Note that this is not defined as a property method. Property class methods were introduced in Python 3.9, where we want this library to be compatible with Python 3.8 for now.
- static sidict_to_unit(sistr: Dict[str, int], div: bool = True, hat: str = '', dot: str = '') str[source]
Static method to return a string with the SI-signature for a dict of SI quantities with their indices, such as {‘m’:1, ‘s’:-1} for Speed, equivalent to m/s;
- Parameters:
sistr – The SI information that maps SI quantity strings on the index to use. Valid quantity strings are ‘rad’, ‘sr’, ‘kg’, ‘m’, ‘s’, ‘A’, ‘K’, ‘mol’, and ‘cd’. These are the 7 SI units plus ‘rad’ and ‘sr’ for angles for reasons of clarity.
div – Defines whether to use a divisor (when div == True) or negative indices for the SI units (when div == False). When div is true, Force returns kgm/s2; when it is false, it returns kgms-2.
hat – Defines the hat sign to use for indices larger than 1. When set to ‘^’, Energy would return kgm^2/s^2. When left blank, kgm2/s2.
dot – Defines the dot sign to use between quantities. When set to ‘.’, ElectricalResistance would return kg.m2/s3.A2. When left blank, kgm2/s3A2. Combined with hat=’^’: kg.m^2/s^3.A^2
- class pydsol.core.units.QuantityDist(wrapped_distribution: Distribution, unit: str)[source]
Bases:
Generic[Q],ABCAbstract class defining distribution functions of quantities. The quantity is created with a wapped distribution function and a unit. Drawing the random value is done using the unit, so not using the base (si) unit. When a Length(Uniform(stream, 1, 3), ‘km’) is created, a draw() will result in a Length between 1 and 3 kilometers.
- __init__(wrapped_distribution: Distribution, unit: str)[source]
Create a random distribution function that returns a quantity.