The Analyse Programs
Generalities
Analyse is a set of programs able to extract data of interest from the results of an QUANTICS calculation. In essence, there is a library of modules providing an interface to the QUANTICS program output. These modules can be then built into programs as required. The documentation is in two parts: Firstly the various programs for computing observable quantities are described, and secondly the various shell-scripts for plotting the results using the Gnuplot program are detailed.
Some of these programs are seldom used, may not be very general, and should be used with caution. Some do not work as they were written for earlier versions of the package and need repairing.
Documentation of the Individual Programs
While all the analyse programs are stand alone codes, analysis is a basic interface to the main analysis programs. It uses a set of menus to interactively analyse the results of calculations.
The following programs are available for general analysis and plotting:
- gwptraj
- Plots the centres of GWP basis functions in G-MCTDH and vMCG calculations.
- rdspf
- Reads the SPFs from psi or restart file and prints the data to screen.
- showd1d
- Enables plotting of the 1-dimensional densities with time.
- showfield
- Enables plotting of a time-dependent field.
- showrst
- Enables selective plotting of the single-particle functions from the restart file.
- showspf
- Enables selective plotting of the single-particle functions from the psi file.
- showsys
- Enables 2D plotting of the wavefunction or the PES . Overlay plots, i.e. WF on PES, are possible as well.
The following programs are available to calculate and plot properties:
- adpop
- Calculates the diabatic and adiabatic populations of the electronic states. The calculation of one and two dimensional adiabatic densities is also possible.
- autospec
- Computation of the spectrum by fourier-transforming the autocorrelation function.
- crosscorr
- Reads two QUANTICS wavefunction (or density operators) ψ and ψ_{ref} and performs the cross-correlation function c(t) = <ψ_{ref}(0)|ψ(t)>. Matrix-elements <ψ_{ref}(0)|Ô|ψ(t)> can also be done (for WFs).
- crosspec
- Fourier-transforms a cross-correlation function generated by crosscorr.
- dengen
- Generates 2D-densities from a wavefunction.
- edengen
- Generates (2D) pair-correlation functions, <x,x|ρ_{2}|y,y>, from the wavefunction.
- expect
- Calculates the time evolution of the expectation value of an operator. Reads the output file psi.
- flux
- Computes the quantum flux by analysing the matrixelements of the CAP. Computes reaction probabilities.
- gwptransmission
- Transforms a GWP wavefunction to the energy representation and computes the energy and transmission spectrum.
- jinpol
- Interpolates flux-probabilities for a range of total J.
- pexpect
- Calculates the time evolution of the expectation value of a one-particle operator. Reads the output file pdensity.
- prhosub
- Reads pdensity file and writes reduced density of one selected DoF on primitive grid to files.
- probrw
- Computes reaction probability from Flux for real wavepacket propagation
- probsq
- Reads the auto file and computes the average of |c(t)|^{2}, which is the sum of the squared occupation probabilities of the eigenstates.
- rdauto
- Reads the auto steps from file "auto" and enables plotting of the data.
- rdcheck
- Outputs various simple expectation values.
- rdeigval
- Reads the eigenvalues from file "eigval" and enables plotting of the stick spectrum.
- statepop
- Outputs the diabatic state populations. If adiabatic populations are not needed this program is preferred to adpop as it is quicker and has interactive plotting.
- sumspec
- Sums spectral components (output from autospec).
- twopdens
- Computes the 2-particle density in the basis of the SPFs.
- twprob
- Computes state-resolved reaction probabilities with the method of Tannor/Weeks.
The following programs are available for checking the data used in a simulation:
- enqoper
- Queries the status and values of parameters and data stored in the oper file.
- maxpe
- Calculates the minimum and maximum value of a PES.
- rdacoeff
- Reads the A-vector and prints it to screen.
- rdgrid
- Reads the DVR grid points from dvr file and prints them to screen.
- vminmax
- Reads a pes-file and runs over the total product grid or a selection of grid points to determine the maxima and minima of a potential energy surface.
The following programs are available for checking the convergence of MCTDH simulations:
- aoverlap
- Calculates the difference between two A-vectors.
- herma
- Computes the hermiticity error of the A-vector.
- norm
- Calculates the norm and A-norm of a wavefunction or density operator of type II.
- ortho
- Checks the orthonormality of the spf's and spdo's. Checks also the hermiticity of the spdo's.
- overlap
- Calculates the difference between two wavefunctions or density operators.
- rdautoe
- Analyses the error within the autocorrelation function.
- rdgpop
- Analyses the grid population read from file gridpop.
- rdsteps
- Reads the step-file and evaluates statistic measures of the integrator steps.
- rdupdate
- Reads the update steps from file "update" and enables plotting of the data.
The following programs are available for analysis of direct dynamics simulations:
- ddgeom
- Generates the expectation values for the geometries of a direct-dynamics simulation.
- ddtraj
- Generates the expectation values for the geometries from a direct-dynamics simulation.
The following programs are available for analysis and manipulation of direct dynamics database:
- checkdb
- Cleans an SQL direct-dynamics database to remove failed and duplicate points.
- cleandb
- Cleans an old flat file direct-dynamics database to remove failed and duplicate points.
- convdb
- Converts an old flat file direct-dynamics database from binary to ascii or vice versa.
- convdbfromsql
- Converts a direct-dynamics database from SQL format to plain files.
- convdbtosql
- Converts a direct-dynamics database from plain files to an SQL format.
- rddddb
- Reads a DD DB and produces a file to plot the geometries.
- trafodb
- Analysis of DD DB using transformations of the energies and coordinates.
The following programs are available to manipulate and transform the wavefunction :
- concat
- Reads two restart files and concatenates the wavefunctions, i.e. psi(q,x)=psi1(q)*psi2(x).
- convpsi
- Converts a multi-packet wavefunction to the corresponding single-packet ones.
- di2ad
- Transforms a diabatic wavefunction to an adiabatic representation.
- joinpsi
- Joins psi files that have been calculated with different number of single particle functions.
- ml2mctdh
- Converts a multilayer wavefunction to MCTDH form.
- oppsi
- Applies an operator to a wavefunction.
- psi2ex
- Converts an QUANTICS psi file to an exact (full grid) representation. Reads the output file psi and creates psi.ex.
- psi2rst
- Writes a WF from an psi file to a restart file.
- sumrst
- Allows calculation of the superposition of up to 8 wavefunctions with different weight.
- wfproj
- Computes the projection of a wavefunction onto a (combined) mode.
The following programs are available for analysis and manipulation of natural potentials calculated by the natpot program:
- chnpot
- Interpolation of natpot terms to another grid.
- npotminmax
- Like vminmax. Reads a set of natpot files and runs over the total product grid or a selection of grid points to determine the maxima and minima of a potential energy surface.
- natpot2cpd
- Read a natpot file and convert to a canonical polyadic decomposition (CPD) which is subsequently optimized using ALS.
- rdnatpot
- Reads a natpot file and prints information on it to rdnatpot.log.
- showpot
- Enables plotting of a PES fit from a natpot file. Comparison with true potential can be made if vpot file is present.
The following programs are available for analysis of Filter Diagonalisation and Obtaining eigenvalues:
- fdcheck
- Checks whether a state has been found in all filter data sets.
- fdmatch
- Finds the optimal matches between sets of eigenvalues, where each set is obtained with the (real) filter program.
- fmat
- Computes the matrix elements <ψ(t1)|Ô|ψ(t2)>. The usual hermitian or the symmetric scalar product may be used. The diagonalisation of the matrix may then be performed by diag.
- diag
- Diagonalizes the Hamiltonian matrix calculated by fmat.
The following programs are available for set-up analysis of Optimal Control Calculations :
- efield
- Calculates the electric field for optimal control runs. efield exchanges data with quantics via fifos. efield is usually called by the script optcntrl.
- guessfld
- Computes the initial guess field for an optimal control run.
- xfrog
- Computes an XFROG trace of the electrical field obtained with OCT-MCTDH
The following program is available for wavefunction analysis:
- diffmap
- Analyses grid-based wavefunctions using diffusion map or isomaps.
Other specialists programs are also available:
- adproj
- Calculates vpot files for the adiabatic potential matrix elements and the adiabatic projector matrix elements for each electronic state.
- compare
- Used by the elk_test program to compare different sets of results.
- mmemtest
- Checks how much memory is available.
- reflex
- Computes reflection and transmission of a CAP.
- tdpespec
- Calculates a pump-probe photo-electron spectrum from a set of calculations.
Below the options of each analyse program are described. This information can also be obtained by using the -h option, e.g.
aoverlap -hThe information given there is a little bit more reliable since the on-line documentation might not be up to date in some cases.
adpop
OptionsThe adpop program is used to calculate the populations of the electronic states from the wavefunction stored in the psi file. Both the diabatic and the adiabatic populations are given. The results are stored in the file adp for each time step. Various options are availale to control the output times so that, e.g. -step or -tcut. The adp file can be easily plotted with plgen.
The full calculation runs over the primitive grid and is slow. It is also restricted to systems for which the full primitive grid fits into memory, typically 4 or fewr DOF. The calculation can be accelerated and memory saved by setting the quick option, -q. Using the quick option, one ignores points for which the product of one-dimensional grid-populations (1D-densities) is lower than qtol. This "quick" algorithm is the default and the default for qtol is 10^{-5}. It is turned off (to provide the exact calculation) using the option -noq.One and two dimensional densities can also be calculated with adpop when using the full grid. The densities are stored in the adp_dof* and adp_dof*_dof* files where dof* is replaced by the name of the corresponding degree of freedom. The densities are calculated with and without weights.
For the adpop density files the script pladpop exists. This script plots the adiabatic densities of the different electronic states with or without weights.
Larger systems can be treated using some approximate schemes. A TDDVR scheme using the DVR from the SPFs is available with the -tddvr option. For calculations with combined mode SPFs the multi-dimensional DVR of Harrevelt and Manthe (JCP (05) 123: 064106) is used. The CDVR correction can also be used with -cdvr to obtain a more accurate result. This brings the memory requirements down to the length of the A-vector, affordable for all systems, but poor results are obtained with small basis sets. An alternative approach is to use Monte-Carlo integration, -mc. This is, of course, less accurate and for small systems (3D, say) it is much slower than the direct method. The accuracy is controlled by the usual MC error variance measure, and is controlled by the -mctol keyword, which by default has a value of 0.001, i.e. plotting accuracy. MC integration allows the treatment of systems which are otherwise too large to be analyzed with adpop, but converges extremely slowly for systems with more than 10 DOFs due to the large empty space being sampled. For single-set vMCG calculations, the -mc option leads to MC integration over each matrix element ⟨g_{i} | P | g_{j}⟩; rather than integrating the population expectation value directly. This allows the use of Gaussian sampling and is much more efficient, giving good results for large systems. By default matrix elements with a low density A_{i}^{*}⟨g_{i} | g_{j}⟩A_{j} are ignored. The tolerance is controlled by the qtol keyword, and -noq means all matrix elements are integrated. For direct dynamics calculations, by default local DBs are used with only points close to the GWP on the RHS included. The -noq option means that Shepard interpolation is done over all points in the DB for all points in the MC integrations. For vMCG calculations, a quick and approximate calculation of the adiabatic populations can be made using a saddle-point approximation with -saddle. This evaluates the expectation value using the transformation only at the centre of all the GWPs multiplied by the overlaps. An even quicker (and less accurate) version includes only the diagonal matrix elements A_{i}^{*}⟨g_{i} | g_{i}⟩A_{i}P_{α}. This is obtained using the -saddle0 option. There is an OpenMP version adpop.omp that speeds up CDVR, MC and saddle point calculations. The number of threads, N, is selected with -omp N. Recommendations . For small grids use the default. For large grids, CDVR is the best option, but run the TDDVR calculation too. If these are similar the CDVR result is definitely to be trusted. For less than 10D systems MC integration can also be used as a check. For large single-set vMCG and DD-vMCG calculations use MC integration, with saddle-point as a quick check. With the MC integration f it runs quickly enough, try to take qtol to 0.0001 for a better result. If it is taking too long, try a qtol of 0.01.adproj
OptionsThe adproj program is used to calculate the adiabatic potential matrix elements and the adiabatic projector matrix elements for each electronic state. The program must be run in a directory containing a dvr-file and an oper file. The results are written into several vpot files that can be fitted with the potfit program. To do this the keyword "pes = none" has to be set in the potfit input file. With a QUANTICS-run the projection operator file can be created. To receive the adiabatic populations run expect with the projection operator file and the corresponding psi file.
NB: The vpot files for the adiabatic potential are: apr_vs, where s is the electronic state.
NB: The vpot files for the projection matrices are: apr_ps_ij, where s is the electronic state and ij denotes the matrix element, i.e. the diabatic states. Please note that the projection matrices are symmetric, this means that each off-diagonal matrix element is only given once. For more details see the MCTDH-guide chaper 11.8.3.
analysis
OptionsFollow the menus, and various information will be plotted.
aoverlap
OptionsThe aoverlap program is very similar to the overlap program, except that it considers the A-vectors exclusively, i.e. it implicitly assumes that the spf's of the two calculations are identical. aoverlap is useful when the two calculations to be compared use different DVR's but identical numbers of spf's. When the overlap between two calculations is OK but the aoverlap is not then the two calculations use different spf's, e.g. a different position of the projector. See also overlap below.
autospec
OptionsThe program computes the spectrum by Fourier transform of the autocorrelation function which is multiplied with the weight function exp(-(t/tau)^{iexp})×cos^{n}(πt/2T), (n = 0, 1, 2). (In the output file there is one column for each n). The variables tau (real [fs]) and iexp (integer) are input arguments. More precisely:
is the formula which is evaluated. Here c(t) is the autocorrelation function and T denotes the largest time for which c(t) is known. (T may be reduced by the option -t). The variable ω runs between E_{min} and E_{max}. The pre-factor prefac is 1/π if -FT is set (default), or is ω/π if -EP is set, or is 0.4279828×dipolemoment^{2} if -Mb is set. In the latter case, dipolemoment is the norm of the D×Ψ, where D denotes the dipole operator. This norm is printed in the QUANTICS log file, when the operation D×Ψ is performed by operate. The -Mb option allows to plot the absorption spectrum on absolute scale in mega barns (Mb). 1 Mb = 10^{-18} cm^{2}
When the option -lin is set, then the filter function cos^{n}(pi*t/2T) (n=0,1,2) is replaced by cos^{3}(pi*t/2T) (column 2), 1 - t/T (column 3), and (1-t/T)*cos(pi*t/T) + sin(pi*t/T)/pi (column 4). Note that the latter two filters are non-negative. A more comprehensive discussion can be found in the lecture notes Introduction to QUANTICS.
When one of the options -EP or -Mb is set, one must ensure, that the energy is the photon energy. It may hence be necessary to shift the energies from total ones to photon energies by using the -e option.
If the option -r is set, the program computes the resolution, i.e. the spectrum of a single line. The time points are taken from the auto file. If there is no auto file and if the option -t is given, a time step of 1 fs is assumed.
The pre-factor omega is omitted by default, or when the option -FT is given. In this case (and only in this case) the energy E_{min} (and eventually E_{max}) may be negative. NB: When the pre-factor is omitted (default), the spectrum is normalized to 1 au.
Example:
autospec -e 13.4071 ev 13 17 ev 50 2checkdb
OptionsCheck the properties of an SQL DB. It can also be used to remove points from failed calculations and duplicate points. These can be removed using a tolerance to define how far apart "duplicate" points can be.
chnpot
OptionsThe program interpolates natural potential terms calculated by program Potfit (written in "natpot" file) from one grid to another. Normally one runs Potfit on an initial coarse grid, then interpolates the natpot terms to a finer grid. At present, the program can interpolate only one or two dimensional natpot terms. The program reads the old grid from "dvr" file. The input file consist of three sections, a Run-Section, a Primitive-Basis-Section and a Fit-Section (see below) and the final keyword "end-input".
In Run-Section following keywords are possible:
Keywords of chnpot RUN-SECTION | |||
---|---|---|---|
Keyword | compulsory / optional | Description | equivalent option |
name=S | C | The name of the calculation. A directory with path S is required in which files will be written. | -D |
dvrdir=S | C | The old DVR file is located in directory S. | -d |
natpotdir=S | O | The old natpot file is located in directory S. If this keyword is not given, natpotdir=dvrdir is assumed. | -nd |
natpotfile=S | O | The path of the old natpot file is S. If this keyword is not given, natpotfile=natpotdir/natpot, or natpotfile=dvrdir/natpot is assumed. | -nf |
readdvr=S | O | The new DVR should be read from directory S. Without argument, S = name is assumed. Without this keyword the dvr file is created in the name directory. | -rd |
overwrite | O | Files in name directory will be overwritten. | -w |
The Primitive-Basis-Section is as in QUANTICS.
In the Fit-Section the parameters for interpolation are given. For translational degrees of freedom one can use cubic (bicubic) spline interpolation or ENO (Essentially Non Oscillatory) interpolation. For angular degrees of freedom (in the case of periodicity) one can select between cosine, sine or fourier interpolation. Note, that the interpolation method should be defined for each degree of freedom, and not for each mode. If grid points for some degree of freedom have not changed, it can be omitted. The keyword "spline" ("spl") is used for spline interpolation. ENO interpolation is currently implemented for non-combined modes. It consists basically on a polynomial interpolation where the points from the original data set used to obtain the interpolant function are automatically selected to fulfill some smooth criterium. The algorithm will provide a continuous non-oscillatory interpolation near regions with sudden changes in slope, as encountered for example when an energy cut is found in the original data. The formulation of the algorithm can be found in J. Comput. Phys. 71, (1987), 231-303. ENO interpolation is requested using the keyword eno, which can optionally be followed by the keywords rmax=integer, maximum degree of interpolation (default 3), rmin=integer, minimum degree of interpolation (default 1) and dfac=real, weight factor controling how preferential is the symmetric interpolation with respect to the asymmetric one (default 50.0). The ENO implementation is a new feature and by now is rather experimental. Use it with care. The defaults should provide a reasonable behaviour of the interpolator, specifically, setting a higher maximum order or lowering dfac too much may result in a noisy potential energy function at the end. Increasing too much dfac (say, above 200) will tight the interpolator always to a symmetric interpolation, thus not being able to avoid discontinuities. A good idea would be to compare it for a given case to the corresponding spline interpolation and pick up the most satisfactory result. The keywords "cosine" ("cos"), "sine" ("sin") and "fourier" ("ft") are used for the Fourier-interpolation of angular degrees of freedom. (NB: "ft" or (equivalently) "fourier" means that sine and cosine functions are used). The keyword "sym" after "sin", "cos" and "ft" can be used, indicating that only even functions (i.e. Cos2x, Cos4x, ...) should be used. The angular fit procedure is described in JCP 104,(1996) 7974. The parameter M (default is max(50,2*gdim)) can be given as a keyword following the sin, cos, or ft keyword (see Eq.(37) in JCP 104,(1996) 7974). Finally, the keyword "period=xx" defines the period of the potential curve, for which xx="2pi/N" or "P" format can be used, where N is an integer and P is a real number. If the keyword period is missing, period=2pi is taken as default. If the variable under discussion is not an angle, period should be set to the interval of periodicity. If the potential is not periodic, period should be set to twice the grid length.
The order of the arguments which follow the method keyword is arbitrary.
Here is an example of Fit-Section:
Fit-Section R spline r fourier 120 period=7.85 q eno rmax=3 dfac=60 Q eno dfac=70 rmin=1 theta cosine 60 period=2pi/2 phi fourier sym period=2pi end-fit-section
Here it was assumed that V(theta=0) = V(theta=pi), e.g. H_{2}O in Jacobian coordinates. If this periodicity is not given, e.g. H_{2}O in valence coordinates, period=2pi should be used.
Note, that the interpolation method for the degrees of freedom in combined mode should be the same (for angular modes cosine, sine and fourier can be mixed). Some parameters of the calculation are written to the "chnpot.log" file. The program writes the new natural potentials file "natpot" and the "dvr" file (if the option -rd or keyword readdvr in Run-Section are not used) to the name directory. For over-writing of the natpot file use "-w" option. For an example input file see chnpot.inp
Example:
chnpot -w -rd inputNote that chnpot may be used to change the modelabels. Chnpot maps the n-th old DOF onto the n-th new DOF, the modelabels are not used. If you just want to change the modelabels without re-fitting the potential, simply set up the PRIMITIVE-BASIS-SECTION of the chnpot input file using the new modelabels but otherwise the old basis definitions. A FIT-SECTION is not needed in this case.
compare
OptionsIs used by the elk_test program to compare different sets of results.
concat
OptionsConcatenates the wavefunctions in two restart files.
cleandb
OptionsCleans an old style flat file DB to remove points from failed calculations. Duplicate points can also be removed using a tolerance to define how far apart "duplicate" points can be.
convdb
OptionsInterconverts the database produced during a direct-dynamics calculation between binary and ascii, i.e. if binary files are present (type .db) they are re-written as ascii (type .dba) and vice-versa. The old DB files are deleted at the end.
convdbfromsql
OptionsConverts the database produced during a direct-dynamics calculation from an SQL database to a set of plain files. By default ascii files are produced (type .dba). The old DB files are deleted at the end.
convdbtosql
OptionsConverts the database produced during a direct-dynamics calculation from an old set of plain files, either ascii or binary, to an SQL format. The old DB files are deleted at the end.
convpsi dir p
Not AvailableConverts a multi-packet wavefunction to the corresponding single-packet ones, i.e. extracts the pth packet from the multi-packet wavefunction dir/psi and writes it to the file dir/psip (or dir/psi0p if p < 10). For p = 0 all packets contained in psi are extracted and written to the files dir/psi01, dir/psi02, etc.
crosscorr
OptionsThe two wavefunctions (density operators) must, of course, have the same primitive grids, but they may have different combination schemes and may differ in numbers of SPF's. A reference wavefunction can conveniently be generated by running QUANTICS with the -t option.
crosspec
OptionsThis routine simply performs the Fourier integral
without invoking damping functions (except possibly for sin(π t/T) and cos(π t/2T)). The option -dc subtracts the average of the cross-correlation function from this function before FT. E_{offset} is zero, if not set by option -e. The option -old removes the prefactor 1/π and interchanges the columns. (Now: Energy, Re, Im, Abs; with -old: Energy, Abs, Re, Im). The new output format is chosen to make crosspec compatible with autospec. The output file cspec.pl may be read by flux, using the -ed option of flux. In this case neither -g nor -a must be given, such that no GNUplot command lines appear in the output file.
If the option -r is set, the program computes the resolution, i.e. the spectrum of a single line. The time points are taken from the crosscorr file. If there is no crosscorr file and if the option -t is given, a time step of 1 fs is assumed.
ddgeom
Optionsddgeom computes the expectation values for the geometries of a direct-dynamics calculation.
ddgeom can analyse distances, angles and dihedrals for the expectation values of the geometries of a direct-dynamics calculation.
ddtraj
Optionsddtraj computes the expectation values for the coordinates from a direct-dynamics calculation to generate trajectories. On start up a menu will be presented with options.
By default the molecular geometries are output in Angstrom. It is possible to select the trajectory of the centre of a single GWP by entering the GWP number. The average structure can also be generated using the "av" option, or the average structure for a single electronic state using "avS" and then entering the selected state. If Jmol is installed it will be launched automatically to animate the molecular structure along the "trajectory". Additionally the geometries are written to ddtraj_X.pl files, with the tag X being the GWP number, or "av" for the average etc. If the option -notr is given and the propagation is in normal modes, then the values of the normal modes will be used and plotted using gnuplot. Again the trajectory for a single GWP or the averaged structures can be selected. The data is saved in ddtrajq_X.pl. If -wr is selected, the files are written but no animation shown. The option "all" writes all of the trajectory files withpout animation. The files can all be animated using jmol (or gnuplot for ddtrajq files).dengen
Optionsdengen computes 2D-densities similar as does showsys. However, in contrast to showsys, dengen computes only 2D-densities, is not menu driven, is not interactive and does not plot. It merely writes the data to an output file, which may then visualized by GNUPLOT. If the computation of the 2D-densities takes a large amount of computer time, the use of dengen is of advantage, because dengen may run in the background, overnight or on a batch system.
dengen computes the diabatic densities for multistate wavefunctions. The output file dens2d.dat displayes the coordinate values in the first two columns and then the densities, one column for each electronic state.
di2ad
OptionsThis program reads the wavefunction in a psi file, and uses the PES information in an oper file to transform it to the adiabatic representation. The waveunction and oper file must be in a full-grid representation. If the psi file was created using an MCTDH wavefunction, this can first be converted using the psi2ex program. The oper file can be created in a genoper calculation with an input file for a numerically exact calculation.
Output is in a full grid representation to the file psi.ad, unless otherwise given using -o FILE.
diag
Not AvailableProgram solves the generalized eigenvalue problem H1 B = H0 B E by a singular value decomposition, where H0 and H1 are overlap and Hamiltonian matrices calculated by Fmat program. The output of the program are the eigenvalues and intensities. The matrix elements are calculated using the hermitian or symmetric scalar product. The widths, in the case of symmetric scalar product, are calculated as -2*Im(E) .
Notes:
The arguments with options -lo,-hi and -n i.e. klo, hki and step are related to the calculated "mtt"-files, and not to the QUANTICS calculation. For example, if "mtt"-files were calculated with step=2, then using step=3 in Diag program will be equivalent to step=6 with respect to the QUANTICS calculation.
If "-t" option is used, the matrix elements are extended to negative times according to the rule: Psi(-t)=conj(Psi(t)). So, here the second set of overlap- and Hamiltonian matrices needed, calculated using the symmetric scalar product, if the first is hermitian, or hermitian scalar product if the first is symmetric. Note, that each set of overlap and Hamiltonian matrices should be calculated using the same scalar product (hermitian or symmetric).
The option "-u UNIT" changes the output energy unit to UNIT. The available units in program can be seen by shell-command "mhelp -s unit".
The following examples show the steps performing the diagonalization after completing the QUANTICS calculation. The first concerns the reactive system (to calculate resonances and widths), the second - the bound system.
1. fmat -sym ! calculates mtt_s fmat -sym -O H1 ! calculates mtt_H1_s diag -u ev -es 1.d-9 mtt_s mtt_H1_s 2. fmat ! calculates mtt_h fmat -O H1 ! calculates mtt_H1_h fmat -sym ! calculates mtt_s fmat -sym -O H1 ! calculates mtt_H1_s diag -u cm-1 -es 1.d-8 -n 2 -t mtt_h mtt_H1_h mtt_s mtt_H1_s
diffmap
OptionsAnalyses an MCTDH or exact wavefunction in a psi file using diffusion map or isomap methods. Works by sampling gridpoints of the wavefunction at each selected time, locating points where the density is some proportion of the density at the centre of the wavefunction. Selected points are then analysed using eith diffusion map (default) or isomap in order to provide insight into the actual modes which most well describe the dynamics. For more details see Richings and Habershon, Molecules, 2021, 26, 7621.
Start the program in the directory containing the propagated wavefunction in a psi file.
Recommendation: The sampling can take long time as the program looks for gridpoints where the density is sufficiently large (as determined by the thresholds given in the options), so this is probably best for use when analysing relatively low dimensional problems.
efield
Not Availableedengen
Not Availableedengen computes 2D (off-diagonal) pair-correlation functions (or pair-density matrices) <x,x|ρ_{2}|y,y> (similar to the one-body density matrix produced by prhosub). It works in analogy to dengen, which however calculates the diagonal density <x,y|ρ_{2}|x,y>. The data is written to an output file, which may then visualized via GNUPLOT (e.g with plgen). Note that, if the computation of the pair-correlation function is very time consumptive, edengen may run in the background, overnight or on a batch system.
edengen computes the diabatic densities for multistate wavefunctions. The output file dens2d.dat displayes the coordinate values in the first two columns and then the densities, one column for each electronic state.
expect
OptionsThe operator must first have been process by the QUANTICS program. This means that it must first be set up in a .op file. If it is known before a propagation is made, this operator can be included with the system operator in the main oper file (by using a named HAMILTONIAN-SECTION_XXX). Alternatively, e.g. if a propagation has already been made, the file oper_name can be generated using the genoper=name keyword.
Start the program in the directory containing the propagated wavefunction in a psi file. If no arguments are given, the program looks in the oper file to see which operators are there and asks which is to be evaluated. The -o option can use a file other than this. The expectation value of this operator is then calculated for each time, and output to the file expect.pl, unless otherwise instructed. The -a option enables the automatic plotting of the results.
fdcheck
Optionsfdcheck analyses the output of fdmatch. It computes the mean value and the variance of eigenvalues and intensities which are grouped together by fdmatch. If there is an exact data set, fdcheck computes the errors of eigenvalues and intensities with respect to the exact data.
fdmatch
Optionsfdmatch orders the eigenvalues computed by different filter runs such that optimal matches are obtained. The output of fdmatch may be piped to fdcheck.
flux
OptionsThe flux analyse routine has currently two restrictions:
- When projectors are used, they must project fully on a MCTDH-particle, i.e. projection on a dof within a combined mode is not possible.
- Projectors or operators operating on the CAP-mode are not allowed.
flux can work with operators and/or projectors, however, they must not operate on the CAP-mode. The operators are to be defined in an HAMILTONIAN-SECTION_xxx, where xxx is the name of the operator to which flux refers. Presently there are projectors onto eigenfunctions of one-mode operators (also to be defined in an HAMILTONIAN-SECTION_xxx ) and projectors onto diffractive states (plane-waves) and onto rotational states. For a full list of projectors available, see the table below. New projectors may be coded and added to the file analyse/flxprj.F. A very general and quite useful projector is the read projector. This projector is build from an SPF, P=|ψ><ψ|, which in turn is read from a (foreign) restart file. The arguments needed by flux are the energy-range ( including its unit) and the CAP-mode, i.e.: Emin, Emax, unit, CAP-mode . Often options are necessary to steer the performance of flux. Rather than options and arguments one may provide an input-file (for an example see below). Note: options will overwrite the statements of the input-file.
The option -t (Test run) is very useful for checking how many data sets are on the psi file, which CAP's have been used, what are the mode labels, etc. The most time consuming part is the generation of the function gtau, as it requires the computation of the matrix elements Wtt' of the CAP. If a gtau file exist, flux will try to read this file (provided the -w option is not given). Thus the computation of the flux for an other energy interval or a different flux-unit (-u) is fast, as the gtau file already exist. When the gtau file is corrupted, use -w to overwrite it. The options -n, -hi and -lo may be used to reduce the number of time-points when computing Wtt' and gtau. This is useful for convergence checks. The option -lo must be used when the mctdh calculation was run with auto-cap (ACAP).
The option -s start determines the grid-point from where on the flux is evaluated. To be more precise, start is the grid-point at which the g_theta evaluation is switched on. If the option -s is not given, start is set to the grid-point where the CAP is switched on. When start is larger than gdim(fcap) (i.e. grid length of the CAP-DOF), then the evaluation of the g_theta part is suppressed. See Appendix B of J.Chem.Phys 116 (2002), 10641, or the MCTDH-feature article (Theor. Chem. Acc. 109, 251 (2003)) for more details. It often improves the speed of convergence, in particular with respect to the total propagation time, if the start of the flux evaluation is moved closer towards the scattering center. Only for testing purposes one may chose a start value, which is further away from the scattering center as the default value, i.e. a start value which lies inside the CAP region.
The CAP may be left (i.e. located at small coordinate values, or right (i.e. located at large coordinate values, this is the default), or both (i.e. the CAP may be anywhere, no checking of areas where the CAP vanishes).
When the option -Mb is given, the flux spectrum will be multiplied with E×norm^{2} where norm is the argument to -Mb. The value of norm is given in the log-file of the mctdh run where operate was performed (Operate-Norm). norm is equal to ||D×Ψ||, where D denotes the operator used by operate. Make sure that a correct energy shift (-e option) is given, as the spectrum is multiplied with E.
Lines like the following are output by flux to screen (see also the flux.log file)
------------------------------------------------------------------------------ 2000*Integral(W_tt) = 996.1052 (total outgoing flux) 1000*Integral(flux) = 995.6810 (total outgoing flux) 1000*Integral(DELTA) = 998.8516 (total incomming flux) ------------------------------------------------------------------------------
The first and second lines gives the total flux going into the specified CAP. The total flux is obtained by (first line) analytically integrating the flux over all energies (see Eq.(118) of Theor. Chem. Acc. 109, 251 (2003)), or by numerically integrating the energy resolved flux over the specified energy interval. The third line is the numerical integral of DELTA(E) over the specified energy interval. Here:
where F denotes the flux operator. DELTA(E) can be obtained trough several ways. quanticsh may generate the so called enerd file (by giving the keyword correction=dia in the Init_WF-Section). (NB: The file enerd is called adwkb in older versions). flux will automatically look for such a file. Alternatively (by using the -ed option) one may use a spectrum.pl file (generated by autospec), or a cspec.pl file (generated by crosspec), or a flux file (generated by flux without employing projectors) as energy-distribution file.
Example (H+D_{2} reactive scattering):
flux -e lsth -lo 7 0.25 2.75 ev rvor
flux flx.inpwhere flx.inp is an input file. The extension .inp may be dropped. The input-file is organised similar to the QUANTICS input-file, however, there are no sections. The last line of the input-file must read: end-input. Below an example input file is shown.
------------------------------------------------------------- # flux input file. Surface scattering. # Average rotational energy for a specific diffraction state. outdir = flux_rot low = 26 flux-unit = mev operator = rot
projector 3 diff2 2 1 # mode ,name, parameters energy = 0.05, 0.30, ev cap = z end-input -------------------------------------------------------------
Using the -d option (or the keyword use-deriv) the flux is computed via a well known formula employing the derivative of the wavefunction. Matrix elements of the CAP are not evaluated. Presently this feature works only if there is a full projection and if the CAP degree of freedom is uncombined and represented by FFT. When using the derivative formulation it is recommended to move the evaluation point a few grid-points before the start of the CAP. (-s option).
Using the -wtt option one can disable the Fourier-transform to energy space and investigate the time-dependence of the flux. This information is stored in the wtt and iwtt files. The iwtt file (integral wtt) contains the values
where Θ denote a Heaviside function starting at the grid-point given by the -s option. (If -s is not given, the starting point of the CAP is used). Hence iwtt provides the probability that the WF has passed the point given by the -s option.
Example (Investigation of particle loss):
flux -wtt -s 21 rvKeywords of flux input-file | ||
---|---|---|
Keyword | Description | equivalent option |
overwrite | overwrites gtau file. gtau will be re-computed completely. | -w |
test | performs a test run | -t |
psi = S | read psi file form path S | -f |
outdir = S | write output to directory S | -o |
dvr = S | read dvr file form path S | -dvr |
edstr = S | read the energy-distribution from file S | -ed |
flux-unit= S | The computed flux is converted to unit S. If a number is given, the flux will be multiplied with that number. I.e. flux-unit=ev and flux-unit=27.2114 will produce the same output. This option is useful when an operator is applied. | -u |
operfile = S | read oper file form path S | -i |
high = I | Compute the flux (i.e. gtau) only up to the I-th psi-output | -hi |
low = I | Compute the flux (i.e. gtau) only from the I-th psi-output onwards. | -lo |
el-state = I | Compute the flux for the I-th electronic state only. | -es |
step = I | Compute the flux (i.e. gtau) only every I-th psi-output. | -n |
epoints = I | The number of output energy-points is I rather than 500. | -p |
cos = I | Cosine**I damping of gtau | -c |
exp = I, R | exp(-(t/R)**I) damping of gtau | -exp |
smooth | Smooth the Delta(E) data read from enerd file by averaging over 5 energy points. | -sm |
Mb = R | The argument is the value of Operate-Norm to be taken from the log-file of the mctdh operate run. The flux-spectrum is multiplied by E*opnorm**2. Make sure that a correct energy shift is given. | -Mb |
start = I | Evaluate the flux at the grid-point start. The default value for start is the start of the CAP (i.e. the last grid-point with vanishing CAP). | -s |
theta-only | Uses only the theta-part of gtau when computing the flux. This is useful for investigating the importance of the theta-region. Note: The W-part only of gtau will be taken when start is set to a number larger than the number of grid-points of the CAP-mode. | -x |
gtau-only | Compute only the theta-part of gtau. This option requires that a gtau file exist. The time-consuming evaluation of the W-part of gtau is suppressed, but gtau_theta is re-evaluated. This option is useful to test different start points (see keyword start). Note: the keywords low and high will be ignored. There values are taken from the previous run. | -v |
wtt-only | Compute only the diagonal terms Wtt.This rather fast calculation is useful to determine the optimal value for low (-lo). | -wtt |
eoffset = R, S | The offset energy is set to R in units S; e.g. "eoffset = 0.3, ev". Note: "eoffset = lsth" is equivalent to "-e 4.74746 ev". | -e |
use-deriv | Compute gtau from spatial derivative of wavefunction. | -d |
eoffset = R, S | The offset energy is set to R in units S; e.g. "eoffset = 0.3, ev". Note: "eoffset = lsth" is equivalent to "-e 4.74746 ev". | -e |
operator = S | Apply operator S before evaluating the flux. | -O |
projector I S (S1) I1 I2 .. | Apply the projector S with(label S1 and) parameters I1 I2 ... to mode I before evaluating the flux. projector has to be the first keyword on a line. There are no equal-sign and no commas. There may be several projectors. One line for each projector. No additional keywords in a projector-line. | -P |
energy = R1, R2, S | Evaluate the flux between Emin=R1 and Emax=R2 where Emin and Emax are given in unit S. | (arguments) |
cap = S or I | The cap is on mode I. Rather than giving the number of the mode, I, one may give the modelabel S. If I is larger than the number of DOFs, this number is interpreted as the H-term, h, of the CAP (run flux -t and/or see op.log file). This feature becomes important if there are several CAPs. | (arguments) |
captype = S | The cap-type is S=both,right,left. | (arguments) |
Projectors | |||
---|---|---|---|
projector name | label | parameters | Description |
eigenf | name of an operator | pop | An eigenfunction of a 1D operator is taken as projector. The 1D operator is to be defined in a HAMILTONIAN-SECTION_ XX when the operator-file is build. The operator XX must be of usediag type. A 1D spf is assumed, i.e a combined mode is incompatible with eigenf. The parameter pop defines which eigenfunction is taken. pop=1 refers to the ground-state. |
read | path of restart directory | pop state | The pop-th SPF of a "foreign" restart file is taken as projector. This "foreign" restart file may be build by an geninwf run. The primitive grids and the combination scheme of the "foreign" restart file and the present calculation must be identical, but the numbers of SPF's and the number of electronic states may differ. If the parameters pop and state are not given, they are set to 1. |
sph | (none) | j m | projects on the (j,m_{j}) rotational state. A sphFBR (see Primitive Basis Section) is required, the two modes of which must not be further combined. I.e a 2D spf is assumed. |
diff | (none) | n | projects on the n-th diffraction channel. (i.e. onto a plane wave). A 1D spf is assumed. |
diff2 | (none) | n m | projects on the (n,m)-th diffraction channel. (i.e. onto a 2D plane wave). A 2D spf is assumed. |
pop2 | (none) | n | projects on the n-th basis function of an underlying DVR. This projector thus can only be used if the (uncombined) DOF is described by an simple DVR. |
Leg | (none) | j | projects on the j-th rotational state. A Leg or Leg/R DVR is required as primitive basis and the DOF should be uncombined. |
KLeg | (none) | j m | projects on the (j,m_{j}) rotational state. A KLeg-DVR combined with a K-DVR, i.e. a 2D spf, is required. |
PLeg | (none) | j m | projects on the (j,m_{j}) rotational state. A PLeg-DVR combined with an exp-DVR, i.e. a 2D spf, is required. |
KLeg2 | (none) | j_{1} m_{1} j_{2} m_{2} sym | projects on the
(j_{1},m_{1};j_{2},m_{2})
rotational state of two coupled angular DOFs. The mode must be
of the type KLeg/K/KLeg/K, i.e. a 4D mode. If sym>0
(sym<0), the projection is on the symmetrized
(antisymmetrized) state, i.e.
{|j_{1},m_{1},j_{2},m_{2}> ± |j_{2},m_{2},j_{1},m_{1}>} / √2 . |
Wigner | (none) | j k m | projects on the (j,k,m) rotational state. A Wigner-DVR combined with two DVRs of either type exp or K, i.e. a 3D spf, is required. |
fmat
Not AvailableN.B. The outputfile is called "mtt_h" or "mtt_s" if no operator is used (i.e. if the overlap matrix is calculated) and is called "mtt_h_oper" or "mtt_s_oper" if the operator oper is employed. The flags "h" and "s" are for the case of hermitian and symmetric scalar products. The operator oper must be defined in a HAMILTONIAN-SECTION_oper and must carry the nodiag flag. The generated matrices may be diagonalised (generalised eigenvalue problem) to obtain the eigenvalues of the operator oper. This should be done with the program diag. Resonances may be calculated as well by using the symmetric scalar product (-sym option).
guessfld name
OptionsThe field is defined by:
The field will be written in ASCII to the file fieldf.0 for every tout over the interval -2×tout ... t_{final} + 2×tout.
gwptraj
Optionsgwptraj plots the centre coordinates or momentum of GWP basis functions. It is a menu driven program and plots can either be for a single DOF against time, of in a selected 2D space. Phase space plots are also possible.
herma
Not Availablegwptransmission
Optionsjinpol
Optionsjinpol interpolates the (reaction) probabilities for different total J. As input it needs two sets of probabilities (e.g. flux files) for J1 and J2. It then creates probabilities for all J with J1 < J < J2. The algorithm has some similarity with J-shifting, but is much more accurate. This J-interpolation algorithm is described in an appendix of J.Chem.Phys. 116 (2002) 10641.
NB: The input files may be in flux-file format or just two-columns ASCII files (energy,probability).
NB: The energy unit is assumed to be eV. Otherwise the R0 value is incorrect, but the interpolation will work. Likewise, if a wrong mass is put in, only the printed value of R0 will be affected.
joinpsi name1, name2, ...
Not AvailableThe program is useful, if the maximum number of SPFs is not needed for all propagation times (for example in the scattering problem). One may perform several calculations with varying numbers of SPFs (usually with smaller numbers of SPFs at the beginning and at the end of the propagation, if it is a scattering process), and then joins the psi-files with the aid of this program for the further analysis (e.g. flux analysis, etc.). The number of SPFs for the resultant psi-file equals the maximum from all psi-files. The artificially augmented SPFs are filled with zeros. The program is working only with psi=single or psi=double formats.
enqoper
OptionsReads parameters and data stored in the information in an oper file. This is useful to check settings.
- enqoper -list
Lists the name of parameters that can be read. - enqoper data
Prints the value of data to teh screen.
maxpe name
OptionsCalculates the maximum and minimum value of a PES. This is useful to check for the presence of large eigenvalues, which affect the efficiency of a numerically exact propagation.
- Generate an oper file ready for a numerically exact calculation, i.e. the keyword exact should be present in the RUN-SECTION.
- Run maxpe. Output is to the screen.
Note that vminmax is a more powerful alternative which does not require the operator in exact format.
ml2mctdh name
OptionsConverts a multilayer wavefunction in a psi/restart file to an equivalent MCTDH form.
ml2mctdh name
OptionsConverts a multilayer wavefunction in a psi/restart file to an equivalent MCTDH form.
mmemtest
OptionsRun mmemtest on the computer to see how much memory is available.
norm
Optionsnpotminmax
OptionsThe program is similar to vminmax, except that the generation of a PES file is skipped and a set of natpot files is used to generate the potential operator. The program requires an input file which contains at least a RUN-SECTION specifying job parameters and a NATPOT-SECTION listing paths to natpot files. In addition, either the keyword readdvr in the RUN-SECTION needs to be set or a PRIMITIVE-BASIS-SECTION needs to be present in the input file. Note, that the system DVR may contain more degrees of freedom than the natpot files are defined on. Furthermore, the natpot files can have different sets of degrees of fredom compared to each other as long as all degrees of freedom are contained in the system DVR, i.e., it is similar to constructing the operator-file from different natpot files.
In Run-Section following keywords are possible:
Keywords of npotminmax RUN-SECTION | |||
---|---|---|---|
Keyword | compulsory / optional | Description | equivalent option |
name = S | C | The name of the calculation. A directory with path S is required in which files will be written. | -D |
readdvr = S | C/O | The DVR file containing all system DOF is located in directory S. Compulsory if there is no PRIMITIVE-BASIS-SECTION. | -d |
trajectory = S | O | The scan is not done over all grid points but only over a subset. S is the path to an ASCII file containing the DVR indices of the grid points, where one grid point is given per line. Note, that the indexing is assumed to be in the same order as the DOF appear in the PRIMITIVE-BASIS-SECTION, i.e., the first index belongs the first coordinate in the PRIMITIVE-BASIS-SECTION, etc. The indices are assigned to the natpotfiles by their modelabels as in the Hamiltonian generation. | -t |
compare = S | O | Compare the sum of all natpot files to a surface file S. That is, after summing the contributions of all natpot files for the n-th grid point, substract the value from the n-th line in S. If the -t option is given, S must contain at least as many lines as the trajectory file where ist is assumed that the n-th line of S corresponds to the n-th line of the trajectory. If the -t option is not given, S must contain as many lines as there are grid points in the system DVR, where the index of the first coordinate runs fastest, the index of the second coordinate second fastest etc. | -c |
wrsrf | O | Write the sum of all natpot files to a surface file srf.dat in the name directory. | -srf |
overwrite | O | Files in name directory will be overwritten. | -w |
The NATPOT-SECTION only contains a list of paths to directories holding a natpot file.
Example:
NATPOT-SECTION ../POTFIT/pf_Q1_Q2 # directory with natpot of Q1 and Q2 ../POTFIT/pf_Q2_Q3 # directory with natpot of Q2 and Q3 ../POTFIT/pf_Q1_Q3 # directory with natpot of Q1 and Q3 end-natpot-section
Output files (in name directory)
- npotmm.log
- The log file.
- dvr
- The primitive grid definitions. (Only if a
PRIMITIVE-BASIS-SECTION is given in the input file.)
- largest.dat
- The set ot N largest values found, the coordinates as well as
contributions of the single natpot files.
- smallest.dat
- The set ot N smallest values found, the coordinates as well as
contributions of the single natpot files.
- smallest_abs.dat
- The set ot N smallest absolute values found, the coordinates as
well as contributions of the single natpot files.
- natpot_statistics
- For each natpot file its mean and RMS values as well as largest, smallest and smallest absolute values found plus their coordinates
natpot2cpd
Not Available The program reads a natpot file and converts it to canonical polyadic decomposition (CPD) format. The CPD file will use the same mode-combinations and mode-labels as the natpot. In a first step, an initial guess in CPD format is created, depending on the given command line options from the given natpot file or simply from random numbers. Subsequently, an optimization procedure is started to iteratively improve the quality of the CPD fit compared to the natpot file using alternating least squares (ALS).Several output files will be written to the name-directory:
- cpd The output file containing the potential in CPD format. Can be used similar to natpot files. See Hamiltonian input documentation.
- np2cpd.log The log file with various information.
- np2cpd_iterations Fit error as a function of the iterations of iterations. Also contains the condition number of the problem and, if -spd is set, total functional that is being optimized, including the regularization part.
- np2cpd_timing Information in time spend in various subroutines.
- np2cpd_stop Stop file. Can be used to stop the ALS optimizer prematurely. The iterations are stoped if np2cpd_stop is removed or does not contain the word "continue" as its first entry.
- als_eigenval_mode_m If -ev is set, these files contain the eigenvalues of the problem solved during the ALS iteration for mode number m. This file is only produced in last iteration step.
- cpdovlp If option -o is given this file contains the overlap matrix of the cpd basis functions.
- cpdcoeff If option -l is given this file contains the coefficients of the cpd basis functions (the core tensor).
Examples
natpot2cpd84 -r 30
natpot2cpd84 -mnd -DD CPD.r100 -r 100 -n 25000 -g 10 1000 -v -l
natpot2cpd84 -mnd -DD CPD.r200 -CC CPD.r100 -r 200 -n 12000 -v -l -ev 1.d-10
The use of the -g option is recommended. Using the -ev option often provides a better fit, but at higher computational costs. The smaller the regularization parameter, the larger become the coefficients (CPD core-tensor) and hence the condition number. The latter should not exceed the value of 1000.
The program supports parallelization with OpenMP. We recommend
compilation with the -P option. Furthermore, as several liner algebra
operations are performed, linking to an optimized Lapack
package is of advantage (needs editing of compile.cnf).
For instance: compile -P -x lapack natpot2cpd
oppsi operator
OptionsApplies the operator operator, defined in the oper file, to the wavefunction stored in psi.
ortho
OptionsThe output is to the screen and shows the square root of the sum of the squares of the matrix-elements of (ov-1) where ov denotes the overlap-matrix of the spf's.
overlap [-f -i -o -n -w -h -?] comp_file
OptionsCalculates the error (overlap) between the wavefunctions (density operators) in ./psi (or FILE) and comp_file . The results are written to the screen and a file, the name of which depends on the input file names, or the argument of the -o option. E.g.
overlap ../dir/psicalculates the error between the wavefunctions (density operators) in ./psi and ../dir/psi, and the results is stored in ./ovl_dir (unless the -o option was used). The WFs on ../dir/psi are taken as bra-states and the WFs of the psi-file of the current directory are the ket-states.
In contrast
overlap -i psi1 psi2would calculate the error between the wavefunctions (density operators) in ./psi1 and ./psi2, storing the results in ./ovl_psi2.
overlap can compute the overlap between exact and MCTDH WFs and between MCTDH WFs with different mode combinations. However, these calculations will be slow. In general one overlaps WFs with identical mode combination schemes, different numbers of SPFs are no problem. overlap85 can also overlap ML-MCTDH WFs, but only ML with ML and the two WFs must have an identical tree-structure.
The output (on screen) is as described in the review Eqs.(159-163). In particular:
The overlaps <psi1|psi2> <psi1|psi1> and <psi2|psi2> are written to the file ovl_dir, where dir denotes the name-directory of the second calculation. If this file exist and when the option -w is not given, overlap will read the file ovl_dir rather than re-do the calculation.
pexpect
Not AvailableThe first argument "mode" is the (combined) mode for which the expectation value is calculated. The second argument "operator" is the name of the operator, as specified in an HAMILTONIAN-SECTION_xxx, for which the expectation value is required. If "system" is chosen as operator the uncorrelated energy of the specified mode is computed. If no argument is given, the user is prompted for the missing argument(s). The operator must first have been processed by the QUANTICS program. This means that it must first be set up in a .op file. If it is known before a propagation is made, this operator can be included with the system operator in the main oper file (by using a named HAMILTONIAN-SECTION_XXX). Alternatively, e.g. if a propagation has already been made, the file oper_name can be generated using the genoper=name keyword.
Start the program in the directory containing the one-particle density in a pdensity file. If no operator is given, the program looks in the oper file to see which operators are there and asks which is to be evaluated. The -o option can use a file other than this. The expectation value of this operator is then calculated for each time, and output to the file pexpect.pl, unless otherwise instructed. The -a option enables the automatic plotting of the results. Note that pexpect computes expectation values of one-particle operators. (For combined modes this may include more than one degree of freedom). If the specified operator acts on several modes, pexpect uses only the uncorrelated part for the specified mode.
prhosub
Not AvailableThe pdensity file must have been produced with the line pdensity=I in the run-section. Here, I is the number of the degree of freedom of interest. pdensity=I will then contain the reduced density in natural orbital representation. prhosub produces one file of output for each tout, with the reduced density represented on the primitive grid. The columns are then x, x', real part, imag. part, absolute value.
Start the program in the directory containing the one-particle density in a pdensity file.
probsq
OptionsThe program computes the integral
where T denotes the final time of the autocorrelation c(t) and g(t) is some weighting function
For large T this converges to Σ p_{i} , where p_{i} denotes the occupation probability of the i-th eigenstate. This sum is related to the so called quadratic entropy. Output are the values Σ p_{i}, 1/(Σ p_{i}), and -Log_{2}(Σ p_{i}).
psi2ex
OptionsThe program reads the MCTDH wavefunction in a psi file and converts it to the numerically exact form, represented on the full grid. This is useful for other analyse routines. The output is by default single precision to the file psi.ex. The argument -dp forces double precision output, and -o FILE changes the output file name. The argument -pop2 gives the exact wavefunction in second population. In case some of the degrees of freedom is of fft type, the x axis (which in such a case is the momentum axis) can be swapped using the option -plot, so that it goes from negative to positive values and can nicely be plotted. In case -plot is set, the momentum grid ranges from -(gdim/2)*dp to (gdim/2-1)*dp in steps of dp, where dp=2*pi/(dx*gdim). The values for dx (grid spacing) and gdim (number of grid points) are listed in the log file. In case -plot is not set, the momentum grid runs form zero to (gdim/2-1)*dp and then from -(gdim/2)*dp to -dp.
The format of the psi file is explained in the QUANTICS/Output Documentation.
When the option -abs is given, the absolute value of the wavefunction is written. In this case the file contains only the wavefunction (i.e. no header, no dummy A-vector). The order of the elements is like in a Fortran array: Psi(dof_1,dof_2,...,dof_f). To inspect the WF it may be written in ASCII format (-ascii). Furthermore, the coordinates may be printed together with the WF-values to an ASCII output file (-ort) and DVR-weights may be removed from the WF (-W, requires that -ort is set).
psi2rst
Optionsrdacoeff
Analyse program "rdacoeff" (Read A-coefficients) ------------------------------------------------------------------------------ Purpose: Prints the A-vector of a wavefunction or restart file. Usage : rdacoeff [-f -i -n -n1 -n2 -s -max -thr -uplo -r -abs -abs2 -re -im -t -at -count -ver -h -?] . Options: -f FILE : The wavefunction is read from file FILE rather than from ./psi The string FILE may be a relative or a full path-name. -i DIR : data is read from directory DIR -n step : Print the A-vector only every step-th output. -thr thr: Print only coefficients whose absolute values are larger than thr (default: 10^-8). -max mx : Print only coefficients whose absolute values are smaller or equal than mx. -uplo ul: Print only coefficients from the upper (ul="U") or lower (ul="L") "triangle" of the A-tensor. If ul="L" is set, only A_j1_j2... with (j1-1)/(n1-1) + (j2-1)/(n2-1) + ... <= 1 are taken into account, if ul="U" is set, only A_j1_j2... with (j1-1)/(n1-1) + (j2-1)/(n2-1) + ... > 1 are taken into account. -n1 n1 : Print only coefficients with J.ge.n1. -n2 n2 : Print only coefficients with J.le.n2. -t tm : Print only WFs with time .le. tm. -at atm : Print only WFs with time .ge. atm. -s s : Print only coefficients for state s. -count : Count the number of coeffs between thr and max. -r : Take the restart file rather than the psi file. -rst : Same as -r. -abs : Print abs(psi). -abs2 : Print abs(psi)**2. -re : Print Re(psi). -im : Print Im(psi). -ver : Version information about the program -h : Print this help text. -? : Print this help text. It is in general useful to pipe the output into less: rdacoeff | less or to re-direct it into a file: rdacoeff > acoeff ------------------------------------------------------------------------------
rdautoe [-f -i -o -d -t -h-?] ns nmd
Not AvailableThe routine rdautoe reads the autoe-file and writes the modified autocorrelation function to the output file (e.g. autoe.pl) which has exactly the same format as the auto file and hence may be read be the routine autospec. By modified autocorrelation function we denote the autocorrelation which is calculated by dropping the most weakly occupied spf of mode nmd and state ns. A spf in each mode (and state) is dropped, if nmd=0. If the option -d is given, the difference of the modified autocorrelation and the (original) autocorrelation is outputed.
rdcheck [-f -i -oc -on -g -gq -t -h -?] ns nmd
OptionsIf one just wants to check the convergence of the natural weights, type: rdcheck 0 , or, to see the development of the lowest natural weights in timesteps of 1.2 fs:
rdcheck -t 1.2 0The entropies of the natural populations are written to screen with the command rdcheck -entropy s 0, where s is to be substituted by the electronic state to be inspected. If there is only one state, s may be dropped. Similar information is obtained with the -tr2 option.
where p_{i} denotes the normalized (by norm^{2}) i-th natural weight.
rddddb
Reads direct dynamics DB file geo.db (or geo.dba if ascii DB) and writes the geometries and energies into a formatted file plot.db . This is in a pseudo-Gaussian format and the geometries can be plotted by e.g. the Jmol program. There are no arguments
rdgrid dof
OptionsThis program is useful to obtain a quick overview of the actual locations of the grid points. Note that the programs showsys and showpot can show cuts of multi-dimensional potential energy surfaces by cutting at grid points only. The input values for the cuts are hence changed by these programs to take the value of the nearest grid point.
To plot the DVR points or weights use the -s and -oc or -w options and re-direct the output to a file. The data can then be plotted by plgen. E.g. plotting coordinate 2 vs grid:
rdgpop -s -oc 2 > file plgen fileOr plotting weights vs coordinate:
rdgpop -s -w 2 > file plgen file 2:3rdgpop nz dof
OptionsThe grid population is summed over the first nz and the last nz points of both the spatial (DVR) grid and the basis (FBR) occupations. By varying nz one may study how much the grid may be shortened. The integer dof specifies the degree of freedom to be investigated. Depending on the QUANTICS input, the grid populations are summed over all electronic states or (if gridpop=el is given in the run-section) treated separately for each electronic state. For a simple check on the convergence with respect to the primitive grids simply type rdgpop 1 0 while being in the name directory.
rdnatpot
OptionsThis program is useful to obtain a quick overview on what is on a given natpot file. Information on the grids, mode combinations, and numbers of SPPs are written to rdnatpot.log. On demand the program writes the natural potentials (SPPs) and the D-tensor to ASCII files.
rdsteps
OptionsThis program reads the steps file and provides information on the integration efficiency
rdupdate
OptionsReads the CMF step sizes from file, and removes repetition steps. The use of the -inter argument starts an menu to enable interactive plotting of the data. Without this argument, the data is written to the screen.
rdauto
OptionsThe use of the -inter argument starts an menu to enable interactive plotting of the data. Without this argument, the data is written to the screen.
rdeigval
OptionsThe use of the -inter argument starts an menu to enable interactive plotting of the data. Without this argument, the data is written to the screen.
reflex
Optionsrdspf
Not Availableshowd1d
OptionsFor instance, showd1d -a f2 would plot the density for the 2nd degree of freedom by automatically calling GNUplot. If RETURN is pressed, the density for the next output-time is shown.
The output is to a file den1d_fx_sx or den1d_fx if no state is specified.
The state is by default taken as 1. Thus if sx is not specified as an argument the 1st state is selected. Note that there is normally only one (effective) electronic state as the densities of the different states are summed before they are written to the file gridpop. If you want to avoid this and investigate the different electronic states separately, you have to provide the keyword "gridpop=el" in the mctdh input file.
The options -T, -S, -I, and -M selects the format for the output.
A Gnuplot index file writes a set of data for each time:
coordinate, Abs(spf), Re(spf), Im(spf)with 2 blank lines between. Gnuplot can then select a set using the "index" option of the "plot" command. If -I id is specified only the plot number id will be ploted. (This is particularly useful when the plot should be printed. See the -p option). If -S is specified (or, since this is the default, if no format option is given) one can scroll through the pictures by pressing RETURN. If -M is specified one sees a "movie", one picture each second.
A Gnuplot grid file (option -T) writes a set of data for each time:
coordinate, time, Abs(spf), Re(spf), Im(spf)with 1 blank lines between. Gnuplot can then plot a 3D plot of the spf evolution with time.
The mathematica option (-Ma) writes information to the screen to be read by a mathematica script (plspf.m). This enables dynamic pictures.
If one want to use showd1d to investigate the grid populations, one should use the option -nw (no weights) because the use of weights may lead to a wrong conclusion. The option -l (logarithmic plot) is also useful when checking grid populations.
showfield
OptionsReads the oper file and plots a time-dependent field.
showpot
OptionsCuts of a potential energy surface (PES) can be generated from a vpot and a natpot file. Both files are generated by the potfit program. The first one contains the exact potential on the complete product grid, the latter a corresponding fit.
After starting the program a menu is presented by the help of which one can select a cut via an interactive process. The menu offers the following choices:
- Select WHAT is plotted: if both files, a vpot file and a natpot file, are read one can plot the PES or a fit of it or the (absolute) difference of both.
- Select between 1D and 2D cuts.
- Select new energy bounds for the plot.
- Change the bounds for the one or two modes which define the cut.
- For a 2D cut contour plots can be generated for which one can specify the number of contours and the corresponding PES levels. Choose between a linear and a logarithmic spacing (see below).
To define a cut, one must attribute x to one coordinate, and one may attribute y to another coordinate (the latter choice generates a 2D plot). The remaining coordinates must be assigned numbers (coordinate values), but at most one of these coordinates may be assigned with the label min or max. If min or max is given, the program sets this coordinate such that the potential is minimal (maximal)with respect to variations of this particular coordinate. max is useful for the plottask abs(Vfit-Vpot).
Description of the logarithmic spacing if Gnuplot commands are included into the output file:
- Firstly, the program calculates the difference d=zmax-zmin, where zmax (zmin) is the upper (lower) bound chosen for the contour levels. In a second step, the program calculates a basis b<1 such that b^{n-1}=r, where n is the number of contour levels and r<1 is a so-called "reduction factor" provided by the user. Contour level i is now fixed at zmin+d*b^{i} , where i runs from 0 to n-1. Note that according to this procedure zmax and/or zmin may be negative!
showrst
Not AvailableThe state is by default taken as 1. Thus if sx is not specified as an argument the 1st state is selected.
E.g. showrst -a -re f2 would plot the real-part of the single-particle functions for the 2nd degree of freedom. GNUplot will be called automatically (-a option). The output is to the file rst.pl_f2.
showspf>
OptionsE.g. showspf -a -spf f2 4 would plot the absolute value of the 4th single-particle function for the 2nd degree of freedom.
By default natural orbitals are output to a file natorbx_fx_sx. If the -spf flag is used, the single-particle functions are output to a file spfx_fx_sx. Also by default, for combined mode SPFs, the SPFs are integrated over the other DOFs and only the absolute can be plotted.
The state is by default taken as 1. Thus if sx is not specified as an argument the 1st state is selected.
The options -T, -S, -I, and -M selects the format for the output.
A Gnuplot index file writes a set of data for each time:
coordinate, Abs(spf), Re(spf), Im(spf)with 2 blank lines between. Gnuplot can then select a set using the "index" option of the "plot" command. If -I id is specified only the plot number id will be ploted. (This is particularly useful when the plot should be printed. See the -p option): If -S is specified (or, since this is the default, no format option is given) one can scroll through the pictures by pressing RETURN. If -M is specified one sees a "movie", one picture each second.
A Gnuplot grid file (option -T) writes a set of data for each time:
coordinate, time, Abs(spf), Re(spf), Im(spf)with 1 blank lines between. Gnuplot can then plot a 3D plot of the spf evolution with time.
The mathematica option (-Ma) writes information to the screen to be read by a mathematica script (plspf.m). This enables dynamic pictures.
For a pMCTDH(I) density matrix, showspsf can plot the diagonal of the SPDOs. Note that SPDOs may be traceless, in which case the diagonal will be zero.
showsys
OptionsCuts of a potential energy surface (PES) can be generated from an oper file, and cuts and (1D or 2D) densities of the wavefunction can be generated from a psi file.
- To plot the WP or the PES, Move to the directory where the output files are, and start showsys
- To plot just the PES, move to the directory where the output files are, and start showsys -pes. This saves the time reading the psi file.
If the (1D or 2D) densities of the wavefunction are to be displayed in the second representation, i.e. as basis set occupation, momentum representation or angular momentum representation, use the option -pop2 . (This switch is not available through the menu).
After starting the program a menu is presented with the help of which one can select a plot via an interactive process. The menu offers a range of options. For example:
- Select (using "10 change plot task") between cuts of the adiabatic or diabatic potential, when a potential is plotted. When a wavefunction is plotted, one may chose between plotting cuts of the adiabatic wavefunction (abs), cuts of the diabatic wavefunction (abs) or the diabatic reduced density. The latter is the default. The reduced density is defined by integrating |psi|^2 over all variables except the one or two denoted by "x" or "x" and "y".
- Select a cut using "20 change coordinate section". This requires a coordinate value for each degree of freedom typed on a single line. One coordinate must be denoted "x", and one may be denoted "y". If no "y" coordinate is specified, a 1D plot is made.
- A cut along a vector can aso be defined using option option
"20". Enter either qfile or file to read in the
start and end coordinate of the vector in normal mode or cartesian
coordinates respectively. The format of the file is a text file with
the vectors in column format. For example the file qcut.dat with
0.0 0.10 0.0 0.15 0.0 0.05
would plot a cut in a 3D normal mode system from (0,0,0) to (0.1,0.15,0.05). The x-axis is labelled with the structures along the cut, with the start point at 0 and the end point at 1. - Change the bounds for the one or two modes which define the cut.
- For a 2D cut contour plots can generated for which one can specify the number of contours and the corresponding PES levels. Choose between a linear and a logarithmic spacing (see showpot below for details).
- For a 2D plot, 3D surfaces can also be produced. Toggle between surface, contour, or both.
- The plot can be printed to a postscript file, or a printer, or saved as a gnuplot file for further editing.
- If the system has more than one electronic state, choice can be made as to how many states, and which, will be plotted.
If the psi file contains a number of snapshots these will be displayed a shot at a time. In the default "step through" mode, press enter to change the frame. Using option 280 it is possible to change to "movie" mode, when the frames are shown at 1 second intervals. It may be useful to turn of the key (option 240) as the key (labelling contours) can cause the frames to have different sizes.
Using the "overlay" option it is possible to display a PES under the evolving wavepacket. First plot and save the PES to an xyz file (option 5). Change to plotting a wavepacket (using 10). Then turn on the overlay plots option with 400. Now with 410 the file name should be given containing the PES. The selected file name is shown. Unless the replot options are toggled (9 for the plot, 420 for the overlay) "plot to screen" (1) will now prompt for contours for both plots before plotting.
Warning: Plotting densities may take a large amount of computer time, if the dimension is large (f>3). Because of this it may be useful to reduce the number of plots by shortening the time-interval. Use menu point 30 to set the time-bounds appropriately. Alternatively (and simpler) one may use the options -n and/or -skip and/or -step to limit the number of wavefunctions read in and processed. E.g. showsys -n 11 will plot only the densities for the first 11 time-steps. If tout=1 this means from 0 to 10 fs. showsys -skip 50 -n 1 will plot the density no. 51 only, and showsys -skip 5 -n 2 -step 10 will plot the densities no. 6, 16 and 26.
Note that there is the routine dengen which generates 2D densities similar as showsys does.
statepop
Optionsstatepop plots the diabatic populations from a on-adiabatic simulation. The -inter option allows interactive plotting.
sumrst
Not AvailableThe program calculates the superposition of up to eight wavefunctions from restart files. The input wavefunctions must have the same primitive grid and mode combinations, but may differ in the number of SPF. The algorithm used is outlined as follows:
- Scan input files and determine maximum number of SPFs.
- Read first restart (psi2) and multiply with coefficient.
- Read next restart (psi1) and multiply with coefficient.
- Construct a SPF-basis from SPFs of psi1 and psi2 while skipping linear dependent SPFs.
- Transform psi1 and psi2 to the new SPF-basis.
- Add psi1 and psi2 (spsi).
- Transform spsi to natural orbitals.
- Reduce SPF basis of spsi if more files are left.
- Copy spsi to psi2.
- If more files are left then goto 3.
- Check superposition and write new restart. Done.
In step 8, the number of SPF for a given mode m is reduced if the superposition is constructed from more then 2 input wavefunctions. The new number of SPF for a given mode is the maximum number of SPF for this mode found in the input files. That is, the largest numbers of SPF found in the input files determine the precision of the new wavefunction.
For two wavefunctions the superposition is exact.
The program requires an input file with a RUN-SECTION and an INIT_WF-SECTION.
Keywords for sumrst RUN-SECTION | |
---|---|
Keyword | Description |
name=S | The name-directory to write the new restart file to |
normalize(=R|S) | Norm of the new wavefunction. The new wavefunction will be normalized to unity if no argument is given. If a real number R is given, the wave function will be scaled to norm R. Alternatively the strings S='yes' or S='no' can be given where S='yes' will result in a normalization to unity, S='no' will leave the wavefunction unchanged (same as not giving the keyword normalize at all). |
overwrite | Enable overwrite of output |
Keywords for sumrst INIT_WF-SECTION | |
---|---|
Keyword | Description |
file=S | Path to a directory with a restart file |
coeff=R(,R1) | The coefficient to be multiplied to the wave function specified in the previous 'file' statement where R is the real part of the coefficient and R1 the imaginary part. |
All keywords within the INIT_WF-SECTION are mandatory. Furthermore, a file statement must be followed by a coeff statement. An example input file would look like:
RUN-SECTION name = HADplus normalize = 1 end-run-section INIT_WF-SECTION file = state0 coeff = 1.0 file = state1 coeff = 1.0 end-init_wf-section end-input
sumspec
OptionsThe spectral component files are assumed to be generated by the autospec program, but sumspec will add the columns 2, 3, and 4 of any sets of files. Hence, one may use sumspec to add flux files. In this case use the option -g 2 to plot the probabilities.
The factors may be negative, and there may be only one input file.
tdpespec
Optionstrafodb
OptionsVarious analyses can be made on the database from a direct dynamics calculation. The program requires an options for which analysis is to be run.
Analysis | Description |
---|---|
adv_error | At each point, the adiabatic energy from the raw data is compared to that obtained from the model. |
twopdens
OptionsThe program computes ρ_{{j,k;j',k'}} = Σ_{J} A*_{{j,k,J}} A_{{j',k',J}}, where J stands for all remaining indices. Of course, j an k do not need to be the first two indices as in this example. The two modes for which ρ is computed are called m1 and m2. ρ is interpreted as a matrix where (j,k) and (j',k') are taken as super-indices. This matrix is then diagonalized and its eigenvalues are printed to stadard output.
twprob
OptionsThis utility calculates state-resolved reaction probabilities according to the formula
from the correlation function c(t)=<φ_{f}|e^{-iĤt}|φ_{i}>=<φ_{f}|ψ(t)>, where φ_{i} denotes the initial state of the propagated wavefunction, and φ_{f} denotes a reference wavefunction. Δ_{i} and Δ_{f} are the energy distributions of these two wavefunctions, respectively.
The reference wavefunction φ_{f} must be a direct product of a (narrow) Gaussian in the translational DOF and an internal state of the products. This internal state is chosen according to the channel you are interested in.
The energy distributions are best obtained from adwkb-files. However, for the propagated wavefunction it is also possible to calculate Δ_{i} from the autocorrelation function (using crosspec).
The usage of twprob is usually as follows:
- Do a normal propagation with QUANTICS. It's advisable to use the option "correction=dia" (INITWF-section) in order to create the adwkb file. The propagation time T must be such that the overlap with the reference WF vanishes for t→T.
- For each channel (i.e. each combination of quantum numbers for
the final state) of interest, do:
- Prepare an input file for a GENINWF run. The generated
wavefunction must be a direct product of
- a Gaussian in the translational DOF. The Gaussian should be very narrow (this will make the energy distribution Δ_{f} broad and also make the correlation function c(t) disappear more quickly), and its center should be outside of the interaction region.
- an internal state of the products that reflects the chosen channel.
- Run QUANTICS with this input file to create the restart file, which will contain the reference wavefunction.
- Compute the correlation function: crosscorr -o crossfile -f /path/to/propagated/wavefunction/psi -r /path/to/reference/wavefunction/restart
- Compute the reaction probability for this channel: twprob -o probfile EMIN EMAX UNIT crossfile /path/to/propagated/wavefunction/adwkb /path/to/reference/wavefunction/adwkb
- Prepare an input file for a GENINWF run. The generated
wavefunction must be a direct product of
In practice, you will probably be interested in a lot of channels (note that with twprob there is no implicit summing like in flux), so you will want to write a script that generates the GENINWF input file, runs quantics, crosscorr and twprob for each channel. It's advisable to make use of the readoper/readdvr options to speed up these calculations (the geninwf part of quantics as well as crosscorr and twprob take virtually no time to complete).
The output file consists of two columns: energy E and probability P(E). E runs between the given EMIN and EMAX. Note that P(E) is set to zero for values of E that lie outside either of the two energy distributions.
Note
The distribution Δ(E) in the above formulas is called |Δ(E)|^{2} in section 8.6.3 of the MCTDH review.
vminmax
OptionsThis program is very useful for checking if the potential of the implemented operator assumes unexpectedly large positive or negative values.
The option -t followed by a filename (trj) allows to run over a subset of primitive grid points. The file contains the indices of the grid points of interest as bank separated integers in ASCII format.
In addition, the option -c allows comparison of the oper-file to the exact potential stored in a surface file (srf).
These two features are used to test an implemented cluster-expansion against the exact potential within the chkpes Python script. Here the indices represent the trajectory of a random walker and the surface file contains the exact potential energies at those points.
wfproj
OptionsThis program uses the same projectors as flux. See the documentation of flux to learn more about the projectors implemented. The most useful projector is possibly the read projector. Here the projector is build from an SPF which is read form a foreign restart file. Note that there may be more than one projector. If the MCTDH wavefunction is expanded in p modes (particles) then there may be at most p-1 projectors.
xfrog
Not Availableprobrw
Purpose : Computation of the reaction probability when using real wavepackete propagation. Usage : probrw [-w -d -ver -h -?] Options : -w : The (un)prob_{dof} file may be overwritten. -d dof : Probability along the dof. -ver : Version information about the program -h : Print this help text. -? : Print this help text. Example: probrw100 -d rd ------------------------------------------------------------------------------
Interactive Plotting
Many of the analysis programs include menu-driven interactive plotting using an interface to gnuplot. In some programs, such as showsys the menu is started automatically, in many the -inter option must be given. Use -h to see if this option is available.
The options allow manipulation of the data and the creation of gnuplot script files which can be further edited, as well as direct conversion to a postscript file for printing (there is a print option but that uses the lpr command which rarely works). Most of the menu commands are self explanatory, and different programs have options so it is impossible to describe them all. Help on som options which may be less intuitive is given here.
Option 20: Change coordinate section This option allows you to select a cut when potting multi-dimensional data, e.g. a potential surface in showsys. The present cut is shown in brackets on the menu option line - the modes designated to be plotted along the x and y axes are shown, along with the values selected for other modes. These can be changed using this option. For example if you have a system with 3 modes labelled v1, v2, v3, then if you want to plot a cut with v1 on the x-axis, v2 on the y-axis and v3 a value of 2.0, then after typing 20 you input on separate lines
v1 x v2 y v3 2.0 0If you then want to plot v1 as a 1D plot with v2=0.0, you just need to type 20 again then
v2 0.0 0etc.
Gnuplot scripts (pl-scripts)
There are a number of shell scripts located on $QUANTICS_DIR/bin, which enable a convenient plotting of some results of an QUANTICS calculation. In general, these scripts call one of the above analyse routines, write the output to a temporary file and plot it using GNUPLOT. (A GNUPLOT of version 3.7 or higher should be used). The default version of the analyse routines is called. This may be changed by setting the environment variable $QUANTICS_VERSION or by using the option -v. The name directory mustbe the current directory when executing the pl-scripts. The pl-scripts allow for options and some scripts need arguments. A help text is always generated by executing plxxx -h .
The different scripts support different options. If appropriate, however, the scripts commonly support the following options:
-h : print a help text. -a val : set lower range of x to val. -x val : set upper range of x to val. -y val : set upper range of y to val. -z val : set lower range of y to val. -G : draw grid lines. -l : use logarithmic scale for y. -s : suppress messages of the called analyse program. -v val : set the version number of the analyse program to be called to val. -p : prompt for printing the plot at default printer lpr. -P printer : specify alternative printer (e.g. -P "| lpr -Pps2"), or print to a file (e.g. -P plot.ps).
- plall
- Prints an overview of all pl-scripts. This is the only pl-script that does not produce a plot. No arguments are required.
- pladpop
- Reads the adpop density files and plots the one or two dimensional densities of the choosen electronic states.
- pladwkb
- Reads the adwkb file and plots the energy distribution DELTA(E) or the translational mean field. No call to any analyse routines. No arguments are required.
- plenerd
- Reads the enerd file and plots the energy distribution DELTA(E) or the translational mean field. No call to any analyse routines. No arguments are required.
- plauto
- Plots the autocorrelation function. It reads the auto file and does not call any analyse routines. No arguments are required.
- plcap
- Plots the reflection and transmission probabilites of a CAP. No output file of other programs needed.
- pledstr
- Plot of the (free) energy distribution of a gaussian WP. No output file of other programs needed.
- pleigval
- Plot of the energies computed in a diagonalisation run. It reads the ./eigval file generated by a mctdh-diagonalisation run. No arguments are required.
- plfdfour
- Plots Fourier file created by the filter-diagonalisation program. Requires as argument the name of the file containing the Fourier spectrum generated by the filter program. No analyse routines are called.
- plfdspec
- Plots line spectra created by the filter-diagonalisation program. Requires as argument the name of the file containing the eigen values. If no file name is given, the default filter.eig is taken. No analyse routines are called.
- plflux
- Plots the quantum flux, the energy distribution of the initial wave packet and the reaction- (or scattering-) probability. It reads the flux file and does not call any analyse routines. However, to create the flux file, flux (see above) must have been run before excecuting plflux. No arguments are required.
- plgen
- General GNUPLOT wrapper. Plots the data of ASCII file(s). plgen requires as arguments a file name and the argument of the GNUPLOT using statement.
- plgpop
- Plots the sum of the grid population of the first and last nz grid points. The occupation of the highest nz FBR basis functions is also shown. plgpop calls rdgpop (see above) to read the gridpop file. It requires the arguments nz and dof, where dof denotes the degree of freedom of which the grid populations are checked.
- plnat
- Plots the natural weights. It calls rdcheck (see above) to read the check file. It requires the arguments state and mode, where state denotes the electronic state and mode the (combined or uncombined) mode for which the natural occupations are shown.
- plpit
- Reads the file iteration from the potfit name directory and plots the potfit error measures. It requires the argument(s) task which can take the values: wr (wighted relevant), ur (unwighted relevant), ua (unweighted all), mr (maximum relevant), ma (maximum all), f1 (error measure for the first dof, see eq.(118) of the review), f2 (as before for the second dof),...
- plpweight
- Reads the file prodwei from the potfit name directory and plots the separable weights. It requires as argument the number of the degree of freedom for which the weight is depicted.
- plqdq
- Plots the expectation values <q> and <dq>. It calls rdcheck (see above) to read the check file. It requires the arguments state and dof, where state denotes the number of the electronic state and dof denotes the degree of freedom of which the expectation values are shown. Note: plqdq requires a check file which is generated by mctdh of version is 8.2.2 or higher.
- plrlx
- Plots the energy vs time of an "improved relaxation" run. It reads the rlx_info file and calls plgen. The options passed to plgen must be quoted.
- plspec
- Plots the (absorption) spectrum. It calls autospec (see above) to read the auto file and to compute the spectrum by fourier transform of the autocorrelation function. It requires as arguments the arguments of autospec.
- plspeed
- Plots the CPU time used between two outputs. It reads the speed file and does not call any analyse routines. No arguments are required.
- plstate
- Plots the electronic state populations. (If there is only one state, this is equivalent to the square of the norm). It calls rdcheck (see above) to read the check file. No arguments are required.
- plupdate
- Plots the CMF update times or the CMF A and Phi errors. It reads the update file and does not call any analyse routines. No arguments are required.
- plwtt
- Plots the CAP expectation values Wtt. It reads the wtt file and does not call any analyse routines. However, to create the wtt file, flux (see above) must have been run before executing plwtt. No arguments are required.
Utility scripts
- compile
- See Installation and Compilation
- cdm
- A very convenient cd for the QUANTICS directory. E.g cdm linear will cd to $QUANTICS_DIR/source/lib/linear. The destination directory may be abbreviated, as long as the abbreviation is unique. I.e. cdm lin is sufficient. The source dirs come before all others. I.e. cdm m cd-es to source/mctdh. To cd to doc/quantics one types cdm doc/m. The cdm script is part of .quanticsrc and is available only, when working under bash.
- elk_test
- See Automatic Program Test
- elk_test_gen
- See Automatic Program Test
- ddiff
- compares files of current directory with those of another directory. (not recursive).
- find235.py
- finds integer numbers of the form 2^{x}3^{y}5^{z} close to a given number -- these are valid grid sizes for the FFT in QUANTICS.
- mkGpatch
- makes a GNU-patch. See Applying Patches
- mkMpatch
- makes a M-patch. See Applying Patches
- mdistribute
- Copies the files collected by mkMpatch or mfind to the QUANTICS directory.
- mdircp
- Copies a QUANTICS directory to a new location, excluding all those files which are not on the original package before installation (e.g. object, binary, *~, and *.dvi files). mdircp can also create tar files and may send them to a remote host.
- mfind
- Finds all files of the QUANTICS directory that are newer than a specified date (default 1 day).
- mcb
- QUANTICS Code Browser
- mcg
- QUANTICS Code Grep
- mcl
- QUANTICS Code List
- menv
- QUANTICS Environment
- mhelp
- QUANTICS short help for input
- minstall
- Sets environment variables and makes another QUANTICS directory active. This script is part of .quanticsrc and is available only, when working under bash. Typing " minstall path-of-second-QUANTICS-directory " makes the second-QUANTICS-directory active.
- mdiff
- Compares two QUANTICS directories and lists files which differ. It can show the differences using diff or mgdiff.
- mreport
- Copies important ASCII files of a name-directory and tar then to a .tgz file. Please add this mreport_<some name>.tgz to your e-mail, if you file a bug report or ask for assistance.
- phelp
- Programmers help. Gives a description of QUANTICS variables.
- vddiff
- Version doc diff. Compares the documentation of two QUANTICS directories.
- vrdiff
- Version rest diff. Compares the 'rest' of two QUANTICS directories.
- vsdiff
- Version source diff. Compares the source of two QUANTICS directories.
Try program -h to obtain more information (-h option is not available for cdm). A Quantics user should be familiar with compile, cdm, menv, minstall, mhelp, mkGpatch, and mkMpatch. The other scripts are primarily for QUANTICS developers. Of particular importance for developers are the scripts elk_test and elk_test_gen, phelp.
Compiling the Programs
The programs should all be compiled during the installation of the package. If thsi is not the case, or a code needs re-compiling after making changes, they can be compiled using the shell script $QUANTICS_DIR/bin/compile. Type:
compile prognameto produce the executable $QUANTICS_DIR/bin/$QUANTICS_PLATFORM/progname, where progname is the name of one of the analysis programs (e.g. overlap or autospec). Typing
compile analysewill compile all the analysis programs.
The compile script has various options (type compile -h for a list). For example, to produce the executable $QUANTICS_DIR/bin/$QUANTICS_PLATFORM/overlapd with debug information, type
compile -d overlapFor more information on the compile script, see Compiling the programs.