MORSE Driver Table

15NOV24

In this sense it is similar to the RFM, although in the RFM most optional sections require the relevant 3-character flag in the *FLG section to 'enable' the option, while MORSE automatically uses any optional section in the driver table, without any need for an associated flag.

Structure of MORSE Driver Table
Mandatory sections (in this order)
1.	*HDR	Comment record written to output file headers
2.	*FLG	Option flags
3.	*L1C	Input spectra
4.	*ALT	Vertical grid levels
5.	*RTV	Target quantities to be retrieved
6.	*MIC	Microwindow list
7.	*ATM	Atmospheric profiles
8.	*ILS	Instrument Line Shape files, or
	*SRF	Spectral Response Function files
9.	*FOV	Field of View Shape (omitted if nadir-viewing)
Optional sections (in any order)
	*ACC	Accuracy settings
	*APR	A Priori specification
	*CLD	Cloud Detection Criteria
	*CNV	Convergence Criteria
	*FIN	Internal spectral fine grid
	*GRD	Irregular Spectral Grid
	*HIT	HITRAN Database
	*LUT	Look Up Table Filenames
	*NTE	Vibrational Temperatures for non-LTE forward model
	*OUT	Specify Output Files
	*PIX	Limit range of pixels to be retrieved
	*SFC	Surface parameters
	*SHP	Specify line shapes for line-by-line calculations
	*SVD	SVD-compressed Look Up Tables
	*XSC	Directories for Molecular Cross Sections
Termination Record (last record that will be read)
	*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 'carriage return' <CR> after the *END)

The first 8 sections (9 for limb-viewing) are mandatory and the sequence is fixed. 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 200 characters is ignored (set by value LENREC in module lenrec_sub.f90)
• 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
• Character fields do not require quotation marks ( ' or " )
• The various fields can be distributed over an arbitrary number of records
• Order may be significant — depends on the type of section.

Keyword Field

A special class of field is of the form PARAM=VALUE (no spaces around the '=' sign). Here PARAM is one of a predefined set of keywords (depending on the section) and VALUE is the string or numerical value assigned to it.

Variable Types

The following notation is used when describing the type of variable represented by each Field in the driver table. Storage values are nominal, and actually defined by the kind_dat.f90 module.

Type	Description	Storage
I	Integer	4 bytes
R	Real	4 bytes
D	Double Precision	8 bytes
Cn	Character string, length n	n bytes

Tokens

To avoid having to write multiple driver tables to process different filenames, in many cases the input/output filenames can use 'tokens', which are expanded according to various parameters extracted from the L1C input file (for that reason the L1C input filename itself cannot use tokens).

Tokens can also be used as part of filename templates, for example replacing all the absorbing species with '#GAS'

Tokens are of the form '#ABC' (always uppercase) and are expanded as follows:

Token	Expansion	Description
L1C parameter tokens
#HMS	C6	[hhmmss] Hours, minutes, seconds of orbit start
#YMD	C8	[yyyymmdd] Year, month, day of orbit start
#ORB	≤C10	Orbit number, truncated (eg '12345')
#INS	≤C10	Instrument identifier, truncated (eg 'IASI-A')
#SAT	≤C10	Satellite identifier, truncated (eg 'MetOp-A')
Filename template tokens
#GAS	≤C7	Absorbing molecule, lower case (eg 'co2', 'f11')
#MIC	≤C8	Microwindow label, as specifed in *MIC section.

Examples

morse_nh3.drv (IASI NH3 retrieval - nadir-viewing)

morse_pt.drv (MIPAS Pressure/Temperature Retrieval - limb-viewing)

morse_h2o.drv (MIPAS Water Vapour Retrieval - limb-viewing)

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

*GRD Section (Optional)

Description

Irregular Spectral Grid for internal forward model calculations

Format

Multiple records, any order

Field	Type	Description
GRDFIL	C200	Name of irregular grid file

Notes

1. MORSE can use either of the RFM irregular grid file formats: .grd files or irregular spectral files
2. The irregular grid filename may contain a '*' character. After all explicit files are read, the '*' is expanded as the label of any microwindow which does not yet have an irregular grid file assigned.

Example

*GRD
    ./examples/iasi_0.25.grd

Description

Filenames for Look Up Tables of absorption coefficient

Format

Multiple fields, arbitrary order

Field	Type	Description
LUTFIL	C200	Name of LUT file

Notes

1. One LUTFIL string may include #MIC and/or (usually both) #GAS tokens, which will be used as a filename template. Once all the explicitly named LUT files are checked, the code will search for files containing the remaining #MIC/#GAS combinations.

Example

*LUT
[need to add some usable examples]

Description

Vibrational temperature filenames

Format

Multiple fields, single type, order is not significant.

Field	Type	Description
NTEFIL	C200	Name of .nte file

Notes

1. MORSE will accept vibrational temperatures using either the RFM .nte files (entered in this section) or, more simply, within standard .atm files using the *gas(iso)(vib) label.
2. Look Up Tables cannot be used in conjunction with non-LTE calculations.

Example

*NTE
 co2_day_200km.nte  ! mid-lat daytime vib.temps

Description

Specify Output Files

Format

Multiple PARAMETER=VALUE fields, any order.

Field	Type	Description	Default
OUTDIR=OUTDIR	C193	Output directory	[local directory]
ATMFIL=ATMFIL	C193	Retrieved Atmosphere	no output
DIAFIL=DIAFIL	C193	Diagnostics	no output
RESFIL=RESFIL	C193	Residual Spectra	no output
RSMFIL=RSMFIL	C193	Resume file	morse.rsm
RTVFIL=RTVFIL	C193	Retrieval Vector	morse.rtv
SWPFIL=SWPFIL	C193	Sweep Diagnostics	no output

Notes

1. Apart from morse.log, only the .rtv file is written by default, and .rsm is written if the RSM Flag is set. Other output files are created by assigning names using this section (including re-assigning the name of the .rtv file).
2. The OUTDIR 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.
3. Output files are listed in the morse.log file when this section of the driver table is read.
4. The module outcom_dat.f90 contains the default and assigned output filenames.
5. 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 morse.f90 if you really do need to change it).
6. Output file names can contain tokens, eg #YMD and #ORB (upper case) which will be expanded to the 8-digit date, eg '20181208', and 5-digit orbit number eg, '05234' in the output filenames.

Example

*OUT
    RTVFIL=morse_#ORB.rtv
    ATMFIL=morse_#ORB.atm
    outdir=../Morse_Outputs/

Description

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

Format

Multiple records, any order

Record structure: SHPNAM GAS(1) GAS(2) ... GAS(N)

Field	Type	Description
SHPNAM	C3	Lineshape to be used
GAS	C7	Molecule to which lineshape is applied, or '*'

Allowed values for SHPNAM

Field	Description
VOI	Voigt Lineshape
LOR	Lorentz Lineshape
DOP	Doppler Lineshape
VVW or VAN	Van Vleck Weisskopf Lineshape
CHI	Voigt plus Chi-factor

Notes

1. As RFM *SHP section.

Example

An unrealistically complicated example ...

*SHP
     Chi-factor  CO2    ! Use CO2 sub-Lorentzian wings
     LORENTZ  H2O CH4   ! Use Lorentz shape for H2O and CH4
     LORENTZ  N2O       ! Also N2O
     VOI         *      ! Use Voigt shape for all other absorbers [default anyway]
     DOPP CO            ! Doppler shape for CO

Description

Filenames for (MIPAS) SVD-compressed Look Up Tables

Format

Multiple fields, arbitrary order

Field	Type	Description
SVDFIL	C200	Name of SVD-compressed LUT file CS*DAT

Notes

1. The SVDFIL filename may contain a '*' character, which is then expanded for the microwindow and absorber ID for any missing data.

Example

*LUT
    ./examples/CS_PT__0511_01.DAT ! pT MW#501 H2O LUT
    ./examples/CS_PT__0511_02.DAT ! pT MW#501 CO2 LUT
    CS_*DAT            ! all other PT MWs & absorber LUTs

Description

Filenames for molecular Cross Section files

Format

Character strings, order is not significant.

Field	Type	Description
XSCFIL	C200	Filenames for .xsc files

Notes

1. If XSCFIL contains the '*' character, this is expanded to the molecule name (lower case, with 'f' numbers for CFCs/HCFCs, eg 'f12', 'f23') of any cross-section molecules which do not have an explicitly assigned .xsc file.

Example

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

• MORSE Index