Enable factory references to create new dimensions on load. (#6168) (#…

…6194)

* Enable factory references to create new dimensions on load.

* Skip hanging tests.

* Skip more hanging tests.

* Adjust misleading comment.

* Add policy control and auto-detect. NOTE: for now only load, not load_cubes/load_cube

* Add temporary testcode.  NB no actual test, just printout.

* Replaced _CubeFilterCollection.merged() with combined(); replace uses in load;load_cube/load_cubes.

* Fix licence header

* Fix to handle empty reference correctly.

* Fix tests.

* Simplify policy options and tidy api.

* More documentation of loading options.

* Fix doctest.

* Fix repeated combination.

* Minor docs improvements.

* Initial load functions testing (WIP).

More

* Integration tests for time-varying reference fields.

* Fix test result.

* Make grib test optional.

* Review changes

* Reinstate skipped tests.

* Make combine_cubes work with plain lists; Make 'combine_cubes' private API.

* Add tests for combine_cubes.

* Add tests for LoadPolicy API.

* Add special split-netcdf roundtrip testing.

* Removed unwanted 'policy' keyword from iris.load .

* Make LoadPolicy examples more consistent.

* Review changes : documentation improvements.

* Doctest fix

* fix controlling_merge docs

* LOAD_POLICY uses 'default' settings by default.

* Various quick fixes to legacy tests.

* Added whatsnew.

---------

Co-authored-by: Patrick Peglar <[email protected]>

docs/src/further_topics/controlling_merge.rst

@@ -4,6 +4,21 @@
 Controlling Merge and Concatenate
 =================================
 
+Preliminaries
+-------------
+
+The following code would have been necessary with loading behaviour prior to version 3.11.0 . For the sake of
+demonstration, we will revert back to this legacy loading behaviour as follows:
+
+    >>> iris.LOAD_POLICY.set("legacy")
+
+.. note::
+    The default settings for :data:`iris.LOAD_POLICY` effectively implements some version of the following demonstration
+    automatically upon loading. It may still be worth being aware of how to handle this manually if an even finer degree
+    of control is required.
+
+How to Merge Cubes When Coordinates Differ
+------------------------------------------
 
 Sometimes it is not possible to appropriately combine a CubeList using merge and concatenate on their own. In such cases
 it is possible to achieve much more control over cube combination by using the :func:`~iris.util.new_axis` utility.
@@ -200,5 +215,8 @@ Once merged, we can now concatenate all these cubes into a single result cube, w
             source                      'Data from Met Office Unified Model'
             um_version                  '12.1'
 
-.. todo::
-    Mention the work done in #6168
+See Also
+--------
+* :data:`iris.LOAD_POLICY` can be controlled to apply similar operations
+  within the load functions, i.e. :func:`~iris.load`, :func:`~iris.load_cube` and
+  :func:`~iris.load_cubes`.

docs/src/whatsnew/latest.rst

@@ -46,6 +46,10 @@ This document explains the changes made to Iris for this release
 
    Requested in :issue:`5970`, actioned in :pull:`6169`.
 
+#. `@pp-mo`_ and `@stephenworsley`_ added support for hybrid coordinates whose
+   references are split across multiple input fields, and :meth:`~iris.LOAD_POLICY` to
+   control it, as requested in :issue:`5369`, actioned in :pull:`6168`.
+
 
 🐛 Bugs Fixed
 =============