general

This is an old revision of the document!


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

H. M. Pickett, "The Fitting and Prediction of Vibration-Rotation Spectra with Spin Interactions," J. Mol. Spectros. 148, 371-377 (1991).

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.

Qmod5 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 Itot.
Add 40 if aggregate spin number n is used because the number of quantum numbers needed otherwise exceeds 6.

Note: These "corrections" to Q can be used simultaneously. For example, it can be 43 for NH2
(see lase entry in table below) or 63 if the two hydrogen nuclei are coupled to Itot before they are coupled to J.

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 + I1 = F1,…, Fn-1 + In = F, but an alternative that can be selected is the scheme …, In-1 + In = Itot, Fn-2 + Itot = 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.

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-1
  • ERR = experimental error.
NOTE: 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.
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.

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.

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)

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 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.
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 Ir representation (z = a, x = b, y = c), usually used for prolate rotors; negative means IIIl 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 F1 ,etc. [default = 0 includes all interactions] (Ignored on all but first option line.)
sign IAX : If negative, use Itot 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

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, Ka + Kc = N+1. For asymmetric top quanta with l = –1, Ka + Kc = 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).)
 

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

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.
  • general.1570193997.txt.gz
  • Last modified: 2019/10/04 14:59
  • by admin