.. _addons:

Add-ons
=========================

Aitomic is the package for AI atomistic (aitomistic) simulations, seamlessly combining AI/ML with quantum mechanical methods. The package leverages the versatility of open-source MLatom, while also providing a treasure trove of the cutting-edge methods made accessible via add-ons even before their publication or preprints. The package is distributed via Aitomistic and can be used for online simulations on Aitomistic Hub.

We provide Aitomic for free for academic users subject to a license agreement, which requests the usual provisions of confidentiality due to the sensitive nature of unpublished methods (the add-ons might be treated separately). If you intend to use it for commercial purposes, you may purchase Aitomic.

If you want to get better support, consultation on the best choice and use of methods, faster replies, and frequent upgrades of the package, you might want to choose the Aitomium (premium) subscription, which will support our efforts too. Please contact us for more details at contact@aitomistic.com.


Add-on examples
---------------
Highlights of the add-ons available in Aitomic:


Universal and Updatable Artificial Intelligence-Enhanced Quantum Chemical Foundational Models:

- The library of the AIQM models – published and unpublished – all collected in one place for convenient access.

    - AIQM3

- Automatic selection of the best AIQM model most suitable for your aitomistic simulations.
- Extension of many AIQM methods to almost all elements in the periodic table.
- OMNI-P2x: A Universal Neural Network Potential for Excited-State Simulations.

Citation
--------

Cite Aitomic as (check your version for details):


- Pavlo O. Dral, Yuxinxin Chen, Mikołaj Martyka, Jingbai Li. Aitomic: A package for AI-enhanced atomistic simulations; version XX. Aitomistic, Shenzhen, China, 2025. http://mlatom.com/aitomic (accessed 17 April 2025).

How to obtain Aitomic?
----------------------
To obtain Aitomic, please register on the Aitomistic Hub (registration is free), proceed to the Download page, click on Request Download Access, and follow the instructions.

Installation
------------

Below we provide the instructions on how to install Aitomic locally, test, and cite.

You can download the Aitomic package, version 0.91alpha, from https://www.aitomistic.xyz/download.

The package is 1.5 GB due to all the ML models.

After downloading, untar Aitomic with

.. code-block:: bash

    tar -xvf aitomic_pkg.v0.91alpha.tar

The resulting folder `aitomic_pkg` contains `aitomic` and `test` subfolders.

To use Aitomic, you can:

* set the PYTHONPATH (if you want to use it in Python scripts), for this, e.g.,:

.. code-block:: bash

    export PYTHONPATH=$PYTHONPATH:path/to/aitomic_pkg 
				
* or set an alias to use it in command line:

.. code-block:: bash

	aitomic=/path/to/aitomic_pkg/aitomic/shell_cmd.py 
				
You would need to install all required Python dependencies, analogously to MLatom (see installation instructions: http://mlatom.com/docs/installation.html). Hint: we use Python 3.11, TorchANI 2.2, and PyTorch 2.2 or 2.1.2 (you can downgrade pytorch and torchani to those versions if the newer ones do not work), you can also download the mlatom.yml to help you to setup the Anaconda environment (see above installation page).

.. note::

    To use UAIQM and AIQM series, softwares for dispersion correction should be properly set in environment variables: 

    - dftd4

    The simplest way to install dftd4 is through conda and then set ``dftd4bin`` to the binary under your conda environment ``/bin/dftd4``. 

    .. code-block:: bash 

        dftd4bin=/path/to/dftd4/dftd4

    You can also try to compile dftd4 from scratch according to the official website: https://github.com/dftd4/dftd4

    - dftd3

    The latest UAIQM methods uses D3 dispersion correction (``uaiqm_gfn2xtbstar@cc`` of version ``20250115``,  ``uaiqm_gfn2xtbstar@dft`` of version ``20240730``, ``AIQM3`` and ``AIQM3@DFT``). Installation instruction can be found in the official website: https://github.com/dftd3/simple-dftd3. After installation of dftd3, the environment variable ``dftd3bin`` is needed 

    .. code-block:: bash 

        dftd3bin=/path/to/dftd3/s-dftd3


Usage instructions
------------------

After installation, you can run Aitomic in the same way as MLatom (e.g., see instructions at http://mlatom.com/docs/tutorial_uaiqm.html for UAIQM), with exception that you need to import aitomic, e.g.:

* in Python:

.. code-block:: bash

    import aitomic as ml

    ...

* in command line/with input file:

.. code-block:: bash

    aitomic myinput.inp > output.out

Note: you can also use Aitomic exactly as MLatom by renaming aitomic folder to mlatom (or creating a symbolic link). Then you can do "import mlatom" as usual.

To test your implementation, you can run the calculations in the test subfolder provided with aitomic_pkg. Go to the aitomic_pkg/test/example folder and run:

.. code-block:: bash

    aitomic sp.inp > sp.out

If successful, you will see the same output as in aitomic_pkg/test/example_successful_output/sp.out provided for your reference.