DOCUMENTATION for SPFIT and SPCAT

These programs use subroutines in SPINV.FOR to calculate energies and
intensities for asymmetric rotors and linear molecules with up to
9 vibrational states and up to 5 spins.  The number of spins can
be increased to 9 by a change of dimensions. Because of other
dimensioning limitations on the size of the Hamiltonian, these
limits on the numbers of vibration and numbers of spins cannot be
exercised at the same time without changing dimension limits on the
size of arrays(see below for directions on how to do this).
No distinction is made between electronic and nuclear spins, or between 
electronic states and vibrational states.
 
See CALPGM.DOC for a description of the input and output files.
Some of the details of the program are described in H. M. Pickett, 
"The Fitting and Prediction of Vibration-Rotation Spectra with Spin
Interactions," J. Molec. Spectroscopy 148, 371-377 (1991). 
 

Quantum numbers which are used in file.lin and file.cat can be given 
in several formats:
                                quantum numbers      [ Q]
          Linear Sigma States:  N, v,  J, F1, F2, F  [11]       or
                                N, J, F1, F2, F3, F  [ 1]
                                N, v,  J, F1, It, F  [31]
                                N, J, F1, F2, It, F  [21]
                                N, v,  n,  F         [51]
                                N, n,  F             [41]
          Symmetric Tops:       N, K,  v,  J, F1, F  [12]       or
                                N, K,  J, F1, F2, F  [ 2]
                                N, K,  v,  J, It, F  [32]
                                N, K,  J, F1, It, F  [22]
                                N, K,  v,  n,  F     [52]
                                K, K,  n,  F         [42]
          Asymmetric Tops:      N, Ka, Kc, v,  J, F  [13]       or
                                N, Ka, Kc, J, F1, F  [ 3]
                                N, Ka, Kc, J, It, F  [23]
                                N, Ka, Kc, v,  n, F  [53]
                                N, Ka, Kc, n,  F     [43]

The quantum number `n' is an aggregate spin quantum number which
is used when the number of quantum numbers would otherwise be
greater than 6. Half integer spins are rounded up to the next
integer. The sign of K for symmetric top notation designates parity
under inversion. The symmetric top notation can also be used
equivalently for linear molecules with orbital angular momentum
(Lambda not zero). If the number of vibrations is one, then v is
not included. The sequence J, F1 .. F can be replaced with F1, F2
.. F if no electronic spin is present. The length of the quantum
number list is determined by the number of spins requested. The
factoring of the Hamiltonian is determined by the parameter set.

The field QNFMT in file.cat can be regarded as having 3 subfields:
    QFMT = Q*100 + H*10 + NQN
in which NQN is the number of quanta per state, H is a binary code
the existence of half integer quanta for the last three quantum numbers,
and Q is the number in square brackets in the table above. The least
significant bit of H refers to the F quantum number and is 1 if F is half
integer

FORMAT option information beginning on line 3 of file.par and file.var :


CHR,SPIND,NVIB,KNMIN,KNMAX,IXX,IAX,WTPL,WTMN,VSYM,EWT,DIAG
        CHR   = character to modify parameter names file
                (must be in first column)
                sping.nam , default is 'g'. 'a' is used
                for Watson A set, 's' is used for Watson
                S set. Other character replaces the 'g' in
                the name 'sping'. Only used to label the .fit
                output file. (Ignored on all but first option line.)
  sign SPIND  = negative, use symmetric rotor quanta
                positive, use asymmetric rotor quanta
                (Sign ignored on all but first option line.)
  mag  SPIND  = degeneracy of spins, first degeneracy
                in units digit, second in tens digit, etc.
                (If last digit is zero, spin degeneracies occupy
                two decimal digits.)
  sign NVIB   = positive, prolate rotor (z=a,y=b,x=c)
                negative,  oblate rotor (z=c,y=b,x=a)
                (Sign ignored on all but first option line.)
  mag  NVIB   = number of vibrational states on the first option
                line, identity of the vibrational state on all but
                the first option line.  (max. value = 99)
  KNMIN,KNMAX = minimum and maximum Kz values
                if both = 0 then linear molecule selected
  IXX         = binary flag for inclusion of interactions
                        1 means no delta N
                        2 means no delta J
                        4 means no delta F1   ,etc.
                        [default include all interactions]
                (Ignored on all but first option line.)
  mag IAX     = axis for statistical weight ( 1=a, 2=b, 3=c,
                add 3 if K-odd are excluded, 
                add 6 if K-even are excluded) 
 sign IAX     = if negative, use 'It' basis in which the last
                two spins are summed to give Itot, which is
                then combined with the other spins to give F
                (Sign ignored on all but first option line.)
  WTPL,WTMN   = statistical weights for even and odd state
  VSYM        = If positive, vibrational symmetry coded as decimal
                digits ( odd means reverse WTPL with WTMN)
                example: 10 = ( v=0 even, v=1 odd)
                (Only works for the first nine states)
                (Value ignored on all but first option line.)
                If negative, signal that the next line is also an
                option line.
  EWT         = weight for states with 3-fold E symmetry
                (SPIND must be negative, WTPL and WTMN
                 apply to A1 and A2 symmetry)
                will not be used if EWT is negative (default) 
                EWT=EWT0+EWT1*100
                If D3 symmetry (e.g. NH3),
                      for bosons: WTPL  =(2I+1)(2I+3)(I+1)/3
                                  WTMN  =(2I+1)(2I-1)(I)/3
                                  EWT0  =(2I+1)(I+1)(2I)/3
                      for fermions WTPL and WTMN are reversed
                      for I=1/2, when WTMN=0, multiply EWT0 by 2
                      because only half the E states are calculated
                If C3 symmetry (e.g. CH3F ),
                                  WTPL=WTMN=(2I+1)(4I*I+4I+3)/3
                                  EWT0=(2I+1)(I+1)(4I)/3
                Note: These weights can be divided by a
                      common multiple if the rotational partition
                      function is divided by the same factor
                The A1 and A2 states are for MOD(ABS(K)+EWT1,3)=0
                with EWT1=0 for l=0, EWT1=1 for l=-1, and EWT2=2 for l=+1
   DIAG       = -1 for no diagonalization
                 0 for energy ordering within Wang subblocks
                 1 for full projection assignment
                 2 for projection assignment followed by
                   energy ordering for same K
                   (DIAG will be converted to -1 if no parameters
                   have operators which are off-diagonal)
                   
                   
For most cases only a single option line is needed. If different vibrational
or electronic states have different spin multiplicity or different KMIN,KMAX
additional lines are needed. Note that additional lines are signaled by the
sign of VSYM. The first option line sets up the defaults for all the 
vibrational states, and subsequent option lines specify deviations from
the default. It is possible to mix Boson and Fermion states in the same
calculation, e.g. fitting different isotopomers together, but the qunatum
number format (QNFMT) in the .cat file will be correct only for the 
v=0 state. 


PARAMETER identifiers in file.par are coded in decimal digit form in the
order
       FF,I2,I1,NS,TYP,KSQ,NSQ,V2,V1
         for NVIB < 10:
             each element occupies one digit except TYP which
             occupies two digits, i.e. 
             ((((((FF*10+I2)*10+I1)*10+NS)*100+TYP)*10+KSQ)*10+V2)*10+V1
         for NVIB > 9:
             each element occupies one digit except TYP, V1, and V2 which
             occupy two digits, i.e. 
             ((((((FF*10+I2)*10+I1)*10+NS)*100+TYP)*10+KSQ)*100+V2)*100+V1

       FF          = Fourier flag (used for internal rotation)
                     1 = operator multiplied by
                         cos(2*NS*pi*Kavg*rho/3)
                     2 = operator multiplied by
                         sin(2*NS*pi*Kavg*rho/3)
                         if NS>0 or sign(Kavg) if NS=0
       I2,I1       = spin identifiers [I1 GE I2] I1=0 or I2=0 means N.
       NS          = power of N.S where S is the first spin
                     when FF=0, otherwise Fourier order
       TYP         = projection type
                         0 = scalar
                         1 = aa projection (no trace for I2 ne 0)
                         2 = bb projection (no trace for I2 ne 0)
                         3 = cc projection (no trace for I2 ne 0)
                       4+n = Phi+**2 N+**2n + Phi-**2 N-**2n
                      20+n = off-diagonal  "a" symmetry
                        20 = vector along a
                        21 = bc + cb projection
                      40+n = off-diagonal  "b" symmetry
                        40 = vector along b
                        41 = ac + ca projection
                      60+n = off-diagonal  "c" symmetry
                        60 = vector along c
                        61 = ab + ba projection
                      80+n = unique contribution
                             for K'=K"=n*10+KSQ
                     90+2n = Euler series multiplying
                             Phi+**2 N+**2n + Phi-**2 N-**2n
                     91+2n = constants for Euler and Fourier series
       KSQ         = power of Nz**2
       NSQ1        = power of N*(N+1)
       V1,V2       = vibrational identifier, [V1 GE V2]
                     for NVIB < 10: V1=V2=9  matches all V1=V2
                     for NVIB >  9: V1=V2=99 matches all V1=V2

note 1: N+ = Nx + i Ny .
        EVEN values of TYP >=20 and < 80 have an implicit i, if
        FF < 2. If FF=2, then the parameter has an implicit i
        unless ITYP >=0 and < 80 and is even.
note 2: Prolate basis is I r, and oblate basis is III l.
note 3: rho(v,v') is specified by 9100vv'. TYP=91+2n parameters,
        including rho, are constants and are not fitted.
note 4: For operators with TYP=1,2,3, if I2 is zero the operator is
        the expected Cartesian projection, while if I2 is not zero
        the operator is the expected Cartesian projection - I2.I1/3.
        For example, 10000 is the NzNz operator, 10010000 is the NzSz
        operator, 120010000 is the SzIz-S.I/3 operator.
note 5: For operators with I2=I1 > 0, spin corrections appropriate for
        nuclear quadrupole coupling are applied: SQRT((2I+1)/(2I-1))/4I.
note 6: For the series with TYP=20+n,40+n,60+n, the operator is the
        tensor of order (n+1) with the highest change in K for the given
        symmetry. For the series with TYP=40+n, the change in K is
        (1,1,3,3,5,5,..) . For a prolate rotor basis, the series with
        TYP=20+n corresponds to a change in K of (0,2,2,4,4,6,..),
        while the series with TYP=60+n has the same change in K as TYP=
        40+n. For the oblate rotor basis, the changes in K are reversed
        between TYP=20+n and TYP=60+n.
note 7: When coupling states where a given electronic (or nuclear) spin
        is different (e.g. spin-orbit coupling), the reduced matrix
        element for the spin operator is assumed to be unity.


FORMAT of dipole identifiers file.int:
   IDIP  is coded in decimal digit form according to the format
     for NVIB < 10:
      (((TYP*10 + I1)*10  + V2)*10 + V1)*10 + SYM, with
     for NVIB >  9:
      (((TYP*10 + I1)*100 + V2)*100+ V1)*10 + SYM, with

      TYP         = dipole type
      I1          = spin identifier [ I1 = 0 means N or null ]
      V1,V2       = vibrational states [ V1 GE V2 ]
      SYM         = symmetry [0 = magnetic, 1=a, 2=b 3=c]

  TYP   SYM     Description
   0     0       magnetic dipole [ N, S, I ]
   0     1       a dipole, phi-a if I1=0, else phi-a X I
   0     2       b dipole, phi-b if I1=0, else phi-b X I
   0     3       c dipole, phi-c if I1=0, else phi-c X I
   1     0       0.5*(3*phi-z*Nz - 1) or 0.5*(3*phi-z*Iz - 1)
   1     1       (phi-b*Nc + phi-c*Nb) or (phi-b*Ic + phi-c*Ib)
   1     2       (phi-a*Nc + phi-c*Na) or (phi-a*Ic + phi-c*Ia)
   1     3       (phi-a*Nb + phi-b*Na) or (phi-a*Ib + phi-b*Ia)
   2     0       (phi-x*Nx - phi-y*Ny)/4 or (phi-x*Ix - phi-y*Iy)/4
   3    any      TYP=0 * N*(N+1)
   4    any      TYP=0 * Nz*Nz
   5    any      TYP=0 left commutator with N*(N+1)/2
   6    any      TYP=0 * (NbNb - NcNc)
   7    any      TYP=0 * cos(2*I1*pi*K*rho/3)
   8    any      TYP=0 * sin(2*I1*pi*K*rho/3)
   9    any      TYP=0 * N*N*(N+1)*(N+1)
  10    any      TYP=0 left commutator with N*N*(N+1)*(N+1)/4


Note: Dipoles with SYM not 0 are assumed to be in units of Debye.
      Dipoles with SYM  =  0 are assumed to be in units of a Bohr
           magneton.
      Dipoles which are even order in direction cosine or N are
           assumed to be multiplied by i.
      For ITYP = 7 or ITYP = 8, I1 is used for the Fourier order
           and not the spin type. The constant rho is
           specified in the parameter set. ITYP = 8 dipoles are
           multiplied by i, and the symmetry of the states
           connected is 3-SYM and the units follow the state
           symmetry (e.g. 81000 is in Debye ).

SPECIAL CONSIDERATIONS FOR LINEAR MOLECULES
     This program set will calculate a variety of interactions and
transitions within a Hund's case(b) basis, including spin orbit
interactions which change spin multiplicity. In the asymmetric
rotor language of this program, the first-order spin orbit
interaction takes the operator form of a vector dot product of a
direction cosine with the spin vector. It can have three distinct
symmetries: S.Phi-a connects states of the same lambda, while
S.Phi-b and S.Phi-c connect states where lambda differs by one.

     Use of the symmetries in this program takes some care,
particularly for linear molecules where it may not be immediately
obvious whether to use the b or the c axis to designate
perpendicular operators. For consistency with the parity
designation for the symmetric top quanta, it is recommended that
the b axis be used for the symmetry defining axis (i.e. IAX=2 in
the option lines of the .par and .var files). With this choice, the
symmetry of rotation lines in the D2h group are:
        Ag: even N for Sigma+ and all N for all other even lambda
        Au: even N for Sigma-
     B(a)u:  odd N for Sigma+ and all N for all other even lambda
     B(a)g:  odd N for Sigma-
     B(b)g: for odd lambda (even parity lambda doublet)
     B(c)u: for odd lambda ( odd parity lambda doublet)
This means that the Hamiltonian, as well as magnetic dipoles, can
couple Sigma+ with Sigma- via an operator of B(a) symmetry. An
example is an operator like 10200001, which is the S.Phi-a spin
orbit interaction operator between state v=0 and v=1. Similarly,
interactions between Sigma- and Pi states have B(c) symmetry and
all other such interactions between Sigma+ and Pi states and
between Pi and Delta have B(b) symmetry. Electric dipole
transitions between Sigma- and Pi states have B(b) symmetry, while
all other delta lambda = 1 electric dipole transitions have B(c)
symmetry. Electric dipole transitions between the lambda doublets
have B(a) symmetry.

The g,u symmetry above is for the parity of the wavefunction under
inversion of the space fixed axes. The nuclear exchange symmetry,
on the other hand, affects only the statistical weights and does
not have any further impact on the factoring of the Hamiltonian.
In general, if IAX=2, WTPL will be the nuclear spin weight for
the Ag,Au,B(b)g, and B(b)u states, while WTMN will be the weight
for the others. For Sigma+g, Sigma-u, and g states with other
lambda, WTPL is the weight for even permutations, while for
Sigma-g, Sigma+u, and u states with other lambda, WTPL is the
weight for odd permutations. For example, in oxygen, Sigma+g and
Delta(g) have WTPL=1 and WTMN=0, while for Sigma-g WTPL=0 and
WTNM=1.

The dipole types given above provide for both allowed and forbidden
transitions. For transitions that owe their intensity to spin orbit
interactions the effective transition moment with be the product
of the interaction and a transition moment to some intermediate
state. Examples are a Delta Sigma- electric dipole code of 21vv'0
and a magnetic dipole code of 11vv'1. Electric dipole transitions
between Sigma+ and Sigma- will use 11vv'0, while magnetic
transitions will use 1vv'1. For transitions between Sigma+ and
Sigma+ the roles of these operators are reversed. Note that for
Sigma Sigma transitions, 11vv'0 has selection rules of delta
N = -2,0,+2, while 1vv'1 has selection rules of delta N = -1,+1.

Example of .var file for oxygen like molecule:
 mock oxygen states 
 4  
-3 3 0 0 0 2 0 1 -1 /default for v=0 triplet Sigma-(g)
 1 1 2 2 0 2 1 0 -1 /v=1 is singlet Delta(g)
 1 2 0 0 0 2 1 0  0 /v=2 is singlet Sigma-(g)
         11 1e+7     0  /term value for v=1
         22 2e+7     0  /term value for v=2
  110010000 1000.0   0  /spin-spin interaction for v=0
        199 10000.0  0  /B for all v
Example of .int file for oxygen like molecule:
 mock oxygen rotational and electronic transitions
 101 99000 200. 0     6    -80. -80.        99999999.
 1000 1. /magnetic moment v=0
 1110 1. /magnetic moment v=1
11011 1. /sigma - delta magnetic moment
 1021 1. /sigma - sigma magnetic moment 
 
--------------------------------------------------


Example of parameter types for asymmetric rotors:
         11 energy for v=1
      10000 A(0)
      10099 A    ( all vibrational states with v'=v" )
      20099 B
      30099 C
      40099 0.25*(B-C)    ( if prolate basis selected )
        299 -DJ
       1199 -DJK
       2000 -DK(0)
     600001 i Nc interaction between v=0 and v=1
   20000099 N.I for second spin
  120010099 SaIa
  220010099 1.5 * quadrupole moment aa for second spin
  220040099 quadrupole moment 0.25*(xx-yy) for second spin

Warning: parameters requested really signify the operator which
will multiply the parameter. Parameters not explicitly requested
are presumed to be zero. For example, B for a linear molecule or
symmetric top is 100, while for an asymmetric top it is 20000.


MODIFYING DIMENSIONS IN SPINV.FOR

For really complicated problems, dimensioning in CALFIT, CALCAT, and SPINV 
may not be adequate. All the easily modified dimensions are in the form of 
PARAMETER statements. In SPINV make sure to modify all instances of the 
given PARAMETER. Generally, there will be an error message which indicates
what PARAMETER is causing a problem.

In CALFIT and CALCAT, basic storage for eigenvectors, derivatives, and 
strength matrices are allocated by HEAPLN. The maximum number of parameters
is given by NDPAR and the maximum number of energies is given by NDEGY.

In SPINV, MXSPIN sets the number of spins, but do not set it above 9. MAXQ 
sets the maximum number of sub-blocks of a given Hamiltonian, while NX sets
the maximum number of spin combinations for a give F. NDPAR sets the maximum
number of 'internal' parameters. The number of internal parameters is greater
because parameters like the C rotational constant are calculated as three 
spherical tensor components. NDMX sets working storage for the number of 
elements that are non zero for a given spherical tensor parameter, but its 
size should not grow with the problem.