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.
Files changed (208) hide show
  1. bfflearn-0.5.0/AGENTS.md +105 -0
  2. bfflearn-0.5.0/CHANGELOG.md +307 -0
  3. {bfflearn-0.4.2 → bfflearn-0.5.0}/CITATION.cff +2 -2
  4. bfflearn-0.5.0/CONTRIBUTING.md +15 -0
  5. {bfflearn-0.4.2 → bfflearn-0.5.0}/MANIFEST.in +1 -1
  6. bfflearn-0.5.0/PKG-INFO +180 -0
  7. bfflearn-0.5.0/README.md +130 -0
  8. {bfflearn-0.4.2 → bfflearn-0.5.0}/SUPPORT.md +3 -2
  9. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/__init__.py +19 -16
  10. bfflearn-0.5.0/bff/bayes/effective_observations.py +78 -0
  11. bfflearn-0.5.0/bff/bayes/fit.py +452 -0
  12. bfflearn-0.5.0/bff/bayes/gaussian_process.py +302 -0
  13. bfflearn-0.5.0/bff/bayes/kernels.py +35 -0
  14. bfflearn-0.5.0/bff/bayes/learning.py +385 -0
  15. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/bayes/likelihoods.py +30 -51
  16. bfflearn-0.5.0/bff/bayes/means.py +131 -0
  17. bfflearn-0.5.0/bff/bayes/posterior.py +27 -0
  18. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/bayes/priors.py +61 -83
  19. bfflearn-0.5.0/bff/bayes/results.py +392 -0
  20. bfflearn-0.5.0/bff/bayes/utils.py +82 -0
  21. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/cli.py +10 -30
  22. bfflearn-0.5.0/bff/domain/__init__.py +19 -0
  23. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/domain/bias.py +0 -68
  24. bfflearn-0.5.0/bff/domain/charge_constraints.py +193 -0
  25. bfflearn-0.5.0/bff/domain/samples.py +189 -0
  26. bfflearn-0.5.0/bff/domain/specs.py +353 -0
  27. bfflearn-0.5.0/bff/domain/systems.py +98 -0
  28. bfflearn-0.5.0/bff/gromacs.py +107 -0
  29. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/__init__.py +0 -3
  30. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/colvars.py +0 -8
  31. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/logs.py +1 -16
  32. bfflearn-0.5.0/bff/io/mdp.py +42 -0
  33. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/progress.py +23 -14
  34. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/utils.py +6 -30
  35. bfflearn-0.5.0/bff/mcmc/convergence.py +135 -0
  36. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/mcmc/proposal.py +14 -9
  37. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/mcmc/sampler.py +99 -140
  38. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/plotting.py +236 -454
  39. bfflearn-0.5.0/bff/qoi/__init__.py +11 -0
  40. bfflearn-0.5.0/bff/qoi/analysis.py +164 -0
  41. bfflearn-0.4.2/bff/qoi/data.py → bfflearn-0.5.0/bff/qoi/dataset.py +70 -36
  42. bfflearn-0.5.0/bff/qoi/hbonds.py +235 -0
  43. bfflearn-0.5.0/bff/qoi/rdf.py +134 -0
  44. bfflearn-0.5.0/bff/qoi/routines.py +140 -0
  45. bfflearn-0.5.0/bff/qoi/trajectory.py +132 -0
  46. bfflearn-0.5.0/bff/slurm.py +208 -0
  47. bfflearn-0.5.0/bff/topology.py +205 -0
  48. bfflearn-0.5.0/bff/workflows/build/box.py +287 -0
  49. bfflearn-0.5.0/bff/workflows/build/config.py +143 -0
  50. bfflearn-0.5.0/bff/workflows/build/main.py +290 -0
  51. bfflearn-0.5.0/bff/workflows/build_qoi_datasets/config.py +278 -0
  52. bfflearn-0.5.0/bff/workflows/build_qoi_datasets/main.py +239 -0
  53. bfflearn-0.5.0/bff/workflows/campaign/config.py +253 -0
  54. bfflearn-0.5.0/bff/workflows/campaign/job.py +302 -0
  55. bfflearn-0.5.0/bff/workflows/campaign/run.py +491 -0
  56. bfflearn-0.5.0/bff/workflows/config.py +326 -0
  57. bfflearn-0.5.0/bff/workflows/fit_lgp/config.py +110 -0
  58. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/fit_lgp/main.py +15 -11
  59. bfflearn-0.5.0/bff/workflows/learn/config.py +198 -0
  60. bfflearn-0.5.0/bff/workflows/learn/main.py +203 -0
  61. bfflearn-0.5.0/bff/workflows/sample_parameters/config.py +101 -0
  62. bfflearn-0.5.0/bff/workflows/sample_parameters/main.py +39 -0
  63. bfflearn-0.5.0/bff/workflows/validate/config.py +96 -0
  64. bfflearn-0.5.0/bff/workflows/validate/main.py +101 -0
  65. bfflearn-0.5.0/bfflearn.egg-info/PKG-INFO +180 -0
  66. {bfflearn-0.4.2 → bfflearn-0.5.0}/bfflearn.egg-info/SOURCES.txt +19 -51
  67. {bfflearn-0.4.2 → bfflearn-0.5.0}/bfflearn.egg-info/requires.txt +1 -1
  68. bfflearn-0.5.0/docs/changelog.md +414 -0
  69. bfflearn-0.5.0/docs/cli.md +36 -0
  70. bfflearn-0.5.0/docs/configuration/build-qoi-datasets.md +257 -0
  71. bfflearn-0.5.0/docs/configuration/build.md +92 -0
  72. bfflearn-0.5.0/docs/configuration/fit-lgp.md +112 -0
  73. bfflearn-0.5.0/docs/configuration/index.md +89 -0
  74. bfflearn-0.5.0/docs/configuration/learn.md +169 -0
  75. bfflearn-0.5.0/docs/configuration/sample-parameters.md +285 -0
  76. bfflearn-0.5.0/docs/configuration/snippets/campaign-options.md +59 -0
  77. bfflearn-0.5.0/docs/configuration/validate.md +139 -0
  78. bfflearn-0.5.0/docs/development.md +87 -0
  79. bfflearn-0.5.0/docs/examples/acetate.md +107 -0
  80. {bfflearn-0.4.2 → bfflearn-0.5.0}/docs/examples/arbitrary-data.md +10 -10
  81. bfflearn-0.5.0/docs/examples/index.md +12 -0
  82. {bfflearn-0.4.2 → bfflearn-0.5.0}/docs/examples/neon-mie-lgpmd.md +13 -15
  83. bfflearn-0.5.0/docs/index.md +82 -0
  84. {bfflearn-0.4.2 → bfflearn-0.5.0}/docs/installation.md +0 -1
  85. bfflearn-0.5.0/docs/migration.md +174 -0
  86. bfflearn-0.5.0/docs/reference-trajectories.md +83 -0
  87. bfflearn-0.5.0/docs/results.md +92 -0
  88. bfflearn-0.5.0/docs/workflow.md +63 -0
  89. {bfflearn-0.4.2 → bfflearn-0.5.0}/mkdocs.yml +15 -8
  90. {bfflearn-0.4.2 → bfflearn-0.5.0}/pyproject.toml +3 -2
  91. bfflearn-0.4.2/AGENTS.md +0 -127
  92. bfflearn-0.4.2/CHANGELOG.md +0 -32
  93. bfflearn-0.4.2/CONTRIBUTING.md +0 -32
  94. bfflearn-0.4.2/PKG-INFO +0 -195
  95. bfflearn-0.4.2/README.md +0 -145
  96. bfflearn-0.4.2/bff/bayes/effective_observations.py +0 -31
  97. bfflearn-0.4.2/bff/bayes/gaussian_process.py +0 -327
  98. bfflearn-0.4.2/bff/bayes/kernels.py +0 -71
  99. bfflearn-0.4.2/bff/bayes/learning.py +0 -603
  100. bfflearn-0.4.2/bff/bayes/means.py +0 -21
  101. bfflearn-0.4.2/bff/bayes/posterior.py +0 -62
  102. bfflearn-0.4.2/bff/bayes/results.py +0 -538
  103. bfflearn-0.4.2/bff/bayes/utils.py +0 -371
  104. bfflearn-0.4.2/bff/domain/__init__.py +0 -18
  105. bfflearn-0.4.2/bff/domain/campaign.py +0 -91
  106. bfflearn-0.4.2/bff/domain/sample.py +0 -330
  107. bfflearn-0.4.2/bff/domain/specs.py +0 -520
  108. bfflearn-0.4.2/bff/domain/systems.py +0 -259
  109. bfflearn-0.4.2/bff/io/cp2k.py +0 -190
  110. bfflearn-0.4.2/bff/io/extxyz.py +0 -236
  111. bfflearn-0.4.2/bff/io/mdp.py +0 -98
  112. bfflearn-0.4.2/bff/io/schedulers.py +0 -118
  113. bfflearn-0.4.2/bff/mcmc/convergence.py +0 -168
  114. bfflearn-0.4.2/bff/qoi/__init__.py +0 -9
  115. bfflearn-0.4.2/bff/qoi/analysis.py +0 -219
  116. bfflearn-0.4.2/bff/qoi/hbonds.py +0 -255
  117. bfflearn-0.4.2/bff/qoi/rdf.py +0 -236
  118. bfflearn-0.4.2/bff/qoi/routines.py +0 -297
  119. bfflearn-0.4.2/bff/tools.py +0 -152
  120. bfflearn-0.4.2/bff/topology.py +0 -516
  121. bfflearn-0.4.2/bff/workflows/_shared/campaign.py +0 -714
  122. bfflearn-0.4.2/bff/workflows/_shared/config.py +0 -354
  123. bfflearn-0.4.2/bff/workflows/_shared/preparation.py +0 -315
  124. bfflearn-0.4.2/bff/workflows/_shared/scheduler.py +0 -143
  125. bfflearn-0.4.2/bff/workflows/build/config.py +0 -268
  126. bfflearn-0.4.2/bff/workflows/build/main.py +0 -285
  127. bfflearn-0.4.2/bff/workflows/build_qoi_datasets/config.py +0 -329
  128. bfflearn-0.4.2/bff/workflows/build_qoi_datasets/main.py +0 -220
  129. bfflearn-0.4.2/bff/workflows/fit_lgp/config.py +0 -161
  130. bfflearn-0.4.2/bff/workflows/label_snapshots/__init__.py +0 -1
  131. bfflearn-0.4.2/bff/workflows/label_snapshots/config.py +0 -252
  132. bfflearn-0.4.2/bff/workflows/label_snapshots/main.py +0 -845
  133. bfflearn-0.4.2/bff/workflows/learn/config.py +0 -325
  134. bfflearn-0.4.2/bff/workflows/learn/main.py +0 -280
  135. bfflearn-0.4.2/bff/workflows/md/__init__.py +0 -1
  136. bfflearn-0.4.2/bff/workflows/md/config.py +0 -107
  137. bfflearn-0.4.2/bff/workflows/md/main.py +0 -379
  138. bfflearn-0.4.2/bff/workflows/sample_parameters/config.py +0 -136
  139. bfflearn-0.4.2/bff/workflows/sample_parameters/main.py +0 -28
  140. bfflearn-0.4.2/bff/workflows/validate/config.py +0 -159
  141. bfflearn-0.4.2/bff/workflows/validate/main.py +0 -53
  142. bfflearn-0.4.2/bfflearn.egg-info/PKG-INFO +0 -195
  143. bfflearn-0.4.2/docs/architecture.md +0 -123
  144. bfflearn-0.4.2/docs/changelog.md +0 -139
  145. bfflearn-0.4.2/docs/cli.md +0 -70
  146. bfflearn-0.4.2/docs/configuration/build-qoi-datasets.md +0 -135
  147. bfflearn-0.4.2/docs/configuration/build.md +0 -111
  148. bfflearn-0.4.2/docs/configuration/fit-lgp.md +0 -35
  149. bfflearn-0.4.2/docs/configuration/label-snapshots.md +0 -60
  150. bfflearn-0.4.2/docs/configuration/learn.md +0 -87
  151. bfflearn-0.4.2/docs/configuration/sample-parameters.md +0 -190
  152. bfflearn-0.4.2/docs/configuration/validate.md +0 -129
  153. bfflearn-0.4.2/docs/development.md +0 -128
  154. bfflearn-0.4.2/docs/examples/acetate.md +0 -60
  155. bfflearn-0.4.2/docs/examples/index.md +0 -15
  156. bfflearn-0.4.2/docs/index.md +0 -91
  157. bfflearn-0.4.2/docs/migration.md +0 -70
  158. bfflearn-0.4.2/tests/bayes/test_effective_observations.py +0 -28
  159. bfflearn-0.4.2/tests/bayes/test_gaussian_process.py +0 -161
  160. bfflearn-0.4.2/tests/bayes/test_learning_problem.py +0 -177
  161. bfflearn-0.4.2/tests/bayes/test_likelihoods.py +0 -149
  162. bfflearn-0.4.2/tests/bayes/test_priors_posterior.py +0 -85
  163. bfflearn-0.4.2/tests/bayes/test_results.py +0 -388
  164. bfflearn-0.4.2/tests/bayes/test_utils.py +0 -29
  165. bfflearn-0.4.2/tests/domain/test_specs.py +0 -191
  166. bfflearn-0.4.2/tests/io/_fake_mdanalysis.py +0 -49
  167. bfflearn-0.4.2/tests/io/test_cp2k.py +0 -56
  168. bfflearn-0.4.2/tests/io/test_cp2k_collect.py +0 -45
  169. bfflearn-0.4.2/tests/io/test_logs.py +0 -148
  170. bfflearn-0.4.2/tests/io/test_mdp.py +0 -64
  171. bfflearn-0.4.2/tests/mcmc/test_convergence.py +0 -61
  172. bfflearn-0.4.2/tests/mcmc/test_proposal.py +0 -77
  173. bfflearn-0.4.2/tests/mcmc/test_sampler.py +0 -119
  174. bfflearn-0.4.2/tests/qoi/test_analysis.py +0 -338
  175. bfflearn-0.4.2/tests/qoi/test_data.py +0 -104
  176. bfflearn-0.4.2/tests/qoi/test_rdf.py +0 -184
  177. bfflearn-0.4.2/tests/test_examples.py +0 -326
  178. bfflearn-0.4.2/tests/test_plotting.py +0 -392
  179. bfflearn-0.4.2/tests/test_release_metadata.py +0 -27
  180. bfflearn-0.4.2/tests/test_topology.py +0 -102
  181. bfflearn-0.4.2/tests/workflows/test_charge_constraints.py +0 -168
  182. bfflearn-0.4.2/tests/workflows/test_configs.py +0 -876
  183. bfflearn-0.4.2/tests/workflows/test_pipeline_manifests.py +0 -1459
  184. bfflearn-0.4.2/tests/workflows/test_preparation.py +0 -94
  185. bfflearn-0.4.2/tests/workflows/test_regressions.py +0 -281
  186. bfflearn-0.4.2/tests/workflows/test_scheduler.py +0 -120
  187. bfflearn-0.4.2/tests/workflows/test_validate.py +0 -122
  188. {bfflearn-0.4.2 → bfflearn-0.5.0}/LICENSE +0 -0
  189. {bfflearn-0.4.2 → bfflearn-0.5.0}/SECURITY.md +0 -0
  190. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/bayes/__init__.py +0 -0
  191. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/commands.py +0 -0
  192. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/io/plumed.py +0 -0
  193. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/mcmc/__init__.py +0 -0
  194. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/__init__.py +0 -0
  195. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/build/__init__.py +0 -0
  196. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/build_qoi_datasets/__init__.py +0 -0
  197. {bfflearn-0.4.2/bff/workflows/_shared → bfflearn-0.5.0/bff/workflows/campaign}/__init__.py +0 -0
  198. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/examples.py +0 -0
  199. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/fit_lgp/__init__.py +0 -0
  200. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/learn/__init__.py +0 -0
  201. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/sample_parameters/__init__.py +0 -0
  202. {bfflearn-0.4.2 → bfflearn-0.5.0}/bff/workflows/validate/__init__.py +0 -0
  203. {bfflearn-0.4.2 → bfflearn-0.5.0}/bfflearn.egg-info/dependency_links.txt +0 -0
  204. {bfflearn-0.4.2 → bfflearn-0.5.0}/bfflearn.egg-info/entry_points.txt +0 -0
  205. {bfflearn-0.4.2 → bfflearn-0.5.0}/bfflearn.egg-info/top_level.txt +0 -0
  206. {bfflearn-0.4.2 → bfflearn-0.5.0}/docs/assets/bff-logo.pdf +0 -0
  207. {bfflearn-0.4.2 → bfflearn-0.5.0}/docs/assets/bff-logo.svg +0 -0
  208. {bfflearn-0.4.2 → bfflearn-0.5.0}/setup.cfg +0 -0
@@ -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.4.2"
5
- date-released: "2026-10-02"
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.
@@ -6,4 +6,4 @@ include SECURITY.md
6
6
  include SUPPORT.md
7
7
  include mkdocs.yml
8
8
  recursive-include docs *.md *.pdf *.svg
9
- recursive-include tests *.py
9
+ prune tests
@@ -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
+ [![Docs](https://img.shields.io/badge/docs-latest-brightgreen)](https://vojtechkostal.github.io/BayesicForceFields/)
58
+ [![Paper](https://img.shields.io/badge/paper-JCTC%202026-blue)](https://pubs.acs.org/doi/10.1021/acs.jctc.5c02051)
59
+ [![Release](https://img.shields.io/github/v/tag/vojtechkostal/BayesicForceFields?label=release)](https://github.com/vojtechkostal/BayesicForceFields/releases)
60
+ [![License](https://img.shields.io/badge/license-GPLv3-blue.svg)](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)