README file for the Vibron triatomic program (vibr3at).

* Reference:	Comp. Phys. Comm. 74, 164 (1993).
		J. Mol. Spectrosc. 142, 85 (1990); ibid. 146, 56 (1991).
 

* List of files in the package:
(NB! these files are all contained in the self-extracting compressed
uuencoded archive package.uu : if you use an unix system, you can download
only package.uu , make it executable [chmod +x package.uu] and execute it
[package.uu] to get automatically all the files listed below in a
subdirectory ./vibr3at/)


README			this file
vibr3at.f		the main fortran code: all the algebraic stuff + fit
racah.f			a tested routine computing Wigner 6-j coefficients
     http://www.kfa-juelich.de/zam/CompServ/software/mathe/mathsrc/cpc/abzu.cpc

vibr3atns.dat		data file: operator names for symmetrical case
vibr3atnn.dat		data file: operator names for non-symmetrical case
tinp.dat		input file (example for bent symmetrical molecule: H2O)

touth2o.dat		example of output file corresponding to tinp.dat
				(for bent symmetrical molecule - H2O)
[the following 6 example files regard the linear non-symmetrical molecule HCN:]
tinphcn1.dat		example of startup input file
touthcn1.dat		the corresponding output file
tinphcn2.dat		example of intermediate input file
touthcn2.dat		the corresponding output file
tinphcn3.dat		example of final input file
touthcn3.dat		the corresponding output file
 

* Compilation:

To run the spectrum-fitting program one must first compile the fortran
code. This code does not follow strictly the f77 standard in many ways,
such as:
- the use of end-of-line commenting (!)
- the enddo structure for loop closing, which is clearer
- a few names exceed the 6-character limit
- lowcase characters.
However, we are confident that your compiler is able to deal with such
pretty common extensions. If not... you've better ask your system manager
for a less ancient compiler.
We have commented out a non-standard extension, the "Variable Format
Expression" (i. e. the structure <integer> in the format instructions) used
twice in the code.  If you have suppoert for that you get better output
appearance.

The racah.f is pretty standard, and should give no problem. The function
racah at the end is not really needed by the program, and can be safely
removed. The only problem that may arise from these routines is the
dimensioning (here 9000) of an array containing log(n!). It limits the
allowed values of N1 and N2 in the following way: N1+N2<9000. If it is not
enough you can always change this constant (in 3 places).

The linking of the objects must be done with some library containing
standard linear-algebra routines. In particular, the code should link "as
is" with the publicly available LAPACK libraries
(http://www.netlib.org/lapack/). Also the IMSL and NAG calls are included A
few easy commenting/uncommenting allow to switch from one library to
another.

NB! The program assumes that the eigenvalues generated by the
diagonalization routine are sorted in ASCENDING order (for imsl2.0 we
provide an explicit re-sorting piece of code), but not that the
eigenvectors are normalized.

A typical compilation command line on many unix systems would look like:
f77 -o vibr3at vibr3at.f racah.f -L<dir with library files> -llapack -lblas


* Runtime:

To work properly, the program requires on the default directory the two
auxiliary files (vibr3atnn/s.dat) containing a ordered list of names of
algebraic operators at disposal. Please, type them to see which operators
you can include in the Hamiltonian as a linear combination. It is very
recommendable not to change these lists.

By default the program vibr3at reads input from the file tinp.dat. If you
find it more convenient that it reads standard-input instead, you may just
remove or comment the following instructions:
	open(unit=5,file='tinp.dat',status='old')
	close(5)

The program writes on standard-output informations mainly about the fit and
its convergence. All the relevant info, however, is written in the output
file, whose default name is tout.dat. We did not introduce a variable file
name, for compatibility with the previous version of the program. Please,
pay attention not to waste precious data by overwriting them!

A second output file is called parguess.dat. It contains the final
parameters in the form ready for being put in a new input file.


* Input format

The format of the input and output files are almost self-explanatory. The
only not obvious symbols in the input file are the following:

A- the "convergence parameter" : it's the convergence threashold of the
iterative fitting loop: the smaller it is, the longer the program goes on
iterating the fit, and the most accurate the final result should be;

B- the format of each parameter-operator line: it is organized this way:
 
parameter initial guess  <space>  1/0 = yes/no fit this parameter  <space>
  'name of the diagonal operator'  <space>  'name of the non diagonal operator'
 
The two names mean that, in general, the algebraic operator will be a
product of a diagonal chain invariant multiplied by a non diagonal
(Majorana) operator: if we want to limit ourselves only to diagonal or not
diagonal operators, it' s sufficient to replace the Majorana operator with
a ' ', i.e. a space character.  The same possibility is open for a "pure"
not diagonal operator, leaving ' ' in the diagonal place.
 
Now we need to clarify the notation used here for these operators, so that
you can be able to confront it with the notation you find in both papers in
J. Mol. Spectrosc. The operator names collected in the vibr3atnn/s.dat
files (for the symmetrical and non symmetrical case) are based on the
following conventions:

Cn      principal Casimir invariant of the n-th O(4) algebra (n= 1, 2, 12 )

CP12    non-analytical Casimir invariant of the 12 coupled O(4) algebra)
        This operator in the J.M.S. papers is characterized by a upper bar

M12     non-diagonal Majorana operator (invariant of U(4)12 algebra)
        This operator provides the coupling of local modes

+       sum operation

*       product operation

^x      x-th power of


The C12 operator in fact is not the "original" invariant operator Co12 of
O(4)12 algebra as in the referred articles, but the special "reduced"
combination:

        C12 := Co12 - (N1+N2+1)/(N1+1) C1 - (N1+N2+1)/(N2+1) C2

which is able to regulate the spectrum of the bending mode without heavily
affecting the stretch modes.


C- The special combination:
 
99  99  'end'  ' '
 
is recognized by the program as the end of the list of operators to be
included into the fit. After reading it, the program starts inputting the
listed experimental levels.

D- Notice the differences of the input format of data between the linear
(HCN) and non linear (H2O) case.

E- The gate for printing the wave-functions is a threshold used for
printing only the "significant" components of the linear combination of
local states by which an energy eigenstate is composed: if set to 0 the
program automatically prints out a convenient minimal set of wave-function
components.


* Output format

The output format is self explanatory. We provide the demo files as a hint
to the general technique that the user may employ in fitting his data.

The three ordered examples for HCN show a typical history of a fit of a
"new" molecular specie, from the beginning. These demo files are meant as
examples of a standard fitting procedure. The values of N1 and N2 are
computed as described in the article, from the diatom anharmonicities. One
starts with only the three fundamentals plus (optionally) the first
overtone of the bending vibration. The initial values of the first order
parameters are also estimated as described in the article. After a first
run, one gets the touthcn1.dat file. The improved parameters (in
parguess.dat) replace the first guess, and more data are added, based on
the computed spectrum. One can iterate this procedure, putting in more and
more data.  If it is necessary to improve the quality of the fit, higher
order operators may be added into the Hamiltonian. They can be chosen in
the lists vibr3atns.dat/vibr3atnn.dat (symmetrical/non-symmetrical
case). The "guess" values of all the new parameters should be small but
always nonzero. For nondiagonal operators try to start with an initial
guess of both signs, and see which sign yields a better local minimum of
the fit deviation.


* New features of 2001 version:

-	complete compatibility with old input files;

-	direct LAPACK / NAG / IMSL compatibility;


* Known bugs

Yes, there is especially one: the local label of each normal state is not
really bullet-proof, especially in high-vibron multiplets. The algorithm to
compute it is partially empirical, and, after all, it does work
surprisingly well, for dealing with such a fancy task as LOCAL assignations
of NORMAL modes!


				If problems might arise, please contact us!
dr. Nicola Manini: manini@mi.infm.it
dr. Stefano Oss  : oss@science.unitn.it