Euphonic

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

- Changes:

- Support for Python 3.6 has been dropped. This has also resulted in
changes to the following dependencies:

- numpy requirement increased from ``1.12.1`` to ``1.14.5``
- scipy requirement increased from ``1.0.0`` to ``1.1.0``
- pint requirement increased from ``0.9`` to ``0.10.1``
- matplotlib requirement increased from ``2.0.0`` to ``2.2.2``
- h5py requirement increased from ``2.7.0`` to ``2.8.0``

- The following deprecated features have been removed:

- The ``return_mode_widths`` argument in ``ForceConstants.calculate_qpoint_phonon_modes``
and ``ForceConstants.calculate_qpoint_frequencies`` has been removed
- The ``eta_scale`` argument in ``calculate_qpoint_phonon_modes/frequencies``
has been removed
- The alias command-line tool argument ``--weights`` has been removed
- The alias arguments ``x_label``, ``y_label``, ``y_min`` and ``y_max`` to
``plot_1d/2d`` have been removed
- The ``modes_from_file`` and ``force_constants_from_file`` functions from
``euphonic.cli.utils`` have been removed
- Calling ``broaden`` on a ``Spectrum`` with uneven bin widths without
specifying the ``method='convolve'`` argument will now raise a ``ValueError``

- DOS and PDOS calculated by the ``calculate_dos`` and
``calculate_dos_map`` methods of ``QpointPhononModes`` and
``QpointFrequencies``, and ``QpointPhononModes.calculate_pdos`` are
now calculated per atom rather than per unit cell (integrated area
is ``3`` rather than ``3*N_atom``). This is to keep consistency with
the structure factors calculated by
``QpointPhononModes.calculate_structure_factor`` which are calculated
per atom.

- The option ``average_repeat_points`` when importing q-point modes or
frequencies from a CASTEP .phonon file with
``QpointFrequencies/QpointPhononModes.from_castep`` is now ``True``
by default. To recover previous behaviour set this to ``False``.

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

- New Features:

- Kinematic constraints have been implemented for 2-D S(q,w)-like data.

- A function ``euphonic.spectra.apply_kinematic_constraints(Spectrum2d, **kwargs) -> Spectrum2D``
is implemented which masks out inaccessible data, replacing it with NaN.
- Both direct-geometry and indirect-geometry are supported, by
using the appropriate argument to set incident or final neutron energy.
- This function is exposed to the ``euphonic-powder-map`` tool, so these
plots can be produced directly from the CLI.
- Some parameters from real-world instruments are collected in the
documentation for convenience.

- There is a new function ``euphonic.util.convert_fc_phases``, which converts
a force constants matrix which uses the atom coordinates in the phase
during interpolation (Phonopy-like), to one which uses the cell origin
coordinates (Euphonic, CASTEP-like).

- When importing q-point modes or frequencies from a CASTEP .phonon
file, a new option (``average_repeat_points=True``) allows
repeated entries (with the same q-point index) to be identified
and their weights divided down by the number of entries. This
option should give better statistics for sampling meshes that
include the Gamma-point with LO-TO splitting.

- Improvements:

- Documentation on the shape and format of the force constants, and how to
read them from other programs has been improved.

- The ``euphonic.util.get_qpoint_labels`` function, which is called when
importing band-structure data to identify and label significant points,
primarily identifies these points by searching for turning-points
in the band path. The function will now also pick up any q-point
that appears twice in succession. This is a common convention in
band-structure calculations and helps with edge-cases such as when
the path passes through a high-symmetry point without changing
direction. This may pick up some previously-missing points in
band-structure plots generated with ``euphonic-dispersion`` and
``euphonic-intensity-map``

- Bug fixes:

- Allow read of ``phonopy.yaml`` quantities in ``'au'`` (bohr) units.
Previously this was interpreted as an astronomical unit by Pint.

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

- Improvements:

- The ``euphonic-dos``, ``euphonic-dispersion`` and
``euphonic-intensity-map`` command-line tools can now read
files that don't contain eigenvectors, if eigenvectors are
not required for the chosen options.
- A new ``--save-json`` option is available for command-line tools
which produce plots, this will output the produced spectrum to
a Euphonic .json file.
- There is now the option to use a fast, approximate variable-width broadening method when
adaptively broadening dos:

- Added new ``adaptive_method`` and ``adaptive_error`` arguments for ``calculate_dos``
which specify which adaptive broadening method to use (``reference`` or ``fast``) and an
acceptable error level when using the ``fast`` method.
- Fast adaptive broadening can be used in the ``euphonic-dos`` tool with the
``--adaptive-method`` and ``--adaptive-error`` arguments.

- Changes:

- ``euphonic.cli.force_constants_from_file`` and ``modes_from_file``
have been deprecated in favour of ``euphonic.cli.load_data_from_file``.
- Using ``Spectrum1D/1DCollection/2D.broaden`` on an axis with unequal
bin widths is now deprecated, as broadening is performed via convolution,
which is incorrect in this case. In the future, this will raise a
``ValueError``. To broaden anyway, ``method='convolve'`` can be supplied,
which will just emit a warning.

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

- New Features:

- New ``Spectrum1D.to_text_file`` and ``Spectrum1DCollection.to_text_file``
methods to write to column text files

- An expanded and consistent set of styling options is made
available for command-line tools that produce plots.

- Consistent styling and advanced changes can be made using
Matplotlib stylesheet files, either as a CLI argument or
using ``matplotlib.style.context()`` in a Python script.

- Improvements:

- Internally, plot theming has been adjusted to rely on Matplotlib
style contexts. This means user changes and style context are more
likely to be respected.
- Additional aliases for plot arguments in the command-line tools have
been added, for example either ``--x-label`` or ``--xlabel`` can be used.

- Changes:

- ``x_label``, ``y_label``, ``y_min`` and ``y_max`` in ``euphonic.plot``
functions have been deprecated in favour of ``xlabel``, ``ylabel``,
``ymin`` and ``ymax`` respectively, to match the Matplotlib arguments
they refer to, and to match other arguments like ``vmin``, ``vmax``.

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

- Improvements:

- Wheels are now provided with PyPI releases
- Type hinting is now handled more consistently across different Euphonic
classes and functions

- Bug Fixes:

- Will no longer raise a KeyError reading from ``phonopy.yaml`` if
``physical_unit`` key is not present, instead will assume default units
- Can now read Phonopy BORN files where the (optional) NAC conversion
factor is not present

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

- Bug fixes:

- The scaling of S(Q,w) as produced by ``StructureFactor.calculate_sqw_map``
was incorrect, and did not correctly scale with energy bin size (given its
units are now ``length**2/energy``). This has been fixed, and S(Q,w) scale
has changed by a factor of (hartee to energy bin unit conversion)/(energy
bin width magnitude). e.g. if using an energy bin width of 0.1 meV, the new
S(Q,w) will be scaled by 2.72e4/0.1 = 2.72e5. The original structure factors
can now be correctly recovered by multiplying S(Q,w) by the energy bin width.