.. _tutorial_dens:

DFT ensembles
===============================

DFT is widely used in physics, chemistry and materials science due to its decent balance between accuracy and computational cost. 

We are suggesting a novel approach of improving the accuracy of established DFT methods by making ensembles of them, see the paper for details:

    - Yuting Rui, Yuxinxin Chen, Elena Ivanova, Vignesh Balaji Kumar, Szymon Śmiga, Ireneusz Grabowski, Pavlo O. Dral. The best DFT functional is the ensemble of functionals. Adv. Sci. 2024, 11, 2408239. DOI: https://doi.org/10.1002/advs.202408239.

The usage of DFT ensembles is basically the same as that of :ref:`DFT in MLatom <tutorial_dft>` except for the keywords for the functional, which will be illustrated in the following section.

Defining DFT ensembles
-------------------------------------

.. note:: 
    
    Currently, the calculations can be only performed on the `XACS cloud computing <http://XACScloud.com>`__ with the open-source PySCF-based functionals. Instructions below also show how to perform simulations with Orca-based functionals but these will be released once the paper is published.

The available DFT ensembles are ``dens24pxN`` and ``dens24oxN`` as listed below:

====================== =========== =============================================
keywords of functional  program     range of N (number of functionals available)
====================== =========== =============================================
``dens24pxN``           PySCF       1~60
``dens24oxN``           Orca        1~28 
====================== =========== =============================================

where ``24`` denotes the year, ``p`` (or ``o``) the program it uses (``p`` for PySCF and ``o`` for ORCA) and ``N`` the number of functionals the DFT ensemble will use. For example, if you want to use an ensemble of 3 functionals supported by PySCF, the functional name would be ``dens24px3``.

The format for the keywords of DFT ensembles in MLatom follows the usual DFT conventions, i.e., ``[functional]/[basis set]``. For MLatom input file, the user just need to request the method in the first line. Here is an example how to use ``dens24px3`` for a single-point calculation:

.. code::

    dens24px3/def2-svp
    xyzfile='2

    1     0.0000    0.0000    0.0000
    1     0.7414    0.0000    0.0000
    '
    yestfile=enest.dat

For Python API, the DFT ensemble can be defined via ``mlatom.models.methods`` module with ``method`` arguments:

.. code::

    import mlatom as ml

    dens24 = ml.models.methods(method='dens24px3/def2-svp')
    #dens24 = ml.models.methods(method='dens24px3/def2-tzvp', nthreads=18)

``nthreads`` can be used to set number of CPUs used and by default all CPUs available on the machine will be used.

.. note::

    For a decent balance between time and accuracy, we recommend ``dens24px3`` functional as the practical tool on XACS cloud from our testing (also because only PySCF is available on the cloud). Users can also use ORCA, i.e., ``dens24ox3`` in the local version of MLatom in the future.


Any questions or suggestions?
-----------------------------

If you have further questions, criticism, and suggestions, we would be happy to receive them in English or Chinese via `email <xacs@xmu.edu.cn>`_, `Slack <https://join.slack.com/t/xacs-support/shared_invite/zt-1gm1lpn68-pReQhfYGu813eCqwmvdGvA>`_ (preferred), or WeChat (please send an email to request to add you to the XACS user support group).