bfflearn 0.2.0__tar.gz → 0.3.0__tar.gz

{bfflearn-0.2.0 → bfflearn-0.3.0}/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 ## Unreleased
 
+## `0.3.0` - 2026-06-11
+
+### Breaking Changes
+
+- Moved effective-observation configuration from `bff fit` to each model under
+  `bff learn`. Model entries now require `model_path` and exactly one strategy:
+  explicit `n_eff`, `independent_observations: true`, or curve inference with
+  `tolerance`.
+- Changed `.lgp` serialization to store reference-curve metadata. Models
+  written by earlier releases must be refitted before use with 0.3.0.
+
+### Added
+
+- Added prominence-based effective-observation estimates for smooth,
+  curve-valued QoIs while retaining direct counts for independent scalar data.
+- Added `qoi-marginals.pdf`, which colors posterior parameter marginals by the
+  local contribution of each QoI and shows priors and parameter bounds.
+- Added per-QoI Gaussian log-likelihood evaluation for post-processing thinned
+  posterior samples.
+
+### Changed
+
+- Made the Gaussian likelihood insensitive to curve binning by applying
+  `n_eff` to a mean squared residual rather than treating every bin as an
+  independent observation.
+- Allowed surrogate models for different QoIs to use different numbers of
+  training rows, provided their parameter dimensions agree.
+- Simplified the `bff` command entry point and shell completion while retaining
+  subcommands such as `bff build`.
+- Made build templates optional for systems that do not require molecule
+  templates.
+- Updated the packaged examples and documentation for effective observations
+  and QoI-attributed posterior plots.
+- Included `pytest` in the standard installation so packaged test and example
+  checks are available without installing the developer extra.
+
+### Fixed
+
+- Fixed multiprocessing imports for analysis routines loaded from user Python
+  files.
+
+## `0.2.1` - 2026-06-01
+
+### Fixed
+
+- Restored Python 3.10 compatibility by replacing the Python 3.11-only
+  `typing.Self` annotation in Gaussian-process model loading.
+
 ## `0.2.0` - 2026-06-01
 
 The public reproduction snapshot for the published study is archived as

{bfflearn-0.2.0 → bfflearn-0.3.0}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use BFF, please cite the repository and the associated paper."
 title: "Bayesic Force Fields"
-version: "0.2.0"
-date-released: "2026-06-01"
+version: "0.3.0"
+date-released: "2026-06-11"
 authors:
   - family-names: Kostal
     given-names: Vojtech

{bfflearn-0.2.0 → bfflearn-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bfflearn
-Version: 0.2.0
+Version: 0.3.0
 Summary: Bayesian workflows for fixed-charge molecular force fields
 Author-email: Vojtech Kostal <vojtakostal8@gmail.com>
 License-Expression: GPL-3.0-only
@@ -28,6 +28,7 @@ Requires-Dist: gmxtopology>=0.1.1
 Requires-Dist: matplotlib>=3.8
 Requires-Dist: MDAnalysis>=2.7
 Requires-Dist: numpy>=1.26
+Requires-Dist: pytest>=8
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: scipy>=1.11
 Requires-Dist: typer>=0.12
@@ -39,7 +40,6 @@ Requires-Dist: jupyterlab; extra == "notebook"
 Requires-Dist: notebook; extra == "notebook"
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Provides-Extra: docs
@@ -64,6 +64,10 @@ molecular force-field parameters from molecular-dynamics observables. It
 coordinates simulation campaigns, trajectory analysis, surrogate fitting, and
 Bayesian posterior learning.
 
+Posterior learning supports explicit or data-derived effective observation
+counts for scalar and curve-valued observables. It also writes QoI-attributed
+marginals that show which observables support different posterior regions.
+
 Full documentation:
 [vojtechkostal.github.io/BayesicForceFields](https://vojtechkostal.github.io/BayesicForceFields/)
 
@@ -91,6 +95,12 @@ mamba activate bfflearn
 pip install bfflearn
 ```
 
+For Jupyter notebooks, install the optional notebook tools:
+
+```bash
+pip install "bfflearn[notebook]"
+```
+
 > **WARNING:** GPU-enabled PyTorch must be installed separately. Use the
 > [official PyTorch installation selector](https://pytorch.org/get-started/locally/)
 > to choose the command matching your CUDA version before running fitting,

{bfflearn-0.2.0 → bfflearn-0.3.0}/README.md

@@ -14,6 +14,10 @@ molecular force-field parameters from molecular-dynamics observables. It
 coordinates simulation campaigns, trajectory analysis, surrogate fitting, and
 Bayesian posterior learning.
 
+Posterior learning supports explicit or data-derived effective observation
+counts for scalar and curve-valued observables. It also writes QoI-attributed
+marginals that show which observables support different posterior regions.
+
 Full documentation:
 [vojtechkostal.github.io/BayesicForceFields](https://vojtechkostal.github.io/BayesicForceFields/)
 
@@ -41,6 +45,12 @@ mamba activate bfflearn
 pip install bfflearn
 ```
 
+For Jupyter notebooks, install the optional notebook tools:
+
+```bash
+pip install "bfflearn[notebook]"
+```
+
 > **WARNING:** GPU-enabled PyTorch must be installed separately. Use the
 > [official PyTorch installation selector](https://pytorch.org/get-started/locally/)
 > to choose the command matching your CUDA version before running fitting,

{bfflearn-0.2.0 → bfflearn-0.3.0}/bff/__init__.py

@@ -6,7 +6,7 @@ from importlib import import_module
 from pathlib import Path
 from typing import Any
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 _INTERNAL_MODULES = {
     "bayes",

bfflearn-0.3.0/bff/bayes/__init__.py

@@ -0,0 +1,21 @@
+from . import (
+    effective_observations,
+    gaussian_process,
+    kernels,
+    learning,
+    likelihoods,
+    priors,
+    results,
+    utils,
+)
+
+__all__ = [
+    'effective_observations',
+    'gaussian_process',
+    'kernels',
+    'learning',
+    'likelihoods',
+    'priors',
+    'results',
+    'utils',
+]

bfflearn-0.3.0/bff/bayes/effective_observations.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import numpy as np
+from scipy.signal import find_peaks, savgol_filter
+
+
+def estimate_curve_n_eff(y: np.ndarray, *, tolerance: float) -> float:
+    """Estimate an effective number of resolved features in one smooth curve."""
+    y = np.asarray(y, dtype=float)
+    tolerance = float(tolerance)
+
+    if y.ndim != 1 or y.size < 11:
+        raise ValueError("curve must be one-dimensional with at least 11 values.")
+    if not np.all(np.isfinite(y)):
+        raise ValueError("curve must contain only finite values.")
+    if not np.isfinite(tolerance) or tolerance <= 0.0:
+        raise ValueError("tolerance must be positive and finite.")
+
+    window_length = min(15, y.size if y.size % 2 else y.size - 1)
+    y_smooth = savgol_filter(y, window_length=window_length, polyorder=3)
+
+    noise = np.median(np.abs(y - y_smooth))
+    prominence_threshold = max(5.0 * noise, np.finfo(float).eps)
+
+    n_eff = 0.0
+    for sign in (1.0, -1.0):
+        _, properties = find_peaks(sign * y_smooth, prominence=prominence_threshold)
+        for prominence in properties["prominences"]:
+            n_eff += max(1.0, np.log(float(prominence) / tolerance))
+
+    return max(1.0, float(n_eff))

{bfflearn-0.2.0 → bfflearn-0.3.0}/bff/bayes/gaussian_process.py

@@ -1,5 +1,5 @@
 from pathlib import Path
-from typing import Callable, Self, Union
+from typing import Callable, TypeVar, Union
 
 import numpy as np
 import torch
@@ -14,6 +14,7 @@ MeanFunction = Union[
     float,
     Callable[[torch.Tensor], torch.Tensor],
 ]
+LGPCommitteeT = TypeVar("LGPCommitteeT", bound="LGPCommittee")
 
 
 def evaluate_mean(
@@ -165,10 +166,10 @@ class LGPCommittee:
     ----------
     lgps : list of LocalGaussianProcess
         List of LGP models.
-    n_observations : int
-        Effective number of observations used in the likelihood term.
     reference_values : np.ndarray
         Reference observation vector matched by the surrogate outputs.
+    n_curves : int
+        Number of curves represented by the flattened reference vector.
     nuisance : float, optional
         Nuisance parameter for model selection (default is None).
     stochastic : bool, optional
@@ -194,15 +195,16 @@ class LGPCommittee:
     def __init__(
         self,
         lgps: list[LocalGaussianProcess],
-        n_observations: int,
         reference_values: np.ndarray,
+        n_curves: int,
         nuisance: float | None = None,
         stochastic: bool = False
     ) -> None:
         self.lgps = lgps
         self.error: float | None = None
-        self.n_observations = int(n_observations)
         self.reference_values = np.asarray(reference_values, dtype=float).reshape(-1)
+        self.n_curves = int(n_curves)
+        self.n_eff = float(self.reference_values.size)
         self.nuisance = nuisance
         self.stochastic = stochastic
 
@@ -210,6 +212,12 @@ class LGPCommittee:
             raise ValueError(
                 "Reference observation size does not match surrogate output size."
             )
+        if self.n_curves <= 0:
+            raise ValueError("'n_curves' must be a positive integer.")
+        if self.reference_values.size % self.n_curves != 0:
+            raise ValueError(
+                "Reference observation size must be divisible by 'n_curves'."
+            )
 
     @property
     def size(self) -> int:
@@ -223,6 +231,10 @@ class LGPCommittee:
     def y_size(self) -> int:
         return self.lgps[0].y_size
 
+    @property
+    def curve_length(self) -> int:
+        return int(self.reference_values.size // self.n_curves)
+
     def predict(self, X: torch.Tensor) -> torch.Tensor:
         """
         Predict outputs by averaging predictions from all LGP models.
@@ -269,13 +281,19 @@ class LGPCommittee:
         return self.error
 
     @classmethod
-    def load(cls, fn: PathLike) -> Self:
+    def load(cls: type[LGPCommitteeT], fn: PathLike) -> LGPCommitteeT:
         state = torch.load(fn, weights_only=False)
+        if "n_curves" not in state:
+            raise ValueError(
+                "This surrogate model predates BFF 0.3.0 and does not contain "
+                "reference-curve metadata. Refit the model before learning."
+            )
         lgps = [LocalGaussianProcess(**lgp_state) for lgp_state in state["lgps"]]
+        reference_values = np.asarray(state["reference_values"], dtype=float)
         committee = cls(
             lgps=lgps,
-            n_observations=state["n_observations"],
-            reference_values=np.asarray(state["reference_values"], dtype=float),
+            reference_values=reference_values,
+            n_curves=int(state["n_curves"]),
             nuisance=state["nuisance"],
             stochastic=state["stochastic"],
         )
@@ -285,8 +303,8 @@ class LGPCommittee:
     def write(self, fn_out: PathLike) -> None:
 
         state = {
-            "n_observations": self.n_observations,
             "reference_values": self.reference_values.tolist(),
+            "n_curves": self.n_curves,
             "nuisance": self.nuisance,
             "stochastic": self.stochastic,
             "error": self.error,

{bfflearn-0.2.0 → bfflearn-0.3.0}/bff/bayes/learning.py

@@ -78,20 +78,6 @@ class LearningProblem:
                 + ", ".join(sorted(inconsistent_inputs))
             )
 
-        model_input_shapes = {
-            qoi: tuple(int(dim) for dim in model.lgps[0].X_train.shape)
-            for qoi, model in self.models.items()
-        }
-        if len(set(model_input_shapes.values())) != 1:
-            shape_summary = ", ".join(
-                f"{qoi}={shape}"
-                for qoi, shape in sorted(model_input_shapes.items())
-            )
-            raise ValueError(
-                "All surrogate models must expect the same training input shape. "
-                f"Found: {shape_summary}"
-            )
-
         n_params = {model.n_params for model in self.models.values()}
         if len(n_params) != 1:
             raise ValueError("All surrogate models must have the same input dimension.")
@@ -114,6 +100,17 @@ class LearningProblem:
                 + ", ".join(sorted(invalid))
             )
 
+        invalid_curve_schema = []
+        for qoi, model in self.models.items():
+            n_curves = int(getattr(model, "n_curves", 0))
+            if n_curves <= 0 or model.reference_values.size % n_curves != 0:
+                invalid_curve_schema.append(qoi)
+        if invalid_curve_schema:
+            raise ValueError(
+                "Models with incompatible n_curves metadata: "
+                + ", ".join(sorted(invalid_curve_schema))
+            )
+
     @property
     def qoi_names(self) -> list[str]:
         return list(self.models)
@@ -306,8 +303,8 @@ def fit_lgp_committee(
     test_fraction: float,
     n_hyper: int,
     committee: int,
-    n_observations: int,
     reference_values: np.ndarray,
+    n_curves: int,
     nuisance: float | None,
     fn_out: PathLike | None,
     device: str,
@@ -395,10 +392,10 @@ def fit_lgp_committee(
         logger.status("Committee", f"{i}/{committee}", level=2, overwrite=True)
 
     lgp_committee = LGPCommittee(
-        lgps,
-        n_observations,
-        reference_values,
-        nuisance,
+        lgps=lgps,
+        reference_values=reference_values,
+        n_curves=n_curves,
+        nuisance=nuisance,
     )
     lgp_committee.validate(X_test, y_test)
     logger.done(
@@ -413,20 +410,11 @@ def fit_lgp_committee(
     return lgp_committee
 
 
-def _effective_observations(
-    dataset: QoIDataset,
-    observation_scale: float = 1.0,
-) -> int:
-    """Return the effective observation count used in the likelihood term."""
-    return max(1, int(round(dataset.n_observations * float(observation_scale))))
-
-
 def fit_surrogates(
     datasets: Sequence[QoIDataset],
     *,
     y_means: Optional[Mapping[str, MeanFunction | str]] = None,
     hyperpriors: Optional[Mapping[str, Priors | Sequence]] = None,
-    observation_scales: Optional[Mapping[str, float]] = None,
     model_paths: Optional[Mapping[str, PathLike | None]] = None,
     reuse_models: bool = True,
     n_hyper_max: int = 200,
@@ -441,7 +429,6 @@ def fit_surrogates(
     logger = logger or Logger("fit")
     y_means = dict(y_means or {})
     hyperpriors = dict(hyperpriors or {})
-    observation_scales = dict(observation_scales or {})
     model_paths = dict(model_paths or {})
 
     if owns_logger:
@@ -456,10 +443,6 @@ def fit_surrogates(
             )
 
         qoi = dataset.name
-        n_observations = _effective_observations(
-            dataset,
-            observation_scales.get(qoi, 1.0),
-        )
         logger.info(f"QoI {qoi}", level=1)
 
         fn_model_raw = model_paths.get(qoi)
@@ -469,19 +452,20 @@ def fit_surrogates(
 
         if reuse_models and fn_model is not None and fn_model.exists():
             models[qoi] = LGPCommittee.load(fn_model)
-            models[qoi].n_observations = n_observations
             models[qoi].reference_values = np.asarray(
                 dataset.outputs_ref,
                 dtype=float,
             ).reshape(-1)
+            models[qoi].n_eff = float(models[qoi].reference_values.size)
+            models[qoi].n_curves = dataset.n_curves
             if models[qoi].reference_values.size != models[qoi].y_size:
                 raise ValueError(
                     f"Cached surrogate for {qoi!r} is incompatible with the "
                     "current reference observation size."
                 )
+            models[qoi].write(fn_model)
             logger.info(
-                f"Using cached surrogate model. | obs = {n_observations} "
-                f"| MAPE = {models[qoi].error:.2f}",
+                f"Using cached surrogate model. | MAPE = {models[qoi].error:.2f}",
                 level=2,
             )
             logger.blank()
@@ -494,8 +478,8 @@ def fit_surrogates(
             test_fraction=test_fraction,
             n_hyper=n_hyper_max,
             committee=committee_size,
-            n_observations=n_observations,
             reference_values=dataset.outputs_ref,
+            n_curves=dataset.n_curves,
             nuisance=dataset.nuisance,
             fn_out=fn_model,
             device=device,
@@ -503,7 +487,6 @@ def fit_surrogates(
             opt_kwargs=opt_kwargs,
             hyperpriors=hyperpriors.get(qoi),
         )
-        logger.kv("Effective observations", n_observations, level=2)
         logger.blank()
 
     return models

{bfflearn-0.2.0 → bfflearn-0.3.0}/bff/bayes/likelihoods.py

@@ -10,6 +10,42 @@ if TYPE_CHECKING:
     from .learning import LearningProblem
 
 
+def _split_parameters_and_sigmas(
+    theta: torch.Tensor,
+    problem: LearningProblem,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Return explicit parameters and one scalar nuisance per QoI."""
+    n_params = problem.n_params
+    params = theta[:, :n_params]
+    nuisance_free = theta[:, n_params:]
+
+    sigma_columns = []
+    j = 0
+    for model in problem.models.values():
+        if model.nuisance is None:
+            sigma_columns.append(nuisance_free[:, j].exp())
+            j += 1
+        else:
+            sigma_columns.append(
+                torch.full(
+                    (len(theta),),
+                    float(model.nuisance),
+                    device=theta.device,
+                    dtype=theta.dtype,
+                )
+            )
+    return params, torch.stack(sigma_columns, dim=1)
+
+
+def _valid_parameter_mask(
+    params: torch.Tensor,
+    problem: LearningProblem,
+) -> torch.Tensor:
+    if problem.constraint is None:
+        return torch.ones(len(params), dtype=bool, device=params.device)
+    return problem.constraint(params)
+
+
 def loo_log_likelihood(
     theta: torch.Tensor, X: torch.Tensor, y: torch.Tensor
 ) -> torch.Tensor:
@@ -103,50 +139,37 @@ def gaussian_log_likelihood(
         Log likelihood for each sample in `theta`, shape (n_samples,).
     """
 
-    # Assign device
-    device = theta.device
-
-    # Split the theta into parameters and nuisances
-    n_params = problem.n_params
-    params = theta[:, :n_params]
-    nuisance_free = theta[:, n_params:]
+    contributions = gaussian_log_likelihood_by_qoi(theta, problem)
+    return torch.stack(tuple(contributions.values())).sum(dim=0)
 
-    sigma_columns = []
-    j = 0
-    for model in problem.models.values():
-        if model.nuisance is None:
-            sigma_columns.append(nuisance_free[:, j].exp())
-            j += 1
-        else:
-            sigma_columns.append(
-                torch.full(
-                    (len(theta),),
-                    float(model.nuisance),
-                    device=device,
-                    dtype=theta.dtype,
-                )
-            )
-    sigmas = torch.stack(sigma_columns, dim=1)
 
-    # Check if the parameters are within the valid bounds
-    if problem.constraint is not None:
-        mask = problem.constraint(params)
-    else:
-        mask = torch.ones(len(theta), dtype=bool, device=device)
+def gaussian_log_likelihood_by_qoi(
+    theta: torch.Tensor,
+    problem: LearningProblem,
+) -> dict[str, torch.Tensor]:
+    """Compute one Gaussian log-likelihood contribution per QoI."""
+    params, sigmas = _split_parameters_and_sigmas(theta, problem)
+    mask = _valid_parameter_mask(params, problem)
     params = params[mask]
     sigmas = sigmas[mask]
 
-    # Compute the log-likelihod
-    log_likelihood = torch.full((len(theta), ), -torch.inf, device=device)
-    if mask.any():
-        log_like_valid = torch.zeros(mask.sum(), device=device)
-        for (qoi, model), sigma in zip(problem.models.items(), sigmas.T):
+    contributions = {}
+    for (qoi, model), sigma in zip(problem.models.items(), sigmas.T):
+        contribution = torch.full(
+            (len(theta),),
+            -torch.inf,
+            device=theta.device,
+            dtype=theta.dtype,
+        )
+        if mask.any():
             y_trial = model.predict(params)
-            N = model.n_observations
             diff = problem.observations[qoi] - y_trial
-            ssq = torch.sum(diff**2, dim=1)
-            log_like_valid += -0.5 * ssq / sigma**2 - N * torch.log(sigma)
-
-        log_likelihood[mask] = log_like_valid
+            mse = torch.mean(diff**2, dim=1)
+            n_eff = float(model.n_eff)
+            contribution[mask] = (
+                -0.5 * n_eff * mse / sigma**2
+                - n_eff * torch.log(sigma)
+            )
+        contributions[qoi] = contribution
 
-    return log_likelihood
+    return contributions