v3.10.x.mergeback

docs/src/whatsnew/3.10.rst

@@ -0,0 +1,245 @@
+.. include:: ../common_links.inc
+
+v3.10 (30 Jul 2024 [release candidate])
+***************************************
+
+This document explains the changes made to Iris for this release
+(:doc:`View all changes <index>`.)
+
+
+.. dropdown:: v3.10 Release Highlights
+   :color: primary
+   :icon: info
+   :animate: fade-in
+   :open:
+
+   The highlights for this minor release of Iris include:
+
+   * Breaking Change: We have moved all of the mesh API from :mod:`iris.experimental.ugrid` to
+     :mod:`iris.mesh`. This is no longer experimental making this public supported API.
+
+   * We have made a suite of mesh improvements, there is a separate entry below for each of these changes .
+
+   * We have made :meth:`~iris.coords.guess_bounds` capable of setting bounds to the start and end of months and years.
+
+   * We have significantly reduced warning noise during NetCDF loading. The datum :class:`python:FutureWarning`
+     will now only be raised if the
+     ``datum_support`` :class:`~iris.Future` flag is disabled AND a datum is
+     present on the loaded NetCDF grid mapping.
+
+   * Checkout the performance enhancements section for an array of improvements to the performance of Iris.
+     Special thanks to the `ESMValTool`_ devs for these contributions.
+
+
+   And finally, get in touch with us on :issue:`GitHub<new/choose>` if you have
+   any issues or feature requests for improving Iris. Enjoy!
+
+
+📢 Announcements
+================
+
+#. Breaking Change: We have moved all of the mesh API from :mod:`iris.experimental.ugrid` to
+   :mod:`iris.mesh`. This is no longer experimental making this public supported API.
+   Future changes will honour Semantic Versioning - i.e. breaking changes will only be in major releases,
+   and ideally will be previewed via :class:`iris.Future` flags.
+
+#. Note that Iris is currently pinned to NumPy ``<2``, we hope to unpin this in the next minor release (Iris v3.11).
+
+
+✨ Features
+===========
+
+#. `@ESadek-MO`_ updated the error messages in :meth:`iris.cube.CubeList.concatenate`
+   to better explain the error. (:pull:`6005`)
+
+#. `@trexfeathers`_ added the
+   :meth:`~iris.experimental.ugrid.mesh.MeshCoord.collapsed` method to
+   :class:`~iris.experimental.ugrid.mesh.MeshCoord`, enabling collapsing of
+   the :class:`~iris.cube.Cube` :attr:`~iris.cube.Cube.mesh_dim` (see
+   :ref:`cube-statistics-collapsing`). (:issue:`5377`, :pull:`6003`)
+
+#. `@pp-mo`_ made a MeshCoord inherit a coordinate system from its location coord,
+   as it does its metadata.  N.B. mesh location coords can not however load a
+   coordinate system from netcdf at present, as this needs the 'extended'
+   grid-mappping syntax -- see : :issue:`3388`.
+   (:issue:`5562`, :pull:`6016`)
+
+#. `@HGWright`_ added the `monthly` and `yearly` options to the
+   :meth:`~iris.coords.guess_bounds` method. (:issue:`4864`, :pull:`6090`)
+
+#. `@HGWright`_ updated to the latest CF Standard Names Table v85
+   (30 July 2024). (:pull:`6100`)
+
+
+🐛 Bugs Fixed
+=============
+
+#. `@bouweandela`_ updated the ``chunktype`` of Dask arrays, so it corresponds
+   to the array content. (:pull:`5801`)
+
+#. `@rcomer`_ made the :obj:`~iris.analysis.WPERCENTILE` aggregator work with
+   :func:`~iris.cube.Cube.rolling_window`.  (:issue:`5777`, :pull:`5825`)
+
+
+#. `@pp-mo`_ corrected the use of mesh dimensions when saving with multiple
+   meshes.  (:issue:`5908`, :pull:`6004`)
+
+#. `@trexfeathers`_ fixed the datum :class:`python:FutureWarning` to only be raised if
+   the ``datum_support`` :class:`~iris.Future` flag is disabled AND a datum is
+   present on the loaded NetCDF grid mapping. (:issue:`5749`, :pull:`6050`)
+
+
+💣 Incompatible Changes
+=======================
+
+#. `@rcomer`_ removed the *target* parameter from
+   :func:`~iris.fileformats.pp.as_fields` and
+   :func:`~iris.fileformats.pp.save_pairs_from_cube` because it had no effect.
+   (:pull:`5783`)
+
+#. `@stephenworsley`_ made masked arrays on Iris objects now compare as equal
+   precisely when all unmasked points are equal and when the masks are identical.
+   This is due to changes in :func:`~iris.util.array_equal` which previously
+   ignored masks entirely. (:pull:`4457`)
+
+#. `@trexfeathers`_ renamed the ``Mesh`` class to
+   :class:`~iris.experimental.ugrid.mesh.MeshXY`, in preparation for a future
+   more flexible parent class (:class:`~iris.experimental.ugrid.mesh.Mesh`).
+   (:issue:`6052` :pull:`6056`)
+
+#. `@stephenworsley`_ replaced the ``include_nodes``, ``include_edges`` and
+   ``include_faces`` arguments with a single ``location`` argument in the
+   :class:`~iris.experimental.ugrid.Mesh` methods
+   :meth:`~iris.experimental.ugrid.Mesh.coord`, :meth:`~iris.experimental.ugrid.Mesh.coords`
+   and :meth:`~iris.experimental.ugrid.Mesh.remove_coords`. (:pull:`6055`)
+
+#. `@pp-mo`_ moved all the mesh API from the :mod:`iris.experimental.ugrid` module to
+   to :mod:`iris.mesh`, making this public supported API.  Note that the
+   :class:`iris.experimental.ugrid.Mesh` class is renamed as :class:`iris.mesh.MeshXY`,
+   to allow for possible future mesh types with different properties to exist as
+   subclasses of a common generic :class:`~iris.mesh.components.Mesh` class.
+   (:issue:`6057`, :pull:`6061`, :pull:`6077`)
+
+#. `@pp-mo`_ and `@stephenworsley`_ Turned on UGRID loading by default, effectively removing
+   the need for and deprecating the :func:`~iris.ugrid.experimental.PARSE_UGRID_ON_LOAD`
+   context manager. (:pull:`6054`, :pull:`6088`)
+
+
+🚀 Performance Enhancements
+===========================
+
+#. `@bouweandela`_ added the option to specify the Dask chunks of the target
+   array in :func:`iris.util.broadcast_to_shape`. (:pull:`5620`)
+
+#. `@schlunma`_ allowed :func:`iris.analysis.cartography.area_weights` to
+   return dask arrays with arbitrary chunks. (:pull:`5658`)
+
+#. `@bouweandela`_ made :meth:`iris.cube.Cube.rolling_window` work with lazy
+   data. (:pull:`5795`)
+
+#. `@bouweandela`_ updated :meth:`iris.cube.CubeList.concatenate` so it keeps
+   ancillary variables and cell measures lazy. (:pull:`6010`)
+
+#. `@bouweandela`_ made :meth:`iris.cube.CubeList.concatenate` faster for cubes
+   that have coordinate factories. (:pull:`6038`)
+
+🔥 Deprecations
+===============
+
+None!
+
+
+🔗 Dependencies
+===============
+
+#. `@tkknight`_ removed the pin for ``sphinx <=5.3``, so the latest should
+   now be used, currently being v7.2.6.
+   (:pull:`5901`)
+
+#. `@trexfeathers`_ updated the :mod:`iris.experimental.geovista`
+   documentation's use of :class:`geovista.geodesic.BBox`
+   to be compatible with GeoVista v0.5, as well as previous versions.
+   (:pull:`6064`)
+
+#. `@pp-mo`_ temporarily pinned matplotlib to ">=3.5, !=3.9.1", to avoid current CI
+   test failures on plot results, apparently due to a matplotlib bug.
+   See : https://github.com/matplotlib/matplotlib/issues/28567
+   (:pull:`6065`)
+
+#. Note that Iris is currently pinned to NumPy ``<2``, we hope to unpin this in the next minor release (Iris v3.11).
+
+
+
+📚 Documentation
+================
+
+#. `@hsteptoe`_ added more detailed examples to :class:`~iris.cube.Cube` functions
+   :func:`~iris.cube.Cube.slices` and :func:`~iris.cube.Cube.slices_over`. (:pull:`5735`)
+
+
+💼 Internal
+===========
+
+#. `@bouweandela`_ removed a workaround in :meth:`~iris.cube.CubeList.merge` for an
+   issue with :func:`dask.array.stack` which has been solved since 2017. (:pull:`5923`)
+
+#. `@trexfeathers`_ introduced a temporary fix for Airspeed Velocity's
+   deprecated use of the ``conda --force`` argument. To be removed once
+   `airspeed-velocity/asv#1397`_ is merged and released. (:pull:`5931`)
+
+#. `@trexfeathers`_ created :func:`iris.tests.stock.realistic_4d_w_everything`;
+   providing a :class:`~iris.cube.Cube` aimed to exercise as much of Iris as
+   possible. (:pull:`5949`)
+
+#. `@trexfeathers`_ deactivated any small 'unit-style' benchmarks for default
+   benchmark runs, and introduced larger more 'real world' benchmarks where
+   coverage was needed. (:pull:`5949`).
+
+#. `@trexfeathers`_ made a Nox `benchmarks` session as the recommended entry
+   point for running benchmarks. (:pull:`5951`)
+
+#. `@ESadek-MO`_ added further `benchmarks` for aggregation and collapse.
+   (:pull:`5954`)
+
+#. `@trexfeathers`_ set the benchmark data generation environment to
+   automatically install iris-test-data during setup. (:pull:`5958`)
+
+#. `@pp-mo`_ reworked benchmark peak-memory measurement to use the
+   `tracemalloc <https://docs.python.org/3.12/library/tracemalloc.html>`_
+   package.
+   (:pull:`5948`)
+
+#. `@pp-mo`_ added a benchmark 'trialrun' sub-command, to quickly test
+   benchmarks during development. (:pull:`5957`)
+
+#. `@pp-mo`_ moved several memory-measurement benchmarks from 'on-demand' to
+   the standard set, in hopes that use of 'tracemalloc' (:pull:`5948`) makes
+   the results consistent enough to monitor for performance changes.
+   (:pull:`5959`)
+
+#. `@rcomer`_ made some :meth:`~iris.cube.Cube.slices_over` tests go faster (:pull:`5973`)
+
+#. `@bouweandela`_ enabled mypy checks for type hints.
+   The entire team would like to thank Bouwe for putting in the hard
+   work on an unglamorous but highly valuable contribution. (:pull:`5956`)
+
+#. `@trexfeathers`_ re-wrote the delegated ASV environment plugin to reduce
+   complexity, remove unnecessary slow operations, apply the least-surprise
+   principle, be more robust against failures, and improve the ability to
+   benchmark historic commits (especially older Python versions).
+   (:pull:`5963`)
+
+#. `@bouweandela`_ made some tests for :func:`~iris.iterate.izip` faster. (:pull:`6041`)
+
+.. comment
+    Whatsnew author names (@github name) in alphabetical order. Note that,
+    core dev names are automatically included by the common_links.inc:
+
+.. _@hsteptoe: https://github.com/hsteptoe
+
+
+.. comment
+    Whatsnew resources in alphabetical order:
+
+.. _airspeed-velocity/asv#1397: https://github.com/airspeed-velocity/asv/pull/1397
+.. _ESMValTool: https://github.com/ESMValGroup/ESMValTool

docs/src/whatsnew/index.rst

@@ -13,6 +13,7 @@ What's New in Iris
    :hidden:
 
    latest.rst
+   3.10.rst
    3.9.rst
    3.8.rst
    3.7.rst