clero 0.1.0__tar.gz

clero-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edward Stevenson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clero-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: clero
+Version: 0.1.0
+Summary: CLERO: the CLimate Emulator for ROcky exoplanets (inference-only runtime)
+Author-email: "Edward T. Stevenson" <es833@cam.ac.uk>
+License: MIT
+Project-URL: Homepage, https://github.com/edstevenson/clero
+Project-URL: Repository, https://github.com/edstevenson/clero
+Project-URL: Documentation, https://edstevenson.github.io/clero/
+Keywords: exoplanets,climate,emulator,Gaussian process,GCM
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.10
+Provides-Extra: gpu
+Requires-Dist: torch; extra == "gpu"
+Provides-Extra: demos
+Requires-Dist: nbformat; extra == "demos"
+Requires-Dist: nbclient; extra == "demos"
+Requires-Dist: ipykernel; extra == "demos"
+Requires-Dist: jupyter; extra == "demos"
+Provides-Extra: docs
+Requires-Dist: pdoc; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: clero[demos]; extra == "dev"
+Dynamic: license-file
+
+# CLERO (CLimate Emulator for ROcky exoplanets)
+
+![Tests](https://github.com/edstevenson/clero/actions/workflows/tests.yml/badge.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+![Docs](https://img.shields.io/badge/docs-pdoc-brightgreen.svg)
+![arXiv](https://img.shields.io/badge/arXiv-TODO-b31b1b.svg)  
+
+## What is CLERO
+
+CLERO is an exoGCM emulator that takes a hypothetical planet as input and outputs its 3D steady-state climate. It targets tidally locked ocean-covered rocky planets in or near the habitable zone; see [SCOPE.md](SCOPE.md) for detail on its scope of validity.
+
+CLERO computes a probability distribution over climates: `predict` returns its mean (our best point estimate of the climate) and `sample` returns draws from the distribution (see [UNCERTAINTY.md](UNCERTAINTY.md)).
+
+CLERO is based on Gaussian-process latent factor regression ([GPLFR](https://github.com/edstevenson/GPLFR)) and is trained on [ThousandWorlds](https://github.com/astroautomata/ThousandWorlds).
+
+Worked examples in [demos/](demos/).
+
+## Inputs
+
+
+| key     | unit            | notes                                                                                                    |
+| ------- | --------------- | -------------------------------------------------------------------------------------------------------- |
+| radius  | Earth radii     | planet radius                                                                                            |
+| gravity | m/s²            | surface gravity                                                                                          |
+| P_rot   | days            | rotation period (assumed = orbital, tidally locked)                                                      |
+| P0      | bar             | surface pressure                                                                                         |
+| CO2     | volume fraction | atmospheric CO2                                                                                          |
+| CH4     | volume fraction | atmospheric CH4                                                                                          |
+| F_star  | W/m²            | stellar flux at the planet                                                                               |
+| T_star  | K               | stellar effective temperature                                                                            |
+| GCM     | str             | climate model the prediction targets (optional, defaults to `"um"`; case-insensitive; see options below) |
+
+
+`CO2 + CH4 <= 1`; the rest of the atmosphere is N2. The validity ranges from [SCOPE.md](SCOPE.md) are available as `clero.CORE_DOMAIN` and `clero.EXTENDED_DOMAIN`.
+
+#### GCM options
+
+`um`, `exocam` (recommended — the two high-fidelity targets). `exoplasim` is a lower-fidelity exoGCM. `exocam-pre2022` and `lfric` should be avoided at inference time — `exocam-pre2022` is an older ExoCAM version, and  `lfric` has few training simulations.
+
+For predictions where self-consistency is important (e.g., spatially resolved plots), use a single emulated GCM. Where self-consistency is not needed (e.g., global means), once can average the emulated UM and ExoCAM predictions; this reduces dependence on either GCM's structural biases.
+
+## Outputs
+
+
+| fields                   | unit  |
+| ------------------------ | ----- |
+| `surface_temperature`    | K     |
+| `asr`, `olr`             | W/m²  |
+| `temperature_0..9`       | K     |
+| `specific_humidity_0..9` | kg/kg |
+| `cloud_fraction_0..9`    | 0–1   |
+| `u_0..9`, `v_0..9`       | m/s   |
+
+
+The 3D variables (`temperature`, `specific_humidity`, `cloud_fraction`, `u`, `v`) are given on 10 pressure levels, level 0 closest to the surface and level 9 closest to the top of the atmosphere; `clero.climate_analysis.pressure_levels(P0)` returns the level pressures.
+
+## Install
+
+```bash
+pip install clero
+```
+
+Optional extras:
+
+```bash
+pip install "clero[gpu]"    # torch, for CUDA batch prediction
+pip install "clero[demos]"  # jupyter, to run the notebooks in demos/
+```
+
+
+
+## Quickstart
+
+```python
+from clero import Emulator
+
+emu = Emulator()
+inputs = {
+    "T_star": 3000.0,     # K
+    "F_star": 1000.0,     # W/m^2
+    "radius": 1.0,        # Earth radii
+    "gravity": 9.8,       # m/s^2
+    "P_rot": 10.0,        # days
+    "P0": 1.0,            # bar
+    "CO2": 4.0e-4,        # volume fraction
+    "CH4": 0.0,           # volume fraction
+    "GCM": "um",
+}
+
+# predict climate
+mean = emu.predict(inputs)                           # CLERO's best point estimate of the climate
+samples = emu.sample(inputs, n_samples=100, seed=0)   # draws from climate distribution
+
+print(mean["surface_temperature"].shape)     # (32, 64)
+print(samples["surface_temperature"].shape)  # (100, 32, 64)
+```
+
+Don't want to spell out every parameter? Start from a bundled preset and override what you need:
+
+```python
+from clero import EARTH, M_EARTH, TRAPPIST1E
+mean = emu.predict({**EARTH, "CO2": 1.0e-3})   # Earth-like planet, overriden to have 1000 ppm CO2
+mean = emu.predict(M_EARTH)                    # Earth-like but around a 2600 K M dwarf (self-consistent 5 day rotation period)
+mean = emu.predict({**TRAPPIST1E, "CO2": 0.0, "CH4": 0.0})    # TRAPPIST-1e with an N₂-only atmosphere 
+```
+
+There's also a walk-through notebook, [demos/quickstart.ipynb](demos/quickstart.ipynb).
+
+## API
+
+Full reference (generated from the docstrings): [https://edstevenson.github.io/clero/](https://edstevenson.github.io/clero/)
+
+`Emulator` (prediction):
+
+
+| call                          | returns                                                                                   | output type                                                    |
+| ----------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `predict(inputs)`             | predict the climate (mean of climate distribution)                                        | `dict[str, ndarray]`, each dict value is `(32, 64)`            |
+| `sample(inputs, n_samples=…)` | draws from climate distribution                                                           | `dict[str, ndarray]`, each dict value is `(n_samples, 32, 64)` |
+| `to_physical` / `to_model`    | move a field dict between physical and model space (see [UNCERTAINTY.md](UNCERTAINTY.md)) | `dict[str, ndarray]`, shapes preserved                         |
+| `output_names`, `grid_shape`  | the 53 field names; `(32, 64)`                                                            | `list[str]`; `tuple[int, int]`                                 |
+
+
+Top-level helpers:
+
+
+| name                             | what                                                                                                                                               |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EARTH`, `M_EARTH`, `TRAPPIST1E` | preset input dicts (see [Quickstart](#quickstart))                                                                                                 |
+| `CORE_DOMAIN`, `EXTENDED_DOMAIN` | `(low, high)` per input, from [SCOPE.md](SCOPE.md)                                                                                                 |
+| `orbital_period(F_star, T_star)` | tidally locked rotation period in days from flux and stellar temperature, via empirical stellar relations; prefer a measured period when available |
+
+
+`clero.climate_analysis` (helper functions for analyzing climates):
+
+
+| group                | functions                                                                                                                   |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| scalar summaries     | `summarize_outputs`, `summary_table`, `global_mean`, `dayside_mean`, `nightside_mean`                                       |
+| vertical structure   | `vertical_profile`, `profile_table`, `profile_stats`, `stack_levels`, `pressure_levels`                                     |
+| physical diagnostics | `water_vapor_path`, `net_toa_radiation`, `ice_fraction`, `bond_albedo`                                                      |
+| maps & grids         | `surface_map`, `zonal_mean`, `meridional_mean`, `map_records`, `grid_records`                                               |
+| plots                | `field_map`, `ice_fraction_map`, `net_radiation_map`, `wind_map`, `wind_streamlines`, `zonal_cross_section`, `plot_profile` |
+| axes & weights       | `latitude_centers`, `longitude_centers`, `latitude_edges`, `longitude_edges`, `latitude_weights`                            |
+| io                   | `write_csv`                                                                                                                 |
+
+
+e.g.,
+
+```python
+from clero.climate_analysis import stack_levels
+climate_mean = emu.predict(inputs)
+T = stack_levels(climate_mean, "temperature")  # per-level fields -> one (10, 32, 64) array
+```
+
+
+
+## Batches and GPU
+
+`predict`/`sample` take a batch directly (list of dicts or a column dict). CPU stays pure NumPy:
+
+```python
+mean, variance = emu.predict(
+    inputs_list,                       # list of input dicts
+    space="model",
+    return_variance=True,
+    fields=["surface_temperature"]     # subset of outputs
+)
+```
+
+GPU needs torch with CUDA. Build the emulator with a device and the torch state is cached on first use:
+
+```python
+emu = Emulator(device="cuda")
+samples = emu.sample(inputs_list, n_samples=64)
+```
+
+
+
+## Citation
+
+If you use CLERO, please cite the paper:
+
+```bibtex
+// TODO: add correct CLERO paper citation here when available
+```
+

clero-0.1.0/README.md

@@ -0,0 +1,188 @@
+# CLERO (CLimate Emulator for ROcky exoplanets)
+
+![Tests](https://github.com/edstevenson/clero/actions/workflows/tests.yml/badge.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+![Docs](https://img.shields.io/badge/docs-pdoc-brightgreen.svg)
+![arXiv](https://img.shields.io/badge/arXiv-TODO-b31b1b.svg)  
+
+## What is CLERO
+
+CLERO is an exoGCM emulator that takes a hypothetical planet as input and outputs its 3D steady-state climate. It targets tidally locked ocean-covered rocky planets in or near the habitable zone; see [SCOPE.md](SCOPE.md) for detail on its scope of validity.
+
+CLERO computes a probability distribution over climates: `predict` returns its mean (our best point estimate of the climate) and `sample` returns draws from the distribution (see [UNCERTAINTY.md](UNCERTAINTY.md)).
+
+CLERO is based on Gaussian-process latent factor regression ([GPLFR](https://github.com/edstevenson/GPLFR)) and is trained on [ThousandWorlds](https://github.com/astroautomata/ThousandWorlds).
+
+Worked examples in [demos/](demos/).
+
+## Inputs
+
+
+| key     | unit            | notes                                                                                                    |
+| ------- | --------------- | -------------------------------------------------------------------------------------------------------- |
+| radius  | Earth radii     | planet radius                                                                                            |
+| gravity | m/s²            | surface gravity                                                                                          |
+| P_rot   | days            | rotation period (assumed = orbital, tidally locked)                                                      |
+| P0      | bar             | surface pressure                                                                                         |
+| CO2     | volume fraction | atmospheric CO2                                                                                          |
+| CH4     | volume fraction | atmospheric CH4                                                                                          |
+| F_star  | W/m²            | stellar flux at the planet                                                                               |
+| T_star  | K               | stellar effective temperature                                                                            |
+| GCM     | str             | climate model the prediction targets (optional, defaults to `"um"`; case-insensitive; see options below) |
+
+
+`CO2 + CH4 <= 1`; the rest of the atmosphere is N2. The validity ranges from [SCOPE.md](SCOPE.md) are available as `clero.CORE_DOMAIN` and `clero.EXTENDED_DOMAIN`.
+
+#### GCM options
+
+`um`, `exocam` (recommended — the two high-fidelity targets). `exoplasim` is a lower-fidelity exoGCM. `exocam-pre2022` and `lfric` should be avoided at inference time — `exocam-pre2022` is an older ExoCAM version, and  `lfric` has few training simulations.
+
+For predictions where self-consistency is important (e.g., spatially resolved plots), use a single emulated GCM. Where self-consistency is not needed (e.g., global means), once can average the emulated UM and ExoCAM predictions; this reduces dependence on either GCM's structural biases.
+
+## Outputs
+
+
+| fields                   | unit  |
+| ------------------------ | ----- |
+| `surface_temperature`    | K     |
+| `asr`, `olr`             | W/m²  |
+| `temperature_0..9`       | K     |
+| `specific_humidity_0..9` | kg/kg |
+| `cloud_fraction_0..9`    | 0–1   |
+| `u_0..9`, `v_0..9`       | m/s   |
+
+
+The 3D variables (`temperature`, `specific_humidity`, `cloud_fraction`, `u`, `v`) are given on 10 pressure levels, level 0 closest to the surface and level 9 closest to the top of the atmosphere; `clero.climate_analysis.pressure_levels(P0)` returns the level pressures.
+
+## Install
+
+```bash
+pip install clero
+```
+
+Optional extras:
+
+```bash
+pip install "clero[gpu]"    # torch, for CUDA batch prediction
+pip install "clero[demos]"  # jupyter, to run the notebooks in demos/
+```
+
+
+
+## Quickstart
+
+```python
+from clero import Emulator
+
+emu = Emulator()
+inputs = {
+    "T_star": 3000.0,     # K
+    "F_star": 1000.0,     # W/m^2
+    "radius": 1.0,        # Earth radii
+    "gravity": 9.8,       # m/s^2
+    "P_rot": 10.0,        # days
+    "P0": 1.0,            # bar
+    "CO2": 4.0e-4,        # volume fraction
+    "CH4": 0.0,           # volume fraction
+    "GCM": "um",
+}
+
+# predict climate
+mean = emu.predict(inputs)                           # CLERO's best point estimate of the climate
+samples = emu.sample(inputs, n_samples=100, seed=0)   # draws from climate distribution
+
+print(mean["surface_temperature"].shape)     # (32, 64)
+print(samples["surface_temperature"].shape)  # (100, 32, 64)
+```
+
+Don't want to spell out every parameter? Start from a bundled preset and override what you need:
+
+```python
+from clero import EARTH, M_EARTH, TRAPPIST1E
+mean = emu.predict({**EARTH, "CO2": 1.0e-3})   # Earth-like planet, overriden to have 1000 ppm CO2
+mean = emu.predict(M_EARTH)                    # Earth-like but around a 2600 K M dwarf (self-consistent 5 day rotation period)
+mean = emu.predict({**TRAPPIST1E, "CO2": 0.0, "CH4": 0.0})    # TRAPPIST-1e with an N₂-only atmosphere 
+```
+
+There's also a walk-through notebook, [demos/quickstart.ipynb](demos/quickstart.ipynb).
+
+## API
+
+Full reference (generated from the docstrings): [https://edstevenson.github.io/clero/](https://edstevenson.github.io/clero/)
+
+`Emulator` (prediction):
+
+
+| call                          | returns                                                                                   | output type                                                    |
+| ----------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `predict(inputs)`             | predict the climate (mean of climate distribution)                                        | `dict[str, ndarray]`, each dict value is `(32, 64)`            |
+| `sample(inputs, n_samples=…)` | draws from climate distribution                                                           | `dict[str, ndarray]`, each dict value is `(n_samples, 32, 64)` |
+| `to_physical` / `to_model`    | move a field dict between physical and model space (see [UNCERTAINTY.md](UNCERTAINTY.md)) | `dict[str, ndarray]`, shapes preserved                         |
+| `output_names`, `grid_shape`  | the 53 field names; `(32, 64)`                                                            | `list[str]`; `tuple[int, int]`                                 |
+
+
+Top-level helpers:
+
+
+| name                             | what                                                                                                                                               |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EARTH`, `M_EARTH`, `TRAPPIST1E` | preset input dicts (see [Quickstart](#quickstart))                                                                                                 |
+| `CORE_DOMAIN`, `EXTENDED_DOMAIN` | `(low, high)` per input, from [SCOPE.md](SCOPE.md)                                                                                                 |
+| `orbital_period(F_star, T_star)` | tidally locked rotation period in days from flux and stellar temperature, via empirical stellar relations; prefer a measured period when available |
+
+
+`clero.climate_analysis` (helper functions for analyzing climates):
+
+
+| group                | functions                                                                                                                   |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| scalar summaries     | `summarize_outputs`, `summary_table`, `global_mean`, `dayside_mean`, `nightside_mean`                                       |
+| vertical structure   | `vertical_profile`, `profile_table`, `profile_stats`, `stack_levels`, `pressure_levels`                                     |
+| physical diagnostics | `water_vapor_path`, `net_toa_radiation`, `ice_fraction`, `bond_albedo`                                                      |
+| maps & grids         | `surface_map`, `zonal_mean`, `meridional_mean`, `map_records`, `grid_records`                                               |
+| plots                | `field_map`, `ice_fraction_map`, `net_radiation_map`, `wind_map`, `wind_streamlines`, `zonal_cross_section`, `plot_profile` |
+| axes & weights       | `latitude_centers`, `longitude_centers`, `latitude_edges`, `longitude_edges`, `latitude_weights`                            |
+| io                   | `write_csv`                                                                                                                 |
+
+
+e.g.,
+
+```python
+from clero.climate_analysis import stack_levels
+climate_mean = emu.predict(inputs)
+T = stack_levels(climate_mean, "temperature")  # per-level fields -> one (10, 32, 64) array
+```
+
+
+
+## Batches and GPU
+
+`predict`/`sample` take a batch directly (list of dicts or a column dict). CPU stays pure NumPy:
+
+```python
+mean, variance = emu.predict(
+    inputs_list,                       # list of input dicts
+    space="model",
+    return_variance=True,
+    fields=["surface_temperature"]     # subset of outputs
+)
+```
+
+GPU needs torch with CUDA. Build the emulator with a device and the torch state is cached on first use:
+
+```python
+emu = Emulator(device="cuda")
+samples = emu.sample(inputs_list, n_samples=64)
+```
+
+
+
+## Citation
+
+If you use CLERO, please cite the paper:
+
+```bibtex
+// TODO: add correct CLERO paper citation here when available
+```
+

clero-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clero"
+version = "0.1.0"
+description = "CLERO: the CLimate Emulator for ROcky exoplanets (inference-only runtime)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Edward T. Stevenson", email = "es833@cam.ac.uk"}]
+keywords = ["exoplanets", "climate", "emulator", "Gaussian process", "GCM"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Astronomy",
+]
+dependencies = ["matplotlib>=3.7", "numpy>=2.0", "scipy>=1.10"]
+
+[project.urls]
+Homepage = "https://github.com/edstevenson/clero"
+Repository = "https://github.com/edstevenson/clero"
+Documentation = "https://edstevenson.github.io/clero/"
+
+[project.optional-dependencies]
+gpu = ["torch"]
+demos = ["nbformat", "nbclient", "ipykernel", "jupyter"]
+docs = ["pdoc"]
+dev = ["pytest", "clero[demos]"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["clero*"]
+
+[tool.setuptools.package-data]
+clero = ["_model_bundle/*"]
+
+[tool.ruff]
+line-length = 140
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

clero-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

clero-0.1.0/src/clero/__init__.py

@@ -0,0 +1,21 @@
+"""the **CL**imate **E**mulator for **RO**cky exoplanets.
+
+CLERO takes a hypothetical planet and returns its 3D steady-state climate as 53 fields on a
+32×64 latitude-longitude grid. It targets tidally locked ocean-covered rocky planets in or
+near the habitable zone. See the [README](https://github.com/edstevenson/clero#readme) for
+an introduction.
+"""
+
+from importlib.metadata import version
+
+from . import climate_analysis, inputs
+from .inference import Emulator
+from .inputs import CORE_DOMAIN, EARTH, EXTENDED_DOMAIN, M_EARTH, TRAPPIST1E, orbital_period
+
+__version__ = version("clero")
+
+__all__ = [  # order is the order on the documentation page
+    "Emulator",
+    "climate_analysis",
+    "inputs",
+]

clero-0.1.0/src/clero/_checkpoint.py

@@ -0,0 +1,48 @@
+"""Private bundle container helpers for CLERO inference."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+_GPLFR_REQUIRED_FILES = ("manifest.json", "gplfr_state.npz")
+_DEFAULT_CHECKPOINT = Path(__file__).resolve().parent / "_model_bundle"
+
+
+class _CheckpointBundle:
+    def __init__(self, root: Path, manifest: dict[str, Any], gplfr_state: dict[str, np.ndarray]):
+        self.root = root
+        self.manifest = manifest
+        self.gplfr_state = gplfr_state
+
+    @property
+    def input_names(self) -> list[str]:
+        return list(self.manifest["input_names"])
+
+    @property
+    def output_names(self) -> list[str]:
+        return list(self.manifest["output_names"])
+
+
+def _load_npz(path: Path) -> dict[str, np.ndarray]:
+    with np.load(path, allow_pickle=False) as data:
+        return {key: np.asarray(data[key]) for key in data.files}
+
+
+def _load_checkpoint(path: str | Path | None = None) -> _CheckpointBundle:
+    root = _DEFAULT_CHECKPOINT if path is None else Path(path)
+    if root.is_file():
+        root = root.parent
+    manifest_path = root / "manifest.json"
+    if not manifest_path.exists():
+        raise FileNotFoundError(manifest_path)
+    manifest = json.loads(manifest_path.read_text())
+    if manifest.get("model_type") != "gplfr_map":
+        raise ValueError("CLERO currently supports only gplfr_map bundles")
+    for name in _GPLFR_REQUIRED_FILES:
+        if not (root / name).exists():
+            raise FileNotFoundError(root / name)
+    return _CheckpointBundle(root=root, manifest=manifest, gplfr_state=_load_npz(root / "gplfr_state.npz"))