Pace-neutrons

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

- Euphonic can now calculate neutron-weighted partial density of states, and
has new ``Spectra`` features to handle PDOS data:

- Added ``QpointPhononModes.calculate_pdos`` method
- Added ``QpointFrequencies.calculate_dos_map`` method
- New ``Spectrum1D.__add__`` method, which adds 2 spectra together
- New ``Spectrum1DCollection.__add__`` method, which concatenates 2 collections
- Enabled indexing of ``Spectrum1DCollection`` by a sequence
- Added ``Spectrum1DCollection.group_by`` method, which allows grouping and
summing spectra by metadata keys e.g. ``group_by('species')``
- Added ``Spectrum1DCollection.select`` method, which allows selection
of spectra by metadata keys e.g. ``select(species='Si')``
- Added ``Spectrum1DCollection.sum`` method, which sums all spectra in a
collection
- Added ``-w={'coherent-dos','incoherent-dos','coherent-plus-incoherent-dos'}``
neutron-weighted PDOS options to ``euphonic-dos`` and ``euphonic-powder-map``
- Added ``--pdos`` options for plotting specific species PDOS to
``euphonic-dos`` and ``euphonic-powder-map``
- Deprecated ``--weights`` command-line argument in favour of ``--weighting``
for consistency with ``calculate_pdos``

- Improvements:

- LICENSE and `CITATION.cff <https://citation-file-format.github.io/>`_
files are now included in Euphonic's installation
- Add ability to interactively change the colormap intensity limits
in ``euphonic-powder-map``
- ``euphonic-optimise-dipole-parameter`` can now read from Phonopy sources
- ``euphonic-optimise-dipole-parameter`` can now also be used for non-polar
materials to get general per-qpoint timings
- Dimensioned Euphonic properties (e.g. ``frequencies``, ``cell_vectors``)
now have setters so can be set, previously this would raise an
``AttributeError``

- Changes:

- The units of density of states as produced by ``calculate_dos`` have
changed from dimensionless to ``1/energy``
- The scaling of density of states has also changed. Previously the
integration would sum to 1 (if the ``x_data`` were converted to Hartree
units), now the integration will sum to 3N in the same units as ``x_data``
- ``StructureFactor.structure_factors`` have been changed to be in absolute
units per atom (rather than per unit cell) so will have changed by a
factor of `1/2*n_atoms`, this formulation change has been reflected in the
``calculate_structure_factor`` docstring
- The default unit of ``StructureFactor.structure_factors`` has been changed
from ``angstrom**2`` to ``millibarn``
- The unit of S(Q,w) as produced by ``StructureFactor.calculate_sqw_map``
has changed dimension from ``length**2`` to ``length**2/energy``. Also,
as its unit is derived from the input ``StructureFactor`` object, its
default units are now ``millibarn/meV``
- The ``eta_scale`` argument in ``calculate_qpoint_phonon_modes`` has been
deprecated, ``dipole_parameter`` should be used instead.
- This means the ``euphonic-optimise-eta`` script has been renamed to
``euphonic-optimise-dipole-parameter``.

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

- Improvements:

- Added ``broaden`` method to ``Spectrum1DCollection``

- Changes:

- The ``return_mode_widths`` argument in ``calculate_qpoint_phonon_modes``
has been deprecated in favour of ``return_mode_gradients``. The mode
widths can still be obtained from the mode gradients with
``util.mode_gradients_to_widths``

- Bug fixes:

- Fixed memory leak when using the C extension and making multiple calls to
``calculate_qpoint_phonon_modes/frequencies``
- Fixed bug which resulted in incorrect energy bins being generated
in ``euphonic-powder-map`` if units other than meV are used and
``--e-max`` and ``--e-min`` aren't specified
- Use correct number of energy bins in ``euphonic-intensity-map``,
``euphonic-powder-map`` and ``euphonic-dos``. Previously only
``ebins - 1`` bins were generated

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

- New Features:

- New ``Crystal.get_symmetry_equivalent_atoms`` method which uses spglib
to get the symmetry operations and equivalent atoms under each operation

- Improvements:

- Added ``symmetrise`` argument to ``QpointPhononModes.calculate_debye_waller``
which will symmetrise it under the crystal symmetry operations. This
means that there will no longer be a discrepancy between ``DebyeWaller``
calculated on a symmetry-reduced or full Monkhorst-Pack grid. By default,
``symmetrise=True``
- Added ``frequencies_min`` argument to ``calculate_debye_waller`` to
exclude very small frequencies. This will also exclude negative
frequencies. This improves on the previous behaviour which only excluded
gamma-point acoustic modes, so would miss small/negative frequencies
elsewhere
- Loading the LAPACK libraries for the C extension now uses the
`interface <https://docs.scipy.org/doc/scipy/reference/linalg.cython_lapack.html>`_
provided by `scipy` for `cython` instead of loading directly from a DLL.
The new method means we don't have to guess the DLL filename anymore!

- Changes:

- New dependency on ``spglib>=1.9.4``
- Fixed formula in ``calculate_debye_waller`` docstring to match actual
implementation: moved ``1/2`` factor and added explicit q-point weights

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

- New Features:

- New command-line tool ``euphonic-powder-map`` allows generation
and plotting of powder-averaged S(|q|,w) and DOS maps.
- New ``QpointFrequencies`` object which allows storage of frequencies
without eigenvectors, meaning that memory usage can be reduced if
eigenvectors are not required.
- ``StructureFactor`` now has a ``weights`` attribute and can be used
to calculate DOS with ``calculate_dos`` and get dispersion with
``get_dispersion``
- ``Spectrum1D``, ``Spectrum1DCollection`` and ``Spectrum2D`` objects
have a new ``metadata`` attribute, see their docstrings for details
- Euphonic can now read DOS/PDOS from CASTEP .phonon_dos files with
``Spectrum1D.from_castep_phonon_dos`` and
``Spectrum1DCollection.from_castep_phonon_dos``
- **Adaptive broadening** is now available for DOS, which can obtain a
more representative DOS than standard fixed-width broadening. See
`the docs <https://euphonic.readthedocs.io/en/latest/dos.html#adaptive-broadening>`__
for details
- Adaptive broadening can be used in the ``euphonic-dos`` tool with the
``--adaptive`` argument

- Improvements:

- Improved default behaviour for C extension use and number of threads:

- By default the C extension will be used if it is installed
- By default the number of threads will be set by
``multiprocessing.cpu_count()``
- The environment variable ``EUPHONIC_NUM_THREADS`` can be used to set
a specific number of threads, which takes priority over
``multiprocessing.cpu_count()``
- ``fall_back_on_python`` argument has been removed and superseded by the
default ``use_c=None`` behaviour
- ``threadpoolctl.threadpool_limits`` is used to limit the number of threads
used by numerical libraries in Euphonic C function calls, resulting in
better overall performance

- Command-line interfaces have been refactored, giving a more
uniform set of options and clearer sections of related arguments
on the interactive help pages.

- It is now possible where appropriate to specify Monkhorst-Pack
sampling with a single-parameter ``--q-spacing`` as an
alternative to setting Monkhorst-Pack divisions. This approach
will account for the size and shape of reciprocal-lattice cells.

- Build process tweaks

- On Linux, the build process will now respect a user-defined
C-compiler variable ``CC``.

- On Mac OSX, the build process will now respect a user-defined
C-compiler variable ``CC``. Homebrew library paths will only be
set if ``CC`` is empty and the ``brew`` command is available.

These tweaks are intended to facilitate Conda packaging.

- Breaking changes:

- The ``--q-distance`` argument to ``euphonic-intensity-map`` has
been renamed to ``--q-spacing`` for consistency with other tools.

- Debye-Waller calculation in ``euphonic-intensity-map`` is now
enabled by setting ``--temperature``, which no longer has a
default value.

- Default Monkhorst-Pack meshes (i.e. [6, 6, 6] in ``euphonic-dos``
and [20, 20, 20] in ``sample_sphere_structure_factor()``) have
been replaced by default grid-spacing values.

- The scaling of density of states has changed, due to a change
in implementation

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

- There have been some major changes and improvements to spectra, plotting
and command line tools, including:

- New command line tool ``euphonic-intensity-map`` for plotting weighted
2D Spectra e.g. Coherent neutron S(Q,w)
- Existing command line tools ``euphonic-dispersion`` and ``euphonic-dos``
have been updated to also read force constants and Phonopy files.
Arguments are also more consistent across tools so some may have changed,
check the command line tool help for details.
- New ``Spectrum1DCollection`` object for containing 1D spectra with a
shared x-axis (e.g. phonon dispersion modes)
- New ``plot_1d_to_axis`` and ``plot_2d_to_axis`` functions to allow
plotting on specific axes
- ``get_bin_centres`` and ``get_bin_edges`` utility functions on spectra
- The ``ratio`` argument to ``plot_2d`` has been removed, it should no longer
be required due to better management of relative axis sizes.
- The ``btol`` argument to ``plot_1d`` has been removed, it is recommended
to use ``Spectrum1D.split()`` or ``Spectrum1DCollection.split()`` instead.
- The ``plot_dispersion`` function has been removed. It is now recommended
to plot dispersion using ``plot_1d(QpointPhononModes.get_dispersion())``.
See docs for details.

- Other changes:

- Some of Euphonic's dependency version requirements have been changed, but
can now be relied on with more certainty due to better CI testing. This
includes:

- numpy requirement increased from ``1.9.1`` to ``1.12.1``
- matplotlib requirement increased from ``1.4.2`` to ``2.0.0``
- pint requirement decreased from ``0.10.1`` to ``0.9``
- h5py requirement decreased from ``2.9.0`` to ``2.7.0``
- pyyaml requirement decreased from ``5.1.2`` to ``3.13``

- Improvements:

- ``yaml.CSafeLoader`` is now used instead of ``yaml.SafeLoader`` by
default, so Phonopy ``.yaml`` files should load faster
- Metadata ``__euphonic_version__`` and ``__euphonic_class__`` have been
added to .json file output for better provenance

- Bug fixes:

- Fix read of Phonopy 'full' force constants from phonopy.yaml and
FORCE_CONSTANTS files
- Fix structure factor calculation at gamma points with splitting, see
`107 <https://github.com/pace-neutrons/Euphonic/issues/107>`_
- Change broadening implementation from ``scipy.signal.fftconvolve``
to use ``scipy.ndimage`` functions for better handling of bright
Bragg peaks, see
`108 <https://github.com/pace-neutrons/Euphonic/issues/108>`_

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

- New Features:

- Added `weights` as an argument to
`ForceConstants.calculate_qpoint_phonon_modes`, this will allow easier
use of symmetry reduction for calculating density of states, for example.
- Modules have been added to support spherical averaging from 3D
q-points to mod(q)

- euphonic.sampling provides pure functions for the generation of
points on (2D) unit square and (3D) unit sphere surfaces.
- A script is provided for visualisation of the different schemes
implemented in euphonic.sampling. This is primarily intended for
education and debugging.
- euphonic.powder provides functions which, given force constants
data, can use these sampling methods to obtain
spherically-averaged phonon DOS and coherent structure factor
data as 1D spectrum objects. (It is anticipated that this module
will grow to include schemes beyond this average over a single
sphere.)
- Added ``Crystal.to_spglib_cell`` convenience function

- Changes:

- The Scripts folder has been removed. Command-line tools are now
located in the euphonic.cli module. The entry-points are managed
in setup.py, and each tool has the prefix "euphonic-" to avoid
namespace clashes with other tools on the user's
computer. (e.g. euphonic-dos)
- From an interactive shell with tab-completion, one can find all
the euphonic tools by typing "euphonic-<TAB>".
- Changed arguments for ``util.get_qpoint_labels(Crystal, qpts)``
to ``util.get_qpoint_labels(qpts, cell=None)`` where
``cell = Crystal.to_spglib_cell()``

- Bug fixes:

- Correctly convert from Phonopy's q-point weight convention to Euphonic's
when reading from mesh.yaml (see
`7509043 <https://github.com/pace-neutrons/Euphonic/commit/7509043>`_)
- Avoid IndexError in ``ForceConstants.calculate_qpoint_phonon_modes`` when
there is only one q-point (which is gamma) and ``splitting=True``