Input Structure

The input file consists of a list of entries, where an entry is an expression of the form  keyword = parameter.  Entries can be separated by commas and/or newlines. Blanks and empty lines are ignored. The input is not case-sensitive. For instance,

key1 = par1, key2=par2
and
KEY1=par1,
keY2=par2
and
key1 = par1

key2 = par2
all are equivalent. The input entries may appear in arbitrary order. An entry that starts with an exclamation mark "!" is ignored. This allows one to disable single entries. A "#" defines the beginning of a comment, i.e. everything between "#" and the end of the line is ignored. For example, if an input file reads
# This is a comment.
key1=par1, ! key2=par2, key3=par3
 !key4=par4, # key5=par5, key6=par6
only the entries one and three will be considered. A few entries are compulsory, but most are optional. If an optional entry is not given in the input file, a default parameter is used. All entries are listed below. For more information on the input syntax see Example Input Files.

It is also possible to pass arguments to the program via the command line. This is done by specifying a string which contains the desired input entries. The syntax is the same as for the input file. Any parameter given in the command line overrides the corresponding entry in the input file (if present). For example, one may start the program by typing

filter "prop_usepackets = 4" input
or
fdc "prop_usepackets = 4" input
where input denotes the input file. (The keyword prop_usepackets is defined below.) Command line arguments are particularly useful for performing a series of calculations which differ by a few parameters only. For instance, the shell script 
for t in 100 200 400; do
  filter "filter_timeinterval=${t}.0d0, file_outputname=out_t$t" input
done
starts three runs using a time interval of 100.0d0, 200.0d0, and 400.0d0 and writes the results to the output files out_t100.*, out_t200.*, and out_t400.*, respectively. All other parameters are taken from the file input.

Compulsory Input Entries

The following input entries are compulsory. A missing compulsory entry raises an error message.

Keyword Description
prop_outputinterval The period with which the autocorrelation function has been computed, i.e. the autocorrelation function is known at t = i*prop_outputinterval,   i = 0,1,2,...
Note that this entry is optional for   file_autoformat = mctdh  or for   prop_sodintegrator = yes.  (In fact, this entry is ignored in these cases.)
window_minimumenergy The minimum or left boundary of the energy window to be "filtered".
window_energywidth The width of the energy window to be "filtered".
window_energypoints The size of the FD-Hamiltonian. If only a single packet is used, this is also the number of (equidistant) energy points in the window. If a cross-correlation function with P packets is employed, the number of energy points is given by window_energypoints / P.

The unit system being used depends on the settings in the input file (see below).

Optional Input Entries

A variety of optional entries may be given in the input file. The table below shows all keywords, together with the corresponding default. Note that some input entries are only relevant in conjunction with certain other parameters.

Keyword Default Description
prop_timeconversion 41.3414 Conversion factor from the desired time unit to atomic units, i.e. all times in the input file are multiplied with that number. The default is the conversion factor from  fs  to  au.
prop_energyshift 0.0 The energy  S  by which the Hamiltonian has been shifted during the propagation, i.e. the autocorrelation functions have been evolved using  H-S  rather than   H.
prop_sodintegrator no Specifies the type of propagation.
yes:
a second-order differencing (SOD) integrator has been used for the propagation
no:
a different integrator has been used for the propagation
prop_skipauto 1 Only every prop_skipautoth value of the auto- or cross-correlation files is employed. The default of 1 hence means that all values are used.
prop_wavepackets 1 The number of wavepackets that have been used in the computation of the cross-correlation functions. This entry is ignored if  file_autoformat = mctdh.
prop_usepackets 0 = all Specifies the number of packets to be used from the cross-correlation function. A value of zero (the default) means that all packets will be employed.
prop_initialtime
(fdc only)		 0.0 Specifies the initial time of the autocorrelation functions, i.e. the first part of the autocorrelation files up to time = prop_initialtime is ignored.
file_autopath  .  (current) Denotes the directory containing all input and output files.
file_autoformat mctdh Specifies the format of the autocorrelation files. See also Autocorrelation and Wave Functions.
ascii:
the autocorrelation files are in ASCII format
binary:
the autocorrelation files are in binary format
mctdh:
the autocorrelation files are in MCTDH format
file_exactname       (blank) Path and name of the file containing comparison (e.g. exact or experimental) results. A blank means none. See also The Comparison File.
file_outputname filter Stem of the file names the results are written to.
file_fourier no Defines whether the Fourier transform of the autocorrelation function is written to file. See also The Fourier File.
yes:
the Fourier transform is output
no:
the Fourier transform is not output
file_fourierresolution 512 The number of energy points used for computing the Fourier transform of the autocorrelation function. This entry is not considered unless  file_fourier = yes.
window_energyconversion 0.0367493 Conversion factor from the desired energy unit to atomic units, i.e. all energies in the input file are multiplied with that number. The default is the conversion factor from  eV  to  au.
window_imaginaryshift
(fdc only)		 0.0 Shift  s  for the imaginary part of the Hamiltonian, i.e. H is replaced by H + i s/2. This is done by correspondingly transforming the autocorrelation functions. The shift is subtracted from the widths before the results are output.
window_intensitypacket 1 The number of the wavepacket for which the intensity will be computed.
window_referenceenergy 0.0 Energy the energy parameters are refered to, i.e. this energy is added on input to the parameters window_minimumenergy, vp_energyshift, and error_energyshift and subtracted on output from the computed energies. Serves, for instance, to specify and output energies with respect to the vibrational ground state.
filter_timeinterval (maximum) Specifies the length in time to be used of the autocorrelation functions. The default is to use the full available autocorrelation functions.
filter_function cos Selects the damping function the autocorrelation functions are convoluted with.
gauss:
a Gaussian filter is employed (not allowed for fdc)
cos:
a cosine filter is employed
cos^2:
a squared cosine filter is employed
box:
a box-like or rectangular filter is employed
sin:
a sine filter is employed (only allowed for fdc)
sin^2:
a squared sine filter is employed (only allowed for fdc)
filter_gausswidth 0.3 The width of the Gaussian filter function  g,  defined such that  g(t) = e-2  for  t = 1/2 filter_gausswidth*filter_timeinterval. This entry is ignored unless  filter_function = gauss.
filter_autoorder two Defines which autocorrelation functions to be used.
zero:
only the zero-order autocorrelation function is used (not implemented in fdc)
two:
also the first and second order autocorrelation functions are used
filter_cutoff 10-10 Relative cut-off for the eigenvalues of the overlap matrix, i.e. all eigenvalues smaller than filter-cutoff  times the largest eigenvalue are ignored in the computation of the truncated matrices.
vp_principle 1/H Specifies the variational principle to be employed.
H:
the Rayleigh quotient <psi | H | psi> /  <psi | psi>  is employed
H^2:
the variational principle <psi | (H-s)2 | psi> /  <psi | psi>  is employed
1/H:
the variational principle <psi | (H-s) | psi> /  <psi | (H-s)2 | psi>  is employed
vp_energyshift (middle) The energy shift  s  used in the variational principles   vp_principle = H^2  and  vp_principle = 1/H.  Default is the middle of the energy window. This entry is ignored if  vp_principle = H.
error_estimate variation Defines how the error is estimated.
stddeviation:
the standard deviation sqrt(<psi | (H-E)2  |  psi>)  is taken as error estimate
variation:
the error is estimated by comparing the results of two different variational principles
error_spurious 0.1 A relative criterion for identifying spurious eigenenergies, i.e. all energies with an error greater than  error_spurious  times the middle of the energy window are ignored. Used only if  error_estimate = stddeviation.
error_principle H or  1/H Specifies the variational principle to be employed for estimating the error.
H:
the Rayleigh quotient <psi | H | psi>  /  <psi | psi>  is employed
H^2:
the variational principle <psi | (H-s)2  |  psi> / <psi | psi>  is employed
1/H:
the variational principle <psi | (H-s) | psi >  / <psi | (H-s)2 | psi >  is employed
This entry is only considered if  error_estimate = variation.
error_energyshift (middle) The energy shift  s  for the variational principles   error_principle = H^2  and  error_principle = 1/H  used to estimate the error. Default is the middle of the energy window. This entry is ignored if  error_principle = H.

Note that the default for  error_principle  depends on the choice for  vp_principle:  if  vp_principle = 1/H,  then  error_principle = H   is the default, otherwise it is  error_principle = 1/H.

The older keywords file_psilength, vp_accuracy, vp_iterative, and error_iterative are now obsolete and will be ignored on input. They should not be used anymore as they might not be supported in future versions.

Example Input Files

A few example input files can be found here:

Example 1:
Displays a complete list of input entries.
Example 2:
Shows the shortest possible input file, i.e. only compulsory entries are included.
Example 3:
Gives a badly arranged but syntactically allowed example for an input file.

The Data File

If an SOD integrator has been employed in the propagation of the wave packet (i.e. for  prop_sodintegrator = yes), the parameters for  prop_outputinterval  and  prop_energyshift  are read from the  data  file instead of the input file. This ASCII file consists of three lines, each containing one real number, for example

0.103405000000000E+006
0.484139803825175E+001
0.652324924114329E-001
The first number defines the time interval for which the autocorrelation functions are known. The second and third number is the value for  prop_outputinterval  and  prop_energyshift,  respectively. All parameters must be given in atomic units. The values in the  data  file override the corresponding entries in the input file.

Autocorrelation and Wave Functions

The auto- or cross- correlation functions of order zero, one and two are assumed to be stored in the files  auto,  auto1,  and  auto2,  respectively, in the directory specified by  file_autopath.  Depending on the input flag  file_autoformat,  these files can be given in ASCII, binary, or MCTDH format. If  file_autoformat = binary , then real and imaginary part (reauto  and  imauto) are read separately from each file (The index  i  runs over the time-dependent values of the autocorrelation functions.):

read(1) reauto(i)
read(1) imauto(i)
From ASCII files the autocorrelation functions are read by 
read(1,*) reauto(i),imauto(i)
Finally, from MCTDH files the autocorrelation functions are read by 
read(1,*) time(i),reauto(i),imauto(i),absauto(i)
Note that the absolute value absauto(i) of the autocorrelation function is not used in the filter program. A line that starts with "#" is ignored if file_autoformat = mctdh.

A cross-correlation matrix cab(n)(t) = <psia(0)|Hn|psib(t)>, where a and b enumerate the wavepackets, is assumed to be stored columnwise in the corresponding files, e.g. c11, c21, c12, c22 if there are two packets, with one matrix element per line.

The Comparison File

It is possible to specify a file containing a spectrum the computed results are compared with, by setting the  file_exactname   parameter appropriately. This comparison data can for example be an exact or experimental spectrum. By using the eigenenergy file it is also possible to compare with the results of a different filter calculation. The file must have ASCII format and consist of a series of lines, one for each state, containing the corresponding energy and intensity, for instance:

-6.5925694172562   0.0103374736668
-6.5619225175745   0.0124474270552
-6.5344266837777   0.0146345138770
-6.5100539138258   0.0172692110073
-6.4991166546213   0.0002512088973
-6.4888302869456   0.0203425006274
-6.4707960225204   0.0219697860398
-6.4689083682758   0.0002263517929
-6.4547552415270   0.0168010368034
-6.4422828378994   0.0003465083987

When the complex symmetric program version, fdc, is employed, the comparison file must also contain the widths as second argument, e.g.

-6.5925694172562   0.0884319056222   0.0103374736668
-6.5619225175745   0.0973643982186   0.0124474270552
-6.5344266837777   0.0349695940229   0.0146345138770
-6.5100539138258   0.0509832159486   0.0172692110073
-6.4991166546213   0.0254670742054   0.0002512088973
-6.4888302869456   0.0643632404813   0.0203425006274
-6.4707960225204   0.0664963330887   0.0219697860398
-6.4689083682758   0.0044885778973   0.0002263517929
-6.4547552415270   0.0935165419140   0.0168010368034
-6.4422828378994   0.0701926188810   0.0003465083987

The energies and widths must have the same unit as the energies in the input file (which can be defined with the aid of the keyword  window_energyconversion). The energies must be given in ascending order.