bfflearn 0.4.2__tar.gz → 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bfflearn-0.5.0/AGENTS.md +105 -0
- bfflearn-0.5.0/CHANGELOG.md +307 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/CITATION.cff +2 -2
- bfflearn-0.5.0/CONTRIBUTING.md +15 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/MANIFEST.in +1 -1
- bfflearn-0.5.0/PKG-INFO +180 -0
- bfflearn-0.5.0/README.md +130 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/SUPPORT.md +3 -2
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/__init__.py +19 -16
- bfflearn-0.5.0/bff/bayes/effective_observations.py +78 -0
- bfflearn-0.5.0/bff/bayes/fit.py +452 -0
- bfflearn-0.5.0/bff/bayes/gaussian_process.py +302 -0
- bfflearn-0.5.0/bff/bayes/kernels.py +35 -0
- bfflearn-0.5.0/bff/bayes/learning.py +385 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/bayes/likelihoods.py +30 -51
- bfflearn-0.5.0/bff/bayes/means.py +131 -0
- bfflearn-0.5.0/bff/bayes/posterior.py +27 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/bayes/priors.py +61 -83
- bfflearn-0.5.0/bff/bayes/results.py +392 -0
- bfflearn-0.5.0/bff/bayes/utils.py +82 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/cli.py +10 -30
- bfflearn-0.5.0/bff/domain/__init__.py +19 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/domain/bias.py +0 -68
- bfflearn-0.5.0/bff/domain/charge_constraints.py +193 -0
- bfflearn-0.5.0/bff/domain/samples.py +189 -0
- bfflearn-0.5.0/bff/domain/specs.py +353 -0
- bfflearn-0.5.0/bff/domain/systems.py +98 -0
- bfflearn-0.5.0/bff/gromacs.py +107 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/__init__.py +0 -3
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/colvars.py +0 -8
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/logs.py +1 -16
- bfflearn-0.5.0/bff/io/mdp.py +42 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/progress.py +23 -14
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/utils.py +6 -30
- bfflearn-0.5.0/bff/mcmc/convergence.py +135 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/mcmc/proposal.py +14 -9
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/mcmc/sampler.py +99 -140
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/plotting.py +236 -454
- bfflearn-0.5.0/bff/qoi/__init__.py +11 -0
- bfflearn-0.5.0/bff/qoi/analysis.py +164 -0
- bfflearn-0.4.2/bff/qoi/data.py → bfflearn-0.5.0/bff/qoi/dataset.py +70 -36
- bfflearn-0.5.0/bff/qoi/hbonds.py +235 -0
- bfflearn-0.5.0/bff/qoi/rdf.py +134 -0
- bfflearn-0.5.0/bff/qoi/routines.py +140 -0
- bfflearn-0.5.0/bff/qoi/trajectory.py +132 -0
- bfflearn-0.5.0/bff/slurm.py +208 -0
- bfflearn-0.5.0/bff/topology.py +205 -0
- bfflearn-0.5.0/bff/workflows/build/box.py +287 -0
- bfflearn-0.5.0/bff/workflows/build/config.py +143 -0
- bfflearn-0.5.0/bff/workflows/build/main.py +290 -0
- bfflearn-0.5.0/bff/workflows/build_qoi_datasets/config.py +278 -0
- bfflearn-0.5.0/bff/workflows/build_qoi_datasets/main.py +239 -0
- bfflearn-0.5.0/bff/workflows/campaign/config.py +253 -0
- bfflearn-0.5.0/bff/workflows/campaign/job.py +302 -0
- bfflearn-0.5.0/bff/workflows/campaign/run.py +491 -0
- bfflearn-0.5.0/bff/workflows/config.py +326 -0
- bfflearn-0.5.0/bff/workflows/fit_lgp/config.py +110 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/fit_lgp/main.py +15 -11
- bfflearn-0.5.0/bff/workflows/learn/config.py +198 -0
- bfflearn-0.5.0/bff/workflows/learn/main.py +203 -0
- bfflearn-0.5.0/bff/workflows/sample_parameters/config.py +101 -0
- bfflearn-0.5.0/bff/workflows/sample_parameters/main.py +39 -0
- bfflearn-0.5.0/bff/workflows/validate/config.py +96 -0
- bfflearn-0.5.0/bff/workflows/validate/main.py +101 -0
- bfflearn-0.5.0/bfflearn.egg-info/PKG-INFO +180 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bfflearn.egg-info/SOURCES.txt +19 -51
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bfflearn.egg-info/requires.txt +1 -1
- bfflearn-0.5.0/docs/changelog.md +414 -0
- bfflearn-0.5.0/docs/cli.md +36 -0
- bfflearn-0.5.0/docs/configuration/build-qoi-datasets.md +257 -0
- bfflearn-0.5.0/docs/configuration/build.md +92 -0
- bfflearn-0.5.0/docs/configuration/fit-lgp.md +112 -0
- bfflearn-0.5.0/docs/configuration/index.md +89 -0
- bfflearn-0.5.0/docs/configuration/learn.md +169 -0
- bfflearn-0.5.0/docs/configuration/sample-parameters.md +285 -0
- bfflearn-0.5.0/docs/configuration/snippets/campaign-options.md +59 -0
- bfflearn-0.5.0/docs/configuration/validate.md +139 -0
- bfflearn-0.5.0/docs/development.md +87 -0
- bfflearn-0.5.0/docs/examples/acetate.md +107 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/docs/examples/arbitrary-data.md +10 -10
- bfflearn-0.5.0/docs/examples/index.md +12 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/docs/examples/neon-mie-lgpmd.md +13 -15
- bfflearn-0.5.0/docs/index.md +82 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/docs/installation.md +0 -1
- bfflearn-0.5.0/docs/migration.md +174 -0
- bfflearn-0.5.0/docs/reference-trajectories.md +83 -0
- bfflearn-0.5.0/docs/results.md +92 -0
- bfflearn-0.5.0/docs/workflow.md +63 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/mkdocs.yml +15 -8
- {bfflearn-0.4.2 → bfflearn-0.5.0}/pyproject.toml +3 -2
- bfflearn-0.4.2/AGENTS.md +0 -127
- bfflearn-0.4.2/CHANGELOG.md +0 -32
- bfflearn-0.4.2/CONTRIBUTING.md +0 -32
- bfflearn-0.4.2/PKG-INFO +0 -195
- bfflearn-0.4.2/README.md +0 -145
- bfflearn-0.4.2/bff/bayes/effective_observations.py +0 -31
- bfflearn-0.4.2/bff/bayes/gaussian_process.py +0 -327
- bfflearn-0.4.2/bff/bayes/kernels.py +0 -71
- bfflearn-0.4.2/bff/bayes/learning.py +0 -603
- bfflearn-0.4.2/bff/bayes/means.py +0 -21
- bfflearn-0.4.2/bff/bayes/posterior.py +0 -62
- bfflearn-0.4.2/bff/bayes/results.py +0 -538
- bfflearn-0.4.2/bff/bayes/utils.py +0 -371
- bfflearn-0.4.2/bff/domain/__init__.py +0 -18
- bfflearn-0.4.2/bff/domain/campaign.py +0 -91
- bfflearn-0.4.2/bff/domain/sample.py +0 -330
- bfflearn-0.4.2/bff/domain/specs.py +0 -520
- bfflearn-0.4.2/bff/domain/systems.py +0 -259
- bfflearn-0.4.2/bff/io/cp2k.py +0 -190
- bfflearn-0.4.2/bff/io/extxyz.py +0 -236
- bfflearn-0.4.2/bff/io/mdp.py +0 -98
- bfflearn-0.4.2/bff/io/schedulers.py +0 -118
- bfflearn-0.4.2/bff/mcmc/convergence.py +0 -168
- bfflearn-0.4.2/bff/qoi/__init__.py +0 -9
- bfflearn-0.4.2/bff/qoi/analysis.py +0 -219
- bfflearn-0.4.2/bff/qoi/hbonds.py +0 -255
- bfflearn-0.4.2/bff/qoi/rdf.py +0 -236
- bfflearn-0.4.2/bff/qoi/routines.py +0 -297
- bfflearn-0.4.2/bff/tools.py +0 -152
- bfflearn-0.4.2/bff/topology.py +0 -516
- bfflearn-0.4.2/bff/workflows/_shared/campaign.py +0 -714
- bfflearn-0.4.2/bff/workflows/_shared/config.py +0 -354
- bfflearn-0.4.2/bff/workflows/_shared/preparation.py +0 -315
- bfflearn-0.4.2/bff/workflows/_shared/scheduler.py +0 -143
- bfflearn-0.4.2/bff/workflows/build/config.py +0 -268
- bfflearn-0.4.2/bff/workflows/build/main.py +0 -285
- bfflearn-0.4.2/bff/workflows/build_qoi_datasets/config.py +0 -329
- bfflearn-0.4.2/bff/workflows/build_qoi_datasets/main.py +0 -220
- bfflearn-0.4.2/bff/workflows/fit_lgp/config.py +0 -161
- bfflearn-0.4.2/bff/workflows/label_snapshots/__init__.py +0 -1
- bfflearn-0.4.2/bff/workflows/label_snapshots/config.py +0 -252
- bfflearn-0.4.2/bff/workflows/label_snapshots/main.py +0 -845
- bfflearn-0.4.2/bff/workflows/learn/config.py +0 -325
- bfflearn-0.4.2/bff/workflows/learn/main.py +0 -280
- bfflearn-0.4.2/bff/workflows/md/__init__.py +0 -1
- bfflearn-0.4.2/bff/workflows/md/config.py +0 -107
- bfflearn-0.4.2/bff/workflows/md/main.py +0 -379
- bfflearn-0.4.2/bff/workflows/sample_parameters/config.py +0 -136
- bfflearn-0.4.2/bff/workflows/sample_parameters/main.py +0 -28
- bfflearn-0.4.2/bff/workflows/validate/config.py +0 -159
- bfflearn-0.4.2/bff/workflows/validate/main.py +0 -53
- bfflearn-0.4.2/bfflearn.egg-info/PKG-INFO +0 -195
- bfflearn-0.4.2/docs/architecture.md +0 -123
- bfflearn-0.4.2/docs/changelog.md +0 -139
- bfflearn-0.4.2/docs/cli.md +0 -70
- bfflearn-0.4.2/docs/configuration/build-qoi-datasets.md +0 -135
- bfflearn-0.4.2/docs/configuration/build.md +0 -111
- bfflearn-0.4.2/docs/configuration/fit-lgp.md +0 -35
- bfflearn-0.4.2/docs/configuration/label-snapshots.md +0 -60
- bfflearn-0.4.2/docs/configuration/learn.md +0 -87
- bfflearn-0.4.2/docs/configuration/sample-parameters.md +0 -190
- bfflearn-0.4.2/docs/configuration/validate.md +0 -129
- bfflearn-0.4.2/docs/development.md +0 -128
- bfflearn-0.4.2/docs/examples/acetate.md +0 -60
- bfflearn-0.4.2/docs/examples/index.md +0 -15
- bfflearn-0.4.2/docs/index.md +0 -91
- bfflearn-0.4.2/docs/migration.md +0 -70
- bfflearn-0.4.2/tests/bayes/test_effective_observations.py +0 -28
- bfflearn-0.4.2/tests/bayes/test_gaussian_process.py +0 -161
- bfflearn-0.4.2/tests/bayes/test_learning_problem.py +0 -177
- bfflearn-0.4.2/tests/bayes/test_likelihoods.py +0 -149
- bfflearn-0.4.2/tests/bayes/test_priors_posterior.py +0 -85
- bfflearn-0.4.2/tests/bayes/test_results.py +0 -388
- bfflearn-0.4.2/tests/bayes/test_utils.py +0 -29
- bfflearn-0.4.2/tests/domain/test_specs.py +0 -191
- bfflearn-0.4.2/tests/io/_fake_mdanalysis.py +0 -49
- bfflearn-0.4.2/tests/io/test_cp2k.py +0 -56
- bfflearn-0.4.2/tests/io/test_cp2k_collect.py +0 -45
- bfflearn-0.4.2/tests/io/test_logs.py +0 -148
- bfflearn-0.4.2/tests/io/test_mdp.py +0 -64
- bfflearn-0.4.2/tests/mcmc/test_convergence.py +0 -61
- bfflearn-0.4.2/tests/mcmc/test_proposal.py +0 -77
- bfflearn-0.4.2/tests/mcmc/test_sampler.py +0 -119
- bfflearn-0.4.2/tests/qoi/test_analysis.py +0 -338
- bfflearn-0.4.2/tests/qoi/test_data.py +0 -104
- bfflearn-0.4.2/tests/qoi/test_rdf.py +0 -184
- bfflearn-0.4.2/tests/test_examples.py +0 -326
- bfflearn-0.4.2/tests/test_plotting.py +0 -392
- bfflearn-0.4.2/tests/test_release_metadata.py +0 -27
- bfflearn-0.4.2/tests/test_topology.py +0 -102
- bfflearn-0.4.2/tests/workflows/test_charge_constraints.py +0 -168
- bfflearn-0.4.2/tests/workflows/test_configs.py +0 -876
- bfflearn-0.4.2/tests/workflows/test_pipeline_manifests.py +0 -1459
- bfflearn-0.4.2/tests/workflows/test_preparation.py +0 -94
- bfflearn-0.4.2/tests/workflows/test_regressions.py +0 -281
- bfflearn-0.4.2/tests/workflows/test_scheduler.py +0 -120
- bfflearn-0.4.2/tests/workflows/test_validate.py +0 -122
- {bfflearn-0.4.2 → bfflearn-0.5.0}/LICENSE +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/SECURITY.md +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/bayes/__init__.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/commands.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/plumed.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/mcmc/__init__.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/__init__.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/build/__init__.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/build_qoi_datasets/__init__.py +0 -0
- {bfflearn-0.4.2/bff/workflows/_shared → bfflearn-0.5.0/bff/workflows/campaign}/__init__.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/examples.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/fit_lgp/__init__.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/learn/__init__.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/sample_parameters/__init__.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/validate/__init__.py +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bfflearn.egg-info/dependency_links.txt +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bfflearn.egg-info/entry_points.txt +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/bfflearn.egg-info/top_level.txt +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/docs/assets/bff-logo.pdf +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/docs/assets/bff-logo.svg +0 -0
- {bfflearn-0.4.2 → bfflearn-0.5.0}/setup.cfg +0 -0
bfflearn-0.5.0/AGENTS.md
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Guidance for AI Coding Agents
|
|
2
|
+
|
|
3
|
+
Repository context for making safe, focused changes. The user's instructions
|
|
4
|
+
and the documentation come first; this file does not widen a task.
|
|
5
|
+
|
|
6
|
+
## Before editing
|
|
7
|
+
|
|
8
|
+
1. Read `README.md`, `docs/workflow.md`, `docs/development.md`, and the page
|
|
9
|
+
of the stage you change (`docs/configuration/<stage>.md`).
|
|
10
|
+
2. Run `git status --short`. The worktree may hold the user's work, including
|
|
11
|
+
untracked run outputs inside `examples/`: keep it, never discard it for a
|
|
12
|
+
clean tree.
|
|
13
|
+
3. Find the nearby tests and follow existing names, file layouts, and config
|
|
14
|
+
conventions.
|
|
15
|
+
4. Make the smallest cohesive change; update tests and docs with it.
|
|
16
|
+
|
|
17
|
+
## Map
|
|
18
|
+
|
|
19
|
+
| Path | Content |
|
|
20
|
+
| --- | --- |
|
|
21
|
+
| `bff/cli.py` | the `bff` command; thin, calls `bff/workflows/<stage>/main.py` |
|
|
22
|
+
| `bff/__init__.py` | public Python API and `__version__` |
|
|
23
|
+
| `bff/workflows/config.py` | `ConfigSection`: read every option through it |
|
|
24
|
+
| `bff/workflows/<stage>/` | one package per stage: `config.py` (parser) and `main.py` |
|
|
25
|
+
| `bff/workflows/campaign/` | MD campaigns of `sample-parameters` and `validate`; `job.py` is the per-sample `bff md` job |
|
|
26
|
+
| `bff/gromacs.py`, `bff/slurm.py` | GROMACS runs, Slurm job arrays |
|
|
27
|
+
| `bff/qoi/` | QoI routines (built-in and custom share one interface), analysis, `QoIDataset` |
|
|
28
|
+
| `bff/bayes/`, `bff/mcmc/` | surrogates, likelihoods, posterior sampling |
|
|
29
|
+
| `bff/domain/`, `bff/io/` | data models (`specs.yaml`, `samples.yaml`), file formats |
|
|
30
|
+
| `scripts/label_structures.py` | standalone CP2K labeling; not installed by pip; must not import `bff` |
|
|
31
|
+
| `examples/` | acetate MD workflow and two notebooks |
|
|
32
|
+
| `docs/` | MkDocs site; `docs/configuration/` is the YAML contract |
|
|
33
|
+
|
|
34
|
+
## Pipeline
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
build -> [reference MD, outside BFF] -> sample-parameters -> build-qoi-datasets
|
|
38
|
+
-> fit-lgp -> learn -> validate
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Use these stage names everywhere and add no aliases for retired names. `bff md`
|
|
42
|
+
is internal. BFF never runs the reference MD; do not add substitute reference
|
|
43
|
+
trajectories or an MLIP implementation.
|
|
44
|
+
|
|
45
|
+
## Contracts
|
|
46
|
+
|
|
47
|
+
- Stage directories, file names, `system_id` and `sample_id` values, and
|
|
48
|
+
`samples.yaml`/`specs.yaml` are interfaces. Pair systems by ID, never by
|
|
49
|
+
order or display name.
|
|
50
|
+
- A new or changed option needs: its parser (through `ConfigSection`), a test,
|
|
51
|
+
its row in `docs/configuration/` (`tests/test_docs_config.py` checks this),
|
|
52
|
+
a link in `docs/configuration/index.md` for a new option group, the example
|
|
53
|
+
YAML if users set it, and a changelog entry if it is user-visible.
|
|
54
|
+
- Campaign files of unfinished samples (`production.cpt`, `.tpr`, `.log`) are
|
|
55
|
+
what a restart needs: never prune them. Only systems with a
|
|
56
|
+
`production.done` marker are cleaned up.
|
|
57
|
+
- A reference trajectory has the atoms, in order, of
|
|
58
|
+
`systems/<system_id>/reference/` written by `bff build`.
|
|
59
|
+
|
|
60
|
+
## External software
|
|
61
|
+
|
|
62
|
+
GROMACS, Colvars/PLUMED, Slurm, and CP2K stay at the edges (`gromacs.py`,
|
|
63
|
+
`slurm.py`, `io/`, the labeling script). Tests use temporary files and mocked
|
|
64
|
+
processes; never claim an external run succeeded when only staging was
|
|
65
|
+
tested. On a shared cluster, follow the site's rules for running test suites
|
|
66
|
+
and builds (for example inside a scheduler job).
|
|
67
|
+
|
|
68
|
+
## Style
|
|
69
|
+
|
|
70
|
+
- Linear, readable code; no wrappers that hide control flow and no
|
|
71
|
+
speculative abstractions. Reuse the existing domain models.
|
|
72
|
+
- `pathlib.Path`; paths in configs resolve relative to the config file.
|
|
73
|
+
- Errors name the stage, system or sample, and the key or path.
|
|
74
|
+
- Python 3.10 compatible; Ruff settings in `pyproject.toml`.
|
|
75
|
+
- Every bug fix gets a regression test of public behavior.
|
|
76
|
+
|
|
77
|
+
## Examples and notebooks
|
|
78
|
+
|
|
79
|
+
- `examples/acetate` is deliberately simple: two systems (`acetate` with an
|
|
80
|
+
RDF QoI, `calcium-acetate` with a Colvars PMF read by `inputs/pmf.py`), one
|
|
81
|
+
`config.yaml` per stage. The sampling config runs locally; its Slurm block
|
|
82
|
+
is commented out and `tests/test_examples.py` uncomments and loads it, so
|
|
83
|
+
keep it valid.
|
|
84
|
+
- Example YAML must load with the CLI's parser; mark settings users must
|
|
85
|
+
adapt with `ADAPT`.
|
|
86
|
+
- Committed notebooks are output-free. The data notebooks let BFF choose the
|
|
87
|
+
device (no `cuda` or `DEVICE` in them). Execute notebooks in a temporary
|
|
88
|
+
copy so generated files stay out of the repository.
|
|
89
|
+
|
|
90
|
+
## Checks
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
make check # compileall, ruff, pytest, mkdocs --strict
|
|
94
|
+
python -m build && python -m twine check dist/* # packaging changes
|
|
95
|
+
git diff --check
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Report exactly what was and was not validated when a check cannot run.
|
|
99
|
+
|
|
100
|
+
## Releases
|
|
101
|
+
|
|
102
|
+
Keep the version identical in `pyproject.toml`, `bff/__init__.py`, and
|
|
103
|
+
`CITATION.cff`; update `CHANGELOG.md` and `docs/changelog.md`. Before a release
|
|
104
|
+
commit, check untracked files so new packages, configs, docs, and tests are
|
|
105
|
+
included.
|
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
## `0.5.0` - 2026-10-09
|
|
2
|
+
|
|
3
|
+
### Changed
|
|
4
|
+
|
|
5
|
+
- BFF pins `gmxtopology==0.3.0`, so upgrading `bfflearn` also upgrades `gmxtopology`. Topologies are read with their conditional
|
|
6
|
+
blocks evaluated, bonded parameters are matched on bonded atom types, and
|
|
7
|
+
written topologies keep only the molecule types, atom types and CMAP grids of
|
|
8
|
+
the system.
|
|
9
|
+
- Examples are streamlined. The acetate example has one directory per stage,
|
|
10
|
+
named after its command (`01-build`, `02-reference-md`,
|
|
11
|
+
`03-sample-parameters`, `04-build-qoi-datasets`, `05-fit-lgp`, `06-learn`,
|
|
12
|
+
`07-validate`), each holding one `config.yaml`; the old `configs/`
|
|
13
|
+
directory and its copy step are gone. It has two systems: `acetate` (QoI:
|
|
14
|
+
acetate-water RDFs) and `calcium-acetate`, whose Ca-C2 distance is biased by
|
|
15
|
+
Colvars metadynamics (`inputs/colvars.dat`) and whose PMF is a QoI read by
|
|
16
|
+
the custom file routine `inputs/pmf.py` and compared with an MLIP reference
|
|
17
|
+
PMF (`02-reference-md/calcium-acetate.pmf`). The sampling config runs
|
|
18
|
+
locally and carries the Slurm settings as a commented block. The CP2K inputs
|
|
19
|
+
of the labeling script (revPBE0-D3 only) are in `02-reference-md/cp2k/`.
|
|
20
|
+
The two acetate notebooks are merged into `06-learn/posterior.ipynb`, and
|
|
21
|
+
the arbitrary-data and neon notebooks are shortened. `LGPCommittee.n_eff` is
|
|
22
|
+
inferred from the reference curve when the committee is created.
|
|
23
|
+
- `fit-lgp` always runs on the CPU in float64 (`fit.device` is removed) and
|
|
24
|
+
the hyperparameter search uses L-BFGS-B with autograd gradients inside box
|
|
25
|
+
bounds derived from the priors, with up to two restarts from prior draws.
|
|
26
|
+
`fit.lr` is removed; `fit.max_iter` (default `500`) and `fit.tol_grad`
|
|
27
|
+
(default `1e-4`, largest gradient component) control the search. On the
|
|
28
|
+
acetate data it needs 8-25 iterations instead of the former 10,000 steps.
|
|
29
|
+
The Laplace covariance of committees floors non-positive curvatures.
|
|
30
|
+
Model files hold CPU tensors and load on any machine (including models
|
|
31
|
+
fitted on a GPU by earlier versions); `bff learn` moves them once to
|
|
32
|
+
`mcmc.device`, which now defaults to `auto` (`cuda` if available). The
|
|
33
|
+
sampling loop no longer synchronizes with the host: `Specs`, `Priors`, the
|
|
34
|
+
likelihood, and the accept step run on the device. `gaussian_kernel` always
|
|
35
|
+
uses explicit differences (no `cdist` switch), `LocalGaussianProcess` has no
|
|
36
|
+
`device` argument (use `.to(device, dtype)`), and `fit_surrogates` has no
|
|
37
|
+
`device` argument. `log_posterior` no longer takes `device`.
|
|
38
|
+
- MCMC convergence uses one diagnostic, `bff.mcmc.convergence.diagnose`:
|
|
39
|
+
rank-normalized split R-hat plus bulk and tail effective sample sizes from
|
|
40
|
+
the pooled multi-walker autocovariance (Geyer truncation), for every
|
|
41
|
+
parameter and the log probability. Sampling stops when `rhat_tol` and
|
|
42
|
+
`ess_min` are met at two consecutive checks; `ess_min` now defaults to
|
|
43
|
+
`400`. `Results.diagnostics()` reports the same quantities (`rhat`,
|
|
44
|
+
`ess_bulk`, `ess_tail`; no autocorrelation time) and `Results.info["mcmc"]`
|
|
45
|
+
stores `max_rhat` and `min_ess`. `ConvergenceInfo` and the autocorrelation
|
|
46
|
+
helpers are removed; older checkpoints cannot be resumed.
|
|
47
|
+
- `learn` writes one self-contained `outputs/results.pt` (prior, posterior
|
|
48
|
+
chain, specifications, QoI information, per-QoI likelihoods) instead of
|
|
49
|
+
`posterior.pt` plus `prior.pt`, and `bff.Results` replaces
|
|
50
|
+
`PosteriorResults`. It provides `samples` in physical units, `map` (the state
|
|
51
|
+
of highest log posterior), `summary()`, `diagnostics()`, `draw()`, and the
|
|
52
|
+
plot methods. Samples are no longer stripped of outliers, and nuisance
|
|
53
|
+
columns are named `noise <qoi>`. `validate` gains `posterior.include_map`.
|
|
54
|
+
Plot functions take only a `Results` and return the figure. In Python,
|
|
55
|
+
`LearningProblem(constraint=...)` is `specs=...`, and `fn_posterior`/
|
|
56
|
+
`fn_priors` is `fn_results`. Checkpoints and posterior files of earlier
|
|
57
|
+
versions cannot be read; rerun `bff learn`.
|
|
58
|
+
- `Specs` is the single parameter specification (`bounds`, `names`,
|
|
59
|
+
`explicit_names`, `implicit_names`, `complete`, `is_valid`, `violations`).
|
|
60
|
+
`latin_hypercube(specs, n, seed)` replaces `RandomParamsGenerator`.
|
|
61
|
+
|
|
62
|
+
- `learn` infers each QoI's effective number of observations from the
|
|
63
|
+
correlation length of its reference curve (Satterthwaite degrees of freedom;
|
|
64
|
+
scalars count once per value) instead of the peak-counting heuristic.
|
|
65
|
+
`models.<name>.tolerance` is now the accepted deviation from the reference
|
|
66
|
+
in the QoI's units and adds to the likelihood variance (`sigma^2 +
|
|
67
|
+
tolerance^2`); it defaults to `0`. `bff.bayes.effective_observations`
|
|
68
|
+
provides `effective_observations`, `curve_n_eff`, and `correlation_length`.
|
|
69
|
+
- Surrogates and datasets use common Gaussian-process names. `QoIDataset`:
|
|
70
|
+
`X`, `y`, `y_ref` (were `inputs`, `outputs`, `outputs_ref`).
|
|
71
|
+
`LocalGaussianProcess`: `mean`, `lengthscales`, `amplitude`,
|
|
72
|
+
`noise_variance` (were `y_mean`, `lengths`, `width`, `sigma`; `sigma` was
|
|
73
|
+
always a variance), `n_inputs`, `n_outputs`. `LGPCommittee`: `members`,
|
|
74
|
+
`y_ref`, `test_error`, `n_members` (were `lgps`, `reference_values`,
|
|
75
|
+
`error`, `size`). `fit_surrogates(y_means=...)` is now `means=...`.
|
|
76
|
+
- Surrogate means: `mean` defaults to `data` (the average training output per
|
|
77
|
+
value) instead of `0`; it also accepts a number, `sigmoid`, or a custom
|
|
78
|
+
`path.py:function`/`module:function`. The RDF sigmoid is centred where each
|
|
79
|
+
reference RDF first reaches 0.5 instead of at a fixed 3 angstrom. Custom
|
|
80
|
+
means are saved in models by reference. A saved model is reused only when
|
|
81
|
+
both its dataset and its mean are unchanged; otherwise it is refitted.
|
|
82
|
+
- Charge constraints: `implicit` names an atom (name or type) of exactly one
|
|
83
|
+
`charge ...` parameter in `bounds` instead of the parameter label. Each
|
|
84
|
+
constraint is one linear equation, and all implicit charges are solved
|
|
85
|
+
together; the rules for nested, non-overlapping constraints and their
|
|
86
|
+
ordering are gone.
|
|
87
|
+
- Campaign artifacts: one `campaign.yaml` holds the job settings shared by all
|
|
88
|
+
samples (jobs run as `bff md campaign.yaml <sample_id>`) instead of a
|
|
89
|
+
`config.yaml` per sample. `samples.yaml` names its parameter columns
|
|
90
|
+
(`parameter_names`), lists `systems` with their `n_steps`, and records each
|
|
91
|
+
sample's outputs per system by role, including the sample's own `topology`,
|
|
92
|
+
which `cleanup` now always keeps. YAML is read and written with libyaml when
|
|
93
|
+
available.
|
|
94
|
+
- `build-qoi-datasets` analyzes each sample with its own topology, so routines
|
|
95
|
+
see the sampled charges. A sample with missing files, a failing trajectory
|
|
96
|
+
or routine, or mismatching QoIs is skipped with a warning instead of
|
|
97
|
+
stopping the stage. In-memory trajectories that would not fit in the
|
|
98
|
+
available memory are read from disk. Datasets record `sample_ids` and
|
|
99
|
+
`parameter_names`; fitted models keep the parameter names, and `learn`
|
|
100
|
+
rejects models fitted to other parameters than its `specs.yaml`.
|
|
101
|
+
- Stage logs share one layout: the stage title, `Config` and one line per
|
|
102
|
+
input or setting, `<step>: Done. | ...` lines, warnings, and a final
|
|
103
|
+
`<Stage>: Done. | summary | time | output`. Progress lines are shown on
|
|
104
|
+
the console only.
|
|
105
|
+
- `sample-parameters` and `validate` share one campaign flow: both write
|
|
106
|
+
`specs.yaml` into the campaign, check every parameter sample against the
|
|
107
|
+
bounds before staging, list all samples in `samples.yaml` from the start,
|
|
108
|
+
record the parameter source under `samples.yaml` `provenance`, and log the
|
|
109
|
+
same parameter summary. New options: `resume` (continue a campaign, running
|
|
110
|
+
only samples not yet completed), `overwrite`, `local.max_parallel_jobs`
|
|
111
|
+
(parallel local samples), and `seed` for `sample-parameters` (a fresh seed
|
|
112
|
+
is drawn and recorded otherwise).
|
|
113
|
+
- Charge-constraint compilation moved to `bff.domain.charge_constraints`
|
|
114
|
+
(`compile_specs`, `check_specs_topologies`).
|
|
115
|
+
- All stage configurations are read by one shared reader with the same rules:
|
|
116
|
+
unknown keys are errors, `null` means "use the default", integers must be
|
|
117
|
+
whole numbers, numbers must be finite (exponent strings such as `1e-3` are
|
|
118
|
+
accepted), booleans must be `true`/`false`, and every error names the full
|
|
119
|
+
key path. Values are now range-checked consistently: for example
|
|
120
|
+
`nsteps.prod >= 1`, `bounds` with `lower < upper`, `mcmc.rhat_tol > 1`,
|
|
121
|
+
`mcmc.priors_disttype` in `normal`/`uniform`, `fit-lgp` `mean` a number or
|
|
122
|
+
`sigmoid`, and devices `cpu`, `cuda[:N]`, or `mps`.
|
|
123
|
+
- The configuration reference lists every option of every stage with type,
|
|
124
|
+
default, and meaning, plus a new conventions page.
|
|
125
|
+
- `charge_constraints` (sample-parameters), `fit` (fit-lgp), and `mcmc`
|
|
126
|
+
(learn) may be omitted to use their defaults.
|
|
127
|
+
- Simulation campaigns can run GROMACS in a node-local `scratch_dir` and copy
|
|
128
|
+
results back, and on Slurm stop production runs cleanly before
|
|
129
|
+
`sbatch.time` (`mdrun -maxh`). With `max_restarts`, samples stopped by the
|
|
130
|
+
time limit are resubmitted and continue from their checkpoints.
|
|
131
|
+
- The production step count is written into a generated
|
|
132
|
+
`production-run.mdp` (which replaces `production-colvars.mdp`) instead of
|
|
133
|
+
being passed as `mdrun -nsteps`.
|
|
134
|
+
- Built-in `rdf` and `hydrogen_bonds` routines now use the same interface as
|
|
135
|
+
custom routines and validate their own options when they run. Their outputs
|
|
136
|
+
are unchanged; hydrogen-bond analysis is substantially faster.
|
|
137
|
+
- Moved `bff.qoi.data` to `bff.qoi.dataset` and `bff.tools.get_unitcell` to
|
|
138
|
+
`bff.qoi`. Custom routines import `QoI`, `get_unitcell`, and `select_atoms`
|
|
139
|
+
from `bff.qoi`.
|
|
140
|
+
- Routines are called as `routine(universe, *, frames, options)` or
|
|
141
|
+
`routine(*, inputs, options)`; `system_id` and `sample_id` are no longer
|
|
142
|
+
passed.
|
|
143
|
+
- Moved surrogate fitting (`fit_surrogates`, MAP search) to `bff.bayes.fit`;
|
|
144
|
+
`bff.bayes.learning` holds posterior learning only.
|
|
145
|
+
- Simulation campaigns (`sample-parameters`, `validate`) run on Slurm as job
|
|
146
|
+
arrays of one `run.sh` instead of one submission per job. `slurm.max_parallel_jobs` limits running tasks; the new
|
|
147
|
+
`slurm.max_array_size` (default 1000) splits large campaigns into
|
|
148
|
+
consecutive arrays.
|
|
149
|
+
- Campaign jobs write directly to `samples/<sample_id>/`; the `outputs/`
|
|
150
|
+
working directory is gone. GROMACS runs inside each system's run directory,
|
|
151
|
+
so `mdout.mdp` and bias outputs no longer land in input directories.
|
|
152
|
+
- A sample whose MD fails no longer aborts a local campaign; it is recorded
|
|
153
|
+
as `failed`, as on Slurm.
|
|
154
|
+
- `sample-parameters` draws all samples from one Latin hypercube instead of
|
|
155
|
+
drawing them one at a time, so samples now fill the parameter space evenly.
|
|
156
|
+
- `build` shares an equilibration only between systems with identical
|
|
157
|
+
topology, templates, box, MDP files, and step counts.
|
|
158
|
+
|
|
159
|
+
- MCMC log-probabilities stay on the compute device (no per-step
|
|
160
|
+
GPU-to-CPU copy), and local-GP predictions reuse a precomputed
|
|
161
|
+
`K^-1 (y - mean)` instead of multiplying by the inverse kernel each call.
|
|
162
|
+
- A NaN parameter vector now gets `-inf` for its own walker only.
|
|
163
|
+
- The source distribution on PyPI no longer contains the tests (the wheel never
|
|
164
|
+
did); they stay in the repository.
|
|
165
|
+
- Documentation is reorganized: a settings overview links every option group
|
|
166
|
+
of every stage, *How BFF Works* replaces the architecture page (the package
|
|
167
|
+
map moved to *Development*), and the README and docs state that BFF does not
|
|
168
|
+
generate reference data.
|
|
169
|
+
- `slurm.sbatch.time` must be a quoted string; YAML reads an unquoted
|
|
170
|
+
`4:00:00` as the number 14400. `slurm.teardown` also runs after a failed
|
|
171
|
+
task. `build.systems[].box` accepts only rectangular boxes, as molecule
|
|
172
|
+
insertion always assumed. `validate.posterior.seed` must be >= 0.
|
|
173
|
+
- Errors of every stage are reported as one line naming the stage, instead of
|
|
174
|
+
a usage message about the config argument.
|
|
175
|
+
|
|
176
|
+
### Removed
|
|
177
|
+
|
|
178
|
+
- The top-level `data/` directory of force-field, MDP, and water templates:
|
|
179
|
+
provide your own inputs, for example from `examples/acetate/inputs/`.
|
|
180
|
+
- `mcmc.include_implicit_charge`, `Bounds`, `ChargeConstraint`,
|
|
181
|
+
`RandomParamsGenerator`, `Priors` file I/O and `from_any`, `sample_posterior`,
|
|
182
|
+
and `prepare_samples`.
|
|
183
|
+
- Removed `models.<name>.n_eff` and `models.<name>.independent_observations`
|
|
184
|
+
from learn configs, and `estimate_curve_n_eff`.
|
|
185
|
+
- Removed the build stage's per-system `system.yaml` (no stage read it),
|
|
186
|
+
`build-qoi-datasets`' `qoi/raw.json` with its `output.write_raw` option, and
|
|
187
|
+
its `training_samples.progress_stride` option.
|
|
188
|
+
- Removed the `project: <path>` shorthand and the undocumented top-level
|
|
189
|
+
`fn_log` from build configs (use `project.directory` and `project.log`), the
|
|
190
|
+
`kind` key of build `bias` mappings, and boolean or single-string `store`
|
|
191
|
+
values. `plots.max_marginal_samples: null` now means the default; use `-1`
|
|
192
|
+
for all samples.
|
|
193
|
+
- Removed `bff label-snapshots`, the hidden `label-snapshot-job` command, the
|
|
194
|
+
`bff.label_snapshots` and `Project.label_snapshots` Python API, and
|
|
195
|
+
`bff.io.cp2k`/`bff.io.extxyz`. BFF no longer runs CP2K; the reference MD is
|
|
196
|
+
an external step documented in the new "Reference trajectories" page. The
|
|
197
|
+
standalone, Slurm-only `scripts/label_structures.py` labels foundation-model
|
|
198
|
+
MD frames with CP2K for MLIP fine-tuning (train/valid/test EXTXYZ and
|
|
199
|
+
isolated-atom energies keyed by atomic number).
|
|
200
|
+
- Removed the `charge` and `multiplicity` build keys and the matching
|
|
201
|
+
`system.yaml` fields; only CP2K labeling used them.
|
|
202
|
+
|
|
203
|
+
### Fixed
|
|
204
|
+
|
|
205
|
+
- A campaign's final cleanup deleted the checkpoints of samples that were
|
|
206
|
+
still incomplete, so `resume: true` had to restart them from scratch; it now
|
|
207
|
+
prunes only systems whose production run finished. A rerun no longer fails
|
|
208
|
+
on the topology left by an attempt that never reached a checkpoint.
|
|
209
|
+
- A Slurm task stopped by `SIGTERM` (time limit, `scancel`) now lets the
|
|
210
|
+
running mdrun checkpoint, copies its files back, and is recorded as
|
|
211
|
+
`incomplete`, so `max_restarts` continues it; before, the sample was lost as
|
|
212
|
+
`failed`. A sample whose job writes no result is `failed` instead of
|
|
213
|
+
reusing a result from an earlier round, and local reruns append to
|
|
214
|
+
`run.out` instead of truncating it.
|
|
215
|
+
- MDP files with inline comments (`nsteps = 500 ; 1 ps`), indented comments,
|
|
216
|
+
or `_` spellings of keys failed or were patched twice; MDP keys are now read
|
|
217
|
+
the way GROMACS reads them.
|
|
218
|
+
- Custom trajectory routines receive the universe positionally, as
|
|
219
|
+
documented, so its parameter may have any name. Samples whose QoI settings
|
|
220
|
+
(for example a grid) differ from the reference are skipped. `~` is expanded
|
|
221
|
+
in reference inputs and custom routine paths. Parallel analysis caps
|
|
222
|
+
in-memory trajectories by the Slurm memory allocation, and a worker killed
|
|
223
|
+
for lack of memory is reported with a hint.
|
|
224
|
+
- `scripts/label_structures.py run` collected results while array tasks were
|
|
225
|
+
still running, because `sbatch --wait` returned early; it now polls
|
|
226
|
+
`squeue` until the arrays leave the queue.
|
|
227
|
+
- `bff learn` resumes a checkpoint written on another device type (CPU vs.
|
|
228
|
+
CUDA) instead of failing on the random-generator state.
|
|
229
|
+
- A charge-constraint selection that fails reports the underlying error
|
|
230
|
+
instead of calling the selection invalid.
|
|
231
|
+
- `fit-lgp` refits a model file written by an older BFF version instead of
|
|
232
|
+
stopping with `reuse_models: true`.
|
|
233
|
+
- `build-qoi-datasets` writes its progress to the log every 100 samples and
|
|
234
|
+
announces the start of the reference and of the sample analysis; a batch
|
|
235
|
+
job's console shows the same lines instead of one per sample.
|
|
236
|
+
- `mean: sigmoid` no longer fails when the sigmoid values are built into the
|
|
237
|
+
surrogate.
|
|
238
|
+
- Running `sample-parameters` or `validate` again on an existing campaign no
|
|
239
|
+
longer mixes newly drawn parameters with the old samples' trajectories; it
|
|
240
|
+
is an error unless `resume` or `overwrite` is set.
|
|
241
|
+
- Validation campaigns in explicit `parameters` mode now contain
|
|
242
|
+
`specs.yaml`, so `build-qoi-datasets` can analyze them.
|
|
243
|
+
- `validate` rejects parameter samples outside the bounds, unknown parameter
|
|
244
|
+
names, and charge constraints that give a different equation in the
|
|
245
|
+
validation systems before staging, instead of failing in every MD job.
|
|
246
|
+
- `max_restarts` with `job_scheduler: local` is an error instead of being
|
|
247
|
+
ignored.
|
|
248
|
+
|
|
249
|
+
- Campaigns started from a build directory (`source`) no longer require the
|
|
250
|
+
build's `production.xtc`, `npt.mdp`, or a loadable `system.yaml`; only the
|
|
251
|
+
files they use must exist.
|
|
252
|
+
- A campaign sample is complete once its production run reaches `n_steps`,
|
|
253
|
+
read from the final checkpoint in the GROMACS log. Runs whose MDP writes no
|
|
254
|
+
compressed trajectory, or whose trajectory is not stored, are no longer
|
|
255
|
+
reported as `incomplete` and resubmitted. A `production.done` marker keeps
|
|
256
|
+
finished systems from rerunning after `cleanup` in a scratch directory.
|
|
257
|
+
- Samples whose campaign did not store a trajectory are usable by
|
|
258
|
+
build-qoi-datasets when their routines only read stored files; a routine
|
|
259
|
+
that needs a missing output fails before analysis with the sample, system,
|
|
260
|
+
and missing role. A missing stored output file is reported per sample.
|
|
261
|
+
|
|
262
|
+
- The learning-rate search no longer accepts runs that diverged to NaN.
|
|
263
|
+
- Walkers can be initialized from uniform priors without charge constraints.
|
|
264
|
+
- `ChargeConstraint` objects can be copied and pickled.
|
|
265
|
+
- The adaptive proposal accumulates its covariance in float64, avoiding
|
|
266
|
+
non-positive-definite proposals in long float32 runs.
|
|
267
|
+
- A transient `squeue` failure no longer counts submitted jobs as finished.
|
|
268
|
+
- Trajectory completeness uses the configured `n_steps`, so production MDP
|
|
269
|
+
files with `nsteps <= 0` or `nstxout-compressed = 0` no longer mark every
|
|
270
|
+
sample as failed or crash.
|
|
271
|
+
- Element guessing keeps name-based elements for deuterium and
|
|
272
|
+
repartitioned hydrogens instead of failing.
|
|
273
|
+
- Molecule insertion stops with an error instead of looping forever when the
|
|
274
|
+
box is too small.
|
|
275
|
+
|
|
276
|
+
## `0.4.2` - 2026-10-02
|
|
277
|
+
|
|
278
|
+
### Changed
|
|
279
|
+
|
|
280
|
+
- Bounded the posterior sample counts used for default corner, standard
|
|
281
|
+
marginal, and QoI marginal plots. The standard marginal cap accepts `-1` or
|
|
282
|
+
`null` to use every sample. QoI likelihood attribution now runs in adaptive
|
|
283
|
+
batches to avoid CUDA memory exhaustion after learning.
|
|
284
|
+
- Centered default LGP hyperparameter priors on the observed input and residual
|
|
285
|
+
target scales, avoiding noise-dominated fits for scalar QoIs whose natural
|
|
286
|
+
parameter or output scales differ substantially from one.
|
|
287
|
+
- Reported the mode of each posterior marginal instead of its mean, limited
|
|
288
|
+
charge modes to three decimal places, and formatted other parameter modes
|
|
289
|
+
with three significant digits.
|
|
290
|
+
- Balanced marginal plots across rows of at most five parameters, placed each
|
|
291
|
+
arbitrary `define` parameter on an independent axis, and added configurable
|
|
292
|
+
axis labels through `plots.plot_metadata`. Marginal figures now reserve
|
|
293
|
+
measured space for legends so they cannot overlap single- or multi-panel
|
|
294
|
+
plots, align y-axis labels within subplot columns, and leave sufficient
|
|
295
|
+
gutters between neighboring panel sections.
|
|
296
|
+
- Made local validation progress visible immediately, including campaigns with
|
|
297
|
+
a single sample, and advanced the displayed count only after each MD job has
|
|
298
|
+
completed.
|
|
299
|
+
|
|
300
|
+
## `0.4.1` - 2026-08-25
|
|
301
|
+
|
|
302
|
+
### Changed
|
|
303
|
+
|
|
304
|
+
- Simplified RDF calculation so selection handling and atom-type expansion
|
|
305
|
+
occur in the QoI adapter while the numerical kernel operates directly on
|
|
306
|
+
MDAnalysis AtomGroups. Dynamic selections and numerical behavior are
|
|
307
|
+
preserved.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
cff-version: 1.2.0
|
|
2
2
|
message: "If you use BFF, please cite the repository and the associated paper."
|
|
3
3
|
title: "Bayesic Force Fields"
|
|
4
|
-
version: "0.
|
|
5
|
-
date-released: "2026-10-
|
|
4
|
+
version: "0.5.0"
|
|
5
|
+
date-released: "2026-10-09"
|
|
6
6
|
authors:
|
|
7
7
|
- family-names: Kostal
|
|
8
8
|
given-names: Vojtech
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Thank you for improving Bayesic Force Fields.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
mamba env create -f environment.yaml
|
|
7
|
+
mamba activate bfflearn
|
|
8
|
+
pip install torch # the build for your machine
|
|
9
|
+
make check # compileall, ruff, pytest, mkdocs build --strict
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Keep pull requests focused, describe the behavior change, and add a
|
|
13
|
+
regression test for every bug fix. The
|
|
14
|
+
[development guide](https://vojtechkostal.github.io/BayesicForceFields/development/)
|
|
15
|
+
covers the code layout, design rules, and releases.
|
bfflearn-0.5.0/PKG-INFO
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: bfflearn
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Bayesian workflows for fixed-charge molecular force fields
|
|
5
|
+
Author-email: Vojtech Kostal <vojtakostal8@gmail.com>
|
|
6
|
+
License-Expression: GPL-3.0-only
|
|
7
|
+
Project-URL: Documentation, https://vojtechkostal.github.io/BayesicForceFields/
|
|
8
|
+
Project-URL: Homepage, https://github.com/vojtechkostal/BayesicForceFields
|
|
9
|
+
Project-URL: Issues, https://github.com/vojtechkostal/BayesicForceFields/issues
|
|
10
|
+
Project-URL: Publication, https://pubs.acs.org/doi/10.1021/acs.jctc.5c02051
|
|
11
|
+
Project-URL: Preprint, https://arxiv.org/abs/2511.05398
|
|
12
|
+
Project-URL: Releases, https://github.com/vojtechkostal/BayesicForceFields/releases
|
|
13
|
+
Project-URL: Repository, https://github.com/vojtechkostal/BayesicForceFields
|
|
14
|
+
Keywords: bayesian-inference,force-fields,gromacs,molecular-dynamics,physical-chemistry
|
|
15
|
+
Classifier: Development Status :: 3 - Alpha
|
|
16
|
+
Classifier: Intended Audience :: Science/Research
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: Chemistry
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: gmxtopology==0.3.0
|
|
28
|
+
Requires-Dist: matplotlib>=3.8
|
|
29
|
+
Requires-Dist: MDAnalysis>=2.7
|
|
30
|
+
Requires-Dist: numpy>=1.26
|
|
31
|
+
Requires-Dist: PyYAML>=6.0
|
|
32
|
+
Requires-Dist: scipy>=1.11
|
|
33
|
+
Requires-Dist: typer>=0.12
|
|
34
|
+
Provides-Extra: notebook
|
|
35
|
+
Requires-Dist: ipykernel; extra == "notebook"
|
|
36
|
+
Requires-Dist: ipython; extra == "notebook"
|
|
37
|
+
Requires-Dist: ipywidgets; extra == "notebook"
|
|
38
|
+
Requires-Dist: jupyterlab; extra == "notebook"
|
|
39
|
+
Requires-Dist: notebook; extra == "notebook"
|
|
40
|
+
Provides-Extra: dev
|
|
41
|
+
Requires-Dist: build; extra == "dev"
|
|
42
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
43
|
+
Requires-Dist: ruff; extra == "dev"
|
|
44
|
+
Requires-Dist: twine; extra == "dev"
|
|
45
|
+
Provides-Extra: docs
|
|
46
|
+
Requires-Dist: mkdocs>=1.6; extra == "docs"
|
|
47
|
+
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
|
|
48
|
+
Requires-Dist: pymdown-extensions; extra == "docs"
|
|
49
|
+
Dynamic: license-file
|
|
50
|
+
|
|
51
|
+
# Bayesic Force Fields
|
|
52
|
+
|
|
53
|
+
<p align="center">
|
|
54
|
+
<img src="https://raw.githubusercontent.com/vojtechkostal/BayesicForceFields/main/docs/assets/bff-logo.svg" alt="BFF logo" width="260">
|
|
55
|
+
</p>
|
|
56
|
+
|
|
57
|
+
[](https://vojtechkostal.github.io/BayesicForceFields/)
|
|
58
|
+
[](https://pubs.acs.org/doi/10.1021/acs.jctc.5c02051)
|
|
59
|
+
[](https://github.com/vojtechkostal/BayesicForceFields/releases)
|
|
60
|
+
[](https://github.com/vojtechkostal/BayesicForceFields/blob/main/LICENSE)
|
|
61
|
+
|
|
62
|
+
Bayesic Force Fields (BFF) learns fixed-charge force-field parameters for
|
|
63
|
+
GROMACS by Bayesian inference. It runs classical MD for many sampled
|
|
64
|
+
parameter sets, compares quantities of interest (QoIs) such as RDFs or free
|
|
65
|
+
energy profiles with a reference simulation, fits Gaussian-process surrogates
|
|
66
|
+
to them, and samples the posterior distribution of the parameters.
|
|
67
|
+
|
|
68
|
+
## Workflow
|
|
69
|
+
|
|
70
|
+
Each step is one command with one YAML config:
|
|
71
|
+
|
|
72
|
+
```text
|
|
73
|
+
bff build build and equilibrate the GROMACS systems
|
|
74
|
+
│
|
|
75
|
+
▼
|
|
76
|
+
reference MD outside BFF: AIMD or an MLIP (see below)
|
|
77
|
+
│
|
|
78
|
+
▼
|
|
79
|
+
bff sample-parameters draw parameter sets, run classical MD for each
|
|
80
|
+
│
|
|
81
|
+
▼
|
|
82
|
+
bff build-qoi-datasets compute the QoIs of every sample and of the reference
|
|
83
|
+
│
|
|
84
|
+
▼
|
|
85
|
+
bff fit-lgp fit a Gaussian-process surrogate per QoI
|
|
86
|
+
│
|
|
87
|
+
▼
|
|
88
|
+
bff learn sample the posterior of the parameters (MCMC)
|
|
89
|
+
│
|
|
90
|
+
▼
|
|
91
|
+
bff validate rerun MD with posterior parameters
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
**BFF does not generate the reference data.** You run the reference simulation
|
|
95
|
+
yourself; we recommend ab initio MD or a machine-learned interatomic potential
|
|
96
|
+
(MLIP), ideally a foundation model fine-tuned for your system. For fine-tuning,
|
|
97
|
+
the repository provides
|
|
98
|
+
[`scripts/label_structures.py`](https://github.com/vojtechkostal/BayesicForceFields/blob/main/scripts/label_structures.py), which labels MD
|
|
99
|
+
frames with CP2K on Slurm. It is not installed by `pip`; download it from the
|
|
100
|
+
repository. See
|
|
101
|
+
[Reference data](https://vojtechkostal.github.io/BayesicForceFields/reference-trajectories/).
|
|
102
|
+
|
|
103
|
+
## Install
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
mamba create -n bfflearn python=3.10 pip
|
|
107
|
+
mamba activate bfflearn
|
|
108
|
+
pip install torch # pick the build for your CPU/GPU: https://pytorch.org/get-started/locally/
|
|
109
|
+
pip install bfflearn
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The MD stages need GROMACS (with Colvars or PLUMED for biased systems).
|
|
113
|
+
Notebook examples need `pip install "bfflearn[notebook]"`.
|
|
114
|
+
|
|
115
|
+
## Quick start
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
bff examples # copy the examples matching your BFF version
|
|
119
|
+
cd examples/acetate # full workflow: aqueous acetate and calcium acetate
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Every stage of the example is a directory with its config; run `bff <stage>
|
|
123
|
+
config.yaml` inside it. The
|
|
124
|
+
[acetate walkthrough](https://vojtechkostal.github.io/BayesicForceFields/examples/acetate/)
|
|
125
|
+
explains each step.
|
|
126
|
+
|
|
127
|
+
## Learned parameters
|
|
128
|
+
|
|
129
|
+
| Parameter | Label in `bounds` |
|
|
130
|
+
| --- | --- |
|
|
131
|
+
| Partial charge | `charge O1 O2` |
|
|
132
|
+
| Lennard-Jones sigma | `sigma OW` |
|
|
133
|
+
| Lennard-Jones epsilon | `epsilon OW` |
|
|
134
|
+
| Function-9 dihedral force constant | `dihedraltype9_3_180` |
|
|
135
|
+
|
|
136
|
+
Names in one label share one value. Charges can be tied by residue- or
|
|
137
|
+
system-level charge constraints.
|
|
138
|
+
|
|
139
|
+
## Repository
|
|
140
|
+
|
|
141
|
+
```text
|
|
142
|
+
BayesicForceFields/
|
|
143
|
+
├── bff/ the Python package and the `bff` command
|
|
144
|
+
│ ├── workflows/ one package per stage
|
|
145
|
+
│ ├── qoi/ QoI routines (rdf, hydrogen_bonds, custom) and datasets
|
|
146
|
+
│ ├── bayes/, mcmc/ surrogates, likelihoods, posterior sampling
|
|
147
|
+
│ └── domain/, io/ data models and file formats
|
|
148
|
+
├── examples/
|
|
149
|
+
│ ├── acetate/ full MD workflow with an RDF and a PMF
|
|
150
|
+
│ ├── arbitrary-data/ notebook: learn from your own tabular data
|
|
151
|
+
│ └── neon-mie-lgpmd/ notebook: learn from published RDFs
|
|
152
|
+
├── scripts/
|
|
153
|
+
│ └── label_structures.py CP2K labeling for MLIP fine-tuning (not installed by pip)
|
|
154
|
+
├── docs/ documentation site
|
|
155
|
+
└── tests/
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Documentation
|
|
159
|
+
|
|
160
|
+
[vojtechkostal.github.io/BayesicForceFields](https://vojtechkostal.github.io/BayesicForceFields/):
|
|
161
|
+
[how BFF works](https://vojtechkostal.github.io/BayesicForceFields/workflow/),
|
|
162
|
+
[all settings](https://vojtechkostal.github.io/BayesicForceFields/configuration/),
|
|
163
|
+
[examples](https://vojtechkostal.github.io/BayesicForceFields/examples/), and
|
|
164
|
+
[development](https://vojtechkostal.github.io/BayesicForceFields/development/).
|
|
165
|
+
See also the [changelog](https://github.com/vojtechkostal/BayesicForceFields/blob/main/CHANGELOG.md), [contributing](https://github.com/vojtechkostal/BayesicForceFields/blob/main/CONTRIBUTING.md),
|
|
166
|
+
[support](https://github.com/vojtechkostal/BayesicForceFields/blob/main/SUPPORT.md), and [security](https://github.com/vojtechkostal/BayesicForceFields/blob/main/SECURITY.md).
|
|
167
|
+
|
|
168
|
+
## Citation
|
|
169
|
+
|
|
170
|
+
> Kostal, V.; Shanks, B. L.; Jungwirth, P.; Martinez-Seara, H.
|
|
171
|
+
> Bayesian Learning for Accurate and Robust Biomolecular Force Fields.
|
|
172
|
+
> *J. Chem. Theory Comput.* **2026**, *22* (5), 2652-2663.
|
|
173
|
+
> [doi:10.1021/acs.jctc.5c02051](https://doi.org/10.1021/acs.jctc.5c02051)
|
|
174
|
+
|
|
175
|
+
The code used for the paper is archived as
|
|
176
|
+
[`v0.0.1`](https://github.com/vojtechkostal/BayesicForceFields/tree/v0.0.1).
|
|
177
|
+
|
|
178
|
+
## License
|
|
179
|
+
|
|
180
|
+
[GNU GPL v3](https://github.com/vojtechkostal/BayesicForceFields/blob/main/LICENSE)
|