Metadata-Version: 2.4
Name: mlatom
Version: 3.25.2
Summary: A Package for AI-enhanced computational chemistry
Author-email: "Pavlo O. Dral" <admin@mlatom.com>
License: Apache-2.0
Project-URL: Homepage, http://mlatom.com
Project-URL: Documentation, http://mlatom.com/docs
Project-URL: Repository, https://github.com/dralgroup/mlatom
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Fortran
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Environment :: Console
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy<2
Requires-Dist: scipy
Requires-Dist: h5py
Requires-Dist: pyh5md
Requires-Dist: torch==2.1.2
Requires-Dist: torchani==2.2.3
Requires-Dist: setuptools<81
Requires-Dist: matplotlib
Requires-Dist: statsmodels
Requires-Dist: tqdm
Requires-Dist: joblib
Requires-Dist: requests
Requires-Dist: psutil
Requires-Dist: geometric
Requires-Dist: rmsd

<p align="center">
  <a href="http://mlatom.com"><img src="assets/img/banner.png" alt="MLatom" width="720"></a>
</p>

<p align="center">
  <a href="https://pypi.org/project/mlatom/"><img src="https://img.shields.io/pypi/v/mlatom.svg" alt="PyPI version"></a>
  <a href="https://pepy.tech/project/mlatom"><img src="https://static.pepy.tech/badge/mlatom" alt="Downloads"></a>
  <a href="https://pepy.tech/project/mlatom"><img src="https://static.pepy.tech/badge/mlatom/month" alt="Downloads per month"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a>
  <a href="http://mlatom.com/docs"><img src="https://img.shields.io/badge/docs-mlatom.com-brightgreen.svg" alt="Documentation"></a>
</p>

# MLatom

MLatom is an open-source package for **atomistic simulations with machine learning and quantum chemical methods** — DFT, wavefunction-based, and semi-empirical approximations. Use it as a Python library, through input files, or from the command line — run it locally, or online with no installation.

**[Website](http://mlatom.com)** · **[Documentation](http://mlatom.com/docs)** · **[Protomia](https://aitomistic.com/protomia)** · **[Aitomistic Hub](https://aitomistic.xyz)** · **[Aitomistic Lab@XMU](https://atom.xmu.edu.cn)** · **[Releases](http://mlatom.com/docs/releases.html)**

## Run online — no installation

Run MLatom in your browser on either online platform — both powered by [Protomia](https://aitomistic.com/protomia), with an AI assistant for autonomous atomistic simulations:

- **[Aitomistic Hub](https://aitomistic.xyz)** — free registration.
- **[Aitomistic Lab@XMU](https://atom.xmu.edu.cn)** — free for academic users (registration with an academic email).

## Local installation

The easiest way to run MLatom is [online](http://mlatom.com/docs/cloud.html) — no installation. To install locally:

```bash
python3 -m pip install -U mlatom
```

That pulls in the required dependencies automatically (including the PyTorch/TorchANI and geometry-optimization backends the **AIQM2** quick start uses). A few features need one more package — install only what you use:

| for | install |
| --- | --- |
| PySCF methods: single point, TDDFT, frequencies and thermochemistry, densities, Raman | `pip install pyscf` |
| AIMNet2 models | `pip install aimnet` |
| format conversions (SMILES to xyz and back) | `conda install -c conda-forge openbabel` |
| the ASE interface (ASE optimizers and dynamics) and MACE | `pip install ase` |
| KREG_API backend (`ml_program='MLatomF'` needs none of this) | `conda install -c conda-forge mkl mkl-service` |
| MDtrajNet / MLTPA / DMC / hyperparameter search | `pip install e3nn` / `rdkit` / `pyvibdmc` / `hyperopt` |

AIQM2 additionally needs the DFT-D4 program, installed via conda:

```bash
conda install -c conda-forge 'dftd4==3.6.0'   # the version MLatom is tested against
export dftd4bin=$(which dftd4)   # point MLatom at the dftd4 executable
```

See the [installation guide](http://mlatom.com/docs/installation.html) for the full dependency list and other methods.

## Quick start

Optimize the geometry of a water molecule with **AIQM2** — an AI-enhanced quantum-mechanical method (native to MLatom, CHNO elements) that reaches beyond-DFT accuracy at semi-empirical cost:

```python
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
''')
aiqm2 = ml.methods(method='AIQM2')
opt = ml.optimize_geometry(model=aiqm2, initial_molecule=mol).optimized_molecule
print(opt.energy)          # optimized energy in hartree (≈ -76.3838)
```

The same calculation as an input file (`geomopt.inp`, with `init.xyz` holding the geometry):

```
AIQM2               # method
geomopt             # task: geometry optimization
xyzfile=init.xyz    # input geometry
optxyz=opt.xyz      # output geometry
```

```bash
mlatom geomopt.inp
```

Prefer zero setup? Run these online on the [Aitomistic Hub](https://aitomistic.xyz) or [Aitomistic Lab@XMU](https://atom.xmu.edu.cn) (both powered by [Protomia](https://aitomistic.com/protomia)) — no installation needed.

## Features & documentation

Full manuals and tutorials are at **[mlatom.com/docs](http://mlatom.com/docs)** — begin with [installation](http://mlatom.com/docs/installation.html) and [get started](http://mlatom.com/docs/get_started.html).

- **Methods** — universal ML potentials (ANI, AIMNet2); AI-enhanced QM methods ([UAIQM](http://mlatom.com/docs/tutorial_uaiqm.html), [AIQM1](http://mlatom.com/docs/tutorial_aiqm1.html), [AIQM2](http://mlatom.com/docs/tutorial_aiqm2.html)) approaching coupled-cluster accuracy at semi-empirical cost; and DFT, semi-empirical, and wavefunction methods via interfaces (PySCF, Gaussian, ORCA, xtb, MNDO, Turbomole, DFTB+, Sparrow, Columbus).
- **ML models** — [train and use ML potentials](http://mlatom.com/docs/tutorial_mlp.html) (KREG, GAP-SOAP, ANI, MACE, and more) with [active learning](http://mlatom.com/docs/tutorial_al.html), Δ-learning, [transfer learning](http://mlatom.com/docs/tutorial_tl.html), and self-correction.
- **Simulations** — [geometry optimization](http://mlatom.com/docs/tutorial_geomopt.html), [transition-state search](http://mlatom.com/docs/tutorial_ts.html), [IRC](http://mlatom.com/docs/tutorial_irc.html), [frequencies & thermochemistry](http://mlatom.com/docs/tutorial_freq.html), [molecular dynamics](http://mlatom.com/docs/tutorial_md.html), [nonadiabatic dynamics](http://mlatom.com/docs/tutorial_namd.html), [IR](http://mlatom.com/docs/tutorial_ir.html)/[Raman](http://mlatom.com/docs/tutorial_raman.html)/[UV–vis](http://mlatom.com/docs/tutorial_uvvis.html) spectra, and [periodic boundary conditions](http://mlatom.com/docs/tutorial_pbc.html).
- **Workflows** — compose methods and tasks into complex pipelines from Python, input files, or the command line.

## How to cite

If you use MLatom in scientific work, please cite:

> Pavlo O. Dral et al. *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](https://doi.org/10.1021/acs.jctc.3c01203)

Feature-specific references appear in the program output and in [`CITATION.cff`](CITATION.cff). The full list with BibTeX is on the [License and citations](http://mlatom.com/docs/license.html) page.

## Ecosystem

- **[MLatom Skills](https://github.com/dralgroup/mlatom-skills)** — agent skills for MLatom (new and growing rapidly).
- **[Aitomic add-ons](http://mlatom.com/docs/addons.html)** — cutting-edge methods (e.g. AIQM3), free for academic, non-commercial use.
- **[Aitomia](https://github.com/dralgroup/aitomia)** — an AI assistant for autonomous atomistic simulations with MLatom.

## Recent releases

Full [release notes](http://mlatom.com/docs/releases.html) · [`CHANGELOG.md`](CHANGELOG.md)

- **3.25** — fine-tuning of the universal models on your own data: ANI, AIQM1, AIQM2, AIQM3, UAIQM, OMNI-P1 and OMNI-P2x all through the same `train()` call, with dispersion handled on both sides so the fine-tuned model keeps the long-range behaviour.
- **3.23** — AIQM3 public add-on (`pip install aitomic-addons`); direct Gaussian workflows; version/commit/build-date banner with a daily update check.
- **3.22** — OMNI-P2x model; faster nonadiabatic dynamics.
- **3.21** — refactored ORCA interface supporting many more excited-state methods.
- **3.18** — FSSH; MDtrajNet-1 (directly predicting MD trajectories); KRR in Julia; ECTS diffusion model for transition states.

## Contributing

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). Report bugs and request features via [GitHub issues](https://github.com/dralgroup/mlatom/issues). You may also create your own private derivatives by following the license requirements.

## Stay updated

Don't miss MLatom updates — [subscribe](https://aitomistic.com/en/contact) to the Aitomistic email newsletter and social channels.

## About

MLatom was founded by [Pavlo O. Dral](http://dr-dral.com) on 10 September 2013, who continues to lead its development. It is open-source under the Apache License 2.0 and supported by [Aitomistic](https://aitomistic.com).
