v2.0.0

This release collects a number of API-breaking changes, creating a
sustainable platform for futher development. It doesn't add a
drastic number of new features compared with recent minor releases.
Still, we would draw particular attention to the work on isotope data,
which includes an expanded "Sears1992" reference data set. This should
allow proper comparison incoherent and coherent DOS weightings for
systems including isotopic substitutions, and support work on
incoherent structure factor calculations in the new "abinslib" library.

During the v1 era Euphonic has done a decent job of "semantic
versioning", and we intend to continue this way. It is recommended
that once downstream code is adapted to work with Euphonic 2.0,
Euphonic is pinned to the range 2.x,<3 (by your favourite mechanism
and syntax).

• CLI changes

  • The --instrument-broadening parameter of euphonic-dos is
    deprecated and hidden. The old --energy-broadening parameter
    is now functionally the same; i.e. it can no longer set the
    adaptive broadening width and --adaptive-scale must be used for that purpose.

• API changes

  • Many public functions and methods now use keyword-only arguments
    where previously these were permitted to be keyword or positional.

    • This will break code that depends on these arguments being in a
      specific order rather than calling them by name
    • The most "obvious" arguments can still be accessed by position
      for concise "standard" function calls; the goal is not to make
      downstream code drastically more verbose.
    • The purpose of this is to give more flexibility to add features
      or alias arguments while deprecating/changing their behaviour,
      without breaking the public API between major releases.

  • The various Spectrum classes have an assert_regular_bins
    method. It is now forbidden to use positional arguments and in the
    2D cases bin_ax has a default value of "y". This makes the API
    safer and more formally correct.

  • Unused argument use_brille is removed from
    euphonic.cli.brille_convergence.check_brille_settings.

  • get_args() function removed from euphonic.cli.utils; this
    was previously simplified to a one-liner so brings no DRY benefit.

  • Some public functions in Crystal (reciprocal_lattice,
    cell_volume) are now @cached_property and don't need ().
    The cache will be cleared on setting cell_vectors so direct changes
    to the _cell_vectors attribute may cause desynchronisation.

  • euphonic.cli.utils has been broken up into submodules. All the
    appropriate functions are re-exported to __all__ so this
    should not break API in practice, but e.g. Quantity can no longer
    be imported from euphonic.cli.utils.

  • The euphonic.data package has been redistributed to keep data
    files underneath their relevant module/package. Isotopic data is
    now under euphonic.isotopes.data and unit registry
    configuration is under euphonic.ureg.data.

  • The "adaptive fit" parameter is removed from spectrum broaden()
    methods and euphonic-dos; "cubic" parametrisation is removed and
    superior "cheby-log" fit always used.

  • validate._check_constructor_inputs is reworked to use a sequence
    of validate.InputCheck NamedTuple classes as arguments.

  • The .copy() method has been removed from Spectrum classes; use
    copy.copy() or copy.deepcopy() from the standard library instead.
    Note that copy.deepcopy() is closer to the legacy behaviour and carries
    much less risk of unintended side-effects.

  • euphonic.util.get_reference_data is deprecated and will be
    removed in Euphonic 2.0. Please use IsotopeData.get_property instead.

• Features

  • Spectrum classes now implement __eq__ and can be compared with
    ==.

  • Spectrum1DCollection and Spectrum2DCollection can be indexed with
    slices where the stop value exceeds the collection
    length. (e.g. if a collection of 5 spectra is indexed with [3:10]
    it will return a collection with the spectra at indices 3 and 4.)
    This is consistent with the behaviour of Python lists and numpy
    arrays.

    These slices can also be 0-size.

    Previously this would raise an IndexError. Technically it is a
    breaking change as somebody's code could depend on this
    IndexError.

  • A new API has been created for isotope data. The IsotopeData
    protocol promises a method .get_property(Structure, key) which
    will return per-atom values; typically these are neutron cross-sections.

    Currently this is backward-compatible and datasets may still be
    specified as a string or provided as a dict; these methods are likely to be
    deprecated as the system matures.

    A new implementation of the Sears1992 dataset has been
    created. This now supports more data columns (i.e. it can be used
    for both incoherent and coherent scattering lengths and cross
    sections) and has a full set of isotopes (as per 1992 data, anyway).
    The correct isotope or mixture is selected automatically using
    element symbols and mass data from Crystal.

• Other changes

  • Fixed several typing issues with Spectrum collections.

  • Error messages have been overhauled and now follow a consistent format::

    summary

    [reason]

    fix

• Maintenance

  • Extend use of Python 3.10 match\ es over if where relevant.