Updated documentation with respect to new handling of non-multiplicative quantities

Few errors with respect to missing/wrong output in doctests were also fixed.

3 files changed, 121 insertions, 27 deletions

diff --git a/docs/nonmult.rst b/docs/nonmult.rst
index 6af34af..3d20c79 100644
--- a/docs/nonmult.rst
+++ b/docs/nonmult.rst
@@ -4,17 +4,17 @@
 Temperature conversion
 ======================
 
-Unlike meters and seconds, fahrenheits, celsius and kelvin are not
-multiplicative units. Temperature is expressed in a system with a
-reference point, and relations between temperature units include
-not only an scaling factor but also an offset. Pint supports these
-type of units and conversions between them. The default definition
-file includes fahrenheits, celsius, kelvin and rankine abbreviated
-as degF, degC, degK, and degR.
+Unlike meters and seconds, the temperature units fahrenheits and
+celsius are non-multiplicative units. These temperature units are 
+expressed in a system with a reference point, and relations between
+temperature units include not only a scaling factor but also an offset.
+Pint supports these type of units and conversions between them. 
+The default definition file includes fahrenheits, celsius,
+kelvin and rankine abbreviated as degF, degC, degK, and degR.
 
 For example, to convert from celsius to fahrenheit:
 
-.. testsetup:: *
+.. testsetup::
 
    from pint import UnitRegistry
    ureg = UnitRegistry()
@@ -24,21 +24,23 @@ For example, to convert from celsius to fahrenheit:
 
    >>> from pint import UnitRegistry
    >>> ureg = UnitRegistry()
-   >>> home = 25.4 * ureg.degC
+   >>> Q_ = ureg.Quantity
+   >>> home = Q_(25.4, ureg.degC)
    >>> print(home.to('degF'))
-   77.72000039999993 degF
+   77.7200004 degF
 
 or to other kelvin or rankine:
 
 .. doctest::
 
-    >>> print(home.to('degK'))
-    298.54999999999995 degK
+    >>> print(home.to('kelvin'))
+    298.55 kelvin
     >>> print(home.to('degR'))
     537.39 degR
 
-Additionally, for every temperature unit in the registry,
-there is also a *delta* counterpart to specify differences.
+Additionally, for every non-multiplicative temperature unit
+in the registry, there is also a *delta* counterpart to specify 
+differences. Absolute units have no *delta* counterpart.
 For example, the change in celsius is equal to the change
 in kelvin, but not in fahrenheit (as the scaling factor
 is different).
@@ -46,20 +48,61 @@ is different).
 .. doctest::
 
    >>> increase = 12.3 * ureg.delta_degC
-   >>> print(increase.to(ureg.delta_degK))
-   12.3 delta_degK
+   >>> print(increase.to(ureg.kelvin))
+   12.3 kelvin
    >>> print(increase.to(ureg.delta_degF))
-   6.833333333333334 delta_degF
+   22.14 delta_degF
 
 ..
-    Subtraction of two temperatures also yields a *delta* unit.
+Subtraction of two temperatures given in offset units yields a *delta* unit:
 
-    .. doctest::
+.. doctest::
+
+    >>> Q_(25.4, ureg.degC) - Q_(10., ureg.degC)
+    <Quantity(15.4, 'delta_degC')>
+
+You can add or subtract a quantity with *delta* unit and a quantity with 
+offset unit:
+
+.. doctest::
+
+    >>> Q_(25.4, ureg.degC) + Q_(10., ureg.delta_degC)
+    <Quantity(35.4, 'degC')>
+    >>> Q_(25.4, ureg.degC) - Q_(10., ureg.delta_degC)
+    <Quantity(15.4, 'degC')>
+
+If you want to add a quantity with absolute unit to one with offset unit, like here
+
+.. doctest::
+
+    >>> heating_rate = 0.5 * ureg.kelvin/ureg.min
+    >>> Q_(10., ureg.degC) + heating_rate * Q_(30, ureg.min)
+    Traceback (most recent call last):
+            ...
+    pint.unit.OffsetUnitCalculusError: Ambiguous operation with offset unit (degC, kelvin).
+
+you have to avoid the ambiguity by either converting the offset unit to the 
+absolute unit before addition
+
+.. doctest::
+
+    >>> Q_(10., ureg.degC).to(ureg.kelvin) + heating_rate * Q_(30, ureg.min)
+    <Quantity(298.15, 'kelvin')>
+
+or convert the absolute unit to a *delta* unit:
+
+.. doctest::
 
-        >>> 25.4 * ureg.degC - 10. * ureg.degC
-        15.4 delta_degC
+    >>> Q_(10., ureg.degC) + heating_rate.to('delta_degC/min') * Q_(30, ureg.min)
+    <Quantity(25.0, 'degC')>
 
-Differences in temperature are multiplicative:
+In contrast to subtraction, the addition of quantities with offset units 
+is ambiguous, e.g. for *10 degC + 100 degC* two different result are reasonable
+depending on the context, *110 degC* or *383.15 °C (= 283.15 K + 373.15 K)*.
+Because of this ambiguity pint raises an error for the addition of two 
+quantities with offset units (since pint-0.6).
+
+Quantities with *delta* units are multiplicative:
 
 .. doctest::
 
@@ -67,7 +110,55 @@ Differences in temperature are multiplicative:
     >>> print(speed.to('delta_degC/second'))
     1.0 delta_degC / second
 
-The parser knows about *delta* units and use them when a temperature unit
+However, 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:
+
+.. doctest::
+
+    >>> home = 25.4 * ureg.degC
+    Traceback (most recent call last):
+        ...
+    pint.unit.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:
+
+* Multiplication of a quantity with a single offset unit with order +1 by
+  a number or ndarray yields the quantity in the given unit.
+
+.. 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
+    Traceback (most recent call last):
+        ...
+    pint.unit.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::
@@ -92,9 +183,10 @@ You can override this behaviour:
 Note that the magnitude is left unchanged:
 
 .. 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::
 
@@ -103,3 +195,5 @@ this is the definition of the celsius and fahrenheit::
 
 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.
\ No newline at end of file
diff --git a/docs/serialization.rst b/docs/serialization.rst
index 6e7c133..c1f2a89 100644
--- a/docs/serialization.rst
+++ b/docs/serialization.rst
@@ -19,7 +19,7 @@ The easiest way to do this is by converting the quantity to a string:
    >>> import pint
    >>> ureg = pint.UnitRegistry()
    >>> duration = 24.2 * ureg.years
-   >>> print(duration)
+   >>> duration
    <Quantity(24.2, 'year')>
    >>> serialized = str(duration)
    >>> print(serialized)
@@ -37,7 +37,7 @@ to recover it in another process/machine, you just:
    >>> ureg = pint.UnitRegistry()
    >>> duration = ureg('24.2 year')
    >>> print(duration)
-   <Quantity(24.2, 'year')>
+   24.2 year
 
 Notice that the serialized quantity is likely to be parsed in **another** registry
 as shown in this example. Pint Quantities do not exist on their own but they are
@@ -72,6 +72,7 @@ To unpickle, just
 
     >>> magnitude, units = pickle.loads(serialized)
     >>> ureg.Quantity(magnitude, units)
+    <Quantity(24.2, 'year')>
 
 You can use the same mechanism with any serialization protocol, not only with binary ones.
 (In fact, version 0 of the Pickle protocol is ascii). Other common serialization protocols/packages
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index 8ad01cd..f89d2cf 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -96,7 +96,6 @@ There are also methods 'to_base_units' and 'ito_base_units' which automatically
    >>> print(height)
    5.75 foot
    >>> height.ito_base_units()
-   <Quantity(1.7526, 'meter')>
    >>> print(height)
    1.7526 meter