Vibronic Coupling
_________________

Tools for analysing vibronic coupling effects.

Huang-Rhys factors
~~~~~~~~~~~~~~~~~~

The ``huang_rhys.py`` script is used for computing Huang-Rhys (HR) factors, which quantify the electron-phonon coupling between 
the ground and excited state geometries of a molecule along vibrational normal modes.
It also calculates the reorganization energy, representing the nuclear reconfiguration cost during electronic transitions.
The computed data are saved to an output file, which can be subsequently used as input for the ``fc_mini.py`` script.

To get detailed information about how to use this script, one can run the help command in the terminal:

.. code:: text

   huang_rhys.py -h

This command will display a comprehensive usage guide, including:

A brief description of the script’s purpose (computing Huang-Rhys parameters and reorganization energies).

Required Arguments: Ground state,  Excited-state geometry file, Selection of vibrational molden files for ground or excited state (-g or -e).

Other options: File format type (-t), Display options for top vibrational modes by Huang-Rhys factors or reorganization energies, plotting and saving output options.

.. code:: text

   usage: huang_rhys.py [-h] (-g GS_VIB | -e ES_VIB) [-t FILETYPE] [-s N] [-l N] [-p PNGFILE] gs_file es_file

   Compute Huang-Rhys parameters and reorganization energies.

   positional arguments:
    gs_file               Ground state geometry file (e.g., gs.xyz)
    es_file               Excited-state geometry file (e.g., es.xyz)


   options:
     -h, --help            show this help message and exit
     -g GS_VIB, --vib_gs GS_VIB
                        Ground-state vibrational Molden file (default)
     -e ES_VIB, --vib_es ES_VIB
                        Excited-state vibrational Molden file
     -t FILETYPE, --filetype FILETYPE
                        Filetype of structure files (default: xyz)
     -s N, --topS N        Show top N modes with highest Huang-Rhys factors
     -l N, --topLambda N   Show top N modes with highest reorganization energies
     -p PNGFILE, --plot PNGFILE
                        Plot Huang-Rhys spectrum and save to file

#NOTE: You are using excited-state vibrational modes (-e). If results seem unreasonable or unphysical, consider using ground-state modes (-g) instead, 
especially if excited-state frequencies are less reliable in your calculations.

Example 

.. code:: text

    huang_rhys.py GS.xyz ES.xyz -e freq.molden -s 10 -l 10 -p huang_rhys.png 


Franck-Condon Spectrum
~~~~~~~~~~~~~~~~~~~~~~

A Franck–Condon (FC) spectrum simulates the vibronic structure (combined electronic and vibrational transitions) of a molecule’s optical absorption or emission process.
The ``fc_mini.py`` script is used for simulating a vibronic (Franck–Condon) progression spectrum based on Huang–Rhys factors, 
using a Gaussian line shape to broaden the discrete transitions.

Before running this script, one need a file containing vibrational mode data hr.txt. 
This is generated by ``huang_rhys.py`` script.
This file should have at least three columns - Mode, Frequency and Huang-Rhys Factor.

Example

.. code:: text

    fc_mini.py hr.txt 

After launching the script, the user is prompted to select the type of spectrum and enter several parameters.

1. Select Spectrum Type
The script first asks whether to compute an absorption or emission spectrum:

.. code:: text

    Select mode: 1 = absorption (abs) or 2 = emission (emi)
    Enter 1 or 2:

Enter 1 for absorption or 2 for emission 

For absorption calculations, the oscillator strength is required.

.. code:: text

    Oscillator strength (dimensionless): 

2. Electronic adiabatic energy (in hartree) – energy gap between the equilibrium structures of ground and excited states.
3. w_min (in cm^-1) – minimum vibrational frequency to include.
4. S_min – minimum Huang–Rhys factor for mode inclusion.

``fc_mini.py`` computes Franck–Condon vibronic spectra for both absorption and emission, using vibrational frequencies and Huang–Rhys factors as input. 
The script interactively guides the user through parameter selection and produces both numerical data and plots.


Normal mode displacement
~~~~~~~~~~~~~~~~~~~~~~~~

Displace a molecular structure along a normal mode.

.. code:: text

    add_normal_mode.py <in_struc> <out_struc> <vib_file> <nm_ind> <disp> [<type>]