DOCUMENTATION for SPFIT and SPCAT

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 H. M. Pickett, "The Fitting and Prediction of Vibration-Rotation Spectra with Spin Interactions," J. Mol. Spectros. 148, 371-377 (1991).

CONTENTS

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

In most cases, the spin coupling scheme is N + S = J, J + I₁ = F₁, …, F_n-1 + I_n = F, but an alternative that can be selected is the scheme …, I_n-1 + I_n = I_tot, F_n-2 + I_tot = 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.

The field QNFMT in 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 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.

 TOP

FORMAT of the lin file:

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^–1

ERR = experimental error. Minus sign means that the frequency and error are in units of cm^–1. FREQ and ERR will be converted internally to units of MHz.

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.
 

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.

 TOP

FORMAT of the par file 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 CALCAT)

ERRTST has to be sufficiently large to use new lines in the fit. It may be reduced if lines outside ERRTST s should be excluded from the fit.

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.

Parameter lines: IDPAR, PAR, ERPAR / LABEL

where IDPAR is a parameter identifier, PAR is the parameter value,  ERPAR 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
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

• NFF = Fourier flag (used for internal rotation) If NFF < 11, basic operator is multiplied by cos (NFF * 2p K_avgr / 3) else operator multiplied by sin((NFF-10)* 2p K_avgr / 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_zN_z operator
• TYP = projection type

• 0 = scalar
• 1 = N_aN_a
• 2 = N_bN_b
• 3 = N_cN_c
• 3+n = N₊²ⁿ + N_–²ⁿ , n = 1 .. 9 (L = 2n, DK = 2n)
• 11+n = "x" symmetry, n = 1 .. 8 (L = 2n + 1, DK = 2n)
• 20+n = off-diagonal "a" symmetry, n = 0 .. 19 (for prolate basis: L = n + 1, DK = 0, 2, 2, 4, 4..)
• 20 = N_a
• 21 = N_b N_c + N_c N_b
• 40+n = off-diagonal "b" symmetry, n = 0 .. 19 (L = n + 1, DK = 1, 1, 3, 3 ..)
• 40 = N_b
• 41 = N_a N_c + N_c N_a
• 60+n = off-diagonal "c" symmetry, n = 0 .. 19 (for prolate basis: L = n + 1, DK = 1, 1, 3, 3 ..)
• 60 = N_c
• 61 = N_a N_b + N_b N_a
• 80+n = unique contribution for K' = K" = n*10+KSQ
• 90+2n = Euler series multiplying N₊²ⁿ + N_–²ⁿ
• 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_z²
• 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.

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.

NOTES:

1. Direction cosines have been omitted.
2. N₊ = N_x+ i N_y . 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_z operator (see below).
3. 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_avgr / 3) instead of cos (4p K_avgr / 3).  If the magnitude of  r is not the same for the two states, replace K_avgr with (K₁r₁ +K₂r₂) / 2.
4. Prolate basis is I r, and oblate basis is III l. DK behavior for TYP = 20+n and 60+n re reversed for oblate basis.
5. r_v,v is specified by 9100vv. TYP=91+2n parameters, including r, are constants and are not fitted.
6. For operators with I2 = 0 and I1 > 0, one value of N is replaced with the appropriate projection of I_I1. 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_zN_z operator, 10010000 is the N_zS_z operator, and 120010000 is the S_zI_z - S.I / 3 operator.
7. For operators with I2 = I1 > 0, spin corrections appropriate for nuclear quadrupole coupling are applied: SQRT((2I+1)/(2I-1))/4I.
8. Whenever operators that do not commute are combined, the resulting operator is half the anti-commutator. The order of application is N_zS_z, followed by N_z², followed by N² and N· S.
9. 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.

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

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.

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 CALFIT, 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.

  TOP

FORMAT for the int file:

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

FLAGS = IRFLG*1000+OUTFLG*100+STRFLG*10+EGYFLG

line 3-end [freeform]: IDIP,DIPOLE
 

IDIP = dipole identifier (see DPI.DOC,SPINV.DOC)

DIPOLE = dipole value

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)**2. Both STR0 and STR1 default to -100.

IDIP is coded in decimal digit form according to the format (for NVIB < 10):
(((TYP*10 + I1)*10 + V2)*10 + V1)*10 + SYM, or (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]

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_avgr / 3) instead of cos (4p K_avgr / 3).  If the magnitude of  r is not the same for the two states, replace K_avgr with (K₁r₁ +K₂r₂) / 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.
 

TOP

FORMAT of cat output 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² 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^–1

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 str output file:

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 egy output file:

IBLK = Internal Hamiltonian block number

INDX = Internal index Hamiltonian block

EGY = Energy in cm^–1

ERR = Expected error of the energy in cm^–1

PMIX = mixing coefficient

QN(6)= Quantum numbers for the state

SPECIAL CONSIDERATIONS FOR LINEAR MOLECULES

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 slection rules under inversion). Generally, the unfilled p orbitals will then be oriented in the c direction. With this choice, the symmetry of rotation lines in the D_2h group are:
 
 

Ag	even N for S+ and all N for all other even l (even parity l doublet)
Au	even N for S-
B(a)u	odd N for S+ and all N for all other even l (odd parity l doublet)
B(a)g	odd N for S-
B(b)g	for odd l (even parity l doublet)
B(c)u	for odd l (odd parity l doublet)

This means that the Hamiltonian, as well as magnetic dipoles, can couple S⁺ with S^- via an operator of B(a) symmetry. An example is an operator like 10200001, which is the S·f spin orbit interaction operator between state v = 0 and v = 1. Similarly, interactions between S^- and P states have B(c) symmetry and all other such interactions between S⁺ and P states and between P and D have B(b) symmetry. Electric dipole transitions between S^- and P states have B(b) symmetry, while all other D l = 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 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_g, A_u, B(b)_g, and B(b)_u states, while WTMN will be the weight for the others. For S⁺_gS^-_u and g states with other l, WTPL is the weight for even permutations, while for S^-_gS⁺_g and u states with other l, WTPL is the weight for odd permutations. For example, in oxygen, S⁺_g and D_g have WTPL=1 and WTMN=0, while S^-_g and D_g 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^-_gD electric dipole code of 21vv'0 and a magnetic dipole code of 11vv'1. Electric dipole transitions between S⁺ and S^- will use 11vv'0, while magnetic transitions will use 1vv'1. For transitions between S⁺ and S⁺ 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.

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

The quantum number correlations between Hund's case (b) and case (a) can be a bit confusing at first. For A < 0 in a doublet P state, e.g. OH, N=J-1/2 always correlates with W =3/2 and N=J+1/2 always correlates with W =1/2. The same correlation is present for A>0 as long as J+1/2 < sqrt(A/2B). Above this J, N = J-1/2 correlates with W =1/2 and N=J+1/2 correlates with W =3/2. Since the unpaired p orbital is assumed to lie along the c axis, parameters representing p, d, and eQq₂ will have opposite sign to what is expected for the usual case (a) parameters. Explicit approximate relationships are:
 
 

100100vv'	A
100101vv'	2 AJ
1vv'	B
100400vv'	-p / 2
400vv'	q / 2
200100vv'	a
1200100vv'	c
1200000vv'	b + c / 3
1200400vv'	-d / 2
2200100vv'	1.5 eQq1
2200400vv'	-eQq2/4

TOP

SPECIAL CONSIDERATIONS FOR l-doubled STATES:

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.

TOP

 SIMPLE EXAMPLES:

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

11	energy for v=1
10000	A00
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	-DK00
600001	i Nc interaction between v=0 and v=1
20000099	N·I for second spin
120010099	Sa Ia
220010099	1.5 * quadrupole moment czz for second spin
220040099	quadrupole moment 0.25*(cxx-cyy) for second spin

TOP

Installation Instructions:

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 windows, put a line like  'set SPECNAME=c:\spectra\' in autoexec.bat.  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.