MORSE Software User's Manual: Driver Table

Last Updated: 09FEB05 - add *NTE section

Section structure of MORSE Driver Table

Mandatory sections
*HDR	1. Comment record written to output file headers
*FLG	2. Option flags
*SCN	3. Nominal altitudes of spectra in full limb scan
*LEV	4. Nominal retrieval levels
*RTV	5. Target quantities to be retrieved
*MWL	6. Microwindow list files
*MDB	7. Microwindow Database files
*L1C	8. Input spectra
*CLI	9. Climatological profiles
*ILS	10. Instrument Line Shape files
*FOV	11. Field of View Shape
Optional sections
*ACC	Accuracy settings
*ACV	A Priori Covariance
*ASD	A Priori Standard Deviation
*CLD	Cloud Detection Criteria
*CNV	Convergence Criteria
*FMZ	Forward Model Altitudes
*HIT	HITRAN Database
*L2P	Level 2 Input Profiles
*LUT	Directories for Look Up Tables
*NTE	Vibrational Temperatures for non-LTE forward model
*OUT	Rename Output Files
*SHP	Specify line shapes for line-by-line calculations
*XSC	Directories for Molecular Cross Sections
Termination Record
*END

Sections

The driver table consists of a number of sections identified by records starting with an asterisk followed by 3 characters

*ABC

where ABC is some code (case-insensitive) defining the contents of the section. These 4 characters have to occupy the first 4 positions in the record.

The driver table is terminated with

*END

(remember to add a <CR> after the *END)

The first 11 sections (*HDR ... *FOV) are mandatory and the sequence is fixed. Thereafter sections are optional and in any order.

Only the first 4 characters of any record starting with * are read, so comments may be added to these records without any exclamation mark if you need to remind yourself what each does

Records

Each section consists of one or more records:

• Anything beyond 80 characters is ignored
• Anything beyond an exclamation mark `!' is ignored - useful for adding comments or `commenting out' records
• Empty records (ie containing only space characters) are also ignored.

Fields

Each record is usually divided into one or more fields separated by spaces:

• Case is not significant except where referring to filenames or directories
• Spaces are not significant except to separate fields
• The various fields can be distributed over an arbitrary number of records
• Order may be significant - depends on the type of section.

RFM Differences

Main differences with respect to the RFM driver table rfm.drv

• While the RFM `optional sections' are usually ignored unless activated by a corresponding flag in the *FLG section, in MORSE the general principle is to use every section that is present in the driver table without requiring a corresponding flag, ie the presence of the section in the driver table acts as the flag.
• Also, while the RFM has fairly specific formats for each section of the driver table, with MORSE I've tried to simplify things

Examples

morse_pt.drv Pressure/Temperature Retrieval

morse_h2o.drv Water Vapour Retrieval

The rest of this document describes the contents of each section.

*HDR Section (#1)

Description

Text passed directly to output files as the second `comment' record in the file headers, eg to identify driver table used to generate output files.

Format

Single record, up to C*79, read as a single field.

Values

[text] for output header record.

Notes

1. In the output file headers, an exclamation mark (!) is written as the first character (to identify a comment record), with the text string following, hence the truncation to 79 characters rather than the full 80 which could fit in the driver table section.
2. Although the record is read as a single string, the usual rules for driver table entries still apply: completely blank records are ignored and the record is truncated at the first exclamation mark.
3. The version of the MORSE software used (variable VIDHDR set at the start of module morse.for) is automatically written into the first header record of output files so there is no need to include this information in the *HDR section.

Example

*HDR
  O3 Rtvl generated with morse.drv 14NOV04 ! [and this part won't be written] 

Description

A series of 3-letter codes indicating various MORSE options to be `switched on' (all switched off by default)

Format

C*3 fields, any order.

Values

APR	Output A Priori information (morse.apr)
CLD	Use cloud detection
COV	Output covariance matrix (morse.cov)
CTM	Use molecular (eg H2O) continuum data
DIA	Output iteration diagnostics (morse.dia)
FGD	Use full, as opposed to irregular, grid (v19NOV04 onwards - see Note 2)
FVZ	Suppress FOV distortion due to refraction
GEO	Use geometric (ie non-refractive) ray paths
GRD	Use irregular spectral grid where available (up to v18NOV04 - see Note 2)
HYD	Use hydrostatic constraint (PRE + TEM retrieval only)
LIN	Assume VMR varies linearly with altitude rather than logarithmically
LUT	Use Look-Up Tables for absorption coefficients where available (up to v18NOV04 - see Note 2)
MWO	Write outputs for each microwindow
NOM	Use nominal sweep altitudes instead of actual
QAD	Use simple quadratic fit to line wings rather than inverse quadratic
RES	Output residual spectra (v25NOV04 onwards ) (morse.res)
TRA	Use transmittance rather than radiance measurements

Notes

1. There are a number of other RFM options which should work in principle but have not been tested, plus a number of RFM options such as FOV and ILS which are assumed always enabled for MORSE so are not explicitly specified - see modules flgcom.inc and drvflg.for]
2. The LUT and GRD flags are only used in MORSE versions up to v18NOV04. After that the irregular grid will be used wherever supplied (ie in the database files in the *MDB section) unless switched off using a new flag FGD. The LUTs will be used whenever files are found in the directories given in the *LUT section of the driver table. However, to allow some period of overlap, the next few versions of MORSE will simply issue warnings, rather than fatal error messages, if these flags are still present in the driver table

Example

*FLG
  CLD HYD FVZ 

Description

The nominal altitudes associated with each sweep (=spectrum) in the L1C file

MORSE v01DEC04 onwards: can also specify spectral resolution

Format

Real numbers, order is significant.

Parameter=Value field, can be placed anywhere

Values

[Nominal Sweep Altitudes] in [km].

RESLN=[resolution] in [cm-1] (optional, default=0.025cm-1) - see Note 3

Notes

1. The sequence of entries must match the altitude ordering of the sweeps (=spectra) that constituted the entire limb scan from which the L1C file was extracted (even if not all sweeps are present in the L1C file).
2. In future versions of the L1C format (v1.5?) the nominal altitude will be written into the L1C file itself so that this driver table section will become redundant.
3. The spectral resolution (strictly, the spectral grid spacing rather than the resolution) is checked in drvscn.for and restricted to the range 0.01-1.0cm-1, also with a requirement that it must correspond to an integer number of points per wavenumber. These checks can be commented out if you're feeling adventurous...
4. The default resolution is specified in msescn.for
5. If you change the spectral resolution, remember to change the AILS file specified in the *ILS section to something appropriate for the new resolution.

Example

*SCN
  68 60 52 47 42 39 36 33 30 27 24 21 18 15 12 9 6 ! Nominal scan

Description

The nominal altitudes of the retrieval levels.

Format

Real numbers, order is significant

Values

[Nominal Retrieval Altitudes] in [km], increasing monotonically

Notes

1. The retrieval altitudes must be a subset of the the nominal sweep altitudes read from the *SCN section, however a maximum of one additional level is permitted above the highest sweep (eg at 76km).
2. `Nominal altitude' here is really just a convenient means of tying the retrieval level to the tangent altitude of each spectrum - easier to handle than listing the sweep indices selected for retrieval levels, or the actual tangent altitudes.
3. The retrieval altitudes always increase monotonically, although the nominal sweep altitudes listed in the *SCN section will usually decrease monotonically

Example

*LEV
  12 15 18 21 24 27 30 33 36 39 42 47 52 60 68 76 ! Retrieve 12-76km

Description

The list of parameters to be retrieved.

Format

Character strings up to C*8, any order.

Values

TEM	Temperature	[K]
PRE	Pressure	[mb]
CTM	Continuum	[/km]
OFF	Radiometric Offset	[nW/(cm2.sr.cm-1)]
[Molecule]	Species VMR	[ppmv]

Notes

1. When Pressure and Temperature are retrieved together, it is normal to enable the HYD Flag in order that hydrostatic constraint is used to adjust the sweep tangent altitudes
2. Continuum is retrieved independently for each microwindow with an upper altitude of 30km (set in drvlev.for). The MWO Flag needs to be set if the output of the retrieved profiles is required.
3. Radiometric Offset is retrieved independently for each microwindow. Currently this information is only written in the diagnostics file, so the DIA Flag needs to be set to see these values.
4. Molecules can either be specified as formula, HITRAN index or (for CFCs) `F' number. However, internally these are stored as formulae or (for CFCs) `F' number, all lower case.
5. For isotopic retrievals add (iso) to the molecule name where iso is the HITRAN isotope ID (1=most abundant, 2=second most, etc), eg for H2 18O use H2O(2). See module gasiso.for for the recognised isotopic indices.

Example

*RTV
  TEM PRE CTM O3 H2O(1) H2O(2)  ! Joint pT, O3, ctm and main two H2O isotopes

Description

File(s) containing the list of microwindows to be used: microwindow labels, spectral and tangent altitude ranges, and, optionally, a list of absorbers.

Format

Character strings, order is significant (see Note 1)

Values

[filename(s)] of .lst files

Notes

1. MORSE processes the microwindows sequentially in the order in which they appear in each .lst file, and in the order in which each .lst file appears in this section. In theory the end result should not be sensitive to the order in which microwindows are used but in practice there are always small differences due to convergence, etc.
2. The C*8 microwindow labels and wavenumber boundaries in the .lst files must match those in the MW*DAT database files included in the *MDB in order to identify a matching microwindow
3. The tangent altitude range in the .lst file overrides that in the database file
4. If any absorber indices are included in the .lst these replace all the absorbers in the database file - a useful way of reducing the cpu time/array space by reducing the number of absorbers considered (the retrieved species are automatically considered as absorbers in every microwindow whether explicitly listed or not)
5. Normally, the microwindow list would only identify the microwindow to be used (combination of code and wavenumber boundaries) and the applied tangent height range, with other information coming from the Microwindow Database file. However it is also possible to use the microwindow list to fully specify the microwindow - see use of * character in *MDB section of the driver table

Example

*MWL
  pt_000.lst  ! pT microwindows
  h2o_000.lst ! plus H2O microwindows for a joint retrieval with pT

Description

Microwindow Database File(s) containing further information on microwindows: spectral masks, irregular grids and full list of absorbers

Format

Character strings, any order

Values

[filename(s)] of MW*DAT files, and/or

* (see Note 2)

Notes

1. The microwindows to be used are specified in the *.lst files in the *MWL section - the MW database files generally contain information for all microwindows of which only a subset is required.
2. An asterisk * in this section indicates that, if the microwindow cannot be found in a database file (or no database files are provided) the complete microwindow information is determined by the entry in the .lst file. This implies no spectral masks or irregular grids, which are only stored in database files, but is useful for running retrievals with ad-hoc `hand selected' microwindows.

Example

*MDB
  MW_PT__103.DAT MW_H2O_103.DAT  ! pT & H2O microwindows

Description

Name of L1C file containing apodised spectra for the selected microwindows for one complete limb scan.

Format

Single Character string

Values

[filename] of L1C file.

Notes

1. See http://www.atm.ox.ac.uk/group/mipas/L1C for L1C file format
2. L1C files can be generated by IDL programs lv2pp.pro or, more recently, l1c.pro using MIPAS L1B files (full, unapodised spectra for complete orbits) as input.

Example

*L1C
  L1C_02081_SCAN#02   ! Scan#2, orbit 2081

Description

Atmospheric profiles, eg from climatology, used to specify both a priori for retrieved species and fixed values for unretrieved species.

Format

Character strings, order is significant

Values

[filename(s)] of .atm files

Notes

1. The altitude grid of the first file determines the altitude grid on which all subsequent files are interpolated and stored, so should typically span 0-120km at 1km intervals [however, this is not the same as the forward model altitude grid - see *FMZ section]
2. If profiles for any species are repeated, subsequent files overwrite the earlier profiles [however, unlike the RFM, the profile is only replaced within the altitude range of the new profile].
3. Previously retrieved profiles within the same scan, and therefore on the same altitude grid as the retrieval (eg pT), should be input via the *L2P section rather than here in order to avoid unecessary interpolation.

Example

*CLI
  day.atm     ! Mid-latitude dayime profiles
  aerosol.atm ! zero extinction aerosol profile 
  h2o.atm     ! H2O retrieved from previous scan (so different alt.grid)

Description

Apodised Instrument Line Shape

Format

Characters strings, any order

Values

[filename(s)] of .ils files.

Notes

1. A generic lineshape can be supplied for all microwindows and/or separate files for particular spectral regions (the valid spectral range is included in the .ils header)

Example

*ILS
  mipas_a.ils  ! MIPAS A band AILS
  mipas_ab.ils ! MIPAS AB band AILS
  nbstrong.ils ! Idealised Norton-Beer Strong ILS for other bands

Description

Field of View Shape

Format

Single Character string

Value

[filename] of .fov file.

Notes

1. It is (currently) assumed that the MIPAS FOV shape has no spectral dependence so only a single shape is used for all bands
2. By default, the FOV is allowed to distort with refraction at low altitudes. This can be switched off by adding the FVZ flag in the *FLG section.

Example

*FOV
  rfm_1km5.fov ! 5 pt representation of MIPAS FOV @1.5km spacing

Description

Specify A Priori Covariance

Introduced in MORSE v29NOV04.

Format

Character string (mandatory)

PARAMETER=VALUE string (optional)

Fields may in either order

Values

[filename] of A Priori Covariance Matrix

RELAX=[float] Relaxation parameter .GE. 0 (optional, default=0)

Notes

1. This section can be used either to specify a more complicated {\it a priori} covariance than can be set by the *ASD section, or to use a previously retrieved covariance partially relaxed to climatological covariance as part of a Kalman filter along the orbit.
2. The A Priori Covariance file only applies to the main target parameters, ie excluding continuum and offset, and is in the same format as morse.cov (or morse.acv) output by the COV flag. The only check on the file is to make sure that the matrix dimension agrees with the current retrieval.
3. The relaxation parameter RELAX=[R] is defined as

   SA' = SA*EXP(-R) + SC*(1-EXP(-R))

   where SA' is the A Priori covariance actually used to start of the retrieval, SA is the covariance read from the file specified in this section, and SC is the climatological covariance constructed in the same way as the default a priori (including modifications in the *ASD section). A value RELAX=0.0 (which is the default) means that the specified A Priori covariance is used exactly as supplied, a value RELAX=0.1 implies relaxing to climatological covariance with a 1/e time constant equivalent to 10 scans, 0.01 is a hundred scans, etc.

Example

*ACV
    morse.cov   ! Use previous output covariance
    relax=0.05  ! Climiatological relaxation length: 20 profiles, or ~1/4 orbit

Description

Change Cloud Detection Criteria

Introduced in MORSE v15DEC04

Format

PARAMETER=VALUE strings, any order

Values

Setting	Definition	Default
IDXCLD=[real]	Maximum Cloud Index (-1 or positive)	1.8
RADCLD=[real]	Minimum Cloud Radiance (-1 or positive)	125.0 [nW/(cm2.sr.cm-1)]
TOPCLD=[real]	Maximum Cloud Altitude (-1 or positive)	30.0 [km]

Notes

1. These settings only have any effect on the retrievals if the CLD flag in the *FLG section is set, otherwise the only effect is on the thresholds for which warning messages on possible cloud contamination are sent to the morse.log file.
2. IDXCLD is the maximum value of the U.Leicester Cloud Index for which the sweep will be assumed cloud-contaminated (ie assumed cloud free for higher values). Note that a Cloud Index of 0.0 in the L1C input file is assumed cloud-free from MORSE v10DEC04 onwards (see Bug#07).
3. RADCLD is the minimum cloud detection channel (960.7cm-1) radiance for which the sweep will be assumed cloud contaminated, (ie assumed cloud-free for lower values).
4. Clouds are flagged if either the Cloud Index or the Cloud Radiance tests indicate a cloud. Set values of -1 to turn off either or both tests.
5. TOPCLD sets the maximum altitude for which a cloud can be flagged. This is necessary because Cloud Index values become a bit random at high altitudes due to noise. Setting this to -1 turns off any altitude limit, but is not recommended unless IDXCLD=-1 also.
6. Default values are set in module mseini.for and reported at the start of the morse.log file.

Example

*CLD
    RADCLD=-1    ! Remove Cloud Radiance threshold test
    CLDIDX=2.2   ! Set more stringent Cloud Index threshold

Description

Spectroscopic Database file

Format

Single Character string

Value

[filename] of binary spectroscopic database file, e.g., binary version of MIPAS HITRAN

Notes

1. A spectroscopic database file is required if any absorbing molecules have HITRAN indices less than 50 (which will usually be the case) AND corresponding Look Up Tables are not available.
2. The binary file is the same format as used by the RFM and GENLN2, and can be created from a HITRAN ASCII file using program hitbin.for
3. The reading of the binary file is machine-dependent, and the appropriate record size needs to be set in module reclen.inc (88 for most machines, 22 for alphas).

Example

*HIT
    ../morse_files/hitran_mipas.bin

Description

Previously retrieved Level 2 profiles

Format

Character strings, order is significant

Values

[filename(s)] of .atm files generated by MORSE for the same limb scan.

Notes

1. If a *SWEEP profile is present (ie MORSE retrieval output if HYD flag enabled) the altitudes associated with each sweep will override those in the L1C data hence also redefine the output altitudes
2. These replace the existing profiles input in the *CLI section (which still have to be supplied) but the difference is that these profiles will usually be represented directly on the retrieval altitudes (assuming they are all retrieved from the same scan) and therefore not interpolated to the climatology grid and then reinterpolated to the retrieval grid (as happens to files in the *CLI section).
3. Original profiles are only replaced over the altitude range of the subsequent profile, unlike in the RFM where the entire profile is overwritten.
4. Profiles retrieved in a different scan, ie on different altitudes, should be included in the *CLI section.
5. In theory the morse.rtv files could also be used here but it is better to use the full profile to ensure a consistent representation of the atmosphere (especially pT) in each retrieval.

Example

*L2P
    morse_pt.atm          ! Input retrieved pT profile
    morse_h2o.atm         ! Input retrieved H2O profile

Description

Directories for Look Up Tables

Ignored unless LUT flag is enabled (up to v18NOV04, always read in later versions).

Format

Character strings, order is significant (Note 1)

Value

[directories] to be searched for CS*DAT files (including trailing `/' character up to MORSE v15DEC04, optional in later versions)

[This is different from the RFM which uses either explicit filenames or a generic filename including a `*' character for the microwindow/molecule name]

Notes

1. If the *LUT section is present in the driver table, MORSE first attempts to find the LUTs for all combinations of microwindow/absorber and, if any LUTs are not found, will then use either the HITRAN .bin file specified in the *HIT section (if HITRAN Index of the absorber is <50), or search for the the .xsc file in directories specified in the *XSC section (HITRAN Index .GE. 50)
2. The directories are searched in order for the first occurrence of the LUT. If a file of the same name occurs in any subsequent directories it is ignored.
3. Use ./ to indicate the current directory

Example

*LUT
    ../morse_files/CS/pt/ ! pT LUTs
    ../morse_files/CS/o3/ ! O3 LUTs

Description

Vibrational temperature filenames

Introduced in MORSE v03FEB05.

Format

Character strings, order is not significant.

Value

[filenames] of .nte files containing vibrational temperatures profiles of various molecules

Notes

1. If the *NTE section is present in the driver table, MORSE will use the non-LTE form of radiative transfer equation, even if no vibrational temperatures are supplied.
2. Look Up Tables (*LUT section) cannot be used in conjunction with non-LTE calculations.

Example

*NTE
    co2_day_amil2da.nte  ! Use mid-lat daytime vib.temps
    h2o_day_amil2da.nte
    o3_day_amil2da.nte

Description

Rename Output Files

Introduced in MORSE v25NOV04.

Format

PARAMETER=VALUE strings, any order. VALUEs are case-sensitive.

Values

Setting	Definition	Default
DIR=[directory]	Output directory	[local directory]
ACV=[filename]	A Priori Covariance	morse.acv
APR=[filename]	A Priori Vector	morse.apr
ATM=[filename]	Retrieved Atmosphere	morse.atm
COV=[filename]	Retrieval Covariance	morse.cov
DIA=[filename]	Diagnostics	morse.dia
RES=[filename]	Residual Spectra	morse.res
RTV=[filename]	Retrieval Vector	morse.rtv

Notes

1. The DIR VALUE [directory] (a trailing '/' character is added if it is not supplied) simply added to the start of all the output filename strings, so what works and what doesn't depends slightly on the operating system. Used on its own, it will simply redirect the standard MORSE output files to a different directory.
2. Renamed output files are listed in the morse.log file when this section of the driver table is read.
3. Default filenames are set in module mseini.for, these are not listed in the morse.log file.
4. This section cannot be used to change the name or location of the log file, which is always morse.log written in the current directory (the reason being that this file is opened before the driver table is read - see module mselog.for if you really do need to change it).
5. If the MWO Flag is used, the string _MW[nn] will be appended to the new names

Example

*OUT
    APR=morse_pt.apr
    cov=./cov/morse_pt.cov
    dir=../Morse_Outputs/

Description

Specify alternative (ie non-Voigt) line shapes for line-by-line calculation

Introduced in MORSE v18NOV04

Format

PARAMETER=VALUE strings, any order

Values

[molecule]=VOI	Voigt line shape
[molecule]=CHI	Chi Factor
[molecule]=LOR	Lorentz line shape
[molecule]=DOP	Doppler line shape
*=[any of the above]	Set lineshape for remaining `line' molecules

Notes

1. Although this section performs the same function as the *SHP section in the RFM driver table, the syntax and defaults are quite different so don't assume anything based on RFM experience
2. The [molecule] parameter values are the chemical formulae of any `line' molecule (indices 1:49)
3. The lineshapes values are converted to lower case and truncated to the first 3 characters, so, for example DOPPLER, doppler and DoP1234 are all interpreted as DOP
4. The asterisk * is useful for setting the all remaining molecules to a particular lineshape. If it isn't used, the Voigt lineshape is used by default (so *=VOI has no effect).
5. These line shapes are only applied to the molecules for which line-by-line calculations are performed, there is no effect on molecules whose cross-section is read from LUTs.

Example

*SHP
  co2=chi      ! Chi factor for CO2
  o3=doppler  h2o=dop     ! Doppler for O3 and H2O
  *=lorentz      ! Lorentz for everything else

Description

Directories for Heavy Molecule Cross Section files

Format

Character strings, order is significant (Note 1)

Value

[directories] for .xsc files (including trailing `/' character up to MORSE v15DEC04, optional in later versions)

Notes

1. The directories are searched in order for the first occurrence of the .xsc file. If a file of the same name occurs in any subsequent directories it is ignored.
2. This is different from the RFM which uses either explicit filenames or a generic filename including a `*' character for the molecule name
3. Use ./ to indicate the current directory
4. The molecular cross section files are assumed to have names of the form ggg.xsc where ggg is the lower case name of a cross-section molecule (ie Index GE 50), using `F' numbers for CFC's (eg f12.xsc)
5. Having located the appropriate file, it is not actually opened until the driver table is fully read in case there are LUTs which can be used instead (and to avoid unnecessarily large array spaces which are sometimes required to accomodate the data in .xsc files)

Example

*XSC
    ./                 ! just aerosol.xsc in current directory
    ../morse_files/    ! directory for all other .xsc files 

Back to MORSE Index