bluemira.base.parameter_frame._units
====================================

.. py:module:: bluemira.base.parameter_frame._units


Functions
---------

.. autoapisummary::

   bluemira.base.parameter_frame._units._validate_units
   bluemira.base.parameter_frame._units._ensure_SI_unit_system
   bluemira.base.parameter_frame._units._remake_units
   bluemira.base.parameter_frame._units._convert_non_commutative
   bluemira.base.parameter_frame._units._combine_commutative


Module Contents
---------------

.. py:function:: _validate_units(param_data: bluemira.base.parameter_frame._parameter.ParamDictT, value_type: collections.abc.Iterable[type]) -> bluemira.base.parameter_frame._parameter.ParamDictT

   Validates the user input units and enforces our version of SI units

   :returns: Parameter dictionary

   :raises ValueError: If a value raises value error on a Quantity
       If a value doesnt have a unit
   :raises TypeError: When trying to convert offset or logarithmic units or strings/bools/None

   .. rubric:: Notes

   Firstly this ensures that scaling factors are folded into the value.
   Deals with empty values (None) and strings for parameters
   Finally where not one of the above converts to our opinionated SI units


.. py:function:: _ensure_SI_unit_system(quantity: pint.Quantity, param_data: bluemira.base.parameter_frame._parameter.ParamDictT, value_type: collections.abc.Iterable[type]) -> bluemira.base.parameter_frame._parameter.ParamDictT

   Enforces our SI unit system and updates the value accordingly

   :returns: Parameter dictionary

   .. rubric:: Notes

   Also deals with the case where a unit is collapsed to dimensionless with
   some scaling factor, then the value should be updated


.. py:function:: _remake_units(quantity: pint.Quantity) -> pint.Quantity

   Reconstruct unit from its dimensionality.

   :param quantity: The quantity to reconstruct

   :returns: The quantity in new units

   .. rubric:: Notes

   The quantity of the conversion is not important here.
   We just want the custom SI version of the input
   The value conversion is done later.


.. py:function:: _convert_non_commutative(unit_list: list[pint.Quantity], filter_index: list[int]) -> pint.Quantity

   Converts angle units and combines non commutative units

   .. rubric:: Notes

   Commutative here means units that we dont want to combine eg time and full power year


.. py:function:: _combine_commutative(unit_list: list[pint.Quantity], filter_index: list[int]) -> pint.Quantity

   Combine commutative units

   .. rubric:: Notes

   Uses pints milp optimisation which can over combine eg W/m^2 -> kg/s^3.
   The optimisation minimises combinations eg the "knapsack problem".
   This function prioritise shorter original over new which could be improved in future

   Commutative here means units that we dont want to combine eg time and full power year