{ "cells": [ { "cell_type": "markdown", "id": "f448d343-355d-45a6-9773-73abe7fac7d2", "metadata": {}, "source": [ "# Introduction" ] }, { "cell_type": "markdown", "id": "50a4eb37-5fb5-49e0-8174-b4b8b29810cf", "metadata": {}, "source": [ "In archNEMESIS, all the parameters we need to simulate the electromagnetic spectrum of a planetary atmosphere are stored into several different Python classes. The sub-division of the input information into the classes was performed so that each class represented key aspects of the radiative transfer modelling, and aiming for the different classes to be independent from each other, so that they can be easily turned on or off based on the user needs. The reference classes hold the information that is fed into the forward model, but they might also be useful for the pre-processing or post-processing of the retrieval. For example, the different classes include methods to easily modify or print the information within the class, perform calculations using this information or produce diagnostic plots." ] }, { "cell_type": "markdown", "id": "ad522171-7393-4012-a3da-d4820f9d00c7", "metadata": { "jp-MarkdownHeadingCollapsed": true }, "source": [ "# Atmosphere\n", "\n", "
\n", "\n", "Summary\n", "\n", "The Atmosphere class includes information, as its name suggests, about the planetary atmosphere we want to model. In particular, it includes information about the planet basic properties (e.g. mass, radius), and more specifically about its atmosphere including the reference vertical profiles for the gaseous species (e.g., altitude, pressure, temperature, gas mixing ratios), as well as for the suspended aerosols in the atmosphere (e.g., dust particles, clouds, etc.). For most applications, the atmosphere of a single column of the planet needs to be defined at a specified latitude and longitude. Nevertheless, the Atmosphere class also includes the possibility of defining reference vertical profiles at multiple latitudes and longitudes.\n", "\n", "
\n", "\n", "\n", "\n", "
\n", "\n", "Description of parameters in class\n", "\n", "Required parameters when writing input files:\n", "\n", "- IPLANET: Planet ID.\n", "- NP: Number of vertical level in the atmospheric profiles.\n", "- NLOCATIONS: Number of locations at which the atmospheric profiles are specified (default: 1).\n", "- LATITUDE: Latitude of the location on the planet.\n", "- LONGITUDE: Longitude of the location on the planet.\n", "- NVMR: Number of gaseous species included in the atmosphere.\n", "- NDUST: Number of aerosol populations included in the atmosphere.\n", "- AMFORM: Flag indicating how the molecular weight should be calculated.\n", "- ID: Gas ID for each of the species included in the atmosphere.\n", "- ISO: Isotope ID for each of the species included in the atmosphere (0 for all isotopes).\n", "- H: Altitude profile (m)\n", "- P: Pressure profile (Pa).\n", "- T: Temperature profile (K).\n", "- VMR: Volume mixing ratio of each species at each altitude level.\n", "- DUST: Aerosol abundance for each aerosol population at each altitude level (m$^{-3}$).\n", "\n", "Optional parameters when writing input files:\n", "\n", "- PARAH2: Fraction of para-H$_2$ profile.\n", "- MOLWT: If AMFORM=0, the atmospheric molecular weight must be explicitly specified (kg mol$^{-1}$).\n", "\n", "Other parameters in class:\n", "\n", "- GRAV: Gravity at each altitude level (m s$^{-2}$).\n", "- RADIUS: Radius of the planet as read from the dictionary (m).\n", "- DUST_UNITS_FLAG: Flag indicating if units of aerosol abundance must be specified in m$^{-3}$ (0 - default) or particles per gram of atmosphere (-1). This flag is automatically activated when reading the information from the standard NEMESIS text files, given that is the units used by NEMESIS.\n", "\n", "\n", "
\n" ] }, { "cell_type": "markdown", "id": "03788d7c-f0e6-4a38-ac5d-7ee1becfaa5d", "metadata": {}, "source": [ "### Planets\n", "\n", "In order to model the atmosphere of different planets, NEMESIS uses an ID number for each of these, and searches some important parameters (e.g., size and mass) to compute the gravitational field at different altitudes and latitudes. Currently, the planets whose IDs have been implemented in the code are:\n", "\n", "
\n", "\n", "| ID | Planet |\n", "| -- | -------- |\n", "| 1 | Mercury |\n", "| 2 | Venus |\n", "| 3 | Earth |\n", "| 4 | Mars |\n", "| 5 | Jupiter |\n", "| 6 | Saturn |\n", "| 7 | Uranus |\n", "| 8 | Neptune |\n", "| 9 | Pluto |\n", "| 10 | Sun |\n", "| 11 | Titan |\n", "| 85 | NGTS-10b |\n", "| 87 | WASP-43b |\n", "\n", "
\n", "

\n", "\n", "The atmosphere of other planets can also be modelled, by including a new ID number in the Python dictionary stored in *Data/planet_data.py*.\n", "\n", "### Gaseous species\n", "\n", "Apart from the gravitational parameters of the planet, the atmosphere is represented by a set of vertical profiles indicating the pressure, temperature and gaseous volume mixing ratios as a function of altitude. In order to define the composition of the atmosphere, different gaseous species are defined using ID numbers. These ID numbers are:\n", "\n", "
\n", "\n", "| ID | Molecule | Isotopes |\n", "| --- | --- | --- |\n", "| 1 | $\\text{H}_2\\text{O}$ | $\\text{H}_2^{16}\\text{O}$, $\\text{H}_2^{18}\\text{O}$, $\\text{H}_2^{17}\\text{O}$, $\\text{HD}^{16}\\text{O}$, $\\text{HD}^{18}\\text{O}$, $\\text{HD}^{17}\\text{O}$, $\\text{D}_2^{16}\\text{O}$ |\n", "| 2 | $\\text{CO}_2$ | $^{12}\\text{C}^{16}\\text{O}_2,$ $^{13}\\text{C}^{16}\\text{O}_2$, $^{18}\\text{O}^{12}\\text{C}^{16}\\text{O}$, $^{17}\\text{O}^{12}\\text{C}^{16}\\text{O}$, $^{18}\\text{O}^{13}\\text{C}^{16}\\text{O}$, $^{17}\\text{O}^{13}\\text{C}^{16}\\text{O}$, $^{12}\\text{C}^{18}\\text{O}_2$, $^{17}\\text{O}^{12}\\text{C}^{18}\\text{O}$, $^{12}\\text{C}^{17}\\text{O}_2$, $^{13}\\text{C}^{18}\\text{O}_2$, $^{18}\\text{O}^{13}\\text{C}^{17}\\text{O}$, $^{13}\\text{C}^{17}\\text{O}_2$ |\n", "| 3 | $\\text{O}_3$ | $^{16}\\text{O}_3$, $^{16}\\text{O}^{16}\\text{O}^{18}\\text{O}$, $^{16}\\text{O}^{18}\\text{O}^{16}\\text{O}$, $^{16}\\text{O}^{16}\\text{O}^{17}\\text{O}$, $^{16}\\text{O}^{17}\\text{O}^{16}\\text{O}$ |\n", "| 4 | $\\text{N}_2\\text{O}$ | $^{14}\\text{N}_2^{16}\\text{O}$, $^{15}\\text{N}^{14}\\text{N}^{16}\\text{O}$, $^{14}\\text{N}^{15}\\text{N}^{16}\\text{O}$, $^{14}\\text{N}_2^{18}\\text{O}$, $^{14}\\text{N}_2^{17}\\text{O}$ |\n", "| 5 | $\\text{CO}$ | $^{12}\\text{C}^{16}\\text{O}$, $^{13}\\text{C}^{16}\\text{O}$, $^{12}\\text{C}^{18}\\text{O}$, $^{12}\\text{C}^{17}\\text{O}$, $^{13}\\text{C}^{18}\\text{O}$, $^{13}\\text{C}^{17}\\text{O}$ |\n", "| 6 | $\\text{CH}_4$ | $^{12}\\text{CH}_4$, $^{13}\\text{CH}_4$, $^{12}\\text{CH}_3\\text{D}$, $^{13}\\text{CH}_3\\text{D}$ |\n", "| 7 | $\\text{O}_2$ | $^{16}\\text{O}_2$, $^{16}\\text{O}^{18}\\text{O}$, $^{17}\\text{O}^{18}\\text{O}$ |\n", "| 8 | $\\text{NO}$ | $^{14}\\text{N}^{16}\\text{O}$, $^{15}\\text{N}^{16}\\text{O}$, $^{14}\\text{N}^{18}\\text{O}$ |\n", "| 9 | $\\text{SO}_2$ | $^{32}\\text{S}^{16}\\text{O}_2$, $^{34}\\text{S}^{16}\\text{O}_2$, $^{33}\\text{S}^{16}\\text{O}_2$, $^{16}\\text{O}^{32}\\text{S}^{18}\\text{O}$ |\n", "| 10 | $\\text{NO}_2$ | $^{14}\\text{N}^{16}\\text{O}_2$, $^{15}\\text{N}^{16}\\text{O}_2$ |\n", "| 11 | $\\text{NH}_3$ | $^{14}\\text{NH}_3$, $^{15}\\text{NH}_3$ |\n", "| 12 | $\\text{HNO}_3$ | $\\text{H}^{14}\\text{N}^{16}\\text{O}_3$, $\\text{H}^{15}\\text{N}^{16}\\text{O}_3$ |\n", "| 13 | $\\text{OH}$ | $^{16}\\text{OH}$, $^{18}\\text{OH}$, $^{16}\\text{OD}$ |\n", "| 14 | $\\text{HF}$ | $\\text{H}^{19}\\text{F}$, $\\text{D}^{19}\\text{F}$ |\n", "| 15 | $\\text{HCl}$ | $\\text{H}^{35}\\text{Cl}$, $\\text{H}^{37}\\text{Cl}$, $\\text{D}^{35}\\text{Cl}$, $\\text{D}^{37}\\text{Cl}$ |\n", "| 16 | $\\text{HBr}$ | $\\text{H}^{79}\\text{Br}$, $\\text{H}^{81}\\text{Br}$, $\\text{D}^{79}\\text{Br}$, $\\text{D}^{81}\\text{Br}$ |\n", "| 17 | $\\text{HI}$ | $\\text{H}^{127}\\text{I}$, $\\text{D}^{127}\\text{I}$ |\n", "| 18 | $\\text{ClO}$ | $^{35}\\text{Cl}^{16}\\text{O}$, $^{37}\\text{Cl}^{16}\\text{O}$ |\n", "| 19 | $\\text{OCS}$ | $^{16}\\text{O}^{12}\\text{C}^{32}\\text{S}$, $^{16}\\text{O}^{12}\\text{C}^{34}\\text{S}$, $^{16}\\text{O}^{13}\\text{C}^{32}\\text{S}$, $^{16}\\text{O}^{12}\\text{C}^{33}\\text{S}$, $^{18}\\text{O}^{12}\\text{C}^{32}\\text{S}$, $^{16}\\text{O}^{13}\\text{C}^{34}\\text{S}$ |\n", "| 20 | $\\text{H}_2\\text{CO}$ | $\\text{H}_2^{12}\\text{C}^{16}\\text{O}$, $\\text{H}_2^{13}\\text{C}^{16}\\text{O}$, $\\text{H}_2^{12}\\text{C}^{18}\\text{O}$ |\n", "| 21 | $\\text{HOCl}$ | $\\text{H}^{16}\\text{O}^{35}\\text{Cl}$, $\\text{H}^{16}\\text{O}^{37}\\text{Cl}$ |\n", "| 22 | $\\text{N}_2$ | $^{14}\\text{N}_2$, $^{14} \\text{N} ^{15} \\text{N}$ |\n", "| 23 | $\\text{HCN}$ | $\\text{H}^{12}\\text{C}^{14}\\text{N}$, $\\text{H}^{13}\\text{C}^{14}\\text{N}$, $\\text{H}^{12}\\text{C}^{15}\\text{N}$ |\n", "| 24 | $\\text{CH}_3\\text{Cl}$ | $^{12}\\text{C}\\text{H}_3^{35}\\text{Cl}$, $^{12}\\text{C}\\text{H}_3^{37}\\text{Cl}$ |\n", "| 25 | $\\text{H}_2\\text{O}_2$ | $\\text{H}_2^{16}\\text{O}_2$ |\n", "| 26 | $\\text{C}_2\\text{H}_2$ | $^{12}\\text{C}_2\\text{H}_2$, $\\text{H}^{12}\\text{C}^{13}\\text{CH}$, $\\text{H}^{12}\\text{C}^{12}\\text{CD}$ |\n", "| 27 | $\\text{C}_2\\text{H}_6$ | $^{12}\\text{C}_2\\text{H}_6$, $^{12}\\text{CH}_3^{13}\\text{CH}_3$ |\n", "| 28 | $\\text{P}\\text{H}_3$ | $^{31}\\text{PH}_3$ |\n", "| 29 | $\\text{C}_2\\text{N}_2$ | $^{12}\\text{C}_2^{14}\\text{N}_2$ |\n", "| 30 | $\\text{C}_4\\text{H}_2$ | $^{12}\\text{C}_4\\text{H}_2$ |\n", "| 31 | $\\text{HC}_3\\text{N}$ | $\\text{H}^{12}\\text{C}_3^{14}\\text{N}$ |\n", "| 32 | $\\text{C}_2\\text{H}_4$ | $^{12}\\text{C}_2\\text{H}_4$, $^{12}\\text{CH}_2^{13}\\text{CH}_2$ |\n", "| 33 | $\\text{GeH}_4$ | $^{74}\\text{GeH}_4$, $^{72}\\text{GeH}_4$, $^{70}\\text{GeH}_4$, $^{73}\\text{GeH}_4$, $^{76}\\text{GeH}_4$ |\n", "| 34 | $\\text{C}_3\\text{H}_8$ | $^{12}\\text{C}_4\\text{H}_2$ |\n", "| 35 | $\\text{HCOOH}$ | $\\text{H}^{12}\\text{C}^{16}\\text{O}^{16}\\text{OH}$ |\n", "| 36 | $\\text{H}_2\\text{S}$ | $\\text{H}_2^{32}\\text{S}$, $\\text{H}_2^{34}\\text{S}$, $\\text{H}_2^{33}\\text{S}$ |\n", "| 37 | $\\text{COF}_2$ | $^{12}\\text{C}^{16}\\text{O}^{19}\\text{F}_2$, $^{13}\\text{C}^{16}\\text{O}^{19}\\text{F}_2$ |\n", "| 38 | $\\text{SF}_6$ | |\n", "| 39 | $\\text{H}_2$ | $\\text{H}_2$, $\\text{HD}$ |\n", "| 40 | $\\text{He}$ | |\n", "| 41 | $\\text{AsH}_3$ | |\n", "| 42 | $\\text{C}_3\\text{H}_4$ | |\n", "| 43 | $\\text{ClONO}_2$ | $^{35}\\text{Cl}^{16}\\text{O}^{14}\\text{N}^{16}\\text{O}_2$, $^{37}\\text{Cl}^{16}\\text{O}^{14}\\text{N}^{16}\\text{O}_2$ |\n", "| 44 | $\\text{HO}_2$ | |\n", "| 45 | $\\text{O}$ | |\n", "| 46 | $\\text{NO}^+$ | |\n", "| 47 | $\\text{CH}_3\\text{OH}$ | |\n", "| 48 | $\\text{H}$ | |\n", "| 49 | $\\text{C}_6\\text{H}_6$ | |\n", "| 50 | $\\text{CH}_3\\text{CN}$ | |\n", "| 51 | $\\text{CH}_2\\text{NH}$ | $^{12}\\text{C}\\text{H}_2^{14}\\text{N}\\text{H}$, $^{13}\\text{C}\\text{H}_2^{14}\\text{N}\\text{H}$, $^{12}\\text{C}\\text{H}_2^{15}\\text{N}\\text{H}$, $^{12}\\text{C}\\text{H}_2^{14}\\text{N}\\text{D}$ |\n", "
\n", "

\n", "\n", "The atmospheric vertical profiles can be read from the *.ref* file, which must be defined following a specific format. This particular file can be read/write using the *read_ref()* and *write_ref()* functions in the Atmosphere class (see Examples). The units of the file are: Altitude (km), Pressure (atm), Temperature (K) and volume mixing ratio (dimensionless). Note that the units of these parameters once the file has been read are different (altitude in m and pressure in Pa), but the read/write functions take this unit conversion automatically into account.\n", "\n", "The *.ref* file also includes some other parameters required for modelling the atmosphere:\n", "\n", "- LATITUDE: The latitude of the profile must be defined to accurately calculate the gravitational field.\n", "- AMFORM: This parameter indicates how the molecular weight of the atmosphere must be calculated. If AMFORM=0, then the molecular weight is assumed to be constant for all altitude levels and must be specified in the *.ref* file. If AMFORM=1, then the molecular weight is calculated internally and independently for each altitude level after the VMRs have been scaled to $\\sum_i{\\mathrm{VMR}_i} = 1$. If AMFORM=2, then the molecular weight is calculated internally and independently for each altitude level but without scaling the molecular abundances. \n", "\n", "\n", "### Aerosols\n", "\n", "Apart from the gaseous species, the atmosphere is also represented by a set of aerosol vertical profiles. These aerosol profiles must be accompanied by a set of optical properties, defined in the Scatter class. Therefore, each of the aerosol populations does not necessarily represent aerosols of different nature (e.g., mineral dust and clouds), but might represent the same aerosol composition with different optical properties (e.g., two different particle size distributions of the same aerosol species).\n", "\n", "archNEMESIS includes a set of functions to calculate the optical properties of aerosols using Mie Theory (see Scatter class), given the complex refractive index of the aerosol species.\n", "\n", "The vertical profiles for the aerosols are defined in the *aerosol.ref* file, which must be defined in a specific format. This particular file can be read/write using the *read_aerosol()* and *write_aerosol()* functions in the Atmosphere class (see Examples). The units of the aerosol vertical profiles in the *aerosol.ref* are m$^{-2}$. Note that this is different from the unit of the file in NEMESIS, which are defined in number of particles per gram of atmosphere.\n" ] }, { "cell_type": "markdown", "id": "e5b48133-97a9-46a4-bd52-b40209dd3074", "metadata": { "jp-MarkdownHeadingCollapsed": true }, "source": [ "# Surface\n", "\n", "
\n", "\n", "Summary\n", "\n", "The Surface class includes the information about the planet’s surface, in the case it has a solid surface. The reflection of light on the surface of the planet can be either modelled following a Lambertian reflectance distribution, where the emissivity and albedo are defined, or following the Hapke reflectance model (Hapke, 2012), where the set of parameters required for this surface model need to be defined. Similar to the Atmosphere class, the Surface class allows the definition of different surface properties at several locations across the planet.\n", "\n", "
\n", "\n", "\n", "
\n", "\n", "Description of used-defined parameters\n", "\n", "Required parameters when writing input files:\n", "\n", "- ISPACE: Spectral units for defining the surface properties (0 - Wavenumber in cm$^{-1}$; 1 - Wavelength in $\\mu$m).\n", "- LOWBC: Flag indicating the type of surface to be considered.\n", "- NLOCATIONS: Number of locations at which the atmospheric profiles are specified (default: 1).\n", "- LATITUDE: Latitude of the location on the planet.\n", "- LONGITUDE: Longitude of the location on the planet.\n", "- TSURF: Surface temperature (K).\n", "- GALB: Ground albedo.\n", "- VEM: Wavelength or wavenumber array at which the surface properties are defined.\n", "- EMISSIVITY: Spectral emissivity of the surface.\n", "\n", "Optional parameters when writing input files:\n", "\n", " - SGLALB: If LOWBC=2 (Hapke), single scattering albedo.\n", " - K: If LOWBC=2 (Hapke), porosity coefficient.\n", " - BS0: If LOWBC=2 (Hapke), amplitude of the opposition effect.\n", " - hs: If LOWBC=2 (Hapke), width of the opposition surge.\n", " - BC0: If LOWBC=2 (Hapke), amplitude of the coherent backscatter opposition effect.\n", " - hc: If LOWBC=2 (Hapke), width of the backscatter function.\n", " - ROUGHNESS: If LOWBC=2 (Hapke), roughness mean slope angle.\n", " - G1: If LOWBC=2 (Hapke), asymmetry factor of the first Henyey-Greenstein function defining the phase function.\n", " - G2: If LOWBC=2 (Hapke), asymmetry factor of the second Henyey-Greenstein function defining the phase function.\n", " - F: If LOWBC=2 (Hapke), parameter defining the relative contribution of G1 and G2 of the double Henyey-Greenstein phase function.\n", "\n", "Other parameters in class:\n", "\n", " - GASGIANT: Flag indicating if planet has a surface (GASGIANT=False) or not (GASGIANT=True).\n", "\n", "
\n" ] }, { "cell_type": "markdown", "id": "561c2df1-29d0-4eb7-af86-6f5866a5df63", "metadata": {}, "source": [ "Whether the surface class for a given retrieval must be included depends on the planet. When the Planet ID is read by archNEMESIS in the Atmosphere class, it will activate a flag indicating whether the planet has a surface or not. In the case the planet has a surface, then archNEMESIS will read the information about the surface.\n", "\n", "The type of surface included in the model caries depending on the value of the LOWBC flag, which essentially defines the type of lower boundary condition in our atmosphere-surface system. This flag can take several values:\n", "\n", "- LOWBC = 0: In this case, only the thermal emission from the surface will be considered, but no reflection of light. The EMISSIVITY parameter defines the spectral emissivity of the surface, while TSURF defines the temperature of the surface.\n", "\n", "- LOWBC = 1: In this case, apart from the thermal emission from the surface, light is reflected following a Lambertian distribution. The EMISSIVITY array still defines the spectral emissivity of the surface ($\\epsilon(\\lambda)$). The parameter GALB defines the albedo of the surface. If GALB is set to be negative, then the spectral albedo of the surface is calculated as $a(\\lambda)$ = 1 - $\\epsilon(\\lambda)$.\n", "\n", "- LOWBC = 2: In this case, apart from the thermal emission from the surface determined by the EMISSIVITY array, the reflection of the directional surface is calculated following the [Hapke model](https://doi.org/10.1017/CBO9781139025683). In order to properly fill the information of this model in the Surface class, we need to define several parameters, described in detail in the [Examples](https://archnemesis.readthedocs.io/en/latest/examples/surface_modes/surface.html)." ] }, { "cell_type": "markdown", "id": "4f17893f-3d02-45bc-a824-7c2428938810", "metadata": {}, "source": [ "# Measurement\n", "\n", "
\n", "\n", "Summary\n", "\n", "The Measurement class includes all the information regarding the instrument setup and measured spectra. In particular, it carries the information about the measured wavelengths and spectra, including the uncertainties in the measurement too. In addition, for each measured spectrum, it specifies the relevant observing angles (i.e., emission, azimuth and solar zenith angles), including any information regarding the reconstruction of the field-of-view (FOV). Finally, this class also carries the information about the instrument line shape, defining the spectral resolution of the instrument, which can be modelled with any arbitrary function defined by the user.\n", "\n", "
\n", "\n", "\n", "
\n", "\n", "Description of used-defined parameters\n", "\n", "Required parameters when writing input files:\n", "\n", "- V_DOPPLER: Doppler velocity between the observed body and observer (km/s).\n", "- LATITUDE: Latitude at the centre of the field-of-view (degrees).\n", "- LONGITUDE: Longitude at the centre of the field-of-view (degrees).\n", "- ISPACE: Spectral units (0 - Wavenumber in cm$^{-1}$; 1 - Wavelength in $\\mu$m).\n", "- IFORM: Flag indicating the units at which the measured spectra are defined.\n", "- NGEOM: Number of observing geometries.\n", "- NAV: For each geometry, number of averaging points needed to reconstruct the field-of-view.\n", "- FLAT: For each geometry, latitude of each averaging point needed to reconstruct the field-of-view (degrees).\n", "- FLON: For each geometry, longitude of each averaging point needed to reconstruct the field-of-view (degrees).\n", "- WGEOM: For each geometry, weight of each averaging point needed to reconstruct the field-of-view.\n", "- EMISS_ANG: For each geometry, emission angle at each averaging point (degrees).\n", "- VCONV: Convolution wavenumbers of wavelengths for each geometry.\n", "- MEAS: Measured spectra.\n", "- ERRMEAS: Uncertainty in the measured spectra.\n", "- FWHM: Full-width at half-maximum of the instrument lineshape (i.e., spectral resolution of the instrument).\n", "\n", "Optional parameters when writing input files:\n", "\n", "- SOL_ANG: If EMISS_ANG$\\geq$0, solar zenith angle for each averaging point in each geometry (degrees).\n", "- AZI_ANG: If EMISS_ANG$\\geq$0, azimuth angle for each averaging point in each geometry (degrees).\n", "- TANHE: If EMISS_ANG$\\lt$0, tangent altitude for each averaging point in each geometry (km).\n", "- ISHAPE: If FWHM$\\gt$0, flag indicating the shape for the instrument function.\n", "- NFIL: If FWHM$\\lt$0, number of points describing the instrument lineshape for each convolution bin.\n", "- VFIL: If FWHM$\\lt$0, spectral points describing the instrument lineshape for each convolution bin.\n", "- AFIL: If FWHM$\\lt$0, instrument lineshape for each convolution bin.\n", "\n", "Other parameters in class:\n", "\n", "- WAVE: Calculation wavelengths or wavenumbers in which to perform the radiative transfer calculations.\n", "- SPECMOD: Modelled spectra.\n", "- VNORM: If IFORM=5, then it defines the wavelength or wavenumber at which the spectra should be normalised to.\n", "\n", "
" ] }, { "cell_type": "markdown", "id": "f409df7e-2d23-469f-aef1-44736695449b", "metadata": { "jp-MarkdownHeadingCollapsed": true }, "source": [ "### Geometry\n", "\n", "Remote sensing of planetary atmospheres can be performed using different kinds of observations such as nadir-viewing, limb-viewing and solar or stelar occultations. In addition, recent measurements of planetary atmospheres also include upward-looking measurements by instruments on the surface. NEMESIS can model the electromagnetic spectrum in any of these types of observations, but the fields of the Measurement class must be filled accordingly to set up the correct geometry.\n", "\n", "\"Drawing\"\n", "\n", "NEMESIS can simultaneously model spectra made with *NGEOM* different observational geometries. For a given geometry, it might be the case that a number of sub-geometries need to be defined to accurately represent the field-of-view of the instrument, which will later be averaged to compute one single spectrum. This number of sub-geometries is defined by *NAV* (i.e., number of averaging points), and the weight of each sub-geometry is defined by *WGEOM*. For each sub-geometry (even if there is just one sub-geometry *NAV* = 1), a number of parameters need to be defined:\n", "\n", "- Latitude and longitude (*FLAT* and *FLON*). If the atmosphere is modelled with different profiles in different locations, then *FLAT* and *FLON* are used to calculate the specific atmospheric profiles relevant for the particular sub-geometry.\n", "\n", "- Solar zenith angle (*SOL_ANG*).\n", "\n", "- Emission angle (*EMISS_ANG*). If the emission angle is $\\lt$90 degrees, then the observation is nadir-viewing. An emission angle equal to 90 degrees indicates a limb-viewing or solar occultation observation. Finally, if the emission angle is $\\gt$90 then that indicates an upward-looking observation.\n", "\n", "- Azimuth angle (*AZI_ANG*). The azimuth angle defines the angle between solar and emission angles projected on the ground. It is defined such that 0 degrees indicates forward scattering.\n", "\n", "- The weight of the averaging point (*WGEOM*) is used to reconstruct the field-of-view of the instrument. NEMESIS will model a spectrum in each sub-geometry (*R*), which will be combined following\n", "\n", "$$\n", "\\bar{R} = \\sum_{i=0}^{\\mathrm{NAV}} R(i) \\times W(i).\n", "$$\n", "\n", "We recommend the users to read the following [example](https://archnemesis.readthedocs.io/en/latest/examples/measurement/measurement_class.html) to get a more detailed description of the definition of the geometry in archNEMESIS.\n", "\n", "### Instrument lineshape\n", "\n", "A spectral measurement is defined by indicating the wavelength points (*VCONV*), the measured spectrum (*MEAS*) and the corresponding uncertainty (*ERRMEAS*). However, a observed spectrum typically represents the convolution of the high-resolution spectrum with the instrumental lineshape. In NEMESIS, the instrument lineshape is defined using the using the full-width at half maximum (*FWHM*) in the Measurement class. There are three options:\n", "\n", "- If *FWHM=0*, then archNEMESIS will not convolve the modelled spectrum with any instrumental function, and will just interpolated the calculated spectrum to the convolution wavelengths VCONV.\n", "\n", "- If *FWHM>0*, then archNEMESIS will convolve the spectrum with a constant instrument line shape throughout the modelled spectral range. The shape of the instrumental function is indicated by the ISHAPE flag, defined by a single integer in the HDF5 file or the .sha file, following:\n", "\n", "| ID | Line shape |\n", "| --- | --- |\n", "| 0 | Square function |\n", "| 1 | Triangular function |\n", "| 2 | Gaussian function |\n", "| 3 | Hamming function |\n", "| 4 | Hanning function |\n", "\n", "- If *FWHM<0*, then archNEMESIS will convolve the modelled spectrum with a used-defined instrumental lineshape. For each convolution wavelength (*VCONV*), then the instrument function is defined independently by defining a finer grid of wavelengths (*VFIL*) with the corresponding values of the filter function (*AFIL*). This information is either included in the HDF5 archNEMESIS file or the .fil NEMESIS file.\n", "\n", "### Units\n", "\n", "NEMESIS can perform the radiative transfer calculations both in wavelength and wavenumber space. This is indicated throughout the code using the *ISPACE* flag. the *ISPACE* flag defined in the *.inp* file, where *ISPACE* = 0 indicates wavenumber space in cm$^{-1}$, and *ISPACE* = 1 indicated wavelength space in $\\mu$m.\n", "\n", "In addition, one can also define several types of spectrum. This is defined through the *IFORM* flag, which can take several values following:\n", "\n", "| IFORM | Spectrum type | ISPACE | Units in *.spx* file | Units in *.mre* file |\n", "| --- | --- | --- | --- | --- |\n", "| 0 | Radiance | 0 | $\\text{W cm}^{-2}\\text{ sr}^{-1}\\text{ }\\mu\\text{m}^{-1}$ | $\\mu \\text{W cm}^{-2}\\text{ sr}^{-1}\\text{ }\\mu\\text{m}^{-1}$ |\n", "| 0 | Radiance | 1 | $\\text{W cm}^{-2}\\text{ sr}^{-1}\\text{ (cm}^{-1}\\text{)}^{-1}$ | $\\text{nW cm}^{-2}\\text{ sr}^{-1}\\text{ (cm}^{-1}\\text{)}^{-1}$ |\n", "| 1 | Secondary transit depth ($\\text{F}_{\\text{planet}}/\\text{F}_{\\text{star}}$) | 0/1 | Dimensionless | Dimensionless |\n", "| 5 | Normalised spectrum to VNORM | 0/1 | Dimensionless | Dimensionless |\n", "| 6 | Integrated radiance over filter | 0/1 | $\\text{W cm}^{-2}\\text{ sr}^{-1}\\text{ }$ | $\\text{W cm}^{-2}\\text{ sr}^{-1}\\text{ }$ |\n", "\n" ] }, { "cell_type": "markdown", "id": "343d8ad9-17b9-4f0f-a77b-56326c13cf8a", "metadata": { "jp-MarkdownHeadingCollapsed": true }, "source": [ "# Spectroscopy\n", "\n", "
\n", "\n", "Summary\n", "\n", "The Spectroscopy class includes information about the absorption cross sections of the gases in the atmosphere. In archNEMESIS, all the radiative transfer calculations are performed using pre-tabulated look-up tables including the line-by-line cross sections or the k-distributions required for solving the radiative transfer equations with the correlated-k approximation. The Spectroscopy class is used to perform calculations with these cross sections.\n", "\n", "
\n", "\n", "\n", "
\n", "\n", "Description of used-defined parameters\n", "\n", "Required parameters when writing input files:\n", "\n", "- ILBL: Flag indicating if line-by-line cross sections or k-distributions are used.\n", "- NGAS: Number of active gases in the atmosphere.\n", "- LOCATION: Path to each of the look-up tables.\n", "\n", "Other parameters in class:\n", "\n", "- ID: Gas ID for each of the species included in the atmosphere.\n", "- ISO: Isotope ID for each of the species included in the atmosphere (0 for all isotopes).\n", "- WAVE: Spectral points in the look-up tables (must be the same for all).\n", "- PRESS: Pressure levels at which the cross sections or k-distributions are tabulated (atm).\n", "- TEMP: Temperature levels at which the cross sections or k-distributions are tabulated (K).\n", "- G_ORD: If ILBL=0, g-ordinates at which the k-distributions are tabulated.\n", "- DELG: If ILBL=0, step in g-ordinates.\n", "- FWHM: If ILBL=0, full-width at half maximum at which the k-distributions are convolved with.\n", "- K: Line-by-line cross sections (cm$^2$) or k-distributions.\n", "\n", "
" ] }, { "cell_type": "markdown", "id": "0bc7e5d4-17fe-426d-977f-5a2704e61923", "metadata": {}, "source": [ "ArchNEMESIS performs the radiative transfer calculations using pre-tabulated correlated-k or line-by-line tables. Whether one or the other are used is specified using the ILBL flag of the Spectroscopy class. In particular:\n", "\n", "- In order to run a retrieval with correlated-k tables, the ILBL flag should be equal to 0. In this case, the LOCATION parameter of the Spectroscopy class must include a list of paths pointing to the several look-up k-tables, which must specified using the NEMESIS .kta extension. These tables are then read and the rest of the fields of the class are filled with the k-distribution information.\n", "\n", "- In order to run a retrieval with line-by-line look-up tables, the ILBL flag should be equal to 2. In this case, the LOCATION parameter of the Spectroscopy class must include a list of paths pointing to the several look-up k-tables, which must specified using the NEMESIS .lta extension. These tables are then read and the rest of the fields of the class are filled with the information about the line-by-line cross sections.\n", "\n", "At this stage, archNEMESIS does not include routines to calculate the cross sections from line databases such as the HITRAN or GEISA spectroscopic line databases. These must be calculated using the programs from the Fortran version of NEMESIS. However, archNEMESIS includes a set of routines in the Spectroscopy class to read these tables (see [Examples](https://archnemesis.readthedocs.io/en/latest/examples/lookup_tables/lookup_tables.html)). It must be noted that the cross sections stored in the pre-tabulated tables are multiplied by a factor of 10$^{20}$, and must be corrected by the user to get the correct values.\n", "\n", "Alternatively, the user might want to use other sources for the cross sections other than from line databases (e.g., UV cross section data). In that case, archNEMESIS includes a set of routines to write the pre-tabulated tables in the correct format (see [Examples](https://archnemesis.readthedocs.io/en/latest/examples/create_UV_lta/create_UV_lta.html))." ] }, { "cell_type": "markdown", "id": "baff3d11-c6b2-4656-ad4c-a228f2e764f1", "metadata": {}, "source": [ "# Stellar\n", "\n", "
\n", "\n", "Summary\n", "\n", "The Stellar class includes information about the reference stellar spectrum and the Sun-planet distance, needed to calculate the stellar flux at the top of the atmosphere. In particular, the Stellar class holds information about the stellar power spectrum and allows to perform the necessary calculations to calculate the relevant fluxes.\n", "\n", "
\n", "\n", "\n", "
\n", "\n", "Description of used-defined parameters\n", "\n", "Required parameters when writing input files:\n", "\n", "- RADIUS: Radius of the star (km).\n", "- ISPACE: Spectral units for defining the surface properties (0 - Wavenumber in cm$^{-1}$; 1 - Wavelength in $\\mu$m).\n", "- WAVE: Wavelength or wavenumber array at which the stellar spectrum is defined (cm$^{-1}$ or $\\mu$m).\n", "- SOLSPEC: Stellar power spectrum (W (cm$^{-1}$)$^{-1}$ or W $\\mu$m$^{-1}$ ).\n", "- DIST: Planet-Star distance (AU).\n", "\n", "Other parameters in class:\n", "\n", "- SOLFLUX: Stellar flux at top of planet's atmosphere (W cm$^{-2}$ (cm$^{-1}$)$^{-1}$ or W cm$^{-2}$ $\\mu$m$^{-1}$ )\n", "\n", "
" ] }, { "cell_type": "markdown", "id": "ac0fa0eb-cc72-424f-aba2-78cc11f78f0a", "metadata": {}, "source": [ "The Stellar class holds the information about the stellar spectrum. Users can specify their own stellar spectrum for their specific needs, as it is shown in the [Examples](https://archnemesis.readthedocs.io/en/latest/examples/stellar/StellarExample.html). Additionally, archNEMESIS stores some reference stellar spectrum files that might be useful for users.\n", "\n", "| | File name | Spectral range | Units | Information |\n", "| --- | --- | --- | --- | --- |\n", "| 1 | *houghtonsolarwn.dat* | 200 - 87000 | $\\text{cm}^{-1}$ | Solar spectrum adapted from Houghton (1986).|\n", "| 2 | *houghtonsolarwl.dat* | 0.11 - 50 | $\\mu\\text{m}$ | Solar spectrum adapted from Houghton (1986).|\n", "| 3 | *houghtonsolar_corr_wl.dat* | 0.11 - 3.8 | $\\mu\\text{m}$ | Solar spectrum adapted from Houghton (1986). Flux multiplied by 1.035. |\n", "| 3 | *solar_noaa_wl_2024.txt* | 0 - 200 | $\\mu\\text{m}$ | Solar spectrum adapted from [NOAA](https://www.ncei.noaa.gov/products/climate-data-records/solar-spectral-irradiance). |" ] }, { "cell_type": "markdown", "id": "b6684849-8404-4182-8bd1-d0ef6be9618f", "metadata": { "jp-MarkdownHeadingCollapsed": true }, "source": [ "# Scatter\n", "\n", "
\n", "\n", "Summary\n", "\n", "The Scatter class includes information of two types. First of all, it includes information about the optical properties of the atmospheric aerosols (i.e., extinction cross section, single scattering albedo, phase function). Secondly, in the case of multiple scattering runs, it specifies the parameters for the discretisation of the model into quadrature angles (for the zenith direction) and Fourier components (for the azimuth direction). In addition, apart from the information required for the forward model calculations, the Scatter class includes functions for the calculation of the optical properties of spherical aerosols based on their refractive index following the Mie Theory.\n", "\n", "
\n", "\n", "\n", "
\n", "\n", "Description of used-defined parameters\n", "\n", "Required parameters when writing input files:\n", "\n", "- ISPACE: Spectral units for defining the aerosol properties (0 - Wavenumber in cm$^{-1}$; 1 - Wavelength in $\\mu$m).\n", "- ISCAT: Flag to define the scattering calculation type.\n", "- IRAY: Flag to define the Rayleigh scattering type.\n", "- IMIE: Flag to indicate the format of the phase functions.\n", "- NMU: Number of quadrature angles for multiple scattering calculations.\n", "- NPHI: Number of azimuth angles for multiple scattering calculations.\n", "- NF: Number of Fourier components for the azimuth decomposition in multiple scattering calculations.\n", "- WAVE: Spectral points at which the aerosol properties are defined.\n", "- NDUST: Number of aerosol populations (must be consistent with that in Atmosphere class).\n", "- KEXT: Extinction cross section (cm$2$, unless normalised).\n", "- SGLALB: Single scattering albedo.\n", "\n", "Optional parameters when writing input files:\n", "\n", "- G1: If IMIE=0, assymmetry parameter of first Henyey-Greenstein function.\n", "- G2: If IMIE=0, assymmetry parameter of second Henyey-Greenstein function.\n", "- F: If IMIE=0, relative contribution from first Henyey-Greenstein function (from 0 to 1).\n", "- THETA: If IMIE=1, scattering angles at which the phase function is defined (degrees).\n", "- PHASE: If IMIE=1, phase function.\n", "- NLPOL: If IMIE=2, number of Legendre polynomials used to reconstruct the phase function.\n", "- WLPOL: If IMIE=2, weight of the Legendre polynomials used to reconstruct the phase function.\n", "\n", "Other parameters in class:\n", "\n", "- KSCA: Scattering cross section (cm$^2$, unless normalised).\n", "- KABS: Absorption cross section (cm$^2$, unless normalised).\n", "- MU: Cosine of the quadrature angles.\n", "- WTMU: Weight of each quadrature angle for Gauss-Lobatto integration.\n", "- WAVER: Wavelength or wavenumber array to define the refractive index.\n", "- REFIND_REAL: Real part of the refractive index.\n", "- REFIND_IM: Imaginary part of the refractive index. \n", "\n", "
" ] }, { "cell_type": "markdown", "id": "72936ea2-457f-40fa-8044-20815d6618a6", "metadata": {}, "source": [ "### Scattering setup\n", "\n", "One of the main objectives of the Scatter class is to define the setup for the scattering calculations in the radiative transfer routines. In particular, the main flag for defining what sort of scattering calculations are used is called ISCAT, which can take the following values:\n", "\n", "| ISCAT | Description |\n", "| --- | --- |\n", "| 0 | No scattering |\n", "| 1 | Multiple scattering calculation |\n", "\n", "In the case that multiple scattering calculations are required, we need to define other parameters to establish how the setup for the scattering calculations. In particular, NMU defines the number of \\enith ordinates, NPHI defines the number of azimuth ordinates, and NF defines the number of Fourier components used to represent the variability of the scattering field in the azimuth direction.\n", "\n", "In archNEMESIS, two types of scattering are calculated, Rayleigh scattering and scattering by aerosols.\n", "\n", "\n", "### Rayleigh scattering\n", "\n", "Rayleigh scattering refers to the elastic scattering of light by particles much smaller than the wavelength of the radiation, which is typically the case for scattering by gas molecules in the atmosphere. ArchNEMESIS can simulate different scenarios for Rayleigh scattering depending on the what the dominating species is in the atmosphere. These scenarios are defined using the IRAY parameter on the Scatter class.\n", "\n", "| IRAY | Description |\n", "| --- | --- |\n", "| 0 | Rayleigh scattering optical depth not included |\n", "| 1 | Rayleigh optical depths for gas giant atmosphere |\n", "| 2 | Rayleigh optical depth suitable for a CO$_2$-dominated atmosphere |\n", "| 3 | Rayleigh optical depth suitable for a N$_2$-O$_2$ atmosphere |\n", "| 4 | New Raighleigh optical depth for gas giant atmospheres |\n", "\n", "### Aerosol scattering\n", "\n", "Scattering by aerosol particles suspended in the atmosphere is represented by three main parameters defining the optical properties of these:\n", "\n", "- Extinction coefficient, which is defined as the sum of the cross sections from absorption and scattering ($k_{ext}$ = $k_{abs}$ + $k_{sca}$).\n", "- Single scattering albedo, which is defined as the fraction of the light that is scattered ($\\omega$ = $k_{sca}$/$k_{ext}$).\n", "- Phase function, which defines the direction of the scattered photons.\n", "\n", "Calculating the optical properties of aerosols is complex, as they not only depend on the composition of the aerosols, which defines the refractive index, but also on several other parameters like the shape of the particles or the particle size distribution. ArchNEMESIS includes a set of routines to calculate the optical properties of aerosols using Mie Theory, which models the particles as spheres. In particular, the Mie calculations are performed using the *Makephase* method of the Scatter class (see [Examples](https://archnemesis.readthedocs.io/en/latest/examples/makephase/run_makephase.html)).\n", "\n", "The calculation of the optical properties with Makephase requires knowledge of the complex refractive index of the particles. This refractive index can be arbitrarily defined using the WAVER, REFIND_REAL and REFIND_IM arrays of the Scatter class. However, archNEMESIS also includes a dictionary of refractive indices relevant for the study of planetary atmospheres. Users can include the refractive indices from their own sources by writing the information on *Data/aerosol_data.py*. The refractive indices that have already been included are:\n", "\n", "| ID | Wavelength range ($\\mu$m) | Description |\n", "| --- | --- | --- |\n", "| 1 | 0.2 - 100 | Mars' mineral dust from Wolff et al. (2006) |\n", "| 2 | 0.04 - >1000 | Water ice from Warren et al. (2008) |\n", "| 3 | 0.05 - >1000 | CO$_2$ ice from Warren et al. (1986) |\n", "| 4 | 0.36 - 25 | Sulfuric acid 75% (Palmer and Williams, 1975) |\n", "\n", "When reading or writing the information of the aerosol optical properties from the input files, the essential information we need to define is:\n", "\n", "- The parameters WAVE, KEXT and SGLALB define the spectral extinction coefficient and single scattering albedo of each aerosol population. The spectral units used in the class are defined by the ISPACE flag, which can be either in wavenumbers (ISPACE=0) or wavelengths (ISPACE=1). This information in the input files is either specified in the archNEMESIS HDF5 file, or the .xsc file.\n", "\n", "- The parameter PHASE includes the information about the phase function of the particles. In archNEMESIS, the phase function can be defined in three different formats, all of which can be internally calculated with *Makephase* or which we can manually define. The format of the phase function is defined with the IMIE flag, which can take the following values.\n", "\n", " - If IMIE=0, the phase function at each wavelength is modelled as a double Henyey-Greenstein function. The two H-G functions are defined by the parameters Scatter.G1 and Scatter.G2, while the relative weight of the two functions is defined by Scatter.F. This information is included either in the HDF5 input file or the NEMESIS *hgphasex.dat* file.\n", " \n", " - If IMIE=1, then the spectral phase function is defined explicitly at different scattering angles. In particular, the scattering angles at which the phase function are defined are included in the Scatter.THETA array, while the phase function is explicitly defined in the PHASE array. Ths information in the input files is included either in the HDF5 file or in the NEMESIS *PHASEX.DAT* file.\n", " \n", " - If IMIE=2, then the phase function is defined as a combination of Legendre polynomials. In particular, the number of Legendre polynomials the phase function is decomposed into is defined by Scatter.NLPOL, and the Scatter.WLPOL array defines the weights of each of the polynomials. This format of the phase function can only be read from the archNEMESIS HDF5 input file. \n", "\n", "We recommend the users to check the [Examples](https://archnemesis.readthedocs.io/en/latest/examples/makephase/run_makephase.html) to familiarise with the different formats used for the optical properties of aerosols.\n", "\n", "It is important to note that in archNEMESIS, the integral of the phase function over solid angle must be normalised to 1, following\n", "\n", "$$\n", "\\int_{4\\pi} p(\\Omega) d\\Omega = \\int_0^{2\\pi} \\int_0^{\\pi} p(\\theta,\\phi) \\sin \\theta d\\theta d\\phi = 1.\n", "$$\n", "\n", "If performing the calculation of the optical properties of aerosols with *Makephase*, this normalisation is already accounted for. However, if this is not the case, users must make sure the phase function is normalised. Once the inputs have been defined, one can check this by simply using the Scatter.check_phase_norm() method.\n", "\n", "Similarly, the units of the extinction coefficient are typically defined in cm$^{-2}$. However, users may prefer to work in units of optical depth. In that case, the extinction coefficient KEXT can be normalised at a given wavelength, so that optical depths at other wavelengths are relative to this. In order to keep consistency within the code, the aerosol abundance profiles need to be properly normalised using the Atmosphere.normalise_dust(idust) method (idust refers of the index of the aerosol population that wants to be normalised), so that the column optical depth for that aerosol species is given by 1. Then, we can decide to choose an arbitrary optical depth just by properly scaling either the values of KEXT or the vertical profiles by a constant factor." ] }, { "cell_type": "markdown", "id": "304bddfb-77e5-4ba0-adfc-021e1dfeae50", "metadata": { "jp-MarkdownHeadingCollapsed": true }, "source": [ "# Layer\n", "\n", "
\n", "\n", "Summary\n", "\n", "The Layer class includes the information regarding the split of the atmospheric profiles into a finite number of layers to perform the radiative transfer calculations. The information in the Layer class indicates the layering setup, but also includes methods to perform the calculations. \n", "\n", "
\n", "\n", "\n", "\n", "
\n", "\n", "Description of used-defined parameters\n", "\n", "Required parameters when writing input files:\n", "\n", "- NLAY: Number of layers in atmosphere.\n", "- LAYTYP: Flag defining the method by which to split the layers in the atmosphere.\n", "- LAYINT: Flag indicating the method by which to calculate the properties of each layer.\n", "- LAYHT: Altitude at base of bottom layer (m).\n", "\n", "Optional parameters when writing input files:\n", "\n", " - P_base: If LAYTYP=4, pressure at base of each layer (Pa).\n", " - H_base: If LAYTYP=5, altitude at base of each layer (m).\n", "\n", "Other parameters in class:\n", "\n", " - BASEH: Base altitude of each layer (m).\n", " - BASEP: Base pressure of each layer (Pa).\n", " - DELH: Width of each layer (m).\n", " - HEIGHT: Effective height of each layer (m).\n", " - PRESS: Effective pressure of each layer (Pa).\n", " - TEMP: Effective temperature of each layer (K).\n", " - TOTAM: Gaseous line-of-sight column density in each layer (m$^{-2}$).\n", " - AMOUNT: Gaseous line-of-sight column density of each gas in each layer (m$^{-2}$).\n", " - PP: Effective partial pressure of each gas in each layer (Pa).\n", " - CONT: Line-of-sight column density of each dust population in each layer (particles m$^{-2}$).\n", " - FRAC: Fraction of para-H$_2$ in each layer.\n", " - DTE: Matrix for translating the temperature of the atmospheric profiles to the temperature of each layer.\n", " - DAM: Matrix for translating the gaseous amounts of the atmospheric profiles to those in each layer.\n", " - DCO: Matrix for translating the aerosol amounts of the atmospheric profiles to those in each layer.\n", " - DUST_UNITS_FLAG: Flag indicating if units of aerosol abundance must be specified in m$^{-3}$ (0 - default) or particles per gram of atmosphere (-1). This flag must be consistent with that in the Atmosphere class.\n", "\n", "\n", "\n", "
" ] }, { "cell_type": "markdown", "id": "b01007b2-7b2d-478a-bc66-d5467b87f94f", "metadata": {}, "source": [ "In the forward model, the calculations are performed using a finite number of atmospheric layers with certain properties (e.g., temperature, pressure, vertical column density, etc.). The Layer class is in charge of dividing the atmospheric profiles listed in the Atmosphere class into this finite number of layers used in the radiative transfer calculations, as well as calculating the mean properties of these layers. ArchNEMESIS allows the division of the atmosphere into *NLAY* layers, which can be split different approaches to mitigate any biases arising from the finite representation of the atmospheric layers. These approaches, which are defined using the *LAYTYP* field of the Layer class, include:\n", "\n", "| LAYTYP | Description |\n", "| --- | --- |\n", "| 0 | Layers divided by equal changes in pressure |\n", "| 1 | Layers divided by equal changes in log pressure |\n", "| 2 | Layers divided by equal changes in height |\n", "| 3 | Layers divided by equal changes in path length |\n", "| 4 | Layer base pressures (atm) indicated in *press.lay* file |\n", "| 5 | Layer base heights (km) indicated in *height.lay* file |\n", "\n", "Additionally, the calculation of the optical properties of the layer can be performed using two main approaches, which are defined using the *LAYINT* flag of the Layer class.\n", "\n", "| LAYINT | Description |\n", "| --- | --- |\n", "| 0 | Properties are set to the values at the centre of the layer (useful for intercomparisons). |\n", "| 1 | Properties are calculated using Curtis-Godson paths (recommended). |\n", "\n", "We recommend the users to have a look at the [Examples](https://archnemesis.readthedocs.io/en/latest/examples/layer_example/layer_example.html) to get insight on how these calculations are performed.\n" ] }, { "cell_type": "markdown", "id": "96f94bf2-6727-4963-ad5e-fbd4f5eb2b73", "metadata": { "jp-MarkdownHeadingCollapsed": true }, "source": [ "# Telluric\n", "\n", "
\n", "\n", "Summary\n", "\n", "The Telluric class includes information about the Earth's atmosphere in the case that we want to model the spectrum of a planetary atmosphere attenuated by the telluric transmission from the observer's position. To some extent, the Telluric class may be thought of as two extra Atmosphere and Spectroscopy classes defining the properties of the Earth’s atmosphere. In addition, this class includes some methods to directly download vertical profiles of the Earth’s atmosphere from the ERA5 reanalysis model from the European Centre for Medium-Range Weather Forecasts (ECMWF) at the time and location of the observations.\n", "\n", "
" ] }, { "cell_type": "markdown", "id": "82dc96a9-2e22-4b2d-87ca-fa860d090145", "metadata": {}, "source": [ "When analysing spectroscopic observations made with ground-based telescopes, one may require to correct for the absorption of the Earth's atmosphere. archNEMESIS includes a specific class in order to define how this correction should be performed. In particular, the information of the Telluric class used in the radiative transfer calculations are mostly given by two other classes contained within Telluric:\n", "\n", "- Telluric.Atmosphere: We define an Atmosphere class within Telluric in order to specify the vertical structure and composition of the Earth's atmosphere at the time of our telescopic observations.\n", "- Telluric.Spectroscopy: We define a Spectroscopy class within Telluric in order to specify the absorption cross sections of any active gases in the Earth's atmosphere within our required spectral range (e.g., H$_2$O, CO$_2$, CH$_4$, O$_3$, etc).\n", "\n", "Apart from these classes, there are two other parameters used in the radiative transfer calculations:\n", "\n", "- Telluric.ALTITUDE: This parameter defines the altitude of the observatory in metres.\n", "- Telluric.EMISS_ANG: This parameter defines the angle at which the planet is observed in the sky. Since we are looking upwards, this angle must be 90$^\\circ$ < EMISS_ANG < 180$^\\circ$, where 180$^\\circ$ represents looking straight up at the zenith, and 90$^\\circ$ represents looking towards the horizon.\n", "\n", "### Extracting Earth's atmospheric profiles from the ERA5 reanalysis model\n", "\n", "archNEMESIS includes a feature to automatically extract profiles from the [ERA5 reanalysis model](https://www.ecmwf.int/en/forecasts/dataset/ecmwf-reanalysis-v5) from the European Centre for Medium-Range Weather Forecasts. This is performed internally in archNEMESIS by coupling it with the cdsapi library, but requires the user to create an account at the Climate Data Store and set up the user information in the machine where archNEMESIS is run from. Information about how to set up the account is given in the following [link](https://cds.climate.copernicus.eu/how-to-api). In particular, the steps that need to be followed in order to use this feature are:\n", "\n", "1. Create account at the [Climate Data Store](https://cds.climate.copernicus.eu/).\n", "2. Agree to the Terms of use for the [dataset](https://cds.climate.copernicus.eu/datasets/reanalysis-era5-pressure-levels?tab=download).\n", "3. Find your API key in the following [link](https://cds.climate.copernicus.eu/how-to-api).\n", "4. Create a file on your machine with your personal API key under the directory $HOME/.cdsapirc (on Linux/Unix systems).\n", "\n", "Once these steps have been executed, you can download vertical profiles of the Earth's atmosphere from the ERA5 model using the Telluric class. The information we need to provide to the class for this is:\n", "\n", "- Telluric.DATE: Date at which the observations took place (DD-MM-YYYY) (UTC).\n", "- Telluric.TIME: Time at which the observations took place (HH:MM:SS) (UTC).\n", "- Telluric.LATITUDE: Latitude of the observatory.\n", "- Telluric.LONGITUDE: Longitude of the observatory.\n", "\n", "There is an example showing how to use this feature, as well as how to calculate the telluric transmission using archNEMESIS in the [Examples](https://archnemesis.readthedocs.io/en/latest/examples/telluric_example/example_telluric.html)." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.13" } }, "nbformat": 4, "nbformat_minor": 5 }