Abins dev docs: move to Concepts, take advantage of plot:: RST magic

To avoid polluting the dev-docs with algorithm-specific info and to
avoid storing/updating many image files the Abins development notes
are moved back into Concepts. The fast broadening method is broken
into a separate document to avoid too much wading through plots.

docs/source/algorithms/Abins-v1.rst

@@ -45,6 +45,7 @@ More information about the implemented working equations can be found :ref:`here
 
 Abins is in constant development and suggestions for improvements are very welcome. For any such contributions please
 contact Dr. Sanghamitra Mukhopadhyay (sanghamitra.mukhopadhyay@stfc.ac.uk).
+If you are developing or hacking on Abins, see the :ref:`AbinsImplementation` notes which outline some of the key conventions, practices and pitfalls.
 
 If Abins is used as part of your data analysis routines, please cite the relevant reference [1]_.
 

docs/source/concepts/AbinsImplementation.rst

+.. _AbinsImplementation:
+
+Abins: Implementation details
+=============================
+
+.. contents::
+
+
+Introduction
+------------
+
+Abins is a relatively complex algorithm with some unique
+infrastructure and built-in design decisions. Details are collected
+here: this is primarily for the benefit of those developing or
+hacking Abins.
+
+
+Deprecation plans
+-----------------
+
+- The *pkt_per_peak* and *fwhm* parameters in
+  ``AbinsParameters.sampling`` are no longer in use and should be
+  removed in a future release.
+
+- The "SingleCrystal" modules and objects support non-existent
+  functionality and should be removed. They may return when that
+  functionality is added, but it is likely that their interfaces will
+  change in the process.
+
+- The *frequencies_threshold* parameter in
+  ``AbinsParameters.sampling`` is currently non-functional and should
+  be removed until it *is* functional.
+
+
+Sampling
+--------
+
+While the scattering cross-sections are calculated for individual
+events and enumerated combinations of events, the output spectra are
+histograms which have been resampled and broadened on a finite grid.
+
+The data range is determined by three parameters:
+
+- *min_wavenumber*, set in ``AbinsParameters.sampling``
+- *max_wavenumber*, set in ``AbinsParameters.sampling``
+- *bin_width*, a parameter set in the main Abins algorithm interface
+  and passed as an argument to internal functions as appropriate. This
+  parameter is more exposed than the energy range, as a convenient to
+  the user. However, it should be applied consistently within a single
+  application of Abins and functions may assume that this value was
+  also used elsewhere.
+
+These parameters are used to establish the edges of the sample *bins*;
+the largest value is rounded up from *max_wavenumber* to contain a
+whole number of *bin_width*.
+
+The histogram of data sampled in these N bins has N-1 "points", which
+should be aligned with the corresponding bin centres if plotted as a
+line. In the code this array of frequency coordinates is generally
+named _freq_points_.
+
+Broadening
+----------
+
+Instrumental broadening in Abins involves an energy-dependent
+resolution function; in the implemented case (the TOSCA instrument)
+this is convolution with a Gaussian kernel with the energy-dependent
+width parameter (sigma) determined by a quadratic polynomial.
+Convolution with a varying kernel is not a common operation and is
+implemented within AbinsModules.
+
+Earlier versions of Abins implemented a Gaussian kernel with a
+fixed number of points spread over a range scaled to the peak width,
+set by *pkt_per_peak* and *fwhm* parameters in
+``AbinsParameters.sampling``.
+This method leads to aliasing when the x-coordinates are
+incommensurate with the histogram spacing, and an uneven number of
+samples falls into each bin.
+
+.. image:: ../images/gaussian_aliasing.png
+    :align: center
+
+The safest way to avoid such trouble is for all broadening methods to
+output onto the regular _freq_points_ grid. A number of broadening
+implementations have been provided in
+_AbinsModules.Instruments.Broadening_. It is up to the Instrument
+logic to dispatch broadening calls to the requested implementation,
+and it is up to specific Instruments to select an appropriate scheme
+for their needs.
+The advanced parameter *AbinsParameters.sampling['broadening_scheme']*
+is made available so that this can be overruled, but it is up to the
+Instrument to interpret this information. 'auto' should select an
+intelligent scheme and inappropriate methods can be forbidden.
+
+A fast, possibly-novel method of frequency-dependent broadening has been implemented as the 'interpolate' method. For notes on this method and its limitations see  :ref:`AbinsInterpolatedBroadening`.
+
+.. categories:: Concepts