# OMPS-LP Retrieval Software¶

This page describes details of the OMPS-LP retrieval software such as retrieval settings and input/output formats. For an overview of the retrieval software and the classes therin try the Retrieval Overview page.

The class OMPSRetrieval is the top level controlling class for the Ozone Mapping and Profiler Suite - Limb Profiler (OMPS-LP) retrieval. It is generally called from a short setup script such as:

orbit_number, image_number, slit_number = get_next_image_to_process()
omps = OMPSRetrieval( oribit_number, image_number, slit_number )
omps.ret_opt['option_name'] = value
output = omps.retrieve_profiles()
save_to_output_file( output )
set_image_as_processed( orbit_number, image_number, slit_number )


## Required Input Files¶

### OMPS-LP level 1 radiance file¶

The level one radiance file is used to provide the retrieval with the OMPS-LP measurements and, if required, measurement noise. The level 1 file is also used to determine the measurements’ geometry and time.

For simulation purposes the measurements are assumed to occur instanteously in both time and space and do not account for changes in solar geometry or instrument position over the course of an exposure. The reported latitude and longitude of a retrieved profile are assumed to be the latitude and longitude of the 35km tangent point.

To determine the measurement geometry the spacecraft position is used in conjunction with the 35km tangent point and the center of the earth to compute the boresight plane of the instrument. The boresight is then rotated within the plane to obtain the lines of sight at each tangent altitude.

The level 1 radiance file is assumed to be an HDF5 file with the following fields and sizes

 /GRIDDED_DATA /Wavelength (image x sensor x wavelength) The wavelengths in nanometers /Radiance (image x sensor x wavelength) The radiance measurements in units of W/m^2/nm/ster /SNR (image x sensor x wavelength) The signal to noise ratio of radiances. Currently this is not used, and the SNR is assumed to be 100. However it is included for forward compatibility. The radiance uncertainty is assumed to be Radiance/SNR. /Bandpass (image x sensor x wavelength) The full-width half-max spectral point spread function in nanometers. /TangentHeight (image x sensor x altitudes) The tangent height of each line of sight in kilometers /GEOLOCATION_DATA /Latitude_35km (image x sensor) The latitude of the tangent point of the 35km line of sight /Longitude_35km (image x sensor) The longitude of the tangent point of the 35km line of sight /SpacecraftLatitude (image) The latitude of the spacecraft corresponding to the 35km line of sight /SpacecraftLongitude (image) The longitude of the spacecraft corresponding to the 35km line of sight /SpacecraftAltitude (image) The altitude of the spacecraft corresponding to the 35km line of sight

### OMPS-LP ancillary file¶

The ancillary file is used to setup the temperature, pressure, and number density profiles for the background atmosphere. If availabel the tropopause is also used to improve the lower bound of the ozone retrieval. If ancillary files are not available the retrieval can be configured to use ECMWF, or other background climatologies. If ancillary files are used the following fields are required:

 /GRIDDED_DATA /Altitude (altitude) The altitudes at which the pressure, temperature and number density profiles are specified. Assumed to be in kilometers. /Temperature (image x sensor x altitude) Temperature in Kelvin /Pressure (image x sensor x wavelength) Pressure in pascals /AirDensity (image x sensor x wavelength) Air number density in cm^-3 /GEOLOCATION_DATA /Latitude (image x sensor) The latitude of the profiles /Longitude (image x sensor) The longitude of the profiles /Date (image) The date of the profiles in the format YEARMONTHDAY, with zero padding. For example June 7th, 2006 is 20060607 /Time (image) The time of the profiles in seconds since midnight of the day given by Date.

## Retrieval Output¶

The output of the retrieval is returned as a python dictionary containing the retrieved species as well as diagnostic information. The fields in the dictionary are typically accessed as follows:

output       = omps.retrieve_profiles()
latitude     = output['omps_geometry','latitude']
ozone_valid  = output['retrieved','o3_valid']
ozone_full   = output['retrieved','o3']


The following fields are available in the output dictionary.

### Geolocation Information¶

Contains basic information about the geometry and location of the retrieval.:

latitude = output['omps_geometry','latitude']

omps_geometry
latitude
Latitude of the 35km tangent point.
longitude
Longitude of the 35km tangent point.
mjd
Modified Julian Date (days since November 17th, 1858) of when the image was acquired.
sza
Solar zenith angle of the 35km tangent point.

### Retrieval Information¶

Contains the options used for the retrieval as well as basic instrument information.:

image_num = output['retrieval_info','image_num']

retrieval_info
ret_opt
Contains the dictionary of the options set in the retrieval.
image_num
zero based image number for the orbit.
orbit_num
orbit number.
slit_num
slit number, 0 = left, 1 = centre, 2 = right.

### Species Profiles¶

Contains the retrieved species profile, both the valid version, which has been truncated above/below the retrieval limits and the full profile used in the radiative transfer model. Profiles are all provided on a 1km grid from 0.5km to 99.5km. Invalid values are filled with nans.:

alts  = np.arange(0.5,100.0,1.0)
ozone = output['retrieved','o3']
plt.plot( ozone, alts )

retrieved
o3
Retrieved ozone profile as used in the radiative tranfer model
o3_valid
Retrieved ozone profile truncated to the valid altitude range.
aero
Retrieved aerosol profile as used in the radiative tranfer model.
aero_valid
Retrieved aerosol profile truncated to the valid altitude range.
albedo
Retrieved albedo used in the radiative transfer model.

### Measurement Vectors¶

Contains the measured and modelled vectors used for the retrieval. The modelled vectors are for the final iteration of the species.:

alts         = np.arange(0.5,75.0,1.0)
ozone_y      = output['retrieved','o3_ymeas']
ozone_f      = output['retrieved','o3_yret']
num_meas_vec = 8
for i in range(num_meas_vec):
plt.plot( ozone_y[np.arange(0,75) + 75*i], alts,color='b' )
plt.plot( ozone_f[np.arange(0,75) + 75*i], alts,color='r' )

retrieved
o3_ymeas
The ozone measurement vector created from the radiances provided in the level 1 radiance field. Measurement vectors are stacked so will have a length of n altitudes * m wavelengths.
o3_yret
The ozone measurement vector created from the modelled radiances at the last iteration of the retrieval. Stacked in the same way as the measured vector.
aero_ymeas
The aerosol measurement vector created from the radiances provided in the level 1 radiance field. Measurement vectors are stacked so will have a length of n altitudes * m wavelengths.
aero_yret
The ozone measurement vector created from the modelled radiances at the last iteration of the retrieval. Stacked in the same way as the measured vector.
alb_ymeas
The albedo measurement vector from the measured level 1 radiances.
alb_yret
The albedo measurement vector from the modelled level 1 radiances.

Contains the measured and modelled radiances use for the retrieval. The modelled radiances are for the final iteration of the species. All radiances are in units of photons/cm^2/nm/s/ster.

modelled radiances used in the ozone retrieval.
measured radiances used in the ozone retrieval.
o3_wavel
wavelengths (nm) corresponding to the radiances used in the ozone retrieval.
modelled radiances used in the aerosol retrieval.
measured radiances used in the aerosol retrieval.
aer_wavel
wavelengths (nm) corresponding to the radiances used in the aerosol retrieval.
modelled radiances used in the albedo retrieval.
measured radiances used in the albedo retrieval.
alb_wavel
wavelengths (nm) corresponding to the radiances used in the albedo retrieval.

## Retrieval Options¶

Several options are available to change the speed/accuracy of the retrievals as well as input/output directory structures. All options are set through:

omps = OMPSRetrieval( oribit_number, image_number, slit_number )
omps.ret_opt['option'] = value


The property name is case senstive and the value may be a scalar, list or an array, depending on the option. The following options are available.

### Retrieval Settings¶

These options control the general flow of the retrieval program, including what species are retrieved, how they are coupled and what optimization technique is used.

retrieval_order (list of strings)

A combination of the strings ‘albedo’, ‘aerosol’, ‘ozone’ which determines the number of retrievals to run and their order. This is what couples the retrieval of one species to another. The default is [‘albedo’, ‘aerosol’, ‘ozone’, ‘albedo’, ‘ozone’]. It is recommended to perform an aerosol retrieval before ozone, particularly during periods of enhanced extinction, as this improves the radiance simulations used in the Chappius triplet. As well, it is recommended to perform an albedo retrieval before aerosol, as the longer aerosol wavelengths are more strongly affected by albedo.

max_iter (list of scalars)

The number of iterations to do for each of the retrievals, should be the same length as retrieval_order if set. Default is [2,5,2,5,7]. 5 iterations is generally sufficient for the LM retrieval, while 10-20 is generally recommended for the MART technique.

retrieval_method (list of strings) [Default: 'LM']

The optimization technique to be used in the retrieval. Can be either ‘LM’ for Levenberg-Marquardt or ‘MART’ for the multiplicative algebraic reconstruction technique.

### Apriori Settings¶

These settings change the initial state of the atmosphere. They have minimal effect on the retrieval results, provided the LM or MART techniques are used and sufficient iterations are performed for convergence.

ozone_apriori (str) [Default: 'labow']

Initial guess for ozone.

• labow - uses the Labow Ozone climatology. Sets up a 1D ozone climatology that is sampled from Labow at the latitude/longitude/time of the 25km tangent point
• omps_l2 - loads in the ozone from the official NASA level 2 data file for that scan. The location of the file is dictated by the option ‘omps_l2_folder’
aerosol_apriori (str) [Default: user_defined']

Inital guess for aerosol.

• user_defined - loads an aerosol profile from the file set by the option ‘aerosol_apriori_filename’
• omps_l2 - loads in the aerosol from the official NASA level 2 data file for that scan. The location of the file is dictated by the option ‘omps_l2_folder’
no2_apriori (string) [Default: 'pratmo']

Initial guess for NO2.

• pratmo - uses the Prathers NO2 climatology. Sets up a 1D climatology that is sampled from Prathers at the latitude/longitude/time of the 25km tangent point
albedo_apriori (string or float) [Default: 0.3]

Initial guess for the gray lambertian reflectivity of the Earth’s surface. Default is 0.3

• scalar - Sets the albedo to the scalar value
• omps_l2 - Uses the retrieved albedo from the official NASA level 2 data file for that scan. The location of the file is dictated by the option ‘omps_l2_folder’
• None - sets albedo to 0.3
background : string

Background pressure, temperature and number density profiles to be used in the retrieval

• ecmwf - Uses the European Centre for Medium-Range Weather Forecasts operation product. MSIS-90 is merged in above the highest provided pressure level.
• msis - Uses the MSIS-90 atmospheric model
• omps_anc - Uses the atmospheric state provided in the OMPS level 2 ancillary files. Altitudes above 80km are scaled MSIS-90

### Input/Output Options¶

omps_l1_folder (string)

The folder name where the OMPS L1 files are stored, default is r’\utls\users\scratch\OMPS_L1\’

omps_l2_folder (string) [Default: r'\utls\users\scratch\OMPS_L2\']

The folder name where the OMPS L2 files are stored. The level 2 files are only necessary if the retrieval uses omps_l2 as the apriori.

omps_anc_folder (string) [Default: r'\utls\users\scratch\OMPS_L2\']

The folder name where the OMPS Ancillary files are stored.

output_folder (string) [Default: r'\utls\users\scratch\OMPS_L2_OSIRIS\']

Sets the folder to which the output file will be written

output_file (string) [Default : None]

Name of the output hdf5 file where the results are written. Default is None where the file name is “OMPS_L2_” + orbit ”.h5”

num_images_in_orbit (int) [Default: None]

Number of images that will be processed for this orbit. This changes the size of the output h5 file to be (num_alts x num_images_in_orbit x num_slits). Default is None, and the number of images will be determined from the number of radiance profiles in the level 1 gridded data files. Note: this will only take effect if the h5 file does not yet exist. If it does this setting will be ignored and the existing tables will be populated.

These are primarily options that affect the speed/accuracy of the retrieval.

scatterorder (list of scalar)

The number of orders of scatter to use in the radiative transfer model. Each scalar corresponds to the string in the list given to retrieval_order. If a single scalar is given all retrievals will use this value. Default is 15

num_diffuse_profiles (int) [Default: 1]

Number of diffuse profiles in the radiative transfer model.

diffuse_point_altitudes (string, or 1d array)

Altitude of diffuse points on each diffuse profile. Can be specified as a 1d array, or as a string. Default placement is 1 diffuse point every 1km. The following strings are accepted

• ‘verylow’ : places 1 diffuse point at the ground, then every 5km up to 100km
• ‘low’ : places 1 diffuse point at the ground, then every 3km up to 100km
• ‘moderate’ : places 1 diffuse at the ground, then every 1km until 60km, every 3km until 80, and every 5km until 100km.
• ‘version_1_00’ : places 1 diffuse point at the ground, then every 2km up to 25km, then every 5km up to 100km.
omps.ret_opt['diffuse_point_altitudes'] = 'version_1_00'


Alternatively, the altitudes are specified manually if the variable is set as an array. For example:

omps.ret_opt['diffuse_point_altitudes'] = numpy.arange(500, 100500, 2000)


will place a diffuse point every 2km, starting at 500m. Generally, it is also recommended to place a diffuse point just above the ground.

wavel_samples (int or array) [Default: 1]

This handles the oversampling of radiance which is convolved down by the instrument model. The number specifies how many radiances are integrated for each measured pixel. If an integer is given all pixels have the same oversampling. If an array is given the number of samples is interpolated as a function of wavelength, given by wavel_samples_nm.

wavel_samples_nm (array) [Default: None]

Same size as wavel_samples. If wavel_samples is an integer this entry is ignored.

vert_samples (int) [Default: 1]

Number of lines of sight per pixel. Default value is one.