MORSE Software User's Manual: Driver Table

17MAY07

Section structure of MORSE Driver Table

Mandatory sections
*HDR	1. Comment record written to output file headers
*FLG	2. Option flags
*L1C	3. Input spectra
*RTV	4. Target quantities to be retrieved
*[LEV]	5. Retrieval levels (*ALT, *PRE, *SWP or *TAN)
*MWL	6. Microwindow list files
*MDB	7. Microwindow Database files
*CLI	8. Climatological profiles
*ILS	9. Instrument Line Shape files
*FOV	10. Field of View Shape (omitted if nadir-viewing)
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 10 sections (*HDR ... *FOV) are mandatory and the sequence is fixed (or 9 sections for nadir-viewing geometry since FOV is not specified for nadir-viewing). Thereafter sections are optional and in any order, terminated with the *END record.

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.

MORSE v2 Differences

Main differences with respect to the structure of the MORSE v2 driver table

• *SCN section (originally #3) is no longer required since the information is now carried in the L1C file itself
• *L1C section is now #3 instead of #8 in order to introduce the data originally in the *SCN section via the L1C file itself. Also includes updated pointing information (via a morse.swp file).
• *RTV section is now specified before the *LEV section (#5 and #6 instead of #3 and #4) in order to allow different retrieval grids for different species
• *LEV section is redefined as one of *ALT, *PRE, *SWP or *TAN, depending on how the retrieval grid is to be specified.

RFM Differences

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

• 'Optional sections' in the RFM are usually ignored unless activated by a corresponding Flag in the *FLG section, but 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 using a generic PARAMETER=VALUE structure wherever possible.

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

Field	Type	Description
HDRREC	C*79	Text for output file headers

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] 

*FLG Section (#2)

Description

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

Format

Multiple fields of single type, any order, limited set of values.

Field	Type	Value	Description
FLG	C*3	ACC	More stringent default accuracy/convergence criteria	New in v3
		AHY	Suppress hydrostatic equilibrium	Only with PRE retrieval
		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
		FIX	Assume fixed relative altitudes (eg detector array)	Only with PRE retrieval New in v3
		FMW	use full microwindow (ie set all masks = TRUE)	New in v3
		FVZ	Suppress FOV distortion due to refraction
		GEO	Use geometric (ie non-refractive) ray paths
		LIN	Assume VMR varies linearly with altitude rather than logarithmically
		MWO	Write outputs for each microwindow
		QAD	Use simple quadratic fit to line wings rather than inverse quadratic
		RES	Output residual spectra (morse.res)

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 following v2 flags are no longer used

   NOM Use nominal sweep altitudes instead of actual

   Now always assumed true

   HYD Use hydrostatic constraint (PRE + TEM retrieval only)

   Now assumed true whenever applicable, use new AHY to switch off

   TRA Use transmittance rather than radiance measurements

   Now determine type of spectra from info L1C file itself

Example

*FLG
  CLD APR RES   ! Use cloud-detection, generate A Priori and Residuals files

*L1C Section (#3)

Description

Input spectral data, plus optional modification to tangent heights.

Format

Single field, followed by optional second field. Fields identified by order.

Field	Type	Description	Requirement
1. L1CFIL	C*80	Name of L1C file	Mandatory
2. SWPFIL	C*80	Name of .swp file	Optional

Notes

1. For MORSE v3, L1C format must be v2.0 or later - this contains an additional record identifying the viewing geometry and resolution which are read by MORSE v3.
2. L1C files can be generated by IDL program l1c.pro using MIPAS L1B files (full, unapodised spectra for complete orbits) as input.
3. If the sweep tangent heights have been modified by a previous pT retrieval, the name of the .swp output file from the pT retrieval (containing a *HGT_RTV profile) should inserted into the driver table immediately after the L1C file and the sweep altitudes will be updated (In v2, the sweeps were updated via the .atm file in the *L2P section)

Example

*L1C
  L1C_02081_SCAN#13   ! Scan#13, orbit 2081
  ../pt/morse.swp     ! Modified Sweep altitudes from pT retrieval output

*RTV Section (#4)

Description

The list of parameters to be retrieved.

Format

Multiple fields of single type, any order, limited set of values.

Field	Type	Value	Description	Units	Restrictions
RTV C*10	TEM	Temperature	[K]
		PRE	Pressure	[mb]	Not on *PRE levels
		CTM	Continuum	[/km]
		AEROSOL	Aerosol	[/km]
		SFT	Surface Temperature	[K]
		OFF	Radiometric Offset	[nW/(cm2.sr.cm-1)]
		[gas]	Molecule VMR	[ppmv]	[gas] from List of gases
		[gas]([iso])	Isotopomeric VMR	[ppmv]	[iso] from List of isotopes
		[gas]([iso])([vib])	Vibrational Temperature	[K]	[vib] is HITRAN Global Quantum Number (1=ground state)
		[gas](lin)	Linear Retrieval	[ppmv]	v13AUG07 onwards

Notes

1. The hydrostatic constraint is assumed whenever temperature (TEM) and pressure (PRE) are retrieved together. The AHY Flag suppresses this (in MORSE v2 it was necessary to explicitly specify the hydrostatic constraint using the HYD flag)
2. Continuum and offset are retrieved independently for each microwindow. The MWO Flag needs to be set if the output of these parameters is required as morse.rtv_MWn files (the offset value is written in the file header).
3. By default (set in subroutine levvec.for) the continuum is only retrieved to a maximum altitude of 30km (or minimum pressure of 10mb on *PRE levels). See *LEV section notes for how to change this.
4. AEROSOL (introduced in MORSE v08NOV05 onwards) differs from CTM in that a single profile is retrieved for all microwindows, rather than an independent profile for each microwindow separately. Effectively AEROSOL is treated just like any other retrieved gas. Note that the a priori covariances for AEROSOL and CTM differ, so even if AEROSOL is retrieved for a single microwindow over the same altitude range as CTM the results will differ.
5. The retrieved values of scalar quantities (i.e. SFT) are written into the header of the morse.rtv file
6. [gas] 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.
7. 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).
8. For Vibrational Temperature retrievals (v01MAY07 or later), add (vib) to the molecule/isotope where vib is the HITRAN Global Quantum number identifying the vibrational level, eg for CO 1st excited level (vib=2) for the most abundant isotope use CO(1)(2).
9. For VT retrievals there is also an option to retrieve the same vibrational temperature for all isotopes together. For this, use a 0 instead of the isotope ID, eg CO(0)(2).
10. Internally, MORSE retrieves ln(vmr) profiles (i.e. always positive values when converted to VMR for output) but by inserting the (lin) qualifier somewhere after the molecule name it will retrieve linearly in VMR (MORSE versions v13AUG07 onwards).

Example

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

*ALT, *PRE, *SWP or *TAN Section (#5)

Description

The retrieval grid

The section header itself defines the grid type

Format

Multiple fields or PARAMETER=VALUE settings, order is significant

Structure:

*LEV	Mandatory	Section Header defines grid type
GRD(i)	Mandatory	Repeat for i=1:ngrd retrieval grid levels
SUBSET=[rtv(j)]	Optional	Start Repeat for j=1:nrtv retrieved parameters
IDXSUB(k,j)	Optional	Repeat for k subset levels of parameter j
		End Repeat for j
REFLEV=[rlev]	Optional	Insert at any point
REFSWP=[rswp]	Optional	Insert at any point

Field	Type	Value	Description
*LEV	C*4	*ALT	Altitudes [km]
		*PRE	Pressures [mb]
		*SWP	Tangent points, specified by Sweep indices
		*TAN	Tangent points, specified by Nominal altitudes [km]
GRD	R*4		Retrieval Grid levels (*ALT, *PRE, *TAN)
	I		Retrieval Grid Sweep indices (*SWP)
	C*1	*	Shorthand to indicate all L1B tangent points/sweeps	v10may07
SUBSET=	C*8	[rtv]	Define subset for retrieved parameter [rtv]
IDXSUB	I		Index of GRD for retrieval subset level
REFLEV=	I	[rlev]	Index of retrieval level used as reference
REFSWP=	I	[rswp]	Index of sweep used as reference

Notes

1. This section is radically different from the v2 *LEV section
2. Both the *SWP and *TAN grids are tangent point grids, just specifying the tangent points in different ways. However, with the *TAN grid it is also possible to specify one additional level above the highest sweep (eg at 76km).
3. The GRD retrieval levels must be specified in order of increasing altitude, decreasing pressure, or sweep indices whose associated tangent point altitudes increase.
4. For the *SWP and *TAN the GRD values must correspond to tangent point information associated with sweeps in the L1C file.
5. For the *SWP and *TAN grids, a wildcard '*' may also be used to indicate all L1B tangent points (v10may07 onwards). Internally this is simply substituted for all the tangent points/sweeps in turn in order of ascending altitude, so with the *TAN option this can be used in conjunction with the extra retrieval level above the tangent point grid, eg ' * 76 ' but not as ' 76 * ' (which would result in an error concerning tangent altitudes not in increasing order).
6. For nadir-viewing L1C spectra, only the *ALT and *PRE grids may be used (since 'tangent point' is meaningless in the nadir viewing geometry).
7. With retrievals on *PRE pressure levels, if the first listed level is 0 this is intepreted as having a retrieval level at the surface (defined as altitude z=0km).
8. If no retrieval grid SUBSET is defined, default is to retrieve everything on full retrieval grid apart from continuum - see Note in *RTV section
9. If a SUBSET is defined, the following values must be indices in increasing order in the range 1:(No.GRD values).
10. If no REFLEV value is defined, the reference level is taken as REFLEV=1, ie the lowest GRD level in altitude
11. If no REFSWP value is defined, the reference sweep is taken as the index of the sweep with the lowest nominal altitude.

Example

*TAN
  12 15 18 21 24 27 30 33 36 39 42 47 52 60 68 ! Retrieve 12-68km tan.pts
  76                                           ! plus extra level at 76km
  SUBSET=SF6
  12 15 18 30 42            ! Retrieve SF6 on fewer levels
  REFLEV=3                  ! Use nominal 18km sweep as reference level
  SUBSET=CTM                
  12 15 18 21               ! Only retrieve continuum to 21km

*MWL Section (#6)

Description

List of microwindows to be used and, optionally, absorbers for each microwindow.

Format

Multiple fields of single type, order is significant.

Field	Type	Description
FILMWL	C*80	Names of .lst files

Notes

1. MORSE processes the microwindows sequentially in the order in which they appear in each MWLFIL file, and in the order in which each MWLFIL 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 MWLFIL 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 MWLFIL file overrides that in the database file
4. If any absorber indices are included in the MWLFIL file 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

*MDB Section (#7)

Description

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

Format

Multiple fields of single type, any order.

Field	Type	Description
MDBFIL	C*80	Names of MW*DAT files

Notes

1. The MW database files MDBFIL generally contain information for all microwindows of which only a subset is required, as specified in the *MWL section
2. An asterisk * in this section (in character position 2 or later) indicates that, if the microwindow cannot be found in a database file (or no database files are provided) the complete microwindow information is determined from the entry in the .lst file in the *MWL section. 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.
3. If you want to remove all spectral masks but still use the irregular grids, use the normal MDBFIL files but add the FMW Flag in the *FLG section.

Example

*MDB
  MW_PT__103.DAT MW_H2O_103.DAT  ! pT & H2O microwindows
  *         ! construct any other MWs from .lst file

*CLI Section (#8)

Description

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

Format

Multiple fields of single type, order is significant

Field	Type	Description
CLIFIL	C*80	Names 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 internal forward model altitude grid which is what appears in the morse.atm output file - 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)

*ILS Section (#9)

Description

Apodised Instrument Line Shape

Format

Multiple fields of single type, any order.

Field	Type	Description
ILSFIL	C*80	Names 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

*FOV Section (#10)

Description

Field of View Shape

This section is omitted for nadir-viewing spectra (as determined by the L1C file).

Format

Single field

Field	Type	Description
ILSFIL	C*80	Name 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.
3. Since only one sweep is processed at a time, there is no particular advantage in having a FOV representation which matches the retrieval grid spacing

Example

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

*ACC Section (Optional)

Description

Change Accuracy settings

Format

Multiple PARAMETER=VALUE fields, any order

Field	Type	Description	Default
NGJACC=	I	Number of gases for which Jacobians are computed	No. rtvd species
PGCACC=	R*4	Fractional change in pressure requiring new C-G path calc	0.01
TGCACC=	R*4	Change in temperature [K] requiring new C-G path calc	0.1
JCPACC=	R*4	Fraction of Jacobian perturbation requiring additional path	0.01
JCCACC=	R*4	Fraction of Jacobian perturbation requiring new C-G path calc	0.5

Notes

1. Default values are set in module mseini.for, except for NGJACC which is set in drvrtv.for
2. For the default setting of NGJACC, TEM and PRE both count as 'retrieved species' so Jacobians are only calculated for the primary (and secondary, in the case of TEM+PRE) absorbing molecules in each microwindow
3. Default values can be made more stringent simply by adding the ACC Flag in the *FLG section, in which case NGJACC becomes the total number of absorbers and the other parameters are all reduced by a factor 10. Any settings in this section will then override these new defaults.

Example

*ACC
    NGJACC=4  TGCACC=0.2

*ACV Section (Optional)

Description

Specify A Priori Covariance

Format

Single mandatory field plus optional PARAMETER=VALUE setting, any order.

Field	Type	Description	Default
ACVFIL	C*80	A Priori Covariance Matrix
RELAX=	R*4	Relaxation parameter	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 dimensions agree 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

*ASD Section (Optional)

Description

Change A Priori Covariance Matrix

Format

Multiple PARAMETER=VALUE fields, any order

Field	Type	Description	Units	Range	Default
CORREL=	R*4	Correlation length	[km]	0:100	50km
TEM=	R*4	Temperature SD	[K]	0.1:1000	10K	R*4
PRE=	R*4	Pressure SD	[%]	0.1:1000	50%
[gas]=	R*4	VMR SD	[%]	0.1:1000	100%

Notes

1. Default values are set in module mseapr.for
2. [gas] has to be given as 'F' number for CFCs, formula for other species
3. Currently there is no way of changing the continuum or offset a priori covariance via the driver table (apart from the continuum correlation length, which follows CORREL). These are set explicitly in micapr.for. The continuum a priori extinction SD [/km] is given by 1E-3*(p/500) where p is the pressure in [mb] (eg +/-0.02/km at 100mb) while the offset SD [nW] is the same as the average NESR value for the microwindow.

Example

*ASD
    CORREL=0 ! Uncorrelated A Priori
    CH4=10   ! Change CH4 to 10% uncertainty

*CLD Section (Optional)

Description

Change Cloud Detection Criteria

Format

Multiple PARAMETER=VALUE fields, any order

Field	Type	Description	Default
IDXCLD=	R*4	Maximum Cloud Index (-1 or positive)	1.8
RADCLD=	R*4	Minimum Cloud Radiance (-1 or positive)	125.0 [nW/(cm2.sr.cm-1)]
TOPCLD=	R*4	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.
3. RADCLD is the minimum radiance in the cloud detection channel (960.7cm^-1) 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

*CNV Section (Optional)

Description

Change Convergence Criteria

Format

Multiple PARAMETER=VALUE fields, any order

Values

Field	Type	Description	Default
MAXITR=	I	Maximum number of iterations (GE 1)	10
CHILIM=	R*4	Minimum value of ChiSq for convergence	1.0
DELCHI=	R*4	Minimum Change in ChiSq for convergence	0.1

Notes

1. Default values are set in module mseini.for, but can also be modified by setting the ACC Flag in the *FLG section: MAXITR multiplied by 10 and other parameters divided by 10.
2. The retrieval is stopped when any of the above criteria are satisfied (tested in swprtv.for)
3. The ChiSq statistic is the sum of the contributions from the A priori and Measurements, evaluated in module chisq.for, and then divided by the number of measurements in swprtv.for, i.e. should equal about 1 if only the instrument noise is the limiting factor.

Example

*CNV
    CHILIM=2.0 MAXITR=5

*FMZ Section (Optional)

Description

Change internal forward model altitude grid

Format

Multiple fields, single type, order is significant

Field	Type	Description
FMZ	R*4	Nominal Foward Model Altitudes [km]	(increasing monotonically)

Notes

1. The main purpose of this section is to allow a finer (eg 1km) forward model grid to be used to investigate problems with 3km representation of the true atmospheric profile, or to set default altitudes to match different scan pattern tangent points.
2. Typically the forward model should have a level 3km below the lowest retrieval level and 5-20km spacing above the highest retrieval level up to 120km (which is the default forward model grid)
3. Additional altitudes will be inserted for nominal retrieval levels which do not match the forward model
4. For pT retrievals on a tangent point grid, altitudes will be adjusted to maintain hydrostatic balance.
5. Prior to v10may07, MORSE used a fixed set of altitudes for the default forward model grid, set in mseini.for, based on the original full resolution 17 sweep nominal tangent altitudes. From v10may07 onwards, the default is now set in drvlev.for and based on the retrieval levels. This should therefore adapt itself to the various different scan patterns without the user having to adjust the grid manually via this *FMZ section

Example

*FMZ
    3 4 5 6 7 8 9 10 11 12 13 14 15 18 21 24 27 30 33 36 39 42
    47 52 60 68 76 85 100 120

*HIT Section (Optional)

Description

Spectroscopic Database file (eg HITRAN binary)

Format

Single Field

Field	Type	Description
HITFIL	C*80	Name of binary spectroscopic database file

Notes

1. A spectroscopic database file is required if any absorbing molecules have HITRAN ID 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

*L2P Section (Optional)

Description

Previously retrieved Level 2 profiles

Format

Multiple fields, single type, order is significant

Field	Type	Description
L2PFIL	C*80	Name of .atm file generated by MORSE for the same limb scan.

Notes

1. 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).
2. Original profiles are only replaced over the altitude range of the subsequent profile, unlike in the RFM where the entire profile is overwritten.
3. Profiles retrieved in a different scan, ie on different altitudes, should be included in the *CLI section.
4. 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 upper atmosphere (especially pT) in each retrieval.
5. The *SWEEP profile, if present, is ignored in MORSE v3 - see the *L1C section for updating L1C tangent altitudes.

Example

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

*LUT Section (Optional)

Description

Directories for Look Up Tables

Format

Multiple fields, single type, order is significant (Note 1)

Field	Type	Description
LUTDIR	C*80	Directory to be searched for CS*DAT files

[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
4. Trailing '/' on LUTDIR is optional

Example

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

*NTE Section (Optional)

Description

Vibrational temperature filenames

Format

Multiple fields, single type, order is not significant.

Field	Type	Description
NTEFIL	C*80	Name of .nte file

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.
3. For non-LTE, MORSE (v01MAY07 or later) will accept vibrational temperatures using either the RFM .nte files or within standard .atm files using the *gas(iso)(vib) label. For VT retrievals, the output is written to the .atm and .rtv files in this format.

Example

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

*OUT Section (Optional)

Description

Rename Output Files

Format

Multiple PARAMETER=VALUE fields, any order.

Field	Type	Description	Default
DIR=	C*76	Output directory	[local directory]
ACV=	C*76	A Priori Covariance	morse.acv
APR=	C*76	A Priori Vector	morse.apr
ATM=	C*76	Retrieved Atmosphere	morse.atm
COV=	C*76	Retrieval Covariance	morse.cov
DIA=	C*76	Diagnostics	morse.dia
RES=	C*76	Residual Spectra	morse.res
RTV=	C*76	Retrieval Vector	morse.rtv
SWP=	C*76	Sweep Diagnostics	morse.swp

Notes

1. The DIR=VALUE (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/

*SHP Section (Optional)

Description

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

Format

Multiple PARAMETER=VALUE fields, limited set of VALUEs, any order

Field	Type	Value	Description
[gas]=	C*3	VOI	Voigt line shape
		CHI	Chi Factor
		LOR	Lorentz line shape
		DOP	Doppler line shape

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 [gas] parameter values are the chemical formulae of any 'line' molecule (ID <50)
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 [gas] parameter can be replaced by an asterisk * which will set 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

*XSC Section (Optional)

Description

Directories for Heavy Molecule Cross Section files

Format

Character strings, order is significant (Note 1)

Field	Type	Description
XSCDIR	C*80	Directories for .xsc files

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. A trailing '/' character is added if none is present.
5. 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)
6. 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