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 HITRAN, JPL catalog and SPFIT below). The simplest way of generating line lists for fitting from spectra is as described in line position fitting. If you want to use published line lists the various alternative formats may be easier to use.

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 "Std Dev" column will need setting as the default in calculated linelists is "-" (excluding the line from the fit). 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.
Std Dev	The relative standard deviation of the observation, used to derive the weight of the observation in the least squares fit. Only the relative values are important, and typically 1 will be used for the most accurate values, with larger values (perhaps 3 or 10) for blended or weak transitions. 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 and the symmetries are not -1, then the rest of line is taken as a comment. If either or both eigenvalue numbers are 0, or symmetries 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 and or symmetry 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.)

Samples

The following are all equivalent ways of specifying the same transition, showing how fields can be omitted. 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

With 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

In addition, the symmetries can be set to -1, in which case the "Excited v=1 6 e - Ground v=0 4 e" string will also be used to work out the quantum numbers:

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

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> <Std Dev>

The <Molecule>, <Manifold> and <Std Dev> entries are optional, similar to normal line lists, though an appropriate value for the (relative) standard deviation is normally essential in this case. Also, if any of the <Molecule>, <Manifold> or <State> names are the same, both names must be given.

A general expression involving parameters can also be given; the format is

Expression <expression> = <Value> <Std Dev>

The <Std Dev> entry is optional; the = sign with a space either size marks the end of the expression. The expression can involve any parameter; these are typically specified using

<object>.<parameter>

though <object> can be omitted for the parameters in the default state or manifold, and additional <object>. prefixes can be added to avoid ambiguity.

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. To find the name of a parameter, right click on it in the constants window and select "Show Full Name". The name is also copied to the clipboard.

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. Note that if the parameter name contains special characters (< or >, for example) then quotes might be needed round the parameter name, as for example:

Constrain NH3.NH3.s.<0+|J+-^6|0+>.Value := "NH3.NH3.s.<0-|J+-^6|0->.Value"

Additional dummy parameters can be added using a "Variables" object.

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; # and ; can also be used elsewhere in a line.

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. In the standard format the eigenvalue number is taken as within the specified state only, and the state label is worked out and then used to find the eigenvalue number subsequently. For the alternative formats listed below it allows the state to be specified where there is more than one in a manifold.

lowerstate name

Set default lower state to name. In the standard format the eigenvalue number is taken as within the specified state only, and the state label is worked out and then used to find the eigenvalue number subsequently. For the alternative formats listed below it allows the state to be specified where there is more than one in a manifold.

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.

overridestddev value
or
overrideweight value

Force the (relative) standard deviation of the following observations to value. Leave value blank to leave the standard deviations unchanged.

scalestddev value
or
scaleweights value

Multiply the (relative) standard deviation of the following observations by value. Leave value blank to leave the (relative) standard deviations unchanged.

stddev% x
or
weight% x

Set the (relative) standard deviation of the following observations to the observed value times x/100. Most useful for intensity fitting. Leave x blank to switch off this behaviour. Note that overridestddev and scalestddev are applied after this calculation.

takeall

Include all lines, regardless of the sign of their standard deviation. Standard deviations of zero are forced to -1.

takeobs

Include only lines with standard deviations > 0, the default.

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₂, ..., so nuclear spins are discarded first. Omit n to revert to using all spins. Note that n adds to the current number of spins discarded.

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 normally J, though can be set to 2J, with 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.

correlation value offset

Set the correlation coefficient between the previous observation and the observation at offset from it. If offset is omitted, it defaults to -1, which sets the correlation coefficient between the previous two observations.

linenumber n filename

Set the effective line number and file name of the next line in the file. This is used internally, and may also be useful for files generated from other sources.

Observation types

The following directives change the type of the observations following the directive; see also CDlower and CDupper.

line	Following observations are line positions
intensity	Following observations are line intensities
Elower	Following observations are lower state energies
Eupper	Following observations are upper state energies

Combination Differences

Observations containing an upper or lower level in common can be combined into a single observation corresponding to the difference in energy between the two levels in the other state. Fitting in this way can be helpful if one of the states is perturbed or unassigned. The directives appropriate for this mode are listed below; see the section on combination difference fitting for how to use them.

CDlower	Following observations are taken in pairs as lower state combination differences
CDupper	Following observations are taken in pairs as upper state combination differences
CDstart	Mark start of region to search for combination differences; requires matching AutoCDupper or AutoCDlower directive.
AutoCDupper flag	Convert preceding observations to upper state combination differences; starts at previous combination difference directive, or start of file if none present. The optional flag controls the handling of observations that are not part of an upper state combination difference: ignore - discard the observations force (default) - report an error for each observation include - include the observation in the fit as is.
AutoCDlower flag	As for AutoCDupper, but convert to lower state combination differences.

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 under (rest of line) at the end of the "Standard PGOPHER format" above for more on this. An alternative method, which is particularly useful when adding or subtracting states from a manifold, 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)
StdDev or Weight	The (relative) standard deviation 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
E' E"	Upper and lower state energy. Note this requires a calculation to be performed as each line is read, and the selection could potentially change on each fit cycle.
Intensity	The transition intensity. As for state energies, this requires a calculation to be performed as each line is read, and the selection could potentially change on each fit cycle.

Alternative Formats

While the standard format above is the most general, and works for all cases, it can be awkward to work with, particularly for line listings from taken from other sources, rather than constructed by interactive assignment. There are various simpler possibilities available, which work in many but not all cases:

Simple Format

This simplified format is introduced by a NQN or nQuantumNumbers directive, that specifies the number of quantum numbers given in each state. Each line then contains the upper state quantum numbers, then the lower state quantum numbers, followed by the observation and relative standard deviation. For example, for an asymmetric top:

NQN 3
2 0 2  1 1 1   187.43463 1.0
1 1 0  1 0 1 21223.35986 1.0
2 1 1  2 0 2 22268.0897  1.0

The layout is free format, in that the numbers can be separated by any number of spaces or tabs. All text after the relative standard deviation is treated as a comment. The quantum numbers are:

J' K_a' K_c' J" K_a" K_c" for asymmetric tops (as here)
J' K' J" K" for symmetric tops
J' J" for linear molecules (See below for other possibilities)

Where a state in either manifold has a non zero spin, replace J by N and add J on the end; for hyperfine structure add F₁...F on the end, so an open shell asymmetric top with two nuclei would be N' K_a' K_c' J' F₁' F' J" K_a" K_c" F₁" F. This format is not appropriate for vibrational structure type calculations, and some of the more complicated cases for other calculation types must be handled using the full standard format. Where multiple states or manifolds are present, use uppermanifold, lowermanifold, upperstate or lowerstate directives (see above) as to indicate the required state. Use NQN 0 to revert to the standard format.

Fitting to energy levels is also possible by setting all the quantum numbers for the unwanted state to "-"

For linear molecules there are two extensions to this format, flagged by the presence of a letter in the second (or third) quantum number:

To specify J and the component (F) number:

J' Fn'e J" Fn"f specifies Fn' e parity in the upper state and Fn" f parity in the lower state. The second item must be given without spaces, so an example might be:

10 F1e 10 F2f

The e and f can be omitted in this case if there is only one one parity present.

To specify J and Ω:

J' Ω'e J" Ω"f specifies Ω' e parity in the upper state and Ω" f parity in the lower state. The second item must be given without spaces, so an example might be:

10 0e 10 1f

The e and f can't be omitted in this format.

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

If the transition is a Raman transition, a multiphoton transition of even rank or a magnetic dipole transition add a branchrank 0 directive before the first line.

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 be taken to have (relative) standard deviation 1, unless overridden with overridestddev or scalestddev.
To end the table, give a branchtable directive with no branches following

HITRAN line lists (.par files)

Line lists extracted from the HITRAN database, or line listings with the same format, can be used as input files for fitting. Both the older 100 character line and the newer 160 character line formats can be read. The quantum number format can normally be determined automatically, but a globalclass n directive can be used to specify the molecule type if necessary. The number corresponds to the entries in Table 3 of the "The HITRAN 2004 molecular spectroscopic database", J. Quant. Spectrosc. Radiat. Transfer 96, 139 (2005).To trigger this mode the file extension must be .par. upperstate/lowerstate and related directives can be used to specify the states involved, if there is more than one possibility, or alternatively the states can be named following the global class quantum numbers. The names required are the "global" quanta for the state, with the fields separated by "_". Note that HITRAN line lists can also by used as overlays or as an external line list for simulations. See Using HTITRAN Files for more information.

ExoMol line lists (.states, .trans files)

Files from the ExoMol project can also be used as input to the fitting process; see Using ExoMol Files.

JPL Line Catalog Files (.cat, .mrg)

PGOPHER can read many JPL line catalog files as produced by Herb Pickett's CALPGM/SPCAT/SPFIT/DPFIT/DPCAT programs, and the .lin files used as input to the SPFIT and DPFIT programs. For details see 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) and http://spec.jpl.nasa.gov/. Note that many parameter (.par) files can be imported by PGOPHER; see File, Import.

To read the catalog file format an extension of .cat or .mrg is required. To read the .lin line lists as input to SPFIT and DPFIT special action is required, as PGOPHER also uses the .lin extension. Either add a line containing:

IncludeSPFIT

at the start of the file or, in a separate .lin file use a line containing:

IncludeSPFIT filename

This format requires the quantum numbers in fixed 3 character columns at the start of each line. The number of quantum numbers is autodetected by counting the number of non blank columns; if zeros have been used for unused quantum numbers then -(half the number of quantum numbers) must be specified in the directive, as for example:

IncludeSPFIT filename -3

for a simple asymmetric top.

Alternatively free format can be used, in which case half the number of quantum numbers must be specified as a positive number as part of the IncludeSPFIT directive:

IncludeSPFIT * 3

at the start of the file or:

IncludeSPFIT filename 3

to include the contents of another file.

Not every format is currently implemented. For the more complicated systems directives such as upperstate may be required to specify one or more of the states involved. 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 m.s	Provide a mapping of state numbers from the .par file to PGOPHER states. This is required for more complicated cases, typically involving multiple states. Degenerate states in symmetric tops also require this, as Pickett's programs treat this type state as pairs, while PGOPHER treats then as a single state. n1 is the number in the .par file. m.s refer to the manifold (m) and state (s) numbers in PGOPHER, numbered starting from zero. s values >= 1000 indicate an alternate kl assignment. The m. can be omitted, in which case the manifold specified by uppermanifold is used. Repeat the directive for every state number that requires changing. n2 values are taken mod 1000;
maplower n1 m.s	As for mapupper, but for the lower state.
DoubleABlevels TrueOrFalse	When fitting intensities, divide input intensity by two where the transition is one of a normally degenerate pair of levels, such as A₁ and A₂ in non-degenerate vibronic states in C_3v. PGOPHER always treats such transitions as separate, but these sometimes appear merged into a single line in .par and .mrg files.