aitomic-addons

Aitomic Add-Ons for MLatom by Aitomistic, starting with AIQM3 — the third generation of delta-learning-based artificial intelligence-enhanced quantum-mechanical methods.

Free for academic, non-commercial research and teaching under the Aitomic Academic License; commercial use requires a separate license. Terms: https://aitomistic.com/mlatom/addons.html.

Tutorials: https://aitomistic.com/mlatom/tutorial_aiqm2.html.

• Methods: AIQM3, AIQM3@DFT, AIQM3@DFT*
• Elements: H, C, N, O, F, S, Cl

Installation

pip install aitomic-addons

MLatom is installed automatically as a dependency. The neural-network parameters are downloaded automatically the first time a method is used.

AIQM3 also uses D3 dispersion. MLatom runs s-dftd3 as a separate program, so it has to be on your system and dftd3bin has to point at the executable:

conda install -c conda-forge simple-dftd3
export dftd3bin=$CONDA_PREFIX/bin/s-dftd3

The conda-forge package is called simple-dftd3. There is no dftd3 package on conda-forge, and pip install dftd3 installs Python bindings only — no s-dftd3 executable — so it does not make AIQM3 work.

Usage

Python API

Run a calculation through MLatom's standard interface — no extra imports once the package is installed:

import mlatom as ml

# Water (XYZ coordinates in Angstrom)
mol = ml.data.molecule.from_xyz_string('''3

O    0.00000    0.00000    0.11779
H    0.00000    0.75545   -0.47116
H    0.00000   -0.75545   -0.47116
''')

aiqm3 = ml.methods(method='AIQM3')
aiqm3.predict(molecule=mol, calculate_energy=True, calculate_energy_gradients=True)

print('Energy (Hartree):', mol.energy)
print('Energy gradients (Hartree/Angstrom):')
print(mol.energy_gradients)

Output:

Energy (Hartree): -76.37869477070018
Energy gradients (Hartree/Angstrom):
[[ 1.72364427e-17  1.85195818e-16  1.57502823e-03]
 [-2.71918885e-17 -1.13356199e-03 -7.87514116e-04]
 [ 9.95544574e-18  1.13356199e-03 -7.87514116e-04]]

(On the first run, a one-time license notice is also printed.)

Without this package installed, MLatom reports AIQM3 as an add-on and points here.

Fine-tuning

New in 1.1.0: AIQM3 can be fine-tuned on your own reference data through the same train() call as any other MLatom model, and the result is saved and loaded like any other model. A few dozen reference points are often enough to specialize it to your own system. Requires MLatom 3.25.2 or newer.

import mlatom as ml

db = ml.data.molecular_database.load('reference_data.json', format='json')

model = ml.models.methods(method='AIQM3')
model.train(
    molecular_database=db,
    property_to_learn='energy',
    xyz_derivative_property_to_learn='energy_gradients',   # optional: fit forces too
    dispersion_kwargs={'method': 'd3bj', 'functional': 'b973c',
                       'damping_function_params': [1.0, 1.5, 0.37, 4.1]},
    file_to_save_model='my_aiqm3',
    hyperparameters={'max_epochs': 100, 'batch_size': 8},
)

# reload it later
model = ml.models.aiqm3.load('my_aiqm3')

dispersion_kwargs is required, and it describes your reference labels, not the model: whatever you name is subtracted from your labels before training and added back at prediction, so your energies are reproduced either way. The value above is AIQM3's own term -- use it when your level's dispersion cannot be cleanly separated (MP2, CCSD(T)). Use {'method': 'd3bj', 'functional': 'b3lyp'} if your labels are B3LYP-D3(BJ) or similar, or False if they carry no dispersion at all.

Input file/CLI

AIQM3 also runs from MLatom input files. For example, a geometry optimization in a self-contained input file geomopt.inp (with the geometry inline):

AIQM3
geomopt
xyzfile='3

O    0.00000    0.00000    0.11779
H    0.00000    0.75545   -0.47116
H    0.00000   -0.75545   -0.47116
'
optxyz=water_opt.xyz

Run it as you would any MLatom job:

mlatom geomopt.inp

The optimized geometry is written to water_opt.xyz:

3

O    0.00000    0.00000    0.11608
H    0.00000    0.75745   -0.47031
H    0.00000   -0.75745   -0.47031

Online

The same calculations can also be run — without installing anything — on the Aitomistic Hub, where the Protomia AI assistant sets them up and runs them for you.

License

Aitomic Add-Ons are free for academic, non-commercial research and teaching under the Aitomic Academic License. By installing and using them you agree to the license and certify that your use is academic and non-commercial; a short one-time notice is printed the first time a method is used.

Commercial use requires a separate license — contact@aitomistic.com. Full terms: https://aitomistic.com/mlatom/addons.html.

Citation

If you use AIQM3, please cite the method, MLatom, and Aitomic add-ons to MLatom:

• Yuxinxin Chen, Yi-Fan Hou, Roman Zubatyuk, Olexandr Isayev, Pavlo O. Dral. AIQM3: Targeting Coupled-Cluster Accuracy with Semi-Empirical Speed across Seven Main Group Elements. J. Chem. Theory Comput. 2026. DOI: 10.1021/acs.jctc.5c01794. Preprint on ChemRxiv: https://doi.org/10.26434/chemrxiv-2025-g2dbg.

• Pavlo O. Dral, Fuchun Ge, Yi-Fan Hou, Peikun Zheng, Yuxinxin Chen, Mario Barbatti, Olexandr Isayev, Cheng Wang, Bao-Xin Xue, Max Pinheiro Jr, Yuming Su, Yiheng Dai, Yangtao Chen, Lina Zhang, Shuang Zhang, Arif Ullah, Quanhao Zhang, Yanchi Ou. MLatom 3: A Platform for Machine Learning-enhanced Computational Chemistry Simulations and Workflows. J. Chem. Theory Comput. 2024, 20, 1193–1213. DOI: 10.1021/acs.jctc.3c01203.

• Pavlo O. Dral, Yuxinxin Chen, Mikołaj Martyka, Jingbai Li. Aitomic add-ons to MLatom; version 1.1.0. Aitomistic, Shenzhen, China, 2025--2026. https://aitomistic.com/mlatom/addons.html (accessed 14 June 2026).

Please also cite the underlying methods (GFN2-xTB*, TorchANI, and the dispersion correction) as listed in the MLatom output and documentation.

Staying up to date

Subscribe to the newsletter for release announcements: https://aitomistic.com/en/contact.