Updated 2.0 release notes.

docs/iris/src/whatsnew/2.0.rst

@@ -0,0 +1,270 @@
+What's New in Iris 2.0.0
+************************
+
+:Release: 2.0.0rc1
+:Date: 2017-10-30
+
+
+This document explains the new/changed features of Iris in version 2.0.0
+(:doc:`View all changes <index>`).
+
+
+Iris 2.0.0 Features
+===================
+.. _showcase:
+
+.. admonition:: Dask Integration
+
+  The use of `Biggus`_ to provide support for *virtual arrays* and
+  *lazy evaluation* within Iris has been replaced with `Dask`_.
+
+  In addition the concept of *lazy data*, already used for the
+  :class:`~iris.cube.Cube` data component, has now been extended to the
+  data arrays of a :class:`~iris.coords.Coord` and an
+  :class:`~iris.aux_factory.AuxCoordFactory`.
+
+  This is a major feature enhancement, allowing Iris to leverage dask's rich
+  functionality and community knowledge.
+
+  In particular, Dask's *threaded*, *multiprocessing* or *distributed*
+  `schedulers`_ can be used in order to best utilise available compute and
+  memory resource.
+
+  For fuller details, see :doc:`Real and Lazy Data
+  </userguide/real_and_lazy_data>`.
+
+* Changes to the :class:`iris.cube.Cube`:
+
+  * The *new* :meth:`~iris.cube.Cube.core_data` method returns the *real* or
+    *lazy* :class:`~iris.cube.Cube` :data:`data`.
+
+  * The *new* in-place arithmetic operators :data:`__iadd__`, :data:`__idiv__`,
+    :data:`__imul__`, :data:`__isub__`, and :data:`__itruediv__` have been
+    added to support :class:`~iris.cube.Cube` operations :data:`+=`,
+    :data:`/=`, :data:`*=`, and :data:`-=`. Note that, for **divison**
+    *__future__.division* is always in effect.
+
+* Changes to the :class:`iris.coords.Coord`:
+
+  * The *new* :attr:`~iris.coords.Coord.bounds_dtype` property (read-only)
+    provides the :data:`dtype` of the coordinate bounds, if they exist.
+
+  * The *new* :meth:`~iris.coords.Coord.core_points` and
+    :meth:`~iris.coords.Coord.core_bounds` methods return the *real* or *lazy*
+    :class:`~iris.coords.Coord` :data:`points` and :data:`bounds` data,
+    respectively.
+
+  * The *new* :meth:`~iris.coords.Coord.has_lazy_points` and
+    :meth:`~iris.coords.Coord.has_lazy_bounds` boolean methods return whether
+    the coordinate has *lazy* :data:`points` and *lazy* :data:`bounds` data,
+    respectively.
+
+  * The *new* :meth:`~iris.coords.Coord.lazy_points` and
+    :meth:`~iris.coords.Coord.lazy_bounds` methods return *lazy*
+    representations of the coordinate :data:`points` and :data:`bounds` data,
+    respectively.
+
+
+The :data:`iris.FUTURE` has arrived!
+------------------------------------
+
+Throughout version 1 of Iris a set of toggles in
+:attr:`iris.FUTURE` were maintained. These toggles allowed certain "future"
+behaviour to be enabled. Since the future has now arrived in Iris 2,
+all existing toggles in :attr:`iris.FUTURE` now default to :data:`True`.
+
+ * :attr:`iris.Future.cell_datetime_objects`
+
+   * Use of this FUTURE toggle is now deprecated
+   *  :class:`iris.coords.Cell` objects in time coordinates now contain datetime objects by default and not numbers.
+      For example::
+        >>> cube = iris.load_cube(iris.sample_data_path('air_temp.pp'))
+        >>> print(cube.coord('time').cell(0).point)
+            1998-12-01 00:00:00
+
+      This change particularly impacts constraining datasets on time. All time constraints
+      must now be constructed with datetime objects or :class:`~iris.time.PartialDateTime` objects.
+      See userguide section 2.2.1 for more details on producing time constraints.
+
+
+ * :attr:`iris.Future.netcdf_promote`
+
+   * Use of this FUTURE toggle is now deprecated Removed deprecated behaviour
+   * that does not automatically promote NetCDF variables to cubes. This change
+   * means that NetCDF variables that define reference surfaces for
+   * dimensionless vertical coordinates will always be promoted and loaded as
+   * independent cubes.
+
+ * :attr:`iris.Future.netcdf_no_unlimited`
+
+   * Use of this FUTURE toggle is now deprecated
+
+ * :attr:`iris.Future.clip_latitudes`
+
+   * Use of this FUTURE toggle is now deprecated
+   * The :meth:`iris.coords.Coord.guess_bounds()` now limits the guessed bounds
+     to [-90, 90] for latitudes by default. The ability to turn this behaviour
+     off is now deprecated.
+
+
+Bugs Fixed
+==========
+
+* Indexing or slicing an :class:`~iris.coords.AuxCoord` coordinate will return a coordinate with
+  :data:`points` and :data:`bounds` data that are new copied arrays, rather than views onto those of
+  the original parent coordinate.
+
+* Indexing or slicing a cell measure will return a new cell measure with
+  :data:`data` that is a new copied array, rather than a view onto the original parent cell measure.
+
+* Performing an in-place arithmetic :func:`~iris.analysis.maths.add`,
+  :func:`~iris.analysis.maths.divide`, :func:`~iris.analysis.maths.multiply`,
+  or :func:`~iris.analysis.maths.subtract` operation on a
+  :class:`~iris.cube.Cube` with :data:`integer` or :data:`boolean` data with
+  a :data:`float` result will raise an :data:`ArithmeticError` exception.
+
+* Lazy data now refers to absolute paths rather than preserving the form that
+  was passed to iris.load functions. This means that it is possible to use
+  relative paths at load, change working directory, and still expect to be able
+  to load any un-loaded/lazy data. (#2325)
+
+* The order in which files are passed to iris.load functions is now the order in
+  which they are processed. (#2325)
+
+
+Incompatible Changes
+====================
+
+* The :meth:`~iris.cube.Cube.lazy_data` method no longer accepts any arguments.
+  Setting lazy data should now be done with :attr:`cube.data
+  <iris.cube.Cube.data>`.
+
+.. admonition:: Significant Changes in Calculated Results
+
+  Due to the replacement of `Biggus`_ with `Dask`_, as described above, the results
+  of certain types of calculation may have significantly different values from
+  those obtained in earlier versions.
+  This is of a much greater order than the usual small changes in floating
+  point results : it applies especially to any data with masked points, or of
+  long integer types.
+
+* Due to concerns regarding maintainability and API consistency the
+  :attr:`iris.cube.Cube.share_data` flag introduced in v1.13 has been removed.
+  Intra-cube data sharing is a oft-requested feature that we will be targeting
+  in a future Iris release.
+
+* Using :meth:`~iris.cube.Cube.convert_units` on a cube with unknown units will
+  now result in a :data:`UnitConversionError` being raised.
+
+
+
+Deprecation removals
+--------------------
+
+All deprecated functionality that was announced for removal in Iris 2.0 has
+been removed. In particular:
+
+* The deprecated keyword arguments ``coord`` and ``name`` have been removed from
+  the :class:`iris.cube.Cube` constructor.
+
+* The deprecated methods ``iris.cube.Cube.add_history``,
+  ``iris.cube.Cube.assert_valid`` and ``iris.cube.Cube.regridded`` have
+  been removed from :class:`iris.cube.Cube`.
+
+* The deprecated module ``iris.fileformats.pp_packing`` has been removed.
+
+* The deprecated module ``iris.proxy`` has been removed.
+
+* The deprecated configuration variable ``SAMPLE_DATA_DIR`` has been removed
+  from ``iris.config`` in favour of user installation of
+  the ``iris-sample-data`` package.
+
+* The deprecated module ``iris.unit`` has been removed in favour of
+  :mod:`cf_units`.
+
+* The ``BitwiseInt`` class has been removed from :mod:`iris.fileformats.pp`.
+
+* Removed deprecated functions ``reset_load_rules``, ``add_save_rules``,
+  ``reset_save_rules`` and ``as_pairs`` from :mod:`iris.fileformats.pp`.
+
+* The deprecated module ``iris.analysis.interpolate`` has been removed, along
+  with the following deprecated classes and functions:
+    * ``iris.analysis.interpolate.linear``
+    * ``iris.analysis.interpolate.nearest_neighbour_data_value``
+    * ``iris.analysis.interpolate.regrid``
+    * ``iris.analysis.interpolate.regrid_to_max_resolution``
+    * ``iris.analysis.interpolate.extract_nearest_neighbour``
+    * ``iris.analysis.interpolate.nearest_neighbour_indices``
+    * ``iris.analysis.interpolate.Linear1dExtrapolator``
+
+* Removed deprecated module ``iris.experimental.fieldsfile``.
+  Note that there is no direct replacement for
+  ``:meth:iris.experimental.fieldsfile.load``, which specifically performed
+  fast loading from _either_ PP or FF files.
+  Instead, please enable `:meth:iris.fileformats.um.structured_um_loading` and
+  within that context call `:meth:iris.load`, or the format-specific
+  `:meth:iris.fileformats.pp.load_cubes` or
+  `:meth:iris.fileformats.um.load_cubes`.
+
+* Removed deprecated module ``iris.fileformats.ff``.
+  Please use facilities in :mod:`iris.fileformats.um` instead.
+
+* Removed deprecated and unused kwarg ``ignore`` from the following functions:
+    * :func:`iris.analysis.calculus.curl`,
+    * :func:`iris.analysis.maths.add`, and
+    * :func:`iris.analysis.maths.subtract`.
+
+* Deprecated functions ``iris.util.broadcast_weights``,
+  ``iris.util.ensure_array`` and ``iris.util.timers`` have been removed from
+  :mod:`iris.util`.
+
+* The following classes and functions have been removed from
+  :mod:`iris.fileformats.rules`:
+
+	* ``iris.fileformat.rules.calculate_forecast_period``
+	* ``iris.fileformat.rules.log``
+	* ``iris.fileformat.rules.CMAttribute``
+	* ``iris.fileformat.rules.CMCustomAttribute``
+	* ``iris.fileformat.rules.CoordAndDims``
+	* ``iris.fileformat.rules.DebugString``
+	* ``iris.fileformat.rules.FunctionRule``
+	* ``iris.fileformat.rules.ProcedureRule``
+	* ``iris.fileformat.rules.Rule``
+	* ``iris.fileformat.rules.RulesContainer``
+	* ``iris.fileformat.rules.RuleResult``
+
+* In addition the deprecated keyword argument ``legacy_custom_rules`` has been
+  removed from the :class:`iris.fileformats.rules.Loader` constructor.
+
+* ``iris.fileformats.pp_rules`` has been renamed to
+  :mod:`iris.fileformats.pp_load_rules` for consistency with the new
+  :mod:`iris.fileformats.pp_save_rules`.
+
+* When saving a cube or list of cubes in NetCDF format, a fill value or list of
+  fill values can be specified via a new `fill_value` argument. If a list is
+  supplied, each fill value will be applied to each cube in turn. If a
+  `fill_value` argument is not specified, the default fill value for the file
+  format and the cube's data type will be used. Fill values are no longer taken
+  from the cube's `data` attribute when it is a masked array.
+
+* A 'fill_value' key can no longer be specified as part of the `packing`
+  argument to `iris.save` when saving in netCDF format. Instead, a fill value or
+  list of fill values should be specified as a separate `fill_value` argument if
+  required.
+
+* If the `packing` argument to `iris.save` is a dictionary, an error is raised
+  if it contains any keys other than 'dtype', 'scale_factor' and 'add_offset'.
+
+
+Documentation Changes
+=====================
+
+* A new UserGuide chapter on :doc:`Real and Lazy Data
+  </userguide/real_and_lazy_data>` has been added, and referenced from key
+  points in the :doc:`User Guide </userguide/index>` .
+
+
+.. _Biggus: https://biggus.readthedocs.io/en/latest/
+.. _Dask: http://dask.pydata.org/en/latest/
+.. _iris_grib: https://github.com/SciTools/iris-grib/
+.. _schedulers: http://dask.pydata.org/en/latest/scheduler-overview.html