Update notebooks (fixing kernel issue), and polish associated docs

.github/workflows/python-package.yml

@@ -58,7 +58,7 @@ jobs:
       - name: Run notebook tests
         env:
           JITR_QUICK: "1"  # cut-down version of the calibration notebooks
-        run: uv run --group examples pytest --nbval-lax --current-env examples/notebooks/
+        run: uv run --group examples pytest --nbval-lax --nbval-current-env examples/notebooks/
 
       - name: Build package
         run: uv build

README.md

@@ -21,129 +21,33 @@ Give your nuclear reaction UQ workflow a caffeine-kick with jitr!
 
 The documentation site is available at <https://beykyle.github.io/jitr/>.
 
-To build the docs locally:
+Check out the [getting started page](https://beykyle.github.io/jitr/getting-started.html) for an overview of the package and quickstart tutorials.
 
-```bash
-uv run --group docs sphinx-build -W -b html docs docs/_build/html
-```
-
-## Installation and Development
-
-### For users
+Check out the [tutorials and examples page](https://beykyle.github.io/jitr/examples/index.html) for a full list of example notebooks and demos.
 
-Install the latest released version of `jitr` from PyPI:
+## Installation
 
 ```bash
 pip install jitr
 ```
 
-Then use it in Python:
-
-```python
-import jitr
-```
-
-To check the installed version:
-
-```bash
-python -c "import jitr; print(jitr.__version__)"
-```
-
-If you use `uv`, you can add `jitr` to a uv-managed project with:
-
-```bash
-uv add jitr
-```
-
-Or install it into the current environment with:
-
-```bash
-uv pip install jitr
-```
-
-### For developers
-
-This repository uses [`uv`](https://docs.astral.sh/uv/) for Python packaging, dependency management, virtual environments, and locking.
-
-#### Clone the repository
-
-```bash
-git clone https://github.com/beykyle/jitr.git
-cd jitr
-```
-
-#### Create and sync the development environment
-
-Install all development dependencies:
-
-```bash
-uv sync --all-groups
-```
-
-This creates a local `.venv/` environment and installs the package in editable mode along with the development and example dependencies defined in `pyproject.toml`.
-
-You can run commands through `uv`:
-
-```bash
-uv run python
-uv run pytest
-```
-
-Or activate the environment manually:
-
-```bash
-source .venv/bin/activate
-```
-
-## Testing
+For `uv` users and other install options, see [Installation](https://beykyle.github.io/jitr/getting-started.html#installation).
 
-### Run the unit tests
-
-```bash
-uv run pytest
-```
-
-### Run the notebook tests
-
-The example notebooks are tested with `pytest` and `nbval`:
-
-```bash
-uv run --group examples pytest --nbval-lax examples/notebooks/
-```
+## Development and testing
 
+- [Development environment](https://beykyle.github.io/jitr/advanced-users.html#development-environment): cloning the repo, syncing the uv-managed environment, and linting.
+- [Tests](https://beykyle.github.io/jitr/tests.html): running the unit, notebook, and regression tests.
+- [Building the docs](https://beykyle.github.io/jitr/advanced-users.html#building-the-docs): building this documentation site locally.
 
 ## Tutorials
 
-Tutorials live in [`examples/notebooks/`](https://github.com/beykyle/jitr/tree/main/examples/notebooks). Currently, the best way to run the notebooks is by cloning the repo and running them with the uv-managed environment as the kernel. This way, you can be sure that all the dependencies are correct and that the notebooks will run as expected.
-
-There are some additional requirements to run the examples. Once you've cloned the repo, from the main directory, run:
-
-```
-uv sync --group examples
-```
-
-Then, register the project environment as a Jupyter kernel:
-
-```
-uv run python -m ipykernel install --user --name jitr --display-name "Python (jitr)"
-```
-
-and start a Jupyter-lab server:
-
-```
-uv run --with jupyter jupyter lab
-```
-
-In JupyterLab, select the `Python (jitr)` kernel. Notebooks using this kernel will run against the uv-managed `.venv/` environment.
-
-Then, you can run the notebooks.
+Tutorials live in [`examples/notebooks/`](./examples/notebooks). See [Examples and tutorials](https://beykyle.github.io/jitr/getting-started.html#examples-and-tutorials) for how to run them locally, and the [examples page](https://beykyle.github.io/jitr/examples/index.html) for an annotated list.
 
 ## BAND
 
-This package is part of the [BAND Framework](https://github.com/bandframework/)
-
+This package is part of the [BAND Framework](https://bandframework.github.io/).
 
-## citations
+## Citations
 
 Please consider citing both this package and the BAND Framework if you use this code in your research. The BibTeX entries are:
 

docs/advanced-users.md

@@ -2,36 +2,56 @@
 
 ## Development environment
 
-This repository uses `uv` for dependency management and local
-environments.
+This repository uses [`uv`](https://docs.astral.sh/uv/) for Python packaging,
+dependency management, virtual environments, and locking.
+
+Clone the repository and install the full development environment:
 
 ```bash
+git clone https://github.com/beykyle/jitr.git
+cd jitr
 uv sync --all-groups
 ```
 
-Common validation commands:
+This creates a local `.venv/` environment and installs the package in
+editable mode together with the test, lint, docs, and example dependencies
+defined in `pyproject.toml`.
+
+You can run commands through `uv`:
 
 ```bash
+uv run python
 uv run pytest
-uv run --group examples pytest --nbval-lax examples/notebooks/
+```
+
+Or activate the environment manually:
+
+```bash
+source .venv/bin/activate
+```
+
+### Linting and type checking
+
+```bash
 uv run ruff check .
 uv run black --check .
 uv run flake8 src tests
 uv run mypy src
 ```
 
+Test commands are documented on the [Tests](tests.md) page.
+
 ## Building the docs
 
 The documentation site is built with Sphinx and MyST-NB. From the
 repository root, run:
 
 ```bash
-uv run --group docs sphinx-build -W -b html -c docs . docs/_build/html
+uv run --group docs sphinx-build -W -b html docs docs/_build/html
 ```
 
-That build uses the repository root as the Sphinx source directory, so
-published notebooks can be linked directly from `examples/notebooks/`
-without copying them into `docs/`.
+The notebooks rendered on the site are copies of the ones in
+`examples/notebooks/`, kept under `docs/examples/notebooks/`.
 
 ## Contributing
 

docs/examples/index.md

@@ -48,6 +48,7 @@
   walks through posterior sampling, solver setup, and interval construction 
   for several of the built-in uncertainty quantified optical potentials in `jitr`.
 - [Tabulated neutron and proton densities](/examples/notebooks/tabulated_density_demo)
+  shows how to grab the tabulated nuclear densities in `jitr`.
 - [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.
@@ -57,7 +58,6 @@
   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`
 - [UQ demo with Koning-Delaroche potential](/examples/notebooks/kduq_uq_demo) 

docs/getting-started.md

@@ -33,9 +33,35 @@ If you use `uv`, add it to an existing project with:
 uv add jitr
 ```
 
+or install it into the current environment with:
+
+```bash
+uv pip install jitr
+```
+
+To check the installed version:
+
+```bash
+python -c "import jitr; print(jitr.__version__)"
+```
+
 ## Examples and tutorials
 
-Browse the curated [example notebooks](examples/index.md).
+Tutorials live in [`examples/notebooks/`](https://github.com/beykyle/jitr/tree/main/examples/notebooks) in the repository, and rendered copies are listed on the [examples page](examples/index.md). The best way to run them is to clone the repo and open them with the default `Python 3 (ipykernel)` kernel, which lives inside the uv-managed environment. This way, you can be sure that all the dependencies are correct and that the notebooks will run as expected. No kernel registration is needed.
+
+There are some additional requirements to run the examples. Once you've cloned the repo, from the main directory, run:
+
+```
+uv sync --group examples
+```
+
+and start a JupyterLab server from the same directory:
+
+```
+uv run --group examples jupyter lab
+```
+
+Then, you can run the notebooks.
 
 ### Quick start
 
@@ -56,7 +82,7 @@ For development setup, test commands, and documentation builds, see
 
 ## BAND
 
-`jitr` is one of the siftware packages included in the [BAND Framework](https://bandframework.github.io/).
+`jitr` is one of the software packages included in the [BAND Framework](https://bandframework.github.io/).
 
 ## Citations
 

docs/tests.md

@@ -10,30 +10,8 @@ regression-tests
 
 ## Set up the development environment
 
-Clone the repository and install the full development environment:
-
-```bash
-git clone https://github.com/beykyle/jitr.git
-cd jitr
-uv sync --all-groups
-```
-
-This creates a local `.venv/` environment and installs the package in
-editable mode together with the development, lint, docs, and example
-dependencies defined in `pyproject.toml`.
-
-You can run commands through `uv`:
-
-```bash
-uv run python
-uv run pytest
-```
-
-Or activate the environment manually:
-
-```bash
-source .venv/bin/activate
-```
+Clone the repository and install all dependency groups as described in
+[Development environment](advanced-users.md#development-environment).
 
 ## Run the unit tests
 
@@ -43,10 +21,12 @@ uv run pytest
 
 ## Run the notebook tests
 
-The example notebooks are tested with `pytest` and `nbval`:
+The example notebooks are tested with `pytest` and `nbval`. The
+`--nbval-current-env` flag makes nbval ignore the kernel recorded in each
+notebook and run the cells in the uv-managed environment, the same way CI does:
 
 ```bash
-uv run --group examples pytest --nbval-lax examples/notebooks/
+uv run --group examples pytest --nbval-lax --nbval-current-env examples/notebooks/
 ```
 
 ## Run the regression tests
@@ -62,16 +42,5 @@ listed in [Example notebooks](examples/index.md).
 
 ## Run the notebooks locally
 
-The notebooks live in
-[`examples/notebooks/`](https://github.com/beykyle/jitr/tree/main/examples/notebooks).
-To run them locally, install the example dependencies and register the
-project environment as a Jupyter kernel:
-
-```bash
-uv sync --group examples
-uv run python -m ipykernel install --user --name jitr --display-name "Python (jitr)"
-uv run --with jupyter jupyter lab
-```
-
-In JupyterLab, select the `Python (jitr)` kernel so the notebooks run
-against the `uv`-managed environment.
+See [Examples and tutorials](getting-started.md#examples-and-tutorials) for
+how to launch JupyterLab against the uv-managed environment.

examples/notebooks/alpha_ca48_ambiguity.ipynb

@@ -13,7 +13,7 @@
     "\n",
     "We reuse its entire setup - the same data, potential form, error model and likelihood - without repeating the derivations; see that notebook for all of the details.\n",
     "\n",
-    "In this notebook we explore the famous *discrete ambiguity* of light-ion optical potentials: depths differing by tens of MeV - interior wavefunctions with different numbers of nodes - can produce nearly identical elastic cross sections when the phase between solutions with different numbers of nodes matches up. The discussion in Sec. 6 of the excellent 1971 review article by [P E Hodgson](https://iopscience.iop.org/article/10.1088/0034-4885/34/2/306/meta), and references therein, go into more detail.\n",
+    "In this notebook we explore the famous *discrete ambiguity* of light-ion optical potentials: depths differing by tens of MeV - interior wavefunctions with different numbers of nodes - can produce nearly identical elastic cross sections when the phase between solutions with different numbers of nodes matches up. The discussion in Sec. 9 of the excellent 1971 review article by [P E Hodgson](https://iopscience.iop.org/article/10.1088/0034-4885/34/2/306/meta), and references therein, go into more detail.\n",
     "\n",
     "In a Bayesian context, we can understand this discrete ambiguity as a *posterior multimodality* - multiple distinct regions in parameter space produce distinct cross sections with similar likelihoods of describing the same data. At the end, we will revisit the conclusions of the calibration notebook, in which we chose priors to center on a distinct family, or mode: how do this choice hold up? Is the family we selected there the one the data prefer, and do the quantities we compared between isotopes survive marginalization over the ambiguity?\n",
     "\n",