Document pseudo-level support in structured um loading.

lib/iris/fileformats/um/_fast_load.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2016, Met Office
+# (C) British Crown Copyright 2016 - 2017, Met Office
 #
 # This file is part of Iris.
 #
@@ -373,16 +373,23 @@ def structured_um_loading():
         fields of each phenomenon, such that different phenomena may have
         different field structures, and can be interleaved in any way at all.
 
+        .. note::
+
+             At present, fields with different values of 'LBUSER5'
+             (pseudo-level) are *also* treated internally as different
+             phenomena, yielding a raw cube per level.
+             The effects of this are not normally noticed, as the resulting
+             multiple raw cubes merge together again in a 'normal' load.
+             However, it is not an ideal solution as operation is less
+             efficient (in particular, slower) :  it is done to avoid a
+             limitation in the underlying code which would otherwise load data
+             on pseudo-levels incorrectly.  In future, this may be corrected.
+
     Known current shortcomings:
 
         * orography fields may be returned with extra dimensions, e.g. time,
           where multiple fields exist in an input file.
 
-        * varying values of LBUSER5, representing a 'pseudo-level' coordinate,
-          are not currently supported.
-
-          * Unfortunately, there is no good workaround for this at present.
-
         * if some input files contain a *single* coordinate value while others
           contain *multiple* values, these will not be merged into a single
           cube over all input files :  Instead, the single- and multiple-valued
@@ -420,8 +427,8 @@ def structured_um_loading():
         Various field header words which can in some cases vary are assumed to
         have a constant value throughout a given phenomenon.  This is **not**
         checked, and can lead to erroneous results if it is not the case.
-        Header elements of potential concern include LBTIM, LBCODE, LBVC,
-        LBRSVD4 (ensemble number) and LBUSER5 (pseudo-level).
+        Header elements of potential concern include LBTIM, LBCODE, LBVC and
+        LBRSVD4 (ensemble number).
 
     """
     with STRUCTURED_LOAD_CONTROLS.context(loads_use_structured=True):

lib/iris/fileformats/um/_fast_load_structured_fields.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2014 - 2016, Met Office
+# (C) British Crown Copyright 2014 - 2017, Met Office
 #
 # This file is part of Iris.
 #
@@ -230,11 +230,13 @@ def _um_collation_key_function(field):
     # as different phenomena.  These will later be merged in the "ordinary"
     # post-load merge.
     # The current structured-load code fails to handle multiple pseudo-levels
-    # correctly :  As pseudo-level is not on in its list of "things that may
+    # correctly: because pseudo-level is not on in its list of "things that may
     # vary within a phenomenon", it will create a scalar pseudo-level
     # coordinate when it should have been a vector of values.
-    # This kludge fixes the error, but it is inefficient because it bypasses
+    # This kludge fixes that error, but it is inefficient because it bypasses
     # the structured load, producing n-levels times more 'raw' cubes.
+    # It will also fail if any phenomenon occurs with multiple 'normal' levels
+    # (i.e. lblev) *and* pseudo-levels (lbuser[4]).
     # TODO: it should be fairly easy to do this properly -- i.e. create a
     # vector pseudo-level coordinate directly in the structured load analysis.
 
@@ -250,7 +252,8 @@ def group_structured_fields(field_iterator):
         A source of PP or FF fields.  N.B. order is significant.
 
     The function sorts and collates on phenomenon-relevant metadata only,
-    defined as the field components: 'lbuser[3]', 'lbuser[6]' and 'lbproc'.
+    defined as the field components: 'lbuser[3]' (stash), 'lbproc' (statistic),
+    'lbuser[6]' (model).
     Each distinct combination of these defines a specific phenomenon (or
     statistical aggregation of one), and those fields appear as a single
     iteration result.
@@ -267,6 +270,12 @@ def group_structured_fields(field_iterator):
         A generator of FieldCollation objects, each of which contains a single
         collated group from the input fields.
 
+    .. note::
+
+         At present, fields with different values of 'lbuser[4]' (pseudo-level)
+         are *also* treated as different phenomena.  This is a temporary fix,
+         standing in place for a more correct handling of pseudo-levels.
+
     """
     _fields = sorted(field_iterator, key=_um_collation_key_function)
     for _, fields in itertools.groupby(_fields, _um_collation_key_function):