Add BayesWHAM driver and configuration examples

README.md

@@ -71,6 +71,39 @@ Each non-comment, non-empty line in `metadata_file` should contain:
   frames by `exp(-energy / kT)`; omit from all lines to use uniform weights.
 
 Lines may start with `#` for comments. Mixing lines with and without temperature is rejected.
+
+### BayesWHAM configuration
+
+Bayesian reconstruction uses the same metadata and trajectory layout as the WHAM
+solvers and accepts the corresponding 1D or 2D histogram parameters. Append the
+following fields to reuse existing YAML inputs:
+
+- `num_samples` (optional, default `200`): total Dirichlet-resampled histograms
+  to draw for posterior estimation.
+- `burn_in` (optional, default `50`): number of initial samples to discard
+  before collecting posterior statistics.
+- `thinning` (optional, default `1`): stride between retained samples.
+- `dirichlet_alpha` (optional, default `1.0`): concentration added to each
+  histogram bin prior to sampling, mirroring the noninformative prior used in
+  the reference BayesWHAM script.
+
+Example 1D configuration (reuses the umbrella trajectories and metadata from the
+WHAM example):
+
+```yaml
+hist_min: -1.0
+hist_max: 1.0
+num_bins: 50
+tolerance: 1e-5
+temperature: 1.0
+numpad: 0
+metadata_file: examples/output_1D/umbrella_metadata.txt
+freefile: examples/output_1D/bayes.free
+num_samples: 400
+burn_in: 100
+thinning: 2
+dirichlet_alpha: 1.0
+```
 All metadata-referenced trajectories (for WHAM or projection runs) may use relative
 paths; they are resolved against the directory that contains the metadata file, so you
 can keep each metadata bundle self-contained regardless of the working directory.
@@ -145,6 +178,7 @@ Sample umbrella-sampling configuration files are included under `examples/`:
 # 1D trajectories and WHAM reconstruction
 python examples/langevin_umbrella.py --config examples/umbrella_config_1d.yaml
 python -m pywham.wham1d examples/wham1d_config.yaml
+python -m pywham.bwham examples/bwham_config.yaml
 
 # 2D trajectories on the Müller-Brown surface and WHAM2D reconstruction
 python examples/langevin_umbrella_2d.py --config examples/umbrella_config_2d.yaml

examples/bwham_config.yaml

@@ -0,0 +1,14 @@
+# bwham-config.yml
+hist_min: -1.0
+hist_max: 1.0
+num_bins: 50
+tolerance: 1e-5
+temperature: 1.0
+numpad: 0
+metadata_file: examples/output_1D/umbrella_metadata.txt
+freefile: examples/output_1D/bayes.free
+num_samples: 400
+burn_in: 100
+thinning: 2
+# optional Bayesian prior strength
+# dirichlet_alpha: 1.0

pyproject.toml

@@ -15,6 +15,7 @@ build-backend = "setuptools.build_meta"
 wham = "pywham.wham1d:main"
 "wham-2d" = "pywham.wham2d:main"
 reweight = "pywham.reweight:main"
+bwham = "pywham.bwham:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

src/pywham/__init__.py

@@ -1,9 +1,37 @@
 """Python translation of the WHAM C implementations."""
 
-from .visualization import plot_free_energy_1d, plot_free_energy_2d, save_free_energy_plots
+from importlib import import_module
+from typing import Any
 
 __all__ = [
+    "BayesWHAM",
+    "BayesWhamConfig",
+    "build_bwham_config",
     "plot_free_energy_1d",
     "plot_free_energy_2d",
     "save_free_energy_plots",
 ]
+
+_LAZY_ATTRS = {
+    "BayesWHAM": (".bwham", "BayesWHAM"),
+    "BayesWhamConfig": (".bwham", "BayesWhamConfig"),
+    "build_bwham_config": (".bwham", "build_config"),
+    "plot_free_energy_1d": (".visualization", "plot_free_energy_1d"),
+    "plot_free_energy_2d": (".visualization", "plot_free_energy_2d"),
+    "save_free_energy_plots": (".visualization", "save_free_energy_plots"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module_name, attr_name = _LAZY_ATTRS[name]
+    except KeyError:
+        raise AttributeError(f"module 'pywham' has no attribute {name!r}") from None
+    module = import_module(module_name, __name__)
+    attr = getattr(module, attr_name)
+    globals()[name] = attr
+    return attr
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)