diff options
| -rw-r--r-- | docs/log_units.rst | 132 |
1 files changed, 48 insertions, 84 deletions
diff --git a/docs/log_units.rst b/docs/log_units.rst index 1f11327..e22acb0 100644 --- a/docs/log_units.rst +++ b/docs/log_units.rst @@ -17,113 +17,77 @@ the recommendations there apply here as well. explicit ``Quantity()`` constructor. Many examples on this page assume you've passed this parameter, and will not work otherwise. -.. testsetup:: +Defining log units +------------------ - from pint import UnitRegistry - ureg = UnitRegistry(autoconvert_offset_to_baseunit=True) - ureg.default_format = '.3f' - Q_ = ureg.Quantity - -.. doctest:: - - >>> from pint import UnitRegistry - >>> ureg = UnitRegistry(autoconvert_offset_to_baseunit=True) - >>> Q_ = ureg.Quantity - >>> signal_power = -20.0 * ureg.dBm - >>> print(f"{sp.to('milliwatts'):0.3~P}") - 0.01 mW - -TODO: -[ ] explain delta units (what purpose do they have here?) -[ ] example computing mW to dBm -[ ] example computing dB and (something) +First, set up your ``UnitRegistry`` with the suggested flag. - -Multiplication, division and exponentiation of quantities with -offset units is problematic just like addition. Pint (since version 0.6) -will by default raise an error when a quantity with offset unit is used in -these operations. Due to this quantities with offset units cannot be created -like other quantities by multiplication of magnitude and unit but have -to be explicitly created: +If you do not wish to use the ``autoconvert_offset_to_baseunit`` flag, you +will need to define all logarithmic units using the ``Quanity()`` constructor: .. doctest:: + >>> from pint import UnitRegistry >>> ureg = UnitRegistry() - >>> home = 25.4 * ureg.degC + >>> Q_ = ureg.Quantity + >>> signal_power_dbm = 20 * ureg.dBm # must pass flag for this to work Traceback (most recent call last): ... - OffsetUnitCalculusError: Ambiguous operation with offset unit (degC). - >>> Q_(25.4, ureg.degC) - <Quantity(25.4, 'degC')> - -As an alternative to raising an error, pint can be configured to work more -relaxed via setting the UnitRegistry parameter *autoconvert_offset_to_baseunit* -to true. In this mode, pint behaves differently: + OffsetUnitCalculusError: Ambiguous operation with offset unit (decibellmilliwatt, ). + >>> Q_(20, 'dBm') # define like this instead + <Quantity(20, 'decibellmilliwatt')> -* Multiplication of a quantity with a single offset unit with order +1 by - a number or ndarray yields the quantity in the given unit. +You will also be restricted in the kinds of operations you can do without +converting to base units first. .. doctest:: - >>> ureg = UnitRegistry(autoconvert_offset_to_baseunit = True) - >>> T = 25.4 * ureg.degC - >>> T - <Quantity(25.4, 'degC')> - -* Before all other multiplications, all divisions and in case of - exponentiation [#f1]_ involving quantities with offset-units, pint - will convert the quantities with offset units automatically to the - corresponding base unit before performing the operation. - - >>> 1/T - <Quantity(0.00334952269302, '1 / kelvin')> - >>> T * 10 * ureg.meter - <Quantity(527.15, 'kelvin * meter')> - -You can change the behaviour at any time: - - >>> ureg.autoconvert_offset_to_baseunit = False - >>> 1/T + >>> Q_(10, 'dBm/Hz') * (100 * ureg.Hz) # not feasible without flag Traceback (most recent call last): ... - OffsetUnitCalculusError: Ambiguous operation with offset unit (degC). - -The parser knows about *delta* units and uses them when a temperature unit -is found in a multiplicative context. For example, here: - -.. doctest:: + UndefinedUnitError: 'delta_decibellmilliwatt' is not defined in the unit registry - >>> print(ureg.parse_units('degC/meter')) - delta_degC / meter - -but not here: +Passing the flag will allow you to use a more natural syntax for defining +logarithmic units: .. doctest:: - >>> print(ureg.parse_units('degC')) - degC + >>> from pint import UnitRegistry + >>> ureg = UnitRegistry(autoconvert_offset_to_baseunit=True) + >>> Q_ = ureg.Quantity + >>> 20.0 * ureg.dBm + <Quantity(20.0, 'decibellmilliwatt')> -You can override this behaviour: +Converting to and from base units +--------------------------------- -.. doctest:: + >>> signal_power_dbm = 20.0 * ureg.dBm + >>> signal_power_dbm.to('mW') + <Quantity(100.0, 'milliwatt')> + >>> signal_power_mw = 100.0 * ureg.mW + >>> signal_power_mw + <Quantity(100.0, 'milliwatt')> + >>> signal_power_mw.to('dBm') + <Quantity(20.0, 'decibellmilliwatt')> - >>> print(ureg.parse_units('degC/meter', as_delta=False)) - degC / meter +Compound log units +------------------ -Note that the magnitude is left unchanged: +Pint also works with mixtures of logarithmic and other units. .. doctest:: - >>> Q_(10, 'degC/meter') - <Quantity(10, 'delta_degC / meter')> - -To define a new temperature, you need to specify the offset. For example, -this is the definition of the celsius and fahrenheit:: - - degC = degK; offset: 273.15 = celsius - degF = 5 / 9 * degK; offset: 255.372222 = fahrenheit + >>> noise_density = -161.0 * ureg['dBm/Hz'] + >>> bandwidth = 10.0 * ureg.kHz + >>> noise_power = noise_density * bandwidth + >>> noise_power.to('dBm') + <Quantity(-121.0, 'decibellmilliwatt')> + >>> noise_power.to('mW') + <Quantity(7.94328235e-13, 'milliwatt')> -You do not need to define *delta* units, as they are defined automatically. - -.. [#f1] If the exponent is +1, the quantity will not be converted to base - unit but remains unchanged. +Multiplication, division and exponentiation of quantities with +offset units is problematic just like addition. Pint (since version 0.6) +will by default raise an error when a quantity with offset unit is used in +these operations. Due to this quantities with offset units cannot be created +like other quantities by multiplication of magnitude and unit but have +to be explicitly created: |