What's new in IMASPy 1.1.1

--------------------------

This is a small release that mainly fixes issues related to the recent Data
Dictionary 4.0.0 release.

Bug fixes
'''''''''

- Data Dictionary 4.0.0 compatibility:

  - Fix a bug with ``get_slice`` and ``put_slice`` not correctly slicing data.
  - Update tests and examples. Some were updated to be compatible with both Data
    Dictionary 4.0.0 and 3.42.0. In other cases, the Data Dictionary version is
    now explicitly indicated.

- :issue:`IMAS-5560`: Fix a bug where IMASPy would not correctly recognize that
  the UDA backend is used.
- :issue:`IMAS-5541`: Fix a bug when converting a closed contour to Data
  Dictionary version 4.0.0.
- Work around incorrect Data Dictionary 3.x metadata when converting
  ``flux_loop/flux`` in the ``magnetics`` IDS to Data Dictionary version 4.0.0.
- Fix a bug when lazy loading Arrays of Structures that where added in a more
  recent Data Dictionary version than the on-disk data was stored with.

Notes for release 1.1.0

=======================

New features
------------

- Improved performance.
- Improved IDS conversion between Data Dictionary versions.
- IMASPy 1.1 adds support for Identifiers defined by the Data Dictionary.
- Support for the new `FLEXBUFFERS_SERIALIZER_PROTOCOL` that is
  implemented in Access Layer Core 5.3.
- Preview feature: IMAS netCDF files. Store IDSs in a self-describing
  netCDF file, which can be used for sharing and/or archiving data.
- Additional utility functions in `imaspy.util`:

  - `imaspy.util.tree_iter` can be used to iterate over all nodes inside
    an IDS.
  - `imaspy.util.get_parent` can be used to get the parent element of
    an IDS node.
  - `imaspy.util.get_time_mode` is a convenience function to get the
    `ids_properties/homogeneous_time` value for any node in the IDS.
  - `imaspy.util.get_toplevel` returns the IDS Toplevel element for any
    node in the IDS.
  - `imaspy.util.is_lazy_loaded` will indicate whether an IDS is lazy
    loaded.
  - `imaspy.util.get_full_path` returns the full path (including Array
    of Structure indices) of a node.
  - `imaspy.util.get_data_dictionary_version` returns the Data
    Dictionary version for which an IDS was created.

- Add support for IMAS Access Layer Core 5.2 and later. IMASPy can now be used
  with just the Access Layer Core package available, the full AL-Python HLI is
  no longer required.
- A diff tool for IDSs: `imaspy.util.idsdiff`.
- Implement `==` equality checking for IDS Structures and Arrays of Structures
  (IMAS-5120).
- Add option to ignore unknown Data Dictionary versions of data stored in the
  backend.
- A new command line tool exists for analyzing which Data Dictionary fields are
  used in provided Data Entries.
- Various improvements to the documentation were made.

Breaking changes
----------------

- Starting with Access Layer 5.2 or newer, the Access Layer will raise
  exceptions when errors occur in the `imas_core` layer. For example, when
  attempting to read from non-existing Data Entries or when a Data Entry cannot
  be opened for writing data.

  You may need to update the `Exception` classes in `try/except`
  blocks to the new Exception classes raised by `imas_core`.

  When using an older version of the Access Layer, the behaviour of IMASPy is no
  different than in IMASPy 1.0.

Bug fixes
---------

- Fixed a bug in `imaspy.util.inspect` when inspecting lazy loaded IDSs.
- Fixed a bug when converting the `neutron_diagnostics` IDS to/from Data
  Dictionary version `3.41.0`.
- Fixed a bug that allowed setting arbitrary attributes on IDS structures. It is
  only allowed to use attributes defined by the Data Dictionary.
- Fixed a bug with `serialize` when the IDS is in a non-default Data Dictionary version.
- Fixed a bug when assigning `nan` to a FLT_0D, which would lead to a
  confusing and incorrect log message in IMASPy 1.0.
- Fixed incorrect oldest supported DD version. Previously IMASPy indicated that
  DD `3.21.1` was supported, however `3.22.0` is the oldest Data Dictionary
  tested (and provided) with IMASPy. `imaspy.OLDEST_SUPPORTED_VERSION`
  has been updated to reflect this.
- Fixed a bug when using numpy functions, such as
  `numpy.isclose` on scalar numbers. Previously an error was
  raised (``TypeError: ufunc 'isfinite' not supported for the input types, and
  the inputs could not be safely coerced to any supported types according to the
  casting rule ''safe''``), now this works as expected.
- Fixed bugs that relied on the presence of the environment variables ``USER``,
  ``PATH`` and ``LD_LIBRARY_PATH``. Although these are defined most of the time
  on Linux systems, they can be empty and this is now handled correctly.

Notes for release 1.0.0

=======================

New features
------------
* Access Layer 5.x support: IMASPy can now work with Access Layer versions 4.11.x, 5.0.0 and 5.1.0.
* imaspy.util.calc_hash: calculate a hash of the data stored in an IDS.
* Updated command line interface. Use $ imaspy --help for more details.
* imaspy.DBEntry can be used as Context Manager in a with-statement.
* Several new Exception types in the imaspy.exception module, which can be used to catch specific errors.
* New keyword option to DBEntry.get and DBEntry.get_slice: set autoconvert=False to obtain an IDS in exactly the same Data Dictionary version as it was stored in.
* Improved dictionary-like access in IDSs and metadata: core_profiles["profiles_1d[0]/grid/rho_tor_norm"] is equivalent to core_profiles.profiles_1d[0].grid.rho_tor_norm.
* New method DBEntry.list_all_occurrences (requires AL 5.1) which lists all occurrences stored in the Data Entry for a given IDS name.
* IDS conversion: add support for successive renames in Data Dictionary metadata.
* Add support for the environment variable IMAS_AL_SERIALIZER_DIR.
* Add support for the envrionment variable IMASPY_LOGLEVEL, which can be used to control the log level of IMASPy.

Other updates
-------------
* New training course: Advanced IMASPy.
* New developer's guide to IMASPy.
* Several performance improvements for common actions such as creating IDSs, filling IDSs and loading/storing IDSs.
* Several small bug fixes.