From d7b66072913f64001e5c9559284d38a30e6f8210 Mon Sep 17 00:00:00 2001 From: beykyle Date: Thu, 17 Sep 2026 15:00:37 -0400 Subject: [PATCH 1/3] add google collab links --- README.md | 5 ++- docs/examples/index.md | 21 +++++++++- docs/getting-started.md | 24 +++++++++-- examples/notebooks/alpha_ca48_ambiguity.ipynb | 42 +++++++++++++++++++ examples/notebooks/alpha_ca_calibration.ipynb | 42 +++++++++++++++++++ examples/notebooks/angular_reaction_xs.ipynb | 32 ++++++++++++++ examples/notebooks/builtin_omps_uq.ipynb | 35 +++++++++++++++- examples/notebooks/chex_jitr_validation.ipynb | 37 ++++++++++++++++ examples/notebooks/chuq_kduq_comp.ipynb | 32 ++++++++++++++ .../notebooks/comparison_to_Runge_Kutta.ipynb | 32 ++++++++++++++ .../convergence_channel_radius.ipynb | 32 ++++++++++++++ .../notebooks/dispersive_optical_model.ipynb | 32 ++++++++++++++ examples/notebooks/example_jlm.ipynb | 32 ++++++++++++++ .../how_to_define_your_interaction.ipynb | 30 +++++++++++++ examples/notebooks/integration.ipynb | 32 ++++++++++++++ .../notebooks/kd03_neutron_dxs_demo.ipynb | 32 ++++++++++++++ examples/notebooks/kduq_uq_demo.ipynb | 32 ++++++++++++++ examples/notebooks/local_omp_demo.ipynb | 32 ++++++++++++++ examples/notebooks/mass_exploration.ipynb | 32 ++++++++++++++ examples/notebooks/quickstart.ipynb | 37 ++++++++++++++++ examples/notebooks/reaction.ipynb | 32 ++++++++++++++ .../notebooks/tabulated_density_demo.ipynb | 32 ++++++++++++++ .../notebooks/test_coupled_single_dwba.ipynb | 30 +++++++++++++ examples/notebooks/test_dom_with_edep_a.ipynb | 32 ++++++++++++++ examples/notebooks/volume_integrals.ipynb | 32 ++++++++++++++ 25 files changed, 776 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 54ea9ca7..0a6342c2 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ [![Python package](https://github.com/beykyle/jitr/actions/workflows/python-package.yml/badge.svg)](https://github.com/beykyle/jitr/actions/workflows/python-package.yml) [![PyPI publish](https://github.com/beykyle/jitr/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/beykyle/jitr/actions/workflows/pypi-publish.yml) +[![Open the quickstart in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/quickstart.ipynb) Documentation site: @@ -41,7 +42,9 @@ For `uv` users and other install options, see [Installation](https://beykyle.git ## Tutorials -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. +Tutorials live in [`examples/notebooks/`](./examples/notebooks). Every notebook opens and runs in Google Colab with nothing to install: click the **Open in Colab** badge at the top of any notebook, [browse them all in Colab](https://colab.research.google.com/github/beykyle/jitr), or start with the [quickstart](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/quickstart.ipynb). The first cell installs `jitr` and downloads the data files that notebook reads. + +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 diff --git a/docs/examples/index.md b/docs/examples/index.md index 227655eb..b7771cbc 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -2,6 +2,7 @@ `jitr` includes a growing collection of example notebooks that demonstrate how to use the library in various contexts, which live in `examples/notebooks/`. +Every notebook also runs in [Google Colab](https://colab.research.google.com/) with nothing to install: click the **Open in Colab** badge at the top of a notebook, or use the badges below. The first cell of each notebook installs `jitr` and downloads any data files it reads, and does so only when it detects a Colab runtime. ```{toctree} :hidden: @@ -31,10 +32,13 @@ - [Quickstart](/examples/notebooks/quickstart) compiles a solver for $\alpha$ + $^{44}$Ca, defines a parametric optical potential, and fits it to real elastic scattering data, all in under a minute. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/quickstart.ipynb) - [Bayesian calibration](/examples/notebooks/alpha_ca_calibration) extends the quickstart to a full Bayesian calibration which reveals shell effects in $\alpha$ + $^{40,44,48}$Ca. Includes construction of an error model which is jointly inferred with the optical model parameters, and checking the posterior predictive against the data using empirical coverages. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/alpha_ca_calibration.ipynb) - [Bayesian calibration with multimodal posteriors](/examples/notebooks/alpha_ca48_ambiguity) extends the quickstart to a tempered Bayesian calibration for $\alpha$ + $^{48}$Ca, providing a Bayesian perspective of the famous discrete parameter ambiguity in the binding of the interaction between nuclei and light ions. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/alpha_ca48_ambiguity.ipynb) @@ -42,29 +46,42 @@ - [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. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/reaction.ipynb) - [Koning-Delaroche neutron elastic scattering](/examples/notebooks/kd03_neutron_dxs_demo) shows how to compute the elastic scattering cross section for neutrons on various targets using the built-in Koning-Delaroche optical potential in `jitr`. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/kd03_neutron_dxs_demo.ipynb) - [Compare built-in uncertainty-quantified optical potentials](/examples/notebooks/builtin_omps_uq) - walks through posterior sampling, solver setup, and interval construction + walks through posterior sampling, solver setup, and interval construction for several of the built-in uncertainty quantified optical potentials in `jitr`. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/builtin_omps_uq.ipynb) - [Tabulated neutron and proton densities](/examples/notebooks/tabulated_density_demo) shows how to grab the tabulated nuclear densities in `jitr`. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/tabulated_density_demo.ipynb) - [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. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/example_jlm.ipynb) - [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`. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/chuq_kduq_comp.ipynb) - [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`. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/volume_integrals.ipynb) - [Channel-radius convergence study for elastic scattering](/examples/notebooks/convergence_channel_radius) shows how to check for numerical convergence in realistic calculations. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/convergence_channel_radius.ipynb) - [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) + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/dispersive_optical_model.ipynb) +- [UQ demo with Koning-Delaroche potential](/examples/notebooks/kduq_uq_demo) demos propagating the uncertainty of the built-in KDUQ interaction. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/kduq_uq_demo.ipynb) - [Optical potential interface](/examples/notebooks/local_omp_demo) shows how to define a custom optical potential using a common interface, and how to use it in a calculation. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/local_omp_demo.ipynb) - [Transmission coefficients by partial wave](/examples/notebooks/angular_reaction_xs) performs uncertainty quantification for partial wave transmission coefficients + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/angular_reaction_xs.ipynb) - [Mass-model effects on transmission-coefficient uncertainty](/examples/notebooks/mass_exploration) explores how mass-model choices propagate into transmission coefficients. + [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/mass_exploration.ipynb) diff --git a/docs/getting-started.md b/docs/getting-started.md index b8276299..58340ff9 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -47,17 +47,35 @@ python -c "import jitr; print(jitr.__version__)" ## Examples and tutorials -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. +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). + +### Run them in your browser + +Every notebook carries an **Open in Colab** badge at the top, and you can +[browse them all in Colab](https://colab.research.google.com/github/beykyle/jitr) or jump straight to the [quickstart](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/quickstart.ipynb). +There is nothing to install: the first cell of each notebook detects the Colab runtime, +`pip install`s `jitr` plus any extra packages that notebook needs, and downloads the data +files it reads. Outside Colab that cell does nothing, so the same notebook runs unchanged on +your own machine. If Colab asks you to restart the runtime after the install, restart and +re-run from the top. + +The two Bayesian calibration notebooks run with `JITR_QUICK=1` on Colab, which uses fewer +data points and live points so that the sampler finishes inside a free CPU runtime; the +posteriors are correspondingly coarser than the ones rendered here. + +### Run them locally + +For real work, clone the repo and open the notebooks 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: -``` +```bash uv sync --group examples ``` and start a JupyterLab server from the same directory: -``` +```bash uv run --group examples jupyter lab ``` diff --git a/examples/notebooks/alpha_ca48_ambiguity.ipynb b/examples/notebooks/alpha_ca48_ambiguity.ipynb index 4eb6dfa6..f06d6546 100644 --- a/examples/notebooks/alpha_ca48_ambiguity.ipynb +++ b/examples/notebooks/alpha_ca48_ambiguity.ipynb @@ -1,5 +1,47 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "3285fd5f", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/alpha_ca48_ambiguity.ipynb)\n", + "\n", + "Colab runs this notebook with `JITR_QUICK=1` -- fewer data points and live points -- so the posterior is coarser than the one rendered in the [documentation](https://beykyle.github.io/jitr/examples/index.html). Drop that line from the setup cell, on a runtime you can keep alive, to reproduce the full result." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0cb441ad", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr and this notebook's extra dependencies,\n", + "# and downloads the data file it reads below.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import os\n", + " import subprocess\n", + " import urllib.request\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\", \"dynesty\", \"corner\"],\n", + " check=True,\n", + " )\n", + " RAW = \"https://raw.githubusercontent.com/beykyle/jitr/main/examples/notebooks/\"\n", + " for fname in (\"alpha_ca_ratio_ruth.csv\",):\n", + " urllib.request.urlretrieve(RAW + fname, fname)\n", + " # keep the nested-sampling run inside a free Colab CPU runtime\n", + " os.environ.setdefault(\"JITR_QUICK\", \"1\")" + ] + }, { "cell_type": "markdown", "id": "d55fe01a", diff --git a/examples/notebooks/alpha_ca_calibration.ipynb b/examples/notebooks/alpha_ca_calibration.ipynb index c5d33c94..5ba72ee2 100644 --- a/examples/notebooks/alpha_ca_calibration.ipynb +++ b/examples/notebooks/alpha_ca_calibration.ipynb @@ -1,5 +1,47 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "df854b3b", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/alpha_ca_calibration.ipynb)\n", + "\n", + "Colab runs this notebook with `JITR_QUICK=1` -- fewer data points and live points -- so the posterior is coarser than the one rendered in the [documentation](https://beykyle.github.io/jitr/examples/index.html). Drop that line from the setup cell, on a runtime you can keep alive, to reproduce the full result." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "97365e9e", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr and this notebook's extra dependencies,\n", + "# and downloads the data file it reads below.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import os\n", + " import subprocess\n", + " import urllib.request\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\", \"dynesty\", \"corner\"],\n", + " check=True,\n", + " )\n", + " RAW = \"https://raw.githubusercontent.com/beykyle/jitr/main/examples/notebooks/\"\n", + " for fname in (\"alpha_ca_ratio_ruth.csv\",):\n", + " urllib.request.urlretrieve(RAW + fname, fname)\n", + " # keep the nested-sampling run inside a free Colab CPU runtime\n", + " os.environ.setdefault(\"JITR_QUICK\", \"1\")" + ] + }, { "cell_type": "markdown", "id": "0feb351c", diff --git a/examples/notebooks/angular_reaction_xs.ipynb b/examples/notebooks/angular_reaction_xs.ipynb index a1f7add6..817ca3c4 100644 --- a/examples/notebooks/angular_reaction_xs.ipynb +++ b/examples/notebooks/angular_reaction_xs.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "3cc7cff3", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/angular_reaction_xs.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2e2c4528", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "b342fc18-ac2f-4fb2-ae02-d7bc4cb12fa8", diff --git a/examples/notebooks/builtin_omps_uq.ipynb b/examples/notebooks/builtin_omps_uq.ipynb index 9705d524..ee74d0e3 100644 --- a/examples/notebooks/builtin_omps_uq.ipynb +++ b/examples/notebooks/builtin_omps_uq.ipynb @@ -1,5 +1,39 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "35920cc3", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/builtin_omps_uq.ipynb)\n", + "\n", + "On Colab the first `import exfor_tools` downloads and unpacks the EXFOR database, which takes a few minutes." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "45c82def", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr and this notebook's extra dependencies.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\", \"exfor-tools\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "93a49da0", @@ -94,7 +128,6 @@ } ], "source": [ - "#! pip install exfor-tools\n", "import exfor_tools" ] }, diff --git a/examples/notebooks/chex_jitr_validation.ipynb b/examples/notebooks/chex_jitr_validation.ipynb index 7333e47a..28699344 100644 --- a/examples/notebooks/chex_jitr_validation.ipynb +++ b/examples/notebooks/chex_jitr_validation.ipynb @@ -1,5 +1,42 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "af6af1f5", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/chex_jitr_validation.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "81bba3a5", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime,\n", + "# and downloads the data file it reads below.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + " import urllib.request\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )\n", + " RAW = \"https://raw.githubusercontent.com/beykyle/jitr/main/examples/notebooks/\"\n", + " for fname in (\"chex_qepn_xs.txt\",):\n", + " urllib.request.urlretrieve(RAW + fname, fname)" + ] + }, { "cell_type": "markdown", "id": "674dae53-f322-4a7f-83ef-942ea1641ddc", diff --git a/examples/notebooks/chuq_kduq_comp.ipynb b/examples/notebooks/chuq_kduq_comp.ipynb index 3bf3baa2..d6f42c03 100644 --- a/examples/notebooks/chuq_kduq_comp.ipynb +++ b/examples/notebooks/chuq_kduq_comp.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "c97ca0f0", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/chuq_kduq_comp.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7bddb780", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "3cfd7e65-ad54-4875-a20a-3fd7b2a6a6e9", diff --git a/examples/notebooks/comparison_to_Runge_Kutta.ipynb b/examples/notebooks/comparison_to_Runge_Kutta.ipynb index 83e93f8b..0e7bcfdd 100644 --- a/examples/notebooks/comparison_to_Runge_Kutta.ipynb +++ b/examples/notebooks/comparison_to_Runge_Kutta.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "ff4ac767", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/comparison_to_Runge_Kutta.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2f5704ce", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "cdbaed91", diff --git a/examples/notebooks/convergence_channel_radius.ipynb b/examples/notebooks/convergence_channel_radius.ipynb index 037e31d6..1be69b45 100644 --- a/examples/notebooks/convergence_channel_radius.ipynb +++ b/examples/notebooks/convergence_channel_radius.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "10719383", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/convergence_channel_radius.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "bf58fed8", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "b342fc18-ac2f-4fb2-ae02-d7bc4cb12fa8", diff --git a/examples/notebooks/dispersive_optical_model.ipynb b/examples/notebooks/dispersive_optical_model.ipynb index 228eb4c8..876cfe1b 100644 --- a/examples/notebooks/dispersive_optical_model.ipynb +++ b/examples/notebooks/dispersive_optical_model.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "9ae4213a", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/dispersive_optical_model.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "cd36e8b5", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "4038a941", diff --git a/examples/notebooks/example_jlm.ipynb b/examples/notebooks/example_jlm.ipynb index 1cdec83c..8867d760 100644 --- a/examples/notebooks/example_jlm.ipynb +++ b/examples/notebooks/example_jlm.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "ed52f7b0", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/example_jlm.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c958059d", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "md-001", diff --git a/examples/notebooks/how_to_define_your_interaction.ipynb b/examples/notebooks/how_to_define_your_interaction.ipynb index 09e638d1..4501a3f1 100644 --- a/examples/notebooks/how_to_define_your_interaction.ipynb +++ b/examples/notebooks/how_to_define_your_interaction.ipynb @@ -1,5 +1,35 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/how_to_define_your_interaction.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "metadata": {}, diff --git a/examples/notebooks/integration.ipynb b/examples/notebooks/integration.ipynb index 29ff929a..a2074340 100644 --- a/examples/notebooks/integration.ipynb +++ b/examples/notebooks/integration.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "2bc6fec1", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/integration.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "968a579d", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "cfa05270", diff --git a/examples/notebooks/kd03_neutron_dxs_demo.ipynb b/examples/notebooks/kd03_neutron_dxs_demo.ipynb index a35cb0f3..95ad870e 100644 --- a/examples/notebooks/kd03_neutron_dxs_demo.ipynb +++ b/examples/notebooks/kd03_neutron_dxs_demo.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "ff2aa2f3", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/kd03_neutron_dxs_demo.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a9f39e36", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "eda26f37", diff --git a/examples/notebooks/kduq_uq_demo.ipynb b/examples/notebooks/kduq_uq_demo.ipynb index 750e6738..ec7e86f2 100644 --- a/examples/notebooks/kduq_uq_demo.ipynb +++ b/examples/notebooks/kduq_uq_demo.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "75ae38e7", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/kduq_uq_demo.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a7dea4f6", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "93a49da0", diff --git a/examples/notebooks/local_omp_demo.ipynb b/examples/notebooks/local_omp_demo.ipynb index 67a372cb..8cb7337a 100644 --- a/examples/notebooks/local_omp_demo.ipynb +++ b/examples/notebooks/local_omp_demo.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "32b991c1", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/local_omp_demo.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ffe1a723", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "80bc7461-98bf-4a6a-a951-2c1666d43e7b", diff --git a/examples/notebooks/mass_exploration.ipynb b/examples/notebooks/mass_exploration.ipynb index fd24e948..8805471f 100644 --- a/examples/notebooks/mass_exploration.ipynb +++ b/examples/notebooks/mass_exploration.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "50d47328", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/mass_exploration.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "4fe8ceaa", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "b342fc18-ac2f-4fb2-ae02-d7bc4cb12fa8", diff --git a/examples/notebooks/quickstart.ipynb b/examples/notebooks/quickstart.ipynb index adc11b3b..d7c9ec00 100644 --- a/examples/notebooks/quickstart.ipynb +++ b/examples/notebooks/quickstart.ipynb @@ -1,5 +1,42 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "c62fe0ea", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/quickstart.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8f83152e", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime,\n", + "# and downloads the data file it reads below.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + " import urllib.request\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )\n", + " RAW = \"https://raw.githubusercontent.com/beykyle/jitr/main/examples/notebooks/\"\n", + " for fname in (\"alpha_ca_ratio_ruth.csv\",):\n", + " urllib.request.urlretrieve(RAW + fname, fname)" + ] + }, { "cell_type": "markdown", "id": "8a66b951", diff --git a/examples/notebooks/reaction.ipynb b/examples/notebooks/reaction.ipynb index 371cac81..daa1391b 100644 --- a/examples/notebooks/reaction.ipynb +++ b/examples/notebooks/reaction.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "5db0a275", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/reaction.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2bb04bd3", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "dd469178-bab9-4515-b3e5-ee0fae371906", diff --git a/examples/notebooks/tabulated_density_demo.ipynb b/examples/notebooks/tabulated_density_demo.ipynb index e1862655..b82a3799 100644 --- a/examples/notebooks/tabulated_density_demo.ipynb +++ b/examples/notebooks/tabulated_density_demo.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "9ddb59d2", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/tabulated_density_demo.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e4517b72", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "dc7dddf7-b53a-45b7-bf6d-9630954fe555", diff --git a/examples/notebooks/test_coupled_single_dwba.ipynb b/examples/notebooks/test_coupled_single_dwba.ipynb index 18cc6675..6a8a5c36 100644 --- a/examples/notebooks/test_coupled_single_dwba.ipynb +++ b/examples/notebooks/test_coupled_single_dwba.ipynb @@ -1,5 +1,35 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/test_coupled_single_dwba.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "code", "execution_count": 1, diff --git a/examples/notebooks/test_dom_with_edep_a.ipynb b/examples/notebooks/test_dom_with_edep_a.ipynb index 35aaa54a..0a9f8407 100644 --- a/examples/notebooks/test_dom_with_edep_a.ipynb +++ b/examples/notebooks/test_dom_with_edep_a.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "e63f3ea8", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/test_dom_with_edep_a.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "055bdd1b", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "8eb6d89c", diff --git a/examples/notebooks/volume_integrals.ipynb b/examples/notebooks/volume_integrals.ipynb index b54af17c..718467df 100644 --- a/examples/notebooks/volume_integrals.ipynb +++ b/examples/notebooks/volume_integrals.ipynb @@ -1,5 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "a5816d85", + "metadata": {}, + "source": [ + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/volume_integrals.ipynb)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7373065c", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# Google Colab setup: installs jitr into the Colab runtime.\n", + "# Does nothing when the notebook is run anywhere else.\n", + "import sys\n", + "\n", + "if \"google.colab\" in sys.modules:\n", + " import subprocess\n", + "\n", + " subprocess.run(\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"jitr\"],\n", + " check=True,\n", + " )" + ] + }, { "cell_type": "markdown", "id": "3cfd7e65-ad54-4875-a20a-3fd7b2a6a6e9", From ec0316b9031186522de097ce610e0fe054bcf142 Mon Sep 17 00:00:00 2001 From: beykyle Date: Thu, 17 Sep 2026 15:24:17 -0400 Subject: [PATCH 2/3] update example index --- docs/examples/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/index.md b/docs/examples/index.md index b7771cbc..38a30aa7 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -2,7 +2,7 @@ `jitr` includes a growing collection of example notebooks that demonstrate how to use the library in various contexts, which live in `examples/notebooks/`. -Every notebook also runs in [Google Colab](https://colab.research.google.com/) with nothing to install: click the **Open in Colab** badge at the top of a notebook, or use the badges below. The first cell of each notebook installs `jitr` and downloads any data files it reads, and does so only when it detects a Colab runtime. +Every notebook also runs in [Google Colab](https://colab.research.google.com/): click the **Open in Colab** badges below. ```{toctree} :hidden: From 0615d44f8b4c72dff593a3b105be12ba0fb4bf20 Mon Sep 17 00:00:00 2001 From: beykyle Date: Thu, 17 Sep 2026 15:25:42 -0400 Subject: [PATCH 3/3] cut down text --- docs/getting-started.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 58340ff9..fa904910 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -53,15 +53,7 @@ Tutorials live in [`examples/notebooks/`](https://github.com/beykyle/jitr/tree/m Every notebook carries an **Open in Colab** badge at the top, and you can [browse them all in Colab](https://colab.research.google.com/github/beykyle/jitr) or jump straight to the [quickstart](https://colab.research.google.com/github/beykyle/jitr/blob/main/examples/notebooks/quickstart.ipynb). -There is nothing to install: the first cell of each notebook detects the Colab runtime, -`pip install`s `jitr` plus any extra packages that notebook needs, and downloads the data -files it reads. Outside Colab that cell does nothing, so the same notebook runs unchanged on -your own machine. If Colab asks you to restart the runtime after the install, restart and -re-run from the top. - -The two Bayesian calibration notebooks run with `JITR_QUICK=1` on Colab, which uses fewer -data points and live points so that the sampler finishes inside a free CPU runtime; the -posteriors are correspondingly coarser than the ones rendered here. + ### Run them locally