ChemWiki - User contributions [en]

Resgrp:comp-photo-dyn/mctdh90.56dv/run

2013-01-11T11:11:01Z

Callan: /* List of questions asked by dd_gennerator */

= '''Basic use of the MCTDH (DD-vMCG) package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh (DD-vMCG).

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection (or other geometry) described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH (DD-vMCG). You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH (DD-vMCG) program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the structure in coin.log need not necessarily be a true conical intersection: this point is only used for performing the diabatisation. Thus the diabatisation will be exact at this point and will become more approximate the further you are from it (on the PES). If you wish to use a point that is not a conical intersection, simply run a conical intersection optimisation (with only a single step) on the desired geometry. This will create a file with the same layout as a conical intersection optimisation output file (mctdh looks for certain things in this file so if some other type of .log file were used instead, it might not contain the required information). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (with atom types rather than numbers) (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (with atom types rather than numbers) (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH (DD-vMCG) program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH (DD-vMCG). It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH (DD-vMCG).

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH (DD-vMCG) package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_generator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH (DD-vMCG) therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully. If the Mass-weighted displacement from start to coin appears as NaN it may be because the start.log contains atom numbers rather than atom types. You will need to redo the freq=hpmodes job with atom types.

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH (DD-vMCG) and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.) If you are creating a new start.fchk, run the solver on that geometry (relative to the original starting geometry) in the Excel spreadsheet. Create the new start.chk using the geometry in the orange box (so that it is in the same orientation as the molecule in start.log).

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH (DD-vMCG)
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record (e.g. a DB with ca. 3800 records will take a couple of minutes to clean interactively). If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.] In 90.35tmp this is ok. In 90.4X it will also be fixed.

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

=== [[Resgrp:comp-photo-dyn/mctdh90.56dv|back]] ===

Resgrp:comp-photo-dyn/mctdh90.56dv/run

2012-09-19T16:11:49Z

Callan: /* Files created by the generator */

= '''Basic use of the MCTDH (DD-vMCG) package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh (DD-vMCG).

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection (or other geometry) described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH (DD-vMCG). You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH (DD-vMCG) program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the structure in coin.log need not necessarily be a true conical intersection: this point is only used for performing the diabatisation. Thus the diabatisation will be exact at this point and will become more approximate the further you are from it (on the PES). If you wish to use a point that is not a conical intersection, simply run a conical intersection optimisation (with only a single step) on the desired geometry. This will create a file with the same layout as a conical intersection optimisation output file (mctdh looks for certain things in this file so if some other type of .log file were used instead, it might not contain the required information). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (with atom types rather than numbers) (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (with atom types rather than numbers) (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH (DD-vMCG) program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH (DD-vMCG). It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH (DD-vMCG).

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH (DD-vMCG) package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH (DD-vMCG) therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully. If the Mass-weighted displacement from start to coin appears as NaN it may be because the start.log contains atom numbers rather than atom types. You will need to redo the freq=hpmodes job with atom types.

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH (DD-vMCG) and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.) If you are creating a new start.fchk, run the solver on that geometry (relative to the original starting geometry) in the Excel spreadsheet. Create the new start.chk using the geometry in the orange box (so that it is in the same orientation as the molecule in start.log).

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH (DD-vMCG)
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record (e.g. a DB with ca. 3800 records will take a couple of minutes to clean interactively). If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.] In 90.35tmp this is ok. In 90.4X it will also be fixed.

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

=== [[Resgrp:comp-photo-dyn/mctdh90.56dv|back]] ===

Resgrp:comp-photo-dyn/mctdh90.56dv/run

2012-09-19T16:11:12Z

Callan: /* Files created by the generator */

= '''Basic use of the MCTDH (DD-vMCG) package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh (DD-vMCG).

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection (or other geometry) described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH (DD-vMCG). You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH (DD-vMCG) program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the structure in coin.log need not necessarily be a true conical intersection: this point is only used for performing the diabatisation. Thus the diabatisation will be exact at this point and will become more approximate the further you are from it (on the PES). If you wish to use a point that is not a conical intersection, simply run a conical intersection optimisation (with only a single step) on the desired geometry. This will create a file with the same layout as a conical intersection optimisation output file (mctdh looks for certain things in this file so if some other type of .log file were used instead, it might not contain the required information). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (with atom types rather than numbers) (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (with atom types rather than numbers) (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH (DD-vMCG) program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH (DD-vMCG). It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH (DD-vMCG).

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH (DD-vMCG) package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH (DD-vMCG) therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully. If the Mass-weighted displacement from start to coin appears as NaN it may be because the start.log contains atom numbers rather than atom types.

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH (DD-vMCG) and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.) If you are creating a new start.fchk, run the solver on that geometry (relative to the original starting geometry) in the Excel spreadsheet. Create the new start.chk using the geometry in the orange box (so that it is in the same orientation as the molecule in start.log).

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH (DD-vMCG)
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record (e.g. a DB with ca. 3800 records will take a couple of minutes to clean interactively). If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.] In 90.35tmp this is ok. In 90.4X it will also be fixed.

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

=== [[Resgrp:comp-photo-dyn/mctdh90.56dv|back]] ===

Resgrp:comp-photo-dyn/mctdh90.56dv/run

2012-09-19T16:09:28Z

Callan: /* Gaussian Output to be Used as Input for the Dynamics Program */

= '''Basic use of the MCTDH (DD-vMCG) package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh (DD-vMCG).

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection (or other geometry) described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH (DD-vMCG). You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH (DD-vMCG) program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the structure in coin.log need not necessarily be a true conical intersection: this point is only used for performing the diabatisation. Thus the diabatisation will be exact at this point and will become more approximate the further you are from it (on the PES). If you wish to use a point that is not a conical intersection, simply run a conical intersection optimisation (with only a single step) on the desired geometry. This will create a file with the same layout as a conical intersection optimisation output file (mctdh looks for certain things in this file so if some other type of .log file were used instead, it might not contain the required information). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (with atom types rather than numbers) (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (with atom types rather than numbers) (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH (DD-vMCG) program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH (DD-vMCG). It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH (DD-vMCG).

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH (DD-vMCG) package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH (DD-vMCG) therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH (DD-vMCG) and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.) If you are creating a new start.fchk, run the solver on that geometry (relative to the original starting geometry) in the Excel spreadsheet. Create the new start.chk using the geometry in the orange box (so that it is in the same orientation as the molecule in start.log).

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH (DD-vMCG)
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record (e.g. a DB with ca. 3800 records will take a couple of minutes to clean interactively). If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.] In 90.35tmp this is ok. In 90.4X it will also be fixed.

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

=== [[Resgrp:comp-photo-dyn/mctdh90.56dv|back]] ===

Resgrp:comp-photo-dyn/mctdh90.56dv/input

2012-09-19T16:07:34Z

Callan: /* 6. Calculate the (High Precision) Vibrational Modes for the Ground State with State Averaged Orbitals */

= Creating Input for Dynamics Calculations =

== MCTDH (DD-vMCG) versions ==

- Development versions:

* mctdh90dv
* mctdh90.31dv
* mctdh90.56dv

The input required for the dynamics calculation is an optimised ground state structure and an optimised conical intersection in the appropriate orientation. [These two structures are used in the diabatic transformation. They need not necessarily correspond to the Franck-Condon and minimum conical intersection geometries. However, these structures are usually good places to start and so most of this tutorial will assume that these are the references that have been chosen.] The ground state structure must have been optimised with state averaged orbitals. These orbitals must be "cleaned" and the high precision frequencies must have been calculated.

* Development version ( mctdh90.??dv): The only input required for the dynamics calculation is an optimised ground state structure and an optimised conical intersection. The rotation will be "automatic".

- The main objective of this tutorial is learn how to run dynamics calculations, thus we will give you the optimised geometries in the appropiate rotation. (A description of how to rotate a structure will follow in due course)

== State Averaged Orbitals==

State averaged orbitals are necessary in order to represent both ground and excited states at the same time in the space close to the conical intersection. The ''State Average'' algorithm allows the convergence of CASSCF when two or more states are close. A solution is found between the average of the involved orbitals if they were calculated independently for each state. At the Frank-Condon region, away from the intersection, this is not needed, but the code maintains this approximation over all the PES to avoid discontinuities.

= Gaussian Calculations - CASSCF =

== '''1. Generate a starting geometry.''' ==

First of all, we need a set of initial orbitals for the CASSCF calculation, which can be obtained from a simple restricted Hartree-Fock (RHF/STO-3G) optimization. It is useful in systems with high symmetry to start with the molecule in the standard orientation and from a symmetrised geometry. This can be achieved by running a Gaussian calculation without the nosymm keyword and using the geometry returned by this calculation.

* NB You should use the structures given in this tutorial because they are oriented appropriately.

[[Media:buta-s-orient.gjf]]

[[Media:buta-s-orient.log]]

== '''2. Identify the Orbitals Required for the CASSCF Calculation''' ==

Use the geometry from 1. Calculate the HF orbitals with a tight basis set e.g. STO-3G (so that it is easier to identify the relevant orbitals for CASSCF).

Keywords: '''HF/STO-3G pop=full nosymm geom=check'''

* Nosymm is required because every time a calculation is run on the molecule with a different symmetry Gaussian reorients the molecule for that particular point group and will destroy the active space. Nosymm disables this feature.
* Pop=full prints out the orbitals.
* Inspect the orbitals. Select those required for the CASSCF.

[[Media:buta-hf.gjf]]

[[Media:buta-hf.log]]

[[Media:buta-hf.fchk]]

== '''3. Identify the State Averaged Orbitals for the Ground State''' ==

An orbital inspection using any visualization software before performing any CASSCF calculation is essential to identify which orbitals make up the chosen active space. In some cases it may be necessary to use '''guess=alter''' to change the order of the orbitals to make sure the optimisation (see step 4) proceeds with the correct orbitals. Gaussian assumes that the electrons specified in a CASSCF calculation come from the highest occupied orbitals in the initial guess and then takes the remaining orbitals as the lowest virtuals of this guess.

* In this example, the relevant orbitals are the four pi orbitals, which contain four electrons (so the calculation is 4,4). The four orbitals that form the pi molecular orbitals are 14, 15, 16 and 17, thus we do not have to worry about swapping orbitals with the keword ''alter''.

Use the orbitals chosen in 2. (i.e. use the .chk from 2.) Use the final geometry from 2.

Keywords: '''CAS(4,4,nroot=2,stateaverage) STO-3G nosymm IOP(5/97=100,10/97=100) guess=read'''

Here, the weights of each state must be listed explicitly. The weights are 0.5 and 0.5. These must be specified by typing 0.5 followed by 7 spaces then 0.5 (on the same line) (The Gaussian program reads 10 characters (inc spaces) for the first weight and another 10 characters for the second weight. Thus the 7 spaces plus the three characters "0", "." and "5" make up the first 10 characters before the second weight is read.)

* The IOp (5/97=100,10/97=100) tells the program to switch the order of the two states. This is so that we calculate the ground state rather than the excited state. (Gaussian CASSCF calculations always perform optimisations on the highest state listed, so by switching the order we force optimisation of what is actually the lower state.)
* Nroot=2 specifies the ''first'' excited state so the orbitals will averaged over the ground state and the first excited state.

* Inspect the orbitals. Select those required for the CASSCF optimisation. The relevant orbitals are still 14, 15, 16 and 17.

[[Media:buta-orbs-sa.gjf]]

[[Media:buta-orbs-sa.log]]

[[Media:buta-orbs-sa.fchk]]

== '''4. Perform a CASSCF Optimisation on the Ground State with the State Averaged Orbitals''' ==

Use the orbitals chosen in 3. Use the .chk from 3.

Keywords: '''opt=conical pop=full CAS(4,4,nroot=2,stateaverage) STO-3G nosymm IOP(10/10=700005) IOP(5/97=100,10/97=100) geom=checkpoint guess=read'''

N.B. This is not a conical intersection optimisation! However, the keyword opt=conical specifies automatically that the populations of the two states will each be 0.5. Thus there is no need to specify the populations manually. The initial '7' in IOp (10/10=700005) specifies that the calculation should be an optimisation to a minimum (rather than a conical intersection). The final '5' ensures that the orbital rotation derivative contributions from the CP-MC-SCF equations are included. (This is necessary and is usually the default. However, in the current version of Gaussian, the combination of '''opt''' and '''stateaverage''' excludes this).
Stateaverage is the default for opt=conical.
Nroot=2 is the default for opt=conical.
Do not include the keyword '''freq''' in the optimisation. (This combination of IOps does not allow '''opt''' and '''freq''' to be keywords in the same job.)

[[Media:buta-cas.gjf]]

[[Media:buta-cas.log]]

== '''5. "Clean" the Orbitals''' ==

In this case, all the orbitals in the active space are pure pi orbitals. Due to small numerical inaccuracies, the final orbitals may include small contributions from other (non-pi) orbitals. The aim of this step is to remove these contributions so that the active space consists (in this example) only of contributions from the C 2PY atomic orbitals. The four relevant orbitals are occupied orbitals 14 and 15 and virtual orbitals 16 and 17. In fact, they are already clean in this example. Verify this by inspection of the "Molecular Orbital Coefficients" in the population analysis.

In other cases, multiple optimisations may be necessary to clean the orbitals:

Open the file in GaussView, and Edit/Symmetrize. Use this symmetrised geometry as a starting geometry for another optimsation as in 4 (including the keyword '''nosymm''').
Use the .chk from 4.
Re-run the optimisation exactly as in 4.

''Ideally here we include the keyword '''opt=(maxstep=1)'''. This should ensure that the optimisation takes the smallest possible step: we already know that the geometry is very close to the minimum and we need to prevent any significant re-orientation that might occur if large steps are taken. However, this does not seem to work (at least with g03).''

Repeat until the orbitals are clean.

== '''6. Calculate the (High Precision) Vibrational Modes for the Ground State ''with State Averaged Orbitals''''' ==

Use the .chk and the geometry from 5. The geometry must be specified explicitly. (With this combination of IOPs, Gaussian extracts the wrong geometry from the .chk file if '''geom=checkpoint''' is specified.)

Keywords: '''CAS(4,4,nroot=2) STO-3G freq=hpmodes guess=read IOP(5/17=41000200,10/10=700007) IOP(5/97=100,10/97=100)'''

The IOp (5/17=41000200,10/10=700007): includes the CP-MC-SCF correction (as above) (for a frequency calculation); and specifies state averaged orbitals. Do not include the keyword '''stateaverage''' with '''freq''' (the current version of Gaussian does not support this). Freq=hpmodes tells Gaussian to print the vibrational modes to 5 decimal places. As before, the IOp (5/97=100,10/97=100) forces calculation of the ground state. Do not use the keyword nosymm here. (Nosymm may prevent Gaussian from identifying the symmetries of the orbitals.) Use atom labels rather than numbers (otherwise the dd_generator will not work (see later)).

[[Media:buta-hpfreq.gjf]]

[[Media:buta-hpfreq.log]]

== '''7. The Conical Intersection''' ==

One strategy for locating the conical intersection is to calculate the Frank-Condon point and run an optimisation from there, following (one of) the negative frequency(ies).

=== 7a. The Frank-Condon Point ===

Use the .chk from 4. Using the same orbitals perform a single point energy calculation for the first excited state.

Keywords: '''CAS(4,4,nroot=2,stateaverage) STO-3G pop=full nosymm guess=read geom=checkpoint'''

As in 3, the weights of each state must be listed explicitly. The weights are 0.5 and 0.5. These must be specified by typing 0.5 followed by 7 spaces then 0.5 (on the same line) ''(The Gaussian program reads 10 characters (inc spaces) for the first weight and another 10 characters for the second weight. Thus the 7 spaces plus the three characters "0", "." and "5" make up the first 10 characters before the second weight is read.)''

[[Media:buta-fc.gjf]]

[[Media:buta-fc.log]]

=== 7b. Optimise the Conical Intersection ===

Use the .chk from 7a. Distort the geometry to break the symmetry.
A suggested distortion is to increase the C-C-C-C dihedral angle to 45° by twisting one of the terminal carbons out of the plane of the other atoms (be careful to move only the CH2 group, not the hydrogen on the adjacent carbon). Then increase the H-C-C-C dihedral angles of both the terminal CH2 groups to 70°, in a disrotatory direction. A conical intersection optimisation should now locate a conical intersection.

Keywords: '''CAS(4,4,nroot=2) STO-3G opt=conical nosymm guess=read pop=full'''

Stateaverage is the default for opt=conical.
Nroot=2 is the default for opt=conical.

[[Media:buta-dis14570ci.gjf]]

[[Media:buta-dis14570ci.log]]

=== [[Resgrp:comp-photo-dyn/mctdh90.56dv|back]] ===

Resgrp:comp-photo-dyn/mctdh90.56dv/input

2012-09-19T16:07:02Z

Callan: /* 6. Calculate the (High Precision) Vibrational Modes for the Ground State with State Averaged Orbitals */

= Creating Input for Dynamics Calculations =

== MCTDH (DD-vMCG) versions ==

- Development versions:

* mctdh90dv
* mctdh90.31dv
* mctdh90.56dv

The input required for the dynamics calculation is an optimised ground state structure and an optimised conical intersection in the appropriate orientation. [These two structures are used in the diabatic transformation. They need not necessarily correspond to the Franck-Condon and minimum conical intersection geometries. However, these structures are usually good places to start and so most of this tutorial will assume that these are the references that have been chosen.] The ground state structure must have been optimised with state averaged orbitals. These orbitals must be "cleaned" and the high precision frequencies must have been calculated.

* Development version ( mctdh90.??dv): The only input required for the dynamics calculation is an optimised ground state structure and an optimised conical intersection. The rotation will be "automatic".

- The main objective of this tutorial is learn how to run dynamics calculations, thus we will give you the optimised geometries in the appropiate rotation. (A description of how to rotate a structure will follow in due course)

== State Averaged Orbitals==

State averaged orbitals are necessary in order to represent both ground and excited states at the same time in the space close to the conical intersection. The ''State Average'' algorithm allows the convergence of CASSCF when two or more states are close. A solution is found between the average of the involved orbitals if they were calculated independently for each state. At the Frank-Condon region, away from the intersection, this is not needed, but the code maintains this approximation over all the PES to avoid discontinuities.

= Gaussian Calculations - CASSCF =

== '''1. Generate a starting geometry.''' ==

First of all, we need a set of initial orbitals for the CASSCF calculation, which can be obtained from a simple restricted Hartree-Fock (RHF/STO-3G) optimization. It is useful in systems with high symmetry to start with the molecule in the standard orientation and from a symmetrised geometry. This can be achieved by running a Gaussian calculation without the nosymm keyword and using the geometry returned by this calculation.

* NB You should use the structures given in this tutorial because they are oriented appropriately.

[[Media:buta-s-orient.gjf]]

[[Media:buta-s-orient.log]]

== '''2. Identify the Orbitals Required for the CASSCF Calculation''' ==

Use the geometry from 1. Calculate the HF orbitals with a tight basis set e.g. STO-3G (so that it is easier to identify the relevant orbitals for CASSCF).

Keywords: '''HF/STO-3G pop=full nosymm geom=check'''

* Nosymm is required because every time a calculation is run on the molecule with a different symmetry Gaussian reorients the molecule for that particular point group and will destroy the active space. Nosymm disables this feature.
* Pop=full prints out the orbitals.
* Inspect the orbitals. Select those required for the CASSCF.

[[Media:buta-hf.gjf]]

[[Media:buta-hf.log]]

[[Media:buta-hf.fchk]]

== '''3. Identify the State Averaged Orbitals for the Ground State''' ==

An orbital inspection using any visualization software before performing any CASSCF calculation is essential to identify which orbitals make up the chosen active space. In some cases it may be necessary to use '''guess=alter''' to change the order of the orbitals to make sure the optimisation (see step 4) proceeds with the correct orbitals. Gaussian assumes that the electrons specified in a CASSCF calculation come from the highest occupied orbitals in the initial guess and then takes the remaining orbitals as the lowest virtuals of this guess.

* In this example, the relevant orbitals are the four pi orbitals, which contain four electrons (so the calculation is 4,4). The four orbitals that form the pi molecular orbitals are 14, 15, 16 and 17, thus we do not have to worry about swapping orbitals with the keword ''alter''.

Use the orbitals chosen in 2. (i.e. use the .chk from 2.) Use the final geometry from 2.

Keywords: '''CAS(4,4,nroot=2,stateaverage) STO-3G nosymm IOP(5/97=100,10/97=100) guess=read'''

Here, the weights of each state must be listed explicitly. The weights are 0.5 and 0.5. These must be specified by typing 0.5 followed by 7 spaces then 0.5 (on the same line) (The Gaussian program reads 10 characters (inc spaces) for the first weight and another 10 characters for the second weight. Thus the 7 spaces plus the three characters "0", "." and "5" make up the first 10 characters before the second weight is read.)

* The IOp (5/97=100,10/97=100) tells the program to switch the order of the two states. This is so that we calculate the ground state rather than the excited state. (Gaussian CASSCF calculations always perform optimisations on the highest state listed, so by switching the order we force optimisation of what is actually the lower state.)
* Nroot=2 specifies the ''first'' excited state so the orbitals will averaged over the ground state and the first excited state.

* Inspect the orbitals. Select those required for the CASSCF optimisation. The relevant orbitals are still 14, 15, 16 and 17.

[[Media:buta-orbs-sa.gjf]]

[[Media:buta-orbs-sa.log]]

[[Media:buta-orbs-sa.fchk]]

== '''4. Perform a CASSCF Optimisation on the Ground State with the State Averaged Orbitals''' ==

Use the orbitals chosen in 3. Use the .chk from 3.

Keywords: '''opt=conical pop=full CAS(4,4,nroot=2,stateaverage) STO-3G nosymm IOP(10/10=700005) IOP(5/97=100,10/97=100) geom=checkpoint guess=read'''

N.B. This is not a conical intersection optimisation! However, the keyword opt=conical specifies automatically that the populations of the two states will each be 0.5. Thus there is no need to specify the populations manually. The initial '7' in IOp (10/10=700005) specifies that the calculation should be an optimisation to a minimum (rather than a conical intersection). The final '5' ensures that the orbital rotation derivative contributions from the CP-MC-SCF equations are included. (This is necessary and is usually the default. However, in the current version of Gaussian, the combination of '''opt''' and '''stateaverage''' excludes this).
Stateaverage is the default for opt=conical.
Nroot=2 is the default for opt=conical.
Do not include the keyword '''freq''' in the optimisation. (This combination of IOps does not allow '''opt''' and '''freq''' to be keywords in the same job.)

[[Media:buta-cas.gjf]]

[[Media:buta-cas.log]]

== '''5. "Clean" the Orbitals''' ==

In this case, all the orbitals in the active space are pure pi orbitals. Due to small numerical inaccuracies, the final orbitals may include small contributions from other (non-pi) orbitals. The aim of this step is to remove these contributions so that the active space consists (in this example) only of contributions from the C 2PY atomic orbitals. The four relevant orbitals are occupied orbitals 14 and 15 and virtual orbitals 16 and 17. In fact, they are already clean in this example. Verify this by inspection of the "Molecular Orbital Coefficients" in the population analysis.

In other cases, multiple optimisations may be necessary to clean the orbitals:

Open the file in GaussView, and Edit/Symmetrize. Use this symmetrised geometry as a starting geometry for another optimsation as in 4 (including the keyword '''nosymm''').
Use the .chk from 4.
Re-run the optimisation exactly as in 4.

''Ideally here we include the keyword '''opt=(maxstep=1)'''. This should ensure that the optimisation takes the smallest possible step: we already know that the geometry is very close to the minimum and we need to prevent any significant re-orientation that might occur if large steps are taken. However, this does not seem to work (at least with g03).''

Repeat until the orbitals are clean.

== '''6. Calculate the (High Precision) Vibrational Modes for the Ground State ''with State Averaged Orbitals''''' ==

Use the .chk and the geometry from 5. The geometry must be specified explicitly. (With this combination of IOPs, Gaussian extracts the wrong geometry from the .chk file if '''geom=checkpoint''' is specified.)

Keywords: '''CAS(4,4,nroot=2) STO-3G freq=hpmodes guess=read IOP(5/17=41000200,10/10=700007) IOP(5/97=100,10/97=100)'''

The IOp (5/17=41000200,10/10=700007): includes the CP-MC-SCF correction (as above) (for a frequency calculation); and specifies state averaged orbitals. Do not include the keyword '''stateaverage''' with '''freq''' (the current version of Gaussian does not support this). Freq=hpmodes tells Gaussian to print the vibrational modes to 5 decimal places. As before, the IOp (5/97=100,10/97=100) forces calculation of the ground state. Do not use the keyword nosymm here. (Nosymm may prevent Gaussian from identifying the symmetries of the orbitals.) Use atom labels rather than numbers (otherwise the dd_geneartor will not work [see later]).

[[Media:buta-hpfreq.gjf]]

[[Media:buta-hpfreq.log]]

== '''7. The Conical Intersection''' ==

One strategy for locating the conical intersection is to calculate the Frank-Condon point and run an optimisation from there, following (one of) the negative frequency(ies).

=== 7a. The Frank-Condon Point ===

Use the .chk from 4. Using the same orbitals perform a single point energy calculation for the first excited state.

Keywords: '''CAS(4,4,nroot=2,stateaverage) STO-3G pop=full nosymm guess=read geom=checkpoint'''

As in 3, the weights of each state must be listed explicitly. The weights are 0.5 and 0.5. These must be specified by typing 0.5 followed by 7 spaces then 0.5 (on the same line) ''(The Gaussian program reads 10 characters (inc spaces) for the first weight and another 10 characters for the second weight. Thus the 7 spaces plus the three characters "0", "." and "5" make up the first 10 characters before the second weight is read.)''

[[Media:buta-fc.gjf]]

[[Media:buta-fc.log]]

=== 7b. Optimise the Conical Intersection ===

Use the .chk from 7a. Distort the geometry to break the symmetry.
A suggested distortion is to increase the C-C-C-C dihedral angle to 45° by twisting one of the terminal carbons out of the plane of the other atoms (be careful to move only the CH2 group, not the hydrogen on the adjacent carbon). Then increase the H-C-C-C dihedral angles of both the terminal CH2 groups to 70°, in a disrotatory direction. A conical intersection optimisation should now locate a conical intersection.

Keywords: '''CAS(4,4,nroot=2) STO-3G opt=conical nosymm guess=read pop=full'''

Stateaverage is the default for opt=conical.
Nroot=2 is the default for opt=conical.

[[Media:buta-dis14570ci.gjf]]

[[Media:buta-dis14570ci.log]]

=== [[Resgrp:comp-photo-dyn/mctdh90.56dv|back]] ===

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-05-05T17:20:04Z

Callan: /* '''The Database (DB)''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection (or other geometry) described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the structure in coin.log need not necessarily be a true conical intersection: this point is only used for performing the diabatisation. Thus the diabatisation will be exact at this point and will become more approximate the further you are from it (on the PES). If you wish to use a point that is not a conical intersection, simply run a conical intersection optimisation (with only a single step) on the desired geometry. This will create a file with the same layout as a conical intersection optimisation output file (mctdh looks for certain things in this file so if some other type of .log file were used instead, it might not contain the required information). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.) If you are creating a new start.fchk, run the solver on that geometry (relative to the original starting geometry) in the Excel spreadsheet. Create the new start.chk using the geometry in the orange box (so that it is in the same orientation as the molecule in start.log).

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record (e.g. a DB with ca. 3800 records will take a couple of minutes to clean interactively). If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.] In 90.35tmp this is ok. In 90.4X it will also be fixed.

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

Resgrp:comp-photo-dyn

2009-05-05T14:22:21Z

Callan: /* mctdh90.31dv */

Benjamin / Charlotte / David / Marta to create this please! Some Documentation and some tutorials...
MY COMMENTS IN UPPER CASE MAR

= The direct quantum dynamics package =

The direct quantum dynamics method we use is based on the propagation of DD-vMCG (direct dynamics variational multi-configuration Gaussian) wavepackets. This has been implemented in a development version of the Heidelberg MCTDH package [[http://www.pci.uni-heidelberg.de/cms/mctdh.html see web page]] by Graham A. Worth [[http://www.stchem.bham.ac.uk/~worthgrp/ see web page]] and collaborators.

This package consists of a set of programs for multidimensional quantum dynamics using the MCTDH algorithm (multi-configuration time- dependent Hartree). The vMCG method is a particular case of MCTDH, where the nuclear wavepacket is expanded in a time-dependent basis set of Gaussian functions. The direct dynamics implementation allows the electronic energy (potential energy for the nuclei) to be calculated on-the-fly by the quantum chemistry package GAUSSIAN around the centre of each Gaussian function in the expansion, for both electronic states involved in the photochemical process under study.

This approach provides a time-resolved simulation of the photochemical mechanism induced by the initial condition chosen by the user. Non-adiabatic effects and tunneling are better described than with semi-classical trajectory methods such as surface hopping [[http://www.informaworld.com/10.1080/00268970802172503 see recent review]].

== Current available versions ==

* mctdh90dev

This is the "old" and stable version of the code, which has been used by Marta Araujo and David Asturiol. This version relies on the multi-set formulation for DD-vMCG calculations (distinct Gaussian functions on different electronic states), which complicates the interpretation of results and often generates numerical problems. In addition, particular cases require particular versions of the source code to be recompiled.

* mctdh90.31dev

This version should be used from now on, but has not been tested extensively yet. It is more portable and more flexible in terms of options. The main new feature is the possibility of using the single-set formulation for DD-vMCG calculations (a unique set of Gaussian functions with varying occupancies on each electronic states).

''N.B.'': the potential energy surfaces are calculated in the adiabatic picture by GAUSSIAN and must be transformed to the diabatic picture for MCTDH. A simple scheme, based on the "regularized" diabatic states of Köppel ''et al.'' [[http://link.aip.org/link/?JCPSA6/115/2377/1 see reference]], has been used to date in which the gradient difference and non-adiabatic coupling at a point on the conical intersection seam can be used to estimate the transformation matrix. As a consequence, the user needs to provide the geometry and the branching-space vectors of a chosen conical intersection. This complicates the generation of the input files, as these three vectors are given in a Cartesian frame that must be re-orientated following some constraints discussed further in this manual. This also introduces a possible bias and also makes the interpretation of results quite delicate in terms of the assignment of the electronic populations in both representations. A work is in progress to implement a new scheme beyond these limitations.

== General overview ==

The study of photochemical mechanisms using the DD-vMCG method can be approached in four stages.

1) The preliminary stage is a static description of the mechanism under study. This corresponds to a description of the main topological features of the potential energy surfaces of the coupled electronic states, as in any other study of the potential energy surfaces using CASSCF [link, see benzene tutorial]. In practice, this involves:

# Choice of the active space and basis set for the electronic wavefunction
# Characterisation of the relevant critical points (stationary points and conical intersection points)
# Characterisations of the main pathways (reaction paths and crossing seams)
# Definition – and possible selection – of the nuclear coordinates

Some comments:

- Choosing the active space may happen to be delicate when a full-valence description is too expensive (or just too large) to be used for frequency calculations, in particular if sigma and pi orbitals can mix. The user should keep in mind that the active space will be propagated along the trajectories followed by the centres of the Gaussian functions and may break in very distorted geometries.

- The main critical points involved in the mechanism must be identified, optimised and characterised. Stationary points are characterised by frequency calculations, and conical intersection points by examining the nature of the electronic states involved and the branching-space vectors that lifts the degeneracy. The important pathways can be characterised in the form of mimimum energy paths (intrinsic reaction coordinate) linking stationary points. In addition, a development version of GAUSSIAN implemented in our group [link, see documentation (Patrick's page)] can be used to characterise the curvatures of the intersection space (crossing seam). The same program can calculate minimum energy paths within the intersection space, linking conical intersection points characterised as seam minima or seam saddle points.

- For now, the nuclear coordinates are defined as the normal coordinates of the electronic ground-state minimum (magnitude of nuclear displacements along the directions of the normal modes) for convenience. Their number can be reduced to keep the most relevant ones and thus simplify the study of the system dynamics. A method based on the development version of GAUSSIAN mentioned above may be used in this context [[http://link.aip.org/link/?JCPSA6/128/124307/1 see reference]].

2) The second stage is the generation of the input files. This can be performed automatically by a utility program that asks the user questions in order to set the correct options, but two calculations have to be done first:

# Frequency calculation at the ground-state minimum (log and chk or fchk files), used for (i) the initial geometry, (ii) the definition of the normal coordinates, and (iii) the initial active space.
# Optimised conical intersection (log file), used for the generation of diabatic electronic states from the adiabatic ones (when the so-called "regularization" scheme is used).

3) The third stage corresponds to the dynamics calculation itself. This part is managed by the MCTDH program and should finish normally if the input file were written correctly. However, this may fail for various reasons, often because converging the active space becomes difficult. Also, calculations may have to be redone several times, with conditions that can be improved, for example by increasing the number of Gaussian functions in the wavepacket expansion, or by changing the conical intersection point chosen for "regularization" scheme if this approach is to be followed.

4) Finally, the last step is the analysis of results. This involves looking at the time evolution of:

* Normal coordinates at the centre of each Gaussian function ("trajectories")
* Averages and widths of the normal coordinates for the global wavepacket
* Adiabatic and diabatic energies at the centre of each Gaussian function ("trajectories")
* Electronic populations for the global wavepacket

Some comments:

- Normal coordinates can be transformed into Cartesian or internal coordinates. Cartesian coordinates can be used to further represent trajectories as movies using a utility program.

- The quality of the calculation can be checked with various indicators. The simplest is the preservation of the mean total energy. If this increases too fast, the time step might have to be reduced.

- Stages 3 and 4, probably might have to be repeated several times before a satisfactory result is reached. Certainly, the spirit of this part is guided by the trial and error method. Playing with variables such as the number of nuclear Gaussian functions, the final propagation time, the propagation time step, or the integrator may be required.

----

=== [[Resgrp:comp-photo-dyn/mctdh90dev|mctdh90dev]] ===

=== [[Resgrp:comp-photo-dyn/mctdh90.31dv|mctdh90.31dv]] ===

=== [[Resgrp:comp-photo-dyn/mctdh90.56dv|mctdh90.56dv]] ===

File:Ircvector.log

2009-04-06T11:43:16Z

Callan:

File:Ircvector.gjf

2009-04-06T11:42:34Z

Callan:

Resgrp:comp-photo-calculations

2009-04-06T11:42:14Z

Callan: /* IRC calculations in which the vector to follow is specified by the user */

Example input files for different types of calculation, mainly using the development code.

=nonstd=
This keyword means 'don't use any keywords', and allows you to access the gaussian route generator directly.
For more info [http://www.gaussian.com/g_ur/m_non_standard_routes.htm see here] [http://www.gaussian.com/iops.htm and here].
For some types of calculation, we have to use template input files that have non-standard routes and bypass Gaussian's own route generator in 'expert mode'. A route is generated for all Gaussian calculations, and should be at the top of the text .log file. Alternatively, for a calculation that has keywords already available, use the [http://www.gaussian.com/g_ur/u_testrt.htm testrt] keyword interactively at a terminal to see what route is generated.

=ionic states=
For ionic states, a 'minimal' active space (e.g. cas(6,6) for benzene) won't give realistic excitation energies, as there's not enough flexibility to properly describe charge redistribution. With conjugated hydrocarbons, using a double active space and a 1-electron basis set with 3p-like functions (scaled from Si basis set) gives much of the necessary flexibility.

<pre>
#p CASSCF(...)/6-31G* extrabasis

Title

0 1
Geometry

C 0
P 3 0.5
.1727380000D+01 -.1779510000D-01
.5729220000D+00 .2535390000D+00
.2221920000D+00 .8006690000D+00
P 1 0.5
.7783690000D-01 .1000000000D+01
****

</pre>

=Calculating and viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling=

'''Calculation:'''

Use the non-standard route described in the section "Computation of Intersection-Space Frequencies" on the page "Seam Calculations of CHD". The only difference in the non-standard route is 7/79. (7/79=1 for energy difference frequencies only, 7/79=2 for the three things, seam, energy difference and bilinear coupling frequencies).

'''Viewing the modes:'''

The scripts dffx_modes_g01.sh, seam_modes_g01.sh and eta_modes_g01.sh can be used to create log files that gaussview can read to visualise the normal modes and frequencies of the energy difference, the modes of the seam and/or the modes of the bilinear coupling respectively.

First, you need a directory (on your mac or on the cluster) that we will call /dir/.
In here, you put the the scripts (dffx_modes_g01.sh, seam_modes_g01.sh, eta_modes_g01.sh) and a file called template.log, and you create a subdirectory /dir/gaussian_output/ in which you put your log file (say it's called jobname.log).
Then you create a subdirectory /dir/data/.
Then you execute the script this way:
./dffx_modes_g01.sh jobname
and you will get a new file in data that is called jobname_DFFX.log (for energy difference frequencies) or jobname_GV.log (for seam modes) and that can be read by GaussView.

N.B.: ./ might not be needed on the cluster (also this may depend on the type of shell), but it is on my Mac.

''Now, there used to be a small printing error in Fabrizio's code that may not have been fixed.
It's about the mass-weighting of the branching-space vectors, gradient difference and derivative coupling (the last two modes, given with zero frequencies). The consequence is that the motion of H atoms is exaggerated when you visualise these last two vectors with Gaussview.
The other ones are fine.''

NB the convention for the energy difference is S0 - S1, so if you want the modes that reduce the energy difference, take those that have a large positive frequency (with respect to the energy difference).

=IRC calculations in which the vector to follow is specified by the user=

This may be required if the starting point for the IRC is not a transition state (i.e. it has more than one imaginary frequency). In this case, GAUSSIAN will not know which negative frequency to follow so it must be specified explicitly.

Using G03, certain combinations of keywords do not seem to work. Guess=read cannot be used: the orbitals must be specified explicitly in the input file along with the keyword guess=cards. It is also not possible to read in the force constants from a previous .chk file: irc=calcfc must be used. Thus if the calculation requires stateaverage orbitals, the stateaverage keyword must not be used (since, due to a bug in G03, it cannot be used in conjunction with a frequency calculation). Instead, the IOP (5/17=41000200,10/10=700007) should be specified. CAN WE VERIFY IF THIS IS ALL/PARTLY TRUE FOR OTHER VERSIONS OF GAUSSIAN?

A typical route might look like:

# CAS(4,4,nroot=2)/sto-3g IRC=(CalcFC,ReadVector) guess=cards nosymm IOP(5/17=41000200,10/10=700007)

followed by the orbitals and then the vector. The orbitals can be extracted form the .fchk of a previous calculation. Extract the section "Alpha MO coefficients" into a file (named, for example, "mo-file") and then run (on the cluster)

dd_formatmos.out < mo-file > formatted-mos

on "mo-file" to create a file called "formatted-mos" containing the formatted MOs. These can be pasted directly into the input file.

Finally, specify the vector to follow. Find the direction to be followed (in the .log of the frequency calculation). The values may be listed vertically under the desired frequency, in which case these values can be used directly: list these values in rows containing 8 values per row with 10 characters (inc spaces) making up each value. If the direction is specified in cartesian coordinates they will need to be converted to internal coordinates. Do this as described in section "Computation of the Intersection Space Minimum Energy Path (MEP)" on the page "Seam Calculations of CHD". (Essentially this will involve adding the desired cartesian frequency to the cartesian coordinates of the molecule, using GAUSSVIEW to convert this structure to internal coordinates and then subtracting the internal coordinates of the molecule.)

[[Media:ircvector.gjf]]

[[Media:ircvector.log]]

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-04-03T13:39:30Z

Callan: /* Starting from a point other than the Franck-Condon point */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection (or other geometry) described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the structure in coin.log need not necessarily be a true conical intersection: this point is only used for performing the diabatisation. Thus the diabatisation will be exact at this point and will become more approximate the further you are from it (on the PES). If you wish to use a point that is not a conical intersection, simply run a conical intersection optimisation (with only a single step) on the desired geometry. This will create a file with the same layout as a conical intersection optimisation output file (mctdh looks for certain things in this file so if some other type of .log file were used instead, it might not contain the required information). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.) If you are creating a new start.fchk, run the solver on that geometry (relative to the original starting geometry) in the Excel spreadsheet. Create the new start.chk using the geometry in the orange box (so that it is in the same orientation as the molecule in start.log).

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.] In 90.35tmp this is ok. In 90.4X it will also be fixed.

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

Resgrp:comp-photo-CHD

2009-03-25T12:36:17Z

Callan: /* Viewing the normal modes and frequencies of the seam (or the normal modes and frequencies of the energy difference or of the bilinear coupling) */

=Overview=
In the following sections it will be described how one can calculate the conical intersection seam of CHD (cyclo-hexa-1,3-diene) respectively ''cZc''-HT (CZc-hexa-1,3,5-triene) with the new algorithm. Therefore the

# Optimization of a minimum point on the S0/S1 crossing seam
# Computation of Intersection-Space Frequencies
# Optimization of a Saddle point on the S0/S1 CHD crossing seam
# Computation of the Intersection Space Minimum Energy Path (MEP)

will be demonstrated.

==Development version and Substitutions==
For the calculations you have to use the Gaussian Development version, for the use of the current stable version your jobscript must contain following lines:

'''module load gaussian/devel-modules''' 
'''module load gdvg01_08'''

[[Media:example-jobscript.ogg]]

Also the beginning of your Input-file (.com) has to contain the following lines:

'''%subst l103 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l103''' 
'''%subst l115 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l115''' 
'''%subst l510 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l510''' 
'''%subst l716 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l716''' 
'''%subst l1003 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l1003'''

[[Media:test_com.ogg]]

=Optimization of a minimum point on the S0/S1 crossing seam=
For the optimization of a minimum point with the new algorithm you can use a standard input file. When you want to optimize a conical intersection geometry between the ''q-th'' and the ''(q-1)-th'' electronic state with an active space of ''n'' electrons in ''m'' orbitals the input file must contain the following lines:

'''#P CAS(m,n,nr = q)/[basis set]''' 
'''Opt = Conical''' 
'''IOp(1/5=-1,10/10=500005)''' 

'''[Input Title]''' 

'''[Charge] [Spin Multiplicity]''' 

'''[Geometry]'''

The IOp(1/5) set to minus one specifies that we are attempting to optimize a minimum conical intersection point along the crossing seam. The IOp(10/10) is set to 500005 in order to compute the average gradient, which is used in the new algorithm, by solving the SA-CPMCSCF equations. The following files are the input and output files for the optimization of the 2A1/1A1 conical intersection minimum of CHD:

[[Media:CI_min_com.ogg]]

[[Media:CI_min_log.ogg]]

Here also the IOp(1/16) is set to 5 in order to set the maximum allowable magnitude of the the eigenvalues of the second derative matrix. In order to check if this point is a saddle point or a minimum point a frequency calculation is necessary, which is described in the next section.

=Computation of Intersection-Space Frequencies=
For the calculation of the Intersection-Space Frequencies no keywords exist to run such calculation yet. Therefore, a non-standard root has to be composed. A non-standard root is a complete sequence of links with associated options specified in an input file and read in by Gaussian. It is important to note that the program executes each link in the specified order, therefore extreme caution has to be taken when composing a non-standard route. Thus, a non-standard route is generally created by modifying the sequence of links produced by the standard route most similar to the one desired. This is accomplished most easily with the ''testrt'' utility, for more information [https://www.ch.ic.ac.uk/wiki/index.php/Resgrp:comp-photo-calculations see here]. In computing intersection-space frequencies, ''testrt'' is used to produce the route for a standard state-average CASSCF frequency calculation:

'''#P CAS(n,m,stateaveraged,nroot = q)/[basis set]''' 
'''Nosymm''' 
'''Freq'''

The route obtained with ''testrt'' gives the correct sequence of links in a SA-CASSCF frequency analysis with the corresponding default options. However, in an intersection-space frequency analysis one needs the Hessian of both the intersecting electronic states and the Hessian of the rotated optimized wavefunctions. Create the route using testrt and repeat the sequence of links 5, 8, 11, 10, 6, 7 another two times within the new route. Then add/edit the specific options as below. Thus, the non-standard route used for an intersection-space frequency analysis should have a form similar to:

'''1/.../1,3;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/..,17=41000200,.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,.../3;''' 
'''6/.../1;''' 
'''7/...,45=52/1,2,3,16;''' 
'''5/...,17=41000200,...,97=100/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,97=100/3;''' 
'''6/.../1;''' 
'''7/...,45=51/1,2,3,16;''' 
'''5/...,17=41000200,...,79=1/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,79=1/3;''' 
'''6/.../1;''' 
'''7/...,45=53/1,2,3,16;''' 
'''1/.../3;''' 
''' 99//99;'''

The following files are the input and output files for the frequency calculation of the optimized conical intersection minimum of CHD, computed in the previous section:

[[Media:CI_min_freq_com.ogg]]

[[Media:CI_min_freq_log.ogg]]

With the IOp(1/29) and the IOp(4/5) set to one, the geometry and the initial guess is read from the checkpoint file, which you got from the optimization. The IOp(4/17) and IOp(4/18) are set to six, which specifies the number of electrons and orbitals in the active space, one might need to add more keywords depending on the specific study and system.

So how you can see in the output file there is no negative frequency, therefore the structure of section 2 should be a conical intersection minimum.

==Viewing the normal modes and frequencies of the seam (or the normal modes and frequencies of the energy difference or of the bilinear coupling)==

The scripts dffx_modes_g01.sh, seam_modes_g01.sh and eta_modes_g01.sh can be used to create log files that gaussview can read to visualise the normal modes and frequencies of the energy difference, the modes of the seam and/or the modes of the bilinear coupling respectively.

First, you need a directory (on your mac or on the cluster) that we will call /dir/.
In here, you put the the scripts (dffx_modes_g01.sh, seam_modes_g01.sh, eta_modes_g01.sh) and a file called template.log, and you create a subdirectory /dir/gaussian_output/ in which you put your log file (say it's called jobname.log).
Then you create a subdirectory /dir/data/.
Then you execute the script this way:
./dffx_modes_g01.sh jobname
and you will get a new file in data that is called jobname_DFFX.log (for energy difference frequencies) or jobname_GV.log (for seam modes) and that can be read by GaussView.

N.B.: ./ might not be needed on the cluster (also this may depend on the type of shell), but it is on my Mac.

''Now, there used to be a small printing error in Fabrizio's code that may not have been fixed. It's about the mass-weighting of the branching-space vectors, gradient difference and derivative coupling (the last two modes, given with zero frequencies). The consequence is that the motion of H atoms is exaggerated when you visualise these last two vectors with Gaussview. The other ones are fine.''

NB the convention for the energy difference is S0 - S1, so if you want the modes that reduce the energy difference, take those that have a large positive frequency (with respect to the energy difference).

[[Media:Freq_scripts.zip]]

[[Media:template.log]]

=Optimization of a Saddle point on the S0/S1 CHD crossing seam=

Generally, in order to optimize a saddle point structure, one must start from a geometry that is close enough to the quadratic region of such a point. In addition, the Hessian at this initial structure must have a negative eigenvalue, and the corresponding eigevector must be a suitable approximation for the direction connecting the two valleys. When one tries to optimize a saddle point within the intersection space, the initial geometry should also be a point of degeneracy (or near-degeneracy), since the intersection-space Hessian must be computed. Thus it is sometimes useful first to make a single point calculation and then a energy gap optimization between the two states along the gradient difference vector. Input and output files of the single point calculation:

[[Media:CI_trans_com.ogg]]

[[Media:CI_trans_log.ogg]]

Input and output files of the energy gap optimization:

[[Media:CI_trans_E_com.ogg]]

[[Media:CI_trans_E_log.ogg]]

Then it is also quite useful first to make a frequency calculation of this point:

[[Media:CI_trans_E_freq_com.ogg]]

[[Media:CI_trans_E_freq_log.ogg]]

And then one can do with this checkpoint file the optimization of the first-order saddle point:

[[Media:CI_trans_opt_com.ogg]]

[[Media:CI_trans_opt_log.ogg]]

The IOp(1/8) set to one specifies the maximum step size allowed during the optimization and the IOp(5/7) set to 250 specifies the maximum number of iterations. Because this time we want to get a first-order saddle point instead of a minimum also the IOp(1/5) is set minus 2. To prove that this is a first-order saddle point a frequency calculation must be done, which is also necessary for the Computation of the Intersection Space Minimum Energy Path (section 5):

[[Media:CI_trans_opt_freq_com.ogg]]

[[Media:CI_trans_opt_freq_log.ogg]]

The one negative frequency indicates that the point is really a first-order saddle point.

=Computation of the Intersection Space Minimum Energy Path (MEP)=

Currently no standard route exists to compute a minimum energy path limited to the intersection-space. Therefore, as discussed in section 3, a non-standard route has to be specified in the input file in order to perform these calculations. Using ''testrt'' and carefully modifying the output obtained for a standard intrinsic reaction path computation, which is specified by the IRC keyword, one should obtain something similar to:

'''1/...,44=-3,.../1,15;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''6/.../1;''' 
'''7/.../16;''' 
'''1/...,44=-3,../15(2);''' 
'''2/.../2;''' 
'''99//99;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''7/.../16;''' 
'''1/...,44=-3,.../15(-8);''' 
'''2/.../2;''' 
'''6/.../1;''' 
'''99/9=1/99;'''

In order to evaluate the intersection-space minimum energy path, there are added three more options to the existing IOp(1/44):

'''1/44 = -1 Compute the intersection-space minimum energy path in mass-weighted Cartesian coordinates.''' 
'''1/44 = -2 Compute the intersection-space minimum energy path in internal coordinates.''' 
'''1/44 = -3 Compute the intersection-space minimum energy path in mass-weighted internal coordinates.'''

For the following example the intersection-space minimum energy path (MEP) is computed in mass-weighted internal coordinates. For the computation of the MEP you need the transition point structure and the search vector from the optimization of the Saddle point from section 4. The transition point structure is the optimized Saddle point structure, while the search vector is the normal mode of the one negative frequency. But because in the output the normal mode is given in Cartesian coordinates, you first have to transform them in internal coordinates, by adding the normal mode to the optimized Saddle point structure, write out this structure in internal coordinates and calculate e.g with Exel the differences of the internal coordinates in comparison to the optimized Saddle point structure. These differences of the internal coordinates (search vector) have to be add to the transition point structure (in internal coordinates) in a 8F10.6 format in the input file:

[[Media:CI_IRC_com.ogg]]

[[Media:CI_IRC_log.tar.gz.ogg]]

So the calculated MEP leads from the transition point (CI_trans) to the minimum point (CI_min) on the S0/S1 crossing seam.

Resgrp:comp-photo-calculations

2009-03-24T13:00:06Z

Callan: /* IRC calculations in which the vector to follow is specified by the user */

Resgrp:comp-photo-calculations

2009-03-24T12:55:53Z

Callan: /* IRC calculations in which the vector to follow is specified by the user */

Example input files for different types of calculation, mainly using the development code.

=nonstd=
This keyword means 'don't use any keywords', and allows you to access the gaussian route generator directly.
For more info [http://www.gaussian.com/g_ur/m_non_standard_routes.htm see here] [http://www.gaussian.com/iops.htm and here].
For some types of calculation, we have to use template input files that have non-standard routes and bypass Gaussian's own route generator in 'expert mode'. A route is generated for all Gaussian calculations, and should be at the top of the text .log file. Alternatively, for a calculation that has keywords already available, use the [http://www.gaussian.com/g_ur/u_testrt.htm testrt] keyword interactively at a terminal to see what route is generated.

=ionic states=
For ionic states, a 'minimal' active space (e.g. cas(6,6) for benzene) won't give realistic excitation energies, as there's not enough flexibility to properly describe charge redistribution. With conjugated hydrocarbons, using a double active space and a 1-electron basis set with 3p-like functions (scaled from Si basis set) gives much of the necessary flexibility.

<pre>
#p CASSCF(...)/6-31G* extrabasis

Title

0 1
Geometry

C 0
P 3 0.5
.1727380000D+01 -.1779510000D-01
.5729220000D+00 .2535390000D+00
.2221920000D+00 .8006690000D+00
P 1 0.5
.7783690000D-01 .1000000000D+01
****

</pre>

=Calculating and viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling=

'''Calculation:'''

Use the non-standard route described in the section "Computation of Intersection-Space Frequencies" on the page "Seam Calculations of CHD". The only difference in the non-standard route is 7/79. (7/79=1 for energy difference frequencies only, 7/79=2 for the three things, seam, energy difference and bilinear coupling frequencies).

'''Viewing the modes:'''

The scripts dffx_modes_g01.sh, seam_modes_g01.sh and eta_modes_g01.sh can be used to create log files that gaussview can read to visualise the normal modes and frequencies of the energy difference, the modes of the seam and/or the modes of the bilinear coupling respectively.

First, you need a directory (on your mac or on the cluster) that we will call /dir/.
In here, you put the the scripts (dffx_modes_g01.sh, seam_modes_g01.sh, eta_modes_g01.sh) and a file called template.log, and you create a subdirectory /dir/gaussian_output/ in which you put your log file (say it's called jobname.log).
Then you create a subdirectory /dir/data/.
Then you execute the script this way:
./dffx_modes_g01.sh jobname
and you will get a new file in data that is called jobname_DFFX.log (for energy difference frequencies) or jobname_GV.log (for seam modes) and that can be read by GaussView.

N.B.: ./ might not be needed on the cluster (also this may depend on the type of shell), but it is on my Mac.

''Now, there used to be a small printing error in Fabrizio's code that may not have been fixed.
It's about the mass-weighting of the branching-space vectors, gradient difference and derivative coupling (the last two modes, given with zero frequencies). The consequence is that the motion of H atoms is exaggerated when you visualise these last two vectors with Gaussview.
The other ones are fine.''

NB the convention for the energy difference is S0 - S1, so if you want the modes that reduce the energy difference, take those that have a large positive frequency (with respect to the energy difference).

=IRC calculations in which the vector to follow is specified by the user=

This may be required if the starting point for the IRC is not a transition state (i.e. it has more than one imaginary frequency). In this case, GAUSSIAN will not know which negative frequency to follow so it must be specified explicitly.

Using G03, certain combinations of keywords do not seem to work. Guess=read cannot be used: the orbitals must be specified explicitly in the input file along with the keyword guess=cards. It is also not possible to read in the force constants from a previous .chk file: irc=calcfc must be used. Thus if the calculation requires stateaverage orbitals, the stateaverage keyword must not be used (since, due to a bug in G03, it cannot be used in conjunction with a frequency calculation). Instead, the IOP (5/17=41000200,10/10=700007) should be specified. CAN WE VERIFY IF THIS IS ALL/PARTLY TRUE FOR OTHER VERSIONS OF GAUSSIAN?

A typical route might look like:

# CAS(4,4,nroot=2)/sto-3g IRC=(CalcFC,ReadVector) guess=cards nosymm IOP(5/17=41000200,10/10=700007)

followed by the orbitals and then the vector. The orbitals can be extracted form the .fchk of a previous calculation. Extract the section "Alpha MO coefficients" into a file (named, for example, "mo-file") and then run

dd_formatmos.out < mo-file > formatted-mos

on "mo-file" to create a file called "formatted-mos" containing the formatted MOs. These can be pasted directly into the input file.

Finally, specify the vector to follow. Find the direction to be followed (in the .log of the frequency calculation). The values may be listed vertically under the desired frequency, in which case these values can be used directly: list these values in rows containing 8 values per row with 10 characters (inc spaces) making up each value. If the direction is specified in cartesian coordinates they will need to be converted to internal coordinates. Do this as described in section

Resgrp:comp-photo-calculations

2009-03-24T12:51:20Z

Callan: /* IRC calculations in which the vector to follow is specified by the user */

Example input files for different types of calculation, mainly using the development code.

=nonstd=
This keyword means 'don't use any keywords', and allows you to access the gaussian route generator directly.
For more info [http://www.gaussian.com/g_ur/m_non_standard_routes.htm see here] [http://www.gaussian.com/iops.htm and here].
For some types of calculation, we have to use template input files that have non-standard routes and bypass Gaussian's own route generator in 'expert mode'. A route is generated for all Gaussian calculations, and should be at the top of the text .log file. Alternatively, for a calculation that has keywords already available, use the [http://www.gaussian.com/g_ur/u_testrt.htm testrt] keyword interactively at a terminal to see what route is generated.

=ionic states=
For ionic states, a 'minimal' active space (e.g. cas(6,6) for benzene) won't give realistic excitation energies, as there's not enough flexibility to properly describe charge redistribution. With conjugated hydrocarbons, using a double active space and a 1-electron basis set with 3p-like functions (scaled from Si basis set) gives much of the necessary flexibility.

<pre>
#p CASSCF(...)/6-31G* extrabasis

Title

0 1
Geometry

C 0
P 3 0.5
.1727380000D+01 -.1779510000D-01
.5729220000D+00 .2535390000D+00
.2221920000D+00 .8006690000D+00
P 1 0.5
.7783690000D-01 .1000000000D+01
****

</pre>

=Calculating and viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling=

'''Calculation:'''

Use the non-standard route described in the section "Computation of Intersection-Space Frequencies" on the page "Seam Calculations of CHD". The only difference in the non-standard route is 7/79. (7/79=1 for energy difference frequencies only, 7/79=2 for the three things, seam, energy difference and bilinear coupling frequencies).

'''Viewing the modes:'''

The scripts dffx_modes_g01.sh, seam_modes_g01.sh and eta_modes_g01.sh can be used to create log files that gaussview can read to visualise the normal modes and frequencies of the energy difference, the modes of the seam and/or the modes of the bilinear coupling respectively.

First, you need a directory (on your mac or on the cluster) that we will call /dir/.
In here, you put the the scripts (dffx_modes_g01.sh, seam_modes_g01.sh, eta_modes_g01.sh) and a file called template.log, and you create a subdirectory /dir/gaussian_output/ in which you put your log file (say it's called jobname.log).
Then you create a subdirectory /dir/data/.
Then you execute the script this way:
./dffx_modes_g01.sh jobname
and you will get a new file in data that is called jobname_DFFX.log (for energy difference frequencies) or jobname_GV.log (for seam modes) and that can be read by GaussView.

N.B.: ./ might not be needed on the cluster (also this may depend on the type of shell), but it is on my Mac.

''Now, there used to be a small printing error in Fabrizio's code that may not have been fixed.
It's about the mass-weighting of the branching-space vectors, gradient difference and derivative coupling (the last two modes, given with zero frequencies). The consequence is that the motion of H atoms is exaggerated when you visualise these last two vectors with Gaussview.
The other ones are fine.''

NB the convention for the energy difference is S0 - S1, so if you want the modes that reduce the energy difference, take those that have a large positive frequency (with respect to the energy difference).

=IRC calculations in which the vector to follow is specified by the user=

This may be required if the starting point for the IRC is not a transition state (i.e. it has more than one imaginary frequency). In this case, GAUSSIAN will not know which negative frequency to follow so it must be specified explicitly.

Using G03, certain combinations of keywords do not seem to work. Guess=read cannot be used: the orbitals must be specified explicitly in the input file along with the keyword guess=cards. It is also not possible to read in the force constants from a previous .chk file: irc=calcfc must be used. Thus if the calculation requires stateaverage orbitals, the stateaverage keyword must not be used (since, due to a bug in G03, it cannot be used in conjunction with a frequency calculation). Instead, the IOP (5/17=41000200,10/10=700007) should be specified. CAN WE VERIFY IF THIS IS ALL/PARTLY TRUE FOR OTHER VERSIONS OF GAUSSIAN?

A typical route might look like:

# CAS(4,4,nroot=2)/sto-3g IRC=(CalcFC,ReadVector) guess=cards nosymm IOP(5/17=41000200,10/10=700007)

followed by the orbitals and then the vector. The orbitals can be extracted form the .fchk of a previous calculation. Extract the section "Alpha MO coefficients" into a file (named, for example, "mo-file") and then run

dd_formatmos.out < mo-file > formatted-mos

on "mo-file" to create a file called "formatted-mos" containing the formatted MOs. These can be pasted directly into the input file.

Finally, specify the vector to follow. Find the direction to be followed (in the .log of the frequency calculation: the values are listed vertically under the desired frequency). List these values in rows containing 8 values per row (back to back) with 10 characters (inc spaces) making up each value.

Resgrp:comp-photo-calculations

2009-03-24T12:47:31Z

Callan: /* IRC calculations in which the vector to follow is specified by the user */

Resgrp:comp-photo-calculations

2009-03-24T12:42:14Z

Callan: /* IRC calculations in which the vector to follow is specified by the user */

Resgrp:comp-photo-calculations

2009-03-24T11:59:50Z

Callan: /* IRC calculations in which the vector to follow is specified by the user */

Resgrp:comp-photo-calculations

2009-03-24T11:56:41Z

Callan: /* IRC calculations in which the vector to follow is specified by the user */

Resgrp:comp-photo-calculations

2009-03-24T11:49:34Z

Callan:

Resgrp:comp-photo-calculations

2009-03-24T11:45:34Z

Callan: /* Calculating and viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling */

Resgrp:comp-photo-calculations

2009-03-24T11:45:19Z

Callan: /* Calculating and viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling */

Resgrp:comp-photo-CHD

2009-03-24T11:39:05Z

Callan: /* Viewing the normal modes and frequencies of the seam (or the normal modes and frequencies of the energy difference or of the bilinear coupling) */

Resgrp:comp-photo-CHD

2009-03-24T11:38:19Z

Callan: /* Viewing the normal modes and frequencies of the seam (or the normal modes and frequencies of the energy difference or of the bilinear coupling) */

=Overview=
In the following sections it will be described how one can calculate the conical intersection seam of CHD (cyclo-hexa-1,3-diene) respectively ''cZc''-HT (CZc-hexa-1,3,5-triene) with the new algorithm. Therefore the

# Optimization of a minimum point on the S0/S1 crossing seam
# Computation of Intersection-Space Frequencies
# Optimization of a Saddle point on the S0/S1 CHD crossing seam
# Computation of the Intersection Space Minimum Energy Path (MEP)

will be demonstrated.

==Development version and Substitutions==
For the calculations you have to use the Gaussian Development version, for the use of the current stable version your jobscript must contain following lines:

'''module load gaussian/devel-modules''' 
'''module load gdvg01_08'''

[[Media:example-jobscript.ogg]]

Also the beginning of your Input-file (.com) has to contain the following lines:

'''%subst l103 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l103''' 
'''%subst l115 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l115''' 
'''%subst l510 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l510''' 
'''%subst l716 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l716''' 
'''%subst l1003 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l1003'''

[[Media:test_com.ogg]]

=Optimization of a minimum point on the S0/S1 crossing seam=
For the optimization of a minimum point with the new algorithm you can use a standard input file. When you want to optimize a conical intersection geometry between the ''q-th'' and the ''(q-1)-th'' electronic state with an active space of ''n'' electrons in ''m'' orbitals the input file must contain the following lines:

'''#P CAS(m,n,nr = q)/[basis set]''' 
'''Opt = Conical''' 
'''IOp(1/5=-1,10/10=500005)''' 

'''[Input Title]''' 

'''[Charge] [Spin Multiplicity]''' 

'''[Geometry]'''

The IOp(1/5) set to minus one specifies that we are attempting to optimize a minimum conical intersection point along the crossing seam. The IOp(10/10) is set to 500005 in order to compute the average gradient, which is used in the new algorithm, by solving the SA-CPMCSCF equations. The following files are the input and output files for the optimization of the 2A1/1A1 conical intersection minimum of CHD:

[[Media:CI_min_com.ogg]]

[[Media:CI_min_log.ogg]]

Here also the IOp(1/16) is set to 5 in order to set the maximum allowable magnitude of the the eigenvalues of the second derative matrix. In order to check if this point is a saddle point or a minimum point a frequency calculation is necessary, which is described in the next section.

=Computation of Intersection-Space Frequencies=
For the calculation of the Intersection-Space Frequencies no keywords exist to run such calculation yet. Therefore, a non-standard root has to be composed. A non-standard root is a complete sequence of links with associated options specified in an input file and read in by Gaussian. It is important to note that the program executes each link in the specified order, therefore extreme caution has to be taken when composing a non-standard route. Thus, a non-standard route is generally created by modifying the sequence of links produced by the standard route most similar to the one desired. This is accomplished most easily with the ''testrt'' utility, for more information [https://www.ch.ic.ac.uk/wiki/index.php/Resgrp:comp-photo-calculations see here]. In computing intersection-space frequencies, ''testrt'' is used to produce the route for a standard state-average CASSCF frequency calculation:

'''#P CAS(n,m,stateaveraged,nroot = q)/[basis set]''' 
'''Nosymm''' 
'''Freq'''

The route obtained with ''testrt'' gives the correct sequence of links in a SA-CASSCF frequency analysis with the corresponding default options. However, in an intersection-space frequency analysis one needs the Hessian of both the intersecting electronic states and the Hessian of the rotated optimized wavefunctions. Create the route using testrt and repeat the sequence of links 5, 8, 11, 10, 6, 7 another two times within the new route. Then add/edit the specific options as below. Thus, the non-standard route used for an intersection-space frequency analysis should have a form similar to:

'''1/.../1,3;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/..,17=41000200,.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,.../3;''' 
'''6/.../1;''' 
'''7/...,45=52/1,2,3,16;''' 
'''5/...,17=41000200,...,97=100/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,97=100/3;''' 
'''6/.../1;''' 
'''7/...,45=51/1,2,3,16;''' 
'''5/...,17=41000200,...,79=1/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,79=1/3;''' 
'''6/.../1;''' 
'''7/...,45=53/1,2,3,16;''' 
'''1/.../3;''' 
''' 99//99;'''

The following files are the input and output files for the frequency calculation of the optimized conical intersection minimum of CHD, computed in the previous section:

[[Media:CI_min_freq_com.ogg]]

[[Media:CI_min_freq_log.ogg]]

With the IOp(1/29) and the IOp(4/5) set to one, the geometry and the initial guess is read from the checkpoint file, which you got from the optimization. The IOp(4/17) and IOp(4/18) are set to six, which specifies the number of electrons and orbitals in the active space, one might need to add more keywords depending on the specific study and system.

So how you can see in the output file there is no negative frequency, therefore the structure of section 2 should be a conical intersection minimum.

==Viewing the normal modes and frequencies of the seam (or the normal modes and frequencies of the energy difference or of the bilinear coupling)==

The scripts dffx_modes_g01.sh, seam_modes_g01.sh and eta_modes_g01.sh can be used to create log files that gaussview can read to visualise the normal modes and frequencies of the energy difference, the modes of the seam and/or the modes of the bilinear coupling respectively.

First, you need a directory (on your mac or on the cluster) that we will call /dir/.
In here, you put the the scripts (dffx_modes_g01.sh, seam_modes_g01.sh, eta_modes_g01.sh) and a file called template.log, and you create a subdirectory /dir/gaussian_output/ in which you put your log file (say it's called jobname.log).
Then you create a subdirectory /dir/data/.
Then you execute the script this way:
./dffx_modes_g01.sh jobname
and you will get a new file in data that is called jobname_DFFX.log (for energy difference frequencies) or jobname_GV.log (for seam modes) and that can be read by GaussView.

N.B.: ./ might not be needed on the cluster (also this may depend on the type of shell), but it is on my Mac.

''''Now, there used to be a small printing error in Fabrizio's code that may not have been fixed.
It's about the mass-weighting of the branching-space vectors, gradient difference and derivative coupling (the last two modes, given with zero frequencies). The consequence is that the motion of H atoms is exaggerated when you visualise these last two vectors with Gaussview.
The other ones are fine.''''

NB the convention for the energy difference is S0 - S1, so if you want the modes that reduce the energy difference, take those that have a large positive frequency (with respect to the energy difference).

[[Media:Freq_scripts.zip]]

[[Media:template.log]]

=Optimization of a Saddle point on the S0/S1 CHD crossing seam=

Generally, in order to optimize a saddle point structure, one must start from a geometry that is close enough to the quadratic region of such a point. In addition, the Hessian at this initial structure must have a negative eigenvalue, and the corresponding eigevector must be a suitable approximation for the direction connecting the two valleys. When one tries to optimize a saddle point within the intersection space, the initial geometry should also be a point of degeneracy (or near-degeneracy), since the intersection-space Hessian must be computed. Thus it is sometimes useful first to make a single point calculation and then a energy gap optimization between the two states along the gradient difference vector. Input and output files of the single point calculation:

[[Media:CI_trans_com.ogg]]

[[Media:CI_trans_log.ogg]]

Input and output files of the energy gap optimization:

[[Media:CI_trans_E_com.ogg]]

[[Media:CI_trans_E_log.ogg]]

Then it is also quite useful first to make a frequency calculation of this point:

[[Media:CI_trans_E_freq_com.ogg]]

[[Media:CI_trans_E_freq_log.ogg]]

And then one can do with this checkpoint file the optimization of the first-order saddle point:

[[Media:CI_trans_opt_com.ogg]]

[[Media:CI_trans_opt_log.ogg]]

The IOp(1/8) set to one specifies the maximum step size allowed during the optimization and the IOp(5/7) set to 250 specifies the maximum number of iterations. Because this time we want to get a first-order saddle point instead of a minimum also the IOp(1/5) is set minus 2. To prove that this is a first-order saddle point a frequency calculation must be done, which is also necessary for the Computation of the Intersection Space Minimum Energy Path (section 5):

[[Media:CI_trans_opt_freq_com.ogg]]

[[Media:CI_trans_opt_freq_log.ogg]]

The one negative frequency indicates that the point is really a first-order saddle point.

=Computation of the Intersection Space Minimum Energy Path (MEP)=

Currently no standard route exists to compute a minimum energy path limited to the intersection-space. Therefore, as discussed in section 3, a non-standard route has to be specified in the input file in order to perform these calculations. Using ''testrt'' and carefully modifying the output obtained for a standard intrinsic reaction path computation, which is specified by the IRC keyword, one should obtain something similar to:

'''1/...,44=-3,.../1,15;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''6/.../1;''' 
'''7/.../16;''' 
'''1/...,44=-3,../15(2);''' 
'''2/.../2;''' 
'''99//99;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''7/.../16;''' 
'''1/...,44=-3,.../15(-8);''' 
'''2/.../2;''' 
'''6/.../1;''' 
'''99/9=1/99;'''

In order to evaluate the intersection-space minimum energy path, there are added three more options to the existing IOp(1/44):

'''1/44 = -1 Compute the intersection-space minimum energy path in mass-weighted Cartesian coordinates.''' 
'''1/44 = -2 Compute the intersection-space minimum energy path in internal coordinates.''' 
'''1/44 = -3 Compute the intersection-space minimum energy path in mass-weighted internal coordinates.'''

For the following example the intersection-space minimum energy path (MEP) is computed in mass-weighted internal coordinates. For the computation of the MEP you need the transition point structure and the search vector from the optimization of the Saddle point from section 4. The transition point structure is the optimized Saddle point structure, while the search vector is the normal mode of the one negative frequency. But because in the output the normal mode is given in Cartesian coordinates, you first have to transform them in internal coordinates, by adding the normal mode to the optimized Saddle point structure, write out this structure in internal coordinates and calculate e.g with Exel the differences of the internal coordinates in comparison to the optimized Saddle point structure. These differences of the internal coordinates (search vector) have to be add to the transition point structure (in internal coordinates) in a 8F10.6 format in the input file:

[[Media:CI_IRC_com.ogg]]

[[Media:CI_IRC_log.tar.gz.ogg]]

So the calculated MEP leads from the transition point (CI_trans) to the minimum point (CI_min) on the S0/S1 crossing seam.

Resgrp:comp-photo-CHD

2009-03-24T11:37:45Z

Callan: /* Viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling */

=Overview=
In the following sections it will be described how one can calculate the conical intersection seam of CHD (cyclo-hexa-1,3-diene) respectively ''cZc''-HT (CZc-hexa-1,3,5-triene) with the new algorithm. Therefore the

# Optimization of a minimum point on the S0/S1 crossing seam
# Computation of Intersection-Space Frequencies
# Optimization of a Saddle point on the S0/S1 CHD crossing seam
# Computation of the Intersection Space Minimum Energy Path (MEP)

will be demonstrated.

==Development version and Substitutions==
For the calculations you have to use the Gaussian Development version, for the use of the current stable version your jobscript must contain following lines:

'''module load gaussian/devel-modules''' 
'''module load gdvg01_08'''

[[Media:example-jobscript.ogg]]

Also the beginning of your Input-file (.com) has to contain the following lines:

'''%subst l103 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l103''' 
'''%subst l115 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l115''' 
'''%subst l510 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l510''' 
'''%subst l716 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l716''' 
'''%subst l1003 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l1003'''

[[Media:test_com.ogg]]

=Optimization of a minimum point on the S0/S1 crossing seam=
For the optimization of a minimum point with the new algorithm you can use a standard input file. When you want to optimize a conical intersection geometry between the ''q-th'' and the ''(q-1)-th'' electronic state with an active space of ''n'' electrons in ''m'' orbitals the input file must contain the following lines:

'''#P CAS(m,n,nr = q)/[basis set]''' 
'''Opt = Conical''' 
'''IOp(1/5=-1,10/10=500005)''' 

'''[Input Title]''' 

'''[Charge] [Spin Multiplicity]''' 

'''[Geometry]'''

The IOp(1/5) set to minus one specifies that we are attempting to optimize a minimum conical intersection point along the crossing seam. The IOp(10/10) is set to 500005 in order to compute the average gradient, which is used in the new algorithm, by solving the SA-CPMCSCF equations. The following files are the input and output files for the optimization of the 2A1/1A1 conical intersection minimum of CHD:

[[Media:CI_min_com.ogg]]

[[Media:CI_min_log.ogg]]

Here also the IOp(1/16) is set to 5 in order to set the maximum allowable magnitude of the the eigenvalues of the second derative matrix. In order to check if this point is a saddle point or a minimum point a frequency calculation is necessary, which is described in the next section.

=Computation of Intersection-Space Frequencies=
For the calculation of the Intersection-Space Frequencies no keywords exist to run such calculation yet. Therefore, a non-standard root has to be composed. A non-standard root is a complete sequence of links with associated options specified in an input file and read in by Gaussian. It is important to note that the program executes each link in the specified order, therefore extreme caution has to be taken when composing a non-standard route. Thus, a non-standard route is generally created by modifying the sequence of links produced by the standard route most similar to the one desired. This is accomplished most easily with the ''testrt'' utility, for more information [https://www.ch.ic.ac.uk/wiki/index.php/Resgrp:comp-photo-calculations see here]. In computing intersection-space frequencies, ''testrt'' is used to produce the route for a standard state-average CASSCF frequency calculation:

'''#P CAS(n,m,stateaveraged,nroot = q)/[basis set]''' 
'''Nosymm''' 
'''Freq'''

The route obtained with ''testrt'' gives the correct sequence of links in a SA-CASSCF frequency analysis with the corresponding default options. However, in an intersection-space frequency analysis one needs the Hessian of both the intersecting electronic states and the Hessian of the rotated optimized wavefunctions. Create the route using testrt and repeat the sequence of links 5, 8, 11, 10, 6, 7 another two times within the new route. Then add/edit the specific options as below. Thus, the non-standard route used for an intersection-space frequency analysis should have a form similar to:

'''1/.../1,3;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/..,17=41000200,.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,.../3;''' 
'''6/.../1;''' 
'''7/...,45=52/1,2,3,16;''' 
'''5/...,17=41000200,...,97=100/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,97=100/3;''' 
'''6/.../1;''' 
'''7/...,45=51/1,2,3,16;''' 
'''5/...,17=41000200,...,79=1/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,79=1/3;''' 
'''6/.../1;''' 
'''7/...,45=53/1,2,3,16;''' 
'''1/.../3;''' 
''' 99//99;'''

The following files are the input and output files for the frequency calculation of the optimized conical intersection minimum of CHD, computed in the previous section:

[[Media:CI_min_freq_com.ogg]]

[[Media:CI_min_freq_log.ogg]]

With the IOp(1/29) and the IOp(4/5) set to one, the geometry and the initial guess is read from the checkpoint file, which you got from the optimization. The IOp(4/17) and IOp(4/18) are set to six, which specifies the number of electrons and orbitals in the active space, one might need to add more keywords depending on the specific study and system.

So how you can see in the output file there is no negative frequency, therefore the structure of section 2 should be a conical intersection minimum.

==Viewing the normal modes and frequencies of the seam (or the normal modes and frequencies of the energy difference or of the bilinear coupling)==

The scripts dffx_modes_g01.sh, seam_modes_g01.sh and eta_modes_g01.sh can be used to create log files that gaussview can read to visualise the normal modes and frequencies of the energy difference, the modes of the seam and/or the modes of the bilinear coupling respectively.

First, you need a directory (on your mac or on the cluster) that we will call /dir/.
In here, you put the the scripts (dffx_modes_g01.sh, seam_modes_g01.sh, eta_modes_g01.sh) and a file called template.log, and you create a subdirectory /dir/gaussian_output/ in which you put your log file (say it's called jobname.log).
Then you create a subdirectory /dir/data/.
Then you execute the script this way:
./dffx_modes_g01.sh jobname
and you will get a new file in data that is called jobname_DFFX.log (for energy difference frequencies) or jobname_GV.log (for seam modes) and that can be read by GaussView.

N.B.: ./ might not be needed on the cluster (also this may depend on the type of shell), but it is on my Mac.

''Now, there used to be a small printing error in Fabrizio's code that may not have been fixed.
It's about the mass-weighting of the branching-space vectors, gradient difference and derivative coupling (the last two modes, given with zero frequencies). The consequence is that the motion of H atoms is exaggerated when you visualise these last two vectors with Gaussview.
The other ones are fine.''

NB the convention for the energy difference is S0 - S1, so if you want the modes that reduce the energy difference, take those that have a large positive frequency (with respect to the energy difference).

[[Media:Freq_scripts.zip]]

[[Media:template.log]]

=Optimization of a Saddle point on the S0/S1 CHD crossing seam=

Generally, in order to optimize a saddle point structure, one must start from a geometry that is close enough to the quadratic region of such a point. In addition, the Hessian at this initial structure must have a negative eigenvalue, and the corresponding eigevector must be a suitable approximation for the direction connecting the two valleys. When one tries to optimize a saddle point within the intersection space, the initial geometry should also be a point of degeneracy (or near-degeneracy), since the intersection-space Hessian must be computed. Thus it is sometimes useful first to make a single point calculation and then a energy gap optimization between the two states along the gradient difference vector. Input and output files of the single point calculation:

[[Media:CI_trans_com.ogg]]

[[Media:CI_trans_log.ogg]]

Input and output files of the energy gap optimization:

[[Media:CI_trans_E_com.ogg]]

[[Media:CI_trans_E_log.ogg]]

Then it is also quite useful first to make a frequency calculation of this point:

[[Media:CI_trans_E_freq_com.ogg]]

[[Media:CI_trans_E_freq_log.ogg]]

And then one can do with this checkpoint file the optimization of the first-order saddle point:

[[Media:CI_trans_opt_com.ogg]]

[[Media:CI_trans_opt_log.ogg]]

The IOp(1/8) set to one specifies the maximum step size allowed during the optimization and the IOp(5/7) set to 250 specifies the maximum number of iterations. Because this time we want to get a first-order saddle point instead of a minimum also the IOp(1/5) is set minus 2. To prove that this is a first-order saddle point a frequency calculation must be done, which is also necessary for the Computation of the Intersection Space Minimum Energy Path (section 5):

[[Media:CI_trans_opt_freq_com.ogg]]

[[Media:CI_trans_opt_freq_log.ogg]]

The one negative frequency indicates that the point is really a first-order saddle point.

=Computation of the Intersection Space Minimum Energy Path (MEP)=

Currently no standard route exists to compute a minimum energy path limited to the intersection-space. Therefore, as discussed in section 3, a non-standard route has to be specified in the input file in order to perform these calculations. Using ''testrt'' and carefully modifying the output obtained for a standard intrinsic reaction path computation, which is specified by the IRC keyword, one should obtain something similar to:

'''1/...,44=-3,.../1,15;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''6/.../1;''' 
'''7/.../16;''' 
'''1/...,44=-3,../15(2);''' 
'''2/.../2;''' 
'''99//99;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''7/.../16;''' 
'''1/...,44=-3,.../15(-8);''' 
'''2/.../2;''' 
'''6/.../1;''' 
'''99/9=1/99;'''

In order to evaluate the intersection-space minimum energy path, there are added three more options to the existing IOp(1/44):

'''1/44 = -1 Compute the intersection-space minimum energy path in mass-weighted Cartesian coordinates.''' 
'''1/44 = -2 Compute the intersection-space minimum energy path in internal coordinates.''' 
'''1/44 = -3 Compute the intersection-space minimum energy path in mass-weighted internal coordinates.'''

For the following example the intersection-space minimum energy path (MEP) is computed in mass-weighted internal coordinates. For the computation of the MEP you need the transition point structure and the search vector from the optimization of the Saddle point from section 4. The transition point structure is the optimized Saddle point structure, while the search vector is the normal mode of the one negative frequency. But because in the output the normal mode is given in Cartesian coordinates, you first have to transform them in internal coordinates, by adding the normal mode to the optimized Saddle point structure, write out this structure in internal coordinates and calculate e.g with Exel the differences of the internal coordinates in comparison to the optimized Saddle point structure. These differences of the internal coordinates (search vector) have to be add to the transition point structure (in internal coordinates) in a 8F10.6 format in the input file:

[[Media:CI_IRC_com.ogg]]

[[Media:CI_IRC_log.tar.gz.ogg]]

So the calculated MEP leads from the transition point (CI_trans) to the minimum point (CI_min) on the S0/S1 crossing seam.

File:Template.log

2009-03-24T11:35:08Z

Callan:

Resgrp:comp-photo-CHD

2009-03-24T11:34:53Z

Callan: /* Viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling */

=Overview=
In the following sections it will be described how one can calculate the conical intersection seam of CHD (cyclo-hexa-1,3-diene) respectively ''cZc''-HT (CZc-hexa-1,3,5-triene) with the new algorithm. Therefore the

# Optimization of a minimum point on the S0/S1 crossing seam
# Computation of Intersection-Space Frequencies
# Optimization of a Saddle point on the S0/S1 CHD crossing seam
# Computation of the Intersection Space Minimum Energy Path (MEP)

will be demonstrated.

==Development version and Substitutions==
For the calculations you have to use the Gaussian Development version, for the use of the current stable version your jobscript must contain following lines:

'''module load gaussian/devel-modules''' 
'''module load gdvg01_08'''

[[Media:example-jobscript.ogg]]

Also the beginning of your Input-file (.com) has to contain the following lines:

'''%subst l103 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l103''' 
'''%subst l115 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l115''' 
'''%subst l510 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l510''' 
'''%subst l716 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l716''' 
'''%subst l1003 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l1003'''

[[Media:test_com.ogg]]

=Optimization of a minimum point on the S0/S1 crossing seam=
For the optimization of a minimum point with the new algorithm you can use a standard input file. When you want to optimize a conical intersection geometry between the ''q-th'' and the ''(q-1)-th'' electronic state with an active space of ''n'' electrons in ''m'' orbitals the input file must contain the following lines:

'''#P CAS(m,n,nr = q)/[basis set]''' 
'''Opt = Conical''' 
'''IOp(1/5=-1,10/10=500005)''' 

'''[Input Title]''' 

'''[Charge] [Spin Multiplicity]''' 

'''[Geometry]'''

The IOp(1/5) set to minus one specifies that we are attempting to optimize a minimum conical intersection point along the crossing seam. The IOp(10/10) is set to 500005 in order to compute the average gradient, which is used in the new algorithm, by solving the SA-CPMCSCF equations. The following files are the input and output files for the optimization of the 2A1/1A1 conical intersection minimum of CHD:

[[Media:CI_min_com.ogg]]

[[Media:CI_min_log.ogg]]

Here also the IOp(1/16) is set to 5 in order to set the maximum allowable magnitude of the the eigenvalues of the second derative matrix. In order to check if this point is a saddle point or a minimum point a frequency calculation is necessary, which is described in the next section.

=Computation of Intersection-Space Frequencies=
For the calculation of the Intersection-Space Frequencies no keywords exist to run such calculation yet. Therefore, a non-standard root has to be composed. A non-standard root is a complete sequence of links with associated options specified in an input file and read in by Gaussian. It is important to note that the program executes each link in the specified order, therefore extreme caution has to be taken when composing a non-standard route. Thus, a non-standard route is generally created by modifying the sequence of links produced by the standard route most similar to the one desired. This is accomplished most easily with the ''testrt'' utility, for more information [https://www.ch.ic.ac.uk/wiki/index.php/Resgrp:comp-photo-calculations see here]. In computing intersection-space frequencies, ''testrt'' is used to produce the route for a standard state-average CASSCF frequency calculation:

'''#P CAS(n,m,stateaveraged,nroot = q)/[basis set]''' 
'''Nosymm''' 
'''Freq'''

The route obtained with ''testrt'' gives the correct sequence of links in a SA-CASSCF frequency analysis with the corresponding default options. However, in an intersection-space frequency analysis one needs the Hessian of both the intersecting electronic states and the Hessian of the rotated optimized wavefunctions. Create the route using testrt and repeat the sequence of links 5, 8, 11, 10, 6, 7 another two times within the new route. Then add/edit the specific options as below. Thus, the non-standard route used for an intersection-space frequency analysis should have a form similar to:

'''1/.../1,3;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/..,17=41000200,.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,.../3;''' 
'''6/.../1;''' 
'''7/...,45=52/1,2,3,16;''' 
'''5/...,17=41000200,...,97=100/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,97=100/3;''' 
'''6/.../1;''' 
'''7/...,45=51/1,2,3,16;''' 
'''5/...,17=41000200,...,79=1/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,79=1/3;''' 
'''6/.../1;''' 
'''7/...,45=53/1,2,3,16;''' 
'''1/.../3;''' 
''' 99//99;'''

The following files are the input and output files for the frequency calculation of the optimized conical intersection minimum of CHD, computed in the previous section:

[[Media:CI_min_freq_com.ogg]]

[[Media:CI_min_freq_log.ogg]]

With the IOp(1/29) and the IOp(4/5) set to one, the geometry and the initial guess is read from the checkpoint file, which you got from the optimization. The IOp(4/17) and IOp(4/18) are set to six, which specifies the number of electrons and orbitals in the active space, one might need to add more keywords depending on the specific study and system.

So how you can see in the output file there is no negative frequency, therefore the structure of section 2 should be a conical intersection minimum.

==Viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling==

The scripts dffx_modes_g01.sh, seam_modes_g01.sh and eta_modes_g01.sh can be used to create log files that gaussview can read to visualise the normal modes and frequencies of the energy difference, the modes of the seam and/or the modes of the bilinear coupling respectively.

First, you need a directory (on your mac or on the cluster) that we will call /dir/.
In here, you put the the scripts (dffx_modes_g01.sh, seam_modes_g01.sh, eta_modes_g01.sh) and a file called template.log, and you create a subdirectory /dir/gaussian_output/ in which you put your log file (say it's called jobname.log).
Then you create a subdirectory /dir/data/.
Then you execute the script this way:
./dffx_modes_g01.sh jobname
and you will get a new file in data that is called jobname_DFFX.log (for energy difference frequencies) or jobname_GV.log (for seam modes) and that can be read by GaussView.

N.B.: ./ might not be needed on the cluster (also this may depend on the type of shell), but it is on my Mac.

''Now, there used to be a small printing error in Fabrizio's code that may not have been fixed.
It's about the mass-weighting of the branching-space vectors, gradient difference and derivative coupling (the last two modes, given with zero frequencies). The consequence is that the motion of H atoms is exaggerated when you visualise these last two vectors with Gaussview.
The other ones are fine.''

NB the convention for the energy difference is S0 - S1, so if you want the modes that reduce the energy difference, take those that have a large positive frequency (with respect to the energy difference).

[[Media:Freq_scripts.zip]]

[[Media:template.log]]

=Optimization of a Saddle point on the S0/S1 CHD crossing seam=

Generally, in order to optimize a saddle point structure, one must start from a geometry that is close enough to the quadratic region of such a point. In addition, the Hessian at this initial structure must have a negative eigenvalue, and the corresponding eigevector must be a suitable approximation for the direction connecting the two valleys. When one tries to optimize a saddle point within the intersection space, the initial geometry should also be a point of degeneracy (or near-degeneracy), since the intersection-space Hessian must be computed. Thus it is sometimes useful first to make a single point calculation and then a energy gap optimization between the two states along the gradient difference vector. Input and output files of the single point calculation:

[[Media:CI_trans_com.ogg]]

[[Media:CI_trans_log.ogg]]

Input and output files of the energy gap optimization:

[[Media:CI_trans_E_com.ogg]]

[[Media:CI_trans_E_log.ogg]]

Then it is also quite useful first to make a frequency calculation of this point:

[[Media:CI_trans_E_freq_com.ogg]]

[[Media:CI_trans_E_freq_log.ogg]]

And then one can do with this checkpoint file the optimization of the first-order saddle point:

[[Media:CI_trans_opt_com.ogg]]

[[Media:CI_trans_opt_log.ogg]]

The IOp(1/8) set to one specifies the maximum step size allowed during the optimization and the IOp(5/7) set to 250 specifies the maximum number of iterations. Because this time we want to get a first-order saddle point instead of a minimum also the IOp(1/5) is set minus 2. To prove that this is a first-order saddle point a frequency calculation must be done, which is also necessary for the Computation of the Intersection Space Minimum Energy Path (section 5):

[[Media:CI_trans_opt_freq_com.ogg]]

[[Media:CI_trans_opt_freq_log.ogg]]

The one negative frequency indicates that the point is really a first-order saddle point.

=Computation of the Intersection Space Minimum Energy Path (MEP)=

Currently no standard route exists to compute a minimum energy path limited to the intersection-space. Therefore, as discussed in section 3, a non-standard route has to be specified in the input file in order to perform these calculations. Using ''testrt'' and carefully modifying the output obtained for a standard intrinsic reaction path computation, which is specified by the IRC keyword, one should obtain something similar to:

'''1/...,44=-3,.../1,15;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''6/.../1;''' 
'''7/.../16;''' 
'''1/...,44=-3,../15(2);''' 
'''2/.../2;''' 
'''99//99;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''7/.../16;''' 
'''1/...,44=-3,.../15(-8);''' 
'''2/.../2;''' 
'''6/.../1;''' 
'''99/9=1/99;'''

In order to evaluate the intersection-space minimum energy path, there are added three more options to the existing IOp(1/44):

'''1/44 = -1 Compute the intersection-space minimum energy path in mass-weighted Cartesian coordinates.''' 
'''1/44 = -2 Compute the intersection-space minimum energy path in internal coordinates.''' 
'''1/44 = -3 Compute the intersection-space minimum energy path in mass-weighted internal coordinates.'''

For the following example the intersection-space minimum energy path (MEP) is computed in mass-weighted internal coordinates. For the computation of the MEP you need the transition point structure and the search vector from the optimization of the Saddle point from section 4. The transition point structure is the optimized Saddle point structure, while the search vector is the normal mode of the one negative frequency. But because in the output the normal mode is given in Cartesian coordinates, you first have to transform them in internal coordinates, by adding the normal mode to the optimized Saddle point structure, write out this structure in internal coordinates and calculate e.g with Exel the differences of the internal coordinates in comparison to the optimized Saddle point structure. These differences of the internal coordinates (search vector) have to be add to the transition point structure (in internal coordinates) in a 8F10.6 format in the input file:

[[Media:CI_IRC_com.ogg]]

[[Media:CI_IRC_log.tar.gz.ogg]]

So the calculated MEP leads from the transition point (CI_trans) to the minimum point (CI_min) on the S0/S1 crossing seam.

File:Freq scripts.zip

2009-03-24T11:34:01Z

Callan:

Resgrp:comp-photo-CHD

2009-03-24T11:33:46Z

Callan: /* Viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling */

=Overview=
In the following sections it will be described how one can calculate the conical intersection seam of CHD (cyclo-hexa-1,3-diene) respectively ''cZc''-HT (CZc-hexa-1,3,5-triene) with the new algorithm. Therefore the

# Optimization of a minimum point on the S0/S1 crossing seam
# Computation of Intersection-Space Frequencies
# Optimization of a Saddle point on the S0/S1 CHD crossing seam
# Computation of the Intersection Space Minimum Energy Path (MEP)

will be demonstrated.

==Development version and Substitutions==
For the calculations you have to use the Gaussian Development version, for the use of the current stable version your jobscript must contain following lines:

'''module load gaussian/devel-modules''' 
'''module load gdvg01_08'''

[[Media:example-jobscript.ogg]]

Also the beginning of your Input-file (.com) has to contain the following lines:

'''%subst l103 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l103''' 
'''%subst l115 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l115''' 
'''%subst l510 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l510''' 
'''%subst l716 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l716''' 
'''%subst l1003 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l1003'''

[[Media:test_com.ogg]]

=Optimization of a minimum point on the S0/S1 crossing seam=
For the optimization of a minimum point with the new algorithm you can use a standard input file. When you want to optimize a conical intersection geometry between the ''q-th'' and the ''(q-1)-th'' electronic state with an active space of ''n'' electrons in ''m'' orbitals the input file must contain the following lines:

'''#P CAS(m,n,nr = q)/[basis set]''' 
'''Opt = Conical''' 
'''IOp(1/5=-1,10/10=500005)''' 

'''[Input Title]''' 

'''[Charge] [Spin Multiplicity]''' 

'''[Geometry]'''

The IOp(1/5) set to minus one specifies that we are attempting to optimize a minimum conical intersection point along the crossing seam. The IOp(10/10) is set to 500005 in order to compute the average gradient, which is used in the new algorithm, by solving the SA-CPMCSCF equations. The following files are the input and output files for the optimization of the 2A1/1A1 conical intersection minimum of CHD:

[[Media:CI_min_com.ogg]]

[[Media:CI_min_log.ogg]]

Here also the IOp(1/16) is set to 5 in order to set the maximum allowable magnitude of the the eigenvalues of the second derative matrix. In order to check if this point is a saddle point or a minimum point a frequency calculation is necessary, which is described in the next section.

=Computation of Intersection-Space Frequencies=
For the calculation of the Intersection-Space Frequencies no keywords exist to run such calculation yet. Therefore, a non-standard root has to be composed. A non-standard root is a complete sequence of links with associated options specified in an input file and read in by Gaussian. It is important to note that the program executes each link in the specified order, therefore extreme caution has to be taken when composing a non-standard route. Thus, a non-standard route is generally created by modifying the sequence of links produced by the standard route most similar to the one desired. This is accomplished most easily with the ''testrt'' utility, for more information [https://www.ch.ic.ac.uk/wiki/index.php/Resgrp:comp-photo-calculations see here]. In computing intersection-space frequencies, ''testrt'' is used to produce the route for a standard state-average CASSCF frequency calculation:

'''#P CAS(n,m,stateaveraged,nroot = q)/[basis set]''' 
'''Nosymm''' 
'''Freq'''

The route obtained with ''testrt'' gives the correct sequence of links in a SA-CASSCF frequency analysis with the corresponding default options. However, in an intersection-space frequency analysis one needs the Hessian of both the intersecting electronic states and the Hessian of the rotated optimized wavefunctions. Create the route using testrt and repeat the sequence of links 5, 8, 11, 10, 6, 7 another two times within the new route. Then add/edit the specific options as below. Thus, the non-standard route used for an intersection-space frequency analysis should have a form similar to:

'''1/.../1,3;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/..,17=41000200,.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,.../3;''' 
'''6/.../1;''' 
'''7/...,45=52/1,2,3,16;''' 
'''5/...,17=41000200,...,97=100/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,97=100/3;''' 
'''6/.../1;''' 
'''7/...,45=51/1,2,3,16;''' 
'''5/...,17=41000200,...,79=1/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,79=1/3;''' 
'''6/.../1;''' 
'''7/...,45=53/1,2,3,16;''' 
'''1/.../3;''' 
''' 99//99;'''

The following files are the input and output files for the frequency calculation of the optimized conical intersection minimum of CHD, computed in the previous section:

[[Media:CI_min_freq_com.ogg]]

[[Media:CI_min_freq_log.ogg]]

With the IOp(1/29) and the IOp(4/5) set to one, the geometry and the initial guess is read from the checkpoint file, which you got from the optimization. The IOp(4/17) and IOp(4/18) are set to six, which specifies the number of electrons and orbitals in the active space, one might need to add more keywords depending on the specific study and system.

So how you can see in the output file there is no negative frequency, therefore the structure of section 2 should be a conical intersection minimum.

==Viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling==

The scripts dffx_modes_g01.sh, seam_modes_g01.sh and eta_modes_g01.sh can be used to create log files that gaussview can read to visualise the normal modes and frequencies of the energy difference, the modes of the seam and/or the modes of the bilinear coupling respectively.

First, you need a directory (on your mac or on the cluster) that we will call /dir/.
In here, you put the the scripts (dffx_modes_g01.sh, seam_modes_g01.sh, eta_modes_g01.sh) and a file called template.log, and you create a subdirectory /dir/gaussian_output/ in which you put your log file (say it's called jobname.log).
Then you create a subdirectory /dir/data/.
Then you execute the script this way:
./dffx_modes_g01.sh jobname
and you will get a new file in data that is called jobname_DFFX.log (for energy difference frequencies) or jobname_GV.log (for seam modes) and that can be read by GaussView.

N.B.: ./ might not be needed on the cluster (also this may depend on the type of shell), but it is on my Mac.

''Now, there used to be a small printing error in Fabrizio's code that may not have been fixed.
It's about the mass-weighting of the branching-space vectors, gradient difference and derivative coupling (the last two modes, given with zero frequencies). The consequence is that the motion of H atoms is exaggerated when you visualise these last two vectors with Gaussview.
The other ones are fine.''

NB the convention for the energy difference is S0 - S1, so if you want the modes that reduce the energy difference, take those that have a large positive frequency (with respect to the energy difference).
[[Media:Freq_scripts.zip]]

=Optimization of a Saddle point on the S0/S1 CHD crossing seam=

Generally, in order to optimize a saddle point structure, one must start from a geometry that is close enough to the quadratic region of such a point. In addition, the Hessian at this initial structure must have a negative eigenvalue, and the corresponding eigevector must be a suitable approximation for the direction connecting the two valleys. When one tries to optimize a saddle point within the intersection space, the initial geometry should also be a point of degeneracy (or near-degeneracy), since the intersection-space Hessian must be computed. Thus it is sometimes useful first to make a single point calculation and then a energy gap optimization between the two states along the gradient difference vector. Input and output files of the single point calculation:

[[Media:CI_trans_com.ogg]]

[[Media:CI_trans_log.ogg]]

Input and output files of the energy gap optimization:

[[Media:CI_trans_E_com.ogg]]

[[Media:CI_trans_E_log.ogg]]

Then it is also quite useful first to make a frequency calculation of this point:

[[Media:CI_trans_E_freq_com.ogg]]

[[Media:CI_trans_E_freq_log.ogg]]

And then one can do with this checkpoint file the optimization of the first-order saddle point:

[[Media:CI_trans_opt_com.ogg]]

[[Media:CI_trans_opt_log.ogg]]

The IOp(1/8) set to one specifies the maximum step size allowed during the optimization and the IOp(5/7) set to 250 specifies the maximum number of iterations. Because this time we want to get a first-order saddle point instead of a minimum also the IOp(1/5) is set minus 2. To prove that this is a first-order saddle point a frequency calculation must be done, which is also necessary for the Computation of the Intersection Space Minimum Energy Path (section 5):

[[Media:CI_trans_opt_freq_com.ogg]]

[[Media:CI_trans_opt_freq_log.ogg]]

The one negative frequency indicates that the point is really a first-order saddle point.

=Computation of the Intersection Space Minimum Energy Path (MEP)=

Currently no standard route exists to compute a minimum energy path limited to the intersection-space. Therefore, as discussed in section 3, a non-standard route has to be specified in the input file in order to perform these calculations. Using ''testrt'' and carefully modifying the output obtained for a standard intrinsic reaction path computation, which is specified by the IRC keyword, one should obtain something similar to:

'''1/...,44=-3,.../1,15;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''6/.../1;''' 
'''7/.../16;''' 
'''1/...,44=-3,../15(2);''' 
'''2/.../2;''' 
'''99//99;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''7/.../16;''' 
'''1/...,44=-3,.../15(-8);''' 
'''2/.../2;''' 
'''6/.../1;''' 
'''99/9=1/99;'''

In order to evaluate the intersection-space minimum energy path, there are added three more options to the existing IOp(1/44):

'''1/44 = -1 Compute the intersection-space minimum energy path in mass-weighted Cartesian coordinates.''' 
'''1/44 = -2 Compute the intersection-space minimum energy path in internal coordinates.''' 
'''1/44 = -3 Compute the intersection-space minimum energy path in mass-weighted internal coordinates.'''

For the following example the intersection-space minimum energy path (MEP) is computed in mass-weighted internal coordinates. For the computation of the MEP you need the transition point structure and the search vector from the optimization of the Saddle point from section 4. The transition point structure is the optimized Saddle point structure, while the search vector is the normal mode of the one negative frequency. But because in the output the normal mode is given in Cartesian coordinates, you first have to transform them in internal coordinates, by adding the normal mode to the optimized Saddle point structure, write out this structure in internal coordinates and calculate e.g with Exel the differences of the internal coordinates in comparison to the optimized Saddle point structure. These differences of the internal coordinates (search vector) have to be add to the transition point structure (in internal coordinates) in a 8F10.6 format in the input file:

[[Media:CI_IRC_com.ogg]]

[[Media:CI_IRC_log.tar.gz.ogg]]

So the calculated MEP leads from the transition point (CI_trans) to the minimum point (CI_min) on the S0/S1 crossing seam.

Resgrp:comp-photo-CHD

2009-03-24T11:31:37Z

Callan:

=Overview=
In the following sections it will be described how one can calculate the conical intersection seam of CHD (cyclo-hexa-1,3-diene) respectively ''cZc''-HT (CZc-hexa-1,3,5-triene) with the new algorithm. Therefore the

# Optimization of a minimum point on the S0/S1 crossing seam
# Computation of Intersection-Space Frequencies
# Optimization of a Saddle point on the S0/S1 CHD crossing seam
# Computation of the Intersection Space Minimum Energy Path (MEP)

will be demonstrated.

==Development version and Substitutions==
For the calculations you have to use the Gaussian Development version, for the use of the current stable version your jobscript must contain following lines:

'''module load gaussian/devel-modules''' 
'''module load gdvg01_08'''

[[Media:example-jobscript.ogg]]

Also the beginning of your Input-file (.com) has to contain the following lines:

'''%subst l103 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l103''' 
'''%subst l115 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l115''' 
'''%subst l510 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l510''' 
'''%subst l716 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l716''' 
'''%subst l1003 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l1003'''

[[Media:test_com.ogg]]

=Optimization of a minimum point on the S0/S1 crossing seam=
For the optimization of a minimum point with the new algorithm you can use a standard input file. When you want to optimize a conical intersection geometry between the ''q-th'' and the ''(q-1)-th'' electronic state with an active space of ''n'' electrons in ''m'' orbitals the input file must contain the following lines:

'''#P CAS(m,n,nr = q)/[basis set]''' 
'''Opt = Conical''' 
'''IOp(1/5=-1,10/10=500005)''' 

'''[Input Title]''' 

'''[Charge] [Spin Multiplicity]''' 

'''[Geometry]'''

The IOp(1/5) set to minus one specifies that we are attempting to optimize a minimum conical intersection point along the crossing seam. The IOp(10/10) is set to 500005 in order to compute the average gradient, which is used in the new algorithm, by solving the SA-CPMCSCF equations. The following files are the input and output files for the optimization of the 2A1/1A1 conical intersection minimum of CHD:

[[Media:CI_min_com.ogg]]

[[Media:CI_min_log.ogg]]

Here also the IOp(1/16) is set to 5 in order to set the maximum allowable magnitude of the the eigenvalues of the second derative matrix. In order to check if this point is a saddle point or a minimum point a frequency calculation is necessary, which is described in the next section.

=Computation of Intersection-Space Frequencies=
For the calculation of the Intersection-Space Frequencies no keywords exist to run such calculation yet. Therefore, a non-standard root has to be composed. A non-standard root is a complete sequence of links with associated options specified in an input file and read in by Gaussian. It is important to note that the program executes each link in the specified order, therefore extreme caution has to be taken when composing a non-standard route. Thus, a non-standard route is generally created by modifying the sequence of links produced by the standard route most similar to the one desired. This is accomplished most easily with the ''testrt'' utility, for more information [https://www.ch.ic.ac.uk/wiki/index.php/Resgrp:comp-photo-calculations see here]. In computing intersection-space frequencies, ''testrt'' is used to produce the route for a standard state-average CASSCF frequency calculation:

'''#P CAS(n,m,stateaveraged,nroot = q)/[basis set]''' 
'''Nosymm''' 
'''Freq'''

The route obtained with ''testrt'' gives the correct sequence of links in a SA-CASSCF frequency analysis with the corresponding default options. However, in an intersection-space frequency analysis one needs the Hessian of both the intersecting electronic states and the Hessian of the rotated optimized wavefunctions. Create the route using testrt and repeat the sequence of links 5, 8, 11, 10, 6, 7 another two times within the new route. Then add/edit the specific options as below. Thus, the non-standard route used for an intersection-space frequency analysis should have a form similar to:

'''1/.../1,3;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/..,17=41000200,.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,.../3;''' 
'''6/.../1;''' 
'''7/...,45=52/1,2,3,16;''' 
'''5/...,17=41000200,...,97=100/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,97=100/3;''' 
'''6/.../1;''' 
'''7/...,45=51/1,2,3,16;''' 
'''5/...,17=41000200,...,79=1/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,79=1/3;''' 
'''6/.../1;''' 
'''7/...,45=53/1,2,3,16;''' 
'''1/.../3;''' 
''' 99//99;'''

The following files are the input and output files for the frequency calculation of the optimized conical intersection minimum of CHD, computed in the previous section:

[[Media:CI_min_freq_com.ogg]]

[[Media:CI_min_freq_log.ogg]]

With the IOp(1/29) and the IOp(4/5) set to one, the geometry and the initial guess is read from the checkpoint file, which you got from the optimization. The IOp(4/17) and IOp(4/18) are set to six, which specifies the number of electrons and orbitals in the active space, one might need to add more keywords depending on the specific study and system.

So how you can see in the output file there is no negative frequency, therefore the structure of section 2 should be a conical intersection minimum.

==Viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling==

The scripts dffx_modes_g01.sh, seam_modes_g01.sh and eta_modes_g01.sh can be used to create log files that gaussview can read to visualise the normal modes and frequencies of the energy difference, the modes of the seam and/or the modes of the bilinear coupling respectively.

First, you need a directory (on your mac or on the cluster) that we will call /dir/.
In here, you put the the scripts (dffx_modes_g01.sh, seam_modes_g01.sh, eta_modes_g01.sh) and a file called template.log, and you create a subdirectory /dir/gaussian_output/ in which you put your log file (say it's called jobname.log).
Then you create a subdirectory /dir/data/.
Then you execute the script this way:
./dffx_modes_g01.sh jobname
and you will get a new file in data that is called jobname_DFFX.log (for energy difference frequencies) or jobname_GV.log (for seam modes) and that can be read by GaussView.

N.B.: ./ might not be needed on the cluster (also this may depend on the type of shell), but it is on my Mac.

''Now, there used to be a small printing error in Fabrizio's code that may not have been fixed.
It's about the mass-weighting of the branching-space vectors, gradient difference and derivative coupling (the last two modes, given with zero frequencies). The consequence is that the motion of H atoms is exaggerated when you visualise these last two vectors with Gaussview.
The other ones are fine.''

NB the convention for the energy difference is S0 - S1, so if you want the modes that reduce the energy difference, take those that have a large positive frequency (with respect to the energy difference).

=Optimization of a Saddle point on the S0/S1 CHD crossing seam=

Generally, in order to optimize a saddle point structure, one must start from a geometry that is close enough to the quadratic region of such a point. In addition, the Hessian at this initial structure must have a negative eigenvalue, and the corresponding eigevector must be a suitable approximation for the direction connecting the two valleys. When one tries to optimize a saddle point within the intersection space, the initial geometry should also be a point of degeneracy (or near-degeneracy), since the intersection-space Hessian must be computed. Thus it is sometimes useful first to make a single point calculation and then a energy gap optimization between the two states along the gradient difference vector. Input and output files of the single point calculation:

[[Media:CI_trans_com.ogg]]

[[Media:CI_trans_log.ogg]]

Input and output files of the energy gap optimization:

[[Media:CI_trans_E_com.ogg]]

[[Media:CI_trans_E_log.ogg]]

Then it is also quite useful first to make a frequency calculation of this point:

[[Media:CI_trans_E_freq_com.ogg]]

[[Media:CI_trans_E_freq_log.ogg]]

And then one can do with this checkpoint file the optimization of the first-order saddle point:

[[Media:CI_trans_opt_com.ogg]]

[[Media:CI_trans_opt_log.ogg]]

The IOp(1/8) set to one specifies the maximum step size allowed during the optimization and the IOp(5/7) set to 250 specifies the maximum number of iterations. Because this time we want to get a first-order saddle point instead of a minimum also the IOp(1/5) is set minus 2. To prove that this is a first-order saddle point a frequency calculation must be done, which is also necessary for the Computation of the Intersection Space Minimum Energy Path (section 5):

[[Media:CI_trans_opt_freq_com.ogg]]

[[Media:CI_trans_opt_freq_log.ogg]]

The one negative frequency indicates that the point is really a first-order saddle point.

=Computation of the Intersection Space Minimum Energy Path (MEP)=

Currently no standard route exists to compute a minimum energy path limited to the intersection-space. Therefore, as discussed in section 3, a non-standard route has to be specified in the input file in order to perform these calculations. Using ''testrt'' and carefully modifying the output obtained for a standard intrinsic reaction path computation, which is specified by the IRC keyword, one should obtain something similar to:

'''1/...,44=-3,.../1,15;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''6/.../1;''' 
'''7/.../16;''' 
'''1/...,44=-3,../15(2);''' 
'''2/.../2;''' 
'''99//99;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''7/.../16;''' 
'''1/...,44=-3,.../15(-8);''' 
'''2/.../2;''' 
'''6/.../1;''' 
'''99/9=1/99;'''

In order to evaluate the intersection-space minimum energy path, there are added three more options to the existing IOp(1/44):

'''1/44 = -1 Compute the intersection-space minimum energy path in mass-weighted Cartesian coordinates.''' 
'''1/44 = -2 Compute the intersection-space minimum energy path in internal coordinates.''' 
'''1/44 = -3 Compute the intersection-space minimum energy path in mass-weighted internal coordinates.'''

For the following example the intersection-space minimum energy path (MEP) is computed in mass-weighted internal coordinates. For the computation of the MEP you need the transition point structure and the search vector from the optimization of the Saddle point from section 4. The transition point structure is the optimized Saddle point structure, while the search vector is the normal mode of the one negative frequency. But because in the output the normal mode is given in Cartesian coordinates, you first have to transform them in internal coordinates, by adding the normal mode to the optimized Saddle point structure, write out this structure in internal coordinates and calculate e.g with Exel the differences of the internal coordinates in comparison to the optimized Saddle point structure. These differences of the internal coordinates (search vector) have to be add to the transition point structure (in internal coordinates) in a 8F10.6 format in the input file:

[[Media:CI_IRC_com.ogg]]

[[Media:CI_IRC_log.tar.gz.ogg]]

So the calculated MEP leads from the transition point (CI_trans) to the minimum point (CI_min) on the S0/S1 crossing seam.

Resgrp:comp-photo-CHD

2009-03-24T11:30:33Z

Callan: /* Computation of the Intersection Space Minimum Energy Path (MEP) */

=Overview=
In the following sections it will be described how one can calculate the conical intersection seam of CHD (cyclo-hexa-1,3-diene) respectively ''cZc''-HT (CZc-hexa-1,3,5-triene) with the new algorithm. Therefore the

# Optimization of a minimum point on the S0/S1 crossing seam
# Computation of Intersection-Space Frequencies
# Optimization of a Saddle point on the S0/S1 CHD crossing seam
# Computation of the Intersection Space Minimum Energy Path (MEP)

will be demonstrated.

==Development version and Substitutions==
For the calculations you have to use the Gaussian Development version, for the use of the current stable version your jobscript must contain following lines:

'''module load gaussian/devel-modules''' 
'''module load gdvg01_08'''

[[Media:example-jobscript.ogg]]

Also the beginning of your Input-file (.com) has to contain the following lines:

'''%subst l103 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l103''' 
'''%subst l115 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l115''' 
'''%subst l510 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l510''' 
'''%subst l716 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l716''' 
'''%subst l1003 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l1003'''

[[Media:test_com.ogg]]

=Optimization of a minimum point on the S0/S1 crossing seam=
For the optimization of a minimum point with the new algorithm you can use a standard input file. When you want to optimize a conical intersection geometry between the ''q-th'' and the ''(q-1)-th'' electronic state with an active space of ''n'' electrons in ''m'' orbitals the input file must contain the following lines:

'''#P CAS(m,n,nr = q)/[basis set]''' 
'''Opt = Conical''' 
'''IOp(1/5=-1,10/10=500005)''' 

'''[Input Title]''' 

'''[Charge] [Spin Multiplicity]''' 

'''[Geometry]'''

The IOp(1/5) set to minus one specifies that we are attempting to optimize a minimum conical intersection point along the crossing seam. The IOp(10/10) is set to 500005 in order to compute the average gradient, which is used in the new algorithm, by solving the SA-CPMCSCF equations. The following files are the input and output files for the optimization of the 2A1/1A1 conical intersection minimum of CHD:

[[Media:CI_min_com.ogg]]

[[Media:CI_min_log.ogg]]

Here also the IOp(1/16) is set to 5 in order to set the maximum allowable magnitude of the the eigenvalues of the second derative matrix. In order to check if this point is a saddle point or a minimum point a frequency calculation is necessary, which is described in the next section.

=Computation of Intersection-Space Frequencies=
For the calculation of the Intersection-Space Frequencies no keywords exist to run such calculation yet. Therefore, a non-standard root has to be composed. A non-standard root is a complete sequence of links with associated options specified in an input file and read in by Gaussian. It is important to note that the program executes each link in the specified order, therefore extreme caution has to be taken when composing a non-standard route. Thus, a non-standard route is generally created by modifying the sequence of links produced by the standard route most similar to the one desired. This is accomplished most easily with the ''testrt'' utility, for more information [https://www.ch.ic.ac.uk/wiki/index.php/Resgrp:comp-photo-calculations see here]. In computing intersection-space frequencies, ''testrt'' is used to produce the route for a standard state-average CASSCF frequency calculation:

'''#P CAS(n,m,stateaveraged,nroot = q)/[basis set]''' 
'''Nosymm''' 
'''Freq'''

The route obtained with ''testrt'' gives the correct sequence of links in a SA-CASSCF frequency analysis with the corresponding default options. However, in an intersection-space frequency analysis one needs the Hessian of both the intersecting electronic states and the Hessian of the rotated optimized wavefunctions. Create the route using testrt and repeat the sequence of links 5, 8, 11, 10, 6, 7 another two times within the new route. Then add/edit the specific options as below. Thus, the non-standard route used for an intersection-space frequency analysis should have a form similar to:

'''1/.../1,3;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/..,17=41000200,.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,.../3;''' 
'''6/.../1;''' 
'''7/...,45=52/1,2,3,16;''' 
'''5/...,17=41000200,...,97=100/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,97=100/3;''' 
'''6/.../1;''' 
'''7/...,45=51/1,2,3,16;''' 
'''5/...,17=41000200,...,79=1/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,79=1/3;''' 
'''6/.../1;''' 
'''7/...,45=53/1,2,3,16;''' 
'''1/.../3;''' 
''' 99//99;'''

The following files are the input and output files for the frequency calculation of the optimized conical intersection minimum of CHD, computed in the previous section:

[[Media:CI_min_freq_com.ogg]]

[[Media:CI_min_freq_log.ogg]]

With the IOp(1/29) and the IOp(4/5) set to one, the geometry and the initial guess is read from the checkpoint file, which you got from the optimization. The IOp(4/17) and IOp(4/18) are set to six, which specifies the number of electrons and orbitals in the active space, one might need to add more keywords depending on the specific study and system.

So how you can see in the output file there is no negative frequency, therefore the structure of section 2 should be a conical intersection minimum.

=Optimization of a Saddle point on the S0/S1 CHD crossing seam=

Generally, in order to optimize a saddle point structure, one must start from a geometry that is close enough to the quadratic region of such a point. In addition, the Hessian at this initial structure must have a negative eigenvalue, and the corresponding eigevector must be a suitable approximation for the direction connecting the two valleys. When one tries to optimize a saddle point within the intersection space, the initial geometry should also be a point of degeneracy (or near-degeneracy), since the intersection-space Hessian must be computed. Thus it is sometimes useful first to make a single point calculation and then a energy gap optimization between the two states along the gradient difference vector. Input and output files of the single point calculation:

[[Media:CI_trans_com.ogg]]

[[Media:CI_trans_log.ogg]]

Input and output files of the energy gap optimization:

[[Media:CI_trans_E_com.ogg]]

[[Media:CI_trans_E_log.ogg]]

Then it is also quite useful first to make a frequency calculation of this point:

[[Media:CI_trans_E_freq_com.ogg]]

[[Media:CI_trans_E_freq_log.ogg]]

And then one can do with this checkpoint file the optimization of the first-order saddle point:

[[Media:CI_trans_opt_com.ogg]]

[[Media:CI_trans_opt_log.ogg]]

The IOp(1/8) set to one specifies the maximum step size allowed during the optimization and the IOp(5/7) set to 250 specifies the maximum number of iterations. Because this time we want to get a first-order saddle point instead of a minimum also the IOp(1/5) is set minus 2. To prove that this is a first-order saddle point a frequency calculation must be done, which is also necessary for the Computation of the Intersection Space Minimum Energy Path (section 5):

[[Media:CI_trans_opt_freq_com.ogg]]

[[Media:CI_trans_opt_freq_log.ogg]]

The one negative frequency indicates that the point is really a first-order saddle point.

=Computation of the Intersection Space Minimum Energy Path (MEP)=

Currently no standard route exists to compute a minimum energy path limited to the intersection-space. Therefore, as discussed in section 3, a non-standard route has to be specified in the input file in order to perform these calculations. Using ''testrt'' and carefully modifying the output obtained for a standard intrinsic reaction path computation, which is specified by the IRC keyword, one should obtain something similar to:

'''1/...,44=-3,.../1,15;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''6/.../1;''' 
'''7/.../16;''' 
'''1/...,44=-3,../15(2);''' 
'''2/.../2;''' 
'''99//99;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''7/.../16;''' 
'''1/...,44=-3,.../15(-8);''' 
'''2/.../2;''' 
'''6/.../1;''' 
'''99/9=1/99;'''

In order to evaluate the intersection-space minimum energy path, there are added three more options to the existing IOp(1/44):

'''1/44 = -1 Compute the intersection-space minimum energy path in mass-weighted Cartesian coordinates.''' 
'''1/44 = -2 Compute the intersection-space minimum energy path in internal coordinates.''' 
'''1/44 = -3 Compute the intersection-space minimum energy path in mass-weighted internal coordinates.'''

For the following example the intersection-space minimum energy path (MEP) is computed in mass-weighted internal coordinates. For the computation of the MEP you need the transition point structure and the search vector from the optimization of the Saddle point from section 4. The transition point structure is the optimized Saddle point structure, while the search vector is the normal mode of the one negative frequency. But because in the output the normal mode is given in Cartesian coordinates, you first have to transform them in internal coordinates, by adding the normal mode to the optimized Saddle point structure, write out this structure in internal coordinates and calculate e.g with Exel the differences of the internal coordinates in comparison to the optimized Saddle point structure. These differences of the internal coordinates (search vector) have to be add to the transition point structure (in internal coordinates) in a 8F10.6 format in the input file:

[[Media:CI_IRC_com.ogg]]

[[Media:CI_IRC_log.tar.gz.ogg]]

So the calculated MEP leads from the transition point (CI_trans) to the minimum point (CI_min) on the S0/S1 crossing seam.

=Viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling=

The scripts dffx_modes_g01.sh, seam_modes_g01.sh and eta_modes_g01.sh can be used to create log files that gaussview can read to visualise the normal modes and frequencies of the energy difference, the modes of the seam and/or the modes of the bilinear coupling respectively.

First, you need a directory (on your mac or on the cluster) that we will call /dir/.
In here, you put the the scripts (dffx_modes_g01.sh, seam_modes_g01.sh, eta_modes_g01.sh) and a file called template.log, and you create a subdirectory /dir/gaussian_output/ in which you put your log file (say it's called jobname.log).
Then you create a subdirectory /dir/data/.
Then you execute the script this way:
./dffx_modes_g01.sh jobname
and you will get a new file in data that is called jobname_DFFX.log (for energy difference frequencies) or jobname_GV.log (for seam modes) and that can be read by GaussView.

N.B.: ./ might not be needed on the cluster (also this may depend on the type of shell), but it is on my Mac.

''Now, there used to be a small printing error in Fabrizio's code that may not have been fixed.
It's about the mass-weighting of the branching-space vectors, gradient difference and derivative coupling (the last two modes, given with zero frequencies). The consequence is that the motion of H atoms is exaggerated when you visualise these last two vectors with Gaussview.
The other ones are fine.''

NB the convention for the energy difference is S0 - S1, so if you want the modes that reduce the energy difference, take those that have a large positive frequency (with respect to the energy difference).

Resgrp:comp-photo-CHD

2009-03-24T11:29:26Z

Callan:

=Overview=
In the following sections it will be described how one can calculate the conical intersection seam of CHD (cyclo-hexa-1,3-diene) respectively ''cZc''-HT (CZc-hexa-1,3,5-triene) with the new algorithm. Therefore the

# Optimization of a minimum point on the S0/S1 crossing seam
# Computation of Intersection-Space Frequencies
# Optimization of a Saddle point on the S0/S1 CHD crossing seam
# Computation of the Intersection Space Minimum Energy Path (MEP)

will be demonstrated.

==Development version and Substitutions==
For the calculations you have to use the Gaussian Development version, for the use of the current stable version your jobscript must contain following lines:

'''module load gaussian/devel-modules''' 
'''module load gdvg01_08'''

[[Media:example-jobscript.ogg]]

Also the beginning of your Input-file (.com) has to contain the following lines:

'''%subst l103 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l103''' 
'''%subst l115 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l115''' 
'''%subst l510 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l510''' 
'''%subst l716 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l716''' 
'''%subst l1003 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l1003'''

[[Media:test_com.ogg]]

=Optimization of a minimum point on the S0/S1 crossing seam=
For the optimization of a minimum point with the new algorithm you can use a standard input file. When you want to optimize a conical intersection geometry between the ''q-th'' and the ''(q-1)-th'' electronic state with an active space of ''n'' electrons in ''m'' orbitals the input file must contain the following lines:

'''#P CAS(m,n,nr = q)/[basis set]''' 
'''Opt = Conical''' 
'''IOp(1/5=-1,10/10=500005)''' 

'''[Input Title]''' 

'''[Charge] [Spin Multiplicity]''' 

'''[Geometry]'''

The IOp(1/5) set to minus one specifies that we are attempting to optimize a minimum conical intersection point along the crossing seam. The IOp(10/10) is set to 500005 in order to compute the average gradient, which is used in the new algorithm, by solving the SA-CPMCSCF equations. The following files are the input and output files for the optimization of the 2A1/1A1 conical intersection minimum of CHD:

[[Media:CI_min_com.ogg]]

[[Media:CI_min_log.ogg]]

Here also the IOp(1/16) is set to 5 in order to set the maximum allowable magnitude of the the eigenvalues of the second derative matrix. In order to check if this point is a saddle point or a minimum point a frequency calculation is necessary, which is described in the next section.

=Computation of Intersection-Space Frequencies=
For the calculation of the Intersection-Space Frequencies no keywords exist to run such calculation yet. Therefore, a non-standard root has to be composed. A non-standard root is a complete sequence of links with associated options specified in an input file and read in by Gaussian. It is important to note that the program executes each link in the specified order, therefore extreme caution has to be taken when composing a non-standard route. Thus, a non-standard route is generally created by modifying the sequence of links produced by the standard route most similar to the one desired. This is accomplished most easily with the ''testrt'' utility, for more information [https://www.ch.ic.ac.uk/wiki/index.php/Resgrp:comp-photo-calculations see here]. In computing intersection-space frequencies, ''testrt'' is used to produce the route for a standard state-average CASSCF frequency calculation:

'''#P CAS(n,m,stateaveraged,nroot = q)/[basis set]''' 
'''Nosymm''' 
'''Freq'''

The route obtained with ''testrt'' gives the correct sequence of links in a SA-CASSCF frequency analysis with the corresponding default options. However, in an intersection-space frequency analysis one needs the Hessian of both the intersecting electronic states and the Hessian of the rotated optimized wavefunctions. Create the route using testrt and repeat the sequence of links 5, 8, 11, 10, 6, 7 another two times within the new route. Then add/edit the specific options as below. Thus, the non-standard route used for an intersection-space frequency analysis should have a form similar to:

'''1/.../1,3;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/..,17=41000200,.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,.../3;''' 
'''6/.../1;''' 
'''7/...,45=52/1,2,3,16;''' 
'''5/...,17=41000200,...,97=100/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,97=100/3;''' 
'''6/.../1;''' 
'''7/...,45=51/1,2,3,16;''' 
'''5/...,17=41000200,...,79=1/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,79=1/3;''' 
'''6/.../1;''' 
'''7/...,45=53/1,2,3,16;''' 
'''1/.../3;''' 
''' 99//99;'''

The following files are the input and output files for the frequency calculation of the optimized conical intersection minimum of CHD, computed in the previous section:

[[Media:CI_min_freq_com.ogg]]

[[Media:CI_min_freq_log.ogg]]

With the IOp(1/29) and the IOp(4/5) set to one, the geometry and the initial guess is read from the checkpoint file, which you got from the optimization. The IOp(4/17) and IOp(4/18) are set to six, which specifies the number of electrons and orbitals in the active space, one might need to add more keywords depending on the specific study and system.

So how you can see in the output file there is no negative frequency, therefore the structure of section 2 should be a conical intersection minimum.

=Optimization of a Saddle point on the S0/S1 CHD crossing seam=

Generally, in order to optimize a saddle point structure, one must start from a geometry that is close enough to the quadratic region of such a point. In addition, the Hessian at this initial structure must have a negative eigenvalue, and the corresponding eigevector must be a suitable approximation for the direction connecting the two valleys. When one tries to optimize a saddle point within the intersection space, the initial geometry should also be a point of degeneracy (or near-degeneracy), since the intersection-space Hessian must be computed. Thus it is sometimes useful first to make a single point calculation and then a energy gap optimization between the two states along the gradient difference vector. Input and output files of the single point calculation:

[[Media:CI_trans_com.ogg]]

[[Media:CI_trans_log.ogg]]

Input and output files of the energy gap optimization:

[[Media:CI_trans_E_com.ogg]]

[[Media:CI_trans_E_log.ogg]]

Then it is also quite useful first to make a frequency calculation of this point:

[[Media:CI_trans_E_freq_com.ogg]]

[[Media:CI_trans_E_freq_log.ogg]]

And then one can do with this checkpoint file the optimization of the first-order saddle point:

[[Media:CI_trans_opt_com.ogg]]

[[Media:CI_trans_opt_log.ogg]]

The IOp(1/8) set to one specifies the maximum step size allowed during the optimization and the IOp(5/7) set to 250 specifies the maximum number of iterations. Because this time we want to get a first-order saddle point instead of a minimum also the IOp(1/5) is set minus 2. To prove that this is a first-order saddle point a frequency calculation must be done, which is also necessary for the Computation of the Intersection Space Minimum Energy Path (section 5):

[[Media:CI_trans_opt_freq_com.ogg]]

[[Media:CI_trans_opt_freq_log.ogg]]

The one negative frequency indicates that the point is really a first-order saddle point.

=Computation of the Intersection Space Minimum Energy Path (MEP)=

Currently no standard route exists to compute a minimum energy path limited to the intersection-space. Therefore, as discussed in section 3, a non-standard route has to be specified in the input file in order to perform these calculations. Using ''testrt'' and carefully modifying the output obtained for a standard intrinsic reaction path computation, which is specified by the IRC keyword, one should obtain something similar to:

'''1/...,44=-3,.../1,15;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''6/.../1;''' 
'''7/.../16;''' 
'''1/...,44=-3,../15(2);''' 
'''2/.../2;''' 
'''99//99;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''7/.../16;''' 
'''1/...,44=-3,.../15(-8);''' 
'''2/.../2;''' 
'''6/.../1;''' 
'''99/9=1/99;'''

In order to evaluate the intersection-space minimum energy path, there are added three more options to the existing IOp(1/44):

'''1/44 = -1 Compute the intersection-space minimum energy path in mass-weighted Cartesian coordinates.''' 
'''1/44 = -2 Compute the intersection-space minimum energy path in internal coordinates.''' 
'''1/44 = -3 Compute the intersection-space minimum energy path in mass-weighted internal coordinates.'''

For the following example the intersection-space minimum energy path (MEP) is computed in mass-weighted internal coordinates. For the computation of the MEP you need the transition point structure and the search vector from the optimization of the Saddle point from section 4. The transition point structure is the optimized Saddle point structure, while the search vector is the normal mode of the one negative frequency. But because in the output the normal mode is given in Cartesian coordinates, you first have to transform them in internal coordinates, by adding the normal mode to the optimized Saddle point structure, write out this structure in internal coordinates and calculate e.g with Exel the differences of the internal coordinates in comparison to the optimized Saddle point structure. These differences of the internal coordinates (search vector) have to be add to the transition point structure (in internal coordinates) in a 8F10.6 format in the input file:

[[Media:CI_IRC_com.ogg]]

[[Media:CI_IRC_log.tar.gz.ogg]]

So the calculated MEP leads from the transition point (CI_trans) to the minimum point (CI_min) on the S0/S1 crossing seam.

=Computation of the Intersection Space Minimum Energy Path (MEP)=

Resgrp:comp-photo-calculations

2009-03-24T11:28:27Z

Callan: /* Viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling */

Resgrp:comp-photo-calculations

2009-03-24T11:26:26Z

Callan: /* Viewing the normal modes and frequencies of the energy difference; the modes of the seam; and the modes of the bilinear coupling */

Resgrp:comp-photo-calculations

2009-03-24T11:21:15Z

Callan:

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-03-24T11:06:13Z

Callan: /* '''Basic use of the MCTDH package''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection (or other geometry) described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the structure in coin.log need not necessarily be a true conical intersection: this point is only used for performing the diabatisation. Thus the diabatisation will be exact at this point and will become more approximate the further you are from it (on the PES). If you wish to use a point that is not a conical intersection, simply run a conical intersection optimisation (with only a single step) on the desired geometry. This will create a file with the same layout as a conical intersection optimisation output file (mctdh looks for certain things in this file so if some other type of .log file were used instead, it might not contain the required information). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.] In 90.35tmp this is ok. In 90.4X it will also be fixed.

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

Resgrp:comp-photo-dyn/mctdh90.31dv/input

2009-03-24T11:03:29Z

Callan: /* MCTDH versions */

= Creating Input for Dynamics Calculations =

== MCTDH versions ==

* Current version (mctdh90dev): The input required for the dynamics calculation is an optimised ground state structure and an optimised conical intersection in the appropriate orientation. [These two structures are used in the diabatic transformation. They need not necessarily correspond to the Franck-Condon and minimum conical intersection geometries. However, these structures are usually good places to start and so most of this tutorial will assume that these are the references that have been chosen.] The ground state structure must have been optimised with state averaged orbitals. These orbitals must be "cleaned" and the high precision frequencies must have been calculated.

* Development version (mctdh90.31dev): The only input required for the dynamics calculation is an optimised ground state structure and an optimised conical intersection (the rotation will be "automatic"). [These two structures are used in the diabatic transformation. They need not necessarily correspond to the Franck-Condon and minimum conical intersection geometries. However, these structures are usually good places to start and so most of this tutorial will assume that these are the references that have been chosen.] Again, the ground state structure must have been optimised with state averaged orbitals. These orbitals must be "cleaned" and finally high precision frequencies must be calculated.

* The main objective of this tutorial is learn how to run dynamics calculations, thus we will give you the optimised geometries in the appropiate rotation. (A description of how to rotate a structure will follow in due course)

== State Averaged Orbitals==

Discussion on the necessity of using state averaged orbitals to go here. NEED TO REPRESENT BOTH GROUND AND EXCITED STATES AT THE SAME TIME. I AM NOT CLEAR WHY YOU ARE USING STATE AVERAGING AT EQUILIBRIUM GEOMETRY. NORMALLY THIS WOULD NOT BE A SENSIBLE THING TO DO.

= Gaussian Calculations - CASSCF =

== '''1. Generate a starting geometry.''' ==

First of all, we need a set of initial orbitals for the CASSCF calculation, which can be obtained from a simple restricted Hartree-Fock (RHF/STO-3G) optimization. It is useful in systems with high symmetry to start with the molecule in the standard orientation and from a symmetrised geometry. This can be achieved by running a Gaussian calculation without the nosymm keyword and using the geometry returned by this calculation.

* NB You should use the structures given in this tutorial because they are oriented appropriately.

[[Media:buta-s-orient.gjf]]

[[Media:buta-s-orient.log]]

== '''2. Identify the Orbitals Required for the CASSCF Calculation''' ==

Use the geometry from 1. Calculate the HF orbitals with a tight basis set e.g. STO-3G (so that it is easier to identify the relevant orbitals for CASSCF).

Keywords: '''HF/STO-3G pop=full nosymm geom=check'''

* Nosymm is required because every time a calculation is run on the molecule with a different symmetry Gaussian reorients the molecule for that particular point group and will destroy the active space. Nosymm disables this feature.
* Pop=full prints out the orbitals.
* Inspect the orbitals. Select those required for the CASSCF.

[[Media:buta-hf.gjf]]

[[Media:buta-hf.log]]

[[Media:buta-hf.fchk]]

== '''3. Identify the State Averaged Orbitals for the Ground State''' ==

An orbital inspection using any visualization software before performing any CASSCF calculation is essential to identify which orbitals make up the chosen active space. In some cases it may be necessary to use '''guess=alter''' to change the order of the orbitals to make sure the optimisation (see step 4) proceeds with the correct orbitals. Gaussian assumes that the electrons specified in a CASSCF calculation come from the highest occupied orbitals in the initial guess and then takes the remaining orbitals as the lowest virtuals of this guess.

* In this example, the relevant orbitals are the four pi orbitals, which contain four electrons (so the calculation is 4,4). The four orbitals that form the pi molecular orbitals are 14, 15, 16 and 17, thus we do not have to worry about swapping orbitals with the keword ''alter''.

Use the orbitals chosen in 2. (i.e. use the .chk from 2.) Use the final geometry from 2.

Keywords: '''CAS(4,4,nroot=2,stateaverage) STO-3G nosymm IOP(5/97=100,10/97=100) guess=read'''

Here, the weights of each state must be listed explicitly. The weights are 0.5 and 0.5. These must be specified by typing 0.5 followed by 7 spaces then 0.5 (on the same line) (The Gaussian program reads 10 characters (inc spaces) for the first weight and another 10 characters for the second weight. Thus the 7 spaces plus the three characters "0", "." and "5" make up the first 10 characters before the second weight is read.)

* The IOp (5/97=100,10/97=100) tells the program to switch the order of the two states. This is so that we calculate the ground state rather than the excited state. (Gaussian CASSCF calculations always perform optimisations on the highest state listed, so by switching the order we force optimisation of what is actually the lower state.)
* Nroot=2 specifies the ''first'' excited state so the orbitals will averaged over the ground state and the first excited state.

* Inspect the orbitals. Select those required for the CASSCF optimisation. The relevant orbitals are still 14, 15, 16 and 17.

[[Media:buta-orbs-sa.gjf]]

[[Media:buta-orbs-sa.log]]

[[Media:buta-orbs-sa.fchk]]

== '''4. Perform a CASSCF Optimisation on the Ground State with the State Averaged Orbitals''' ==

Use the orbitals chosen in 3. Use the .chk from 3.

Keywords: '''opt=conical pop=full CAS(4,4,nroot=2,stateaverage) STO-3G nosymm IOP(10/10=700005) IOP(5/97=100,10/97=100) geom=checkpoint guess=read'''

N.B. This is not a conical intersection optimisation! However, the keyword opt=conical specifies automatically that the populations of the two states will each be 0.5. Thus there is no need to specify the populations manually. The initial '7' in IOp (10/10=700005) specifies that the calculation should be an optimisation to a minimum (rather than a conical intersection). The final '5' ensures that the orbital rotation derivative contributions from the CP-MC-SCF equations are included. (This is necessary and is usually the default. However, in the current version of Gaussian, the combination of '''opt''' and '''stateaverage''' excludes this).
Stateaverage is the default for opt=conical.
Nroot=2 is the default for opt=conical.
Do not include the keyword '''freq''' in the optimisation. (This combination of IOps does not allow '''opt''' and '''freq''' to be keywords in the same job.)

[[Media:buta-cas.gjf]]

[[Media:buta-cas.log]]

== '''5. "Clean" the Orbitals''' ==

In this case, all the orbitals in the active space are pure pi orbitals. Due to small numerical inaccuracies, the final orbitals may include small contributions from other (non-pi) orbitals. The aim of this step is to remove these contributions so that the active space consists (in this example) only of contributions from the C 2PY atomic orbitals. The four relevant orbitals are occupied orbitals 14 and 15 and virtual orbitals 16 and 17. In fact, they are already clean in this example. Verify this by inspection of the "Molecular Orbital Coefficients" in the population analysis.

In other cases, multiple optimisations may be necessary to clean the orbitals:

Open the file in GaussView, and Edit/Symmetrize. Use this symmetrised geometry as a starting geometry for another optimsation as in 4 (including the keyword '''nosymm''').
Use the .chk from 4.
Re-run the optimisation exactly as in 4.

''Ideally here we include the keyword '''opt=(maxstep=1)'''. This should ensure that the optimisation takes the smallest possible step: we already know that the geometry is very close to the minimum and we need to prevent any significant re-orientation that might occur if large steps are taken. However, this does not seem to work (at least with g03).''

Repeat until the orbitals are clean.

== '''6. Calculate the (High Precision) Vibrational Modes for the Ground State ''with State Averaged Orbitals''''' ==

Use the .chk and the geometry from 5. The geometry must be specified explicitly. (With this combination of IOPs, Gaussian extracts the wrong geometry from the .chk file if '''geom=checkpoint''' is specified.)

Keywords: '''CAS(4,4,nroot=2) STO-3G freq=hpmodes guess=read IOP(5/17=41000200,10/10=700007) IOP(5/97=100,10/97=100)'''

The IOp (5/17=41000200,10/10=700007): includes the CP-MC-SCF correction (as above) (for a frequency calculation); and specifies state averaged orbitals. Do not include the keyword '''stateaverage''' with '''freq''' (the current version of Gaussian does not support this). Freq=hpmodes tells Gaussian to print the vibrational modes to 5 decimal places. As before, the IOp (5/97=100,10/97=100) forces calculation of the ground state. Do not use the keyword nosymm here. (Nosymm may prevent Gaussian from identifying the symmetries of the orbitals.)

[[Media:buta-hpfreq.gjf]]

[[Media:buta-hpfreq.log]]

== '''7. The Conical Intersection''' ==

One strategy for locating the conical intersection is to calculate the Frank-Condon point and run an optimisation from there, following (one of) the negative frequency(ies).

=== 7a. The Frank-Condon Point ===

Use the .chk from 4. Using the same orbitals perform a single point energy calculation for the first excited state.

Keywords: '''CAS(4,4,nroot=2,stateaverage) STO-3G pop=full nosymm guess=read geom=checkpoint'''

As in 3, the weights of each state must be listed explicitly. The weights are 0.5 and 0.5. These must be specified by typing 0.5 followed by 7 spaces then 0.5 (on the same line) ''(The Gaussian program reads 10 characters (inc spaces) for the first weight and another 10 characters for the second weight. Thus the 7 spaces plus the three characters "0", "." and "5" make up the first 10 characters before the second weight is read.)''

[[Media:buta-fc.gjf]]

[[Media:buta-fc.log]]

=== 7b. Optimise the Conical Intersection ===

Use the .chk from 7a. Distort the geometry to break the symmetry.
A suggested distortion is to increase the C-C-C-C dihedral angle to 45° by twisting one of the terminal carbons out of the plane of the other atoms (be careful to move only the CH2 group, not the hydrogen on the adjacent carbon). Then increase the H-C-C-C dihedral angles of both the terminal CH2 groups to 70°, in a disrotatory direction. A conical intersection optimisation should now locate a conical intersection.

Keywords: '''CAS(4,4,nroot=2) STO-3G opt=conical nosymm guess=read pop=full'''

Stateaverage is the default for opt=conical.
Nroot=2 is the default for opt=conical.

[[Media:buta-dis14570ci.gjf]]

[[Media:buta-dis14570ci.log]]

=== [[Resgrp:comp-photo-dyn/mctdh90.31dv|back]] ===

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-03-24T10:49:45Z

Callan: /* '''Gaussian Output to be Used as Input for the Dynamics Program''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the structure in coin.log need not necessarily be a true conical intersection: this point is only used for performing the diabatisation. Thus the diabatisation will be exact at this point and will become more approximate the further you are from it (on the PES). If you wish to use a point that is not a conical intersection, simply run a conical intersection optimisation (with only a single step) on the desired geometry. This will create a file with the same layout as a conical intersection optimisation output file (mctdh looks for certain things in this file so if some other type of .log file were used instead, it might not contain the required information). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.] In 90.35tmp this is ok. In 90.4X it will also be fixed.

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-03-24T10:41:49Z

Callan: /* '''Gaussian Output to be Used as Input for the Dynamics Program''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the structure in coin.log need not necessarily be a true conical intersection: this point is used to perform the diabatisation. Thus the diabatisation will be exact at this point and the diabatisation will be become more approximate the further you are from this point. NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.] In 90.35tmp this is ok. In 90.4X it will also be fixed.

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-02-27T16:37:59Z

Callan: /* '''Current Known Bugs''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.] In 90.35tmp this is ok. In 90.4X it will also be fixed.

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-02-27T16:37:13Z

Callan: /* '''Current Known Bugs''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems). In 90.35tmp this is ok. In 90.4X it will also be fixed.

Total energy:

1) The total energy is sometimes "artificially" increased by a lot. If so, try a different integrator or play around with the timestep (may need to get larger or smaller). Or try increasing scf convergence to 10-12.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.]

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-02-27T16:29:55Z

Callan: /* '''Questions and Modifications to be made to this wiki''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems).

Total energy:

1) The total energy can be "artificially" increased by much. If so, try a different integrator.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.]

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state? To study GS rxns; chemiluminesence (eg glowworms).
*In terms of Delta-E, how much is too much? ca1eV but shape of E-tot vs time is important: discontiunities or v flat then steep increase are less reliable than smooth gradual increases.
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files? G03 is fine. we don't know about gdvg03 but we don't care because we probablly won't use it.

Resgrp:comp-photo-CHD

2009-02-27T11:44:53Z

Callan: /* Computation of Intersection-Space Frequencies */

=Overview=
In the following sections it will be described how one can calculate the conical intersection seam of CHD (cyclo-hexa-1,3-diene) respectively ''cZc''-HT (CZc-hexa-1,3,5-triene) with the new algorithm. Therefore the

# Optimization of a minimum point on the S0/S1 crossing seam
# Computation of Intersection-Space Frequencies
# Optimization of a Saddle point on the S0/S1 CHD crossing seam
# Computation of the Intersection Space Minimum Energy Path (MEP)

will be demonstrated.

==Development version and Substitutions==
For the calculations you have to use the Gaussian Development version, for the use of the current stable version your jobscript must contain following lines:

'''module load gaussian/devel-modules''' 
'''module load gdvg01_08'''

[[Media:example-jobscript.ogg]]

Also the beginning of your Input-file (.com) has to contain the following lines:

'''%subst l103 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l103''' 
'''%subst l115 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l115''' 
'''%subst l510 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l510''' 
'''%subst l716 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l716''' 
'''%subst l1003 /home/gaussian-devel/gaussiandvg01_pgi_lindafix/gdv_fabrizio/l1003'''

[[Media:test_com.ogg]]

=Optimization of a minimum point on the S0/S1 crossing seam=
For the optimization of a minimum point with the new algorithm you can use a standard input file. When you want to optimize a conical intersection geometry between the ''q-th'' and the ''(q-1)-th'' electronic state with an active space of ''n'' electrons in ''m'' orbitals the input file must contain the following lines:

'''#P CAS(m,n,nr = q)/[basis set]''' 
'''Opt = Conical''' 
'''IOp(1/5=-1,10/10=500005)''' 

'''[Input Title]''' 

'''[Charge] [Spin Multiplicity]''' 

'''[Geometry]'''

The IOp(1/5) set to minus one specifies that we are attempting to optimize a minimum conical intersection point along the crossing seam. The IOp(10/10) is set to 500005 in order to compute the average gradient, which is used in the new algorithm, by solving the SA-CPMCSCF equations. The following files are the input and output files for the optimization of the 2A1/1A1 conical intersection minimum of CHD:

[[Media:CI_min_com.ogg]]

[[Media:CI_min_log.ogg]]

Here also the IOp(1/16) is set to 5 in order to set the maximum allowable magnitude of the the eigenvalues of the second derative matrix. In order to check if this point is a saddle point or a minimum point a frequency calculation is necessary, which is described in the next section.

=Computation of Intersection-Space Frequencies=
For the calculation of the Intersection-Space Frequencies no keywords exist to run such calculation yet. Therefore, a non-standard root has to be composed. A non-standard root is a complete sequence of links with associated options specified in an input file and read in by Gaussian. It is important to note that the program executes each link in the specified order, therefore extreme caution has to be taken when composing a non-standard route. Thus, a non-standard route is generally created by modifying the sequence of links produced by the standard route most similar to the one desired. This is accomplished most easily with the ''testrt'' utility, for more information [https://www.ch.ic.ac.uk/wiki/index.php/Resgrp:comp-photo-calculations see here]. In computing intersection-space frequencies, ''testrt'' is used to produce the route for a standard state-average CASSCF frequency calculation:

'''#P CAS(n,m,stateaveraged,nroot = q)/[basis set]''' 
'''Nosymm''' 
'''Freq'''

The route obtained with ''testrt'' gives the correct sequence of links in a SA-CASSCF frequency analysis with the corresponding default options. However, in an intersection-space frequency analysis one needs the Hessian of both the intersecting electronic states and the Hessian of the rotated optimized wavefunctions. Create the route using testrt and repeat the sequence of links 5, 8, 11, 10, 6, 7 another two times within the new route. Then add/edit the specific options as below. Thus, the non-standard route used for an intersection-space frequency analysis should have a form similar to:

'''1/.../1,3;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/..,17=41000200,.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,.../3;''' 
'''6/.../1;''' 
'''7/...,45=52/1,2,3,16;''' 
'''5/...,17=41000200,...,97=100/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,97=100/3;''' 
'''6/.../1;''' 
'''7/...,45=51/1,2,3,16;''' 
'''5/...,17=41000200,...,79=1/10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/...,10=600007,...,79=1/3;''' 
'''6/.../1;''' 
'''7/...,45=53/1,2,3,16;''' 
'''1/.../3;''' 
''' 99//99;'''

The following files are the input and output files for the frequency calculation of the optimized conical intersection minimum of CHD, computed in the previous section:

[[Media:CI_min_freq_com.ogg]]

[[Media:CI_min_freq_log.ogg]]

With the IOp(1/29) and the IOp(4/5) set to one, the geometry and the initial guess is read from the checkpoint file, which you got from the optimization. The IOp(4/17) and IOp(4/18) are set to six, which specifies the number of electrons and orbitals in the active space, one might need to add more keywords depending on the specific study and system.

So how you can see in the output file there is no negative frequency, therefore the structure of section 2 should be a conical intersection minimum.

=Optimization of a Saddle point on the S0/S1 CHD crossing seam=

Generally, in order to optimize a saddle point structure, one must start from a geometry that is close enough to the quadratic region of such a point. In addition, the Hessian at this initial structure must have a negative eigenvalue, and the corresponding eigevector must be a suitable approximation for the direction connecting the two valleys. When one tries to optimize a saddle point within the intersection space, the initial geometry should also be a point of degeneracy (or near-degeneracy), since the intersection-space Hessian must be computed. Thus it is sometimes useful first to make a single point calculation and then a energy gap optimization between the two states along the gradient difference vector. Input and output files of the single point calculation:

[[Media:CI_trans_com.ogg]]

[[Media:CI_trans_log.ogg]]

Input and output files of the energy gap optimization:

[[Media:CI_trans_E_com.ogg]]

[[Media:CI_trans_E_log.ogg]]

Then it is also quite useful first to make a frequency calculation of this point:

[[Media:CI_trans_E_freq_com.ogg]]

[[Media:CI_trans_E_freq_log.ogg]]

And then one can do with this checkpoint file the optimization of the first-order saddle point:

[[Media:CI_trans_opt_com.ogg]]

[[Media:CI_trans_opt_log.ogg]]

The IOp(1/8) set to one specifies the maximum step size allowed during the optimization and the IOp(5/7) set to 250 specifies the maximum number of iterations. Because this time we want to get a first-order saddle point instead of a minimum also the IOp(1/5) is set minus 2. To prove that this is a first-order saddle point a frequency calculation must be done, which is also necessary for the Computation of the Intersection Space Minimum Energy Path (section 5):

[[Media:CI_trans_opt_freq_com.ogg]]

[[Media:CI_trans_opt_freq_log.ogg]]

The one negative frequency indicates that the point is really a first-order saddle point.

=Computation of the Intersection Space Minimum Energy Path (MEP)=

Currently no standard route exists to compute a minimum energy path limited to the intersection-space. Therefore, as discussed in section 3, a non-standard route has to be specified in the input file in order to perform these calculations. Using ''testrt'' and carefully modifying the output obtained for a standard intrinsic reaction path computation, which is specified by the IRC keyword, one should obtain something similar to:

'''1/...,44=-3,.../1,15;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''6/.../1;''' 
'''7/.../16;''' 
'''1/...,44=-3,../15(2);''' 
'''2/.../2;''' 
'''99//99;''' 
'''2/.../2;''' 
'''3/.../1,2,3;''' 
'''4/.../1,5;''' 
'''5/.../10;''' 
'''8/.../1;''' 
'''11/.../1;''' 
'''10/10=500005,.../3;''' 
'''7/.../16;''' 
'''1/...,44=-3,.../15(-8);''' 
'''2/.../2;''' 
'''6/.../1;''' 
'''99/9=1/99;'''

In order to evaluate the intersection-space minimum energy path, there are added three more options to the existing IOp(1/44):

'''1/44 = -1 Compute the intersection-space minimum energy path in mass-weighted Cartesian coordinates.''' 
'''1/44 = -2 Compute the intersection-space minimum energy path in internal coordinates.''' 
'''1/44 = -3 Compute the intersection-space minimum energy path in mass-weighted internal coordinates.'''

For the following example the intersection-space minimum energy path (MEP) is computed in mass-weighted internal coordinates. For the computation of the MEP you need the transition point structure and the search vector from the optimization of the Saddle point from section 4. The transition point structure is the optimized Saddle point structure, while the search vector is the normal mode of the one negative frequency. But because in the output the normal mode is given in Cartesian coordinates, you first have to transform them in internal coordinates, by adding the normal mode to the optimized Saddle point structure, write out this structure in internal coordinates and calculate e.g with Exel the differences of the internal coordinates in comparison to the optimized Saddle point structure. These differences of the internal coordinates (search vector) have to be add to the transition point structure (in internal coordinates) in a 8F10.6 format in the input file:

[[Media:CI_IRC_com.ogg]]

[[Media:CI_IRC_log.tar.gz.ogg]]

So the calculated MEP leads from the transition point (CI_trans) to the minimum point (CI_min) on the S0/S1 crossing seam.

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-02-13T11:32:18Z

Callan: /* '''Modifications to be made to the files before running the dynamics''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems).

Total energy:

1) The total energy can be "artificially" increased by much. If so, try a different integrator.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.]

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state?
*Need a section on using the database.
*In terms of Delta-E, how much is too much?
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files?

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-02-12T11:23:16Z

Callan: /* '''Current Known Bugs''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01_08).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:

It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems).

Total energy:

1) The total energy can be "artificially" increased by much. If so, try a different integrator.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.]

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":

Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

State Averaging:

To increase the threshold above which stateaveraging is turned off, increase the default value of 10 (to e.g. 50) in the line ''ddregions'' in the OPERATOR-SECTION of the .inp file.

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state?
*Need a section on using the database.
*In terms of Delta-E, how much is too much?
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files?

Resgrp:comp-photo-dyn/mctdh90.31dv/input

2009-02-11T17:05:49Z

Callan: /* '''4. Perform a CASSCF Optimisation on the Ground State with the State Averaged Orbitals''' */

= Creating Input for Dynamics Calculations =

== MCTDH versions ==

* Current version (mctdh90dev): The input required for the dynamics calculation is an optimised ground state structure and an optimised conical intersection in the appropriate orientation . The ground state structure must have been optimised with state averaged orbitals. These orbitals must be "cleaned" and the high precision frequencies must have been calculated.

* Development version (mctdh90.31dev): The only input required for the dynamics calculation is an optimised ground state structure and an optimised conical intersection (the rotation will be "automatic"). Again, the ground state structure must have been optimised with state averaged orbitals. These orbitals must be "cleaned" and finally high precision frequencies must be calculated.

* The main objective of this tutorial is learn how to run dynamics calculations, thus we will give you the optimised geometries in the appropiate rotation. (A description of how to rotate a structure will follow in due course)

== State Averaged Orbitals==

Discussion on the necessity of using state averaged orbitals to go here. NEED TO REPRESENT BOTH GROUND AND EXCITED STATES AT THE SAME TIME. I AM NOT CLEAR WHY YOU ARE USING STATE AVERAGING AT EQUILIBRIUM GEOMETRY. NORMALLY THIS WOULD NOT BE A SENSIBLE THING TO DO.

= Gaussian Calculations - CASSCF =

== '''1. Generate a starting geometry.''' ==

First of all, we need a set of initial orbitals for the CASSCF calculation, which can be obtained from a simple restricted Hartree-Fock (RHF/STO-3G) optimization. It is useful in systems with high symmetry to start with the molecule in the standard orientation and from a symmetrised geometry. This can be achieved by running a Gaussian calculation without the nosymm keyword and using the geometry returned by this calculation.

* NB You should use the structures given in this tutorial because they are oriented appropriately.

[[Media:buta-s-orient.gjf]]

[[Media:buta-s-orient.log]]

== '''2. Identify the Orbitals Required for the CASSCF Calculation''' ==

Use the geometry from 1. Calculate the HF orbitals with a tight basis set e.g. STO-3G (so that it is easier to identify the relevant orbitals for CASSCF).

Keywords: '''HF/STO-3G pop=full nosymm geom=check'''

* Nosymm is required because every time a calculation is run on the molecule with a different symmetry Gaussian reorients the molecule for that particular point group and will destroy the active space. Nosymm disables this feature.
* Pop=full prints out the orbitals.
* Inspect the orbitals. Select those required for the CASSCF.

[[Media:buta-hf.gjf]]

[[Media:buta-hf.log]]

[[Media:buta-hf.fchk]]

== '''3. Identify the State Averaged Orbitals for the Ground State''' ==

An orbital inspection using any visualization software before performing any CASSCF calculation is essential to identify which orbitals make up the chosen active space. In some cases it may be necessary to use '''guess=alter''' to change the order of the orbitals to make sure the optimisation (see step 4) proceeds with the correct orbitals. Gaussian assumes that the electrons specified in a CASSCF calculation come from the highest occupied orbitals in the initial guess and then takes the remaining orbitals as the lowest virtuals of this guess.

* In this example, the relevant orbitals are the four pi orbitals, which contain four electrons (so the calculation is 4,4). The four orbitals that form the pi molecular orbitals are 14, 15, 16 and 17, thus we do not have to worry about swapping orbitals with the keword ''alter''.

Use the orbitals chosen in 2. (i.e. use the .chk from 2.) Use the final geometry from 2.

Keywords: '''CAS(4,4,nroot=2,stateaverage) STO-3G nosymm IOP(5/97=100,10/97=100) guess=read'''

Here, the weights of each state must be listed explicitly. The weights are 0.5 and 0.5. These must be specified by typing 0.5 followed by 7 spaces then 0.5 (on the same line) (The Gaussian program reads 10 characters (inc spaces) for the first weight and another 10 characters for the second weight. Thus the 7 spaces plus the three characters "0", "." and "5" make up the first 10 characters before the second weight is read.)

* The IOp (5/97=100,10/97=100) tells the program to switch the order of the two states. This is so that we calculate the ground state rather than the excited state. (Gaussian CASSCF calculations always perform optimisations on the highest state listed, so by switching the order we force optimisation of what is actually the lower state.)
* Nroot=2 specifies the ''first'' excited state so the orbitals will averaged over the ground state and the first excited state.

* Inspect the orbitals. Select those required for the CASSCF optimisation. The relevant orbitals are still 14, 15, 16 and 17.

[[Media:buta-orbs-sa.gjf]]

[[Media:buta-orbs-sa.log]]

[[Media:buta-orbs-sa.fchk]]

== '''4. Perform a CASSCF Optimisation on the Ground State with the State Averaged Orbitals''' ==

Use the orbitals chosen in 3. Use the .chk from 3.

Keywords: '''opt=conical pop=full CAS(4,4,nroot=2,stateaverage) STO-3G nosymm IOP(10/10=700005) IOP(5/97=100,10/97=100) geom=checkpoint guess=read'''

N.B. This is not a conical intersection optimisation! However, the keyword opt=conical specifies automatically that the populations of the two states will each be 0.5. Thus there is no need to specify the populations manually. The initial '7' in IOp (10/10=700005) specifies that the calculation should be an optimisation to a minimum (rather than a conical intersection). The final '5' ensures that the orbital rotation derivative contributions from the CP-MC-SCF equations are included. (This is necessary and is usually the default. However, in the current version of Gaussian, the combination of '''opt''' and '''stateaverage''' excludes this).
Stateaverage is the default for opt=conical.
Nroot=2 is the default for opt=conical.
Do not include the keyword '''freq''' in the optimisation. (This combination of IOps does not allow '''opt''' and '''freq''' to be keywords in the same job.)

[[Media:buta-cas.gjf]]

[[Media:buta-cas.log]]

== '''5. "Clean" the Orbitals''' ==

In this case, all the orbitals in the active space are pure pi orbitals. Due to small numerical inaccuracies, the final orbitals may include small contributions from other (non-pi) orbitals. The aim of this step is to remove these contributions so that the active space consists (in this example) only of contributions from the C 2PY atomic orbitals. The four relevant orbitals are occupied orbitals 14 and 15 and virtual orbitals 16 and 17. In fact, they are already clean in this example. Verify this by inspection of the "Molecular Orbital Coefficients" in the population analysis.

In other cases, multiple optimisations may be necessary to clean the orbitals:

Open the file in GaussView, and Edit/Symmetrize. Use this symmetrised geometry as a starting geometry for another optimsation as in 4 (including the keyword '''nosymm''').
Use the .chk from 4.
Re-run the optimisation exactly as in 4.

''Ideally here we include the keyword '''opt=(maxstep=1)'''. This should ensure that the optimisation takes the smallest possible step: we already know that the geometry is very close to the minimum and we need to prevent any significant re-orientation that might occur if large steps are taken. However, this does not seem to work (at least with g03).''

Repeat until the orbitals are clean.

== '''6. Calculate the (High Precision) Vibrational Modes for the Ground State ''with State Averaged Orbitals''''' ==

Use the .chk and the geometry from 5. The geometry must be specified explicitly. (With this combination of IOPs, Gaussian extracts the wrong geometry from the .chk file if '''geom=checkpoint''' is specified.)

Keywords: '''CAS(4,4,nroot=2) STO-3G freq=hpmodes guess=read IOP(5/17=41000200,10/10=700007) IOP(5/97=100,10/97=100)'''

The IOp (5/17=41000200,10/10=700007): includes the CP-MC-SCF correction (as above) (for a frequency calculation); and specifies state averaged orbitals. Do not include the keyword '''stateaverage''' with '''freq''' (the current version of Gaussian does not support this). Freq=hpmodes tells Gaussian to print the vibrational modes to 5 decimal places. As before, the IOp (5/97=100,10/97=100) forces calculation of the ground state. Do not use the keyword nosymm here. (Nosymm may prevent Gaussian from identifying the symmetries of the orbitals.)

[[Media:buta-hpfreq.gjf]]

[[Media:buta-hpfreq.log]]

== '''7. The Conical Intersection''' ==

One strategy for locating the conical intersection is to calculate the Frank-Condon point and run an optimisation from there, following (one of) the negative frequency(ies).

=== 7a. The Frank-Condon Point ===

Use the .chk from 4. Using the same orbitals perform a single point energy calculation for the first excited state.

Keywords: '''CAS(4,4,nroot=2,stateaverage) STO-3G pop=full nosymm guess=read geom=checkpoint'''

As in 3, the weights of each state must be listed explicitly. The weights are 0.5 and 0.5. These must be specified by typing 0.5 followed by 7 spaces then 0.5 (on the same line) ''(The Gaussian program reads 10 characters (inc spaces) for the first weight and another 10 characters for the second weight. Thus the 7 spaces plus the three characters "0", "." and "5" make up the first 10 characters before the second weight is read.)''

[[Media:buta-fc.gjf]]

[[Media:buta-fc.log]]

=== 7b. Optimise the Conical Intersection ===

Use the .chk from 7a. Distort the geometry to break the symmetry.
A suggested distortion is to increase the C-C-C-C dihedral angle to 45° by twisting one of the terminal carbons out of the plane of the other atoms (be careful to move only the CH2 group, not the hydrogen on the adjacent carbon). Then increase the H-C-C-C dihedral angles of both the terminal CH2 groups to 70°, in a disrotatory direction. A conical intersection optimisation should now locate a conical intersection.

Keywords: '''CAS(4,4,nroot=2) STO-3G opt=conical nosymm guess=read pop=full'''

Stateaverage is the default for opt=conical.
Nroot=2 is the default for opt=conical.

[[Media:buta-dis14570ci.gjf]]

[[Media:buta-dis14570ci.log]]

=== [[Resgrp:comp-photo-dyn/mctdh90.31dv|back]] ===

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-02-10T15:32:43Z

Callan: /* '''Basic use of the MCTDH package''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01_08).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:
It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems).

Total energy:

1) The total energy can be "artificially" increased by much. If so, try a different integrator.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.]

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":
Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state?
*Need a section on using the database.
*In terms of Delta-E, how much is too much?
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files?

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-02-10T15:32:32Z

Callan: /* '''Basic use of the MCTDH package''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

'''Notes'''

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01_08).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:
It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems).

Total energy:

1) The total energy can be "artificially" increased by much. If so, try a different integrator.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.]

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":
Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state?
*Need a section on using the database.
*In terms of Delta-E, how much is too much?
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files?

Resgrp:comp-photo-dyn/mctdh90.31dv/run

2009-02-10T15:32:18Z

Callan: /* '''Basic use of the MCTDH package: Notes''' */

= '''Basic use of the MCTDH package''' =

A script called dd_generator uses GAUSSIAN output files and user input to write the input files for mctdh.

Notes

'''The number of gaussian wavepackets (requested by the dd_generator script)'''

Start with one (to keep calculation times short). When an appropriate momentum, time period, time step and integrator have been established, increase the number of wavepackets until the results are not changed by adding more. Calculation times are proportional to the number of wavepackets. To ensure efficient use of computing resources, always specify an even number of wavepackets if using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''The database'''

The most time-consuming part of a dynamics run is the GAUSSIAN CASSCF calculations. The results of these calculations can be stored in a database and re-used in future runs. The user must choose whether or not to read and/or write a database. Each calculation will write a separate database so the databases from each run must be combined (and any duplicate entries removed (to save space)). LINK HERE TO SECTION ON MANAGING THE DATABASE

'''Initial momentum'''

An initial momentum can be specified to direct the wavepacket to a particular area of the PES (e.g. towards a conical intersection, a transition state or minimum geometry). The momentum is given as a geometry (in frequency mass weighted normal coordinates). The Excel spreadsheet used for rotation of the conical intersection can be used to transform the coordiinates of the desired geometry. If the user requests an initial momentum, dd_generator will search for a file called momentum.dat. If this file is found, dd_generator will ask if the user wishes to use the momentum specified in it. The user can then specify how much energy to give (in eV). Thus, the values in momentum.dat need only be relative values (since they will be multiplied by a scaling factor to provide the total number of eV requested). If there is no file called momentum.dat in the appropriate folder, the user will not be asked to specify a total number of eV to give to the wavepacket(s). A momentum can still be added by manually modifying the .inp file after the dd_generator script has been run (replace the zero values in the fifth column of the section of the .inp file entitled INIT_WF-SECTION). However, it is simpler to create the momentum.dat file mainly because if the user edits the .inp file directly, there is no way of knowing what the total excess energy will be: the values listed in .inp also incorporate magnitude (not just relative values as in momentum.dat).

'''Memory and number of processors'''

In template.dat, the memory for each GAUSSIAN CASSCF calculation is specified. In the .job file (created by dd_generator from user input) the total memory is specified. Thus, the memory specified in .job must be at least as great as the memory given in template.dat multiplied by the number of processors.

The GAUSSIAN calculations for each wavepacket will run on a single processor. If the user specifies more than one processor then the calculations for each wavepacket can run simultaneously. To ensure efficient use of computing resources, always specify an even number of wavepackets when using more than one processor (since the number of processors can only be an even number: currently 2, 4 or 8).

'''Symmetry Considerations'''

The way the diabatisation is performed in mctdh90.31dv sometimes leads to complications involving symmetry. The diabatic states are defined using the conical intersection described in coin.log. If the molecule is highly symmetric, there will be more than one conical intersection (all identical by symmetry). If the wavepacket moves close to one of the other conical intersections that is not described in coin.log, the diabatic states may not be properly described in this area of the PES. This of course means that the behaviour of the wavepacket(s) is likely to be described poorly also.

If the conical intersection has lower symmetry than the starting material, the symmetry must necessarily be broken during the dynamics calculation before the conical intersection is reached. The breaking of each mode will occur either due to the accumulation of small numerical inaccuracies or if a momentum is given which forces particular modes to break symmetry.
Mctdh90.31dv uses frequency-mass-weighted normal coordinates to describe molecular geometries. Each frequency-mass-weighted coordinate corresponds to a vibration of the molecule (and there are therefore 3N-6 coordinates). Displacements of atoms are described by a (or a combination of) vibration(s). Each vibration can be displaced in one of two directions: positive or negative. The 3N-6 frequency-mass-weighted coordinates can be classified by symmetry. Whether a particular symmetry mode is broken in the positive or negative direction will be equally likely if no initial momentum is given. Thus for each mode that is broken during a simulation the symmetry may break in the positive direction or the negative direction. There will be 2x possible conical intersections corresponding to a particular starting geometry, where x is the number of modes that must be broken going from starting material to conical intersection.

Additionally, care must be taken over atom labeling. It must be possible to transform the starting material into the conical intersection without permuting atom labels. If the conical intersection has been optimised by following the MEP downhill from the starting material this is not likely to be a problem. However, bear this in mind if drawing the conical intersection by hand.

Example: Butadiene

Cis-butadiene belongs to the C2h point group and its 3N-6 frequency-mass-weighted coordinates can be classified as Ag, Bg, Au or Bu (see the C2h character table and GAUSSIAN frequency output). The S1/S0 conical intersection has no symmetry. Thus there are four symmetry modes that must be broken going from starting material to conical intersection. There are sixteen (24) equivalent conical intersections that could be specified in coin.log, corresponding to all possible ways of distorting the starting geometry into the conical intersection geometry. The sixteen conical intersections correspond to: two structures resulting from disrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from disrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers); two structures resulting from conrotatory motion in one direction followed by out-of-plane twisting (and their enantiomers); and two structures resulting from conrotatory motion in the other direction followed by out-of-plane twisting (and their enantiomers). Each of the sixteen conical intersections will have a different arrangement of atomic labels but all can be reached by distorting the starting geometry.

=='''Creating the Directories'''==

* First of all, create a folder in which to save the calculations in your $HOME and $WORK directories. Create a directory in $HOME, and an identical directory in $WORK that has the same path. Keep pathlengths as short as possible (if the total path becomes too long the dynamics code will not run). For simplicity, in this case, we are going to assume that this directory is named ''buta'' (for butadiene).

mkdir buta

* Create a subdirectory called '''dd_data''' in the new directory in $WORK. Thus you should start with:

/home/$USER/buta
/work/$USER/buta/dd_data

* Important Note: it is essential to have the same path in both directories, $HOME and $WORK. Do not change the path-names within the HOME/WORK directories. If you re-name or move any subdirectory in your, for example HOME directory, you have to be consistent and make the same changes in the $WORK directory.

=='''Gaussian Output to be Used as Input for the Dynamics Program'''==

* Populate the new directory /work/$USER/buta/dd_data with four files which must be named: '''coin.log'''; '''start.fchk'''; '''start.log'''; and '''template.dat'''.These files are required in order to run any dynamics simulation, they are the basis that the script dd_generator (see the following section) will use to create the necessary files for running MCTDH. You may also create a file named "'momentum.dat"' if you wish to give a momentum to the wavepacket(s) (this is optional and may be created later instead).

'''coin.log''' is the logfile resulting from the optimisation of the conical intersection. NB The MCTDH program will rotate the conical intersection before starting the dynamics. To do this it must be provided with three angles which describe the appropriate rotation. There is an Excel spreadsheet available to calculate these angles (see the section entitled "Rotating the Conical Intersection"). NB the final conical intersection log file must only contain one geometry (otherwise the dynamics program will not know which geometry to use). IS THIS STATEMENT TRUE FOR THIS VERSION??

[[Media:coin.log]]

(Insert a link here to section "Rotating the Conical Intersection")

'''start.fchk''' is the formatted checkpoint file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.fchk]]

'''start.log''' is the log file from the high precision vibrational modes of the ground state with state averaged orbitals (Part A, 6)

[[Media:start.log]]

'''template.dat''' is a template for the creation of GAUSSIAN input files by the MCTDH program. It contains all the mutual keywords of the GAUSSIAN calculations which will be run on-the-fly by MCTDH. It also contains other information relating to the GAUSSIAN calculations such as memory requirements.

[[Media:template.dat]]

'''momentum.dat''' is a file containing a list of values to be used as vectors to indicate the momentum to be given to a particular (set of) wavepacket(s). The vectors must be listed in the order of the frequency-mass-weighted normal coordinates specified in the Excel spreadsheet. They give the magnitude of the momentum to be given along each of these frequency-mass-weighted normal coordinates. N.B. The signs of the values here are important!

[[Media:momentum.dat]]

=='''The Generator'''==

* The "generator" script uses the GAUSSIAN output files (above) along with other information supplied by the user to create input files for MCTDH.

* Navigate to /home/$USER/buta and run the generator by typing:

dd_generator

for the HPC Cluster, or

dd_generator_MAC

for a MAC OS X system

* Typing dd_generator will run the script automatically. After installing the MCTDH package this command has been added to your list of executable commands.

********************************************************************************
******************** ------- DD GENERATOR -------- *****************
********************************************************************************

* The generator will ask a series of questions and will use the answers provided to prepare the input files for the dynamics program. The questions it asks are listed below along with answers for a trial run on butadiene.

==== List of questions asked by dd_gennerator====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''Which version of GAUSSIAN should we use? (gdv|g03)''' </td> <td> g03 </td> <td> </td></tr>
<tr><td> '''How many shared-memory processors should we use? (1|2|4|8)
N.B.: (ncpus=1) serial or (ncpus=2|4|8) parallel (omp) version of MCTDH launched as batch job
and launching monoprocessor GAUSSIAN interactive jobs (nprocshared=1 or no specification)
'''</td> <td> 1 </td> <td> </td></tr>
<tr><td> '''What is the name of the molecule?''' </td> <td> butadiene </td> <td> The first four letters will be used to name the new files that the generator is creating </td></tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''The number of nuclear degrees of freedom is 24.
Do you want to reduce the dimensionality? (y|n)
(N.B.: this can be used also for re-ordering the coordinates)
''' </td> <td> n </td> <td> </td></tr>
<tr><td> '''What is the number of nuclear Gaussian functions?''' </td> <td> 1 </td><td> 1 means 1 gaussian on state 1 and 1 gaussian on state 2. This is the "single-set" implementation of MCTDH therefore the gaussian wavepacket on state 1 is the same as the gaussian wavepacket on state 2.</td> </tr>
<tr><td> ''''What is the final propagation time (in fs)?'''</td> <td> 200 </td> <td> </td></tr>
<tr><td> '''What is the propagation time step (in fs)?'''</td> <td> 0.1 </td><td> </td> </tr>
<tr><td> '''What is the number of electronic states? (1|2)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''What is the highest electronic root?''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''From which electronic state should the wavepacket start? (2|1)''''</td> <td> 2 </td> <td> </td></tr>
<tr><td> '''Will there be an initial momentum given to the wavepacket? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Do you want to add a reference label to the name of the case? (y|n)'''</td> <td> y </td> <td> </td></tr>
<tr><td> '''Please type your text:'''</td> <td> trial </td> <td>This question is only asked if the answer to the previous question was yes. </td></tr>
<tr><td> '''What will be the status of the database? (rdwr|rd|wr|none)'''</td> <td> none </td> <td> Choose rd for read, wr for write etc. In this case we are not going to use the database, but if it was used (rd or rdwr is specified) the script would ask the user to specify the threshold below which the database values will be used (%). In this case the value none is chosen so this question is not asked.</td></tr>
<tr><td> '''Please type the value of the maximum-difference criterion (in %):'''</td> <td> 1 </td> <td>If 1 is specified, the database value will be used if the geometry is within 1% of the new geometry being calculated</td></tr>
<tr><td> '''>> Manual rotation (using Excel spreadsheet) <<
Please type the values of the three Euler angles (in deg)</td> <td> 176.543006
185.772905
4.538147 </td><td>From the spreadsheet [[Media:spreadsheet.xls]]</td></tr>

<tr><td>The generator will now tell you that it has read the files start.fchk from the folder /work/dm107/dyn/dd_data/ and written the file start.chk.

<pre>
Read formatted file /work/$USER/buta/dd_data/start.fchk
Write checkpoint file /work/$USER/buta/dd_data/start.chk
using /apps/gaussian/g03_e01/g03/unfchk

</pre></td></tr>
<tr><td> '''Do you want to read the direction of the initial momentum from the existing file in /work/$USER/buta/dd_data? (y|n)
(you still have time to change it now, before answering)
'''</td> <td> y </td> <td>This question is only asked if the answer to the question "Will there be an initial momentum given to the wavepacket?" was yes. </td></tr>
<tr><td> '''Please type the value of the excess kinetic energy (in eV) for calculating the magnitude:''' </td> <td> 1 </td> <td> </td></tr>
</table>
</blockquote>

=='''Files created by the generator'''==

* The generator will now tell you that it has read the files start.log, coin.log and momentum.dat (if a momentum has been specified) from the folder /work/dm107/dyn/dd_data/:

<pre>
about to read parameters...
... parameters just read
about to read file /work/dm107/dyn_90dev/dd_data/start.log
...
... file /work/dm107/dyn_90dev/dd_data/start.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/coin.log
...
*********************************************************
Mass-weighted displacement from start to coin:
old total norm: 22.070387
new total norm: 4.669035
vibrational part: 4.669035
rotational part: 0.000000
*********************************************************
... file /work/dm107/dyn_90dev/dd_data/coin.log
read successfully
about to read file /work/dm107/dyn_90dev/dd_data/momentum.dat
...
*********************************************************
Using the momentum given in momentum.dat would have given
an excess kinetic energy (in eV) of: 15.269
For your information, the momentum has been multiplied
by a factor of: 0.572
*********************************************************

... file /work/dm107/dyn_90dev/dd_data/momentum.dat
read successfully
</pre>

and that the extraction of data and the creation of a summary file were done successfully

<pre>
Data extracted successfully
The summary of this file generation is in:
-rw-r--r-- 1 dm107 hpc-users 3070 Dec 2 17:06 /home/dm107/dyn_90dev/but1dd1o.txt

Do not forget you still can add a momentum, change the integrator, change convergence criteria for GAUSSIAN and MCTDH...

Do not forget to check the order of the atoms of the conical intersection geometry in /work/dm107/dyn_90dev/dd_data/coin.log

Now go to your jobscript file and give values to the memory and walltime.

Good luck!
</pre>

* The dd_generator script has generated four files in the same directory (/home/$USER/buta):

# but1dd1p_trial.inp
# but1dd1p_trial.job
# but1dd1p_trial.txt
# but1dd_none.op

(Link to a more detailed explanation of this files)

* The script has also created some files and directories in /work/$USER/buta where the MCTDH and GAUSSIAN calculations will be stored:

1) Directories:

* butadd1p_trial
* butadd1p_trial/dd_data

2) Files (in butadd1o_trial/dd_data):

# refdb.dat
# start.chk
# template.dat
# forward.dat
# backward.dat

=='''Modifications to be made to the files before running the dynamics'''==

* In the .job file in /home/$USER/buta specify the memory and walltime if you are in the HPC Cluster.

* When running a development version of GAUSSIAN (gdvg03 or gdvg01), copy the start.chk file into the folder /work/$USER/dyn_90dev/but1dd1p_trial/dd_data. The unformatted checkpoint file from start.fchk that dd_generator has created is corrupted (due to a bug in formchk in gdvg01_08).

====Starting from a point other than the Franck-Condon point====

When the molecule is highly symmetric and there is more than one equivalent conical intersection (see above) it may be necessary to direct the wavepacket towards the particular conical intersection described in coin.log. The easiest way to do this is to use an initial momentum but it can also be achieved by distorting the geometry of the starting structure slightly towards the conical intersection (i.e. breaking the symmetry in the appropriate direction(s)).

Define the new starting geometry in frequency-mass-weighted normal coordinates (this can be done using the Excel spreadsheet). One option for selecting the new geometry is to use a fraction of the displacement from the FC point to the conical intersection.

After running dd_generator in the normal way, replace the default FC geometry in the .inp file with the new geometry. This geometry (frequency-mass-weighted-coordinates of the centre of the wavepacket) forms the fourth column in the section entitled INIT_WF-SECTION (in .inp).

If the new geometry is very different from the FC geometry, run a single-point state-averaged-CAS calculation (start from RHF, look at the MOs, alter if needed, and check the final active MOs) and call the resulting .chk file start.chk. Replace the start.chk that would have been used ($WORK/buta/but1dd1p_trial/dd_data/start.chk) with this new start.fchk. If the distorted geometry is close enough to the FC geometry it may not be necessary to generate a new start.chk. (When the distortion is large there is a risk of breaking the active space from FC to the new point. Creating a new start.chk is just a way of making sure the starting active space is OK at the new point.)

N.B. There is no need to replace start.log even when start.fchk is replaced.

=='''Running the dynamics'''==

* Navigate to /home/$USER/buta. Queue the job file. In this case, type:

qsub butadd1p_trial.job

for MAC OS X users the shell command is already written in butadd1p_trial.job

=='''The Database (DB)'''==

The DB is made of four binary files:
geo.db
pes.db
gra.db
hes.db
They can be used in place of GAUSSIAN calculations to save some
computation time when you ask for DBrd or DBrdwr.

Each set of geometry, energy, gradient and Hessian (the latter
three quantities having been calculated by GAUSSIAN for the two
adiabatic electronic states) will be called a DB record and
assigned a record number defining the order of occurrence in the DB.
If you run a calculation where the DB is to be read, in the *.res
file that you obtain after the calculation is done (file that
actually is a redirection of the standard output) you will see the
number of records in the DB as it grows.
Example (formaldehyde, multi-set 1+1):
53
s= 1 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 2 e= 1 t= 0.000 V1= 0.001 V2= 4.533 H11= 0.001 H22=
4.533 H12= 0.000 q= 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000
53
s= 1 e= 1 t= 0.500 V1= 0.197 V2= 4.701 H11= 0.211 H22=
4.687 H12= 0.251 q= -0.6258 -0.6146 0.6136 0.6049
-0.5520 -0.0616
53
s= 2 e= 1 t= 0.500 V1= 0.000 V2= 4.533 H11= 0.000 H22=
4.533 H12= -0.001 q= 0.0009 0.0009 0.0093 -0.0245
-0.0066 0.0001
53

ERROR in subroutine Distdb :
Redundant records in Data Base: 18 19
s= 1 e= 1 t= 1.000 V1= 0.469 V2= 4.455 H11= 0.479 H22=
4.445 H12= 0.200 q= -0.4640 -0.5641 1.2594 -0.5871
-1.0864 -0.1120
53
s= 2 e= 1 t= 1.000 V1= 0.001 V2= 4.473 H11= 0.001 H22=
4.473 H12= -0.002 q= 0.0003 0.0004 0.0404 -0.0944
-0.0292 0.0001
53
s= 1 e= 1 t= 1.500 V1= 0.113 V2= 4.543 H11= 0.120 H22=
4.536 H12= 0.170 q= -0.3994 -0.4377 0.5444 0.2057
-0.5149 -0.0638
53
s= 2 e= 1 t= 1.500 V1= 0.013 V2= 4.390 H11= 0.013 H22=
4.390 H12= -0.005 q= 0.0009 0.0010 0.0897 -0.2104
-0.0634 0.0002
53
s= 1 e= 1 t= 2.000 V1= 0.068 V2= 4.431 H11= 0.071 H22=
4.428 H12= 0.110 q= -0.2751 -0.3274 0.4796 -0.0812
-0.3880 -0.0605
54
s= 2 e= 1 t= 2.000 V1= 0.019 V2= 4.367 H11= 0.019 H22=
4.367 H12= -0.009 q= 0.0012 0.0013 0.1563 -0.3658
-0.1058 0.0003
54
s= 1 e= 1 t= 2.500 V1= 0.064 V2= 4.273 H11= 0.065 H22=
4.272 H12= -0.064 q= 0.2559 0.0914 0.1691 -0.7218
-0.1052 -0.0595
55
s= 2 e= 1 t= 2.500 V1= 0.070 V2= 4.258 H11= 0.070 H22=
4.257 H12= -0.013 q= 0.0013 0.0015 0.2384 -0.5572
-0.1528 0.0004

Here, we started with a DB of 53 records. It is large enough until
2 fs, where an additional record is produced, and so on.
The error message saying here that records 18 and 19 are identical
will not prevent the code from working. It is just here to remind you
that the DB is not clean in that it has redundant records.
This is to be prevented as the DB files might become large quite
rapidly and all records will be read at each update time (dd_update
= tout in the integrator section, tout = xxx fs in the run section
of the *.inp file) for each Gaussian function.

Incidentally, when you want to analyse results written to a *.res
file, you need to look for lines starting with "s=" (other lines
are various messages and numbers of DB records).
The criterion for using the DB is to be seen as a maximum-allowed
relative difference

So, it is up to you to clean the DB when you see this, and to keep
this in mind when you concatenate DBs that have branched in their
past (see more details below).

Also, a given DB depends on the choice of a reference geometry in
Cartesian coordinates because geometries written to the DB files
will always be re-orientated with respect to this particular
geometry. The back and forth transformations are performed by MCTDH
so you don't need not worry about this.
This geometry is written to refdb.dat. It is the starting geometry
that comes from start.log (the only difference being that it is
mass-centred).
As long as you do not change the starting geometry or the nature
of the electronic states, you can thus keep growing the DB of your
system.

MANAGING THE DATA BASE

A set of DB programs can be found in XXXXX. Their roles are
explained below.
For now, the sources are in dd_utildev and dd_util.31dv and the
executables are in mctdh90dev/bin and mctdh90.31dv/bin, so you can
call them from anywhere, as long as DB files are there.

1) countdb.out: returns the number of records of the current DB
2) cleandb.out: "brute-force" cleaning of the current DB. This
might be too long to be run interactively when the number of
records is too large, because each record needs to be compared to
each other record. If so, run in batch mode (ask me or Marta if you
have a doubt).
The cleaned files are:
geoclean.db
pesclean.db
graclean.db
hesclean.db
You need to rename them without 'clean' for them to be used as a DB.
3) cutdb.out: allows you to cut out the beginning of a DB.
This is to be used in the following situation:
- You start from a mother DB, DB0, assumed to be clean, with N0
records.
- You want to use DB0 in two independent calculations. You
replicate DB0 to daughter DBs, DB1 and DB2.
- When these calculations are done, DB1 and DB2 have grown to N0+N1
and N0+N2 records, respectively.
- You want to concatenate them to create a new mother DB, DB3.
- DB1 and DB2 have their N0 first records the same. To avoid
redundant records, you need to cut N0 records from DB2 for example.
--> go to where DB2 is and use cleandb.out
The resulting files are:
geocut.db
pescut.db
gracut.db
hescut.db
these have N1 records.
--> rename DB1, for instance geo.db1 etc., and concatenate the files:
cat geo.db1 geoclean.db > geo.db
etc.
- Your new mother DB, DB3, should now have N0+N1+N2 distinct records.
4) deldb.out: allows you to remove one selected record (for
instance if corrupted) from the DB if you know its number.
The resulting files are:
geodel.db
pesdel.db
gradel.db
hesdel.db
You need to rename them without 'del' for them to be used as a DB.
5) seedb.out: allows you extract one selected record from the
binary files for reading it (the record is not removed from the DB).
The resulting file can be read as a text file (ascii) and is:
see.db

=='''Restarting dynamics jobs'''==

The examples below make use of the directory and filenames in the examples above.

A dynamics run can be restarted if the job was terminated before completion (e.g if it ran out of time or failed because of convergence problems) or if the user wishes to continue the job for a longer time period than had originally been specified. The program will continue writing the same output file but will overwrite the .res file. Thus the .res file should be saved under a different name to prevent loss of the data calculated in the original run. The .res is not written until the job stops so this can be done after the restart.

*To increase the final propagation time

Retrieve the .inp file (in $HOME/buta) and change ''propagation'' to ''continuation'' in the section entitled RUN-SECTION. Then change the final time ''tfinal'' to a larger value. (NB this new value should include the time already done).

Re-queue the job.

*To increase the number of scf cycles (the most common reason for convergence failure)

Edit the template.dat file in $WORK/buta/but1dd1p_trial/dd_data. Insert scf=(maxcycle=128) on the keyword line (for example). It is important that you change the template.dat file in the but1dd1p_trial/dd_data folder that was created by dd_generator (rather than the one created by the user in $WORK/buta/dd_data) because the original $WORK/buta/dd_data/template.dat file is only read by dd_generator and used to create the job-specific file in the job folder. (Of course if you wish all future jobs run in $WORK/buta to have increased scf cycles, change the other template.dat file in $WORK/buta/dd_data too.)

Re-queue the job.

*To increase the run-time so that a job will finish

Edit the walltime in the .job file in the $HOME directory and re-queue the job.

='''Analysis of the results'''=

The most important files are the output and .res files.

=== Detailed information about files and directories ===

*output

The output contains some standard results:

'''Time''': time in fs.

'''CPU''': CPU time in s.

'''Norm''':

'''E-tot''': the total energy in eV. This value should be conserved (i.e by the end of the run the E-tot value should not be too different from what it was a time=0).

'''E-corr''': correlated Hamiltonian energy

'''Delta-E''': diference between E-tot at time t=0 and the current time t

Note: In a multi-packet run, i.e. when npacket > 1, the total energy and the norm of the wavefunction, as given in the "total" part, are averaged over the packets.

'''population''' : diabatic populations of state 1 and state 2 (in that order) at the current time t

For every mode:

'''< q >''': position expectation value

'''<dq>''': standard deviation Sqrt[< q2 > - < q >2]

'''''' : momentum expectation value

'''<dq>''': standard deviation Sqrt[< p2 > - 2]

*.res

This file contains the energy of each state (diabatic and adiabatic) at each timestep for each gaussian function:

'''s''' is a redundant value in mctdh90.31dv. It is only meaningful in multi-set implementations of mctdh (where there are double the number of gaussian functions than specified: one for each state). (It indicates whether the gaussian function in question is on the lower (1) or upper (2) state. (In the single set implementation, the gaussian functions on each state are identical)).

'''e''' is a label given to each gaussian function

'''t''' is the current time in fs

'''V1''' is the energy of the lower adiabatic state at time t

'''V2''' is the energy of the upper adiabatic state at time t

'''H11''' is the energy of the lower diabatic state at time t

'''H22''' is the energy of the upper diabatic state at time t

'''H12'''

'''q''' is the list of frequency mass-weighted normal coordinates that describe the geometry at time t

The end of the file will read something like:

Propagation was successful.

Total time [h:m:s] : 0 : 1 : 21.60

---------------------------------------------------------------------------
------ Host: "cx1-3-2-4" ----------Sat Jan 17 06:50:20 2009

The other most common result is that the calculation aborted because of scf convergence problems in the CASSCF GAUSSIAN calculations. In this case the ouput file will break off after the last complete step and the end of the .res file will read something like:
ERROR in subroutine Getddpes :
CAS convergence failed for gwp on state: 1 1

If the job terminates due to scf convergence problems, it may be possible to restart it after modifying the .inp and/or .job and/or template.dat files.

*log

This file contains information such as the source code version, type of calculation performed, integrator used, numerical parameters, which data files are opened, any error messages, and much more. The information provided by the log file can be very helpful, in particular when searching for errors. One should always carefully inspect the log file.

* dvr

* oper

*ddpeserr

*input

*op.log

*psi

*check

*auto

*ddpes

*restart

*stop

*speed

*timing

*update

=== Example: butadiene ===

*Examine the end of the output file to check that the calculation ran to completion.

*Plot the energy of the diabatic and adiabatic states over time (.res file: V1, V2, H11 and H22). Calculate V2-V1 and H22-H11 and plot these also. H12 may also be plotted on the same graph.
[[Image:EnergyofStates.png]]

The diabatic states cross at 176.2 fs and the adiabatic states cross at 174.5 fs. At a conical intersection, the value V2-V1 will become negative and the H22-H11 will be a minimum (<1eV). Ideally these crossings will occur at the same time. If the diabatisation has worked well, after V2-V1 becomes negative, V2-V1 and H22-H11 will become mirror images (i.e. the diabatic and adiabatic states follow each other).

*Plot the value of the total energy over time (.res file: E-tot). Verify that the Delta-E value is not too large (compare with the total energy (E-tot) at time 0).
[[Image:TotalEnergy.png]]

*Plot the population of one of the (diabatic) states over time (.res file: population).
[[Image:Population.png]]

At the conical intersection the population transfer is large. In this case the job has been terminated after 200 fs. Usually the calculation should be continued until the populations stabilise (which obviously has not happened in this case).

=== Making a Movie ===

Navigate to /work/$USER/buta/but1dd1p_trial (the place where the .res file was written). Type:
dd_movie.out
* The script will ask a series of questions and will use the answers provided to create a file that can be read into Molden or iMol.

==== List of questions asked by dd_movie.out====

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
<table border="1">

<tr><td> '''Question''' </td> <td> '''Answer for this tutorial''' </td> <td> '''Explanation''' </td> </tr>
<tr><td> '''What is the number of atoms?''' </td> <td> 10 </td> <td> </td></tr>
<tr><td> '''What is the actual number of active coordinates?'''</td> <td> 24 </td> <td> In this case all coordinates were active (so there are 3N-6 where N is the number of atoms) </td></tr>
<tr><td> '''Name of result file to read?''' </td> <td> but1dd1p_trial.res </td> <td>Ensure that the forward.dat and backward.dat files are located in the current directory in the folder dd_data (they will have been written there automatically)</td></tr>
<tr><td> '''Name of movie file to write?''' </td> <td> but1dd1p_trial.xyz </td> <td> Choose any name .xyz </td></tr>
<tr><td> '''Which electronic state (s=...)?''' </td> <td> 1 </td> <td>Choose 1 (this question dates from the multi-set implementation of mctdh where the wavepackets on each state were different) </td></tr>
<tr><td> '''Which Gaussian function (e=...)?''' </td> <td> 1 </td><td>In this case we have only one wavepacket</td> </tr>

<tr><td>The script will now return the number of lines and the initial number of points
<pre>
number of lines: 4684
initial number of points: 4674
</pre></td></tr>
<tr><td> '''Maximum number of points you want?'''</td> <td> 4674 </td> <td>If you wish to view the movie in Molden you must reduce the number of points to less than 100 (so choose 99 for maximum number of points). iMol can cope with any number of frames so choose the number printed by the script: this number will be reduced and the script will tell you how many points it has written. </td></tr>
<tr><td>
<pre>
writing frequency: 2
final number of points: 2337
</pre></td></tr>
</table>
</blockquote>

The .xyz file is ready to be opened in Molden or iMol.

= '''Current Known Bugs''' =

Parallelisation:
It is not possible to run calculations in parallel with version 90.31dv (reading the same template.dat file simultaneously by each processor is causing problems).

Total energy:

1) The total energy can be "artificially" increased by much. If so, try a different integrator.

2) If Delta-E suddenly becomes too large, you can get the following message:
"ERROR in subroutine WRGAUSSIAN :
Do not use $Swap:...$ metastring in file /.../template.dat"
Often, when getting this message, no more steps are added to the simulation, although the calculation seems to keep running (the integrator keeps trying and failing).

Using the database:

1) Every record generated with mctdh90.31dev and several GWPs is corrupted, so, for now, when launching calculations with more that one wavepacket, use "formdd_none.op" (i.e. do not read nor write the database).
[For instance, when using dbrdwr and starting from a clean db, all newly generated records are added to the existing database, even if they are identical to records that were already written in the db.]

2) Records obtained in calculations with one GWP should be OK, but this is still to be confirmed.

"Impossible case":
Error message that forces the calculation to stop. It seems to be associated with moving towards an "unexpected" geometry (e.g. a radical).

= '''Questions and Modifications to be made to this wiki''' =

*Why we would ever need to start the gwps from the lower state?
*Need a section on using the database.
*In terms of Delta-E, how much is too much?
*Benjamin: Note that Marta has noticed that for very strange geometries, you may receive an error message saying "impossible case", which stops MCTDH. It is too complicated to explain here. I know where this happens in the code, and I should prevent this error to stop the code but I didn't have time to fix this. I'll do it soon.
*Need to edit/correct section on the DB.
*Is does unfchk in gdvg03 create corrupted fchk files?