Docs update

.github/copilot-instructions.md

@@ -23,6 +23,21 @@ uv sync --all-groups
 ```
 
 
+## Building documentation
+
+Build the docs locally:
+
+```bash
+uv run --group docs sphinx-build -W -b html docs docs/_build/html
+```
+
+Output lands in `docs/_build/html/`. The `docs/examples/notebooks` and `docs/tests` symlinks are gitignored; create them once before building:
+
+```bash
+mkdir -p docs/examples && ln -sf "$(pwd)/examples/notebooks" docs/examples/notebooks
+ln -sf "$(pwd)/tests" docs/tests
+```
+
 ## Testing and validation
 
 Run unit tests:

.github/workflows/docs.yml

@@ -35,8 +35,14 @@ jobs:
       - name: Install package and documentation dependencies
         run: uv sync --frozen --group docs
 
+      - name: Create documentation symlinks
+        run: |
+          mkdir -p docs/examples
+          ln -sf "$(pwd)/examples/notebooks" docs/examples/notebooks
+          ln -sf "$(pwd)/tests" docs/tests
+
       - name: Build documentation
-        run: uv run --group docs sphinx-build -W -b html -c docs . docs/_build/html
+        run: uv run --group docs sphinx-build -W -b html docs docs/_build/html
 
       - name: Configure GitHub Pages
         if: github.event_name != 'pull_request'

.gitignore

@@ -79,6 +79,9 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/jupyter_execute/
+docs/examples/notebooks
+docs/tests
 
 # PyBuilder
 .pybuilder/

README.md

@@ -19,7 +19,13 @@ Give your nuclear reaction UQ workflow a caffeine-kick with jitr!
 
 ## Documentation
 
-The documentation site is available at <https://beykyle.github.io/jitr/>. 
+The documentation site is available at <https://beykyle.github.io/jitr/>.
+
+To build the docs locally:
+
+```bash
+uv run --group docs sphinx-build -W -b html docs docs/_build/html
+```
 
 ## Installation and Development
 

docs/api/folding.md

@@ -4,10 +4,6 @@ The folding page documents the finite-range folding helpers and JLM/JLMB
 parameterizations. The reusable analytic/tabulated density helpers live in
 `jitr.utils.density` and are documented on the core API page.
 
-```{eval-rst}
-.. automodule:: jitr.folding
-   :members:
-```
 
 ## Quadrature and folding helpers
 

docs/conf.py

@@ -43,9 +43,10 @@
     "**/.pytest_cache",
     "build",
     "dist",
-    "docs/_build",
-    "docs/_build/**",
-    "docs/index.md",
+    "_build",
+    "_build/**",
+    "jupyter_execute",
+    "jupyter_execute/**",
     "CHANGELOG.rst",
     "README.md",
     "SUPPORT.rst",

docs/examples/index.md

@@ -12,37 +12,42 @@
 /examples/notebooks/reaction
 /examples/notebooks/example_jlm
 /examples/notebooks/builtin_omps_uq
-/examples/notebooks/kduq_uq_demo
-/examples/notebooks/local_omp_demo
-/examples/notebooks/angular_reaction_xs
 /examples/notebooks/tabulated_density_demo
-/examples/notebooks/dispersive_optical_model
-/examples/notebooks/mass_exploration
 /examples/notebooks/chuq_kduq_comp
 /examples/notebooks/volume_integrals
 /examples/notebooks/convergence_channel_radius
+/examples/notebooks/dispersive_optical_model
+/examples/notebooks/kduq_uq_demo
+/examples/notebooks/local_omp_demo
+/examples/notebooks/angular_reaction_xs
+/examples/notebooks/mass_exploration
 ```
 
 
 ## Start here
 
-- [quickstart](/examples/notebooks/quickstart)
+- [Quickstart](/examples/notebooks/quickstart)
   gives a full end-to-end example for compiling a solver for a given reaction system, defining a parametric interaction potential, and calculating an elastic scattering cross section for an ensemble of potential parameters.
 - [Reactions and kinematics](/examples/notebooks/reaction)
   introduces the `Reaction` class and shows how to use it to store useful information about the reaction of interest, and how to use it to compute kinematic quantities.
 
-## Full "batteries included" example:
+
+
+## Other useful examples
 
 - [JLM and JLMB semi-microscopic optical-potentials](/examples/notebooks/example_jlm)
   converts the original JLM example into a notebook and walks through folded
   microscopic potentials, Lane trends, and tabulated self-energy usage.
 - [Compare built-in uncertainty-quantified optical potentials](/examples/notebooks/builtin_omps_uq)
   walks through posterior sampling, solver setup, and interval construction 
   for several of the built-in uncertainty quantified optical potentials in `jitr`.
-
-## Other useful examples
-
-- [Tabulated density usage](/examples/notebooks/tabulated_density_demo)
+- [Tabulated neutron and proton densities](/examples/notebooks/tabulated_density_demo)
+- [Compare global optical-potential radial forms](/examples/notebooks/chuq_kduq_comp)
+  provides a quick visual comparison of the radial forms of the built-in global potentials in `jitr`.
+- [Visualize global optical potential volume integrals](/examples/notebooks/volume_integrals)
+  shows how to compute and visualize volume integrals for the built-in global optical potentials in `jitr`.
+- [Channel-radius convergence study for elastic scattering](/examples/notebooks/convergence_channel_radius)
+  shows how to check for numerical convergence in realistic calculations.
   shows how to grab the tabulated nuclear densities in `jitr`.
 - [Dispersive optical model](/examples/notebooks/dispersive_optical_model)
   shows how to use the built-in dispersive optical model in `jitr`
@@ -54,9 +59,3 @@
   performs uncertainty quantification for partial wave transmission coefficients
 - [Mass-model effects on transmission-coefficient uncertainty](/examples/notebooks/mass_exploration)
   explores how mass-model choices propagate into transmission coefficients.
-- [Compare global optical-potential radial forms](/examples/notebooks/chuq_kduq_comp)
-  provides a quick visual comparison of the radial forms of the built-in global potentials in `jitr`.
-- [Visualize global optical potential volume integrals](/examples/notebooks/volume_integrals)
-  shows how to compute and visualize volume integrals for the built-in global optical potentials in `jitr`.
-- [Channel-radius convergence study for elastic scattering](/examples/notebooks/convergence_channel_radius)
-  shows how to check for numerical convergence in realistic calculations.

docs/getting-started.md

@@ -39,135 +39,10 @@ Browse the curated [example notebooks](examples/index.md).
 
 ### Quick start
 
-Here is full end-to-end example for 
-- compiling a solver for a given reaction system
+The [quickstart example](/examples/notebooks/quickstart) gives a full end-to-end walk-through afor:
+- compiling a solver for a given reaction system ($\alpha$ + $^{48}$Ca)
 - defining a parametric interaction potential
-- calculating an elastic scattering cross section for an ensemble of potential parameters
-
-This is adapted from the [quickstart example](/examples/notebooks/quickstart). 
-```python
-import numpy as np
-from matplotlib import pyplot as plt
-from scipy import stats
-from tqdm import tqdm
-
-from jitr.optical_potentials.potential_forms import (
-    coulomb_charged_sphere as coulomb,
-    woods_saxon_safe as ws,
-)
-from jitr.reactions.reaction import Reaction
-from jitr.rmatrix import Solver as SolverKernel
-from jitr.utils import utils
-from jitr.xs import elastic
-
-# define reaction system
-alpha = (4, 2)
-Ca48 = (48, 20)
-reaction = Reaction(target=Ca48, projectile=alpha, process="El")
-
-# calculate kinematics for a given lab energy
-energy_lab = 28.2
-kinematics = reaction.kinematics(energy_lab)
-
-# set the channel radius, number of nodes, and number of partial waves
-interaction_range_fm = 1.2 * (48 ** (1 / 3) + 4 ** (1 / 3)) + 2
-channel_radius_dimensionless = utils.suggested_dimensionless_channel_radius(
-    interaction_range_fm, kinematics.k
-)
-channel_radius = channel_radius_dimensionless / kinematics.k
-N = utils.suggested_basis_size(channel_radius_dimensionless)
-lmax = 180
-
-# build a solver for the system and reaction of interest
-print(f"Compiling solver for {reaction} at {energy_lab} MeV")
-print(f" - channel radius {channel_radius:1.2f} fm")
-print(f" - {N} nodes")
-print(f" - {lmax} partial waves")
-
-solver = elastic.DifferentialWorkspace.build_from_system(
-    reaction=reaction,
-    kinematics=kinematics,
-    channel_radius_fm=channel_radius,
-    solver=SolverKernel(N),
-    lmax=lmax,
-    angles=np.linspace(0.1, np.pi, 180),
-)
-rgrid = solver.radial_grid()
-# jit warmup
-_ = solver.xs(central_potential=np.zeros_like(solver.radial_grid()))
-print("Done!")
-```
-
-```
-Compiling solver for 48-Ca(alpha,el) at 28.2 MeV
- - channel radius 11.19 fm
- - 40 nodes
- - 180 partial waves
-Done!
-```
-
-```python
-# define interaction
-def U_central(r, Vv, Wv, Rv, av):
-    fr = ws(r, Rv, av)
-    return -(Vv * fr + 1j * Wv * fr)
-
-
-def V_Coulomb(r, Zz, RC):
-    return coulomb(r, Zz, RC)
-
-
-# define parameter distribution and draw samples
-# just
-param_means = np.array([185, 20, 1.0, 0.6, 1.2])
-param_std_devs = np.array([6, 2, 0.05, 0.05, 0.01])
-num_samples = 1000
-param_draws = stats.multivariate_normal(
-    mean=param_means, cov=np.diag(param_std_devs) ** 2
-).rvs(num_samples)
-
-print(f"Running {num_samples} calculations...")
-prediction_samples = np.zeros((num_samples, solver.angles.size))
-for i in tqdm(range(param_draws.shape[0])):
-    Vv, Wv, rv, av, rC = param_draws[i]
-    A_factor = reaction.target.A ** (1 / 3) + reaction.projectile.A ** (1 / 3)
-    Zz = reaction.target.Z * reaction.projectile.Z
-    xs = solver.xs(
-        central_potential=U_central(
-            rgrid, Vv, Wv, rv * A_factor, av, 
-        ),
-        coulomb_potential=V_Coulomb(rgrid, Zz, rC * A_factor),
-    )
-    prediction_samples[i, :] = xs.dsdo / solver.rutherford
-
-print("Done!")
-```
-
-```
-Running 1000 calculations...
-
-100%|██████████████████████████████████████████████████████████| 1000/1000 [00:05<00:00, 168.00it/s]
-
-Done!
-
-```
-
-```python
-plt.figure()
-plt.fill_between(
-    np.rad2deg(solver.angles),
-    *np.percentile(prediction_samples, [16, 84], axis=0),
-    alpha=0.5,
-)
-plt.yscale("log")
-plt.xlabel(r"$\theta$ [deg]")
-plt.ylabel(r"$(\frac{d\sigma}{d\Omega}) / (\frac{d\sigma}{d\Omega})_{R}$")
-plt.title(f"${reaction.reaction_latex}$ at {kinematics.Elab:1.0f} MeV")
-plt.tight_layout()
-plt.show()
-```
-
-See the [quickstart example](/examples/notebooks/quickstart) for more details and the results of this calculation!
+- fitting and full Bayesian calibration of the potential parameters to real experimental data
 
 ## API reference and development