The fitting of the parameters is done using the VCHFIT program. This reads an input file, specified as the first argument
vchfitXX input
or
vchfitXX name.inp
where XX is the version number, e.g. vchfit83 for package version 8.3, and where name (or name.inp) denotes the input file. The input format uses, like all the MCTDH package input files, keywords that are for the most part free format and case insensitive. See MCTDH input file structure

for further information on the general use of keywords, noting that there are no sections in the VCHAM input files. The input file ends with the keyword end-input

Various output files are produced. These include

Output files
file name Description
name.vcham contains the data from the fit
name.log the log file
name.par the parameters in an MCTDH .par file format. To write this file the keyword mctdh_par must be set
name.op the operator and parameters in a MCTDH .op file format. to write this file the keyord mctdh_op must be set

Input file (*.inp)

The input file contains a set of keywords to control exactly how the fit is made. The following list is of the groups of keywords that are used

Defining the Data Set

The basic ingredient for a fit is a set of data - energies and derivatives at various points. These are contained in a *.info file set up previously (see setting up a database )

Defining the Data set
Keyword Argument Description
infofile S S is the name of the .info file

Defining the Model

The vibronic coupling model Hamiltonian contains sets of parameters which can be defined as on-diagonal and off-diagonal. These sets can be further divided according to the power of the coordinate: linear, second-order, etc. In the following documentation the sets of parameters are described using the nomenclature in the following table:
Sets of Parameters
Name Description
E (s,s1) Constant for states s,s1
kappa (m,s) On-diagonal linear parameters for mode m state s
lambda (m,s,s1) Off-diagonal linear parameters for mode m connecting states s and s1
gamma (m,m1,s) On-diagonal second-order parameters for modes m,m1 and state s
mu (m,m1,s,s1) Off-diagonal second-order parameters for modes m,m1 connecting states s and s1
general (k,m,s) The expansion coefficient k for a general potential for mode m and state s

Which sets of parameters are included in the fit can be controlled by the following keywords:

Defining the Model
Keyword Description
linear_mod linear model - Constants + kappa + lambda
adiab2_mod Adiabatic 2nd order model - Constants + kappa + lambda + gamma
diab2_mod Diabatic 2nd order model - Constants + kappa + lambda + gamma + mu

Further control is possible by selecting only a set of the parameters for fitting:
Choosing the parameters to fit
Keyword Description
fullfit All parameters are included
linfit All constants and linear terms included
constfit Only constants included
kappafit Only on-diagonal linear terms
lambdafit Only off-diagonal linear terms
gammafit Only on-digonal second-order terms (quadratic and bi-linear)
gammafit_diag Only on-diagonal quadratic terms
mufit Only off-diagonal second-order terms
read_mask The symmetry "mask" defining which parameters are to be optimised will be read from a .vcham file specified by the guess = S keyword
Thus if one chooses diab2_mod linfit all parameters up to second-order both on- and off-diagonal are included in the Hamiltonian, but only parameters up to linear will be optimised. In this way all parameters are written to the output files and can be used in later stages.

More detailed control is possible using keywords described below, or by editing and using a .vcham file to set up the initial guess.

It is also possible to fit only a set of modes.

Selecting Modes
Keyword Description
fit_all Fit all modes (default)
fit_select = m [,m1 [, m2 ....]] Fit only parameters for modes m [and m1 etc.]

Defining the Non-zero Parameters

If a system has symmetry, many parameters in the model Hamiltonian are zero from group theory arguments. The program reads information defining the system from the *.info file, e.g. the number of electronic states and vibrational modes in the system. It also reads the symmetry labels for the modes. The following keywords use the symmetry labels to define which parameters are non-zero by symmetry. In each case label is the symmetry label as written in the *.info file.
Defining the Non-zero Parameters
Keyword Description
symmode = label "label" is the symmetry label for the totally symmetric modes
cpmode = s s1 label "label" is the symmetry label for the modes coupling states s and s1
jtmode = s label "label" is the symmetry label for any Jahn-Teller active modes for state s
jtstates = s, s1 [,s2, ...] States s and s1 are a degenerate pair with Jahn-Teller active modes defined
using jtmode and coupled by the mode defined by cpmode(s,s1). Higher
order JT than double degenrate is possible if s2 etc. defined.

The symmode label defines the modes that have non-zero on-diagonal linear parameters (all modes have non-zero on-diagonal second-order parameters). The cpmode(s,s1) label is the product of the symmetries of states s and s1. Modes with this symmetry have non-zero linear off-diagonal (coupling) parameters. Two modes whose product has this symmetry will have non-zero second-order off-diagonal terms (not implemented fully). If the system has a Jahn-Teller intersection, then in addition to the totally symmetric modes, modes with symmetry label jtmode(s) can appear as linear parameters on the diagonal of state s.

If any other parameters need to be added to the calculation they are set in a list between the lines
addpar-section
and
end-addpar-section
This can be used, e.g. to add a mu parameter in a system for which the bilinear symmetry rules are not known (in this case diab_mod2 must be selected).

The parameters are added using the following syntax:

Explicitely adding parameters
Keyword Description
E s s1 = S add a constant
kappa m s = S add an on-diagonal linear parameter
lambda m s s1 = S add an off-diagonal linear parameter
gamma m m1 s = S add an on-diagonal second-order parameter
mu m m1 s s1 = S add an off-diagonal second-order parameter
S = optimize Added parameter will be optimised
S = freeze Added parameter will be added but kept frozen

Defining the Zero-Order Diabatic Potential

By default, the zero-order diabatic potential is a harmonic oscillator function for each mode with the frequency taken from the .info file. A different function can be selected from the following table and written between the keywords diabatic_function
and
end-define
Zero-order Diabatic Potentials
Keyword Description
m s quartic Quartic potential
m s morse Morse oscillator

The definitions of the potential functions are here .

Setting Initial Values for the Parameters

The initial values of parameters can be set by reading in the results of a previous fit. They may be also be selectively set to zero.
Setting Initial values for Parameters
Keyword Description
guess = S The initial values are read from the .vcham file S
nonopt_zero All parameters that are not to be optimised are set to zero, irrespective of whether they are zero by symmetry or not.
nozero_zero By default, all parameters zero by symmetry are set to zero before the optimisation is done. This keyword turns off the initial zeroing so that if a value has been read in for one of these parameters it is kept at that value.

The initial value for a parameter may be defined by listing the desired values between the strings

set_parameters-section
and
end-set_parameters-section

VALUE in the following table can be any number and energy units may be used as usual. The description uses the parameter nomenclature from above.

Setting the initial value for a parameter
Keyword Description
E s s1 = VALUE set E(s,s1) to VALUE
kappa m s = VALUE set kappa(m,s) to VALUE
lambda m s s1 = VALUE set lambda(m,s,s1) to VALUE
gamma m m1 s = VALUE set gamma(m,m1,s) to VALUE
mu m m1 s s1 = VALUE set mu(m,m1,s,s1) to VALUE
general k m s = VALUE set general(k,m,s) to VALUE

Constraining the Parameters

Constraints can be set to keep relationships between parameters during the optimisation. To use constraints, the following keyword must be used:
Constraining the parameters
Keyword Description
use_cons use the constraints defined either in input file or vchfit file from which symmetry mask is read

If Jahn-Teller modes have been defined the program automatically tries to set up the appropriate contraints. Other constraints are set in a list between the lines
constraints-section
and
end-constraints-section

The constraints are set using the following syntax:

Constraining the parameters
Keyword Description
E s s1 = CONSTRAINT constrain a constant
kappa m s = CONSTRAINT constrain an on-diagonal linear parameter
lambda m s s1 = CONSTRAINT constrain an off-diagonal linear parameter
gamma m m1 s = CONSTRAINT constrain an on-diagonal second-order parameter
mu m m1 s s1 = CONSTRAINT constrain an off-diagonal second-order parameter
general k m s = CONSTRAINT constrain an expansion coefficient of a general potential

where using the parameter nomenclature above CONSTRAINT can be one of the following:

Possible Constraints
CONSTRAINT Description
freeze keep the parameter fixed
unfreeze allow a previously fixed parameter to be optimised
E s s1 factor constrain to the factor*constant E(s,s1)
kappa m s factor constrain to factor*kappa(m,s)
lambda m s s1 factor constrain to factor*lambda(m,s,s1)
gamma m m1 s factor constrain to factor*gamma(m,m1,s)
mu m m1 s s1 factor constrain to factor*mu(m,m1,s,s1)
general k m s factor constrain to factor*general(k,m,s)
For example to set the on-diagonal linear parameters of mode 1 equal and opposite in two states and equal to the linear off-diagonal parameter of mode 2
Constraints-section
kappa 1 2 = kappa 1 1 -1.0
kappa 1 2 = lambda 2 1 2 1.0
End-Constraints-section

Controlling the Optimisation

Various features of the optimisation can be controlled. In particular, factors can be chosen to weight the points in the database, e.g. by energy (lower energy more important)
Weighting the Points
Keyword Description
equalweight The points are equally weighted (default)
energyweight [ = R ] The points are exponentially weighted according to their energy
wi = exp -R(Ei - E0). If the argument R is not input, R=1.0

The optimisation algorithm may be selected

Controlling the Optimisation
Keyword Description
iter = I I iterations will be made
tol = R The convergence tolerance is set to R
optimiser = S The optimser used will be S where
Keyword Description
conj_grad Conjugate Gradient (default). A simple routine using derivatives.
powell Powell. This uses second derivatives.
simplex Simplex. Requires no derivatives.
no-ortho The normal mode vectors are not initially orthonormalised but used as read in.
nofit Do not make the fit - only a guess is set up. This differs in effect from setting iter=0 as any constraints set up or modes selected will be ignored.

*.vchfit file structure

In this file all parameters for the vibronic-coupling Hamiltonian are written down. All this parameters are necassary to describe the potential energy surfaces. The unit is eV.
The file is structurated into different parts. On the beginning all parameters are list: frequencies, equilibrium point energies at Q0, linear on- and off-diagonal constants, bilinear on- and off-diagonal constants.
Then follows a section where the energyminimas are listed.
At the end you can get the information which parameters were calculated. 0 means not and 1 means yes.

*.par file structure

This file includes the same parameters as in the *.vcham file. But this file is in a format, that can be used as MCTDH input.

*.op file structure

This file includes the same parameters as in the *.par file. This file aslo includes the hamiltonian section, in a format that can be used as MCTDH input.

*.log file structure

Some useful information are given in the *.log file.

Example: Cr(CO)5
As an example, crco5_vchfit0.inp uses the information in the crco5_trans0.info database (see VCTRANS documentation) to get the paameters. No fit is made, but the derivative coupling and gradient difference information from CASSCF calculations are used to obtain the parameters. The results are in the file crco5_vchfit0.vcham and crco5_vchfit0.log

This calculation is then used as the initial guess in crco5_vchfit1.inp a fit of the model to the data in the full database crco5_trans1.info. The results are written to the files crco5_vchfit1.vcham and crco5_vchfit1.log and crco5_vchfit1.par