sagari 1.0.0__tar.gz

sagari-1.0.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 1.0.0 (2026-10-15)
+
+First public release of SAGARI (Schwarzschild Adaptive Gaussian-process Acquisition, Refinement, and
+Inference), accompanying Waters & Gültekin (2026).
+
+- `ParameterSpace`: bounds, linear and logarithmic axes, fixed parameters; YAML and dict input.
+- `SobolGlobalDesign` / `initial_design`: persistent scrambled-Sobol global design.
+- `propose_round`: refinement rounds by feasibility-weighted Expected Improvement with a nugget for the
+  model-to-model scatter, a training window in units of that scatter, a denoised incumbent, a two-scale
+  candidate pool, a minimum separation, verification of isolated low models, and a global Sobol share.
+- `smoothed_estimate`, `estimate_converged`: monitoring estimate and stopping rule; `trusted_best_point`.
+- `errorbar_round`, `inference_gp`, `gp_profiles`, `profile_verdict`, `out_of_sample`: error-bar rounds,
+  the inference surrogate (optionally with an automatically chosen training window) and its checks.
+- `posterior`: the ensemble-MCMC posterior on the supported surrogate, surrogate-marginalized quantiles and
+  mode shares, Δχ² profiles and their parametric-bootstrap widening.
+- `Campaign` and the `sagari` command line: file-based campaigns for clusters, and an in-process loop.
+- `replay`, `benchmark`: archive replays and the two-basin objective of the paper; `benchmarks/two_basin.py`.
+- Parity tests against the original campaign code of the paper, and a golden fixture written by it.
+- Four executed example notebooks (a first campaign; the cluster workflow; the final analysis on a two-solution
+  problem; the two-basin benchmark and an archive replay), a documentation site (concepts, cluster workflow,
+  configuration reference, analysis, reproducibility, FAQ), and example space and settings files.
+- `posterior.surface_draws` raises the covariance jitter when the factorization fails (posterior samples much
+  closer together than the kernel's length scales); the first attempt uses the paper's value.
+- Tested on Python 3.10–3.13, down to NumPy 1.26, SciPy 1.11, scikit-learn 1.3 and pandas 2.0, and up to
+  pandas 3.0.

sagari-1.0.0/CITATION.cff

@@ -0,0 +1,40 @@
+cff-version: 1.2.0
+title: "SAGARI: Schwarzschild Adaptive Gaussian-process Acquisition, Refinement, and Inference"
+message: "If you use this software, please cite the paper below and the software."
+type: software
+authors:
+  - family-names: Waters
+    given-names: Thomas K.
+    affiliation: University of Michigan
+    orcid: "https://orcid.org/0000-0002-5231-7240"
+  - family-names: Gültekin
+    given-names: Kayhan
+    affiliation: University of Michigan
+    orcid: "https://orcid.org/0000-0002-1146-0198"
+version: 1.0.0
+date-released: "2026-10-15"
+url: "https://github.com/thomas-k-waters/sagari"
+license: MIT
+keywords:
+  - astronomy
+  - supermassive black holes
+  - Schwarzschild modeling
+  - Bayesian optimization
+  - Gaussian processes
+abstract: >
+  SAGARI replaces the nested parameter grids of orbit-superposition modeling campaigns with adaptive
+  rounds: a scrambled Sobol initial design, refinement by feasibility-weighted Expected Improvement under a
+  Gaussian-process surrogate with an explicit term for the model-to-model scatter of chi2, a stopping rule on
+  smoothed parameter ranges, error-bar rounds that test the surrogate out of sample, and a posterior sampled
+  on the final surrogate. It needs only the parameters and chi2 of each model.
+preferred-citation:
+  type: article
+  authors:
+    - family-names: Waters
+      given-names: Thomas K.
+    - family-names: Gültekin
+      given-names: Kayhan
+  title: "Schwarzschild Orbit-library Modeling with an Order of Magnitude Fewer Models: Adaptive Gaussian-process Sampling and a Case Study of M 86"
+  journal: "The Astrophysical Journal"
+  year: 2026
+  notes: "submitted"

sagari-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas K. Waters
+
+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.

sagari-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md CHANGELOG.md CITATION.cff LICENSE
+recursive-include tests *.py *.json
+recursive-include examples *.py *.md
+recursive-include benchmarks *.py
+recursive-include docs *.py *.md *.rst
+global-exclude __pycache__ *.py[cod] .DS_Store

sagari-1.0.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: sagari
+Version: 1.0.0
+Summary: SAGARI: Schwarzschild Adaptive Gaussian-process Acquisition, Refinement, and Inference -- adaptive sampling for orbit-superposition modeling and other expensive, noisy chi2 surfaces
+Author-email: "Thomas K. Waters" <waterstk@umich.edu>
+License: MIT License
+        
+        Copyright (c) 2026 Thomas K. Waters
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/thomas-k-waters/sagari
+Project-URL: Bug Tracker, https://github.com/thomas-k-waters/sagari/issues
+Project-URL: Documentation, https://sagari.readthedocs.io
+Keywords: astronomy,black holes,Schwarzschild modeling,orbit superposition,Bayesian optimization,Gaussian process,expected improvement,Sobol sequence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: emcee>=3.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Requires-Dist: corner>=2.2; extra == "plot"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: myst-nb>=1.0; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Requires-Dist: matplotlib>=3.7; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# SAGARI
+
+**Schwarzschild Adaptive Gaussian-process Acquisition, Refinement, and Inference**
+
+[![Tests](https://github.com/thomas-k-waters/sagari/actions/workflows/tests.yml/badge.svg)](https://github.com/thomas-k-waters/sagari/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/sagari.svg)](https://pypi.org/project/sagari/)
+[![Documentation](https://readthedocs.org/projects/sagari/badge/?version=latest)](https://sagari.readthedocs.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Adaptive Gaussian-process sampling for Schwarzschild orbit-superposition modeling, and for any other model
+whose goodness of fit is an expensive, noisy χ².
+
+An orbit-superposition model costs hours of CPU time, and a nested parameter grid needs ~10⁴ of them.
+SAGARI replaces the grid with a sequence of rounds, each placed where a surrogate of the χ² surface predicts
+the largest gain, and stops the campaign when the answer stops moving. On the archived models of two published
+black-hole mass measurements it recovered the published mass in every replayed trial with **9 to 30 times fewer
+models** than the original campaigns.
+
+It is the method of
+
+> Waters & Gültekin (2026), *Schwarzschild Orbit-library Modeling with an Order of Magnitude Fewer Models:
+> Adaptive Gaussian-process Sampling and a Case Study of M 86*
+
+and reproduces the code used there exactly ([details](#fidelity-to-the-paper)).
+
+The package never runs a model. It proposes parameter sets and reads back their χ², so it can drive any code: an
+orbit-superposition pipeline on a cluster, a Jeans model, or a lookup in an archive.
+
+📖 **Documentation:** https://sagari.readthedocs.io
+
+## Installation
+
+```bash
+pip install sagari            # add [plot] for the example notebooks
+```
+
+Python ≥ 3.10. Depends on NumPy, SciPy, pandas, scikit-learn, emcee and PyYAML.
+
+## Quick start
+
+```python
+import sagari as sg
+
+space = sg.ParameterSpace.from_dict({"parameters": {
+    "mbh":         {"bounds": [1e6, 1e10], "scale": "log"},
+    "upsilon":     {"bounds": [1.0, 10.0]},
+    "v_c":         {"bounds": [0.0, 500.0]},
+    "inclination": {"value": 60.0},            # fixed
+}})
+
+def my_model(design):                          # a DataFrame of parameter sets -> one chi2 per row
+    ...                                        # (NaN for a model that failed)
+
+c = sg.Campaign.create("my_campaign", space, converge_on=["mbh", "upsilon"])
+results = c.run(my_model)                      # Sobol design, search rounds, stopping rule, error-bar rounds
+
+gp, _, _ = c.surrogate(results)                # the final surrogate of the chi2 surface
+post = sg.posterior.sample_posterior(gp, space)
+```
+
+## On a cluster
+
+When each model is a batch job, the campaign lives in a directory and moves one round at a time:
+
+```bash
+sagari init my_campaign --space space.yaml --converge-on mbh,upsilon
+sagari next my_campaign                          # writes my_campaign/rounds/round_000.csv
+#   ... run the models of the round with your own code; add model_id,chi2 rows to results.csv ...
+sagari next my_campaign --results results.csv    # the next round (search or error bars), or "done"
+sagari status my_campaign --results results.csv  # ranges per round, stopping rule, out-of-sample checks
+sagari posterior my_campaign --results results.csv --out posterior --profiles
+```
+
+Failed models are written as `chi2 = nan` and kept: the search learns to avoid where models fail.
+`examples/sco_runalls.py` connects a campaign to the Fortran pipeline of the paper (`runallt` commands file in,
+`cres` files out).
+
+## How it works
+
+1. **Initial design**: a scrambled Sobol sequence over the box, continued by every later round.
+2. **Search rounds**: a Gaussian process with a Matérn 5/2 kernel and an explicit nugget for the model-to-model
+   scatter of χ², fitted near the minimum. A second GP fitted to every model keeps the search out of regions that
+   are hopeless or where models fail. Each round places 65% of its models by feasibility-weighted Expected
+   Improvement, with a denoised incumbent, two-scale candidates and a minimum separation, and verifies isolated
+   low models by their neighbours. The other 35% continues the Sobol sequence.
+3. **Stopping rule**: smoothed 16–84% ranges of the parameters you care about. The search stops when they move
+   by less than 0.2 of their width, after at least two refinement rounds.
+4. **Error-bar rounds**: models fill the acceptable region and the parameter profiles. Each model's χ² is
+   predicted before it runs, so the surrogate is tested out of sample.
+5. **Posterior**: MCMC on the final surrogate where models constrain it, averaged over the surrogate's own
+   uncertainty, plus Δχ² profile intervals.
+
+The defaults are the settings adopted and validated in the paper.
+
+## Example notebooks
+
+| notebook | |
+| --- | --- |
+| [01 Your first campaign](examples/notebooks/01_quickstart.ipynb) | a complete campaign in Python on a noisy analytic χ² |
+| [02 A campaign on a cluster](examples/notebooks/02_cluster_workflow.ipynb) | round files, results tables, failures, narrowing the box, the CLI |
+| [03 From the surrogate to a measurement](examples/notebooks/03_analysis.ipynb) | profiles, posteriors, two solutions, surrogate uncertainty |
+| [04 Benchmark and replay](examples/notebooks/04_benchmark_and_replay.ipynb) | the paper's two-basin benchmark and a replay on an archive |
+
+## Fidelity to the paper
+
+The package is a port of the campaign code used in the paper, not a reimplementation:
+
+- `tests/test_parity.py` runs the original code and the package side by side and requires identical output at
+  every stage (needs the original code; see the docs).
+- `tests/test_golden.py` checks the same outputs against a fixture written by the original code, and runs anywhere.
+- Replays of the paper's NGC 5102 and NGC 3258 campaigns, and its two-basin benchmark
+  (`benchmarks/two_basin.py`), are reproduced model for model.
+
+Exact repetition from a seed also needs the same library versions and the same number of linear-algebra threads
+(`OMP_NUM_THREADS=1`).
+
+## Citing
+
+Please cite Waters & Gültekin (2026) and the software (`CITATION.cff`).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

sagari-1.0.0/README.md

@@ -0,0 +1,123 @@
+# SAGARI
+
+**Schwarzschild Adaptive Gaussian-process Acquisition, Refinement, and Inference**
+
+[![Tests](https://github.com/thomas-k-waters/sagari/actions/workflows/tests.yml/badge.svg)](https://github.com/thomas-k-waters/sagari/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/sagari.svg)](https://pypi.org/project/sagari/)
+[![Documentation](https://readthedocs.org/projects/sagari/badge/?version=latest)](https://sagari.readthedocs.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Adaptive Gaussian-process sampling for Schwarzschild orbit-superposition modeling, and for any other model
+whose goodness of fit is an expensive, noisy χ².
+
+An orbit-superposition model costs hours of CPU time, and a nested parameter grid needs ~10⁴ of them.
+SAGARI replaces the grid with a sequence of rounds, each placed where a surrogate of the χ² surface predicts
+the largest gain, and stops the campaign when the answer stops moving. On the archived models of two published
+black-hole mass measurements it recovered the published mass in every replayed trial with **9 to 30 times fewer
+models** than the original campaigns.
+
+It is the method of
+
+> Waters & Gültekin (2026), *Schwarzschild Orbit-library Modeling with an Order of Magnitude Fewer Models:
+> Adaptive Gaussian-process Sampling and a Case Study of M 86*
+
+and reproduces the code used there exactly ([details](#fidelity-to-the-paper)).
+
+The package never runs a model. It proposes parameter sets and reads back their χ², so it can drive any code: an
+orbit-superposition pipeline on a cluster, a Jeans model, or a lookup in an archive.
+
+📖 **Documentation:** https://sagari.readthedocs.io
+
+## Installation
+
+```bash
+pip install sagari            # add [plot] for the example notebooks
+```
+
+Python ≥ 3.10. Depends on NumPy, SciPy, pandas, scikit-learn, emcee and PyYAML.
+
+## Quick start
+
+```python
+import sagari as sg
+
+space = sg.ParameterSpace.from_dict({"parameters": {
+    "mbh":         {"bounds": [1e6, 1e10], "scale": "log"},
+    "upsilon":     {"bounds": [1.0, 10.0]},
+    "v_c":         {"bounds": [0.0, 500.0]},
+    "inclination": {"value": 60.0},            # fixed
+}})
+
+def my_model(design):                          # a DataFrame of parameter sets -> one chi2 per row
+    ...                                        # (NaN for a model that failed)
+
+c = sg.Campaign.create("my_campaign", space, converge_on=["mbh", "upsilon"])
+results = c.run(my_model)                      # Sobol design, search rounds, stopping rule, error-bar rounds
+
+gp, _, _ = c.surrogate(results)                # the final surrogate of the chi2 surface
+post = sg.posterior.sample_posterior(gp, space)
+```
+
+## On a cluster
+
+When each model is a batch job, the campaign lives in a directory and moves one round at a time:
+
+```bash
+sagari init my_campaign --space space.yaml --converge-on mbh,upsilon
+sagari next my_campaign                          # writes my_campaign/rounds/round_000.csv
+#   ... run the models of the round with your own code; add model_id,chi2 rows to results.csv ...
+sagari next my_campaign --results results.csv    # the next round (search or error bars), or "done"
+sagari status my_campaign --results results.csv  # ranges per round, stopping rule, out-of-sample checks
+sagari posterior my_campaign --results results.csv --out posterior --profiles
+```
+
+Failed models are written as `chi2 = nan` and kept: the search learns to avoid where models fail.
+`examples/sco_runalls.py` connects a campaign to the Fortran pipeline of the paper (`runallt` commands file in,
+`cres` files out).
+
+## How it works
+
+1. **Initial design**: a scrambled Sobol sequence over the box, continued by every later round.
+2. **Search rounds**: a Gaussian process with a Matérn 5/2 kernel and an explicit nugget for the model-to-model
+   scatter of χ², fitted near the minimum. A second GP fitted to every model keeps the search out of regions that
+   are hopeless or where models fail. Each round places 65% of its models by feasibility-weighted Expected
+   Improvement, with a denoised incumbent, two-scale candidates and a minimum separation, and verifies isolated
+   low models by their neighbours. The other 35% continues the Sobol sequence.
+3. **Stopping rule**: smoothed 16–84% ranges of the parameters you care about. The search stops when they move
+   by less than 0.2 of their width, after at least two refinement rounds.
+4. **Error-bar rounds**: models fill the acceptable region and the parameter profiles. Each model's χ² is
+   predicted before it runs, so the surrogate is tested out of sample.
+5. **Posterior**: MCMC on the final surrogate where models constrain it, averaged over the surrogate's own
+   uncertainty, plus Δχ² profile intervals.
+
+The defaults are the settings adopted and validated in the paper.
+
+## Example notebooks
+
+| notebook | |
+| --- | --- |
+| [01 Your first campaign](examples/notebooks/01_quickstart.ipynb) | a complete campaign in Python on a noisy analytic χ² |
+| [02 A campaign on a cluster](examples/notebooks/02_cluster_workflow.ipynb) | round files, results tables, failures, narrowing the box, the CLI |
+| [03 From the surrogate to a measurement](examples/notebooks/03_analysis.ipynb) | profiles, posteriors, two solutions, surrogate uncertainty |
+| [04 Benchmark and replay](examples/notebooks/04_benchmark_and_replay.ipynb) | the paper's two-basin benchmark and a replay on an archive |
+
+## Fidelity to the paper
+
+The package is a port of the campaign code used in the paper, not a reimplementation:
+
+- `tests/test_parity.py` runs the original code and the package side by side and requires identical output at
+  every stage (needs the original code; see the docs).
+- `tests/test_golden.py` checks the same outputs against a fixture written by the original code, and runs anywhere.
+- Replays of the paper's NGC 5102 and NGC 3258 campaigns, and its two-basin benchmark
+  (`benchmarks/two_basin.py`), are reproduced model for model.
+
+Exact repetition from a seed also needs the same library versions and the same number of linear-algebra threads
+(`OMP_NUM_THREADS=1`).
+
+## Citing
+
+Please cite Waters & Gültekin (2026) and the software (`CITATION.cff`).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

sagari-1.0.0/benchmarks/two_basin.py

@@ -0,0 +1,129 @@
+"""The two-basin benchmark of the paper (Section 4.3 and Appendix B), run with sagari.
+
+Each trial is a campaign of 256 Sobol points and five rounds of 128 (896 models) on the synthetic objective
+of :mod:`sagari.benchmark`, for three samplers:
+
+  full      the method of the paper (Matern 5/2 kernel, 30 sigma training window, 35% global share, plug-in
+            incumbent, two-scale candidates, minimum separation, verification of isolated models)
+  ablated   the same search without its robustness measures: squared-exponential kernel, no training window,
+            15% global share, the lowest model as the incumbent, no local candidates, no minimum separation
+            or verification, one candidate pool for the whole campaign (the feasibility weighting is kept)
+  sobol     Sobol sampling alone
+
+After every round it records whether the best point of the smoothed estimate lies in the deeper basin, its
+M_BH error, the models within 2 sigma of the deeper minimum, and the share of local points in the failure
+region. Trials use seeds 1000, 1001, ... as in the paper (100 trials: Figure 1).
+
+    python two_basin.py [n_trials] [--hopeless] [--out results/two_basin.csv] [--procs N]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from multiprocessing import Pool
+from pathlib import Path
+
+for _v in ("OMP_NUM_THREADS", "OPENBLAS_NUM_THREADS", "MKL_NUM_THREADS", "VECLIB_MAXIMUM_THREADS"):
+    os.environ.setdefault(_v, "1")
+
+import numpy as np  # noqa: E402
+import pandas as pd  # noqa: E402
+
+import sagari as sg  # noqa: E402
+from sagari.benchmark import NOISE, PILOT_SPACE, TwoBasin  # noqa: E402
+
+N0, NR, N_ROUNDS = 256, 128, 5
+WASTE_ABOVE = 2000.0           # a local point with true Delta chi2 above this is wasted
+VARIANTS = {
+    "full": dict(kernel="matern52", train_window=30.0, global_fraction=0.35),
+    "ablated": dict(kernel="rbf", train_window=None, global_fraction=0.15, incumbent="raw", n_local_candidates=0,
+                    min_separation=0.0, verify=False, redraw_candidates=False),
+    "sobol": None,
+}
+
+
+def trial(args):
+    variant, seed, hopeless = args
+    obj = TwoBasin(hopeless=hopeless)
+    space = PILOT_SPACE
+    rng = np.random.default_rng(seed)
+    sob = sg.SobolGlobalDesign(space.dim, seed)
+    d = sg.initial_design(space, N0, sob)
+    table = d[space.free_params].copy()
+    table["chi2"] = obj(d, rng)
+    rows, waste = [], []
+    for rnd in range(N_ROUNDS + 1):
+        if rnd > 0:
+            if VARIANTS[variant] is None:
+                d = sg.initial_design(space, NR, sob)
+            else:
+                # noise_diagnostic=False: the band for verifying isolated models is twice the sd of the 20 lowest
+                # chi2, as in the benchmark runs of the paper
+                d = sg.propose_round(table, space, NR, sob, seed=seed, noise_diagnostic=False, **VARIANTS[variant])
+                loc = (d["stage"] != "sobol_global_continuation").values
+                if loc.any():
+                    waste.append(float(((obj.true(space.to_unit(d[loc]))[0] - 1000) > WASTE_ABOVE).mean()))
+            new = d[space.free_params].copy()
+            new["chi2"] = obj(d, rng)
+            table = pd.concat([table, new], ignore_index=True)
+        # The runs of the paper drew a search pool for a diagnostic not reported here from the generator that also
+        # draws the chi2 scatter; draw the same numbers so that every later round sees identical scatter.
+        rng.random((20000, space.dim))
+        for _ in range(50):
+            rng.standard_normal((20, space.dim))
+        f, in_n = obj.true(space.to_unit(table))
+        row = dict(variant=variant, seed=seed, round=rnd, n_models=len(table), n_failed=int(table["chi2"].isna().sum()),
+                   waste=float(np.mean(waste)) if waste else np.nan, n_in_N=int((((f - 1000) < 2 * NOISE) & in_n).sum()))
+        est = sg.smoothed_estimate(table, space, seed=seed, kernel="matern52", train_window=30.0)
+        if est is not None:
+            row.update(est_found=obj.found(est), est_mbh_err=obj.mbh_error(est),
+                       est_mbh_covers=bool(est["mbh"][1] <= 8.0e8 <= est["mbh"][2]))
+        rows.append(row)
+    return rows
+
+
+def wilson(k, n, z=1.96):
+    p = k / n
+    c = (p + z * z / (2 * n)) / (1 + z * z / n)
+    h = z * np.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / (1 + z * z / n)
+    return c - h, c + h
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("n_trials", type=int, nargs="?", default=20)
+    ap.add_argument("--hopeless", action="store_true", help="add the region of failed and very-high-chi2 models")
+    ap.add_argument("--variants", default="full,ablated,sobol")
+    ap.add_argument("--out", default=None)
+    ap.add_argument("--procs", type=int, default=None)
+    a = ap.parse_args()
+    out = Path(a.out or f"results/two_basin_{'hopeless' if a.hopeless else 'plain'}.csv")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    part = out.with_suffix(".jsonl")
+    done = set()
+    if part.exists():          # finished trials are kept, so an interrupted run loses nothing
+        done = {(r[0]["variant"], r[0]["seed"]) for r in map(json.loads, part.read_text().splitlines())}
+    jobs = [(v, 1000 + s, a.hopeless) for v in a.variants.split(",") for s in range(a.n_trials)
+            if (v, 1000 + s) not in done]
+    print(f"{len(jobs)} trials to run ({len(done)} already in {part})", flush=True)
+    with Pool(a.procs) as pool:
+        for rs in pool.imap_unordered(trial, jobs):
+            with open(part, "a") as f:
+                f.write(json.dumps(rs, default=float) + "\n")
+            print(f"{rs[0]['variant']} {rs[0]['seed']}: found={rs[-1].get('est_found')}", flush=True)
+    rows = [r for rs in map(json.loads, part.read_text().splitlines()) for r in rs if r["seed"] < 1000 + a.n_trials]
+    df = pd.DataFrame(rows)
+    df.to_csv(out, index=False)
+    fin = df[df["n_models"] == N0 + N_ROUNDS * NR]
+    print(f"\nat {N0 + N_ROUNDS * NR} models ({'with' if a.hopeless else 'without'} the failure region):")
+    for v, g in fin.groupby("variant"):
+        k, n = int(g["est_found"].sum()), len(g)
+        lo, hi = wilson(k, n)
+        print(f"  {v:8s} deeper basin found in {k}/{n} ({100 * lo:.0f}-{100 * hi:.0f}%), median M_BH error "
+              f"{g['est_mbh_err'].median():.2f} dex, median models within 2 sigma of it {g['n_in_N'].median():.0f}, "
+              f"local points wasted {100 * g['waste'].mean():.0f}%")
+
+
+if __name__ == "__main__":
+    main()

sagari-1.0.0/docs/analysis.md

@@ -0,0 +1,77 @@
+# From the final surrogate to a measurement
+
+The constraints come from the **inference surrogate**: a GP fitted to every model inside the training window,
+with a nugget for the model-to-model scatter. Do not use the lowest model. With scatter, the lowest of many
+models lies well below the smooth minimum (in M86, 17 below).
+
+```python
+import sagari as sg
+from sagari import posterior as po
+
+c = sg.Campaign("my_campaign")
+gp, chi2_min, threshold = c.surrogate("results.csv")
+print(gp.scatter)                    # sigma_chi2, the fitted model-to-model scatter
+```
+
+Outside a campaign directory, use `sg.inference_gp(table, space)` on any table of models.
+
+## Profiles: Δχ² intervals
+
+```python
+prof = po.profiles(gp, space, seed=c.seed)                         # every free parameter
+iv = po.profile_intervals(prof, space, levels=(1.0, 4.0, 10.0))     # {param: {level: [(lo, hi), ...]}}
+```
+
+A profile minimizes the surrogate mean over all other parameters at each value of one. Points are trusted only
+where models constrain the surrogate (latent sd ≤ 2σ). Intervals can have several pieces when the region is
+disconnected. The ends move when the scatter is redrawn; `profile_interval_bootstrap` refits the surrogate to
+parametric-bootstrap copies and gives their spread.
+
+## The posterior
+
+```python
+post = po.sample_posterior(gp, space)          # emcee: 32 walkers, 25000 steps, 5000 burn-in
+post["mbh"].quantile([0.1585, 0.5, 0.8415])
+```
+
+This samples $p\propto\exp(-\mu/2)$ with priors uniform in the unit cube (log-uniform on log axes). The posterior
+is zero wherever the surrogate's latent sd exceeds $2\sigma_{\chi^2}$: there no models constrain it, and a sampler
+would settle in any low value the surrogate extrapolates. The samples in the unit cube are in
+`post.attrs["unit"]`.
+
+## Averaging over the surrogate's uncertainty
+
+The surrogate is fitted to noisy models, so its mean is uncertain too. This matters most when two solutions
+differ by less than the scatter:
+
+```python
+idx, D, D_refit = po.surface_draws(gp, post.attrs["unit"])        # 2000 latent draws at 3000 samples (+300 refits)
+lo, med, hi = po.pooled_quantiles(post["mbh"].values[idx], D)     # the surrogate-marginalized posterior
+shares = po.mode_shares(D, post["upsilon"].values[idx] > 7.0)     # how uncertain the split between two solutions is
+```
+
+`D` holds joint draws of the surrogate's latent error (the scatter removed, so it is not counted twice).
+`D_refit` comes from refits to the models with their χ² redrawn from the scatter. Reweighting the samples by each
+draw gives the posterior of that realization of the surface. Pooling the reweighted posteriors gives the
+surrogate-marginalized posterior that the paper adopts.
+
+## Other priors
+
+Every prior is a reweighting of the samples. For a prior uniform in $r_c$ instead of $\log r_c$:
+
+```python
+w = post["r_c"].values[idx]
+po.pooled_quantiles(post["mbh"].values[idx], D, prior_w=w)
+po.mode_shares(D, select, prior_w=w)
+```
+
+## Checking the surrogate
+
+- **Out of sample**: every error-bar round stores the prediction made before each model ran;
+  `sagari status` reports the rms of $z=(\chi^2-\mu)/s$ (≈1 for a calibrated surrogate) and the fractions
+  beyond ±2. `sg.out_of_sample(round_table, chi2)` computes it directly.
+- **Leave-one-out**: `po.loo(gp)` returns the closed-form leave-one-out residuals of the training models.
+- **The scatter**: `gp.scatter` should be stable once the region of the minimum is sampled.
+  `sg.errorbars.window_check(gp)` compares it with the leave-one-out rms near the floor.
+
+The [analysis notebook](notebooks/03_analysis.ipynb) runs all of this on a two-solution problem.

sagari-1.0.0/docs/api.rst

@@ -0,0 +1,32 @@
+API
+===
+
+.. automodule:: sagari.space
+   :members:
+
+.. automodule:: sagari.sobol
+   :members:
+
+.. automodule:: sagari.acquisition
+   :members:
+
+.. automodule:: sagari.monitor
+   :members:
+
+.. automodule:: sagari.errorbars
+   :members:
+
+.. automodule:: sagari.posterior
+   :members:
+
+.. automodule:: sagari.campaign
+   :members:
+
+.. automodule:: sagari.gp
+   :members:
+
+.. automodule:: sagari.replay
+   :members:
+
+.. automodule:: sagari.benchmark
+   :members:

sagari-1.0.0/docs/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```

sagari-1.0.0/docs/citing.md

@@ -0,0 +1,8 @@
+# Citing
+
+If you use SAGARI, please cite the paper that describes and validates the method:
+
+> Waters, T. K., & Gültekin, K. 2026, *Schwarzschild Orbit-library Modeling with an Order of Magnitude Fewer
+> Models: Adaptive Gaussian-process Sampling and a Case Study of M 86*, ApJ, submitted
+
+and the software itself (`CITATION.cff` in the repository; the archived version on Zenodo).