Universal and updatable AIQM models
=====================================================================

This tutorial will use the `MLatom program <http://MLatom.com>`__.

- :ref:`Slides <get_started_mlatom_slides>`
- :ref:`Geometry optimization <get_started_mlatom_geomopt>`

.. _get_started_mlatom_slides:

Slides
------

:download:`Slides <_static/mlatom/XACSW2024_20240702_Dral_wm.pdf>`:

.. raw:: html
    
    <embed src="_static/mlatom/XACSW2024_20240702_Dral_wm.pdf" width="741" height="310" aligh="left" type="application/pdf">

.. _get_started_mlatom_geomopt:

Geometry optimization
---------------------

We will get started by showcasing the power of ML to supercharge the computational chemistry simulations. We will use the most recent and advanced concept of performing simulations with the universal and updatable AI-enhanced quantum mechanical (UAIQM) models:

.. raw:: html

   <iframe src="https://player.bilibili.com/player.html?isOutside=true&aid=1205972334&bvid=BV1Zf421B7GB&cid=1597373556&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" height=500 width=800></iframe>

Let's say you want to optimize the molecular geometry. Now you do not need to worry which method (DFT or *ab initio*, etc.) to choose: MLatom will choose the best model automatically for you.

.. admonition:: Example 1.

    The input is simple:

    .. code-block:: 

        UAIQM
        geomopt
        xyzfile='5
        
        C         0.0000000000        0.0000000000        0.0000000000
        H         1.0870000000        0.0000000000        0.0000000000
        H        -0.3623333220       -1.0248334322       -0.0000000000
        H        -0.3623333220        0.5124167161       -0.8875317869
        H        -0.3623333220        0.5124167161        0.8875317869
        ' 

    In the output file, you will get the information which UAIQM model was selected:

    .. code-block::

        Selected UAIQM method: uaiqm_gfn2xtbstar@cc
        Selected version: 20240106

    It is much nicer to use MLaton as a Python package, and Jupyter notebooks make it also easy to use if you do not know Python.
    The connoisseurs of Python can get much more flexibility when using MLatom.
    Here is the same example as above, but in Python (:download:`uaiqm_geomopt.ipynb <_static/get_started/uaiqm_geomopt.ipynb>`), which you can use after you launch the Jupyter Lab on the `Aitomistic Lab@XMU <https://atom.xmu.edu.cn/>`__.

    .. raw:: html
        :file: _static/get_started/uaiqm_geomopt.html

You can check the model's composition `online <http://mlatom.com/docs/tutorial_uaiqm.html#uaiqm-library>`__.

If your molecule happened to be neutral and closed shell and only contain the CHNO elements, UAIQM will give you the CCSD(T)/CBS-level result but at a very fast speed (usually even faster than DFT).

The MLatom output ``.log`` file will contain information about the optimization iterations and print out the final optimized geometry, which you can also find in the ``optgeoms.xyz``.

Note that same kind of input works for other, QM and ML, methods, e.g. for DFT:

.. admonition:: Example 2.

    .. code-block:: 

        # example for DFT:
        B3LYP/6-31G*
        # example for ab initio:
        # CCSD(T)/cc-pVDZ
        # example for very fast universal ML model (also approaching CCSD(T)/CBS):
        # ANI-1ccx
        geomopt
        xyzfile='5
        
        C         0.0000000000        0.0000000000        0.0000000000
        H         1.0870000000        0.0000000000        0.0000000000
        H        -0.3623333220       -1.0248334322       -0.0000000000
        H        -0.3623333220        0.5124167161       -0.8875317869
        H        -0.3623333220        0.5124167161        0.8875317869
        '

    or in Python:

    .. code-block:: python

        import mlatom as ml

        # Get the initial guess for the molecules to optimize
        initmol = ml.data.molecule.from_xyz_string('''5

        C         0.0000000000        0.0000000000        0.0000000000
        H         1.0870000000        0.0000000000        0.0000000000
        H        -0.3623333220       -1.0248334322       -0.0000000000
        H        -0.3623333220        0.5124167161       -0.8875317869
        H        -0.3623333220        0.5124167161        0.8875317869
        ''')

        # define DFT method
        b3lyp = ml.models.methods(method='B3LYP/6-31G*')

        # Optimize the geometry with the choosen optimizer:
        geomopt = ml.optimize_geometry(model=b3lyp, initial_molecule=initmol, program='geometric')

        # Get the final geometry
        final_mol = geomopt.optimized_molecule
        # and its XYZ coordinates
        print('\nOptimized coordinates\n')
        print(final_mol.get_xyz_string())

        # save the final geometry
        final_mol.write_file_with_xyz_coordinates(filename='final.xyz')

        # View the molecule
        final_mol.view()

You can play with these different options.

Since MLatom is a data-drive package, the optimization trajectory is also saved in the json format, i.e., you will find files like ``opttraj.json`` (it is also available in XYZ format for convenience: ``opttraj.xyz``).

For more options on how to use MLatom for geometry optimizations, you can check out the `dedicated tutorial <http://mlatom.com/docs/tutorial_geomopt.html>`__. For example, you can use MLatom for the `optimization with constraints <http://mlatom.com/docs/tutorial_geomopt.html#optimization-with-constraints>`__ too.

The power of MLatom is that you can use different ML models to do many types of simulations, including geometry optimization as we will see in the :ref:`basics of ML <ml-basics>`.

.. include:: outdating.rst