add google collab links

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: <https://beykyle.github.io/jitr/>
 
@@ -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
 

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/): click the **Open in Colab** badges below. 
 
 ```{toctree}
 :hidden:
@@ -31,40 +32,56 @@
 
 - [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)
 
 
 
 ## Other useful examples
 
 - [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)

docs/getting-started.md

@@ -47,7 +47,17 @@ 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). First, clone the repository and navigate to the project directory:
+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).
+
+
+### 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.
 
 ```
 git clone https://github.com/beykyle/jitr.git
@@ -56,13 +66,13 @@ cd jitr
 
 Before you can run the notebooks, there are some additional requirements which need to be installed into the environment. They live in the `examples` dependency group. To install them, from the main project directory, run:
 
-```
+```bash
 uv sync --group examples
 ```
 
 Then, you can launch `jupyter` inside the uv-managed environment. For example, to spin up a JupyterLab server:
 
-```
+```bash
 uv run --group examples jupyter lab
 ```
 

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",

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",

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",

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"
    ]
   },

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",

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",