Add Sphinx documentation for ReadTheDocs hosting

.gitignore

@@ -6,3 +6,4 @@ dist/
 .vscode/
 
 notebook/
+docs/_build/

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,72 @@
+API Reference
+=============
+
+This page documents the public API of NeSST. The main entry point is:
+
+.. code-block:: python
+
+   import NeSST as nst
+
+Core Module
+-----------
+
+.. automodule:: NeSST.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Fitting Module
+--------------
+
+.. automodule:: NeSST.fitting
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Time-of-Flight Module
+---------------------
+
+.. automodule:: NeSST.time_of_flight
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Constants
+---------
+
+.. automodule:: NeSST.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Utilities
+---------
+
+.. automodule:: NeSST.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Spectral Model
+--------------
+
+.. automodule:: NeSST.spectral_model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Collisions
+----------
+
+.. automodule:: NeSST.collisions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ENDF Interface
+--------------
+
+.. automodule:: NeSST.endf_interface
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -0,0 +1,64 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "NeSST"
+copyright = "2024, Aidan Crilly"
+author = "Aidan Crilly"
+
+version = "1.1.2"
+release = "1.1.2"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "myst_parser",
+    "nbsphinx",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+language = "en"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+# -- Napoleon settings -------------------------------------------------------
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = True
+
+# -- Intersphinx mapping -----------------------------------------------------
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+}
+
+# -- Autodoc settings --------------------------------------------------------
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": False,
+    "show-inheritance": True,
+}
+
+# -- nbsphinx settings -------------------------------------------------------
+nbsphinx_execute = "never"

docs/example_notebook.rst

@@ -0,0 +1,17 @@
+Example Notebook
+================
+
+A Jupyter notebook guide to NeSST is available in the ``example/`` directory of the
+`GitHub repository <https://github.com/aidancrilly/NeSST>`_.
+
+The notebook covers:
+
+- Setting up energy grids and scattering matrices
+- Computing primary neutron spectra (DT, DD, TT)
+- Calculating singly-scattered neutron spectra
+- Applying areal density asymmetry effects
+- Using ion kinematics corrections
+- Synthetic neutron time-of-flight detector signals
+
+You can `view the notebook interactively on nbviewer
+<https://nbviewer.org/github/aidancrilly/NeSST/blob/master/example/NeSST%20Guide.ipynb>`_.

docs/guide.rst

@@ -0,0 +1,195 @@
+User Guide
+==========
+
+This guide gives an overview of NeSST's main features and how to use them.
+
+Quick Start
+-----------
+
+.. code-block:: python
+
+   import NeSST as nst
+   import numpy as np
+
+Primary Spectra
+---------------
+
+NeSST provides models for primary neutron spectra from DT, DD and TT fusion reactions.
+
+Spectral Moments (Ballabio Fits)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The mean energy and variance of the primary neutron spectrum can be calculated using
+Ballabio fits (`Ballabio et al. 1998, Nucl. Fusion 38 1723 <https://doi.org/10.1088/0029-5515/38/11/310>`_):
+
+.. code-block:: python
+
+   Tion = 3000  # ion temperature in eV (3 keV)
+
+   # DT primary spectrum moments
+   mean_DT, stddev_DT, variance_DT = nst.DTprimspecmoments(Tion)
+
+   # DD primary spectrum moments
+   mean_DD, stddev_DD, variance_DD = nst.DDprimspecmoments(Tion)
+
+Primary Spectral Shapes
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Two shapes are available for the primary spectrum:
+
+- **Brysk (Gaussian)**: :func:`~NeSST.core.QBrysk`
+- **Ballabio (modified Gaussian)**: :func:`~NeSST.core.QBallabio`
+
+.. code-block:: python
+
+   Ein = np.linspace(10e6, 18e6, 1000)  # energy array in eV
+   mean, _, variance = nst.DTprimspecmoments(Tion)
+
+   # Brysk (Gaussian) shape
+   I_E = nst.QBrysk(Ein, mean, variance)
+
+   # Ballabio (modified Gaussian) shape
+   I_E = nst.QBallabio(Ein, mean, variance)
+
+Yields and Reactivities
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Yield ratios between reactions can be estimated from reactivities:
+
+.. code-block:: python
+
+   dt_yield = 1e15
+   # DD yield predicted from DT yield
+   dd_yield = nst.yield_from_dt_yield_ratio("dd", dt_yield, Tion)
+   # TT yield predicted from DT yield
+   tt_yield = nst.yield_from_dt_yield_ratio("tt", dt_yield, Tion)
+
+Scattered Spectra
+-----------------
+
+The main feature of NeSST is calculating the singly-scattered neutron spectrum.
+
+Setting Up Energy Grids and Scattering Matrices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before computing scattered spectra, energy grids and scattering matrices must be initialised:
+
+.. code-block:: python
+
+   # Define energy grids
+   Eout = np.linspace(10e6, 16e6, 500)   # outgoing energy grid (eV)
+   Ein  = np.linspace(12e6, 16e6, 500)   # incoming energy grid (eV)
+
+   # Initialise DT scattering matrices
+   nst.init_DT_scatter(Eout, Ein)
+
+Symmetric (Isotropic) Areal Density
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For a spherically symmetric implosion:
+
+.. code-block:: python
+
+   I_E = nst.QBrysk(Ein, mean, variance)
+   total_spec, (nD, nT, Dn2n, Tn2n) = nst.DT_sym_scatter_spec(I_E)
+
+Asymmetric Areal Density
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For an asymmetric (anisotropic) areal density distribution:
+
+.. code-block:: python
+
+   # rhoL_func must be a function of cos(theta), normalised such that
+   # the integral over the sphere equals 1
+   rhoL_func = lambda x: np.ones_like(x)  # isotropic example
+
+   total_spec, components = nst.DT_asym_scatter_spec(I_E, rhoL_func)
+
+Ion Kinematics
+~~~~~~~~~~~~~~
+
+The effect of scattering ion velocities can be included:
+
+.. code-block:: python
+
+   # Ion velocity array
+   varr = np.linspace(-3e5, 3e5, 51)  # velocities in m/s
+
+   # Initialise scattering matrices with ion kinematics
+   nst.init_DT_ionkin_scatter(varr, nT=True, nD=True)
+
+Transmission
+------------
+
+The straight-line transmission of primary neutrons through the DT fuel can be calculated:
+
+.. code-block:: python
+
+   rhoL = 0.2    # areal density in kg/m^2
+   rhoL_func = lambda x: np.ones_like(x)
+
+   transmission = nst.DT_transmission(rhoL, Ein, rhoL_func)
+
+Areal Density Conversion
+------------------------
+
+Helper functions are provided to convert between areal density and scattering amplitude:
+
+.. code-block:: python
+
+   A_1S = nst.rhoR_2_A1s(rhoL)   # areal density -> scattering amplitude
+   rhoL = nst.A1s_2_rhoR(A_1S)   # scattering amplitude -> areal density
+
+Fitting Models
+--------------
+
+The :class:`~NeSST.fitting.DT_fit_function` class provides pre-built models for fitting
+experimental data:
+
+.. code-block:: python
+
+   E_DTspec = np.linspace(12e6, 16e6, 500)
+   E_sspec  = np.linspace(10e6, 16e6, 500)
+
+   fit = nst.DT_fit_function(E_DTspec, E_sspec)
+   fit.set_primary_Tion(Tion)
+   fit.init_symmetric_model()
+
+   # fit.model is a callable for use with scipy.optimize.curve_fit etc.
+
+Neutron Time-of-Flight (nToF)
+-----------------------------
+
+Synthetic nToF detector signals can be generated using the :class:`~NeSST.time_of_flight.nToF` class:
+
+.. code-block:: python
+
+   from NeSST.time_of_flight import nToF, get_unity_sensitivity, get_transit_time_tophat_IRF
+
+   distance = 3.0          # distance to detector in meters
+   sensitivity = get_unity_sensitivity()
+   IRF = get_transit_time_tophat_IRF(scintillator_thickness=0.01)
+
+   detector = nToF(distance, sensitivity, IRF)
+   t, t_norm, signal = detector.get_signal(Ein, I_E)
+
+Materials
+---------
+
+In addition to the default D and T materials, other materials can be initialised:
+
+.. code-block:: python
+
+   # Available by default: H, D, T, C12, Be9
+   mat = nst.init_mat_scatter(Eout, Ein, "C12")
+   rhoL_func = lambda x: np.ones_like(x)
+   spec = nst.mat_scatter_spec(mat, I_E, rhoL_func)
+
+Publications
+------------
+
+The models used in NeSST are described in:
+
+- A. Crilly et al., *The effect of areal density asymmetries on scattered neutron spectra in ICF implosions*, Physics of Plasmas, 2021
+- A. Crilly et al., *Neutron backscatter edge: A measure of the hydrodynamic properties of the dense DT fuel at stagnation in ICF experiments*, Physics of Plasmas, 2020