.. _tutorial_es_methods:

Methods for excited states
==========================================

Here we briefly overview the electronic structure methods supported by MLatom via interfaces:

- TDDFT and TDA via interface to PySCF.
- TDDFT via interface to Gaussian.
- :ref:`AIQM1 <tutorial_aiqm1>` and other semi-empirical QM methods implemented in the :ref:`MNDO <install_MNDO>` program. The excited-state properties can be calculated with fast CIS or slow MR-CI approaches with the above Hamiltonians. Note that AIQM1 also requires installation of :ref:`TorchANI <install_TorchANI>` and :ref:`dftd4 <install_dftd4>` programs.
- CASSCF via the interface to :ref:`COLUMBUS <install_COLUMBUS>`.
- ADC(2) via interface to :ref:`Turbomole <install_Turbomole>`.

These methods support calculations of various excited-state properties such as energies, forces, oscillator strengths, and, often, nonadiabatic couplings.

.. note:

    Only TDDFT and TDA through interface to PySCF are provided on the Aitomistic cloud platforms due to the license restrictions of other programs.

Example
-------

An example below shows how to define an excited-state method and use it for single-point calculations. Here, we use an interfce to Gaussian to perform TD-DFT calculations. To request such calculations, simply add 'TD- to your DFT functional, i.e., `B3LYP` will not work, but `TD-B3LYP` will work. If you need to define a solvent or add any other keywords to the input, you can do it by passing them to the `method` argument together with your TD-DFT keyword. Example below shows how to extract excitation energies and oscillator strengths. You can use the method instance you have setup (below `b3lyp` variable) to do other simulations as usual, e.g., :ref:`geometry optimization <tutorial-geomopt>`, :ref:`molecular dynamics <tutorial_md>`, and calculate and plot :ref:`UV/vis spectra <tutorial_uvvis>`.

.. code-block:: python

    import mlatom as ml

    mol = ml.molecule.from_xyz_string('''3

    O             0.0047037000647           0.0034825819509          -0.0024602018358
    H             0.2765387552084           0.8860394374343           0.2512345704190
    H             0.6029575451964          -0.2349220208587          -0.7112743681126
    ''')
    b3lyp = ml.methods(method='TD-B3LYP/6-31G* SCRF(CPCM, Solvent=Acetonitrile)', program='gaussian', save_files_in_current_directory=True)
    b3lyp.predict(molecule=mol, nstates=3, current_state=1) # making predictions for 3 states (S0, S1, and S2) and calculating properties (energies & gradients, population analysis) for S1 (numbering of states from 0).
    print(mol.excitation_energies * ml.constants.hartree2eV) # they are in hartree, so here we convert to eV for convenience
    print(mol.oscillator_strengths)

Citation
--------

See our paper for more details (please also cite it if you use the corresponding features):

- Lina Zhang, Sebastian Pios, Mikołaj Martyka, Fuchun Ge, Yi-Fan Hou, Yuxinxin Chen, Joanna Jankowska, Lipeng Chen, Mario Barbatti, `Pavlo O. Dral <http://dr-dral.com>`__. `MLatom software ecosystem for surface hopping dynamics in Python with quantum mechanical and machine learning methods <https://doi.org/10.1021/acs.jctc.4c00468>`__. *J. Chem. Theory Comput.* **2024**, *20*, 5043--5057. DOI: 10.1021/acs.jctc.4c00468. Preprint on *arXiv*: https://arxiv.org/abs/2404.06189.