mchammer-pt 0.27.0__tar.gz

mchammer_pt-0.27.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Benjamin J. Morgan
+
+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.

mchammer_pt-0.27.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: mchammer-pt
+Version: 0.27.0
+Summary: Replica-exchange orchestrators for mchammer: canonical parallel tempering and multi-walker replica-exchange Wang-Landau
+Author-email: "Benjamin J. Morgan" <b.j.morgan@bath.ac.uk>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: ase
+Requires-Dist: icet>=3.2
+Requires-Dist: h5py
+Provides-Extra: custom-moves
+Requires-Dist: mchammer-moves>=0.6.0; extra == "custom-moves"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Requires-Dist: scipy-stubs; extra == "dev"
+Requires-Dist: mchammer-pt[custom-moves]; extra == "dev"
+Provides-Extra: plot
+Requires-Dist: matplotlib; extra == "plot"
+Dynamic: license-file
+
+# mchammer-pt
+
+Replica-exchange orchestrators for [`mchammer`](https://icet.materialsmodeling.org/)
+Monte Carlo with `icet` cluster expansions: canonical-ensemble
+parallel tempering across a temperature ladder, and replica-exchange
+Wang-Landau (REWL) across an energy-window ladder, with optional
+multiple walkers per window.
+
+For an architecture overview, see [docs/architecture.md](docs/architecture.md).
+
+## Why
+
+`mchammer`'s canonical ensemble samples at a single temperature. Large
+supercells with competing ordered basins can trap the chain in local
+minima; a single-temperature chain may never visit the other basin.
+Parallel tempering runs `N` replicas at different temperatures and
+periodically proposes configuration swaps between adjacent replicas,
+so a high-temperature chain can cross barriers and deliver escape
+paths to the colder chains.
+
+`mchammer`'s single-walker Wang-Landau samples a fixed energy window,
+but on rugged density-of-states landscapes the walker spends long
+stretches near the window edges and the fill-factor schedule stalls
+before the histogram is flat. REWL splits the target energy range
+into overlapping windows and proposes configuration swaps between
+adjacent windows weighted by their within-window density-of-states
+ratio, so each walker mixes faster inside its own window and the
+combined run converges in wall-clock time that scales with window
+width rather than total energy range. Each window optionally runs
+multiple walkers in lockstep that share the flatness gate and merge
+their entropy estimates, further reducing the random-walk variance
+that drives Wang-Landau's per-window convergence cost.
+
+## Features
+
+- `CanonicalParallelTempering` — canonical-ensemble PT with an
+  arbitrary temperature ladder.
+- `WangLandauParallelTempering` — replica-exchange Wang-Landau
+  (REWL) on top of icet's `WangLandauEnsemble`. Each window owns a
+  fixed energy range; adjacent windows attempt configuration swaps
+  with a within-window density-of-states ratio for acceptance.
+  `n_walkers_per_window` (scalar or per-window sequence) runs
+  multiple WL walkers inside the same window, sharing the flatness
+  gate and merging entropies across the group — straightforward to
+  configure here, not exposed by raw icet. To use the
+  Belardinelli-Pereyra 1/t schedule, pass
+  `ensemble_kwargs={'schedule': '1_over_t'}`; the default
+  `schedule='halving'` gives the standard WL fill-factor scheme.
+  Serial and process-parallel backends as for the canonical
+  orchestrator; checkpoint/resume into either pool kind.
+- `mchammer_pt.analysis.dos.stitch_entropy` and
+  `reweight_canonical_from_dos` post-process REWL output: stitch the
+  per-window ln g(E) curves into a single density of states (working
+  in log space, with bin-index matching that survives ULP-level
+  energy drift between windows), then evaluate canonical
+  thermodynamic observables on a user-supplied temperature grid.
+- `mchammer-pt-stitch` and `mchammer-pt-reweight` console scripts
+  expose the same pipeline from the command line, reading either an
+  mchammer-pt checkpoint HDF5 or `WangLandauDataContainer` files
+  directly.
+- Serial and multiprocessing backends, swappable via a single
+  constructor argument.
+- Custom Monte Carlo moves: pass any `mchammer.CanonicalEnsemble`
+  subclass via `ensemble_cls=`, with extra constructor arguments
+  forwarded via `ensemble_kwargs=`. Custom `_do_trial_step` overrides
+  ride the PT machinery without subclassing `Replica`.
+- Per-replica `mchammer.BaseObserver` attachment on both serial and
+  process-parallel pools, with each replica receiving its own
+  observer copy. Three attach paths cover the spectrum: pass an
+  observer instance for the common case (`attach_observer`), a class
+  plus constructor arguments when picklable (`attach_observer_class`),
+  or a top-level factory that constructs the observer inside each
+  worker — required for observers like `ClusterCountObserver` whose
+  constructors take icet `ClusterSpace` objects that do not pickle
+  (`attach_observer_factory`). The factory reloads the
+  `ClusterExpansion` from disk via
+  `ClusterExpansion.read(replica.cluster_expansion_path)`;
+  `ProcessPool` auto-populates the path on every worker.
+- HDF5 output bundling one `mchammer.BaseDataContainer` per replica plus
+  a compact `ExchangeHistory` of per-pair swap statistics and
+  replica-label trajectories.
+- Round-trip count and integrated-autocorrelation-time diagnostics
+  as pure functions over the run output.
+- `ExchangeCallback` protocol for PT-level events (with `ExchangePrinter`
+  and `SwapRateTracker` built-ins).
+- `CycleCallback` protocol for per-cycle hooks, with `ProgressPrinter`
+  built-in for periodic stderr progress lines on long runs (cycle,
+  percent, elapsed, ETA, swap-acceptance rates).
+- `CheckpointWriter` cycle callback and
+  `CanonicalParallelTempering.resume(...)` for crash-safe long runs
+  and bit-identical continuation across `pt.run()` calls (after
+  `ExchangeHistory.concatenate`). Same payload also written by
+  `pt.save_checkpoint(path)` and via the existing
+  `data_container_file=` constructor kwarg.
+- `mchammer_pt.testing.assert_boltzmann_sampling` — public utility for
+  pinning the empirical stationary distribution of a custom
+  `CanonicalEnsemble` subclass against an analytic Boltzmann fixture.
+  Downstream packages providing custom moves can use this to pin
+  stationarity correctness against the same anchor as mchammer-pt's
+  own test suite.
+
+## Install
+
+    pip install -e .
+
+Requires Python 3.11+ and `icet>=3.2` (installed automatically from
+PyPI).
+
+Optional dev tooling: `pip install -e '.[dev]'` adds `pytest`,
+`mypy`, `ruff`.
+
+## Quickstart
+
+```python
+from ase.build import bulk
+from icet import ClusterExpansion
+from mchammer_pt import CanonicalParallelTempering
+
+ce = ClusterExpansion.read("my_ce.ce")
+atoms = bulk("Cu", "fcc", a=4.0, cubic=True).repeat((4, 4, 4))
+# ... decorate atoms with the correct composition ...
+
+pt = CanonicalParallelTempering(
+    cluster_expansion=ce,
+    atoms=atoms,
+    temperatures=[100, 200, 350, 550, 800, 1200, 1800, 2700],
+    block_size=1000,
+    random_seed=0,
+    data_container_file="pt.h5",
+)
+
+# Optional: live progress on stderr for long runs.
+from mchammer_pt import ProgressPrinter
+pt.attach_cycle_callback(ProgressPrinter(interval=100))
+
+pt.run(n_cycles=200)
+
+# Diagnostics.
+from mchammer_pt import (
+    round_trip_counts,
+    swap_acceptance_rates,
+    energy_autocorrelation_time,
+)
+print("acceptance:", swap_acceptance_rates(pt.history))
+print("round-trips:", round_trip_counts(pt.history.replica_labels_per_cycle))
+# The single-argument form above is for one walker per rung (canonical PT
+# and single-walker REWL). For multi-walker REWL pass the window mapping,
+# which the history carries (so it works on a run read back from disk):
+#   round_trip_counts(pt.history.replica_labels_per_cycle,
+#                     pt.history.window_of_position)
+for r in range(len(pt.pool)):
+    tau = energy_autocorrelation_time(pt.history.energies_per_cycle[:, r])
+    print(f"replica {r}: tau = {tau:.1f} cycles")
+```
+
+For multiprocess parallelism, use the `process_pool` classmethod:
+
+```python
+with CanonicalParallelTempering.process_pool(
+    cluster_expansion=ce,
+    atoms=atoms,
+    temperatures=[200, 400, 800, 1600],
+    block_size=1000,
+    random_seed=0,
+) as pt:
+    pt.run(n_cycles=200)
+```
+
+The factory handles seed spawning, writing the CE to a managed temp
+directory, and constructing a `ProcessPool` at the same ladder as
+the orchestrator. See `examples/03_parallel_workers.py`.
+
+Observer attachment is supported on both `SerialPool` and `ProcessPool`.
+See the Features list above for the three attach paths and when to use each.
+
+For custom Monte Carlo moves, subclass `mchammer.CanonicalEnsemble`
+and pass via `ensemble_cls=`:
+
+```python
+from mchammer.ensembles import CanonicalEnsemble
+
+class MyMove(CanonicalEnsemble):
+    def _do_trial_step(self) -> int:
+        # ... your custom move ...
+        return super()._do_trial_step()
+
+with CanonicalParallelTempering.process_pool(
+    cluster_expansion=ce,
+    atoms=atoms,
+    temperatures=[200, 400, 800, 1600],
+    block_size=1000,
+    random_seed=0,
+    ensemble_cls=MyMove,
+) as pt:
+    pt.run(n_cycles=200)
+```
+
+Spawn workers re-import the class by fully qualified name, so define
+the subclass in a `.py` module file rather than a Jupyter cell. See
+`examples/05_custom_ensemble.py` for a complete worked example.
+
+### Wang-Landau parallel tempering
+
+For Wang-Landau parallel tempering, build per-window starting
+configurations whose energies lie inside their assigned windows,
+then drive `WangLandauParallelTempering.from_bin_count` (or pass
+explicit `windows=` for non-uniform splits):
+
+```python
+from mchammer_pt import WangLandauParallelTempering
+
+# `per_window_atoms` is a list[Atoms], one per window, with each
+# entry's energy in the corresponding window. Generating these
+# is the user's responsibility — typically a short pilot MC run.
+pt = WangLandauParallelTempering.from_bin_count(
+    cluster_expansion=ce,
+    atoms=per_window_atoms,
+    n_bins=4,
+    energy_spacing=1.0,
+    minimum_energy=-32.0,
+    maximum_energy=32.0,
+    overlap=4,
+    block_size=len(per_window_atoms[0]) * 1000,
+    random_seed=0,
+)
+pt.run(n_cycles=500)
+```
+
+`pt.run(...)` exits early once every replica reports `converged`.
+`WangLandauParallelTempering.process_pool(...)` spawns one OS
+process per replica. `save_checkpoint(path)` / `resume(path, ...)`
+/ `resume_process_pool(path, ...)` mirror the canonical surface.
+Observers attach the same way as on the canonical pool (via
+`pt.attach_observer(...)` or, for the class and factory paths,
+directly on `pt.pool`); each replica's recorded observable
+trajectory ends up in its `WangLandauDataContainer`, ready for
+icet's `get_average_observables_wl` against the stitched ln g(E).
+
+Stitch the per-window ln g(E) curves into a single density of
+states, then reweight onto a canonical temperature grid:
+
+```python
+from mchammer_pt.analysis.dos import (
+    reweight_canonical_from_dos,
+    stitch_entropy,
+)
+
+per_window = [r.get_entropy() for r in pt.results()]
+stitched, errors = stitch_entropy(per_window, energy_spacing=1.0)
+canonical = reweight_canonical_from_dos(
+    stitched, temperatures=[100, 200, 400, 800, 1600],
+)
+```
+
+The same pipeline is available from the command line via the
+`mchammer-pt-stitch` and `mchammer-pt-reweight` console scripts, which
+read either an mchammer-pt checkpoint HDF5 or
+`WangLandauDataContainer` files directly. Pass `--multi-run` with two
+or more checkpoints to merge independent seeds of the same system into
+one consensus DOS (each window is merged across runs before
+stitching). For production runs on a new system, plan
+to validate the recovered DOS against ground truth (e.g. by
+brute-force enumeration on a small case, or against an analytic
+result) before trusting downstream thermodynamic averages.
+
+## Examples
+
+- `examples/01_basic_canonical.py` — self-contained run on a toy Cu/Au CE.
+- `examples/02_custom_callback.py` — writing your own `ExchangeCallback`.
+- `examples/03_parallel_workers.py` — PT with the `ProcessPool`.
+- `examples/04_equilibrium_sampling.py` – discarding the initial burn-in period for equilibrium sampling.
+- `examples/05_custom_ensemble.py` — PT with a custom
+  `CanonicalEnsemble` subclass.
+- `examples/06_progress_monitoring.py` — live progress on stderr for
+  long runs via `ProgressPrinter`.
+- `examples/07_resume.py` — checkpoint and resume a PT run, with
+  bit-identical continuation.
+- `examples/08_rewl.py` — replica-exchange Wang-Landau on a 4x4
+  2D Ising model, with per-window seeding and DOS stitching.
+- `examples/09_dos_postprocessing.py` — stitching REWL output into
+  a single ln g(E) and reweighting onto a canonical temperature
+  grid via `mchammer_pt.analysis.dos`.
+
+## License
+
+MIT.

mchammer_pt-0.27.0/README.md

@@ -0,0 +1,286 @@
+# mchammer-pt
+
+Replica-exchange orchestrators for [`mchammer`](https://icet.materialsmodeling.org/)
+Monte Carlo with `icet` cluster expansions: canonical-ensemble
+parallel tempering across a temperature ladder, and replica-exchange
+Wang-Landau (REWL) across an energy-window ladder, with optional
+multiple walkers per window.
+
+For an architecture overview, see [docs/architecture.md](docs/architecture.md).
+
+## Why
+
+`mchammer`'s canonical ensemble samples at a single temperature. Large
+supercells with competing ordered basins can trap the chain in local
+minima; a single-temperature chain may never visit the other basin.
+Parallel tempering runs `N` replicas at different temperatures and
+periodically proposes configuration swaps between adjacent replicas,
+so a high-temperature chain can cross barriers and deliver escape
+paths to the colder chains.
+
+`mchammer`'s single-walker Wang-Landau samples a fixed energy window,
+but on rugged density-of-states landscapes the walker spends long
+stretches near the window edges and the fill-factor schedule stalls
+before the histogram is flat. REWL splits the target energy range
+into overlapping windows and proposes configuration swaps between
+adjacent windows weighted by their within-window density-of-states
+ratio, so each walker mixes faster inside its own window and the
+combined run converges in wall-clock time that scales with window
+width rather than total energy range. Each window optionally runs
+multiple walkers in lockstep that share the flatness gate and merge
+their entropy estimates, further reducing the random-walk variance
+that drives Wang-Landau's per-window convergence cost.
+
+## Features
+
+- `CanonicalParallelTempering` — canonical-ensemble PT with an
+  arbitrary temperature ladder.
+- `WangLandauParallelTempering` — replica-exchange Wang-Landau
+  (REWL) on top of icet's `WangLandauEnsemble`. Each window owns a
+  fixed energy range; adjacent windows attempt configuration swaps
+  with a within-window density-of-states ratio for acceptance.
+  `n_walkers_per_window` (scalar or per-window sequence) runs
+  multiple WL walkers inside the same window, sharing the flatness
+  gate and merging entropies across the group — straightforward to
+  configure here, not exposed by raw icet. To use the
+  Belardinelli-Pereyra 1/t schedule, pass
+  `ensemble_kwargs={'schedule': '1_over_t'}`; the default
+  `schedule='halving'` gives the standard WL fill-factor scheme.
+  Serial and process-parallel backends as for the canonical
+  orchestrator; checkpoint/resume into either pool kind.
+- `mchammer_pt.analysis.dos.stitch_entropy` and
+  `reweight_canonical_from_dos` post-process REWL output: stitch the
+  per-window ln g(E) curves into a single density of states (working
+  in log space, with bin-index matching that survives ULP-level
+  energy drift between windows), then evaluate canonical
+  thermodynamic observables on a user-supplied temperature grid.
+- `mchammer-pt-stitch` and `mchammer-pt-reweight` console scripts
+  expose the same pipeline from the command line, reading either an
+  mchammer-pt checkpoint HDF5 or `WangLandauDataContainer` files
+  directly.
+- Serial and multiprocessing backends, swappable via a single
+  constructor argument.
+- Custom Monte Carlo moves: pass any `mchammer.CanonicalEnsemble`
+  subclass via `ensemble_cls=`, with extra constructor arguments
+  forwarded via `ensemble_kwargs=`. Custom `_do_trial_step` overrides
+  ride the PT machinery without subclassing `Replica`.
+- Per-replica `mchammer.BaseObserver` attachment on both serial and
+  process-parallel pools, with each replica receiving its own
+  observer copy. Three attach paths cover the spectrum: pass an
+  observer instance for the common case (`attach_observer`), a class
+  plus constructor arguments when picklable (`attach_observer_class`),
+  or a top-level factory that constructs the observer inside each
+  worker — required for observers like `ClusterCountObserver` whose
+  constructors take icet `ClusterSpace` objects that do not pickle
+  (`attach_observer_factory`). The factory reloads the
+  `ClusterExpansion` from disk via
+  `ClusterExpansion.read(replica.cluster_expansion_path)`;
+  `ProcessPool` auto-populates the path on every worker.
+- HDF5 output bundling one `mchammer.BaseDataContainer` per replica plus
+  a compact `ExchangeHistory` of per-pair swap statistics and
+  replica-label trajectories.
+- Round-trip count and integrated-autocorrelation-time diagnostics
+  as pure functions over the run output.
+- `ExchangeCallback` protocol for PT-level events (with `ExchangePrinter`
+  and `SwapRateTracker` built-ins).
+- `CycleCallback` protocol for per-cycle hooks, with `ProgressPrinter`
+  built-in for periodic stderr progress lines on long runs (cycle,
+  percent, elapsed, ETA, swap-acceptance rates).
+- `CheckpointWriter` cycle callback and
+  `CanonicalParallelTempering.resume(...)` for crash-safe long runs
+  and bit-identical continuation across `pt.run()` calls (after
+  `ExchangeHistory.concatenate`). Same payload also written by
+  `pt.save_checkpoint(path)` and via the existing
+  `data_container_file=` constructor kwarg.
+- `mchammer_pt.testing.assert_boltzmann_sampling` — public utility for
+  pinning the empirical stationary distribution of a custom
+  `CanonicalEnsemble` subclass against an analytic Boltzmann fixture.
+  Downstream packages providing custom moves can use this to pin
+  stationarity correctness against the same anchor as mchammer-pt's
+  own test suite.
+
+## Install
+
+    pip install -e .
+
+Requires Python 3.11+ and `icet>=3.2` (installed automatically from
+PyPI).
+
+Optional dev tooling: `pip install -e '.[dev]'` adds `pytest`,
+`mypy`, `ruff`.
+
+## Quickstart
+
+```python
+from ase.build import bulk
+from icet import ClusterExpansion
+from mchammer_pt import CanonicalParallelTempering
+
+ce = ClusterExpansion.read("my_ce.ce")
+atoms = bulk("Cu", "fcc", a=4.0, cubic=True).repeat((4, 4, 4))
+# ... decorate atoms with the correct composition ...
+
+pt = CanonicalParallelTempering(
+    cluster_expansion=ce,
+    atoms=atoms,
+    temperatures=[100, 200, 350, 550, 800, 1200, 1800, 2700],
+    block_size=1000,
+    random_seed=0,
+    data_container_file="pt.h5",
+)
+
+# Optional: live progress on stderr for long runs.
+from mchammer_pt import ProgressPrinter
+pt.attach_cycle_callback(ProgressPrinter(interval=100))
+
+pt.run(n_cycles=200)
+
+# Diagnostics.
+from mchammer_pt import (
+    round_trip_counts,
+    swap_acceptance_rates,
+    energy_autocorrelation_time,
+)
+print("acceptance:", swap_acceptance_rates(pt.history))
+print("round-trips:", round_trip_counts(pt.history.replica_labels_per_cycle))
+# The single-argument form above is for one walker per rung (canonical PT
+# and single-walker REWL). For multi-walker REWL pass the window mapping,
+# which the history carries (so it works on a run read back from disk):
+#   round_trip_counts(pt.history.replica_labels_per_cycle,
+#                     pt.history.window_of_position)
+for r in range(len(pt.pool)):
+    tau = energy_autocorrelation_time(pt.history.energies_per_cycle[:, r])
+    print(f"replica {r}: tau = {tau:.1f} cycles")
+```
+
+For multiprocess parallelism, use the `process_pool` classmethod:
+
+```python
+with CanonicalParallelTempering.process_pool(
+    cluster_expansion=ce,
+    atoms=atoms,
+    temperatures=[200, 400, 800, 1600],
+    block_size=1000,
+    random_seed=0,
+) as pt:
+    pt.run(n_cycles=200)
+```
+
+The factory handles seed spawning, writing the CE to a managed temp
+directory, and constructing a `ProcessPool` at the same ladder as
+the orchestrator. See `examples/03_parallel_workers.py`.
+
+Observer attachment is supported on both `SerialPool` and `ProcessPool`.
+See the Features list above for the three attach paths and when to use each.
+
+For custom Monte Carlo moves, subclass `mchammer.CanonicalEnsemble`
+and pass via `ensemble_cls=`:
+
+```python
+from mchammer.ensembles import CanonicalEnsemble
+
+class MyMove(CanonicalEnsemble):
+    def _do_trial_step(self) -> int:
+        # ... your custom move ...
+        return super()._do_trial_step()
+
+with CanonicalParallelTempering.process_pool(
+    cluster_expansion=ce,
+    atoms=atoms,
+    temperatures=[200, 400, 800, 1600],
+    block_size=1000,
+    random_seed=0,
+    ensemble_cls=MyMove,
+) as pt:
+    pt.run(n_cycles=200)
+```
+
+Spawn workers re-import the class by fully qualified name, so define
+the subclass in a `.py` module file rather than a Jupyter cell. See
+`examples/05_custom_ensemble.py` for a complete worked example.
+
+### Wang-Landau parallel tempering
+
+For Wang-Landau parallel tempering, build per-window starting
+configurations whose energies lie inside their assigned windows,
+then drive `WangLandauParallelTempering.from_bin_count` (or pass
+explicit `windows=` for non-uniform splits):
+
+```python
+from mchammer_pt import WangLandauParallelTempering
+
+# `per_window_atoms` is a list[Atoms], one per window, with each
+# entry's energy in the corresponding window. Generating these
+# is the user's responsibility — typically a short pilot MC run.
+pt = WangLandauParallelTempering.from_bin_count(
+    cluster_expansion=ce,
+    atoms=per_window_atoms,
+    n_bins=4,
+    energy_spacing=1.0,
+    minimum_energy=-32.0,
+    maximum_energy=32.0,
+    overlap=4,
+    block_size=len(per_window_atoms[0]) * 1000,
+    random_seed=0,
+)
+pt.run(n_cycles=500)
+```
+
+`pt.run(...)` exits early once every replica reports `converged`.
+`WangLandauParallelTempering.process_pool(...)` spawns one OS
+process per replica. `save_checkpoint(path)` / `resume(path, ...)`
+/ `resume_process_pool(path, ...)` mirror the canonical surface.
+Observers attach the same way as on the canonical pool (via
+`pt.attach_observer(...)` or, for the class and factory paths,
+directly on `pt.pool`); each replica's recorded observable
+trajectory ends up in its `WangLandauDataContainer`, ready for
+icet's `get_average_observables_wl` against the stitched ln g(E).
+
+Stitch the per-window ln g(E) curves into a single density of
+states, then reweight onto a canonical temperature grid:
+
+```python
+from mchammer_pt.analysis.dos import (
+    reweight_canonical_from_dos,
+    stitch_entropy,
+)
+
+per_window = [r.get_entropy() for r in pt.results()]
+stitched, errors = stitch_entropy(per_window, energy_spacing=1.0)
+canonical = reweight_canonical_from_dos(
+    stitched, temperatures=[100, 200, 400, 800, 1600],
+)
+```
+
+The same pipeline is available from the command line via the
+`mchammer-pt-stitch` and `mchammer-pt-reweight` console scripts, which
+read either an mchammer-pt checkpoint HDF5 or
+`WangLandauDataContainer` files directly. Pass `--multi-run` with two
+or more checkpoints to merge independent seeds of the same system into
+one consensus DOS (each window is merged across runs before
+stitching). For production runs on a new system, plan
+to validate the recovered DOS against ground truth (e.g. by
+brute-force enumeration on a small case, or against an analytic
+result) before trusting downstream thermodynamic averages.
+
+## Examples
+
+- `examples/01_basic_canonical.py` — self-contained run on a toy Cu/Au CE.
+- `examples/02_custom_callback.py` — writing your own `ExchangeCallback`.
+- `examples/03_parallel_workers.py` — PT with the `ProcessPool`.
+- `examples/04_equilibrium_sampling.py` – discarding the initial burn-in period for equilibrium sampling.
+- `examples/05_custom_ensemble.py` — PT with a custom
+  `CanonicalEnsemble` subclass.
+- `examples/06_progress_monitoring.py` — live progress on stderr for
+  long runs via `ProgressPrinter`.
+- `examples/07_resume.py` — checkpoint and resume a PT run, with
+  bit-identical continuation.
+- `examples/08_rewl.py` — replica-exchange Wang-Landau on a 4x4
+  2D Ising model, with per-window seeding and DOS stitching.
+- `examples/09_dos_postprocessing.py` — stitching REWL output into
+  a single ln g(E) and reweighting onto a canonical temperature
+  grid via `mchammer_pt.analysis.dos`.
+
+## License
+
+MIT.