Some obvious places for further improvement:

- Access from CLI interface
- Optimise for use with multiple data series (i.e. for
  Spectrum1DCollection and Spectrum2D we don't need to keep
  recalculating the adaptive broadening parameters.)
- Lorentzians?
- Exact broadening?

But this is enough to play with and open discussion about API.

This is expected to evolve as implementation/API are tweaked, but
makes a good sanity check as we go.

There seem to be two y-axis conventions at work; for "sparse" data
that has not been binned, the weights indicate a symmetry weighting or
possible neutron scattering intensity. For data in a spectrum, there
is also a weight for the bin width to compensate for bin-size effects.

The variable-width broadening machinery currently expects the
former (which makes sense for adaptive DOS broadening) and converts to
the latter (which is the expected form for spectrum
objects). Broadening _from_ a spectrum object therefore needs to
account for this.

Figure out which versions of the random generators both
a) work
b) don't raise deprecation warnings

for our range of supported numpy versions.

What's especially annoying is that RandomState isn't even the current
recommended way of doing this; according to Numpy docs the
best-practice is now `rng = np.random.default_rng(seed)`, with the
resulting Generator providing random() and integers() methods.

But that doesn't exist in older versions, so we'll probably want to
migrate this in future.

Requiring a special Tuple is a _tiny_ bit awkward, but it's easier
than defining a Class for the same information!

The unit handling is extra-clunky to handle the minimum dependencies;
newer numpy/Pint combinations allow a lot more Numpy functions to be
applied directly on Quantity objects.

For now we have a new method on Spectrum1D, this might get refactored.

A lot of Numpy functions strip units from Quantites or otherwise
misbehave up to version 1.16, whereas with 1.17 and later these
function calls can be much cleaner. Unintuitively, this is linked more
to the Numpy version than the Pint version.

While getting things working, refactor to pure functions.

Results look good and don't seem horribly slow

- Polynomial broadening not included yet; just use the first width
  value

- Current API is too ambiguous, sometimes we want to layer adaptive
  and instrumental broadening. Solve this by

  - Introducing explicit --adaptive-scale and --instrument-broadening,
    with existing --energy-broadening dispatching as appropriate

  - Over subsequent major versions --energy-broadening can become
    a simple alias to --instrument-broadening and
    --instrument-broadening can be dropped.

- Where Gaussian broadening is applied on top of adaptive broadening,
  do this efficiently by calculating appropriate widths and apply once.

Changing energy-broadening to nargs='?' results in a list and broke
energy broadening in all CLI programs. These will soon be updated to
use all values; for now just take the first as width.

An interesting problem is that if we try to use the width-dependent
broadening function for fixed-width, the results don't quite agree.
It's not a big problem to avoid this, and probably more efficient.
But it's weird, shouldn't it just create two kernels, align one of
them to the exact width and then mix the results to 100% "lower"?
Is it the actual convolution implementation giving different
results (e.g. due to re-binning?)

Part of migration to more open-ended API

The (tested) polynomial width functions are now thin wrappers around
more general width-function based broadeners

Differences are of order 1e-12 so not deeply concerning. It would be
good to know exactly where they come from, though...

- Remove resulting circular import from euphonic.broadening. It's a
  little messy for now but will be ok when the Spectrum broadening
  functions are removed.

- Refactor bin width checks to a Spectrum method. We gain some lines
  of code but should keep logic a bit clearer.

- Feels natural to make this an assertion but currently we just raise
  a warning so this needs wrapping.

- cli.dos now a bit cleaner, just calls broaden() method either way

- 1D sanity check moved from broadening tests to spectrum tests

The low-level variable broadening function still lives there, but
Spectrum1D(Collection)-specific details can exist as methods only.

- This is a touch messier to handle the various permutations of x and
  y broadening; bring in a whole private staticmethod that operates on
  Spectrum2D.
- Further streamlining certainly possible, but maybe it can wait until
  we implement 2-D covariance input (xy_width)
- Another general streamlining approach would be to somehow ditch the
  fixed-width broadening implementation and make the variable-width
  work efficiently and accurately with fixed-width inputs

- New parametrisation for Lorentzian width/error relationship
- We may want to look at the Gaussian one too, it seems to
  overestimate acceptable spacing for lowest error range.
- Lorentzian gamma _is_ FWHM and std seems to be undefined for this
  function!

Currently width "1 0 0" gives a wider broadening than "1" so something
is being scaled inappropriately somewhere...

- missing shape argument was causing a factor of ~2 (for Gaussian
  FWHM/sigma)

This combination of arguments is now allowed!

Slightly concerning that the test hangs on my machine rather than fail
cleanly, but anyway it seems ok on CI and I suppose a crash is better
than a false Pass...

The existing scheme truncates the Lorentzian function to 3
sigma. However, truncating Lorentzians is a poor way of making them
more efficient as the tails die away very slowly. Other approaches are
available, but for now it is safest if this exact implementation
always evaluates the kernel over twice the bin range. This guarantees
no truncation.

For similar reasons the numerical normalisation might not be the best
idea. It may be more correct for a long tail to carry intensity out of
the plot range and reduce the overall visible magnitude. It doesn't
really cost more to calculate the theoretical normalisation constant,
so let's use that instead.

Lorentzian kernels now calculated over full bin range, so every y
value has changed in the affected data.

Plot posted to Github PR, looks like a small change.

Inspecting the 1D data we can see that blocks of zeros (outside
truncation range) now contain data.

- range cutoff has been eliminated, changing results

This is not ideal; in the case of very large broadening it will tend
to overestimate peak intensities. However, evaluating the kernel with
"correct" scaling derived from bin widths can drastically overestimate
peak heights at narrow broadening width.

There are better ways of doing this; the width range can be
constrained, or histogram integrals can be worked out
properly. However, this is not generally done and can lead to results
that look strange compared to other implementations (including the
Scipy Gaussian broadening) that use simple normalisation. Hopefully we
can revisit this some time.

- Although we have reverted to normalised kernels, increasing the
  calculation range has slightly changed the normalisation magnitude

It's quite common for band structure calcs to end up with slightly
mismatched q-sampling segments, so we allow it until a better option
is made available.

The kernel range has slightly changed, which in turn affects
normalisation. When plotted, the change to the test example is indistinguishable.

Justification same as 1d. The differences are actually a little bit
larger in these cases, with a max of around 2%. Visually we can see
nothing too wacky is happening.

In this data we can clearly see how the extended tail replaces zeros
that previous lay outside the truncation region.

Accept multiple arguments and try to set up polynomials.
- Have checked that this doesn't break existing
- Initial manual checks also look ok

Test files a bit big but makes them easy to visually debug.

Error messages were very confusing and misleading, suggesting that
there were problems with defining and importing things. Actually it
was just normal problems...

For new broadening methods we default to the new Chebyshev-log(energy)
fits. But test data is for the old cubic fit... First we make sure
that the option to select method is still working and existing tests pass.

This logic case only applies when there is no adaptive broadening, so
backward compabibility is not an issue.

Very few changes needed! Most tests are for self-consistency or
against exact broadening. Added one new reference dataset for
spectrum2d.

Slight correction to cheby-log parametrisation gives slight difference in corresponding test ref

The safe range for cheby-log fit is a bit smaller than the data range;
it goes a bit crazy at the lowest two points!