pychmp 0.1.0__tar.gz

pychmp-0.1.0/.gitattributes

@@ -0,0 +1,6 @@
+* text=auto
+
+*.py text eol=lf
+*.sh text eol=lf
+*.cmd text eol=crlf
+*.bat text eol=crlf

pychmp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,24 @@
+name: Bug report
+description: Report a reproducible problem
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Minimal reproducible steps
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true

pychmp-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,18 @@
+name: Feature request
+description: Propose an enhancement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What need does this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the desired behavior
+    validations:
+      required: true

pychmp-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+Describe the problem and the change.
+
+## Provenance Notes
+
+If this PR ports or mirrors logic from IDL gxmodelfitting,
+add concise references to source routines and rationale.
+
+## Validation
+
+- [ ] Tests pass locally
+- [ ] CI passes
+- [ ] Documentation updated (if needed)

pychmp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Run tests
+        run: pytest -q

pychmp-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+
+# Packaging
+*.egg-info/
+dist/
+build/
+
+# Testing
+.pytest_cache/
+.coverage
+
+# Virtual environments
+.venv/
+venv/
+.conda/
+
+# IDE
+.vscode/
+.idea/
+
+# macOS
+.DS_Store

pychmp-0.1.0/.zenodo.json

@@ -0,0 +1,44 @@
+{
+  "title": "pyCHMP",
+  "description": "Python Coronal Heating Modeling Pipeline for data-constrained fitting of GX Simulator active-region models.",
+  "license": "BSD-3-Clause",
+  "creators": [
+    {
+      "name": "Nita, Gelu",
+      "affiliation": "SUNCAST-ORG"
+    },
+    {
+      "name": "Kuznetsov, Alexey"
+    }
+  ],
+  "keywords": [
+    "solar physics",
+    "GX Simulator",
+    "EBTEL",
+    "model fitting",
+    "microwave",
+    "EUV"
+  ],
+  "related_identifiers": [
+    {
+      "identifier": "https://github.com/kuznetsov-radio/gxmodelfitting",
+      "relation": "isDerivedFrom",
+      "scheme": "url"
+    },
+    {
+      "identifier": "10.5281/zenodo.19057091",
+      "relation": "isSupplementTo",
+      "scheme": "doi"
+    },
+    {
+      "identifier": "10.5281/zenodo.15660387",
+      "relation": "isSupplementTo",
+      "scheme": "doi"
+    },
+    {
+      "identifier": "10.3847/1538-4365/acd343",
+      "relation": "isDerivedFrom",
+      "scheme": "doi"
+    }
+  ]
+}

pychmp-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-04
+
+First public release of the unified artifact and adaptive-search infrastructure,
+intended for observational fitting workflows together with [pyAMPP](https://pypi.org/project/pyampp/)
+and [pyGXrender](https://pypi.org/project/pyGXrender/).
+
+### Added
+
+- Unified HDF5 layout: slice-level `common`, per-search `grid_points`, shared `map_store`.
+- Adaptive runner: `examples/python/adaptive_ab_search_single_observation.py` with live
+  `pychmp-view` refresh, warm Q₀ start from `map_store`, and HDF5 grid-point events.
+- CLI utilities: `pychmp-rescore`, `pychmp-repair-grid-trial-maps`.
+- Targeted search modes: `--recompute-search-id` (repair incomplete/contract-broken cells),
+  `--expand-grid-search-id` (widen `a`/`b` with prior-footprint wall seed on resume).
+- Library modules: `grid_points`, `slice_map_index`, `warm_q0`, `search_contract`,
+  `refresh_signal`, expand/resume helpers in `ab_search`.
+- Viewer: heatmap log scale, improved runner liveness vs terminal search status,
+  HDF5 read retries, dedicated heatmap colorbar axes.
+
+### Changed
+
+- Version `0.1.0a2` → `0.1.0` (drops alpha pre-release label for this artifact generation).
+- Consolidated sparse/fixed/adaptive point metadata under one schema for `pychmp-view`.
+- Documentation: `README.md`, `docs/workflow_architecture.md`, `docs/artifact_data_contract.rst`.
+
+### Removed
+
+- `examples/python/adaptive_ab_search_single_frequency.py` and its dedicated CLI tests
+  (use `adaptive_ab_search_single_observation.py`).
+
+### Migration from 0.1.0a2
+
+- Artifacts produced with `0.1.0a2` may not resume cleanly; prefer a new search identity
+  or `--recompute-search-id` / `--expand-grid-search-id` after validating compatibility.
+- Pin versions in publications: `pychmp==0.1.0`, `pyampp>=1.0.2`, and your chosen `pyGXrender`
+  release; record model/observation provenance in the artifact.
+
+### Known limitations
+
+- Cherry-picked refit of individual grid points under an existing `search_id` is planned
+  but not shipped in 0.1.0 (see project implementation notes).
+- Full observational runs still require external model H5, EBTEL, and observation inputs
+  (for example the `pyGXrender-test-data` checkout referenced in `README.md`).
+
+[0.1.0]: https://github.com/suncast-org/pyCHMP/releases/tag/v0.1.0

pychmp-0.1.0/CITATION.cff

@@ -0,0 +1,65 @@
+cff-version: 1.2.0
+title: "pyCHMP"
+version: 0.1.0
+date-released: 2026-06-04
+message: "If you use this software, please cite it using the metadata below."
+type: software
+authors:
+  - family-names: "Nita"
+    given-names: "Gelu"
+  - family-names: "Kuznetsov"
+    given-names: "Alexey"
+repository-code: "https://github.com/suncast-org/pyCHMP"
+url: "https://github.com/suncast-org/pyCHMP"
+license: "BSD-3-Clause"
+keywords:
+  - solar physics
+  - GX Simulator
+  - EBTEL
+  - model fitting
+  - microwave
+  - EUV
+abstract: >-
+  pyCHMP is a Python coronal heating model fitting pipeline for data-constrained
+  exploration of EBTEL parameter space using pyAMPP models and pyGXrender
+  synthetic observables.
+references:
+  - type: software
+    title: "gxmodelfitting"
+    url: "https://github.com/kuznetsov-radio/gxmodelfitting"
+  - type: software
+    title: "gximagecomputing"
+    url: "https://github.com/kuznetsov-radio/gximagecomputing"
+  - type: software
+    title: "pyAMPP"
+    url: "https://github.com/suncast-org/pyAMPP"
+    doi: "10.5281/zenodo.19057091"
+  - type: software
+    title: "pyAMPP (all versions)"
+    doi: "10.5281/zenodo.15660387"
+  - type: article
+    title: "Data-constrained Solar Modeling with GX Simulator"
+    authors:
+      - family-names: "Nita"
+        given-names: "Gelu M."
+      - family-names: "Fleishman"
+        given-names: "Gregory D."
+      - family-names: "Kuznetsov"
+        given-names: "Alexey A."
+      - family-names: "Anfinogentov"
+        given-names: "Sergey A."
+      - family-names: "Stupishin"
+        given-names: "Alexey G."
+      - family-names: "Kontar"
+        given-names: "Eduard P."
+      - family-names: "Schonfeld"
+        given-names: "Samuel J."
+      - family-names: "Klimchuk"
+        given-names: "James A."
+      - family-names: "Gary"
+        given-names: "Dale E."
+    journal: "The Astrophysical Journal Supplement Series"
+    year: 2023
+    volume: 267
+    issue: 1
+    doi: "10.3847/1538-4365/acd343"

pychmp-0.1.0/CODEOWNERS

@@ -0,0 +1 @@
+* @Gelu-Nita

pychmp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to pyCHMP
+
+## Workflow
+
+- Create a feature branch from `main`.
+- Open a pull request into `main`.
+- Keep changes scoped and documented.
+- Ensure CI passes before merge.
+
+## Architecture
+
+Keep the package layering clear:
+
+- `src/pychmp/` contains package-level primitives and reusable workflow logic.
+- `examples/` contains runnable real-data and validation workflows.
+- `scripts/` contains tracked shell launchers that wrap those Python workflows.
+
+For the current observational fitting/search stack:
+
+- `fit_q0_to_observation(...)` is the core single-point numerical primitive.
+- `examples/fit_q0_obs_map.py` is the single-point real observational workflow.
+- `examples/scan_ab_obs_map.py` is the fixed-grid / sparse-grid orchestration layer.
+- `search_local_minimum_ab(...)` is the adaptive `(a, b)` search core.
+- `examples/python/adaptive_ab_search_single_observation.py` is the real observational wrapper around the adaptive search core.
+
+For observational-map ingestion, prefer reusing:
+
+- `load_obs_map(...)`
+- `validate_obs_map_identity(...)`
+- `estimate_obs_map_noise(...)`
+
+Do not introduce new script-local FITS/refmap loaders unless there is a clear reason they cannot fit the shared `obs_maps.py` contract.
+
+For artifact work, align new storage and viewer changes with the tracked
+contract in [docs/artifact_data_contract.rst](docs/artifact_data_contract.rst).
+Do not introduce new file families or MW-only metadata assumptions if the same
+goal can be expressed through the canonical slice / trial / solution model.
+
+## Commit style
+
+Use clear, action-oriented commit messages.
+
+## Scientific provenance
+
+When implementing logic ported from IDL CHMP/gxmodelfitting, include concise provenance notes in code docstrings and PR descriptions.
+
+## Testing
+
+Run locally before opening PR:
+
+```bash
+pytest -q
+```

pychmp-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, SUNCAST-ORG
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pychmp-0.1.0/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: pychmp
+Version: 0.1.0
+Summary: Python Coronal Heating Modeling Pipeline for data-constrained fitting of GX models
+Project-URL: Homepage, https://github.com/suncast-org/pyCHMP
+Project-URL: Repository, https://github.com/suncast-org/pyCHMP
+Project-URL: Algorithmic Provenance, https://github.com/kuznetsov-radio/gxmodelfitting
+Author: Gelu Nita, Alexey Kuznetsov
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: ebtel,euv,gx-simulator,model-fitting,radio,solar-physics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Requires-Dist: astropy>=5
+Requires-Dist: h5py>=3.8
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=1.25
+Requires-Dist: scipy>=1.11
+Provides-Extra: dev
+Requires-Dist: bumpver>=2024.1130; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyCHMP
+
+Python Coronal Heating Modeling Pipeline for data-constrained fitting of GX Simulator active-region models.
+
+## Overview
+
+pyCHMP is a Python application for parameter-space exploration of EBTEL-based magneto-thermal models in search of best agreement between synthetic and observational maps.
+
+Initial scope:
+- Replicate the validated CHMP search strategy used in the IDL GX Simulator ecosystem.
+- Use pyAMPP-produced models and pyGXrender synthetic maps.
+- Support microwave fitting first, then extend the same workflow to EUV constraints.
+
+## Provenance and Acknowledgement
+
+This project is algorithmically grounded in the model-fitting approach developed and maintained by Alexey Kuznetsov in gxmodelfitting:
+
+- https://github.com/kuznetsov-radio/gxmodelfitting
+
+pyCHMP is an independent Python implementation under SUNCAST-ORG. The intent is scientific reproducibility and extensibility, while preserving explicit provenance and credit.
+
+## Installation
+
+### pyCHMP only
+
+```bash
+pip install pychmp
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+### SUNCAST fitting stack (pyAMPP → pyGXrender → pyCHMP)
+
+Observational fitting uses three installable packages. Pin versions in publications
+(for example `pyampp==1.0.2`, your chosen `pyGXrender` release, and `pychmp==0.1.0`).
+
+```bash
+pip install -U pip setuptools wheel
+pip install "pyampp>=1.0.2" pyGXrender pychmp
+```
+
+`pyGXrender` currently requires **Python 3.12+** on PyPI; `pychmp` supports **3.10+**.
+Use a 3.12 environment when installing the full stack.
+
+Packages alone do not include model cubes, EBTEL tables, or observation FITS. For
+runnable examples, clone [pyGXrender-test-data](https://github.com/suncast-org/pyGXrender-test-data)
+next to this repository (or set explicit `--model-h5`, `--ebtel-path`, and
+`--obs-fits-path` / `--obs-map-id` on the workflow scripts). See `examples/python/`
+and `scripts/README.md`.
+
+Console entry points after install:
+
+| Command | Role |
+|---------|------|
+| `pychmp` | Package CLI |
+| `pychmp-view` | Artifact viewer |
+| `pychmp-rescore` | Rescore `map_store` into a parallel search identity |
+| `pychmp-repair-grid-trial-maps` | Repair invalid trial HDF5 groups |
+
+Release history: [CHANGELOG.md](CHANGELOG.md).
+
+## Quick Start
+
+```bash
+pychmp --help
+```
+
+User-facing runnable workflows live under `examples/`, and tracked shell
+launchers for the heavier manual validation and observational fitting runs live
+under `scripts/`.
+
+If you use the tracked launcher scripts, install `pyGXrender-test-data` as a
+sibling checkout next to `pyCHMP` so they can resolve shared models, EOVSA
+maps, and EBTEL inputs without machine-specific absolute paths.
+
+For EUV/UV model-refmap workflows, `--euv-response-sav` is now an explicit
+compatibility override rather than the default path. When omitted,
+gximagecomputing resolves supported instrument responses through its
+pyEUVTools-backed provider and surfaces the chosen `response.source` /
+`response.mode` metadata in the downstream render result.
+
+## User Manual
+
+### Artifact Reuse Policy
+
+pyCHMP artifacts are meant to represent meaningful scientific products, not to
+act as an audit log of failed or abandoned attempts.
+
+- A new slice should appear only when the scientific target changes in a way
+   that changes slice identity, such as a different EUV channel, MW frequency,
+   geometry/WCS, observer contract, or other incompatibility that makes the
+   stored maps physically non-reusable.
+- If the current run is compatible with the existing artifact and no grid-reset
+   flag is set, pyCHMP resumes implicitly from the existing search state.
+   Changing only search boundaries does not create a new slice or a new search
+   lineage.
+- `--recompute-search-id SEARCH_ID` (with `--artifact-h5`): **repair** mode —
+  restores the stored scoring recipe, preserves valid map-linked trials, resets
+  only contract-broken points, and resumes the adaptive walk to complete incomplete
+  cells. Allowed flags: `--artifact-h5`, `--recompute-search-id`, optional
+  `--no-viewer` / `--dry-run`.
+- `--expand-grid-search-id SEARCH_ID` (with `--artifact-h5`): widen `a`/`b` on the
+  same search id and stored recipe; hydrates completed cells; explores only new or
+  outstanding cells in the enlarged domain (Phase‑1 seeds from the prior footprint
+  wall toward the widened bound).
+- `pychmp-repair-grid-trial-maps`: purge invalid trial HDF5 groups and rebuild
+  headers; does not refit or clear `map_store`.
+- `pychmp-rescore build|commit`: rescore existing `map_store` maps into a new
+  `{root}_rN` search via a sidecar file (no gxrender, no viewer). Commit when no
+  adaptive run is active.
+- `--recompute-existing` clears the grid for the matching search identity and
+   refits every point, reusing `map_store` maps for warm q0 start (no gxrender
+   for compatible stored q0 values).
+- `--new-search-identity` does the same refit under a parallel search identity
+   for debugging (e.g. algorithm changes with the same target contract). Prior
+   searches remain in the artifact; `map_store` warm start still applies.
+- Changes that alter the scientific meaning of the stored results, such as
+   different masks, thresholds, or beams, must not silently reuse incompatible
+   results. They should branch only when the metadata signature requires it.
+
+Practical interpretation:
+
+- same target + same compatible signature + default (no flags): resume
+- same target + same compatible signature + `--recompute-existing`: same search
+   id, fresh grid, map_store warm start
+- same target + same compatible signature + `--new-search-identity`: parallel
+   search id, fresh grid, prior searches kept, map_store warm start
+- changed slice identity: create a new slice
+
+## Development
+
+```bash
+pytest -q
+```
+
+User-facing runnable workflows are available in `examples/`.
+
+Consolidated scan artifacts now use one normalized point schema across
+fixed-grid and adaptive search workflows. Each artifact keeps common
+slice-level metadata plus per-search point records under a unified slice/search
+layout, with reusable rendered arrays promoted into the shared `map_store`
+when applicable. Each stored point carries the final best-fit maps plus
+per-trial `q0`, `chi2`, `rho2`, and `eta2` histories when available, so
+`pychmp-view` can plot the selected metric history directly from the artifact.
+
+Real-data gxrender validation workflows live under `examples/python/` rather
+than in the default automated test suite.
+
+The `examples/` area is now structured to allow parallel workflow formats:
+standalone Python validation scripts live under `examples/python/`, while
+future developer and collaborator notebook examples can live under
+`examples/notebooks/`.
+
+The `scripts/` directory remains reserved for tracked shell launchers (`.sh`
+and `.cmd`) that wrap those Python workflows; it is not the home of the Python
+entry-point files themselves.
+
+## Workflow Call Graph
+
+The package has a layered structure. The most important distinction is between:
+
+- package-level fitting/search primitives under `src/pychmp/`
+- real-data runnable workflows under `examples/`
+- shell launchers under `scripts/`
+
+The current call hierarchy for the observational workflows is:
+
+```text
+shell launchers (.sh / .cmd)
+  -> examples/fit_q0_obs_map.py
+     -> pychmp.load_obs_map(...)
+     -> pychmp.estimate_obs_map_noise(...)
+     -> pychmp.resolve_geometry_policy(...)
+     -> pychmp.fit_q0_to_observation(...)
+
+shell launchers (.sh / .cmd)
+  -> examples/scan_ab_obs_map.py
+     -> pychmp.load_obs_map(...)
+     -> pychmp.estimate_obs_map_noise(...)
+     -> pychmp.resolve_geometry_policy(...)
+     -> per-point fit workflow
+        -> examples/fit_q0_obs_map.py
+           -> pychmp.fit_q0_to_observation(...)
+
+shell launchers (.sh / .cmd)
+  -> examples/python/adaptive_ab_search_single_observation.py
+     -> pychmp.load_obs_map(...)
+     -> pychmp.validate_obs_map_identity(...)
+     -> pychmp.resolve_render_geometry_via_gxrender(...)
+     -> pychmp.validate_scan_artifact_reuse_preflight(...) [when reusing an existing target slice]
+     -> pychmp.estimate_obs_map_noise(...)
+     -> pychmp.resolve_geometry_policy(...)
+     -> pychmp.search_local_minimum_ab(...)
+        -> pychmp.evaluate_ab_point(...)
+           -> pychmp.fit_q0_to_observation(...)
+```
+
+Contributor notes:
+
+- `fit_q0_to_observation(...)` is the core single-point numerical primitive.
+- `fit_q0_obs_map.py` is the single-point real observational workflow wrapper around that primitive.
+- `scan_ab_obs_map.py` is the fixed-grid / sparse-grid orchestration layer.
+- `search_local_minimum_ab(...)` is the adaptive `(a, b)` search core.
+- `adaptive_ab_search_single_observation.py` is the real observational wrapper around the adaptive search core.
+- `src/pychmp/obs_maps.py` is the shared observation-ingestion layer used by the real observational workflows.
+- `src/pychmp/geometry_policy.py` resolves observation LOS compatibility before workflows reuse model-saved observer/FOV metadata.
+- `src/pychmp/ab_scan_artifacts.py` owns the unified slice/search artifact contract, compatibility validation, and reusable map-store plumbing shared by fixed-grid and adaptive workflows.
+
+When adding new observational workflows, prefer reusing:
+
+- `load_obs_map(...)`
+- `validate_obs_map_identity(...)`
+- `estimate_obs_map_noise(...)`
+- `resolve_geometry_policy(...)`
+
+instead of introducing new script-local FITS/refmap loaders.
+
+The user-facing `fit_q0_obs_map.py`, `scan_ab_obs_map.py`, and
+`adaptive_ab_search_single_observation.py` workflows all expose the bounded
+Q0 minimizer controls `--xatol` and `--maxiter`. These tune the final bounded
+minimization accuracy and iteration budget; adaptive-search
+`--max-bracket-steps` only limits additional bracket expansion attempts before
+that minimization stage.
+
+### Version Bumping
+
+This repository uses `bumpver` to keep package versions in sync between
+`pyproject.toml` and `src/pychmp/__init__.py`.
+
+```bash
+pip install -e .[dev]
+bumpver show
+```
+
+For normal stable-version increments you can use the usual `bumpver update`
+subcommands. For explicit pre-release bumps like `0.1.0a0 -> 0.1.0a1`, update
+the version fields directly or use an explicit `bumpver` target rather than
+assuming `--patch` is the right semantic move.
+
+```bash
+python -m bumpver show
+```
+
+## Citation
+
+Please cite using [CITATION.cff](CITATION.cff) (version **0.1.0**) and the Zenodo record
+created from the matching GitHub release tag. See also `.zenodo.json` for archive metadata.
+
+## License
+
+BSD-3-Clause