Line List Input File Format

PGOPHER accepts a wide variety of formats for files used for line position or intensity fitting, or for plots of energy levels derived from experiment. The files are text files, and can include directives to control defaults. The file name is not normally important, though .lin or .obs is conventionally used for these files. (.cat, .mrg and .par have a special interpretation - see JPL catalog and SPFIT below). The simplest way of generating line lists for fitting is as described in line position fitting.

Standard PGOPHER format (.lin, .obs)

The standard format is a line for each observation, interspersed by directives that set defaults, allow other files to be included and other functions - see below for a full list. In principle, each line consists of a 11 items separated by spaces or tabs and a comment but, depending on the Mixture and other settings many of these are optional, and the comment can also be used to specify the transition. The text generated in the Line List Window or from File, Export, Line List is compatible with this format, though the "Weight" column will need setting. The items are:

Molecule	The Molecule; can be omitted if there is only one molecule or the molecule directive is used.
M'	The upper state Manifold; can be omitted if there is only one or two manifolds or the uppermanifold directive is used.
J'	Upper state total angular momentum (i.e. normally J, but F if hyperfine structure is included).
S'	Symmetry of upper state. This can be a symmetry number (starting from 0) or name. The symmetry names understood depend on the molecule type, but include "+", "-" "e" and "f" for linear molecules. -1 in this field indicates that the symmetry should be worked out from the text field at the end of the line.
#'	Eigenvalue number for upper state. This indicates the rank of the upper energy level in the list levels of the same J and symmetry for the upper manifold (numbered staring from 1). 0 in this field indicates the number should be worked out from the text field at the end of the line.
M''	The lower state Manifold; can be omitted if there is only one or two manifolds or the lowermanifold directive is used. Note that this is also allowed directly after the upper state manifold.
J''	Lower state total angular momentum (i.e. normally J', but F" if hyperfine structure is included).
S''	Symmetry of lower state. This can be a symmetry number (starting from 0) or name. The symmetry names understood depend on the molecule type, but include "+", "-" "e" and "f" for linear molecules. -1 in this field indicates that the symmetry should be worked out from the text field at the end of the line.
#''	Eigenvalue number for lower state. This indicates the rank of the lower energy level in the list levels of the same J and symmetry for the lower manifold (numbered staring from 1). 0 in this field indicates the number should be worked out from the text field at the end of the line.
Frequency	The frequency of the transition or (for line intensity fits) the intensity. The units are taken as set by PlotUnits of the Mixture, unless the units directive is used.
Weight	The weight to assign to this observation in the fit. The value should be proportional to the standard deviation of the measurement. A negative or zero value or a single "-" character will cause the line to be ignored.
(rest of line)	If the eigenvalue numbers given above are >= 1, then the rest of line is taken as a comment. If either or both eigenvalue numbers are 0, then the comment should contain a string of the form: : upper state quantum numbers - lower state quantum numbers where the quantum numbers are in the format output by PGOPHER in line listings, and thus depend on the molecule type. The eigenvalue number will be worked out from this field.

Energy Level Fits

To force a fit to energy levels, rather than transitions, replace J S and # for the unwanted state with "-" and leave the manifold field blank. (This style of fit can also be selected for a complete file from the Log Window.)

Branch Format

A "branch" style label for a transition can also be used, by replacing all the upper and lower state quantum numbers with a branch label such as P(2). The format should match that output by PGOPHER in the Line List Window for the given molecule type. The branch label should not contain spaces. If the transition is a Raman transition, or multiphoton transition of even rank, add a branchrank 0 directive. For example, a simple linear molecule input file could look like:

    P(2)    996.0000 1.0 
    P(1)    998.0000 1.0
    R(0)   1002.0000 1.0
    R(1)   1004.0000 1.0
    R(2)   1006.0000 1.0

Branch Table

A branch table can also be given, in the compact form often found in papers. This is started by the branchtable directive, and a typical sample is (this is for a ³Σ - ³Σ transition in SO):

QuantumNumberFormat J

BranchTable P11 P22     P33     R11     R22     R33
8       -       -       -       -       -       -
9       -       47126.7 47123.0 -       -       -
10      -       47120.9 47116.3 -       -       -
11      47123.0 47114.2 47108.9 -       -       47131.0
12      47116.3 47106.1 47101.0 -       47128.7 47124.9
13      47108.9 47099.5 47092.6 47131.0 47123.0 47118.0

Notes:

The branchtable directive is followed by a list of branches, with the (J) section omitted.
Each following line has the lower state total angular momentum as the first item on the line.
The observed frequencies (or intensities for an intensity fit) follow on the same line, with "-" used to indicate excluded values.
The number of observations on each line must be less than or equal to the number of branches following the branchtable directive.
All the observations will have weight 1, unless overridden with overrideweight or scaleweights.
To end the table, give a branchtable directive with no branches following

Parameters as input values

To constrain fits, it may be helpful to include expected parameter values as "observed" values in fits. To do this the basic format is:

Parameter <Molecule> <Manifold> <State> <Parameter> = <Value> <Weight>

The <Molecule>, <Manifold> and <Weight> entries are optional, as for normal line lists, though an appropriate value for the weight is normally essential in this case.

Constraints

Constraints on parameters be expressed symbolically, with a format in general

Constrain <parameter> := <expression>

where <expression> is an arbitrary expression in terms of other <parameter> names. In the simplest cases the parameters are specified using

<object>.<parameter>

though in most cases the names of the containing <object>'s will also be required on front to avoid ambiguity. A typical example might look like

Constrain A.v=0.B := X.v=0.B

which would force two B values to be the same. The constraints are applied when the constraints are first read, and then at every appropriate stage of the fitting process.

Samples

The following are all equivalent ways of specifying the same transition. The default linear molecule has been taken for this example.

All fields given:

LinearMolecule Excited  6  1  1 Ground  4  0  1    1006.0000 1.0   .005      0 :    R( 4) : Excited v=1  6 e - Ground v=0  4 e

Only the essential fields:

                        6  1  1         4  0  1    1006.0000 1.0

The spaces are not required either:

 6 1 1 4 0 1 1006.0000 1.0

Alternatively, the eigenvalue numbers can be set to 0, in which case the "Excited v=1 6 e - Ground v=0 4 e" string will be used to work out the quantum numbers.

LinearMolecule Excited  6  1  0 Ground  4  0  0    1006.0000 1.0   .005      0 :    R( 4) : Excited v=1  6 e - Ground v=0  4 e

Finally, in branch format:

R(4) 1006.0000 1.0

Directives valid in any file

The following directives can be put on any line in a file; the line should start with the directive. The effect will normally apply to all lines after the directive, and to any files included after the directive.

stop (or end or -1)

Stop reading from current file

/ or # or ;

Lines starting with / # or ; are treated as comments and ignored

include filename

Read contents of filename (and then continue reading current file). A blank filename causes the current state to be saved, but reading continues normally. A stop or end will causes the state to be reset, giving the effect of an included file within one file.

includeoldpgopher filename

Include file in old PGOPHER format.

molecule molecule

Set the default molecule to molecule. (If there is only one molecule in the mixture, the default will be initialized to this anyway.)

uppermanifold manifold

Set the default upper manifold to manifold. For this to work a default molecule must be set. If there are only one or two manifolds present in the default molecule, this will be initialized to the state with Initial false or the higher energy manifold.

lowermanifold manifold

Set the default lower manifold to manifold. For this to work a default molecule must be set. If there are only one or two manifolds present in the default molecule, this will be initialized to the state with Initial true or the lower energy manifold.

upperstate name

Set default upper state to name.

lowerstate name

Set default lower state to name.

symmetry name

Set default symmetry to name. This may be required for cases (such as symmetric tops) where two choose between two otherwise degenerate transitions when using branch format.

overrideweight value

Force the weight of the following observations to value. Leave value blank to leave the weights unchanged.

scaleweights value

Multiply the weights of the following observations by value. Leave value blank to leave the weights unchanged.

frequencyoffset value

Add value to the position of the following observations. Leave value blank to reset the offset to zero.

offsetfrequencyoffset value

Add value to the frequency offset of the following observations. Leave value blank to reset the offset to zero.

frequencyscale value

Multiply the position of the following observations by value. Leave blank to reset the scale to 1.

units units

Set the units of the following observations. Unless this is set, the units are assumed to be the same as the PlotUnits of the Mixture. If it is set, the appropriate conversion will be performed.

efield value
bfield value
angle value

Set the External Field for the following observations. Unless one or more of these are set, the fields are taken from the Simulation settings in the Mixture.

indexoffsets ...

Offset the eigenvalue numbers of the following observations. See Adjusting Eigenvalue Numbers below.

upperindexoffsets ...

As for indexoffsets, but applied to the upper state only.

lowerindexoffsets ...

As for indexoffsets, but applied to the lower state only.

select condition

Add an additional condition to including observations in the fit. See Selecting Observations below.

removespins n

Discard the n outermost spins from the calculations from the following observations. This works backwards down the list S, I₁, I₂, ...

colour name

(or color name). Mark the following observations with colour name. Leave name blank to leave the colour unset. See Determining Colours and J ranges for the possible colours.

quantumnumberformat f

Set the format for quantum numbers as follows:

f	Number read is	Number must be
2J	2 * quantum number	Integer
J	quantum number	Integer or half integer written as n/2 or n.5
J+1/2	quantum number + ½	Integer
J-1/2	quantum number - ½	Integer

The default is J or 2J, depending on the DoubleQnos setting in Mixture.

regeneratelabels no|yes

State labels displayed at end of line are calculated as they are fit, rather than using the strings read from the file.

nameoverride name

Override displayed filename for following observations

pgopherversion version

Set the PGOPHER version the line list file was created for. This allows for changes in the input format in later versions of the program. Currently it only affects asymmetric top line lists, where the definition of the numbers defining rovibronic symmetry changed between version 5.1 and 5.2 as described here. The version string is of the form 5.1 or 5.1.144.

branchrank rank

Specify the type of the transition to assume when specifying branches. Leave rank blank for the default, (one photon) electric dipole transitions; specify rank = 0 for Raman or two photon transitions.

Adjusting Eigenvalue Numbers

One of the key fields in identifying states is the eigenvalue number, where all the energy levels of a given total angular momentum and symmetry are ranked in order of increasing energy starting from 1. While this uniquely identifies energy levels, it will change if states are added to a manifold, and the desired state can also change as constants are changed. One approach to both these problems is to use the state description to work out the eigenvalue number for each case - see the discussion at the end of the "Standard PGOPHER format" above for more on this. An alternative method, which only works for the first case is to shift the eigenvalue numbers with the indexoffsets, upperindexoffsets and lowerindexoffsets directives. The basic forms are

indexoffsets	Clear any offsets.
indexoffsets search	Use the transition comment at the end of the line to determine the eigenvalue number.
indexoffsets searchall	Use the transition comment at the end of the line to determine the eigenvalue number and symmetry.
indexoffsets n1 n2 n3 ....	Add to the eigenvalue number, as described below.

The last line needs additional explanation. If a single number is given, then that number is added to all following eigenvalue numbers. This is normally too simple, as the number of states often depends on the symmetry. (For example, a ¹Σ⁺ state only has e parity levels.) To get round this problem, specify a separate number for each symmetry as in:
indexoffsets 3 4
which would add 3 to levels with symmetry number 0 and 4 to levels with symmetry number 1. J adjusted symmetries are used (if JAdjustSym is set in Mixture), so for linear molecules this corresponds to e and f levels. As a further complication, the required offset can depend on J (a ²Π state has only one J = ½ state but two levels of every other J). For this reason the sets of numbers, one for each symmetry, can be repeated as often as required. The first set are for J = 0 or ½, the second set for J = 1 or 3/2, and so on. The last set is taken for all higher J. For example, to take account of inserting a ²Π state below the state of interest the line:
indexoffsets 1 1 2 2
would be appropriate, as a linear molecule has only two symmetries.

Selecting Observations

To include just some observations from a line list, add a directive such as:
select J' < 20
which will only take observations after the directive with upper state J < 20. Note that, in contrast to most other areas, quantum numbers are never doubled. (This is because the expression can be very general and involve several quantities so it is not possible to distinguish quantum numbers from other values.) Multiple select directives can be given, and all must be satisfied. To clear all the directives use a select with no expression. The variables currently understood are:

Frequency	Frequency of observation (or intensity for intensity fits)
Weight	The weight of the observation
J' J"	Upper and lower state total angular momentum. (Note that the quantum numbers are never doubled)
Sym' Sym"	Upper and lower state symmetry number
Index', Index"	Upper and lower state index

JPL Line Catalog Files (.par, .mrg)

PGOPHER can read many JPL line catalog files as used by Herb Pickett's CALPGM/SPCAT/SPECFIT and defined in:

H.M. Pickett, R.L.Poynter, E.A. Cohen, M.L. Delitsky, J.C. Pearson and H.S.P. Muller J. Quant. Spectrosc. Radiat. Transfer 60, 883 (1998)

See also http://spec.jpl.nasa.gov/

Not every format is currently implemented. For the more complicated systems directives such as defaultmanifold may be required. A few specific directives apply to this type of file:

takeall	Include both experimental and calculated lines.
takeobs	Include only experimental lines.
takecalc	Include only calculated lines.
mapupper n1 n2	Provide a mapping of state numbers from the .par file to PGOPHER numbers. This is required as Pickett's programs treat some types of states (such as degenerate states in symmetric tops) as pairs, while PGOPHER treats then as a single state. n1 is the number in the .par file and n2 is the PGOPHER number. Repeat the directive for every state number that requires changing. n2 values are taken mod 1000; values >= 1000 indicate an alternate kl assignment.
maplower n1 n2	As for mapupper, but for the lower state.