bfflearn 0.3.0

Bayesian workflows for fixed-charge molecular force fields

Bayesic Force Fields

Bayesic Force Fields (BFF) is a Python toolkit for learning fixed-charge 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

Workflow

build -> prepare-assets -> evaluate-snapshots
                       -> sample -> analyze -> fit -> learn -> validate

The command-line interface guides a force-field model from prepared molecular systems to sampled trajectories, quantities of interest, surrogate models, and validated posterior samples. See the CLI reference for the individual commands.

Installation

Create an environment, install the PyTorch build appropriate for your machine, and then install BFF:

mamba create -n bfflearn python=3.10 pip
mamba activate bfflearn
pip install bfflearn

For Jupyter notebooks, install the optional notebook tools:

pip install "bfflearn[notebook]"

WARNING: GPU-enabled PyTorch must be installed separately. Use the official PyTorch installation selector to choose the command matching your CUDA version before running fitting, learning, or the posterior notebooks.

Full MD workflows also require GROMACS. CP2K and PLUMED are needed only for the stages that use them. See the installation guide for details, CUDA guidance, and the repository-development setup.

Quick Start

Install the example tree and choose a walkthrough:

bff examples
cd examples/acetate

• Acetate: complete staged MD workflow.
• Arbitrary data: notebook using existing tabular simulation results and targets.
• Neon Mie: notebook using published RDF data.

The examples guide explains which starting point fits your data. The acetate walkthrough shows the full command sequence.

Supported Parameters

BFF currently updates and learns four GROMACS force-field parameter families:

Parameter	Bound label example
Partial charge	charge O1 O2
Lennard-Jones sigma	sigma OW
Lennard-Jones epsilon	epsilon OW
Function-9 dihedral force constant	dihedraltype9_3_180

Multiple names in one label share one learned value. Charges can additionally participate in hierarchical residue- or system-level constraints. The sample configuration reference documents the complete syntax and matching rules.

Architecture

flowchart LR
    A["YAML configs or Python API"] --> B["Simulation workflows"]
    B --> C["Trajectories and reference data"]
    C --> D["QoIDataset"]
    D --> E["Gaussian-process surrogates"]
    E --> F["Posterior learning and validation"]

The architecture guide describes the package modules, workflow stages, persisted artifacts, and repository layout.

Documentation

• Installation
• Examples
• Configuration reference
• Architecture
• Changelog
• Development
• Contributing
• Support
• Security

Citation

If you use BFF, please cite:

Kostal, V.; Shanks, B. L.; Jungwirth, P.; Martinez-Seara, H. Bayesian Learning for Accurate and Robust Biomolecular Force Fields. J. Chem. Theory Comput. 2026, 22 (5), 2652-2663. https://doi.org/10.1021/acs.jctc.5c02051

The exact publication snapshot is archived as v0.0.1.

License

BFF is distributed under the GNU GPL v3.