general [CDMS classic documentation]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Documentaion for SPFIT and SPCAT ======


Last local (HSPM) modification: May 2, 2001\\
Notes, hints, and special considerations are highlighted.

These programs use subroutines in SPINV.C to calculate energies and intensities for asymmetric rotors and linear molecules with up to 99 vibrational states and up to 9 spins. No distinction is made between electronic states and vibrational states, or between electronic and nuclear spins. SPFIT is used for fitting transitions and term values, with no requirement that the transitions obey any particular selection rules. SPFIT takes input files with extensions par and lin, copies the par file to a bak file, creates new text output files with extensions par, fit, var, and creates a binary file with extension unf which is redundant with the var file but carries more precision for use in SPCAT. (Note: The unf file has been omitted in the more recent versions !) The par and var files follow essentially the same format and contain fitting parameters and optionally correlation information. The fit file contains the results of the fit. SPCAT is used for predicting line positions and strengths. It takes the var and unf files as input along with an int file that specifies limits for the calculation and contains the transition dipoles. The main output files for SPCAT use extensions out and cat, which are for general information and for the catalog output format, respectively. The cat file follows the format of the JPL catalog, but does not have experimental data flagged. Auxiliary output files with extensions egy and str can also be requested. The egy file can contain energies, derivatives with respect to the parameters, eigenvalues, and the undiagonalized Hamiltonian. The str file contains a list of all transition dipole moments. The file names for SPFIT and SPCAT can be specified as command line arguments in any order. The first file name is used as the base file name for any files not explicitly specified. If no command line arguments are specified the program will give a prompt for the file names.

Some of the details of the program are described in
<alert type="info">
H. M. Pickett, "The Fitting and Prediction of Vibration-Rotation Spectra with Spin Interactions," J. Mol. Spectros. 148, 371-377 (1991).
</alert>

===== Format of Quantum Numbers =====

Quantum numbers which are used in the files **can be given in several formats**:

The field QNFMT in the cat file can be regarded as having 3 sub-fields:\\
**QNFMT = Q*100 + H*10 + NQN**, in which **NQN** is the number of quanta per state,
**H** is a binary code to indicate which of the last three quantum numbers are half integer quanta
(1 indicates that F is half integer), and **Q** is the number in square brackets in the table below.
The least significant bit of **H** refers to the F quantum number and is 1 if F is half integer.

**Q**mod5 gives the number of principal quantum numbers, i.e. without those designating spin quanta.
Thus it is **0** for atoms, **1** for linear molecules in S states, **2** for symmetric rotors and linear molecules
in states other than S, and **3** for asymmetric rotors.\\
Add 11 if several states are fit together. These can be vibrational or electronic states, different
isotopomers etc.\\
Add 20 if two spins are coupled to I<sub>tot</sub>.\\
Add 40 if [[aggregate|aggregate spin number n]] is used because the number of quantum numbers needed otherwise exceeds 6.

<alert type="warning">
**Note:** These "corrections" to **Q** can be used simultaneously. For example, it can be 43 for NH<sub>2</sub> (see lase entry in table below) or 63 if the two hydrogen nuclei are coupled to I<sub>tot</sub> before they are coupled to J.
</alert>

Examples for Q:

^Linear Sigma States: ^^^^^^[Q]^
|N	|v	|J	|F1	|F2	|F	|[12]|
|N	|J	|F1	|F2	|F3	|F	|[01]|
|N	|v	|J	|F1	|Itot	|F	|[32]|
|N	|J	|F1	|F2	|Itot	|F	|[21]|
|N	|v	|n	|F	|-	|-	|[52]|

^Symmetric Tops: 	^^^^^^[Q]^
|N	|K	|v	|J	|F1	|F 	|[13]|
|N	|K	|J	|F1	|F2	|F	|[02]|
|N	|K	|v	|J	|Itot	|F	|[33]|
|N	|K	|J	|F1	|Itot	|F 	|[22]|
|N	|K	|v	|n	|F	|-	|[53]|
|N	|K	|n	|F	|-	|-	|[42]|

^Asymmetric Tops: 	^^^^^^[Q]^
|N	|Ka	|Kc	|v	|J	|F	|[14]|
|N	|Ka	|Kc	|J	|F1	|F	|[03]|
|N	|Ka	|Kc	|J	|Itot	|F 	|[23]|
|N	|Ka	|Kc	|v	|n	|F 	|[54]|
|N	|Ka	|Kc	|n	|F 	|-	|[43]|

In most cases, the spin coupling scheme is N + S = J, J + I<sub>1</sub> = F<sub>1</sub>,...,
F<sub>n-1</sub> + I<sub>n</sub> = F, but an alternative that can be selected is the scheme ...,
I<sub>n-1</sub> + I<sub>n</sub> = I<sub>tot</sub>, F<sub>n-2</sub> + I<sub>tot</sub> = F.
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 rotation about the //b// axis. When the vibronic wave function
is even with respect to reflection in the //ac// plane, then the sign of K will also indicate the parity
with respect to inversion. The symmetric top notation can also be used equivalently for linear molecules
with orbital or vibrational 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.

===== Format of the ''lin'' File =====

**line 1-NLINE [12|3, freeform]:** QN, FREQ, ERR, WT

> QN = 12 integer field of quantum numbers. Interpreted in a multiple I3 format as the quantum numbers for the line (upper quanta first, followed immediately by lower quanta). Unused fields can be used for annotation. The entire field is printed in file.fit\\
> FREQ = frequency in MHz or cm<sup>-1</sup>
> ERR = experimental error.
<alert type="warning">
**NOTE:** Minus sign means that the frequency and error are in units of cm<sup>–1</sup>. FREQ and ERR will be converted internally to units of MHz.
</alert>
> WT = relative weight of line within a blend **(normalized to unity by program)**. Not needed for unblended lines. If WT is not specifically given in the line file, **1/n** will be used by the program if **n** is the number of blended lines at the same frequency and following successively.

<alert type="warning">
**NOTES:** If an end-of-file is encountered before all the lines are read in, NLINE is set to the number read to that point. If successive lines have the same frequency, the lines will be treated as a blend and derivatives will be averaged using WT/ERR. Any lines with format errors will be ignored.
</alert>
The freeform input begins in column 37 and extends to the end of the line.
See the notes at the end of the next section for more on the freeform input.

===== Format of the ''par'' and ''var'' Files =====

**line 1:** title

**line 2 [freeform]:** NPAR, NLINE, NITR, NXPAR,  THRESH, ERRTST, FRAC, CAL

> NPAR = maximum number of parameters
> NLINE = maximum number of lines
> NITR = maximum number of iterations
> NXPAR = number of parameters to exclude from end of list when fitting special lines (with negative //**F**// quantum number)
> THRESH = initial Marquardt-Levenburg parameter
> ERRTST = maximum [(obs-calc)/error]
> FRAC = fractional importance of variance
> CAL = scaling for infrared line frequencies (only NPAR used by SPCAT)

<alert type="warning">
**NOTES:** After a fit, NPAR will be set to the actual number of parameters or to the number of parameters requested – whichever is **SMALLER** ! Therefore, it is mandatory to increase NPAR if new parameters are specified.\\
The same applies to NLINE !\\
ERRTST has to be sufficiently large to use new lines in the fit. It may be reduced if lines outside **ERRTST** should be excluded from the fit.
</alert>
**Option information beginning on line 3:** 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.) SPFIT looks for the //nam// files in the current directory and then in the path given by the SPECNAME environment variable. (i.e. put something like SET SPECNAME=C:\SPECTRA\ in AUTOEXEC.BAT for Windows or setenv SPECNAME /spectra/ for unix). The trailing path delimiter is required.\\
> sign SPIND: If negative, use symmetric rotor quanta. If positive, use asymmetric rotor quanta (Sign ignored on all but first option line.)\\
> mag SPIND = degeneracy of spins, first spin degeneracy in units digit, second in tens digit, etc. (If last digit is zero, spin degeneracies occupy two decimal digits and the zero is ignored.)\\
> sign NVIB: positive means //I<sup>r</sup>// representation (z = a, x = b, y = c), usually used for prolate rotors; negative means //III<sup>l</sup>// representation (z = c, x = b, y = a), usually used for oblate rotors. (Sign ignored on all but first option line.)\\
> mag NVIB = number of states (e. g. vibronic; also possible: isotopomers etc.; **counted from zero !**) on the first option line, identity of the vibronic state on all but the first option line. (max. value = 99)\\
> KNMIN,KNMAX = minimum and maximum K values. If both = 0, then linear molecule is selected.\\
> IXX: binary flag for inclusion of interactions: 1 means no delta N, 2 means no delta J, 4 means no delta F<sub>1</sub> ,etc. [default = 0 includes all interactions] (Ignored on all but first option line.)\\
> sign IAX: If negative, use I<sub>tot</sub> 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
> 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)\\
> VSYM: If positive, vibronic symmetry coded as decimal digits (odd digit 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 = EWT0 + EWT1*100 = weight for states with 3-fold E symmetry. Ignore if EWT is negative (default) (WTPL and WTMN apply to A1 and A2 symmetry)
 
For D3 symmetry (e.g. ND3), 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

For C3 symmetry (e.g. CH3F ):

> WTPL = WTMN = (2I+1)(4I*I+4I+3)/3
> EWT0 = (2I+1)(I+1)(4I)/3

<alert type="warning">
**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. STATES with EWT1 not zero MUST be specified in adjacent pairs. E symmetry states will be designated with positive K for symmetric top quanta. For asymmetric top quanta with l = 1, K<sub>a</sub> + K<sub>c</sub> = N+1. For asymmetric top quanta with l = –1, K<sub>a</sub> + K<sub>c</sub> = N. This designation for quanta in l=1 and l = –1 states will also be applied to A symmetry states if there are only delta l = 0 operators. If both WTPL and WTMN are not zero, there will be two E states with the same nominal quantum number. (CALMRG will merge the degenerate transitions into a single line. **(It appears as if this does not always happen)**.)
</alert>
<code>
DIAG =
  –1 for no diagonalization\\
  0 for energy ordering within Wang sub-blocks\\
  1 for full projection assignment\\
  2 for energy ordering within Wang sub-blocks which follows order of diagonal elements of Hamiltonian\\
  3 for energy ordering within vibration and spin sub-block set
</code>

<alert type="warning">
**NOTE:** For many cases only a single option line is needed. If different vibronic 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 quantum number format (QNFMT) in SPCAT output will be correct only for the v = 0 state.
</alert>

====== Coding of the Parameters ======

===== Parameter lines: IDPAR, PAR, ERRPAR / LABEL =====

where IDPAR is a parameter identifier, PAR is the parameter value,  ERRPAR is the parameter uncertainty, LABEL is a parameter label (10 characters are used) that is delimited by **/. ** If the sign of IDPAR is negative, SPFIT constrains the ratio of this parameter to the previous parameter to a fixed value during the fit.

PARAMETER identifiers (IDPAR) are coded in decimal digitform in the order
<code>
NFF, 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+NSQ)*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)*10+NSQ)*100+V2)*100+V1
</code>
  * NFF = Fourier flag (used for internal rotation) If NFF < 11, basic operator is multiplied by cos (NFF * 2p K<sub>avg</sub>r / 3) else operator multiplied by sin ( (NFF-10) * 2p K<sub>avg</sub>r / 3) where r is coded by the absoulte value of parameter ID=9100vv. See further discussion below.
  * I2,I1 = spin identifiers [I1 >= I2], I1=0 or I2=0 means N.
  * NS = power of  N· S where S is the first spin If NS > 4, subtract 5 and add S<sub>z</sub>N<sub>z</sub> operator
  * TYP = projection type
    * 0 = scalar
    * 1 = N<sub>a</sub>N<sub>a</sub>
    * 2 = N<sub>b</sub>N<sub>b</sub>
    * 3 = N<sub>c</sub>N<sub>c</sub>
    * 3+n = N<sub>+</sub><sup>2n</sup> + N<sub>–</sub><sup>2n</sup> , n = 1 ... 8 (//L// = 2n, D//K// = 2n)
    * 11+n = "x" symmetry, n = 1 ... 8 (//L// = 2n + 1, D//K// = 2n)
    * 20+n = off-diagonal "a" symmetry, n = 0 ... 19 (for prolate basis: //L// = n + 1, D//K// = 0, 2, 2, 4, 4, ...)
    * 20 = N<sub>a</sub>
    * 21 = N<sub>b</sub> N<sub>c</sub> + N<sub>c</sub> N<sub>b</sub>
    * 40+n = off-diagonal "b" symmetry, n = 0 ... 19 (//L// = n + 1, D//K// = 1, 1, 3, 3, ...)
    * 40 = N<sub>b</sub>
    * 41 = N<sub>a</sub> N<sub>c</sub> + N<sub>c</sub> N<sub>a</sub>
    * 60+n = off-diagonal "c" symmetry, n = 0 ... 19 (for prolate basis: //L// = n + 1, D//K// = 1, 1, 3, 3, ...)
    * 60 = N<sub>c</sub>
    * 61 = N<sub>a</sub> N<sub>b</sub> + N<sub>b</sub> N<sub>a</sub>
    * 80+n = unique contribution for //K'// = //K"// = n*10+KSQ
    * 90+2n = Euler series multiplying N<sub>+</sub><sup>2n</sup> + N<sub>–</sub><sup>2n</sup>
    * 91+2n = constants for Euler and Fourier series
    * 91 = r for Fourier series if KSQ = 0, NSQ1 = 0, and V1=V2.  Only the absolute value is used for  r, and the value is used to designate a special symmetry.
  * KSQ = power of N<sub>z</sub><sup>2</sup>
  * NSQ = power of N*(N+1)
  * V1,V2 = vibrational identifier, [V1 >= V2] For NVIB < 10: V1 = V2 = 9 matches all V1 = V2. For NVIB > 9: V1 = V2 = 99 matches all V1 = V2.

<alert type="danger">
**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.
</alert>

<alert type="warning">
**NOTES:**
  - Direction cosines have been omitted.
  - N<sub>+</sub> = N<sub>x</sub> + iN<sub>y</sub>. If NFF < 11, then parameters with EVEN values of TYP >= 20 and < 80 have an implicit i. If NFF>10, then parameters with ODD values of TYP >= 20 and < 80 have an implicit i. Also, if NFF > 10, then all parameters of TYP < 20 have an implicit i. If EWT1 = 1 for both of the vibrational states, then these nominally imaginary parameters are assumed to be real and multiplied by the L<sub>z</sub> operator (see below).
  - The sign of the r parameter is used to designate a special symmetry for the Fourier series.  If this sign is different for V1 and V2, then 0.5 is subtracted from NFF.  For example, if NFF = 2, the basic operator is multiplied by cos ( 3p K<sub>avg</sub>r / 3) instead of cos (4p K<sub>avg</sub>r / 3).  If the magnitude of  r is not the same for the two states, replace K<sub>avg</sub>r with (K<sub>1</sub>r<sub>1</sub> +K<sub>2</sub>r<sub>2</sub>) / 2.
  - Prolate basis is //I <sup>r</sup>//, and oblate basis is //III <sup>l</sup>//. D//K// behavior for TYP = 20+n and 60+n are reversed for oblate basis.
  - r<sub>v,v</sub> is specified by 9100vv. TYP = 91+2n parameters, including r, are constants and are not fitted.
  - For operators with I2 = 0 and I1 > 0, one value of N is replaced with the appropriate projection of I<sub>I1</sub>. For operators with I2 > 0 and I1 > 0, two values of N are replaced with appropriate projections of both I. For TYP=1,2,3, the operator is the expected Cartesian projection - I2.I1 / 3. For example, 10000 is the N<sub>z</sub>N<sub>z</sub> operator, 10010000 is the N<sub>z</sub>S<sub>z</sub> operator, and 120010000 is the S<sub>z</sub>I<sub>z</sub> – S.I / 3 operator.
  - For operators with I2 = I1 > 0, spin corrections appropriate for nuclear quadrupole coupling are applied: SQRT( (2I+1)/(2I–1) )/4I.
  - Whenever operators that do not commute are combined, the resulting operator is half the anti-commutator. The order of application is N<sub>z</sub>S<sub>z</sub>, followed by N<sub>z</sub><sup>2</sup>, followed by N<sup>2</sup> and N· S.
  - 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.
  - A value for **ERRPAR** much larger than 10<sup>10</sup> means that the parameter is allowed to vary in the fit. A value much smaller than 10<sup>–10</sup> means the parameter is kept fixed. A value inbetween constrains the parameter to some extent. In theory, it should not vary by more than ERRPAR. In practice, correlation effect may lead to changes which are larger by more than an order of magnitude.
</alert>

**line (n+1)-end [8F10.6]:** ((V(i,j), j = i, ... ,NPAR), i = 1, ... ,NPAR)

> V = Choleski decomposition of the correlation matrix, optional for file.par

<alert type="warning">
**NOTES:** In the freeform input, the variables are all preset to reasonable default values. The input numbers can be separated by any character not usually found in an E or F formatted number. A space or comma is recommended. Two successive commas indicate that the default value is to be used for that variable. At the end of the line or when a ‘/’ character is encountered, all unspecified variables remain set to their default values. PAR defaults to zero. ERRPAR defaults to a very large number for CALFIT and to zero for CALCAT. If an end-of-file or error is encountered before the parameters are read in, NPAR is set to the number read to that point. If an end-of-file or error is encountered before V is completely read in, V is set to a unit matrix. CALCAT will attempt to get V from file.unf if it exists.
</alert>
Special lines to which NXPAR applies are lines in which the F quantum number is negative. In the quantum number assignment process in the program, the line is flagged and F is set to an appropriate value. When derivatives are accumulated, the last NXPAR derivatives are ignored, and the energies are corrected by subtracting the first order contribution of these parameters. If F < –1, the absolute value of F is used in the energy calculation. If F = –1, the F used is as close to the previous spin quantum number as angular momentum addition rules allow. The value selected will be shown in the fit file line listing in place of the –1.

If IDPAR is less than zero the magnitude is taken. In SPFIT, the parameter value will be constrained to be a constant ratio of the preceding parameter value. In this way linear combinations of parameters can be fit as a unit.

===== Format of the ''int'' File =====

**line 1:** title

**line 2 [freeform]:** FLAGS, TAG, QROT, FBGN, FEND, STR0, STR1, FQLIM, TEMP

> FLAGS = IRFLG*1000+OUTFLG*100+STRFLG*10+EGYFLG
>> IRFLG = 1 if constants are in cm<sup>–1</sup>
>> IRFLG = 0 if constants are in MHz
>> OUTFLG = 0 for a short form of //file.out// (recommended)
>> OUTFLG = 1 for a long form of //file.out//
>> STRFLG > 0 to enable the output of //file.str// (recommended: = 0)
>> STRFLG = 2 to enable separate entries for each dipole component in //file.str//
>> EGYFLG > 0 to enable in //file.egy// the energy listing
>> EGYFLG = 2, 4 to enable in //file.egy// the derivative listing
>> EGYFLG = 3, 4 to enable in //file.egy// the eigenvector listing
>> EGYFLG > 4 to dump Hamiltonian with no diagonalization

<alert type="warning">
**NOTE:** If the constants are in MHz, lines can be in units of cm<sup>–1</sup>, see Format of the //lin// File. However, if the constants are in units of cm<sup>–1</sup>, lines in units of MHz have to be converted into cm<sup>–1</sup>.
</alert>
> TAG = catalog species tag (integer)
> QROT = partition function for TEMP
> FBGN = beginning integer F quantum (round up)
> FEND = ending integer F quantum (round up)
> STR0,STR1 = log strength cutoffs
> FQLIM = frequency limit in GHz
> TEMP = temperature for intensity calculation in degrees K (default is 300K)

**line 3-end [freeform]**: IDIP,DIPOLE\\

> IDIP = dipole identifier (see below)
> DIPOLE = dipole value
<alert type="warning">
**NOTE:** The freeform input is defined above in the notes for //file.par//. The maximum log of the line strength output to file.cat from SPCAT must be greater than STR0 + STR1*(frequency/300GHz)<sup>2</sup>. Both STR0 and STR1 default to –100.
</alert>
> IDIP is coded in decimal digit form according to the format (for NVIB < 10):
<code>
(((TYP*10 + I1)*10 + V2)*10 + V1)*10 + SYM, or (for NVIB > 9):\\
(((TYP*10 + I1)*100 + V2)*100+ V1)*10 + SYM, with
</code>
> TYP = dipole type
> I1 = spin identifier [ I1 = 0 means N or null ]
> V1,V2 = vibrational states [ V1 >= 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, f<sub>a</sub> if I1 = 0, else f<sub>a</sub>´ I                                                                                                                                            |
|0  |2  |b dipole, f<sub>b</sub> if I1 = 0, else f<sub>b</sub>´ I                                                                                                                                            |
|0  |3  |c dipole, f<sub>c</sub> if I1 = 0, else f<sub>c</sub>´ I                                                                                                                                            |
|1  |0  |//i// (2f<sub>z</sub>N<sub>z</sub> – f<sub>x</sub>N<sub>x</sub> – f<sub>y</sub>N<sub>y</sub>)/2 or //i// (2f<sub>z</sub>I<sub>z</sub> – f<sub>x</sub> I<sub>x</sub> – f<sub>y</sub> I<sub>y</sub>)/2|
|1  |1  |//i// {f<sub>b</sub>, N<sub>c</sub>}/2 +  //i// {f<sub>c</sub>, N<sub>b</sub>}/2 or  //i// {f<sub>b</sub>, I<sub>c</sub>}/2 +  //i// {f<sub>c</sub>, I<sub>b</sub>}/2                               |
|1  |2  |//i// {f<sub>a</sub>, N<sub>c</sub>}/2 +  //i// {f<sub>c</sub>, N<sub>a</sub>}/2 or  //i// {f<sub>a</sub>, I<sub>c</sub>}/2 + //i// {f<sub>c</sub>, I<sub>a</sub>}/2                                |
|1  |3  |//i// {f<sub>a</sub>, N<sub>b</sub>}/2 +  //i// {f<sub>b</sub>, N<sub>a</sub>}/2 or  //i// {f<sub>a</sub>, I<sub>b</sub>}/2 +  //i// {f<sub>b</sub>, I<sub>a</sub>}/2                               |
|2  |0  |//i// (f<sub>x</sub> N<sub>x</sub> – f<sub>y</sub>N<sub>y</sub>) or  //i// (f<sub>x</sub>I<sub>x</sub> – f<sub>y</sub>I<sub>y</sub>)                                                                |
|2  |1-3|same as TYP = 1                                                                                                                                                                                     |
|3  |any|{N<sup>2</sup>, TYP = 0}/2                                                                                                                                                                          |
|4  |any|{N<sub>z</sub><sup>2</sup> , TYP = 0}/2                                                                                                                                                             |
|5  |1-3|[N<sup>2</sup> , TYP = 0] / 2                                                                                                                                                                       |
|6  |0  |L = 3, DK = 2                                                                                                                                                                                       |
|6  |1  |L = 3, DK = 2 if prolate basis                                                                                                                                                                      |
|6  |2,3|L = 3, DK = 3 if prolate basis                                                                                                                                                                      |
|7  |any|TYP=0 * cos(I1*2p K<sub>avg</sub> r / 3)                                                                                                                                                            |
|8  |any|TYP=0 * //i// sin(I1*2p K<sub>avg</sub> r / 3) or cos(20p K<sub>avg</sub> r / 3)  if I1 = 0                                                                                                         |
|9  |any|{N<sup>4</sup>, TYP = 0}/2                                                                                                                                                                          |
|10 |any|[N<sup>2</sup>, [N<sup>2</sup>, TYP = 0]]/4                                                                                                                                                         |
|11 |any|[N<sup>2</sup> , TYP = 2] / 2                                                                                                                                                                       |
|12 |any|//i// {N<sub>z</sub> , TYP=2}/2                                                                                                                                                                     |

<alert type="warning">
**NOTE:** Dipoles with SYM > 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 imaginary, except between states with EWT1 = 1. Dipoles between states with EWT1 = (0,2), (2,0), and (2,2) are ignored, but the matrix elements are calculated using corresponding dipoles from states with EWT1 = 1 (see below). For ITYP = 7 or ITYP = 8, I1 is used for the Fourier order and not the spin type. The constant r is specified in the parameter set. The sign of the r parameter is used to designate a special symmetry for the Fourier series.  If this sign is different for V1 and V2, then 0.5 is subtracted from the Fourier order.  For example, if IDIP = 72012, the basic //b//-dipole operator is multiplied by cos ( 3p K<sub>avg</sub>r / 3) instead of cos (4p K<sub>avg</sub>r / 3).  If the magnitude of  r is not the same for the two states, replace K<sub>avg</sub>r with (K<sub>1</sub>r<sub>1</sub> + K<sub>2</sub>r<sub>2</sub>) / 2. ITYP = 8 (with I1 > 0) 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 ). ITYP = 2, 5 are used for first-order Herman-Wallis corrections. ITYP = 3, 4, 6, 11, 12 are used for second-order Herman-Wallis corrections.
</alert>

===== Format of the ''cat'' File =====

**[F13.4, 2F8.4, I2, F10.4, I3, I7, I4, 12I2]:** FREQ, ERR, LGINT, DR, ELO, GUP, TAG, QNFMT, QN

> FREQ = Frequency of the line
> ERR = Estimated or experimental error (999.9999 indicates error is larger)
> LGINT = Base 10 logarithm of the integrated intensity in units of nm<sup>2</sup> MHz
> DR = Degrees of freedom in the rotational partition function (0 for atoms, 2 for linear molecules, and 3 for nonlinear molecules)\\
> ELO = Lower state energy in cm<sup>–1</sup>
> GUP = Upper state degeneracy
> TAG = Species tag or molecular identifier. A negative value flags that the line frequency has been measured in the laboratory. The absolute value of TAG is then the species tag (as given in line 2 of file.int above) and ERR is the reported experimental error.\\
> QNFMT = Identifies the format of the quantum numbers given in the field QN.
> QN(12) = Quantum numbers coded according to QNFMT. Upper state quanta start in character 1. Lower state quanta start in character 14. Unused quanta are blank, quanta whose magnitude is larger than 99 or smaller than –9 are shown with alphabetic characters or %%**%%. Quanta between –10 and –19 are shown as a0 through a9. Similarly, –20 is b0, etc., up to –259, which is shown as z9. Quanta between 100 and 109 are shown as A0 through A9. Similarly, 110 is B0, etc., up to 359, which is shown as Z9.

===== Format of the ''str'' File =====

**[F15.4, E15.6, I5, 1X, 24A, I5]:** FREQ, DIPOLE, QNFMT, QN, ITEM

> FREQ = Frequency of the line
> DIPOLE = Reduced matrix element of the transition dipole
> QNFMT = Identifies the format of the quantum numbers given in the field QN.
> QN(12) = Quantum numbers coded according to QNFMT. Upper state quanta start in character 1. Lower state quanta start in character 14. Unused quanta are blank, quanta whose magnitude is larger than 99 or smaller than –9 are shown with alphabetic characters or %%**%%. Quanta between –10 and –19 are shown as a0 through a9. Similarly, –20 is b0, etc., up to –259, which is shown as z9. Quanta between 100 and 109 are shown as A0 through A9. Similarly, 110 is B0, etc., up to 359, which is shown as Z9.\\
> ITEM = identifies number of dipole

===== Format of the ''egy'' File =====

**energy output [2I5, 3F18.6, 6I3]:** IBLK, INDX, EGY, PMIX, ERR, QN

> IBLK = Internal Hamiltonian block number
> INDX = Internal index Hamiltonian block
> EGY = Energy in cm<sup>–1</sup>
> ERR = Expected error of the energy in cm<sup>–1</sup>
> PMIX = mixing coefficient
> QN(6) = Quantum numbers for the state

====== 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.  The operator N<sub>a</sub> in the asymmetric rotor becomes lambda for the linear molecule. N is the sum of rotational and electronic orbital angular momenta. For linear molecules, it is convenient (but not essential) to think of the angular momentum along the bond as being purely electronic in nature. 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 two distinct symmetries: S·f<sub>a</sub> connects states of the same lambda, while S·f<sub>b</sub> and S·f<sub>c</sub> conect states where lambda differs by one. For S·f<sub>b</sub> or S·f<sub>c</sub> , the L<sub>b</sub> or L<sub>c</sub> operator is implicitly included in the parameter. When the spin orbit operator connects different spin multiplicity, the reduced matrix value of <S||**S**||S'> is set to unity.

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, the vibronic wave function should be chosen so that it is symmetric with respect to the //ab// plane. Then the //b// axis can be used for the inversion defining axis (i.e. IAX = 2 in the option lines of the .par and .var files can be used to define selection rules under inversion).  With this choice, the symmetry of rotation lines in the D<sub>2</sub> group are:

|A   |even N for S and all N for all other even l (even parity l doublet)|
|B(a)|odd N for S and all N for all other even l (odd parity l doublet)  |
|B(b)|all N for all odd l (even parity l doublet)                        |
|B(c)|all N for all odd l (odd parity l doublet)                         |

For S<sup>+</sup> states, the parity is odd for odd N, while for S<sup>-</sup> states the parity is odd for even N. This means that the Hamiltonian can couple S<sup>+</sup> with S<sup>–</sup> via an operator of  B(a) symmetry or B(c) symmetry. An example is an operator like 10200001, which is the S·f<sub>a</sub> spin orbit interaction operator between state v = 0 and v = 1.  For normal coupling not involving S<sup>-</sup> states (or for coupling between S<sup>-</sup> states) the operators should have A or B(b) symmetry.  Similarly, electric dipole transitions with  Dl even should have B(a) symmetry, and transitions with  Dl odd should have B(c) symmetry so that the parity changes sign with the transition. Magnetic dipole transitions should follow the Hamiltonian symmetry.

The g, u symmetry for an electronic state is for the parity of the wave-function 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 A and  B(b) states, while WTMN will be the weight for the other two symmetries. For S<sup>+</sup><sub>g</sub> S<sup>-</sup><sub>u</sub> and g states with other l, WTPL is the weight for even permutations, while for S<sup>-</sup><sub>g</sub> S<sup>+</sup><sub>u</sub> and u states with other l, WTPL is the weight for odd permutations. For example, in oxygen, S<sup>+</sup><sub>g</sub> and D<sub>g</sub> have WTPL = 1 and WTMN = 0, while S<sup>-</sup><sub>g</sub> and D<sub>u</sub> have 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 S<sup>-</sup><sub>g</sub>D electric dipole code of 21vv'0 and a magnetic dipole code of 11vv'1. Electric dipole transitions between S<sup>+</sup> and S<sup>-</sup> will use 11vv'0, while magnetic transitions will use 1vv'1. For transitions between S<sup>+</sup> and S<sup>+</sup> the roles of these operators are reversed. Note that for S S transitions, 11vv'0 has selection rules of DN = –2, 0, +2, while 1vv'1 has selection rules of DN = –1, +1.

The correlation between parity and e,f designations follow the recommendations of J. M. Brown //et al.//, //J. Mol. Spectrosc.// **55,** 500 (1975).

| |odd spin multiplicity   |even spin multiplicity|
|e|p = (–1)<sup>J–1/2</sup>|p = (–1)<sup>J+1</sup>|
|f|p = (–1)<sup>J+1/2</sup>|p = (–1)<sup>J </sup> |

An 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%%''

An 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%%''

The quantum number correlations between Hund's case (b) and case (a) can be a bit confusing at first. For example in a doublet P state N=J-1/2 always correlates with W =3/2 and N=J+1/2 always correlates with W =1/2 on the basis of projection. For A < 0, e.g. OH, the projection-based correlation follows the energy ordering.  For A>0, the lower energy state is N=J+1/2 and W =3/2 as long as J+1/2 < sqrt(A/2B). Above this J,  N = J+1/2 and W =1/2 (based on projection) is higher in energy than and N=J-1/2 and W = 3/2.  Therefore quantum number assignments based on projections lead to different quanta than those based on energy.  For a triplet S state, N=J+1 correlates with S =0 based on projection, N=J correlates with an odd combination of S =1 and S =-1, and N=J-1 correlates with an even combination of S =1 and S =-1.

Since q multiplies the same operator as (B-C) / 2, it is possible to use the sign of q to determine whether there are more electrons in the ab plane (q > 0) or whether there are more electrons in the ac plane (q < 0).

Explicit approximate relationships for the parameters are:

|100100vv' |A                  |
|100101vv' |2 A<sub>J</sub>    |
|1vv'      |B                  |
|100400vv' |–p/2               |
|400vv'    |q/2                |
|200100vv' |a                  |
|1200100vv'|c                  |
|1200000vv'|b + c/3            |
|1200400vv'|–d/2               |
|2200100vv'|1.5eQq<sub>1</sub> |
|2200400vv'|–eQq<sub>2</sub>/4 |
|1100100vv'|4 l S (2S–1)       |

The extra factors of S in the definition of the spin-spin interaction parameter l,  i. e. a spin-spin interaction  2 l ( S<sub>z</sub><sup>2</sup> – S <sup>2</sup> /  3), is a correction for the special normalization assumed for eQq.

====== Special  Considerations for 'l'-doubled States ======

The  //l//-doubled states must be specified in adjacent pairs. The EWT1 = 1 states are those with //K l// > 0, and EWT1 = 2 states are those with //K  l// <= 0. The sign of //K// represents the parity, as in the non //l//-doubled states. Operators should be only specified between vibrational states with EWT1 = (0,0), (0,1), (1,0), (1,1), (1,2), and (2,1). Operators between vibrational states with EWT1 = (0,2), (2,0), and (2,2) are ignored. Operators connecting vibrational states with different //'l'// obey the selection rule that '//K-l//' can only change by multiples of 3. Operators diagonal in //l// have no '//K-l//' selection rules. If EWT1 = 1 for both states and if the parameter would normally be implicitly imaginary (i.e. operators odd-order in angular momentum for the Hamiltonian, or even-order for the dipole moment), then the parameter is assumed to be real and the rotational operator is multiplied by the sign of '//l//<sub>z</sub>'. DIAG = 0 is not recommended on the first option line in the //par// file, since the first-order energy is not likely to ordered with //K.//

The //K// quantum numbers for  //l//-doubled states are designated specially when asymmetric rotor quanta are used so that the lower //K// doublet is associated with the EWT1 = 1 state and the upper //K// doublet and //K// = 0 states are assiciated with EWT1 = 2.  In this way the degenerate states have the same quantum numbers.

=====  Simple Examples =====

Example of parameter types for asymmetric rotors (assuming < 10 vibronic states):

|11       |energy for v = 1                                                     |
|01       |first order Fermi (F<sub>0</sub>) interaction between v = 0 and v = 1|
|10000    |A<sub>00</sub>                                                       |
|10099    |A (for all vibrational states)                                       |
|20099    |B (dito)                                                             |
|30099    |C (dito)                                                             |
|40099    |0.25*(B – C)  (if prolate basis selected)                            |
|299      |–D<sub>J</sub>                                                       |
|1199     |–D<sub>JK</sub>                                                      |
|2000     |–D<sub>K</sub> for v = 0                                             |
|600001   |i N<sub>c</sub> interaction between v = 0 and v = 1                  |
|20000099 |N·I for second spin                                                  |
|120010099|S<sub>a</sub> I<sub>a</sub>                                          |
|220010099|1.5*c<sub>zz</sub> for second spin                                   |
|220040099|0.25*(c<sub>xx</sub>–c<sub>yy</sub>) for second spin                 |

Quadrupole and magnetic spin-spin interactions are defined to be traceless (i.e. c<sub>xx</sub> + c<sub>yy</sub> + c<sub>zz</sub> = 0 or T<sub>xx</sub> + T<sub>yy</sub> + T<sub>zz</sub> = 0). Therefore, all three components cannot be fit simultaneously. The most efficient choice of parameters is shown in the table below. In cases where the user wants an alternative, it is possible to use constrained parameters. For example, to fit c<sub>aa</sub> and c<sub>cc</sub> (with no multipliers):

''%% 220010099   100.%%''\\
''%%–220020099  –100.%%''\\
''%% 220030099    50.%%''\\
''%%–220020099   –50.%%''

specifies c<sub>aa</sub> = 100, c<sub>cc</sub> = 50, and c<sub>bb</sub> = –150.

====== Installation Instructions ======

The Makefile shows how the various files are to be linked. The programs have been tested with Microsoft Visual
C++ compiler and the gnu gcc compiler (which is freely available for unix and windows platforms).
The programs should work without modification with any ANSI compliant 'c' compiler on any size computer.
All arrays are allocated dynamically, and addressing or memory limits will place a practical limit on the size
of matrices that can be used.  For 16-bit computers the address limit is equivalent to a 90 X 90 double precision
matrix, while for a 32-bit computer the adressing limit is 23170 X 23170.
The program has been used on a 64-bit DEC alpha computer where the adressing limit is correspondingly larger.
For both 32-bit and 64-bit computers, a more significant practical limit is usually given by the amount of
memory or the amount of disk space available for virtual memory.

The identity of the files are:

  * calfit.c, calcat.c, and calmrg.c are the main programs.
  * subfit.c is supplementary to calfit.
  * ulib.c, blas.c, and cnjj.c are generic libraries.
  * calpgm.h, cnjj.h, and blas.h are required header files.
  * slibgcc.c contains system dependent fuctions.
  * spinv.c contains functions for spins and multiple vibrations. The executables using this library and calfit or calcat are called SPFIT and SPCAT respectively.
  * dpi.c  is contains functions for doublet pi with a nuclear spin. The executables using this library and calfit or calcat are called DPFIT and DPCAT respectively.
  * *.nam are parameter name files for function getlbl in subfit. They are only used to label the output from calfit. The first default directory is the current directory. The second default directory is given in an environment variable named SPECNAME. Under Unix put a line like 'setenv SPECNAME /home/myname/' in one of your initialization files (e.g. .cshrc).
  * blas.c contains needed LINPACK double precision Basic Linear Algebra Subroutines (these may be available on some  systems in a machine coded and/or vector processor form).
  * Makefile is the make file for the gcc compilation.
  * spinv.html is the specific documentation for the SPFIT and SPCAT and dpi.html is the specific documentation for the DPFIT and DPCAT.