Scripts reference#

The command-line tools under scripts/, grouped by task. Run everything from the repository root. Python scripts run with uv run python <script> and every one that parses arguments prints its full option list with --help, so this page does not repeat option lists. Shell and Slurm launchers show their invocation form instead.

Most tools here are for developers and cluster users. If you just want to run a forecast, you do not need any of them: see A verified first forecast.

Which script do I want?#

I want to…	Use	Section
Compare CAMB and CLASS forecasts for the configured validation cases	`scripts/validation/run_selected_validations.sh`	Backend validation
Compare two Fisher matrices on disk	`scripts/validation/compare_fishers_in_dir.py`	Backend validation
Check a CMB forecast against a Planck chain	`scripts/planck/run_planck_bestfit_fisher.py`	Planck diagnostics
Compare Fisher and Nautilus posteriors for WL and GCsp	`scripts/likelihood/nautilus/wl_gcsp_fisher_nautilus_demo.py`	Likelihood tools
Run long Nautilus chains on a Slurm cluster	`scripts/hpc/slurm/submit_wl_gcsp_nautilus.sh`	Slurm launchers
Time the photometric pipeline, or compare backends and fast paths	`scripts/archive/benchmarks/photometric_benchmark.py`	Benchmarks and profiling
Run a CMB Fisher for Planck, Simons Observatory or CMB-S4 specs	`scripts/archive/cmb/run_cmb_fisher_smoke.py`	Benchmarks and profiling
Add a Gaussian prior to a saved Fisher matrix	`scripts/utilities/fisher/add_scalar_prior_to_fisher.py`	Fisher utilities
Prepare a release	`scripts/maintenance/release/`	Release maintenance

Backend validation#

Run CAMB-versus-CLASS comparisons and build the report dashboard; see Backend validation for the workflow. Start with run_selected_validations.sh. It calls most of the others.

Script	What it does
`scripts/validation/run_selected_validations.sh`	Runs selected cases (`--cases LIST`) or all of them (`--all`), then refreshes the dashboard. `--help` prints the table of configured case IDs.
`scripts/validation/compare_backends_report.sh`	Runs both backends, the comparison, plots and report for one case (`--config path`).
`scripts/validation/run_fisher_compare_backends.py`	Computes two Fisher forecasts with chosen backends (`--code-a`, `--code-b`) and optionally compares and plots them (`--compare`, `--plot`).
`scripts/validation/compare_fishers_in_dir.py`	Compares the Fisher matrices in a result directory; positional `dir`, optional `--ref`.
`scripts/validation/plot_compare_fishers.py`	Plots the comparison stored in a JSON file (positional `json`).
`scripts/validation/render_compare_reports.py`	Renders comparison folders as Markdown or HTML reports.
`scripts/validation/render_validation_dashboard.py`	Builds the dashboard HTML from validation configs and results; `--serve` previews it locally.
`scripts/validation/publish_validation_dashboard.sh`	Publishes the dashboard to the `dashboard/` path of `gh-pages`. It leaves the `docs/` path, where `.github/workflows/docs.yml` publishes this site, untouched. It changes the publication checkout, so run it only when you intend to publish.
`scripts/validation/setup/install_camb_fork_for_validation.sh`	Installs the pinned CAMB fork for validation without changing the package’s CAMB pin.

Planck diagnostics#

Compare CMB Fisher forecasts with Planck chains and published covariances. The Planck directory must hold the chain’s .likestats, .margestats, .covmat, .paramnames and .minimum.inputparams products.

Script	What it does
`scripts/planck/run_planck_bestfit_fisher.py`	Builds a CMB Fisher at a Planck best fit, with options for parameterisation, observables, noise and solver settings.
`scripts/planck/run_planck_diagnostics_suite.sh`	Runs the standard set of best-fit variants used by the covariance/noise diagnostic notebook: `bash scripts/planck/run_planck_diagnostics_suite.sh [PLANCK_DIR]`. `PLANCK_DIR` defaults to a path under `Planck-Results/`.
`scripts/planck/compare_planck_published.py`	Compares a Fisher forecast (positional `fisher`) with published Planck constraints.
`scripts/planck/plot_planck_covmat_vs_fisher.py`	Plots Planck covariance constraints against a Fisher forecast.

Likelihood tools#

For the Nautilus workflow itself, see Likelihood sampling with Nautilus.

Script	What it does
`scripts/likelihood/nautilus/wl_gcsp_fisher_nautilus_demo.py`	Quick WL, GCsp and joint Fisher-versus-Nautilus demo with comparison plots. Use `--skip-nautilus` to skip sampling.
`scripts/likelihood/nautilus/run_wl_gcsp_nautilus_case.py`	Runs one case (`--case {wl,gcsp,joint}`) into `--run-dir`; `--n-live`, `--n-eff` and `--workers` are required; `--resume` continues a run.
`scripts/likelihood/nautilus/postprocess_wl_gcsp_nautilus.py`	Summarises a finished run (`--run-dir`) with chain-versus-Fisher statistics and plots.
`scripts/likelihood/postprocess/render_likelihood_validation.py`	Collects copied HPC run artefacts into the statistics and figures of Likelihood validation.
`scripts/likelihood/postprocess/plot_finished_chain.py`	Plots posterior samples from one or more chain metadata files.
`scripts/likelihood/diagnostics/run_syren_new_likelihoods.py`	Runs the SYREN likelihood checks (`--probe {gcsp,photo,both}`).
`scripts/likelihood/diagnostics/gcsp_likelihood_grid.py`	Evaluates and saves a two-parameter GCsp likelihood grid.
`scripts/likelihood/diagnostics/gcsp_likelihood_hessian.py`	Checks the GCsp likelihood curvature for several finite-difference step fractions.
`scripts/likelihood/diagnostics/wl_likelihood_grid.py`	Two-parameter weak-lensing likelihood grid with parallel workers.
`scripts/likelihood/diagnostics/verify_gcsp_covariance_sympy.py`	Prints SymPy checks of the GCsp covariance. It has no options and no `--help`.

Slurm launchers#

For cluster runs of the WL and GCsp Nautilus cases. They need Slurm and the site environment (JURECA/PUNCH for the WL/GCsp templates). Start with submit_wl_gcsp_nautilus.sh, which submits the two WL/GCsp .sbatch templates for you.

Script	Invocation
`scripts/hpc/slurm/submit_wl_gcsp_nautilus.sh`	`RUN_DIR=<dir> [OPTIONS] scripts/hpc/slurm/submit_wl_gcsp_nautilus.sh` submits the WL, GCsp and joint jobs plus a dependent postprocessing job. `--help` lists the environment variables.
`scripts/hpc/slurm/check_wl_gcsp_status.sh`	`scripts/hpc/slurm/check_wl_gcsp_status.sh [--watch [SECONDS]] <RUN_DIR> <WL_JOBID> <GCSP_JOBID> <JOINT_JOBID> <POST_JOBID>` reports job status and results; it never submits or cancels jobs.
`scripts/hpc/slurm/wl_gcsp_nautilus_case.sbatch`	Template for one case: `sbatch --export=ALL,... <file>`.
`scripts/hpc/slurm/wl_gcsp_nautilus_postprocess.sbatch`	Template for the dependent postprocessing job.
`scripts/hpc/slurm/nautilus_sampler.sbatch`	Generic launcher for the YAML-driven `scripts/likelihood/sampler/run_sampler.py`: `REPO_ROOT=<repo> CONFIG_FILE=<yaml> OUTPUT_DIR=<dir> sbatch scripts/hpc/slurm/nautilus_sampler.sbatch`.
`scripts/likelihood/sampler/`	Small YAML examples and generic runner: `uv run python scripts/likelihood/sampler/run_sampler.py scripts/likelihood/sampler/fresh_lcdm_symbolic_small.yaml` from the repository root. See Validation data and examples (cjfp-data) for operational configurations and published outputs.

Benchmarks and profiling#

Script	What it does
`scripts/archive/benchmarks/photometric_benchmark.py`	Times photometric (`GCph`, `WL`) Fisher forecasts and the lensing-efficiency integrators; see below.
`scripts/profiling/photo_obs/profile_photo_obs.py`	Profiles photometric angular spectra and Fisher calculations across backends, accuracies and derivative settings. `--output` is required.
`scripts/archive/cmb/run_cmb_fisher_smoke.py`	Runs one CMB Fisher forecast from a survey-spec YAML; see below.
`scripts/archive/cmb/run_cmb_benchmarks.py`	Runs the Planck, Simons Observatory and CMB-S4 presets in one go; see below.

The photometric and CMB scripts live in scripts/archive/, where historical tools are kept. They still run but are not part of the maintained validation workflow. See also CMB benchmarks for the CMB specifications they use.

Photometric benchmark#

uv run python scripts/archive/benchmarks/photometric_benchmark.py \
  --code symbolic --observables WL

This computes a Fisher forecast with the symbolic backend in about 10 seconds. It prints one timing and error summary per run and writes the matrix, a timings file and *_fisher_comparison.json to scripts/benchmark_results/ (gitignored, created relative to the current directory, so run it from the repository root). Useful options:

--codes camb,class,symbolic (or all) runs several backends and compares them.
--observables GCph,WL (the default) selects the probes.
--accuracy N scales the grid sizes; higher is slower and more precise.
--efficiency also benchmarks the lensing-efficiency integrators, and --skip-fisher skips the Fisher run.
--fast-benchmark runs a full Fisher with the fast code paths on and off and writes a JSON summary; --fast, --fast-eff, --fast-p and --fast-kernel set the fast-path toggles.
--compare-ref PREFIX_OR_JSON compares against an earlier run.

CMB Fisher smoke test#

Run it from the repository root:

uv run python scripts/archive/cmb/run_cmb_fisher_smoke.py \
  --code camb \
  --spec-yaml cosmicjellyfish/configs/default_survey_specifications/Planck.yaml \
  --observables CMB_T,CMB_E --lmax 120 \
  --outdir tmp/cmb_planck_smoke --write-enabled-yaml

--spec-yaml can also be Simons-Observatory-PlanckLowEll.yaml or CMB-Stage4-PlanckLowEll.yaml from the same folder. --observables takes any of CMB_T, CMB_E, CMB_B. --write-enabled-yaml saves a copy of the solver YAML with CMB outputs switched on in the output directory and runs with it; keep it unless your own YAML already enables CMB outputs.

run_cmb_benchmarks.py --which planck,so,s4 runs the three presets with CAMB; add --lmax 120 for a quick test. --boltzmann-yaml selects another solver YAML and is forwarded to run_cmb_fisher_smoke.py.

Fisher utilities#

Script	What it does
`scripts/utilities/fisher/add_scalar_prior_to_fisher.py`	Adds a one-parameter Gaussian prior (`--param`, `--sigma`) to a Fisher matrix (positional `fisher`) and can compare the result with another forecast (`--compare-to`).

Release maintenance#

Script	Invocation
`scripts/maintenance/release/prepare_changelog.py`	`uv run python scripts/maintenance/release/prepare_changelog.py` moves the current version from the Unreleased section into a dated `CHANGELOG.md` heading. It edits the file in place and takes no arguments.
`scripts/maintenance/release/check_version_consistency.py`	`uv run python scripts/maintenance/release/check_version_consistency.py` exits with an error if `CITATION.cff` carries a different `version:` than `cosmicjellyfish/version.py`; it runs in CI as the `Metadata` task.
`scripts/maintenance/release/release_notes.py`	`TAG=<git-tag> uv run python scripts/maintenance/release/release_notes.py` generates release notes; the release GitHub Actions workflow also uses it.
`scripts/maintenance/release/release.sh`	`bash scripts/maintenance/release/release.sh [--dry-run] [--yes]` is a guided, step-by-step release helper. From a clean, up-to-date `main` it checks that `version.py` and `CITATION.cff` agree, turns `## Unreleased` into a dated `## [vX.Y.Z]` changelog section, commits only `CHANGELOG.md` and creates the tag `vX.Y.Z`, explaining and confirming each step. It never pushes; it prints the push commands and the post-release checks. A tag containing `rc` publishes to TestPyPI, any other tag to PyPI. See Releasing.