Notes for release 2.1.0

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

Build
-----
* update Python version support (remove 3.8, add 3.13)
* add dependency on `imas_core`

Improvements
------------
- issue#84: improve `imas process-db-analysis`
- issue#71: take into account identifier aliases (introduced in DD 4.1)
- issue#78: disable *implicit* conversion when crossing a major version update
- improve integration of UDA backend
- cleaning old AL4 deprecated code
- issue#59: convert name+identifier (DD3) into description+name (DD4)
- improve type hints (following PEP-585 and PEP-604)
- improve performance of IDS deepcopy
- issue#60: improve `equilibrium` DD3->4 by converting `boundary_separatrix` into `contour_tree`
- issue#22: add custom conversion example in the doc for `em_coupling` IDS

Bug fixes
---------
- fix testcases with coordinate validation issues
- issue#80: fix `imas print` when using netcdf and imas_core is not present
- issue#61: special DD3->4 rule to flip sign quantities missing the `cocos_label_transform attribute` in DD
- pr#58: fix unclear provenance capture
- pr#57: fix 0D arrays from lazy loading with netcdf
- issue#55: handle missing case when converting 3.42->4 (_tor->_phi)

Notes for release 2.0.1

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

Improvements
------------
* Improve DD3-->DD4 conversion (sign conversion to dodpsi_like)
* Improve conversion of pulse_schedule IDS >= 3.39.0
* Numpy 2 compatibility
* Improve UDA data fetch
* Improve documentation
* New dependency on imas-data-dictionaries package (remove internal build via saxonche)
* Full compatibility of tests with netCDF<1.7 (no complex numbers)

Notes for release 2.0.0

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

Breaking change
-------------------

The package name was changed from ``imaspy`` to ``imas`` while porting the code to GitHub https://github.com/iterorganization/IMAS-Python. This shall only affect the import
statements in your code.

New features and improvements
------------------------------------

- Add `imas.util.to_xarray` to convert a full IDS or only specific paths herein to a Xarray ``Dataset``. See `Convert IMAS-Python IDSs directly to Xarray Datasets` in the documentation for more details.
- Implements automatic DD version conversion on `imas.db_entry.DBEntry.get` (conversion during `imas.db_entry.DBEntry.put` is not supported as this is rarely needed and easily worked around).
- Enable lazy loading when reading data from a netCDF file.
- Minor performance improvement loading data from a netCDF file.
- Replace versioneer by setuptools-scm to determine the version of the code.
- Use `saxonche` https://pypi.org/project/saxonche/ instead of the JAR for XSL transforms (when building versions of the DD).
- Updating the README, CONTRIBUTING guidelines and documentation after making the code open access.

Notes for release 1.2.0

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

New features and improvements
-----------------------------
- Add `imaspy.DBEntry.get_sample` (requires imas_core >= 5.4.0)
- Improved validation of netCDF files
- Improve compatibility with the UDA backend in imas_core
- Extend the support of netCDF to >= 1.4.1 (without complex numbers)
- Allow running test without imas_core

Bug fixes
---------
- Fix a bug when lazy loading multiple IDSs from the same HDF5 DBEntry
- Fix a bug when lazy loading a child quantity that was added in a newer DD version than stored on disk

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.