# The TIR Engine¶

The `TIR`

engine solves the radiative transfer equation in the thermal infra-region on a true spherical Earth.

Note

The `TIR`

model should be used with caution for:

Extremely optical thick conditions like clouds. The code does not handle the large optical depths very well.

Nadir geometries. They are supported but the surface emission is a simple black body emitter with scalar emissivity.

SASKTRAN-TIR is a radiative transfer model designed for limb viewing applications in the thermal infrared spectral region. It is recommended to use this model for applications where the radiative source at the target wavelengths is dominated by thermal emissions, meaning that the contribution from solar scattering can be ignored. Typically, this occurs for wavelengths larger than 5000 nm. Nadir viewing is also supported where the surface is modeled as a black body with a constant user-specified emissivity.

- Features
Scalar radiative transfer computations for Limb and Nadir lines of sight

Scalar weighting functions computations for species’ number density

Supports refractive ray tracing

Supports varying temperature and atmospheric properties along the line of sight

- Limitations
Basic black body surface model used in Nadir geometries

Currently this is no support for non-LTE effects, continuum absorption, and line-mixing

## Weighting Functions¶

SASKTRAN-TIR supports the same weighting function interface as SASKTRAN-HR, and supports multiple-species weighting functions with a similar interface to SASKTRAN-Disco.

```
# Standard atmosphere configuration
atmosphere = sk.Atmosphere()
atmosphere['o3'] = sk.Species(sk.HITRANChemical('O3'), sk.Labow())
atmosphere['no2'] = sk.Species(sk.HITRANChemical('NO2'), sk.Pratmo())
```

```
atmosphere.wf_species = 'o3' # single species syntax
```

```
atmosphere.wf_species = ['no2', 'o3'] # multiple species syntax
```

```
# calculate radiance and weighting functions
rad, wf = engine.calculate_radiance()
```

To compute temperature weighting functions:

```
engine.do_temperature_wf = True
```

### Shape of `wf`

¶

- Length definitions for this section
`lwav = len(engine.wavelengths)`

`llos = len(geometry.lines_of_sight)`

`lwfs = len(atmosphere.wf_species)`

`lwfa = len(weighting function altitudes)`

The shape of `wf`

depends on the syntax you used to specify the weighting functions. If you used the single species
syntax to specify `atmosphere.wf_species`

then the shape of `wf`

is `(lwav, llos, lwfa)`

. If you used the
multiple species syntax then the shape is `(lwav, llos, lwfs, lwfa)`

.

## Engine Options¶

### Weighting Functions¶

- EngineTIR.wf_heights¶
Heights, in meters, to compute analytic weighting functions at.

**Default:**`np.linspace(500, 99500, 100)`

# 500, 1500, 2500, …, 99500

- EngineTIR.wf_widths¶
Weighting function widths. The weighting functions determine the effect of perturbing a species population at each height specified by

`wf_heights`

on the radiance. The property wf_widths species the vertical distance from each value in`wf_heights`

to the height where the perturbation is zero. Therefore,`wf_heights`

and`wf_widths`

must have identical lengths.i.e. for a weighting function calculation at

`wf_heights[i]`

, the perturbation is maximum at`wf_heights[i]`

and decreases linearly (with height) to 0 at`(wf_heights[i] - wf_widths[i])`

and`(wf_heights[i] + wf_widths[i])`

.**Default:**`np.array([1000] * 100)`

# sets a width of 1000 m at every height in wf_heights

- EngineTIR.do_vmr_wf¶
Controls the units of gas species weighting functions. The default setting configures weighting functions to be given in (radiance / number density) where number density has units of cm^-3. Setting this property to True tells the engine to calculate weighting functions with units of (radiance / VMR).

**Default:**False

- EngineTIR.do_temperature_wf¶
Set this property to True to enable temperature weighting function calculations.

**Default:**False

### Integration¶

- EngineTIR.adaptive_integration¶
A boolean property that, if True, enables dynamic cell splitting during the radiative transfer integration. During the ray tracing process, the line of sight is split into cells based on the intersection of the line of sight with geometric shapes used to split the atmosphere into homogeneous layers. When the optical depth of a cell is computed, the cell is split if one or both of the following conditions are satisfied:

The optical depth of the cell exceeds the value specified by the property

`max_optical_depth_of_cell`

The ratio of the smaller of the two values of extinction at the endpoints of the cell to the larger value is less than the property

`min_extinction_ratio_of_cell`

**Default:**True

- EngineTIR.max_optical_depth_of_cell¶
Set the maximum optical depth of a single cell is allowed to have before it is split into two cells, when adaptive integration is enabled. If the property

`adaptive_integration`

is set to False, this property has no effect.**Default:**0.1

- EngineTIR.min_extinction_ratio_of_cell¶
Set the minimum ratio between the extinction at the endpoints of single cell that is allowed before the cell is split, when adaptive integration is enabled. If the property

`adaptive_integration`

is set to False, this property has no effect. The ratio is calculated as the smaller of the two extinction values divided by the larger.**Default**0.9

- EngineTIR.linear_extinction¶
If this property is set to True, the engine calculates the optical depth of a cell by allowing the extinction to vary linearly with height, between the values at the endpoints of the cell. If this property is set to False, the extinction of a cell is constant, calculated as the average of the values at the endpoints.

**Default:**True

### Geometry and Atmosphere¶

- EngineTIR.ground_emissivity¶
Sets the scalar emissivity of the surface of the Earth. If the line of sight ends at the ground, the emission from the Earth’s surface must be taken into account. In the TIR engine this emission is modelled as a black body with constant emissivity. For limb-viewing geometries this setting will have no effect as there are no scattering effects in the TIR engine.

**Default:**1

- EngineTIR.refraction¶
If set to true, then refractive ray tracing is performed for the observer line of sight rays.

**Default:**false

- EngineTIR.surface_elevation¶
Sets the surface elevation in meters.

**Default:**0 m

- EngineTIR.top_of_atmosphere_altitude¶
Sets the altitude of the top of the atmosphere. Above this altitude it is assumed there is no atmosphere. Due to the assumption of local thermodynamic equilibrium within the Thermal InfraRed engine, increasing the value above 100000 m is not recommended because this simplification can not be used at higher altitudes.

**Default:**100000 m

- EngineTIR.grid_spacing¶
Sets the vertical spacing of homogeneous atmosphere layers in [m].

**Default:**1000 m

- EngineTIR.atmosphere_dimensions¶
Sets the number of dimensions for the atmosphere in the radiative transfer calculation.

Input

Setting

1

One-dimensional in altitude

2

Two-dimensional in altitude and along along the line of sight

**Default:**1

### Performance¶

- EngineTIR.num_threads¶
Controls the number of threads to use when multithreading the radiative transfer calculation. The default value of 0 indicates that the number of threads used will be equal to the number of available logical cores on the target machine.

Setting this value to a lower number than the number of available cores can be useful when running a radiative transfer calculation in the background and the computer is too slow to multitask.

**Default:**0

- EngineTIR.use_cached_cross_sections¶
Designed to enable faster iterative radiance calculations, this setting instructs the TIR engine to compute cross sections using cached results. This can only be done if:

`calculate_radiance()`

has been called at least onceThe only change to the engine object since the last call to

`calculate_radiance()`

is the number density climatology of one or more species in the atmosphere property. The optical properties used for these species must the same; if a new optical property is specified, the resulting radiance will be as though the old optical property were used.The species whose climatologies have been changed must also be set as the

`wf_species`

of the atmosphere property, i.e. only the species for which weighting functions are computed may have their climatologies changed

**Default:**True