# 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 is 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 plan to compute line shapes directly, read par files into `SpectralLines`

objects. The constructor reads files using `readpar`

then rearranges it for line shape calculations. Unnecessary information is dropped and the molecule name, formula, and molar masses are assigned. To compute line shapes, see Computing 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)`

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)

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. Also, in combination with the `cia`

function, a `CIATables`

can be used to compute absorption cross-sections from provided wavenumber, temperature, and partial pressures.

`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]
Pair = 1e5; #air pressure [Pa]
Pco2 = 40; #CO2 partial pressure [Pa]
Pch4 = 0.1; #CH4 partial pressure [Pa]
σ = cia(ν, co2ch4, T, Pair, Pco2, Pch4) #absorption cross-section [cm^2/molecule]
```