Add-ons

Aitomic add-ons extend open-source MLatom with cutting-edge methods from Aitomistic, some of them available even before their publication. Over time methods graduate to fully open distribution: for example, OMNI-P2x is now part of public MLatom, and AIQM3 is now available as the open aitomic-addons package.

You can run all of these methods online, without installing anything, on the Aitomistic Lab@XMU and Aitomistic Hub with the Protomia AI assistant.

Installation of AIQM3

AIQM3, the third generation of delta-learning-based artificial intelligence-enhanced quantum-mechanical methods, is distributed as a compiled add-on on PyPI.

Supported platforms and Python versions

The aitomic-addons package ships pre-compiled binary wheels only (there is no source distribution to build from), so it installs only where a matching wheel is published. Check your environment against this list before installing:

  • Operating system / architecture: Linux on x86-64 or ARM64 (aarch64), built for manylinux2014 (glibc >= 2.17). There are no macOS or Windows wheels. On macOS or Windows, run the methods online on the Aitomistic Lab@XMU / Aitomistic Hub, or install inside a Linux container, VM, or WSL2.

  • Python: 3.9, 3.10, or 3.11 (3.11 recommended).

    • Python <= 3.8 is not supported by aitomic-addons – no wheels are published below 3.9.

    • Python >= 3.12 currently has no wheel for the pinned torch==2.1.2 that AIQM3 requires, so stay on 3.9–3.11.

  • Clean environment: install into a fresh conda/venv, not an old base environment, to avoid version conflicts.

Per-component compatibility (AIQM3 needs all of them, so its requirements are the intersection):

Component

OS / architecture

Python

mlatom

any (the compiled backends run on Linux)

>= 3.9

aitomic-addons (AIQM3 engine)

Linux x86-64 / aarch64 only

3.9 – 3.13

torch==2.1.2 (pinned for AIQM3)

Linux / macOS / Windows

3.8 – 3.11

AIQM3 (all combined)

Linux x86-64 / aarch64, glibc >= 2.17

3.9, 3.10, or 3.11

Installing

Install AIQM3 into a fresh Python 3.11 environment (it requires specific PyTorch/TorchANI versions; see also Installation):

conda create -n aiqm3 python=3.11 -y
conda activate aiqm3
pip install -U "numpy<2" torch==2.1.2 torchani==2.2.3 mlatom aitomic-addons joblib pyscf geometric

AIQM3 also uses D3 dispersion – install the s-dftd3 tool and point dftd3bin at the executable:

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

That is all – MLatom resolves AIQM3 automatically, with no extra imports. The neural-network parameters are downloaded automatically the first time the method is used, together with a one-time license notice. Verify the installation with a water geometry optimization:

import mlatom as ml

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')
opt = ml.optimize_geometry(model=aiqm3, initial_molecule=mol).optimized_molecule
print(opt.energy)          # -76.3787 Hartree

If you encounter a UnicodeDecodeError from xtb, run under a UTF-8 locale, e.g. with export PYTHONUTF8=1.

Troubleshooting the installation

“No matching distribution found for aitomic-addons”

ERROR: Could not find a version that satisfies the requirement aitomic-addons (from versions: none)
ERROR: No matching distribution found for aitomic-addons

pip reached PyPI but found no wheel matching your Python version, operating system, or CPU architecture. The usual causes:

  • Python is too old (3.7 or 3.8) – aitomic-addons provides wheels only for Python 3.9–3.13. Check with python --version.

  • The platform is macOS, Windows, or a CPU other than x86-64 / aarch64 – only Linux x86-64 / aarch64 wheels are published, and there is no source distribution to fall back on.

Fix: create a fresh Python 3.11 environment on a supported Linux platform (see Supported platforms and Python versions above).

The same message for torch==2.1.2 (No matching distribution found for torch==2.1.2) usually means your Python is 3.12 or newer, for which that pinned torch has no wheel – use Python 3.9–3.11.

License

The Aitomic add-ons are free for academic, non-commercial research and teaching under the Aitomic Add-Ons Academic License. You accept the license by installing or using the package, and certify that your use is academic and non-commercial. Commercial use requires a separate license – contact contact@aitomistic.com.

See the full license text.

More methods (UAIQM and others)

Further Aitomic methods – including the UAIQM family (universal, updatable AIQM foundational models, extended to almost all elements of the periodic table, with automatic selection of the most suitable model) and other still-unpublished methods – are not yet on PyPI. If you would like to use them, please contact us at contact@aitomistic.com.

For better support, consultation on the best choice and use of methods, faster replies, and frequent upgrades, you might want the Aitomistic subscription, which also supports our efforts. Please contact us for details at contact@aitomistic.com.

Citation

If you use the Aitomic add-ons, please cite them (check your version for the exact number):

Please also cite the underlying methods (for example, AIQM3) as listed in the MLatom output and documentation.