aimnet 0.2.0__tar.gz → 0.2.6__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 (78) hide show
  1. {aimnet-0.2.0 → aimnet-0.2.6}/.gitignore +7 -0
  2. aimnet-0.2.6/PKG-INFO +300 -0
  3. aimnet-0.2.6/README.md +228 -0
  4. aimnet-0.2.6/aimnet/calculators/_graph_options.py +114 -0
  5. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/calculators/aimnet2ase.py +5 -4
  6. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/calculators/aimnet2pysis.py +2 -2
  7. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/calculators/aimnet2torchsim.py +1 -1
  8. aimnet-0.2.6/aimnet/calculators/calculator.py +2416 -0
  9. aimnet-0.2.6/aimnet/calculators/cuda_graph/__init__.py +17 -0
  10. aimnet-0.2.6/aimnet/calculators/cuda_graph/_capture.py +47 -0
  11. aimnet-0.2.6/aimnet/calculators/cuda_graph/cache.py +866 -0
  12. aimnet-0.2.6/aimnet/calculators/cuda_graph/contracts.py +278 -0
  13. aimnet-0.2.6/aimnet/calculators/cuda_graph/dense.py +125 -0
  14. aimnet-0.2.6/aimnet/calculators/cuda_graph/sparse.py +201 -0
  15. aimnet-0.2.6/aimnet/calculators/derivatives.py +230 -0
  16. aimnet-0.2.6/aimnet/calculators/hf_hub.py +443 -0
  17. aimnet-0.2.6/aimnet/calculators/model_registry.py +285 -0
  18. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/calculators/model_registry.yaml +75 -3
  19. aimnet-0.2.6/aimnet/calculators/neighbor_buffers.py +79 -0
  20. aimnet-0.2.6/aimnet/calculators/neighbors.py +428 -0
  21. aimnet-0.2.6/aimnet/calculators/resolve.py +186 -0
  22. aimnet-0.2.6/aimnet/calculators/vibrations.py +277 -0
  23. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/cli.py +44 -7
  24. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/config.py +87 -31
  25. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/constants.py +0 -17
  26. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/data/sgdataset.py +52 -6
  27. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/kernels/__init__.py +19 -7
  28. aimnet-0.2.6/aimnet/kernels/aev_sv_dense_triton.py +223 -0
  29. aimnet-0.2.6/aimnet/kernels/conv_finish_triton.py +274 -0
  30. aimnet-0.2.6/aimnet/kernels/conv_sv_2d_sp_wp.py +1054 -0
  31. aimnet-0.2.6/aimnet/kernels/coulomb_wp.py +221 -0
  32. aimnet-0.2.6/aimnet/kernels/geometry_baddbmm_triton.py +120 -0
  33. aimnet-0.2.6/aimnet/kernels/triton_support.py +50 -0
  34. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/models/__init__.py +6 -2
  35. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/models/aimnet2.py +99 -15
  36. aimnet-0.2.6/aimnet/models/artifact_validation.py +559 -0
  37. aimnet-0.2.6/aimnet/models/base.py +308 -0
  38. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/models/utils.py +54 -19
  39. aimnet-0.2.6/aimnet/modules/aev.py +390 -0
  40. aimnet-0.2.6/aimnet/modules/aev_inference.py +240 -0
  41. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/modules/core.py +3 -14
  42. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/modules/lr.py +442 -365
  43. aimnet-0.2.6/aimnet/nbops.py +747 -0
  44. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/ops.py +21 -15
  45. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/train/default_train.yaml +15 -0
  46. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/train/export_model.py +89 -20
  47. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/train/loss.py +11 -10
  48. aimnet-0.2.6/aimnet/train/neighbor_lists.py +240 -0
  49. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/train/train.py +29 -5
  50. aimnet-0.2.6/aimnet/train/utils.py +861 -0
  51. aimnet-0.2.6/aimnet/validation/__init__.py +1 -0
  52. aimnet-0.2.6/aimnet/validation/compare_observables.py +152 -0
  53. aimnet-0.2.6/aimnet/validation/gpu_observables.py +128 -0
  54. {aimnet-0.2.0 → aimnet-0.2.6}/pyproject.toml +32 -14
  55. aimnet-0.2.0/PKG-INFO +0 -326
  56. aimnet-0.2.0/README.md +0 -258
  57. aimnet-0.2.0/aimnet/calculators/calculator.py +0 -1527
  58. aimnet-0.2.0/aimnet/calculators/hf_hub.py +0 -314
  59. aimnet-0.2.0/aimnet/calculators/model_registry.py +0 -137
  60. aimnet-0.2.0/aimnet/interfaces/__init__.py +0 -1
  61. aimnet-0.2.0/aimnet/kernels/conv_sv_2d_sp_wp.py +0 -606
  62. aimnet-0.2.0/aimnet/models/base.py +0 -239
  63. aimnet-0.2.0/aimnet/modules/aev.py +0 -206
  64. aimnet-0.2.0/aimnet/nbops.py +0 -258
  65. aimnet-0.2.0/aimnet/train/utils.py +0 -383
  66. {aimnet-0.2.0 → aimnet-0.2.6}/LICENSE +0 -0
  67. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/__init__.py +0 -0
  68. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/calculators/__init__.py +0 -0
  69. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/data/__init__.py +0 -0
  70. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/dftd3_data.pt +0 -0
  71. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/models/aimnet2.yaml +0 -0
  72. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/models/aimnet2_dftd3_wb97m.yaml +0 -0
  73. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/models/aimnet2_rxn.yaml +0 -0
  74. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/models/convert.py +0 -0
  75. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/modules/__init__.py +0 -0
  76. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/train/__init__.py +0 -0
  77. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/train/calc_sae.py +0 -0
  78. {aimnet-0.2.0 → aimnet-0.2.6}/aimnet/train/metrics.py +0 -0
@@ -187,3 +187,10 @@ PLANS.md
187
187
  # and can be added to the global gitignore or merged into this file. For a more nuclear
188
188
  # option (not recommended) you can uncomment the following to ignore the entire idea folder.
189
189
  .idea/
190
+
191
+ # AIMNet Hessian/optimization run artifacts
192
+ hess_calc_cyc_*.h5
193
+ final_geometry.xyz
194
+
195
+ # GPU validation tool output (transient)
196
+ gpu-validation-results/
aimnet-0.2.6/PKG-INFO ADDED
@@ -0,0 +1,300 @@
1
+ Metadata-Version: 2.5
2
+ Name: aimnet
3
+ Version: 0.2.6
4
+ Summary: AIMNet Machine Learned Interatomic Potential
5
+ Project-URL: Homepage, https://github.com/isayevlab/aimnetcentral
6
+ Project-URL: Documentation, https://isayevlab.github.io/aimnetcentral/
7
+ Project-URL: Repository, https://github.com/isayevlab/aimnetcentral
8
+ Author-email: Roman Zubatyuk <zubatyuk@gmail.com>
9
+ License: MIT License
10
+
11
+ Copyright (c) 2024, Roman Zubatyuk
12
+
13
+ Permission is hereby granted, free of charge, to any person obtaining a copy
14
+ of this software and associated documentation files (the "Software"), to deal
15
+ in the Software without restriction, including without limitation the rights
16
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
17
+ copies of the Software, and to permit persons to whom the Software is
18
+ furnished to do so, subject to the following conditions:
19
+
20
+ The above copyright notice and this permission notice shall be included in all
21
+ copies or substantial portions of the Software.
22
+
23
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
26
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
28
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29
+ SOFTWARE.
30
+ License-File: LICENSE
31
+ Keywords: computational chemistry,deep learning,interatomic potential,machine learning,molecular dynamics
32
+ Classifier: Intended Audience :: Science/Research
33
+ Classifier: License :: OSI Approved :: MIT License
34
+ Classifier: Operating System :: OS Independent
35
+ Classifier: Programming Language :: Python :: 3
36
+ Classifier: Programming Language :: Python :: 3.11
37
+ Classifier: Programming Language :: Python :: 3.12
38
+ Classifier: Programming Language :: Python :: 3.13
39
+ Classifier: Programming Language :: Python :: 3.14
40
+ Classifier: Topic :: Scientific/Engineering :: Chemistry
41
+ Classifier: Topic :: Scientific/Engineering :: Physics
42
+ Requires-Python: >=3.11
43
+ Requires-Dist: click>=8.1.7
44
+ Requires-Dist: h5py>=3.12.1
45
+ Requires-Dist: jinja2>=3.1.6
46
+ Requires-Dist: numpy
47
+ Requires-Dist: nvalchemi-toolkit-ops>=0.4.1
48
+ Requires-Dist: pyyaml>=6.0.2
49
+ Requires-Dist: requests>=2.32.3
50
+ Requires-Dist: torch>=2.10
51
+ Requires-Dist: warp-lang<2,>=1.13
52
+ Provides-Extra: ase
53
+ Requires-Dist: ase<4,>=3.27.0; extra == 'ase'
54
+ Provides-Extra: cuda-graph
55
+ Requires-Dist: triton>=3.0; (sys_platform == 'linux') and extra == 'cuda-graph'
56
+ Provides-Extra: hf
57
+ Requires-Dist: huggingface-hub>=0.20; extra == 'hf'
58
+ Requires-Dist: safetensors>=0.4; extra == 'hf'
59
+ Provides-Extra: pysis
60
+ Requires-Dist: pysisyphus>=1.0.0; extra == 'pysis'
61
+ Provides-Extra: sella
62
+ Requires-Dist: ase<4,>=3.27.0; extra == 'sella'
63
+ Requires-Dist: sella>=2.4.0; extra == 'sella'
64
+ Provides-Extra: torchsim
65
+ Requires-Dist: torch-sim-atomistic<0.7.0,>=0.6.0; (python_version >= '3.12') and extra == 'torchsim'
66
+ Provides-Extra: train
67
+ Requires-Dist: omegaconf>=2.3.0; extra == 'train'
68
+ Requires-Dist: pytorch-ignite>=0.5.1; extra == 'train'
69
+ Requires-Dist: tqdm>=4.66; extra == 'train'
70
+ Requires-Dist: wandb>=0.18.5; extra == 'train'
71
+ Description-Content-Type: text/markdown
72
+
73
+ [![PyPI](https://img.shields.io/pypi/v/aimnet)](https://pypi.org/project/aimnet/) [![Release](https://img.shields.io/github/v/release/isayevlab/aimnetcentral)](https://github.com/isayevlab/aimnetcentral/releases) [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/) [![Build status](https://img.shields.io/github/actions/workflow/status/isayevlab/aimnetcentral/main.yml?branch=main)](https://github.com/isayevlab/aimnetcentral/actions/workflows/main.yml?query=branch%3Amain) [![License](https://img.shields.io/github/license/isayevlab/aimnetcentral)](https://github.com/isayevlab/aimnetcentral/blob/main/LICENSE)
74
+
75
+ # AIMNet2
76
+
77
+ Fast neural-network interatomic potentials for organic, elemental-organic, open-shell, reactive, and palladium chemistry.
78
+
79
+ - **Documentation:** <https://isayevlab.github.io/aimnetcentral/>
80
+ - **Repository:** <https://github.com/isayevlab/aimnetcentral>
81
+ - **PyPI:** <https://pypi.org/project/aimnet/>
82
+ - **Demo:** <https://huggingface.co/spaces/isayevlab/aimnet2-demo>
83
+
84
+ ## What It Does
85
+
86
+ AIMNet2 predicts energies, forces, atomic charges, stress tensors, and Hessians for molecules and periodic systems. Pretrained models cover general organic chemistry, open-shell and reactive chemistry, and palladium catalysis.
87
+
88
+ - One calculator, `AIMNet2Calculator`, for single molecules, batches, and periodic cells
89
+ - ASE, PySisyphus, Sella, TorchSim, Hugging Face Hub, and command-line workflows
90
+ - Long-range Coulomb (DSF, Ewald, PME) and DFT-D3(BJ) dispersion on GPU
91
+ - Optional CUDA-graph replay and `torch.compile` for repeated evaluations
92
+ - Python 3.11 to 3.14 and PyTorch 2.10 or newer
93
+
94
+ ## Install
95
+
96
+ ```bash
97
+ pip install aimnet
98
+ ```
99
+
100
+ On Linux the default PyTorch wheel from PyPI includes CUDA. To pick a specific CUDA build, install PyTorch first, then AIMNet2:
101
+
102
+ ```bash
103
+ pip install torch --index-url https://download.pytorch.org/whl/cu126
104
+ pip install aimnet
105
+ ```
106
+
107
+ Optional integrations:
108
+
109
+ ```bash
110
+ pip install "aimnet[ase]" # ASE calculator
111
+ pip install "aimnet[pysis]" # PySisyphus reaction paths
112
+ pip install "aimnet[sella]" # Sella transition-state search, includes ASE
113
+ pip install "aimnet[hf]" # Hugging Face Hub model loading
114
+ pip install "aimnet[torchsim,ase]" # TorchSim, Python 3.12+
115
+ pip install "aimnet[train]" # training and export commands
116
+ ```
117
+
118
+ For offline or HPC clusters, see [Offline and HPC installation](https://isayevlab.github.io/aimnetcentral/offline_hpc/).
119
+
120
+ ## Quick Start
121
+
122
+ ```python
123
+ from aimnet.calculators import AIMNet2Calculator
124
+
125
+ calc = AIMNet2Calculator("aimnet2") # downloads the model on first use
126
+
127
+ water = {
128
+ "coord": [[0.000, 0.000, 0.119], [0.000, 0.763, -0.477], [0.000, -0.763, -0.477]],
129
+ "numbers": [8, 1, 1],
130
+ "charge": 0.0,
131
+ }
132
+ result = calc(water, forces=True)
133
+
134
+ print(result["energy"]) # eV
135
+ print(result["forces"]) # eV/Å
136
+ print(result["charges"]) # e
137
+ ```
138
+
139
+ ### ASE
140
+
141
+ ```python
142
+ from ase.io import read
143
+ from aimnet.calculators import AIMNet2ASE
144
+
145
+ atoms = read("molecule.xyz")
146
+ atoms.calc = AIMNet2ASE("aimnet2", charge=0)
147
+
148
+ energy = atoms.get_potential_energy()
149
+ forces = atoms.get_forces()
150
+ ```
151
+
152
+ ### TorchSim
153
+
154
+ ```python
155
+ import ase.io
156
+ import torch_sim as ts
157
+
158
+ from aimnet.calculators import AIMNet2Calculator, AIMNet2TorchSim
159
+
160
+ atoms = ase.io.read("molecule.xyz")
161
+ model = AIMNet2TorchSim(AIMNet2Calculator("aimnet2"))
162
+
163
+ results = ts.static(system=atoms, model=model)
164
+ print(results[0]["potential_energy"], results[0]["forces"])
165
+ ```
166
+
167
+ ### Periodic Systems
168
+
169
+ ```python
170
+ calc = AIMNet2Calculator("aimnet2")
171
+ calc.set_lrcoulomb_method("ewald", ewald_accuracy=1e-6)
172
+
173
+ result = calc(
174
+ {
175
+ "coord": coordinates, # (N, 3), Å
176
+ "numbers": atomic_numbers, # (N,)
177
+ "charge": 0.0,
178
+ "cell": cell_vectors, # (3, 3), Å; fully periodic
179
+ },
180
+ forces=True,
181
+ stress=True,
182
+ )
183
+ ```
184
+
185
+ See the [periodic systems tutorial](https://isayevlab.github.io/aimnetcentral/tutorials/periodic_systems/) and [long-range methods](https://isayevlab.github.io/aimnetcentral/long_range/) for choosing a Coulomb method.
186
+
187
+ ### Performance
188
+
189
+ `compile_model=False` and `cuda_graph=False` are the defaults. For many repeated evaluations of the same system size on a GPU, such as MD or geometry optimization, `cuda_graph=True` replays captured CUDA graphs and is often several times faster for small and medium molecules. See [CUDA-graph inference](https://isayevlab.github.io/aimnetcentral/cuda_graph/) for supported models and memory costs, and [performance tuning](https://isayevlab.github.io/aimnetcentral/tutorials/performance/) for batching and `torch.compile`.
190
+
191
+ ## Model Families
192
+
193
+ | Model | Elements | Best for |
194
+ | --- | --- | --- |
195
+ | `aimnet2` | H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I | General organic and elemental-organic chemistry, wB97M-D3 |
196
+ | `aimnet2-2025` | H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I | B97-3c with improved intermolecular interactions |
197
+ | `aimnet2-b973c` | H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I | Legacy B97-3c reproducibility |
198
+ | `aimnet2-nse` | H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I | Open-shell systems and radicals |
199
+ | `aimnet2-pd` | H, B, C, N, O, F, Si, P, S, Cl, Se, Br, Pd, I | Pd catalysis with B97-3c/CPCM(THF) reference data |
200
+ | `aimnet2-rxn` | H, C, N, O | Reactive chemistry, transition states, NEB, IRC; net-neutral systems only |
201
+
202
+ Each family has four ensemble members, `0` to `3`; short aliases load member `0`. Previously published names such as `aimnet2_2025`, `aimnet2nse`, and `aimnet2pd` still resolve.
203
+
204
+ The [model selection guide](https://isayevlab.github.io/aimnetcentral/models/guide/) covers known limitations, aliases, citations, and download links.
205
+
206
+ ## Hugging Face Models
207
+
208
+ With the `hf` extra installed, pass a repository ID directly:
209
+
210
+ ```python
211
+ from aimnet.calculators import AIMNet2Calculator
212
+
213
+ calc = AIMNet2Calculator("isayevlab/aimnet2-wb97m-d3")
214
+ calc = AIMNet2Calculator("isayevlab/aimnet2-wb97m-d3", ensemble_member=2)
215
+ calc = AIMNet2Calculator("isayevlab/aimnet2-wb97m-d3", revision="v1.0")
216
+ ```
217
+
218
+ | HF repo | Alias | Use |
219
+ | --- | --- | --- |
220
+ | `isayevlab/aimnet2-wb97m-d3` | `aimnet2` | General organic chemistry |
221
+ | `isayevlab/aimnet2-2025` | `aimnet2-2025` | Improved intermolecular interactions |
222
+ | `isayevlab/aimnet2-nse` | `aimnet2-nse` | Open-shell chemistry |
223
+ | `isayevlab/aimnet2-pd` | `aimnet2-pd` | Palladium chemistry |
224
+ | `isayevlab/aimnet2-rxn` | `aimnet2-rxn` | Reactive paths and transition states |
225
+
226
+ Private repositories load with `token=` or the `HF_TOKEN` environment variable. Local directories with `config.json` and `ensemble_N.safetensors` also work.
227
+
228
+ ## Outputs
229
+
230
+ | Key | Shape | Units |
231
+ | --------- | ----------------------------------- | ------ |
232
+ | `energy` | `(B,)` | eV |
233
+ | `forces` | `(N, 3)` or `(B, N, 3)` | eV/Å |
234
+ | `charges` | `(N,)` or `(B, N)` | e |
235
+ | `stress` | `(3, 3)` or `(B, 3, 3)` | eV/Å^3 |
236
+ | `hessian` | `(N, 3, N, 3)` or `(B, N, 3, N, 3)` | eV/Å^2 |
237
+
238
+ `B` is the number of systems (1 for a single molecule) and `N` the number of atoms. Stress uses the ASE sign convention. Batched Hessians are evaluated per system and returned as a list when the systems differ in size. The [calculator reference](https://isayevlab.github.io/aimnetcentral/calculator/) documents input layouts, batching, and the derivative support of each long-range method.
239
+
240
+ ## Training
241
+
242
+ ```bash
243
+ pip install "aimnet[train]"
244
+ aimnet train data.train=dataset.h5 data.sae.energy.file=dataset_sae.yaml run_name=firstrun
245
+ ```
246
+
247
+ The `aimnet` command is installed with the core package; training, export, and self-atomic-energy commands need the `train` extra. The [training guide](https://isayevlab.github.io/aimnetcentral/train/) covers datasets, configuration, compiled training, stress training, and exporting models.
248
+
249
+ ## Development
250
+
251
+ ```bash
252
+ git clone https://github.com/isayevlab/aimnetcentral.git
253
+ cd aimnetcentral
254
+ make install # uv environment with all extras and pre-commit hooks
255
+ make check # formatting, linting, dependency checks
256
+ make test # pytest suite
257
+ make docs # serve the docs locally
258
+ ```
259
+
260
+ CI tests Python 3.11, 3.13, and 3.14, PyTorch 2.10 to 2.15, and each optional integration. Contributions are welcome; see [CONTRIBUTING.md](https://github.com/isayevlab/aimnetcentral/blob/main/CONTRIBUTING.md).
261
+
262
+ ## Citation
263
+
264
+ If AIMNet2 is useful in your work, please cite the relevant model papers:
265
+
266
+ **AIMNet2**
267
+
268
+ ```bibtex
269
+ @article{aimnet2,
270
+ title={AIMNet2: A Neural Network Potential to Meet Your Neutral, Charged, Organic, and Elemental-Organic Needs},
271
+ author={Anstine, Dylan M and Zubatyuk, Roman and Isayev, Olexandr},
272
+ journal={Chemical Science},
273
+ volume={16},
274
+ pages={10228--10244},
275
+ year={2025},
276
+ doi={10.1039/D4SC08572H}
277
+ }
278
+ ```
279
+
280
+ **AIMNet2-2025**
281
+
282
+ If you use AIMNet2-2025 (`aimnet2-2025`), please also cite [the AIMNet2-2025 paper](https://doi.org/10.1088/2632-2153/aea39f):
283
+
284
+ ```bibtex
285
+ @article{nayal2026critical,
286
+ title={Critical benchmarking of machine-learned interatomic potentials for intermolecular and noncovalent interactions},
287
+ author={Nayal, Kamal and Cho, IlKwon and Isayev, Olexandr},
288
+ journal={Machine Learning: Science and Technology},
289
+ year={2026},
290
+ doi={10.1088/2632-2153/aea39f}
291
+ }
292
+ ```
293
+
294
+ **AIMNet2-NSE:** Kalita, B.; Zubatyuk, R.; Anstine, D. M.; Bergeler, M.; Settels, V.; Stork, C.; Spicher, S.; Isayev, O. AIMNet2-NSE: A Transferable Reactive Neural Network Potential for Open-Shell Chemistry. _Angew. Chem. Int. Ed._ **2026**. DOI: [10.1002/anie.202516763](https://doi.org/10.1002/anie.202516763)
295
+
296
+ **AIMNet2-Pd:** Anstine, D. M.; Zubatyuk, R.; Gallegos, L.; Paton, R.; Wiest, O.; Nebgen, B.; Jones, T.; Gomes, G.; Tretiak, S.; Isayev, O. Transferable Machine Learning Interatomic Potential for Pd-Catalyzed Cross-Coupling Reactions. _ChemRxiv_ **2025**. DOI: [10.26434/chemrxiv-2025-n36r6](https://doi.org/10.26434/chemrxiv-2025-n36r6)
297
+
298
+ ## License
299
+
300
+ MIT; see [LICENSE](https://github.com/isayevlab/aimnetcentral/blob/main/LICENSE).
aimnet-0.2.6/README.md ADDED
@@ -0,0 +1,228 @@
1
+ [![PyPI](https://img.shields.io/pypi/v/aimnet)](https://pypi.org/project/aimnet/) [![Release](https://img.shields.io/github/v/release/isayevlab/aimnetcentral)](https://github.com/isayevlab/aimnetcentral/releases) [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/) [![Build status](https://img.shields.io/github/actions/workflow/status/isayevlab/aimnetcentral/main.yml?branch=main)](https://github.com/isayevlab/aimnetcentral/actions/workflows/main.yml?query=branch%3Amain) [![License](https://img.shields.io/github/license/isayevlab/aimnetcentral)](https://github.com/isayevlab/aimnetcentral/blob/main/LICENSE)
2
+
3
+ # AIMNet2
4
+
5
+ Fast neural-network interatomic potentials for organic, elemental-organic, open-shell, reactive, and palladium chemistry.
6
+
7
+ - **Documentation:** <https://isayevlab.github.io/aimnetcentral/>
8
+ - **Repository:** <https://github.com/isayevlab/aimnetcentral>
9
+ - **PyPI:** <https://pypi.org/project/aimnet/>
10
+ - **Demo:** <https://huggingface.co/spaces/isayevlab/aimnet2-demo>
11
+
12
+ ## What It Does
13
+
14
+ AIMNet2 predicts energies, forces, atomic charges, stress tensors, and Hessians for molecules and periodic systems. Pretrained models cover general organic chemistry, open-shell and reactive chemistry, and palladium catalysis.
15
+
16
+ - One calculator, `AIMNet2Calculator`, for single molecules, batches, and periodic cells
17
+ - ASE, PySisyphus, Sella, TorchSim, Hugging Face Hub, and command-line workflows
18
+ - Long-range Coulomb (DSF, Ewald, PME) and DFT-D3(BJ) dispersion on GPU
19
+ - Optional CUDA-graph replay and `torch.compile` for repeated evaluations
20
+ - Python 3.11 to 3.14 and PyTorch 2.10 or newer
21
+
22
+ ## Install
23
+
24
+ ```bash
25
+ pip install aimnet
26
+ ```
27
+
28
+ On Linux the default PyTorch wheel from PyPI includes CUDA. To pick a specific CUDA build, install PyTorch first, then AIMNet2:
29
+
30
+ ```bash
31
+ pip install torch --index-url https://download.pytorch.org/whl/cu126
32
+ pip install aimnet
33
+ ```
34
+
35
+ Optional integrations:
36
+
37
+ ```bash
38
+ pip install "aimnet[ase]" # ASE calculator
39
+ pip install "aimnet[pysis]" # PySisyphus reaction paths
40
+ pip install "aimnet[sella]" # Sella transition-state search, includes ASE
41
+ pip install "aimnet[hf]" # Hugging Face Hub model loading
42
+ pip install "aimnet[torchsim,ase]" # TorchSim, Python 3.12+
43
+ pip install "aimnet[train]" # training and export commands
44
+ ```
45
+
46
+ For offline or HPC clusters, see [Offline and HPC installation](https://isayevlab.github.io/aimnetcentral/offline_hpc/).
47
+
48
+ ## Quick Start
49
+
50
+ ```python
51
+ from aimnet.calculators import AIMNet2Calculator
52
+
53
+ calc = AIMNet2Calculator("aimnet2") # downloads the model on first use
54
+
55
+ water = {
56
+ "coord": [[0.000, 0.000, 0.119], [0.000, 0.763, -0.477], [0.000, -0.763, -0.477]],
57
+ "numbers": [8, 1, 1],
58
+ "charge": 0.0,
59
+ }
60
+ result = calc(water, forces=True)
61
+
62
+ print(result["energy"]) # eV
63
+ print(result["forces"]) # eV/Å
64
+ print(result["charges"]) # e
65
+ ```
66
+
67
+ ### ASE
68
+
69
+ ```python
70
+ from ase.io import read
71
+ from aimnet.calculators import AIMNet2ASE
72
+
73
+ atoms = read("molecule.xyz")
74
+ atoms.calc = AIMNet2ASE("aimnet2", charge=0)
75
+
76
+ energy = atoms.get_potential_energy()
77
+ forces = atoms.get_forces()
78
+ ```
79
+
80
+ ### TorchSim
81
+
82
+ ```python
83
+ import ase.io
84
+ import torch_sim as ts
85
+
86
+ from aimnet.calculators import AIMNet2Calculator, AIMNet2TorchSim
87
+
88
+ atoms = ase.io.read("molecule.xyz")
89
+ model = AIMNet2TorchSim(AIMNet2Calculator("aimnet2"))
90
+
91
+ results = ts.static(system=atoms, model=model)
92
+ print(results[0]["potential_energy"], results[0]["forces"])
93
+ ```
94
+
95
+ ### Periodic Systems
96
+
97
+ ```python
98
+ calc = AIMNet2Calculator("aimnet2")
99
+ calc.set_lrcoulomb_method("ewald", ewald_accuracy=1e-6)
100
+
101
+ result = calc(
102
+ {
103
+ "coord": coordinates, # (N, 3), Å
104
+ "numbers": atomic_numbers, # (N,)
105
+ "charge": 0.0,
106
+ "cell": cell_vectors, # (3, 3), Å; fully periodic
107
+ },
108
+ forces=True,
109
+ stress=True,
110
+ )
111
+ ```
112
+
113
+ See the [periodic systems tutorial](https://isayevlab.github.io/aimnetcentral/tutorials/periodic_systems/) and [long-range methods](https://isayevlab.github.io/aimnetcentral/long_range/) for choosing a Coulomb method.
114
+
115
+ ### Performance
116
+
117
+ `compile_model=False` and `cuda_graph=False` are the defaults. For many repeated evaluations of the same system size on a GPU, such as MD or geometry optimization, `cuda_graph=True` replays captured CUDA graphs and is often several times faster for small and medium molecules. See [CUDA-graph inference](https://isayevlab.github.io/aimnetcentral/cuda_graph/) for supported models and memory costs, and [performance tuning](https://isayevlab.github.io/aimnetcentral/tutorials/performance/) for batching and `torch.compile`.
118
+
119
+ ## Model Families
120
+
121
+ | Model | Elements | Best for |
122
+ | --- | --- | --- |
123
+ | `aimnet2` | H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I | General organic and elemental-organic chemistry, wB97M-D3 |
124
+ | `aimnet2-2025` | H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I | B97-3c with improved intermolecular interactions |
125
+ | `aimnet2-b973c` | H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I | Legacy B97-3c reproducibility |
126
+ | `aimnet2-nse` | H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I | Open-shell systems and radicals |
127
+ | `aimnet2-pd` | H, B, C, N, O, F, Si, P, S, Cl, Se, Br, Pd, I | Pd catalysis with B97-3c/CPCM(THF) reference data |
128
+ | `aimnet2-rxn` | H, C, N, O | Reactive chemistry, transition states, NEB, IRC; net-neutral systems only |
129
+
130
+ Each family has four ensemble members, `0` to `3`; short aliases load member `0`. Previously published names such as `aimnet2_2025`, `aimnet2nse`, and `aimnet2pd` still resolve.
131
+
132
+ The [model selection guide](https://isayevlab.github.io/aimnetcentral/models/guide/) covers known limitations, aliases, citations, and download links.
133
+
134
+ ## Hugging Face Models
135
+
136
+ With the `hf` extra installed, pass a repository ID directly:
137
+
138
+ ```python
139
+ from aimnet.calculators import AIMNet2Calculator
140
+
141
+ calc = AIMNet2Calculator("isayevlab/aimnet2-wb97m-d3")
142
+ calc = AIMNet2Calculator("isayevlab/aimnet2-wb97m-d3", ensemble_member=2)
143
+ calc = AIMNet2Calculator("isayevlab/aimnet2-wb97m-d3", revision="v1.0")
144
+ ```
145
+
146
+ | HF repo | Alias | Use |
147
+ | --- | --- | --- |
148
+ | `isayevlab/aimnet2-wb97m-d3` | `aimnet2` | General organic chemistry |
149
+ | `isayevlab/aimnet2-2025` | `aimnet2-2025` | Improved intermolecular interactions |
150
+ | `isayevlab/aimnet2-nse` | `aimnet2-nse` | Open-shell chemistry |
151
+ | `isayevlab/aimnet2-pd` | `aimnet2-pd` | Palladium chemistry |
152
+ | `isayevlab/aimnet2-rxn` | `aimnet2-rxn` | Reactive paths and transition states |
153
+
154
+ Private repositories load with `token=` or the `HF_TOKEN` environment variable. Local directories with `config.json` and `ensemble_N.safetensors` also work.
155
+
156
+ ## Outputs
157
+
158
+ | Key | Shape | Units |
159
+ | --------- | ----------------------------------- | ------ |
160
+ | `energy` | `(B,)` | eV |
161
+ | `forces` | `(N, 3)` or `(B, N, 3)` | eV/Å |
162
+ | `charges` | `(N,)` or `(B, N)` | e |
163
+ | `stress` | `(3, 3)` or `(B, 3, 3)` | eV/Å^3 |
164
+ | `hessian` | `(N, 3, N, 3)` or `(B, N, 3, N, 3)` | eV/Å^2 |
165
+
166
+ `B` is the number of systems (1 for a single molecule) and `N` the number of atoms. Stress uses the ASE sign convention. Batched Hessians are evaluated per system and returned as a list when the systems differ in size. The [calculator reference](https://isayevlab.github.io/aimnetcentral/calculator/) documents input layouts, batching, and the derivative support of each long-range method.
167
+
168
+ ## Training
169
+
170
+ ```bash
171
+ pip install "aimnet[train]"
172
+ aimnet train data.train=dataset.h5 data.sae.energy.file=dataset_sae.yaml run_name=firstrun
173
+ ```
174
+
175
+ The `aimnet` command is installed with the core package; training, export, and self-atomic-energy commands need the `train` extra. The [training guide](https://isayevlab.github.io/aimnetcentral/train/) covers datasets, configuration, compiled training, stress training, and exporting models.
176
+
177
+ ## Development
178
+
179
+ ```bash
180
+ git clone https://github.com/isayevlab/aimnetcentral.git
181
+ cd aimnetcentral
182
+ make install # uv environment with all extras and pre-commit hooks
183
+ make check # formatting, linting, dependency checks
184
+ make test # pytest suite
185
+ make docs # serve the docs locally
186
+ ```
187
+
188
+ CI tests Python 3.11, 3.13, and 3.14, PyTorch 2.10 to 2.15, and each optional integration. Contributions are welcome; see [CONTRIBUTING.md](https://github.com/isayevlab/aimnetcentral/blob/main/CONTRIBUTING.md).
189
+
190
+ ## Citation
191
+
192
+ If AIMNet2 is useful in your work, please cite the relevant model papers:
193
+
194
+ **AIMNet2**
195
+
196
+ ```bibtex
197
+ @article{aimnet2,
198
+ title={AIMNet2: A Neural Network Potential to Meet Your Neutral, Charged, Organic, and Elemental-Organic Needs},
199
+ author={Anstine, Dylan M and Zubatyuk, Roman and Isayev, Olexandr},
200
+ journal={Chemical Science},
201
+ volume={16},
202
+ pages={10228--10244},
203
+ year={2025},
204
+ doi={10.1039/D4SC08572H}
205
+ }
206
+ ```
207
+
208
+ **AIMNet2-2025**
209
+
210
+ If you use AIMNet2-2025 (`aimnet2-2025`), please also cite [the AIMNet2-2025 paper](https://doi.org/10.1088/2632-2153/aea39f):
211
+
212
+ ```bibtex
213
+ @article{nayal2026critical,
214
+ title={Critical benchmarking of machine-learned interatomic potentials for intermolecular and noncovalent interactions},
215
+ author={Nayal, Kamal and Cho, IlKwon and Isayev, Olexandr},
216
+ journal={Machine Learning: Science and Technology},
217
+ year={2026},
218
+ doi={10.1088/2632-2153/aea39f}
219
+ }
220
+ ```
221
+
222
+ **AIMNet2-NSE:** Kalita, B.; Zubatyuk, R.; Anstine, D. M.; Bergeler, M.; Settels, V.; Stork, C.; Spicher, S.; Isayev, O. AIMNet2-NSE: A Transferable Reactive Neural Network Potential for Open-Shell Chemistry. _Angew. Chem. Int. Ed._ **2026**. DOI: [10.1002/anie.202516763](https://doi.org/10.1002/anie.202516763)
223
+
224
+ **AIMNet2-Pd:** Anstine, D. M.; Zubatyuk, R.; Gallegos, L.; Paton, R.; Wiest, O.; Nebgen, B.; Jones, T.; Gomes, G.; Tretiak, S.; Isayev, O. Transferable Machine Learning Interatomic Potential for Pd-Catalyzed Cross-Coupling Reactions. _ChemRxiv_ **2025**. DOI: [10.26434/chemrxiv-2025-n36r6](https://doi.org/10.26434/chemrxiv-2025-n36r6)
225
+
226
+ ## License
227
+
228
+ MIT; see [LICENSE](https://github.com/isayevlab/aimnetcentral/blob/main/LICENSE).
@@ -0,0 +1,114 @@
1
+ """Resolve graph opt-in and its runtime requirements without importing the optional execution backend."""
2
+
3
+ import importlib.metadata
4
+ import os
5
+ import re
6
+ import sys
7
+
8
+ import torch
9
+
10
+ # Minimum versions for CUDA-graph capture. nvalchemi-toolkit-ops 0.5.0 orders its Warp neighbor kernels on
11
+ # PyTorch's current stream and resets buffers internally (see ``neighbor_buffers.ReusableNeighborMatrix``); graphs
12
+ # captured with 0.4.1 were measured to replay wrong energies (1-4700 eV off). 0.5.0 itself requires warp-lang >= 1.16. The package floor stays at the regular path's requirements, so older
13
+ # installs keep working and only graph capture is refused.
14
+ GRAPH_MIN_VERSIONS: dict[str, tuple[int, ...]] = {
15
+ "nvalchemi-toolkit-ops": (0, 5, 0),
16
+ "warp-lang": (1, 16, 0),
17
+ }
18
+
19
+
20
+ def cuda_graph_enabled(cuda_graph: bool | None = False) -> bool:
21
+ """Explicit booleans win; ``None`` opts into environment-based selection.
22
+
23
+ An omitted argument is ``False`` even if ``AIMNET_CUDA_GRAPH`` is set.
24
+ Environment selection enables graphs only for 1/true/yes/on, ignoring case.
25
+ """
26
+ if cuda_graph is not None:
27
+ return bool(cuda_graph)
28
+ return os.environ.get("AIMNET_CUDA_GRAPH", "0").strip().lower() in ("1", "true", "yes", "on")
29
+
30
+
31
+ # PEP 440 public version with optional local label (normalized forms and the usual spellings). ``packaging`` is not a
32
+ # core dependency, so the few fields the gate needs are parsed here.
33
+ _VERSION = re.compile(
34
+ r"""
35
+ ^\s*v?
36
+ (?:(?P<epoch>\d+)!)?
37
+ (?P<release>\d+(?:\.\d+)*)
38
+ (?P<pre>[-_.]?(?:a|alpha|b|beta|c|rc|pre|preview)[-_.]?\d*)?
39
+ (?P<post>-\d+|[-_.]?(?:post|rev|r)[-_.]?\d*)?
40
+ (?P<dev>[-_.]?dev[-_.]?\d*)?
41
+ (?:\+[a-z0-9]+(?:[-_.][a-z0-9]+)*)?
42
+ \s*$
43
+ """,
44
+ re.VERBOSE | re.IGNORECASE,
45
+ )
46
+
47
+
48
+ def version_at_least(text: str, minimum: tuple[int, ...]) -> bool:
49
+ """Whether version ``text`` is at least the final release ``minimum`` under PEP 440 ordering.
50
+
51
+ Pre-releases and development builds of ``minimum`` itself precede it and are rejected (``0.5.0rc1``,
52
+ ``0.5.0.dev3``); post-releases and later releases, including their development builds (``0.5.1.dev0``), pass.
53
+ Unparsable versions are rejected."""
54
+ match = _VERSION.match(text)
55
+ if match is None:
56
+ return False
57
+ if int(match.group("epoch") or 0) > 0:
58
+ return True
59
+ release = tuple(int(part) for part in match.group("release").split("."))
60
+ width = max(len(release), len(minimum))
61
+ release, padded_min = release + (0,) * (width - len(release)), minimum + (0,) * (width - len(minimum))
62
+ if release != padded_min:
63
+ return release > padded_min
64
+ if match.group("pre"):
65
+ return False
66
+ return not (match.group("dev") and not match.group("post"))
67
+
68
+
69
+ def installed_versions() -> dict[str, str | None]:
70
+ """Installed versions of the graph backend's dependencies (None when the distribution is not found)."""
71
+ found: dict[str, str | None] = {}
72
+ for name in GRAPH_MIN_VERSIONS:
73
+ try:
74
+ found[name] = importlib.metadata.version(name)
75
+ except importlib.metadata.PackageNotFoundError:
76
+ found[name] = None
77
+ return found
78
+
79
+
80
+ def cuda_graph_dependency_problem() -> str | None:
81
+ """Why the installed dependencies cannot capture correct CUDA graphs, or None when they can."""
82
+ too_old = []
83
+ for name, version in installed_versions().items():
84
+ minimum = GRAPH_MIN_VERSIONS[name]
85
+ if version is None or not version_at_least(version, minimum):
86
+ required = ".".join(map(str, minimum))
87
+ too_old.append(f"{name} {version or 'unknown'} (needs >= {required})")
88
+ if not too_old:
89
+ return None
90
+ return (
91
+ "the installed " + ", ".join(too_old) + " cannot capture correct CUDA graphs; "
92
+ 'upgrade with `pip install -U "nvalchemi-toolkit-ops>=0.5.0" "warp-lang>=1.16"`'
93
+ )
94
+
95
+
96
+ def cuda_graph_platform_problem() -> str | None:
97
+ """Why this PyTorch build cannot run the graph backend, or None."""
98
+ if getattr(torch.version, "hip", None):
99
+ return "ROCm builds are not supported (the Warp/nvalchemi kernels are CUDA-only)"
100
+ return None
101
+
102
+
103
+ _PACKAGE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + os.sep
104
+
105
+
106
+ def external_stacklevel() -> int:
107
+ """``stacklevel`` for a ``warnings.warn`` issued by the caller of this function that attributes the warning to
108
+ the first frame outside the ``aimnet`` package (the user's call, however deep the internal dispatch is)."""
109
+ frame = sys._getframe(1)
110
+ level = 1
111
+ while frame is not None and frame.f_code.co_filename.startswith(_PACKAGE_DIR):
112
+ frame = frame.f_back # type: ignore[assignment]
113
+ level += 1
114
+ return level
@@ -51,7 +51,7 @@ class AIMNet2ASE(Calculator):
51
51
  ):
52
52
  if _ASE_IMPORT_ERROR is not None:
53
53
  raise ImportError(
54
- 'AIMNet2ASE requires ASE. Install it with `pip install "aimnet[ase]"`.'
54
+ 'AIMNet2ASE requires ASE. Install with `pip install "aimnet[ase]"` — or on conda: conda install -c conda-forge ase'
55
55
  ) from _ASE_IMPORT_ERROR
56
56
 
57
57
  super().__init__()
@@ -164,9 +164,10 @@ class AIMNet2ASE(Calculator):
164
164
  """Return Cartesian Hessian as a (3N, 3N) ndarray in eV/Å^2.
165
165
 
166
166
  Designed for use as ``Sella(atoms, hessian_function=atoms.calc.get_hessian)``.
167
- Computed via double-backward through the AIMNet2 energy graph; cost scales
168
- as O(3N) backward passes per call. Not supported when ``compile_model=True``
169
- or for batched / multi-molecule input.
167
+ Computed via the original eager AIMNet2 module, including when the
168
+ calculator's inference forward is compiled. Cost scales as O(3N)
169
+ backward passes per call. Batched or multi-molecule input is not
170
+ supported.
170
171
 
171
172
  This method intentionally bypasses the standard ASE
172
173
  ``Calculator.calculate(properties=['hessian'])`` flow and ``self.results``