2. System modelling

CONTROL LAUNCHER begins by modelling the system on which the control procedure will be performed. In order to do so, it must parse the source file to extract all the needed values from it and build the Matrix Image of the MoleculE (MIME), as well as the transition dipole moments matrix. The MIME can act as an effective Hamiltonian describing the molecule. Once it has been determined, it is then diagonalized in order to build the eigenstates basis set needed by QOCT-GRAD to perform the control procedure.

2.1. Parsing the source file

While CONTROL LAUNCHER parses the source file, it is looking for various information about the molecule, depending on what type of control is to be performed. What this parsing does and how it works is defined by a function present in the modelling_fcts.py file, called a parsing function. The only argument this function needs is the content of the source file, stored as a list in the source_content variable (each element of the list corresponds to a line of the file).

2.1.1. General definition of the parsing functions

All the parsing functions are defined in the modelling_fcts.py file and obey some restrictions, in order to be callable by CONTROL LAUNCHER:

  • They must only take one argument: a list containing the lines of the source file (source_content).

  • They must return a dictionary (system) containing two mandatory keys: mime and momdip_mtx (you can have additional keys if you want) where:

    • mime is the Matrix Image of the MoleculE, acting as an effective Hamiltonian. The diagonal elements are the energy values of the states and the non-diagonal values are the coupling elements between those states. Those values must be expressed in atomic units of energy (Hartree).

    • momdip_mtx is the transition dipole moments matrix containing the transition dipole moments between the states. Those values must be expressed in atomic units.

The values for system’s two keys can either be NumPy 2D-arrays or a simple list of lists, depending on your preferences.

If a problem arises when parsing the source file, a ControlError exception should be raised with a proper error message (see how to handle errors for more details).

2.1.2. Choosing a parsing function

The parsing function that will be called by CONTROL LAUNCHER is the one associated with the parsing_function YAML key defined in the clusters configuration file:

mycluster:
   profiles:
      myprofile1:
         parsing_function: name-of-parsing-function
      myprofile2:
         parsing_function: name-of-parsing-function

where mycluster corresponds to the name of your cluster (given as a command line argument) while myprofile1 and myprofile2 are the names of the profiles you want to use (such as chains_qoctra). This way, a different parsing function can be assigned to each profile.

2.1.3. Convert energy units

Since the mime values need to be expressed in Hartree, a small function named energy_unit_conversion has been added at the beginning of the modelling_fcts.py file to help you convert energy units:

This function works by first converting the value from the init unit to Hartree, then converting it from Hartree to the target unit.

As an example, let’s say we want to convert 50 eV into Hz, we can simply use:

value_hz = energy_unit_conversion(50,"eV","Hz")

which gives us ~1.209e+16 Hz. If you simply want the value in Hartree, just use "Ha" as the target unit (which would give ~1.837 Ha in this case).

If you want to add support for another unit, simply add the conversion factor from Hartree to that unit to the conv_factors dictionary defined in the function. Note that the unit labels are case insensitive.

2.1.4. Q-CHEM TDDFT parsing function

This parsing function uses a Q-CHEM TD-DFT calculation output as the source file. Note that the ground state of the calculation must be a singlet, otherwise this function will need to be slightly modified.

2.1.4.1. Structure of the Q-CHEM output file

As an example, let’s consider here a TD-DFT calculation of the H2O molecule, focused on four excited triplet states and four excited singlet states. The output file is quite lengthy so we will only focus on the relevant parts in this subsection, where the lines containing the needed information are emphasized. The whole file can however be consulted here.

The first part of interest is the list of the excited electronic states and their excitation energies. (click on the arrow below to see this portion of the output file.)

h2o.out - TDDFT/TDA Excitation Energies
 ---------------------------------------------------
         TDDFT/TDA Excitation Energies              
 ---------------------------------------------------

 Excited state   1: excitation energy (eV) =    5.1669
 Total energy for state  1:                   -76.16715634 au
    Multiplicity: Triplet
    Trans. Mom.:  0.0000 X   0.0000 Y   0.0000 Z
    Strength   :     0.0000000000
    D(    5) --> V(    1) amplitude =  0.9982

 Excited state   2: excitation energy (eV) =    6.0765
 Total energy for state  2:                   -76.13372898 au
    Multiplicity: Singlet
    Trans. Mom.:  0.1591 X   0.0000 Y  -0.0000 Z
    Strength   :     0.0037677982
    D(    5) --> V(    1) amplitude =  0.9992

 Excited state   3: excitation energy (eV) =    6.9584
 Total energy for state  3:                   -76.10131974 au
    Multiplicity: Triplet
    Trans. Mom.:  0.0000 X   0.0000 Y   0.0000 Z
    Strength   :     0.0000000000
    D(    4) --> V(    1) amplitude =  0.9834

 Excited state   4: excitation energy (eV) =    7.0964
 Total energy for state  4:                   -76.09624682 au
    Multiplicity: Triplet
    Trans. Mom.:  0.0000 X   0.0000 Y   0.0000 Z
    Strength   :     0.0000000000
    D(    5) --> V(    2) amplitude =  0.9980

 Excited state   5: excitation energy (eV) =    7.8295
 Total energy for state  5:                   -76.06930672 au
    Multiplicity: Singlet
    Trans. Mom.: -0.0387 X   0.0000 Y  -0.0000 Z
    Strength   :     0.0002868084
    D(    5) --> V(    2) amplitude =  0.9990

 Excited state   6: excitation energy (eV) =    8.6463
 Total energy for state  6:                   -76.03928870 au
    Multiplicity: Triplet
    Trans. Mom.:  0.0000 X   0.0000 Y   0.0000 Z
    Strength   :     0.0000000000
    D(    3) --> V(    1) amplitude =  0.4719
    D(    4) --> V(    2) amplitude =  0.8726

 Excited state   7: excitation energy (eV) =    9.0470
 Total energy for state  7:                   -76.02456327 au
    Multiplicity: Singlet
    Trans. Mom.: -0.0000 X   0.4219 Y   0.5281 Z
    Strength   :     0.1012770585
    D(    3) --> V(    2) amplitude = -0.2857
    D(    4) --> V(    1) amplitude =  0.9481

 Excited state   8: excitation energy (eV) =   10.5648
 Total energy for state  8:                   -75.96878617 au
    Multiplicity: Singlet
    Trans. Mom.:  0.0000 X  -0.2156 Y   0.0714 Z
    Strength   :     0.0133563830
    D(    3) --> V(    1) amplitude = -0.5409
    D(    4) --> V(    2) amplitude =  0.8351
 
 ---------------------------------------------------
  SETman timing summary (seconds)
  CPU time                 1.39s
  System time              0.00s
  Wall time                0.73s

Next comes the spin-orbit couplings between those excited states (and the ground state). (click on the arrow below to see this portion of the output file.)

h2o.out - Spin-orbit Couplings
*********SPIN-ORBIT COUPLING JOB BEGINS HERE*********


=======================================================================================
    SPIN-ORBIT COUPLING BETWEEN THE SINGLET GROUND STATE AND EXCITED TRIPLET STATE
=======================================================================================

SOC between the singlet ground state and excited triplet states (ms=0):
T1(ms=0)      0.000000  +  -44.677284i    cm-1
T2(ms=0)      0.000000  +  -0.000000i    cm-1
T3(ms=0)      0.000000  +  78.913890i    cm-1
T4(ms=0)      0.000000  +  0.000000i    cm-1
SOC between the singlet ground state and excited triplet states (ms=1):
T1(ms=1)      48.878430  + (-0.000000i)    cm-1
T2(ms=1)      -0.000000  + (-7.605108i)    cm-1
T3(ms=1)      44.133355  + (-0.000000i)    cm-1
T4(ms=1)      0.000000  + (-28.173176i)    cm-1
SOC between the singlet ground state and excited triplet states (ms=-1):
T1(ms=-1)     48.878430  - (-0.000000i)    cm-1
T2(ms=-1)     -0.000000  - (-7.605108i)    cm-1
T3(ms=-1)     44.133355  - (-0.000000i)    cm-1
T4(ms=-1)     0.000000  - (-28.173176i)    cm-1
Total SOC between the singlet ground state and excited triplet states:
T1      82.305902    cm-1
T2      10.755247    cm-1
T3      100.612664    cm-1
T4      39.842887    cm-1




=======================================================================================
                     SPIN-ORBIT COUPLING BETWEEN EXCITED TRIPLET STATES
=======================================================================================

SOC between the T1 (ms=0) state and excited triplet states (ms=1):
T2(ms=1)      43.769237  + (-0.000000i)    cm-1
T3(ms=1)      0.000000  + (30.702888i)    cm-1
T4(ms=1)      14.498245  + (-0.000000i)    cm-1
SOC between the T1 (ms=0) state and excited triplet states (ms=-1):
T2(ms=-1)     -43.769237  + (-0.000000i)    cm-1
T3(ms=-1)     -0.000000  + (30.702888i)    cm-1
T4(ms=-1)     -14.498245  + (-0.000000i)    cm-1
SOC between the T1 (ms=1) state and excited triplet states (ms=0):
T2(ms=0)      -43.769237  + (-0.000000i)    cm-1
T3(ms=0)      -0.000000  + (30.702888i)    cm-1
T4(ms=0)      -14.498245  + (-0.000000i)    cm-1
SOC between the T1 (ms=1) state and excited triplet states (ms=1):
T2(ms=1)      0.000000  + (-50.273623i)    cm-1
T3(ms=1)      0.000000  + (-0.000000i)    cm-1
T4(ms=1)      0.000000  + (29.933381i)    cm-1
SOC between the T1 (ms=-1) state and excited triplet states (ms=0):
T2(ms=0)      43.769237  + (-0.000000i)    cm-1
T3(ms=0)      0.000000  + (30.702888i)    cm-1
T4(ms=0)      14.498245  + (-0.000000i)    cm-1
SOC between the T1 (ms=-1) state and excited triplet states (ms=-1):
T2(ms=-1)     0.000000  + (50.273623i)    cm-1
T3(ms=-1)     0.000000  + (0.000000i)    cm-1
T4(ms=-1)     0.000000  + (-29.933381i)    cm-1
Total SOC between the T1 state and excited triplet states:
T2      112.773484    cm-1
T3      61.405776    cm-1
T4      51.310925    cm-1



SOC between the T2 (ms=0) state and excited triplet states (ms=1):
T3(ms=1)      -6.297781  + (0.000000i)    cm-1
T4(ms=1)      -0.000000  + (8.835057i)    cm-1
SOC between the T2 (ms=0) state and excited triplet states (ms=-1):
T3(ms=-1)     6.297781  + (0.000000i)    cm-1
T4(ms=-1)     0.000000  + (8.835057i)    cm-1
SOC between the T2 (ms=1) state and excited triplet states (ms=0):
T3(ms=0)      6.297781  + (0.000000i)    cm-1
T4(ms=0)      0.000000  + (8.835057i)    cm-1
SOC between the T2 (ms=1) state and excited triplet states (ms=1):
T3(ms=1)      0.000000  + (-5.361951i)    cm-1
T4(ms=1)      0.000000  + (0.000000i)    cm-1
SOC between the T2 (ms=-1) state and excited triplet states (ms=0):
T3(ms=0)      -6.297781  + (0.000000i)    cm-1
T4(ms=0)      -0.000000  + (8.835057i)    cm-1
SOC between the T2 (ms=-1) state and excited triplet states (ms=-1):
T3(ms=-1)     0.000000  + (5.361951i)    cm-1
T4(ms=-1)     0.000000  + (-0.000000i)    cm-1
Total SOC between the T2 state and excited triplet states:
T3      14.702013    cm-1
T4      17.670113    cm-1



SOC between the T3 (ms=0) state and excited triplet states (ms=1):
T4(ms=1)      34.139589  + (0.000000i)    cm-1
SOC between the T3 (ms=0) state and excited triplet states (ms=-1):
T4(ms=-1)     -34.139589  + (0.000000i)    cm-1
SOC between the T3 (ms=1) state and excited triplet states (ms=0):
T4(ms=0)      -34.139589  + (0.000000i)    cm-1
SOC between the T3 (ms=1) state and excited triplet states (ms=1):
T4(ms=1)      0.000000  + (-51.118247i)    cm-1
SOC between the T3 (ms=-1) state and excited triplet states (ms=0):
T4(ms=0)      34.139589  + (0.000000i)    cm-1
SOC between the T3 (ms=-1) state and excited triplet states (ms=-1):
T4(ms=-1)     0.000000  + (51.118247i)    cm-1
Total SOC between the T3 state and excited triplet states:
T4      99.439411    cm-1







=======================================================================================
         SPIN-ORBIT COUPLING BETWEEN EXCITED SINGLET STATES AND TRIPLET STATES
=======================================================================================

SOC between the S1 state and excited triplet states (ms=0):
T1(ms=0)      0.000000  +  0.000000i    cm-1
T2(ms=0)      0.000000  +  -50.307450i    cm-1
T3(ms=0)      0.000000  +  -0.000000i    cm-1
T4(ms=0)      0.000000  +  30.205761i    cm-1
SOC between the S1 state and excited triplet states (ms=1):
T1(ms=1)      (0.000000)  + (-0.171651i)    cm-1
T2(ms=1)      (-43.914779)  + (-0.000000i)    cm-1
T3(ms=1)      (-0.000000)  + (29.840963i)    cm-1
T4(ms=1)      (-14.912585)  + (0.000000i)    cm-1
SOC between the S1 state and excited triplet states (ms=-1):
T1(ms=-1)    -(0.000000)  + (-0.171651i)    cm-1
T2(ms=-1)    -(-43.914779)  + (-0.000000i)    cm-1
T3(ms=-1)    -(-0.000000)  + (29.840963i)    cm-1
T4(ms=-1)    -(-14.912585)  + (0.000000i)    cm-1
Total SOC between the S1 state and excited triplet states:
T1      0.242751    cm-1
T2      79.924059    cm-1
T3      42.201494    cm-1
T4      36.839630    cm-1



SOC between the S2 state and excited triplet states (ms=0):
T1(ms=0)      0.000000  +  0.000000i    cm-1
T2(ms=0)      0.000000  +  5.260747i    cm-1
T3(ms=0)      0.000000  +  0.000000i    cm-1
T4(ms=0)      0.000000  +  -51.592528i    cm-1
SOC between the S2 state and excited triplet states (ms=1):
T1(ms=1)      (0.000000)  + (-29.815912i)    cm-1
T2(ms=1)      (-5.876476)  + (-0.000000i)    cm-1
T3(ms=1)      (-0.000000)  + (-0.128402i)    cm-1
T4(ms=1)      (-34.188511)  + (0.000000i)    cm-1
SOC between the S2 state and excited triplet states (ms=-1):
T1(ms=-1)    -(0.000000)  + (-29.815912i)    cm-1
T2(ms=-1)    -(-5.876476)  + (-0.000000i)    cm-1
T3(ms=-1)    -(-0.000000)  + (-0.128402i)    cm-1
T4(ms=-1)    -(-34.188511)  + (0.000000i)    cm-1
Total SOC between the S2 state and excited triplet states:
T1      42.166067    cm-1
T2      9.835720    cm-1
T3      0.181588    cm-1
T4      70.707125    cm-1



SOC between the S3 state and excited triplet states (ms=0):
T1(ms=0)      0.000000  +  60.527241i    cm-1
T2(ms=0)      0.000000  +  -0.000000i    cm-1
T3(ms=0)      0.000000  +  11.674671i    cm-1
T4(ms=0)      0.000000  +  -0.000000i    cm-1
SOC between the S3 state and excited triplet states (ms=1):
T1(ms=1)      (35.779788)  + (0.000000i)    cm-1
T2(ms=1)      (0.000000)  + (10.917196i)    cm-1
T3(ms=1)      (-10.477856)  + (0.000000i)    cm-1
T4(ms=1)      (0.000000)  + (57.507112i)    cm-1
SOC between the S3 state and excited triplet states (ms=-1):
T1(ms=-1)    -(35.779788)  + (0.000000i)    cm-1
T2(ms=-1)    -(0.000000)  + (10.917196i)    cm-1
T3(ms=-1)    -(-10.477856)  + (0.000000i)    cm-1
T4(ms=-1)    -(0.000000)  + (57.507112i)    cm-1
Total SOC between the S3 state and excited triplet states:
T1      78.891910    cm-1
T2      15.439246    cm-1
T3      18.864487    cm-1
T4      81.327337    cm-1



SOC between the S4 state and excited triplet states (ms=0):
T1(ms=0)      0.000000  +  29.204821i    cm-1
T2(ms=0)      0.000000  +  -0.000000i    cm-1
T3(ms=0)      0.000000  +  41.456284i    cm-1
T4(ms=0)      0.000000  +  0.000000i    cm-1
SOC between the S4 state and excited triplet states (ms=1):
T1(ms=1)      (-20.412740)  + (0.000000i)    cm-1
T2(ms=1)      (-0.000000)  + (1.392102i)    cm-1
T3(ms=1)      (37.555272)  + (-0.000000i)    cm-1
T4(ms=1)      (-0.000000)  + (-6.169170i)    cm-1
SOC between the S4 state and excited triplet states (ms=-1):
T1(ms=-1)    -(-20.412740)  + (0.000000i)    cm-1
T2(ms=-1)    -(-0.000000)  + (1.392102i)    cm-1
T3(ms=-1)    -(37.555272)  + (-0.000000i)    cm-1
T4(ms=-1)    -(-0.000000)  + (-6.169170i)    cm-1
Total SOC between the S4 state and excited triplet states:
T1      41.064358    cm-1
T2      1.968729    cm-1
T3      67.375221    cm-1
T4      8.724524    cm-1






            *********SOC CODE ENDS HERE*********

And finally, the transition dipole moments between those electronic states. (click on the arrow below to see this portion of the output file.)

h2o.out - Transition dipole moments
                    STATE-TO-STATE TRANSITION MOMENTS


    Electron Dipole Moments of Ground State
 -----------------------------------------------------
   State     X           Y           Z(a.u.) 
 -----------------------------------------------------
       0     0.000000    1.300841    0.947111
 -----------------------------------------------------

 Within CIS/TDA Excited States:

    Electron Dipole Moments of Triplet Excited State
 -----------------------------------------------------
   State     X           Y           Z(a.u.) 
 -----------------------------------------------------
       1     0.000000    1.895546    2.164075
       3     0.000000    1.823154    2.122535
       4     0.000000    2.445870    1.472994
       6     0.000000    2.368149    1.372921
 -----------------------------------------------------

                Transition Moments Between Ground and Triplet Excited States
 --------------------------------------------------------------------------------
    States   X          Y          Z           Strength(a.u.)
 --------------------------------------------------------------------------------
    0    1   0.000000   0.000000   0.000000              0
    0    3   0.000000   0.000000   0.000000              0
    0    4   0.000000   0.000000   0.000000              0
    0    6   0.000000   0.000000   0.000000              0
 --------------------------------------------------------------------------------

                Transition Moments Between Triplet Excited States
 --------------------------------------------------------------------------------
    States   X          Y          Z           Strength(a.u.)
 --------------------------------------------------------------------------------
    1    3   0.141759   0.000000  -0.000000   0.0008820152
    1    4   0.000000  -1.067329   1.011496      0.1022192
    1    6  -0.018428   0.000000   0.000000   2.894918E-05
    3    4   0.005304  -0.000000   0.000000   9.515553E-08
    3    6  -0.000000  -0.835833   0.726613     0.05072422
    4    6   0.136187  -0.000000   0.000000   0.0007042604
 --------------------------------------------------------------------------------

 Within CIS/TDA Excited States:

    Electron Dipole Moments of Singlet Excited State
 -----------------------------------------------------
   State     X           Y           Z(a.u.) 
 -----------------------------------------------------
       2     0.000000    1.903150    2.203818
       5     0.000000    2.481787    1.473044
       7     0.000000    1.896353    2.145199
       8     0.000000    2.362852    1.364006
 -----------------------------------------------------

                Transition Moments Between Ground and Singlet Excited States
 --------------------------------------------------------------------------------
    States   X          Y          Z           Strength(a.u.)
 --------------------------------------------------------------------------------
    0    2   0.159088   0.000000  -0.000000    0.003767798
    0    5  -0.038668   0.000000  -0.000000   0.0002868084
    0    7  -0.000000   0.421885   0.528148      0.1012771
    0    8   0.000000  -0.215642   0.071420     0.01335638
 --------------------------------------------------------------------------------

                Transition Moments Between Singlet Excited States
 --------------------------------------------------------------------------------
    States   X          Y          Z           Strength(a.u.)
 --------------------------------------------------------------------------------
    2    5   0.000000  -1.089808   1.028835     0.09646942
    2    7   0.164346   0.000000   0.000000    0.001965671
    2    8   0.002864  -0.000000  -0.000000   9.020868E-07
    5    7  -0.004680   0.000000  -0.000000   6.534342E-07
    5    8   0.113103  -0.000000   0.000000   0.0008572624
    7    8   0.000000  -1.226098   1.179333       0.107618
 --------------------------------------------------------------------------------

                    END OF TRANSITION MOMENT CALCULATION

 STSman time:  CPU 0.00 s  wall 0.00 s

2.1.4.2. Function definition

modelling_fcts.qchem_tddft(source_content: list)[source]

Parses the content of a Q-CHEM SOC TD-DFT calculation output file, looking to build the non-relavistic MIME and the non-relavistic transition dipole moments matrices of the molecule. It then diagonalizes the MIME to build the eigenstates basis set (relativistic states) and convert the dipole moments matrices into this new basis set.

Parameters:

source_content (list) – Content of the Q-CHEM output file. Each element of the list is a line of the file.

Returns:

system – The extracted information of the source file. It contains the two mandatory keys and their associated values: states_list and momdip_mtx where

  • states_list is a list of dictionaries containing three keys each: energy, number and label where

    • energy is the excitation energy of the relativistic state, in Ha.

    • number is the number of the state in an increasing order of energy, starting at 0 (which is the ground state).

    • label is the label of the state, in the form of “E” + number of that state.

  • momdip_mtx is a dictionary containing three keys and their associated values:

    • X is a NumPy array representing the relativistic transition dipole moments matrix along the X axis (in atomic units).

    • Y is a NumPy array representing the relativistic transition dipole moments matrix along the Y axis (in atomic units).

    • Z is a NumPy array representing the relativistic transition dipole moments matrix along the Z axis (in atomic units).

It also contains two additional keys and their associated values that will be used by the rendering function: eigenvectors, eigenvectors_inv where

  • eigenvectors is a NumPy array, containing the eigenvectors of the eigenstates in its columns.

  • eigenvectors_inv is the inverse of the eigenvectors matrix, containing the eigenvectors of the eigenstates in its lines.

It also contains three additional keys and their associated values that will be used by another script: zero_states_list, mime and momdip_o_mtx where

  • zero_states_list is a list of dictionaries containing four keys each: number, type, label and energy where

    • number is the number of the non-relativistic state, starting at 0 (which is the ground state).

    • type reflects the selection rule for transitions going from the ground state to this state, i.e. either “Bright” or “Dark”.

    • energy is the excitation energy of the state, in Ha.

    • label is the label of the state, in the form of the first letter of its multiplicity + number of that state of this multiplicity (e.g. T1 for the first triplet, S3 for the third singlet, …).

  • mime is a NumPy array, representing the Matrix Image of the MoleculE which acts as an effective Hamiltonian. It contains the excitation energies on the diagonal elements, and the spin-orbit couplings on the non-diagonal elements (in Hartree).

  • momdip_o_mtx is a dictionary containing three keys and their associated values:

    • X is a NumPy array representing the transition dipole moments matrix along the X axis (in atomic units).

    • Y is a NumPy array representing the transition dipole moments matrix along the Y axis (in atomic units).

    • Z is a NumPy array representing the transition dipole moments matrix along the Z axis (in atomic units).

Return type:

dict

Raises:

ControlError – If some of the needed values are missing or unknown.

The first noticeable thing is that the system dictionary returned by this function contains an additional key: states_list. While this key is not explicitly needed by CONTROL LAUNCHER, it contains useful information that can be used, for example, by a transition function.

The way this function works is by making heavy use of regular expressions. It detects the beginning and the end of each of the three portions presented above and process their content, picking the relevant values and converting them to atomic units if needed.

Example with the H2O output file:

Parsing the excited states ...                   [ DONE ]

--------------------------------------------------
                  States List
--------------------------------------------------
Number     Multiplicity    Energy (cm-1)   Label
--------------------------------------------------
0          Singlet         0.000           S0
1          Triplet         41673.859       T1
2          Singlet         49010.278       S1
3          Triplet         56123.281       T2
4          Triplet         57236.326       T3
5          Singlet         63149.176       S2
6          Triplet         69737.113       T4
7          Singlet         72968.976       S3
8          Singlet         85210.859       S4
--------------------------------------------------

Parsing the spin-orbit couplings ...             [ DONE ]

Building the MIME ...                            [ DONE ]

MIME (cm-1)

0.00000e+00  8.23059e+01  0.00000e+00  1.07552e+01  1.00613e+02  0.00000e+00  3.98429e+01  0.00000e+00  0.00000e+00
8.23059e+01  4.16739e+04  2.42751e-01  1.12773e+02  6.14058e+01  4.21661e+01  5.13109e+01  7.88919e+01  4.10644e+01
0.00000e+00  2.42751e-01  4.90103e+04  7.99241e+01  4.22015e+01  0.00000e+00  3.68396e+01  0.00000e+00  0.00000e+00
1.07552e+01  1.12773e+02  7.99241e+01  5.61233e+04  1.47020e+01  9.83572e+00  1.76701e+01  1.54392e+01  1.96873e+00
1.00613e+02  6.14058e+01  4.22015e+01  1.47020e+01  5.72363e+04  1.81588e-01  9.94394e+01  1.88645e+01  6.73752e+01
0.00000e+00  4.21661e+01  0.00000e+00  9.83572e+00  1.81588e-01  6.31492e+04  7.07071e+01  0.00000e+00  0.00000e+00
3.98429e+01  5.13109e+01  3.68396e+01  1.76701e+01  9.94394e+01  7.07071e+01  6.97371e+04  8.13273e+01  8.72452e+00
0.00000e+00  7.88919e+01  0.00000e+00  1.54392e+01  1.88645e+01  0.00000e+00  8.13273e+01  7.29690e+04  0.00000e+00
0.00000e+00  4.10644e+01  0.00000e+00  1.96873e+00  6.73752e+01  0.00000e+00  8.72452e+00  0.00000e+00  8.52109e+04

MIME (Ha)

0.00000e+00  3.75013e-04  0.00000e+00  4.90045e-05  4.58425e-04  0.00000e+00  1.81538e-04  0.00000e+00  0.00000e+00
3.75013e-04  1.89880e-01  1.10605e-06  5.13834e-04  2.79785e-04  1.92123e-04  2.33790e-04  3.59458e-04  1.87103e-04
0.00000e+00  1.10605e-06  2.23307e-01  3.64161e-04  1.92284e-04  0.00000e+00  1.67854e-04  0.00000e+00  0.00000e+00
4.90045e-05  5.13834e-04  3.64161e-04  2.55716e-01  6.69873e-05  4.48148e-05  8.05110e-05  7.03464e-05  8.97019e-06
4.58425e-04  2.79785e-04  1.92284e-04  6.69873e-05  2.60788e-01  8.27376e-07  4.53079e-04  8.59529e-05  3.06984e-04
0.00000e+00  1.92123e-04  0.00000e+00  4.48148e-05  8.27376e-07  2.87729e-01  3.22165e-04  0.00000e+00  0.00000e+00
1.81538e-04  2.33790e-04  1.67854e-04  8.05110e-05  4.53079e-04  3.22165e-04  3.17746e-01  3.70555e-04  3.97519e-05
0.00000e+00  3.59458e-04  0.00000e+00  7.03464e-05  8.59529e-05  0.00000e+00  3.70555e-04  3.32471e-01  0.00000e+00
0.00000e+00  1.87103e-04  0.00000e+00  8.97019e-06  3.06984e-04  0.00000e+00  3.97519e-05  0.00000e+00  3.88249e-01

Parsing the transition dipole moments ...        [ DONE ]

Dipole moments matrix (atomic units)

0.00000e+00  0.00000e+00  3.76780e-03  0.00000e+00  0.00000e+00  2.86808e-04  0.00000e+00  1.01277e-01  1.33564e-02
0.00000e+00  0.00000e+00  0.00000e+00  8.82015e-04  1.02219e-01  0.00000e+00  2.89492e-05  0.00000e+00  0.00000e+00
3.76780e-03  0.00000e+00  0.00000e+00  0.00000e+00  0.00000e+00  9.64694e-02  0.00000e+00  1.96567e-03  9.02087e-07
0.00000e+00  8.82015e-04  0.00000e+00  0.00000e+00  9.51555e-08  0.00000e+00  5.07242e-02  0.00000e+00  0.00000e+00
0.00000e+00  1.02219e-01  0.00000e+00  9.51555e-08  0.00000e+00  0.00000e+00  7.04260e-04  0.00000e+00  0.00000e+00
2.86808e-04  0.00000e+00  9.64694e-02  0.00000e+00  0.00000e+00  0.00000e+00  0.00000e+00  6.53434e-07  8.57262e-04
0.00000e+00  2.89492e-05  0.00000e+00  5.07242e-02  7.04260e-04  0.00000e+00  0.00000e+00  0.00000e+00  0.00000e+00
1.01277e-01  0.00000e+00  1.96567e-03  0.00000e+00  0.00000e+00  6.53434e-07  0.00000e+00  0.00000e+00  1.07618e-01
1.33564e-02  0.00000e+00  9.02087e-07  0.00000e+00  0.00000e+00  8.57262e-04  0.00000e+00  1.07618e-01  0.00000e+00

Caution

This function was used on output files generated by Q-CHEM versions 5.2.1 and 5.3. If you are using another version of Q-CHEM, the output might be different and the function might need to be adapted.

2.2. Eigenstates basis set

Once the MIME and the transition dipole moments matrix have been recovered from the source file, it is time to build the eigenstates basis set that will be used by QOCT-GRAD. In order to do so, the MIME needs to be diagonalized, this is done with the NumPy package, through the linalg.eig function.

system['eigenvalues'], system['eigenvectors'] = np.linalg.eig(system['mime'])

This gives us the eigenvalues, which are the eigenstates energies, and the associated eigenvectors, which are regrouped into a 2D-array. Those values are then sorted by ascending order of eigenvalues, so that the states are organized in ascending order of energies.

The last step is to compute the transpose of the eigenvectors matrix, with the transpose function from NumPy:

system['transpose'] = np.transpose(system['eigenvectors'])

With the eigenvectors matrix and its transpose, we can now convert the transition dipole moments matrix to the eigenstates basis set, using the matmul function from NumPy:

system['momdip_es_mtx'] = np.matmul(np.matmul(system['transpose'],system['momdip_mtx']),system['eigenvectors'])

Even though it’s not needed, the diagonalized MIME is also recomputed, so that the diagonalization efficiency can be evaluated:

system['mime_diag'] = np.matmul(np.matmul(system['transpose'],system['mime']),system['eigenvectors'])

Note that all those computed variables have been added to the system dictionary, for ease of access by the other parts of CONTROL LAUNCHER.

Let’s end this subsection by using the H2O Q-CHEM output file as an example:

Diagonalizing the MIME ...                       [ DONE ]

Eigenvalues (Ha)

-1.6557807727135554e-06
0.18987382916367557
0.22330190065149785
0.25572335800927826
0.2607872862126559
0.28772579137139187
0.31774427201646704
0.33248157890059926
0.3882501806655301

Eigenvectors matrix

-9.99996e-01 -1.96175e-03 -1.46461e-05  1.77022e-04  1.76039e-03 -4.20907e-06  5.84862e-04 -1.87018e-05  4.04557e-06
 1.97120e-03 -9.99953e-01 -1.93928e-04  7.73046e-03  4.01626e-03  1.94498e-03  1.79630e-03 -2.56768e-03  9.47513e-04
-2.25213e-06 -8.34760e-05  9.99923e-01  1.11428e-02  5.22847e-03 -2.04159e-05  1.79791e-03 -4.44360e-05  3.57291e-06
 1.87040e-04  7.79518e-03 -1.12157e-02  9.99808e-01  1.38601e-02  1.40381e-03  1.31095e-03 -9.61265e-04  7.29489e-05
 1.75469e-03  3.93215e-03 -5.08649e-03 -1.39604e-02  9.99845e-01 -1.26364e-04  7.93151e-03 -1.36897e-03  2.41264e-03
-1.98561e-06  1.95372e-03  1.71601e-05 -1.43349e-03  1.32757e-05  9.99939e-01  1.07426e-02 -1.93645e-04  3.73071e-06
 5.67332e-04  1.79979e-03 -1.74281e-03 -1.24264e-03 -8.00107e-03 -1.07488e-02  9.99588e-01 -2.52312e-02  5.82656e-04
-3.25671e-06  2.50978e-03  1.77862e-05 -9.30988e-04 -1.19125e-03  7.14264e-05 -2.52479e-02 -9.99677e-01  1.37866e-05
-2.39976e-06  9.36334e-04  1.07164e-05 -4.58767e-05 -2.41244e-03  8.91066e-07 -6.03052e-04  3.42902e-05  9.99996e-01

Eigenvectors transpose matrix

-9.99996e-01  1.97120e-03 -2.25213e-06  1.87040e-04  1.75469e-03 -1.98561e-06  5.67332e-04 -3.25671e-06 -2.39976e-06
-1.96175e-03 -9.99953e-01 -8.34760e-05  7.79518e-03  3.93215e-03  1.95372e-03  1.79979e-03  2.50978e-03  9.36334e-04
-1.46461e-05 -1.93928e-04  9.99923e-01 -1.12157e-02 -5.08649e-03  1.71601e-05 -1.74281e-03  1.77862e-05  1.07164e-05
 1.77022e-04  7.73046e-03  1.11428e-02  9.99808e-01 -1.39604e-02 -1.43349e-03 -1.24264e-03 -9.30988e-04 -4.58767e-05
 1.76039e-03  4.01626e-03  5.22847e-03  1.38601e-02  9.99845e-01  1.32757e-05 -8.00107e-03 -1.19125e-03 -2.41244e-03
-4.20907e-06  1.94498e-03 -2.04159e-05  1.40381e-03 -1.26364e-04  9.99939e-01 -1.07488e-02  7.14264e-05  8.91066e-07
 5.84862e-04  1.79630e-03  1.79791e-03  1.31095e-03  7.93151e-03  1.07426e-02  9.99588e-01 -2.52479e-02 -6.03052e-04
-1.87018e-05 -2.56768e-03 -4.44360e-05 -9.61265e-04 -1.36897e-03 -1.93645e-04 -2.52312e-02 -9.99677e-01  3.42902e-05
 4.04557e-06  9.47513e-04  3.57291e-06  7.29489e-05  2.41264e-03  3.73071e-06  5.82656e-04  1.37866e-05  9.99996e-01

MIME in the eigenstates basis set (Ha)

-1.65578e-06  5.17176e-19  8.26105e-20 -3.83673e-20  4.84987e-20  1.62193e-22 -1.12580e-19  4.18511e-21 -9.63496e-23
 4.51967e-19  1.89874e-01 -1.88871e-16  2.14489e-18 -2.17604e-16 -1.00210e-19  2.86313e-17  4.52254e-18  6.06340e-17
 8.24916e-20 -1.88867e-16  2.23302e-01  1.07060e-16 -2.36417e-16  1.89052e-16 -9.51223e-17 -3.23605e-16  6.92267e-17
-4.26371e-20  1.75558e-18  1.08101e-16  2.55723e-01  3.82438e-17 -5.42028e-16  4.64968e-17 -2.49204e-16  8.48270e-17
 1.37265e-19 -2.17695e-16 -2.36238e-16  3.71988e-17  2.60787e-01  6.43149e-17  7.40554e-16 -7.01983e-17  1.21322e-16
 4.63403e-22 -1.34276e-19  1.89053e-16 -5.42005e-16  6.43137e-17  2.87726e-01 -6.63569e-20 -1.31016e-16 -1.06336e-16
-1.98754e-19  2.84508e-17 -9.50175e-17  4.66660e-17  7.40323e-16  3.34245e-20  3.17744e-01 -5.79015e-16 -2.00848e-17
 5.04310e-21  4.44232e-18 -3.23606e-16 -2.49150e-16 -7.00717e-17 -1.31017e-16 -5.77398e-16  3.32482e-01  6.61872e-18
-2.11758e-22  6.06611e-17  6.92263e-17  8.48253e-17  1.21322e-16 -1.06336e-16 -2.00577e-17  6.62041e-18  3.88250e-01

Dipole moments matrix in the eigenstates basis set (atomic units)

 1.46187e-06 -4.45419e-04 -3.77106e-03  8.23924e-05  3.36084e-04 -2.93927e-04  2.56796e-03  1.01243e-01 -1.33574e-02
-4.45419e-04 -8.16837e-04  7.14051e-04  6.41318e-04 -1.02209e-01  8.10129e-07 -4.39198e-04  2.28362e-04 -4.88745e-07
-3.77106e-03  7.14051e-04  5.47117e-06 -2.31070e-04 -1.42461e-05  9.64612e-02  4.15342e-04 -1.96738e-03  2.14454e-06
 8.23924e-05  6.41318e-04 -2.31070e-04 -1.37580e-04  3.80026e-04  5.28634e-04  5.06996e-02 -1.31406e-03 -6.81140e-05
 3.36084e-04 -1.02209e-01 -1.42461e-05  3.80026e-04  7.98671e-04  6.85852e-04  1.60022e-03 -2.27197e-04 -6.05293e-06
-2.93927e-04  8.10129e-07  9.64612e-02  5.28634e-04  6.85852e-04 -5.51515e-06  2.44983e-04 -6.04909e-06  8.65636e-04
 2.56796e-03 -4.39198e-04  4.15342e-04  5.06996e-02  1.60022e-03  2.44983e-04  1.50952e-04 -5.19329e-05 -2.69342e-03
 1.01243e-01  2.28362e-04 -1.96738e-03 -1.31406e-03 -2.27197e-04 -6.04909e-06 -5.19329e-05 -1.78773e-07 -1.07585e-01
-1.33574e-02 -4.88745e-07  2.14454e-06 -6.81140e-05 -6.05293e-06  8.65636e-04 -2.69342e-03 -1.07585e-01  3.55564e-06

2.3. Creating the files

The last step of this system modelling process is to create the actual data files, writing down everything that has been computed until now. There are six of those files:

  • mime contains the MIME in Hartree, stored in the mime key of the system dictionary.

  • momdip_mtx contains the transition dipole moments matrix in atomic units, stored in the momdip_mtx key of the system dictionary.

  • eigenvalues contains the list of the eigenvalues in Hartree, stored in the eigenvalues key of the system dictionary.

  • eigenvectors contains the eigenvectors matrix, stored in the eigenvectors key of the system dictionary.

  • transpose contains the eigenvectors transpose matrix, stored in the transpose key of the system dictionary.

  • momdip_es_mtx contains the transition dipole moments matrix in atomic units, converted to the eigenstates basis set, stored in the momdip_es_mtx key of the system dictionary.

Those files are all created inside a new directory named data, inside another new molecule directory bearing the name of the source file (minus a possible extension). At the end of the system modelling process, the output directory structure is then

out_dir/
  └── source/
        └── data/
              ├── mime
              ├── momdip_mtx
              ├── eigenvalues
              ├── eigenvectors
              ├── transpose
              ├── momdip_es_mtx
              └── source_file

Note that a copy of the source file has also been created into the data directory.