CosmoStat · cailmdaley · May 31, 2026 · May 31, 2026 · May 31, 2026
diff --git a/README.rst b/README.rst
@@ -1,22 +1,56 @@
 ShapePipe
 =========
 
-|CI| |CD| |python39| |release|
+|CI| |CD| |python312| |release|
 
 .. |CI| image:: https://github.com/CosmoStat/shapepipe/workflows/CI/badge.svg
   :target: https://github.com/CosmoStat/shapepipe/actions?query=workflow%3ACI
 
 .. |CD| image:: https://github.com/CosmoStat/shapepipe/actions/workflows/pages/pages-build-deployment/badge.svg
   :target: https://github.com/CosmoStat/shapepipe/actions/workflows/pages/pages-build-deployment
 
-.. |python39| image:: https://img.shields.io/badge/python-3.9-green.svg
-  :target: https://www.python.org/‰
+.. |python312| image:: https://img.shields.io/badge/python-3.12-green.svg
+  :target: https://www.python.org/
 
 .. |release| image:: https://img.shields.io/github/v/release/CosmoStat/shapepipe
   :target: https://github.com/CosmoStat/shapepipe/releases/latest
 
 ShapePipe is a galaxy shape measurement pipeline developed within the
-CosmoStat lab at CEA Paris-Saclay.
+CosmoStat lab at CEA Paris-Saclay. It runs the full chain from raw survey
+images to calibrated shear catalogues — object detection, PSF modelling, and
+shape measurement — and produced the first UNIONS cosmic-shear release.
 
-See the `documentation <https://cosmostat.github.io/shapepipe>`_ for details
-on how to install and run ShapePipe.
+Quickstart
+----------
+
+ShapePipe ships as a container image, so you can run the bundled example
+pipeline — a single CFIS tile through the full chain — without installing
+anything:
+
+.. code-block:: bash
+
+    # Apptainer (HPC, no root needed):
+    apptainer exec docker://ghcr.io/cosmostat/shapepipe:develop-runtime shapepipe_run_example
+
+    # ...or Docker:
+    docker run --rm ghcr.io/cosmostat/shapepipe:develop-runtime shapepipe_run_example
+
+The image is published on every push to the `GitHub Container Registry
+<https://github.com/CosmoStat/shapepipe/pkgs/container/shapepipe>`_:
+``:develop`` tracks the integration branch, release tags (e.g. ``:v1.1.0``) a
+stable cut, and the ``-runtime`` suffix selects the slim batch image over the
+full interactive one.
+
+Documentation
+-------------
+
+Full documentation lives at https://cosmostat.github.io/shapepipe. Good places
+to start:
+
+- `Installation <https://cosmostat.github.io/shapepipe/installation.html>`_ — getting ShapePipe onto your machine or cluster.
+- `Basic execution <https://cosmostat.github.io/shapepipe/basic_execution.html>`_ and `configuration <https://cosmostat.github.io/shapepipe/configuration.html>`_ — running ``shapepipe_run`` and writing pipeline configs.
+- `Container workflow <https://cosmostat.github.io/shapepipe/container.html>`_ — the two image targets and the ``pyproject.toml`` / ``uv.lock`` / ``Dockerfile`` layers.
+- `Running on a cluster <https://cosmostat.github.io/shapepipe/clusters.html>`_ — pulling the image and submitting jobs, with worked candide (SLURM) and CANFAR examples.
+
+If you use ShapePipe in academic work, please cite Guinot et al. (2022) and
+Farrens et al. (2022).
diff --git a/docs/source/basic_execution.md b/docs/source/basic_execution.md
@@ -7,7 +7,7 @@ option:
 
 ```{seealso}
 :class: margin
-The `shapepipe` environment will need to be built and activated in order to run this script (see [Installation](installation.md)).
+ShapePipe runs inside its container — there is no environment to activate. See [Installation](installation.md).
 ```
 ```bash
 shapepipe_run --help
@@ -37,11 +37,33 @@ shapepipe_run -c <PATH TO CONFIG FILE>
 ## Running the Pipeline with MPI
 
 ShapePipe can also use [mpi4py](https://mpi4py.readthedocs.io/en/stable/)
-for managing parallel processes on clusters with multiple nodes.
-The `shapepipe_run` script can be run with MPI as follows
+to spread work across multiple nodes of a cluster. Set `MODE = mpi` in the
+`[EXECUTION]` section of the config and launch with an MPI runner:
 
 ```bash
-mpiexec -n <NUMBER OF CORES> shapepipe_run
+mpiexec -n <NUMBER OF RANKS> shapepipe_run -c <PATH TO CONFIG FILE>
 ```
 
-where `<NUMBER OF CORES>` is the number of cores to allocate to the run.
+where `<NUMBER OF RANKS>` is the number of MPI processes to start.
+
+### Through the container (the supported way on a cluster)
+
+On a cluster you run ShapePipe from the published image as a standard Apptainer
+*hybrid* MPI job: the **host** `mpirun`/`mpiexec` launches one container rank per
+slot, and the OpenMPI bundled in the image wires the ranks together.
+
+```bash
+# one-time: pull the runtime image
+apptainer pull shapepipe.sif docker://ghcr.io/cosmostat/shapepipe:develop-runtime
+
+# load a host MPI in the same family as the image's OpenMPI (5.0.x), then launch
+module load openmpi
+mpirun -n <NUMBER OF RANKS> \
+    apptainer exec --bind "$PWD:$PWD" shapepipe.sif \
+    shapepipe_run -c <PATH TO CONFIG FILE>
+```
+
+The image ships **OpenMPI 5.0.x** so that its PMIx matches modern cluster
+launchers. The host and container MPI must be compatible: if you see *N* copies
+of `rank 0 of 1` instead of one *N*-rank job, load a host OpenMPI in the 5.0.x
+family. See `example/pbs/candide_mpi.sh` for a complete SLURM batch script.
diff --git a/docs/source/canfar.md b/docs/source/canfar.md
diff --git a/docs/source/clusters.md b/docs/source/clusters.md
@@ -0,0 +1,101 @@
+# Running on a Cluster
+
+ShapePipe runs the same way on every cluster: **through the container**. You
+pull the slim `runtime` image once, bind-mount your clone, and run
+`shapepipe_run` (or the CANFAR submission tooling) inside it — there is no
+environment to install or activate on the host. This page covers the shared
+pattern, then the specifics for each supported machine.
+
+For what is *inside* the image and how it is built, see
+[Container Workflow](container.md).
+
+## The pattern
+
+Three things hold on any cluster:
+
+- **The container is the unit of execution.** Pull the runtime image to a SIF
+  (`apptainer pull … docker://ghcr.io/cosmostat/shapepipe:<tag>-runtime`) and run
+  the pipeline inside it. Nothing else is installed on the host.
+- **Bind-mount your clone at the same path.** The config files reference their
+  location for the input and output directories; bind-mounting the host clone at
+  the *identical* path inside the container makes those paths resolve the same in
+  and out of the container.
+- **Keep SIFs and Apptainer's scratch off a quota-limited `$HOME`.** A pull under
+  a tight home quota fails with `disk quota exceeded`; point `APPTAINER_CACHEDIR`
+  (and the SIF itself) at a roomy data partition.
+
+MPI jobs add one constraint: the container's MPI must speak the same PMIx wire
+protocol as the host launcher (see the candide section below).
+
+## candide (SLURM)
+
+candide uses **SLURM** (`sbatch`; the old `qsub`/PBS commands are gone). The repo
+ships ready job scripts in `example/pbs/` — `candide_smp.sh` (single node,
+parallelised with joblib) and `candide_mpi.sh` (multi-node, hybrid MPI). To run
+the bundled single-tile example end to end:
+
+```bash
+# Keep the SIF and Apptainer's scratch off the quota-limited $HOME.
+export DATA=/n17data/$USER                 # adjust to your data partition
+export APPTAINER_CACHEDIR=$DATA/.apptainer
+
+# Pull the runtime image (~850 MB).
+apptainer pull "$DATA/shapepipe-runtime.sif" \
+    docker://ghcr.io/cosmostat/shapepipe:develop-runtime
+
+# Submit. SPDIR is your clone, bind-mounted at the same path inside the
+# container; SP_IMAGE is the SIF. The same script serves the example and a real
+# run — point the config inside it at your own pipeline.
+SP_IMAGE="$DATA/shapepipe-runtime.sif" SPDIR="/path/to/shapepipe" \
+    sbatch example/pbs/candide_smp.sh
+```
+
+Partitions are `comp` (2-day limit) and `compl` (5-day). Both job scripts read
+`SP_IMAGE` (the SIF) and `SPDIR` (the clone) from the environment, so the only
+thing that changes between the example and a real run is the config the script
+points at.
+
+For multi-node MPI, use `candide_mpi.sh`. It `module load`s a host OpenMPI in the
+5.0.x series to match the PMIx that the image's OpenMPI speaks; a mismatched host
+MPI (e.g. OpenMPI 4) silently degrades the job to *N* independent "rank 0 of 1"
+processes instead of one *N*-rank job. The script's header comments carry the
+detail.
+
+Adapting these scripts to another SLURM cluster is mostly the `#SBATCH`
+directives and the `module load` line — the `apptainer exec` invocation carries
+over unchanged.
+
+## CANFAR
+
+CANFAR submission does not go through a batch scheduler. Instead you submit
+container jobs to CANFAR's headless system with the `canfar_submit_job` console
+script (backed by the `canfar` library), and watch them with `canfar_monitor` /
+`canfar_monitor_log`. Pipeline steps are **bit-coded** through `-j` (the same
+scheme as `scripts/sh/job_sp_canfar.bash`), the PSF model is chosen with
+`-p psfex|mccd`, and `-V` selects the image version:
+
+```bash
+# Submit pipeline step(s) for the configured tiles (bit-coded -j).
+canfar_submit_job -j 1 -p psfex -V 1.1
+
+# Monitor sessions/jobs and stream logs.
+canfar_monitor
+canfar_monitor_log
+```
+
+The full production run — input preparation, the per-step `-j` table, and
+post-processing — is documented in the
+[CANFAR production walkthrough](pipeline_canfar.md).
+
+```{note}
+The CANFAR production submission scripts (`scripts/sh/job_sp_canfar*.bash`) still
+run under the pre-container environment and are slated for the same
+container-first cleanup the candide scripts received. Treat the walkthrough as
+the current-but-evolving production procedure.
+```
+
+## ccin2p3
+
+ccin2p3 is not yet containerised. The `example/pbs/cc_{smp,mpi}.sh` scripts target
+the pre-container environment; a container-first path mirroring candide is future
+work.
diff --git a/docs/source/configuration.md b/docs/source/configuration.md
@@ -1,6 +1,6 @@
 # Configuration
 
-The pipeline requires a configuration file (by default called `conifg.ini`)
+The pipeline requires a configuration file (by default called `config.ini`)
 in order to be run. Example configuration files are provided in the
 [example](https://github.com/CosmoStat/shapepipe/tree/develop/example)
 directory.
@@ -114,7 +114,7 @@ INPUT_DIR = last:psfex_runner
 OUTPUT_DIR = /home/username/my_output_dir
 FILE_PATTERN = psf
 FILE_EXT = fits
-NUMBERING_LIST = -001, -002
+NUMBER_LIST = -001, -002
 ```
 
 ShapePipe will look for the specific files `psf-001.fits` and `psf-002.fits`

diff --git a/docs/source/container.md b/docs/source/container.md
@@ -2,7 +2,8 @@
 
 ShapePipe ships as a container image. This page covers the two image
 targets and the three configuration files (`pyproject.toml`, `uv.lock`,
-`Dockerfile`) that determine what's inside.
+`Dockerfile`) that determine what's inside. For running the image on a batch
+cluster (candide, CANFAR), see [Running on a cluster](clusters.md).
 
 ## Two image targets
 

diff --git a/docs/source/contributing.md b/docs/source/contributing.md
@@ -2,7 +2,7 @@
 
 ShapePipe is a fully open-source project and we welcome contributions.
 
-Pleas read our
+Please read our
 [contribution guidelines](https://github.com/CosmoStat/shapepipe/blob/develop/CONTRIBUTING.md).
 for details on how to contribute to the development of this package.