.. include:: ../common_links.inc

v3.11 (11 Nov 2024)
*******************

This document explains the changes made to Iris for this release
(:doc:`View all changes <index>`.)


.. dropdown:: v3.11 Release Highlights
   :color: primary
   :icon: info
   :animate: fade-in
   :open:

   The highlights for this minor release of Iris include:

   * Iris is now compliant with NumPy v2. See the notes below for how this might
     affect your scripts.

   * Loading now supports varying reference fields for hybrid vertical
     coordinates, e.g. a time-varying orography.  This is controlled by the
     :meth:`~iris.LOAD_POLICY` object : see :class:`~iris.LoadPolicy`.

   * `@bouweandela`_ added type hints for :class:`~iris.cube.Cube`.

   * Checkout the significant performance enhancements section for a couple of
     improvements to the performance of Iris.
     Special thanks to `@bouweandela`_ for these contributions.

   * We added ``colorbar`` keyword to allow optional creation of
     the colorbar in three quickplot methods!

   And finally, get in touch with us on :issue:`GitHub<new/choose>` if you have
   any issues or feature requests for improving Iris. Enjoy!

v3.11.1 (19 Dec 2024)
===========================

.. dropdown:: |iris_version| Patches
   :color: primary
   :icon: alert
   :animate: fade-in

   The patches in this release of Iris include:

   #. We added in a :class:`~iris.Future` flag - ``date_microseconds``, which
      prevents floating point problems arisen from :class:`cf_units.Unit` v3.3.

   #. We pinned dask to <2024.9 to prevent an indexing bug.

📢 Announcements
================

#. Iris is now compliant with NumPy v2. This may affect your scripts.
   :ref:`See the full What's New entry for more details <numpy2>`.


✨ Features
===========

#. `@jrackham-mo`_ added :meth:`~iris.io.format_picker.FormatAgent.copy` and
   equality methods to :class:`iris.io.format_picker.FormatAgent`, as requested
   in :issue:`6108`, actioned in :pull:`6119`.

#. `@ukmo-ccbunney`_ added ``colorbar`` keyword to allow optional creation of
   the colorbar in the following quickplot methods:

   * :meth:`iris.quickplot.contourf`

   * :meth:`iris.quickplot.pcolor`

   * :meth:`iris.quickplot.pcolormesh`

   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`.

#. `@ESadek-MO`_ has updated :mod:`iris.fileformats.pp_save_rules` and
   :mod:`iris.fileformats.pp` to include the `label_surface_fields` flag across
   relevant functions, most notably :func:`iris.fileformats.pp.save`.
   This allows the user to choose whether or not surface fields are recognised
   and handled appropriately. (:issue:`3280`, :pull:`5734`)

#. `@ESadek-MO`_ updated to the latest CF Standard Names Table v86
   (5 September 2024). (:pull:`6200`)

#. `@trexfeathers`_ added a new :class:`~iris.Future` flag -
   ``date_microseconds`` - which sets whether Iris should use the new
   microsecond-precision units (see :class:`cf_units.Unit`, microseconds
   introduced in version 3.3) when the unit
   is a time unit. The previous maximum precision was seconds. You should check
   your code for new floating point problems if activating this (e.g. when
   using the :class:`~iris.Constraint` API). (:pull:`6260`)

🐛 Bugs Fixed
=============

#. `@rcomer`_ enabled partial collapse of multi-dimensional string coordinates,
   fixing :issue:`3653`. (:pull:`5955`)

#. `@bouweandela`_ made further updates to the ``chunktype`` of Dask arrays,
   so it corresponds better with the array content. (:pull:`5989`)

#. `@ukmo-ccbunney`_ improved error handling for malformed `cell_method`
   attribute. Also made cell_method string parsing more lenient w.r.t.
   whitespace. (:pull:`6083`)

#. `@ukmo-ccbunney`_ fixed comparison of cubes with array type attributes;
   fixes :issue:`6027` (:pull:`6181`)

💣 Incompatible Changes
=======================

#. N/A


🚀 Performance Enhancements
===========================

#. `@bouweandela`_ made the time coordinate categorisation functions in
   :mod:`~iris.coord_categorisation` faster. Anyone using
   :func:`~iris.coord_categorisation.add_categorised_coord`
   with cftime :class:`~cftime.datetime` objects can benefit from the same
   improvement by adding a type hint to their category funcion. (:pull:`5999`)

#. `@bouweandela`_ made :meth:`iris.cube.CubeList.concatenate` faster if more
   than two cubes are concatenated with equality checks on the values of
   auxiliary coordinates, derived coordinates, cell measures, or ancillary
   variables enabled.
   In some cases, this may lead to higher memory use. This can be remedied by
   reducing the number of Dask workers.
   In rare cases, the new implementation could potentially be slower. This
   may happen when there are very many or large auxiliary coordinates, derived
   coordinates, cell measures, or ancillary variables to be checked that span
   the concatenation axis. This issue can be avoided by disabling the
   problematic check. (:pull:`5926` and :pull:`6187`)

#. Note that due to the new ``date_microseconds`` :class:`~iris.Future` flag,
   the time coordinate categorisation speedup introduced above
   will only be available when ``iris.FUTURE.date_microseconds == True``.

🔥 Deprecations
===============

#. N/A


🔗 Dependencies
===============

.. _numpy2:

#. `@trexfeathers`_ adapted the Iris codebase to work with NumPy v2. The
   `NumPy v2 full release notes`_ have the exhaustive details. Notable
   changes that may affect your Iris scripts are below. (:pull:`6035`)

   * `NumPy v2 changed data type promotion`_

   * `NumPy v2 changed scalar printing`_

#. `@stephenworsley`_ pinned dask to <2024.9 due to an indexing bug. (:issue:`6251`,
   :pull:`6255`)


📚 Documentation
================

#. `@bouweandela`_ added type hints for :class:`~iris.cube.Cube`. (:pull:`6037`)

#. `@ESadek-MO`_ has updated :ref:`um_files_loading` to include a short description
   of the new `label_surface_fields` functionality. (:pull:`5734`)


💼 Internal
===========

#. `@trexfeathers`_ improved the new ``tracemalloc`` benchmarking (introduced
   in Iris v3.10.0, :pull:`5948`) to use the same statistical repeat strategy
   as timing benchmarks. (:pull:`5981`)

#. `@trexfeathers`_ adapted Iris to work with Cartopy v0.24. (:pull:`6171`,
   :pull:`6172`)

#. `@trexfeathers`_ refactored spanning checks in :mod:`iris.fileformats.cf`
   to reduce code duplication. (:pull:`6196`)


.. comment
    Whatsnew author names (@github name) in alphabetical order. Note that,
    core dev names are automatically included by the common_links.inc:

.. _@jrackham-mo: https://github.com/jrackham-mo


.. comment
    Whatsnew resources in alphabetical order:

.. _cartopy#2390: https://github.com/SciTools/cartopy/issues/2390
.. _NumPy v2 changed data type promotion: https://numpy.org/doc/stable/numpy_2_0_migration_guide.html#changes-to-numpy-data-type-promotion
.. _NumPy v2 changed scalar printing: https://numpy.org/doc/stable/release/2.0.0-notes.html#representation-of-numpy-scalars-changed
.. _NumPy v2 full release notes: https://numpy.org/doc/stable/release/2.0.0-notes.html