.. _tutorial_re_explore:

Reaction exploration
====================

Generate transition states and reaction path
--------------------------------------------
One of the key steps in reaction exploration is to enumerate reaction steps. MLatom supports generating transition states as well as reaction paths given reactants and products with the state-of-the-art diffusion model ECTS:

- Xu M, Li B, Dong Z, Dral P, Zhu T, Chen H. ECTS: An ultra-fast diffusion model for exploring chemical reactions with equivariant consistency. ChemRxiv. 2025; doi:`10.26434/chemrxiv-2025-f9vdp <https://doi.org/10.26434/chemrxiv-2025-f9vdp>`_.

Prerequisites
+++++++++++++

- ``MLatom 3.18.0`` or later
- ``EcTs 1.0`` (Installation instructions can be found in https://github.com/AI4Reactions/ECTS. The required setting files in .json and models can also be there)


An example to generate TS 
+++++++++++++++++++++++++++++++

.. code::

    reactant = ml.data.molecule.from_xyz_file('./r.xyz')
    product = ml.data.molecule.from_xyz_file('./p.xyz')

    results = ml.simulations.gen_ts(
        reactant=reactant, product=product, program='ects',
        program_kwargs_json='./ts_kwargs.json',
        n_ts=8, avg_ts=True,
        working_directory='ects_ts'
    )
    
    generated_ts = results.ts 
    generated_avg_ts = results.avg_ts 


The returned ``generated_ts`` contain a list of sampled transition states with the same length as ``n_ts``. If ``avg_ts`` is set to ``True``, you can obtain the averaged transition state ``generated_avg_ts`` based on the all the samples. 


An example to generate reaction path
++++++++++++++++++++++++++++++++++++++++++

.. code::

    reactant = ml.data.molecule.from_xyz_file('./r.xyz')
    product = ml.data.molecule.from_xyz_file('./p.xyz')

    results = ml.simulations.gen_ts(
        reactant=reactant, product=product, program='ects',
        program_kwargs_json='./path_kwargs.json',
        path=True, n_path=8
        avg_ts=True,
        working_directory='ects_path')
    
    reaction_path = results.path 


The ``reaction_path`` contains a list of molecular database and each molecular database consists of one reaction path.


Related arguments
+++++++++++++++++

1. program related

- ``program [str]``: specify the program to use. Currently only `ects` is supported.
- ``program_kwargs [dict]``: the keywords to pass to program 
- ``program_kwargs_json [str]``: the json file to be loaded in to program. 
- ``working_dir [str]``: the path to save all the files

2. generation related 

- ``n_ts [int]``: number of transition state to be generated
- ``avg_ts [bool]``: whether to average the sampled transition states
- ``path [bool]``: setting to True will generate reaction path.
- ``n_path [int]``: number of reaction paths to be generated