# Absorption Data

## Spectral Lines

The model is designed to use the HITRAN database of spectral line data for various atmospheric gases. To download line data, you must register for a free account then search for lines. It's generally best to download all lines for a single gas into a single file, which will have a `.par`

extension. These are text files in fixed-width format and they can be read by functions in `ClearSky`

.

To work with spectral line data directly, use the `readpar`

function to load the data. This function simply parses the fixed-width file into a dictionary of vectors with the appropriate data types. For more information, see the `readpar`

documentation.

If you want to compute line shapes, read par files into `SpectralLines`

objects. The constructor reads files using `readpar`

then does some rearranging for fast line shape calculations. Unnecessary information is dropped and the molecule name, formula, and molar masses are assigned. To compute line shapes, see Line Shapes.

For only high-level calculations, `par`

files can also be loaded directly into gas objects.

`ClearSky.readpar`

— Function`readpar(filename; νmin=0, νmax=Inf, Scut=0, I=[], maxlines=-1, progress=true)`

Read an absoption line file from the HITRAN database, which should have the ".par" extension. These files are available at `https://hitran.org/lbl`

after registering for a free account.

**Keyword Arguments**

`νmin`

: smallest line wavenumber to include`νmax`

: largest line wavenumber to include`Scut`

: smallest spectral line intensity`I`

: array of isotopologue numbers to include (excludes all others)`maxlines`

: maximum number of lines to include (includes only the most intense`maxlines`

lines)`progress`

: whether to display the progress meter

A dictionary of vectors is returned, reflecting the definitions from

- HITRAN website
- Rothman, Laurence S., et al. "The HITRAN 2004 molecular spectroscopic database." Journal of quantitative spectroscopy and radiative transfer 96.2 (2005): 139-204.

Key | Vector Type | Description |
---|---|---|

`M` | `Int16` | HITRAN molecular identification number |

`I` | `Char` | HITRAN isotopologue identification symbol |

`ν` | `Float64` | spectral line wavenumber [cm$^{-1}$] in a vacuum |

`S` | `Float64` | spectral line intensity [cm$^{-1}$/(molecule$\cdot$cm$^{-2}$)] at 296 K |

`A` | `Float64` | Einstein-A coefficient (s$^{-1}$) of a transition |

`γa` | `Float64` | air-broadened half width at half maximum (HWHM) [cm$^{-1}$/atm] at 296 K and 1 atm |

`γs` | `Float64` | self-broadened half width at half maximum (HWHM) [cm$^{-1}$/atm] at 296 K and 1 atm |

`Epp` | `Float64` | lower-state energy of the transition [cm$^{-1}$] |

`na` | `Float64` | coefficient of temperature dependence of air-broadened half width |

`δa` | `Float64` | pressure shift [cm$^{-1}$/atm] at 296 K and 1 atm of the line position with respect to vacuum transition wavenumber |

`Vp` | `String` | upper-state "global" quanta |

`Vpp` | `String` | lower-state "global" quanta |

`Qp` | `String` | upper-state "local" quanta |

`Qpp` | `String` | lower-state "local" quanta |

`Ierr` | `String` | uncertainty indices |

`Iref` | `String` | reference indices |

`*` | `Char` | flag (?) |

`gp` | `String` | statistical weight of upper state |

`gpp` | `String` | statistical weight of lower state |

`ClearSky.SpectralLines`

— TypeOrganizing type for spectral line data of a single gas

Field | Type | Description |
---|---|---|

`name` | `String` | gas name |

`formula` | `String` | gas formula |

`N` | `Int64` | number of lines |

`M` | `Int16` | see `readpar` |

`I` | `Vector{Int16}` | see `readpar` |

`μ` | `Vector{Float64}` | molar mass of isotopologues [kg/mole] |

`A` | `Vector{Float64}` | isotopologue abundance (Earth) |

`ν` | `Vector{Float64}` | see `readpar` |

`S` | `Vector{Float64}` | see `readpar` |

`γa` | `Vector{Float64}` | see `readpar` |

`γs` | `Vector{Float64}` | see `readpar` |

`Epp` | `Vector{Float64}` | see `readpar` |

`na` | `Vector{Float64}` | see `readpar` |

**Constructors**

`SpectralLines(par::Dict)`

Construct a `SpectralLines`

object from a dictionary of line data. That dictionary can be created with `readpar`

.

`SpectralLines(filename, νmin=0, νmax=Inf, Scut=0, I=[], maxlines=-1)`

Read a `.par`

file directly into a `SpectralLines`

object. Keyword arguments are passed through to `readpar`

.

## Collision Induced Absorption (CIA)

The model also makes it easy to include CIA data from HITRAN. These files can be downloaded directly or all at once using the `download_cia.py`

script. Each file contains potentially many tables of absorption data at different wavenumbers and temperatures.

Like the line data, there is a function for reading these CIA files without doing anything else. The `readcia`

function reads a `cia`

file into a vector of dictionaries. Each dictionary represents a table of absorption data. This is the raw data, but it is relatively hard to work with.

A `CIATables`

object arranges each table of absorption data into an interpolator and makes it easy to compute the CIA absorption coefficient at any wavenumber and temperature.

A `CIA`

struct links a `CIATables`

object with the gasses that are inducing absorption. Because concentrations are defined in the gas objects, `CIA`

objects can be used to compute induced absorption cross-sections using only the wavenumber, temperature, and pressure values.

The `cia`

function also provides a number of methods for computing induced cross-sections.

`ClearSky.readcia`

— Function`readcia(filename)`

Read a collision induced absorption data file. These files are available from HITRAN and desribed by this readme. A vector of dictionaries is returned. Each dictionary represents absorption coefficients for a single temperature over a range of wavenumbers. Each dictionary contains:

Key | Type | Description |
---|---|---|

`symbol` | `String` | chemical symbol |

`νmin` | `Float64` | minimum wavenumber of absorption range [cm$^{-1}$] |

`νmax` | `Float64` | maximum wavenumber of absorption range [cm$^{-1}$] |

`npts` | `Int64` | number of points |

`T` | `Float64` | temperature for absorption data [K] |

`ν` | `Vector{Float64}` | wavenumber samples [cm$^{-1}$] |

`k` | `Vector{Float64}` | absorption coefficients [cm$^5$/molecule$^2$] |

`maxcia` | `Float64` | maximum absorption coefficient [cm$^5$/molecule$^2$] |

`res` | `Float64` | ? |

`comments` | `String` | miscelleneous comments |

`reference` | `Int64` | indices of data references |

`ClearSky.CIATables`

— TypeOrganizing type for collision induced absorption data, with data tables loaded into interpolators.

Field | Type | Description |
---|---|---|

`name` | `String` | molecular symbol, i.e. `"CO2-H2"` |

`formulae` | `Tuple{String,String}` | split molecular formulae, i.e `("CO2", "H2")` |

`Φ` | `Vector{BilinearInterpolator}` | interpolators for each grid of absorption coefficients |

`ϕ` | `Vector{LinearInterpolator}` | interpolators for isolated ranges of absorption coefficients |

`T` | `Vector{Float64}` | temperatures [K] for single ranges in `ϕ` |

`extrapolate` | `Bool` | whether to extrapolate using flat boundaries from the coefficient grids in `Φ` |

`singles` | `Bool` | whether to use the single ranges in `ϕ` at all |

The interpolator objects are described in the `BasicInterpolators.jl`

documentation.

**Constructors**

`CIATables(cia::Vector{Dict}; extrapolate=false, singles=false, verbose=true)`

Construct a `CIATables`

object from a dictionary of coefficient data, which can be read from files using `readcia`

. Keywords `extrapolate`

and `singles`

are used to set those fields of the returned object.

`CIATables(filename; extrapolate=false, singles=false, verbose=true)`

Construct a `CIATables`

object directly from file, using `readcia`

along the way.

**Examples**

A `CIATables`

object is function-like. To retrieve the absorption coefficient at a given wavenumber [cm$^{-1}$] and temperature [K], use the object like a function.

```
co2co2 = CIATables("data/cia/CO2-CO2_2018.cia"); #read data
ν = 100; #wavenumber [cm^-1]
T = 288; #temperature [K]
k = co2co2(ν, T) #absorption coefficient [cm^5/molecule^2]
```

The object interpolates and sums all data tables that contain `ν`

and `T`

. If `extrapolate`

is `true`

, boundary values are included whenever the temperature is out of range. If `singles`

is `true`

, data ranges for a single temperature are included whenever they contain `ν`

.

A `CIATables`

can be passed to the `cia`

function to compute an absorption cross-section with different temperatures and pressures.

```
co2ch4 = CIATables("data/cia/CO2-CH4_2018.cia"); #read data
ν = 250; #wavenumber [cm^-1]
T = 310 #temperature [K]
Pa = 1e5; #air pressure [Pa]
Pco2 = 40; #CO2 partial pressure [Pa]
Pch4 = 0.1; #CH4 partial pressure [Pa]
σ = cia(ν, co2ch4, T, Pa, Pco2, Pch4) #absorption cross-section [cm^2/molecule]
```

`ClearSky.CIA`

— TypeContainer for a `CIATables`

object and the two gasses representing the CIA components. Specializes with the type of each gas for fast retreival of absorption cross-sections from CIA data and partial pressures.

Field | Type | Description |
---|---|---|

`name` | `String` | molecular symbol, i.e. `"CO2-H2"` |

`formulae` | `Tuple{String,String}` | split molecular formulae, i.e `("CO2", "H2")` |

`x` | `CIATables` | collision induced absorption tables |

`g₁` | `<:Gas` | first component of CIA pair |

`g₁` | `<:Gas` | second component of CIA pair |

**Constructors**

`CIA(ciatables::CIATables, g₁::Gas, g₂::Gas)`

The name and formulae are taken from `ciatables`

.

`CIA(ciatables::CIATables, gases::Tuple)`

Using the formulae in `ciatables`

, the correct pair of gases is automatically selected from a VarArg collection of gases.

**Example**

A `CIA`

object is function-like. Use it like a function, passing it wavenumber, temperature, and pressure arguments to compute an absorption cross-section. Underneath, the `CIATables`

object is interpolated and partial pressures are computed using the concentrations stored with the gases.

```
#load gases
ν = LinRange(1, 2500, 2500);
Ω = AtmosphericDomain((100,350), 8, (0.9,2e5), 16);
co2 = WellMixedGas("data/par/CO2.par", 0.96, ν, Ω);
ch4 = WellMixedGas("data/par/CH4.par", 1e-6, ν, Ω);
#create CIA object
co2ch4 = CIA(CIATables("data/cia/CO2-CH4_2018.cia"), co2, ch4);
#compute a cross-section
ν = 667;
T = 250;
P = 1e5;
σ = co2ch4(ν, T, P)
```

`ClearSky.cia`

— Function`cia(k, T, Pₐ, P₁, P₂)`

Compute a collision induced absorption cross-section

**Arguments**

`k`

: absorption coefficient [cm$^5$/molecule$^2$]`T`

: temperature [K]`Pₐ`

: total air pressure [Pa]`P₁`

: partial pressure of first gas [Pa]`P₂`

: partial pressure of second gas [Pa]

`cia(ν, x::CIATables, T, Pₐ, P₁, P₂)`

Compute a collision induced absorption cross-section after retrieving the total absorption coefficient from a `CIATables`

object

**Arguments**

`ν`

: wavenumber [cm$^{-1}$]`x`

:`CIATables`

object`T`

: temperature [K]`Pₐ`

: total air pressure [Pa]`P₁`

: partial pressure of first gas [Pa]`P₂`

: partial pressure of second gas [Pa]

`cia(ν::AbstractVector, x::CIATables, T, Pₐ, P₁, P₂)`

Compute a vector of collision induced absorption cross-sections, retrieving the total absorption coefficient from a `CIATables`

object.

**Arguments**

`ν`

: vector of wavenumbers [cm$^{-1}$]`x`

:`CIATables`

object`T`

: temperature [K]`Pₐ`

: total air pressure [Pa]`P₁`

: partial pressure of first gas [Pa]`P₂`

: partial pressure of second gas [Pa]

`cia(ν, x::CIATables, T, Pₐ, g₁::Gas, g₂::Gas)`

Compute a collision induced absorption cross-section, retrieving the total absorption coefficient from a `CIATables`

object and computing partial pressures from gas objects.

**Arguments**

`ν`

: vector of wavenumbers [cm$^{-1}$]`x`

:`CIATables`

object`T`

: temperature [K]`Pₐ`

: total air pressure [Pa]`g₁`

: gas object representing the first component of the CIA pair`g₂`

: gas object representing the second component of the CIA pair

`ClearSky.cia!`

— Function`cia!(σ::AbstractVector, ν::AbstractVector, x::CIATables, T, Pₐ, P₁, P₂)`

Compute a vector of collision induced absorption cross-sections in-place, retrieving the total absorption coefficient from a `CIATables`

object.

**Arguments**

`σ`

: vector to store computed cross-sections`ν`

: vector of wavenumbers [cm$^{-1}$]`x`

:`CIATables`

object`T`

: temperature [K]`Pₐ`

: total air pressure [Pa]`P₁`

: partial pressure of first gas [Pa]`P₂`

: partial pressure of second gas [Pa]