diff --git a/docs/iris/src/userguide/cube_maths.rst b/docs/iris/src/userguide/cube_maths.rst index 0ac2b8da74..e42af10ea2 100644 --- a/docs/iris/src/userguide/cube_maths.rst +++ b/docs/iris/src/userguide/cube_maths.rst @@ -206,7 +206,7 @@ Finally, the cube we have created needs to be given a suitable name:: temperature.rename('air_temperature') -The result could now be plotted using the guidance provided in the +The result could now be plotted using the guidance provided in the :doc:`plotting_a_cube` section. .. only:: html @@ -219,3 +219,36 @@ The result could now be plotted using the guidance provided in the A very similar example to this can be found in the examples section, with the title "Deriving Exner Pressure and Air Temperature". +Combining units +--------------- + +It should be noted that when combining cubes by multiplication, division or +power operations, the resulting cube will have a unit which is an appropriate +combination of the constituent units. In the above example, since ``pressure`` +and ``p0`` have the same unit, then ``pressure / p0`` has a dimensionless +unit of ``'1'``. Since ``(pressure / p0)`` has a unit of ``'1'``, this does +not change under power operations and so +``( (pressure / p0) ** (287.05 / 1005) )`` also has unit ``1``. Multiplying +by a cube with unit ``'1'`` will preserve units, so the cube ``temperature`` +will be given the same units as are in ``pot_temperature``. It should be +noted that some combinations of units, particularly those involving power +operations, will not result in a valid unit and will cause the calculation +to fail. For example, a cube ``a`` had units ``'m'`` then ``a ** 0.5`` +would result in an error since the square root of a meter has no meaningful +unit (if ``a`` had units ``'m2'`` then ``a ** 0.5`` would result in a cube +with units ``'m'``). + +Iris inherits units from `cf_units `_ +which in turn inherits from `UDUNITS `_. +As well as the units UDUNITS provides, cf units also provides the units +``'no-unit'`` and ``'unknown'``. A unit of ``'no-unit'`` means that the +associated data is not suitable for describing with a unit, cf units +considers ``'no-unit'`` unsuitable for combining and therefore any +arithmetic done on a cube with ``'no-unit'`` will fail. A unit of +``'unknown'`` means that the unit describing the associated data +cannot be determined. cf units and Iris will allow arithmetic on cubes +with a unit of ``'unknown'``, but the resulting cube will always have +a unit of ``'unknown'``. If a calculation is prevented because it would +result in inappropriate units, it may be forced by setting the units of +the original cubes to be ``'unknown'``. + diff --git a/docs/iris/src/userguide/navigating_a_cube.rst b/docs/iris/src/userguide/navigating_a_cube.rst index 581d1a67cf..a7b7717ae3 100644 --- a/docs/iris/src/userguide/navigating_a_cube.rst +++ b/docs/iris/src/userguide/navigating_a_cube.rst @@ -65,7 +65,8 @@ and :attr:`Cube.units ` respectively:: print(cube.units) Interrogating these with the standard :func:`type` function will tell you that ``standard_name`` and ``long_name`` -are either a string or ``None``, and ``units`` is an instance of :class:`iris.unit.Unit`. +are either a string or ``None``, and ``units`` is an instance of :class:`iris.unit.Unit`. A more in depth discussion on +the cube units and their functional effects can be found at the end of :doc:`cube_maths`. You can access a string representing the "name" of a cube with the :meth:`Cube.name() ` method:: diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Aug-25_clarify_unit_handling.txt b/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Aug-25_clarify_unit_handling.txt new file mode 100644 index 0000000000..a9d953dfbe --- /dev/null +++ b/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Aug-25_clarify_unit_handling.txt @@ -0,0 +1 @@ +* Added an explanation to the user guide of how units are handled by cube arithmetic. \ No newline at end of file