API reference

Main atmosphere module for storing model data

This module primarily contains the Atmos_t struct which does most of the heavy lifting in AGNI. There are also functions for setting up and configuring the struct.

Check that a named parameter value lies within a valid range, logging an error if not.

Check that the installed SOCRATES version is acceptably recent.

SOCRATES versions take the form of YYMM.VV where YY is the year, MM is the month, and VV is the minor version number.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Returns:

• accept::Bool whether the SOCRATES version is compatible.

Calculate index of photosphere from contribution function.

This is retained as a legacy method.

Estimates the location of the photosphere by finding the median of the contribution function in each band (0.2 μm to 150 μm), and then finding the pressure level at which these median values are maximised.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Returns:

• iphot::Int64 index of photosphere

Calculate index of photosphere simply from a reference pressure.

This is a simple method that does not require optical depth profiles.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• p_ref::Float64 reference pressure [Pa]

Returns:

• Int64 index of photosphere

Calculate index of photosphere at a reference wavelength.

Assuming that atmos.tau_p has already been determined using calc_tau_isolines!, this method finds the index of the photosphere at the reference wavelength.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• ref_wl::Float64 reference wavelength [m]

Returns:

• Int64 index of photosphere

Get the name of an aerosol from its type number in the spectral file.

Type numbers defined by SOCRATES map to their standard suffix. Larger type numbers are used for aerosols whose properties were calculated at runtime.

Arguments:

• atmos::atmosphere.Atmos_t the atmosphere struct instance
• type_id::Int aerosol type number

Returns:

• name::String name of the aerosol

Allocate atmosphere arrays, prepare spectral files, and final steps.

Will not modify spectral file if stellar_spectrum is an empty string. Will treat star as blackbody with photospheric effective temperature of stellar_Teff if the parameter stellar_spectrum has value of "blackbody".

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• stellar_spectrum::String path to stellar spectrum csv file
• stellar_Teff::Float64 star effective temperature if blackbody
• check_safe_gas::Bool require that there be at least one 'safe' gas in the mix

Calculate condensate mass mixing ratio at a specific layer.

Arguments:

• atmos::atmosphere.Atmos_t atmosphere struct instance to be used.
• c::String condensate species to calculate for (e.g. "H2O")
• i::Int64 layer index

Returns:

• cond_mmr::Float64 condensate c mass mixing ratio at layer i

Calculate properties within each layer of the atmosphere (e.g. density, mmw).

Function will return false if hydrostatic calculcation fails. This is usually when the atmosphere becomes unbound.

Arguments: - atmos::Atmos_t the atmosphere struct instance to be used.

Returns: - ok::Bool function result is ok

Calculate planet's bulk density.

This function is retained for legacy API compatibility. The main calculation of the bulk density is done by estimate_photosphere!.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Returns:

• transspec_rho::Float64 the bulk density observed in transmission

Calculate the scale height for all layers.

Requires temperature, pressure, mmw to be already have been set.

Arguments: - atmos::Atmos_t the atmosphere struct instance to be used.

Calculate specific heat capacity and thermal conductivity for all layers.

Specific heat per unit mass: J K-1 kg-1. Thermal conductivity: W m-1 K-1.

Arguments: - atmos::Atmos_t the atmosphere struct instance to be used.

Calculate the mass-density for all layers.

Requires temperature, pressure, mmw to be already have been set.

Arguments: - atmos::Atmos_t the atmosphere struct instance to be used.

Calculate mean molecular weight for all layers.

MMW stored as kg/mol.

Arguments: - atmos::Atmos_t the atmosphere struct instance to be used.

Calculate radii, gravities, and masses for all layers.

Performs hydrostatic integration from the ground upwards. Requires density, temperature, pressure to have already been set.

Does not account for surface ocean height.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Returns:

• bound::Bool atmosphere is strongly bound by gravity

Calculate the scale height of a single layer.

Requires temperature, pressure, mmw to be already have been set.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• idx::Int64 index of the layer

Calculate specific heat capacity and thermal conductivity of a single layer.

Specific heat per unit mass

J K-1 kg-1, the mass-weighted sum over gases.

Thermal conductivity

W m-1 K-1, from the Wassiljewa mixing rule with the Mason-Saxena (Wilke) coefficients on mole fractions, k = Σ_i x_i k_i / Σ_j x_j Φ_ij,

where Φ_ij = [1 + (η_i/η_j)^(1/2) (M_j/M_i)^(1/4)]² / sqrt(8 (1 + M_i/M_j)).

• Poling, Prausnitz & O'Connell 2001, The Properties of Gases and Liquids
• https://idaes-pse.readthedocs.io/en/stable/explanations/components/propertypackage/general/transportproperties/thermalconductivitywms.html
• https://en.wikipedia.org/wiki/Viscositymodelsformixtures?useskin=vector#Classicmixingrulesfor_gas

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• idx::Int64 index of the layer

Calculate the mass-density of a single layer.

Requires temperature, pressure, mmw to be already have been set.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• idx::Int64 index of the layer

Find pressure and radius where optical depth τ=τ_ref, for each spectral band.

Uses the optical depth profiles stored in atmos.tau_band and determines the layer where τ is closest to atmos.transspec_ref_tau. Values are stored in atmos.tau_p [Pa] and atmos.tau_r [m].

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Returns:

• tau_p::Array{Float64,1} pressure at which τ=τ_ref for each band [Pa]
• tau_r::Array{Float64,1} radius at which τ=τ_ref for each band [m]

Get TOA heating from atmosphere parameters.

Return the effective irradiation flux at the top of the atmosphere (TOA).

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be accessed

Returns:

• Float64 effective TOA heating [W m-2]

Get the solar zenith angle for a given longitude and latitude

Assuming tidally locked planet with coordinate system centred on subsolar point. Does not account for super-illumination in the twilight regions.

Arguments:

• lon::Float64 the longitude of location (degrees)
• lat::Float64 the latitude of location (degrees)

Returns:

• zen::Float64 the zenith angle for the location (degrees)

Deallocate SOCRATES arrays and mark the atmosphere as unallocated.

Estimate the index of the photosphere.

This is the layer that is probed in transmission, and is used to calculate the observed radius and bulk density. This is a wrapper function that updates the transspec_* properties of the atmosphere struct.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be updated.
• setby::String method to use for estimating photosphere ("tau" or "prs")

Returns:

• idx::Int64 index of photosphere

Generate pressure grid.

Almost equally log-spaced between pboa and pboa. The near-boundary layers are smaller than they would be on an equally log-spaced grid, to avoid numerics.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Get interleaved cell-centre and cell-edge PTR grid.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Returns:

• arr_P::Array pressure array [Pa]
• arr_T::Array temperature array [K]
• arr_R::Array radius array [m]

Integrate hydrostatic and gravity equations across a pressure interval.

Uses the classic fourth-order Runge-Kutta method.

Internally, this function integrates from p0 to p1, which means that the pressure is decreasing across the interval. The gravity is updated at each integration step, and is offset by the centrifugal acceleration.

Arguments:

• r0::Float64 radius at start of interval [m]
• g0::Float64 gravity at start of interval [m s-2]
• a0::Float64 net accel at start of interval (grav - cent) [m s-2]
• m0::Float64 mass enc at start of interval [kg]
• p0::Float64 pressure at start of interval [Pa]
• p1::Float64 pressure at end of interval [Pa]
• rho::Float64 density throughout interval, constant [kg m-3]
• n::Int64 number of steps for integration (n >= 2)

Optional keyword arguments:

• constg::Bool constant gravity with height?
• selfg::Bool include self-gravity of the atmosphere?

Returns:

• rj::Float64 radius at end of interval [m]
• gj::Float64 gravity at end of interval [kg]
• mj::Float64 mass enc at end of interval [kg]

List available aerosol species.

Arguments:

• atmos::atmosphere.Atmos_t the atmosphere struct instance to check

Returns:

• aerosol_names::Array{String, 1} list of available aerosol species

Set atmosphere properties such that it is effectively transparent.

This will modify the surface pressure and disable gas opacity in SOCRATES. These changes cannot be reversed directly. To undo them, it is best to create and allocate a new atmosphere struct.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Parse and validate the configuration of a single aerosol species.

Each aerosol is described by a dictionary containing a method key, which is either "mon" (pre-computed SOCRATES monochromatic scattering data) or "mie" (properties calculated at runtime from refractive indices using Mie theory).

Arguments:

• name::String name of the aerosol
• value the configuration for this aerosol
• condensates::Vector{String} list of condensable species
• nk_dir::String refractive index directory (setup! passes the atmosphere's; the default ignores res_dir)

Returns:

• entry::Union{Dict,Nothing} normalised configuration, or nothing if invalid

Set aerosol MMR profiles for a given species.

Aerosol in the singular form.

Arguments:

• atmos::atmosphere.Atmos_t the atmosphere struct instance to be used
• species::String the name of the aerosol species to set
• mmr the mixing ratio to assign (1D array, or Float, or species String)
• pmin::Float64 the minimum pressure to set aerosol at [Pa]
• pmax::Float64 the maximum pressure to set aerosol at[Pa]
• mmr_sf::Float64 scaling factor to apply to aerosol MMR

Returns:

• any_aerosol::Bool whether aerosol is present after setting

Loop over all available aerosols and set profiles based on condensate yields.]

Aerosols in the plural form.

Arguments:

• atmos::atmosphere.Atmos_t the atmosphere struct instance to be used
• mmr_sf::Float64 scaling factor to apply to all aerosol MMR profiles

Returns:

• any_aerosol::Bool whether any aerosols are present after setting

Set water cloud profile based on saturation.

Arguments:

• atmos::atmosphere.Atmos_t the atmosphere struct instance to be used.
• from_yield::Bool set cloud properties based on condensation yield
• mmr_sf::Float64 scaling factor to apply to cloud MMR

Returns:

• any_cloud::Bool whether any clouds are present

Set deep atmospheric heating parameters.

Configures the deep heating source which deposits energy as a Gaussian distribution in log-pressure space.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• Pmid::Float64 deposition pressure [Pa].
• Pwid::Float64 width of Gaussian in log-pressure space [logPa].
• flux_rel::Float64 heating flux relative to instellation.
• flux_abs::Float64 heating flux absolute [W m-2].
• norm_method::String method for normalising the Gaussian (pressure, mass).
• domain::String how to handle deposition pressures outside the domain (clamp, boundary_flux).
• power_mode::String off, or relative/absolute flux (off, rel, abs).
• verbose::Bool whether to show info messages about the configuration.

Returns:

• Bool indicating success or failure of the operation.

Set cell-edge temperatures from cell-centre values.

Uses interpolation within the bulk of the column and extrapolation for the topmost edge.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Set parameters of the atmosphere.

This is used to set up the struct immediately after creation. It must be done before allocate!() is called, and before any RT calculcations are performed.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• ROOT_DIR::String AGNI root directory.
• OUT_DIR::String Output directory.
• spfile::String path to spectral file ('grey' => use grey gas)
• instellation::Float64 bolometric solar flux at the top of the atmosphere [W m-2]
• s0_fact::Float64 scale factor to account for planetary rotation (i.e. S0^*/S0 in Cronin+14)
• albedo_b::Float64 bond albedo scale factor applied to instellation in order to imitate shortwave reflection
• zenith_degrees::Float64 angle of radiation from the star, relative to the zenith [degrees].
• tmp_surf::Float64 effective surface temperature to provide upward longwave flux at the bottom of the atmosphere [K].
• gravity::Float64 gravitational acceleration at the surface [m s-2].
• radius::Float64 planet radius at the surface [m].
• nlev_centre::Int64 number of model levels.
• p_surf::Float64 total surface pressure [bar].
• p_top::Float64 total top of atmosphere pressure [bar].
• mf_dict::Dict dictionary of VMRs in the format (key,value)=(gas,mf).
• mf_path::String path to file containing VMRs at each level.

Optional arguments:

• name::String name of the atmosphere (generates name if not provided).
• IO_DIR::String directory used for fast file operations.
• res_dir::String folder used in place of res/ ([files] res_dir).
• condensates list of condensates (gas names).
• metallicities::Dict dictionary of elemental metallicities (mass ratio rel to hydrogen)
• surface_material::String surface material (default is "greybody", but can point to file instead).
• albedo_s::Float64 grey surface albedo used when surface_material="greybody".
• tmp_floor::Float64 temperature floor [K].
• surf_roughness::Float64 surface roughness length scale [m]
• surf_windspeed::Float64 surface wind speed [m s-1].
• Kzz_kbreak::Float64 reference eddy diffusion coefficient, SI units [m2 s-1]
• Kzz_pbreak::Float64 reference pressure for Kzz break point [Pa]
• Kzz_floor::Float64 minimum Kzz value used for filling [m2 s-1]
• Kzz_type::Int64 parametrisation of Kzz. Options: 1 (constant), 2 (MLT wl), 3 (MLT Fc)
• mlt_asymptotic::Bool mixing length scales asymptotically, but ~0 near ground
• mlt_criterion::Char MLT stability criterion. Options: (s)chwarzschild, (l)edoux.
• tmp_magma::Float64 mantle temperature [K] for sol_type==2.
• skin_d::Float64 skin thickness [m].
• skin_k::Float64 skin thermal conductivity [W m-1 K-1].
• overlap_method::String gaseous overlap scheme (ro: rand overlap, ee: equiv extinct, rorr: ro+resort+rebin).
• target_olr::Float64 target OLR [W m-2] for sol_type==4.
• flux_int::Float64 planet's internal flux for sol_type==3.
• all_channels::Bool use all channels available for RT?
• flag_rayleigh::Bool include rayleigh scattering?
• flag_gcontinuum::Bool include generalised continuum absorption?
• flag_aerosol::Bool include aerosols?
• aerosol_species::Dict aerosols MMR values or associated condensates
• flag_cloud::Bool include clouds?
• phs_timescale::Float64 phase change timescale [s]
• evap_efficiency::Float64 re-evaporatione efficiency compared to saturating amount
• coldtrap::Bool keep the cold-trapping effect of condensation on gas mixing ratios
• real_gas::Bool use real gas EOS where possible
• thermo_functions::Bool use temperature-dependent thermodynamic properties
• use_all_gases::Bool store information on all supported gases, incl those not provided in cfg
• use_all_vols::Bool store information on all supported VOLATILE gases, neglecting rock vapours
• check_integrity::Bool confirm integrity of thermo files using their checksum
• κ_grey_lw::Float64 gas opacity when using grey-gas RT scheme, longwave
• κ_grey_sw::Float64 gas opacity when using grey-gas RT scheme, shortwave
• fastchem_work::String working directory for fastchem
• fastchem_floor::Float64 temperature floor on profile provided to fastchem
• fastchem_maxiter_chem::Float64 maximum chemical iterations allowed by fastchem
• fastchem_maxiter_solv:Float64 maximum solver iterations allowed by fastchem
• fastchem_xtol_chem::Float64 solution tolerance required of fastchem (chemical)
• fastchem_xtol_elem::Float64 solution tolerance required of fastchem (elemental)
• rfm_parfile::String path to HITRAN-formatted .par file provided to RFM
• transspec_ref_tau::Float64 vertical (normal) optical depth used to define the photosphere
• transspec_ref_wl::Float64 wavelength used to define photosphere [m]
• transspec_ref_p::Float64 pressure level used to define photosphere [bar]
• ocean_ob_frac::Float64 ocean basin area, as fraction of planet surface
• ocean_cs_height::Float64 continental shelf height [m]
• hydrograv_steps::Int64 number of steps to use when calculating heights and gravity
• hydrograv_maxdr::Float64 maximum step size to use when calculating heights [m]
• hydrograv_hilldr::Float64 maximum step size to use beyond the Hill radius [m]
• hydrograv_mindr::Float64 minimum step size to use when calculating heights [m]
• hydrograv_ming::Float64 minimum allowed gravity [m/s^2]
• hydrograv_constg::Bool constant gravity with height?
• hydrograv_selfg::Bool include self-gravity of the atmosphere?
• hill_radius::Float64 Hill radius of the planet [m]; layers beyond this are unbound

Returns: Nothing

Contains the energy module, for everything relating to energy transport

Calculates radiative, convective, conductive, etc, flux terms. Combines them together self-consistently to update the temperature profile.

Calculate energy flux at each level.

Calculates flux components (radtrans, convection, etc.) and sums them to get total flux. Also updates thermodynamic properties (heat capacity, density, etc.) at each layer.

Assumes that chemistry functions have already been called, if wanted. Does not call fastchem here.

Arguments:

• atmos::Atmos_t the atmosphere instance to be used.

Optional arguments:

• radiative::Bool include radiation fluxes
• latent_heat::Bool include condensation flux
• convective::Bool include MLT convection flux
• sens_heat::Bool include TKE sensible heat flux
• conductive::Bool include conductive heat flux
• deep::Bool include deep heating flux (layer-internal production)
• convect_sf::Float64 scale factor applied to convection fluxes
• latent_sf::Float64 scale factor applied to phase change fluxes
• calc_cf::Bool calculate LW contribution function?
• calc_hr::Bool calculate heating rates from fluxes?

Returns:

• Bool calculation succeeded

Calculate heating rates at cell-centres from the total flux.

Requires the total flux to have already been set (atmos.flux_dif). Heating rates are calculated in units of kelvin per day.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Returns:

• Bool whether the calculation succeeded

Calculate conductive heat fluxes using Fourier's law

Updates array of atmos.flux_cdct at each layer of the atmosphere, positive upwards.

Within the bulk atmosphere, conductive flux is calculated as: F_i = (T_i - T_{i-1}) / ((r_{i-1} - rl_i)/k_{i-1} + (rl_i - r_i)/k_i)

The flux to space (TOA) is zero, and from the surface uses the bottom half-cell.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used

Calculate deep atmospheric heating flux.

The heating is deposited as a Gaussian distribution in log-pressure space, centered at P_dep with width sigma_P.

Two power modes are supported:

• "rel" total flux = deepheat_flux_rel * instellation (stellar efficiency)
• "abs" total flux = deepheat_flux_abs (fixed radiative flux in W m⁻²)

The flux gradient is defined as: dFdeep/dP = Ftotal / (sqrt(2π) * σP * P) * exp(-(ln(P) - ln(Pdep))² / (2 * σ_P²))

This flux is integrated from the TOA downwards to obtain the cumulative flux at each cell edge, representing energy being deposited into the atmosphere.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Calculate turbulent kinetic energy (TKE) exchange coefficient.

Based on Monin-Obukhov similarity theory, from roughness length scale. See eq 9 in Nicholson & Benn (2006). Added small epsilon-factor to avoid function blowing-up around regime where height ≈ roughness.

A reasonable length scale can be found here: https://arxiv.org/pdf/2608.21549

Arguments:

• height::Float64 Height above surface [m]
• roughness::Float64 Roughness length scale [m]

Returns:

• C_d::Float64 TKE exchange coefficient [dimensionless]

Analytical diffusion scheme for condensation and evaporation energy.

Updates fluxes. Requires chemistry._sat_aloft to be called first.

Integrates from bottom of model upwards. Based on the amount of phase change at each level, a phase change flux is calculated by assuming a fixed condensation timescale.

If evaporation is enabled, then integrates from top downwards to determine flux from re-evaporation of droplets. Any droplets which reach the ground go towards forming an ocean.

Should ideally perform a microphysical treatment; e.g. by following this paper: https://agupubs.onlinelibrary.wiley.com/doi/epdf/10.1029/2020JE006653

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Returns:

• Bool whether the calculation succeeded

Reset energy fluxes to zero.

Calculate sensible heat flux from turbulent kinetic energy (TKE)

Updates the values of atmos.C_d and atmos.flux_sens.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used

Calculate conductive skin boundary layer thickness, given a conductive flux.

This is effectively the inverse of the skin_flux function, and can be used to determine the thickness of the boundary layer.

d = k * ΔT / F

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• flux_skn::Float64 the conductive flux through the skin layer [W m-2].

Returns:

• skin_d::Float64 conductive skin boundary layer thickness [m].

Calculate conductive flux carried by conductive skin boundary layer.

This is a simple implementation of fourier's conduction law, with fixed conductivity and thickness of the boundary layer. Parameters are set in the atmos struct.

F = k * ΔT / d

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Returns:

• flux::Float64 conductive flux through the skin layer [W m-2].

Contains module for Mie scattering calculations

Scattering and absorption by homogeneous spheres, following the BHMIE algorithm of Bohren & Huffman (1983), with the series truncation criterion of Wiscombe (1980). Polydisperse properties are integrated over a log-normal size distribution using Gauss-Hermite quadrature in ln(r).

https://www.astro.princeton.edu/~draine/code/bhmie.f

References:

• Bohren, C. F. & Huffman, D. R. (1983), Absorption and Scattering of Light by Small Particles, Wiley. https://doi.org/10.1002/9783527618156
• Wiscombe, W. J. (1980), Improved Mie scattering algorithms, Applied Optics 19, 1505. https://doi.org/10.1364/AO.19.001505

Gauss-Hermite quadrature nodes and weights.

Computed with the Golub-Welsch algorithm. Weights are normalised such that sum(w .* f.(t)) approximates the expectation of f(t) for t ~ N(0, 1/2).

Arguments:

• n::Int number of nodes

Returns:

• t::Vector{Float64} nodes
• w::Vector{Float64} normalised weights (sum to unity)

Geometric mean radius of a log-normal distribution from its effective radius.

For a log-normal number distribution, reff = rg exp(2.5 ln²σ_g).

Arguments:

• r_eff::Float64 effective (area-weighted mean) radius [m]
• σ_g::Float64 geometric standard deviation (≥ 1)

Returns:

• r_g::Float64 geometric mean radius [m]

Analytic mean particle volume of a log-normal distribution.

Arguments:

• r_eff::Float64 effective radius [m]
• σ_g::Float64 geometric standard deviation (≥ 1)

Returns:

• V::Float64 number-weighted mean volume [m3]

Quadrature nodes for a log-normal size distribution.

Nodes with negligible weight are removed, and the remaining weights renormalised. A monodisperse distribution (σg = 1) returns a single node at reff.

Arguments:

• r_eff::Float64 effective radius [m]
• σ_g::Float64 geometric standard deviation (≥ 1)

Optional arguments:

• n::Int number of Gauss-Hermite nodes

Returns:

• r::Vector{Float64} radii [m]
• w::Vector{Float64} number weights (sum to unity)

Mass absorption and scattering coefficients over a log-normal size distribution.

Coefficients are per unit mass of condensate, as required by SOCRATES: k = ⟨σ⟩ / (ρ ⟨V⟩).

Arguments:

• λ::Vector{Float64} wavelengths [m]
• m::Vector{ComplexF64} complex refractive index at each wavelength
• r_eff::Float64 effective radius [m]
• σ_g::Float64 geometric standard deviation (≥ 1)
• ρ::Float64 bulk density of the particle material [kg m-3]

Optional arguments:

• n::Int number of quadrature nodes

Returns:

• k_abs::Vector{Float64} mass absorption coefficient [m2 kg-1]
• k_sca::Vector{Float64} mass scattering coefficient [m2 kg-1]
• g::Vector{Float64} asymmetry parameter

Mie efficiencies of a homogeneous sphere in the Rayleigh limit.

Valid for size parameter x << 1 and |m|x << 1.

Arguments:

• x::Float64 size parameter, 2πr/λ
• m::ComplexF64 complex refractive index n + ik, with k ≥ 0 for absorption

Returns:

• Qext::Float64 extinction efficiency
• Qsca::Float64 scattering efficiency
• g::Float64 asymmetry parameter

Mie efficiencies of a homogeneous sphere.

Implementation of the BHMIE algorithm (Bohren & Huffman 1983, Appendix A), with the number of terms set by Wiscombe (1980). Falls back to the Rayleigh limit for very small size parameters, and clamps very large size parameters to X_MAX.

Arguments:

• x::Float64 size parameter, 2πr/λ
• m::ComplexF64 complex refractive index n + ik, with k ≥ 0 for absorption

Returns:

• Qext::Float64 extinction efficiency
• Qsca::Float64 scattering efficiency
• g::Float64 asymmetry parameter

Optical properties averaged over a log-normal size distribution.

Calculated for each wavelength and refractive index, using Gauss-Hermite quadrature.

Arguments:

• λ::Float64 wavelength [m]
• m::ComplexF64 complex refractive index n + ik
• r_eff::Float64 effective radius [m]
• σ_g::Float64 geometric standard deviation (≥ 1)

Optional arguments:

• n::Int number of quadrature nodes

Returns:

• σ_ext::Float64 mean extinction cross-section per particle [m2]
• σ_sca::Float64 mean scattering cross-section per particle [m2]
• g::Float64 scattering-weighted asymmetry parameter
• V::Float64 mean particle volume [m3]

Contains module for calculating aerosol optical properties at runtime

Aerosol and cloud particle optical properties are calculated from the complex refractive index (n, k) of the particle material using Mie theory (see the mie module), for a log-normal size distribution. The resultant spectral mass absorption coefficient, mass scattering coefficient, and asymmetry parameter are averaged over each band of a SOCRATES spectral file, weighted by the stellar spectrum ('thin' averaging).

Integral of the flux across one segment of the stellar spectrum, from λ0 to x. Uses a power law between the end points where both fluxes are positive (exact for the λ^-4 Rayleigh-Jeans tail, which is often sparsely sampled), and linear otherwise.

Band-averaged aerosol optical properties.

Performs 'thin' averaging as in SOCRATES scatter_average, weighted by the stellar spectrum: k̄ = ∫ k w dλ / ∫ w dλ ḡ = ∫ g ksca w dλ / ∫ ksca w dλ. Where the stellar spectrum has no flux within a band, uniform weighting is used.

Arguments:

• bands::Matrix{Float64} band edges [m], size (nbands, 2)
• star::NTuple{3,...} stellar spectrum, as returned by star_cumulative
• λ_tab::Vector{Float64} wavelengths at which to include extra grid points [m]
• props::Function function mapping a wavelength vector [m] to a tuple (k_abs, k_sca, g, extrap) of equal-length vectors

Returns:

• k_abs::Vector{Float64} band-mean mass absorption coefficient [m2 kg-1]
• k_sca::Vector{Float64} band-mean mass scattering coefficient [m2 kg-1]
• g::Vector{Float64} band-mean asymmetry parameter
• f_ext::Vector{Float64} fraction of weight in each band which was extrapolated

Wavelength grid within a single correlated-k band.

Union of log-spaced points spanning the band and (a subset of) the tabulated refractive index wavelengths inside the band.

Arguments:

• λ_lo::Float64 short wavelength edge of band [m]
• λ_hi::Float64 long wavelength edge of band [m]
• λ_tab::Vector{Float64} tabulated refractive index wavelengths [m]

Returns:

• λ::Vector{Float64} sorted wavelength grid including the band edges [m]

Integration weights of the stellar spectrum over a wavelength grid.

Each grid point is assigned the integral of the stellar flux over its cell, with cell boundaries at the midpoints between grid points. The stellar spectrum is integrated at its native resolution, and is taken to be zero outside of its tabulated range.

Arguments:

• λ::Vector{Float64} sorted wavelength grid [m]
• star::NTuple{3,...} stellar spectrum, as returned by star_cumulative

Returns:

• w::Vector{Float64} weights (arbitrary units)
• dλ::Vector{Float64} cell widths [m]

Calculate band-averaged optical properties of an aerosol from Mie theory.

Arguments:

• material::String material name, selecting refractive index and density
• r_eff::Float64 effective radius [m]
• σ_g::Float64 geometric standard deviation of log-normal distribution
• bands::Matrix{Float64} band edges [m], size (nbands, 2)
• star_wl::Vector{Float64} stellar spectrum wavelengths [nm]
• star_fl::Vector{Float64} stellar spectral flux (any units, per unit wavelength)
• nk_dir::String refractive index directory

Returns on success:

• k_abs::Vector{Float64} band-mean mass absorption coefficient [m2 kg-1]
• k_sca::Vector{Float64} band-mean mass scattering coefficient [m2 kg-1]
• g::Vector{Float64} band-mean asymmetry parameter
• f_ext::Vector{Float64} fraction of weight in each band which was extrapolated

Returns on failure:

• false failure to read refractive index file

Interpolate refractive index to a given wavelength.

The real part is interpolated linearly in log(λ). The imaginary part is interpolated linearly in log(k) against log(λ) where both neighbouring values are positive, and linearly otherwise. Outside of the tabulated range, the edge values are used.

Arguments:

• λ_tab, n_tab, k_tab tabulated data, as returned by read_nk
• λ::Float64 wavelength at which to evaluate [m]

Returns:

• m::ComplexF64 complex refractive index n + ik
• extrap::Bool whether the wavelength is outside the tabulated range

List materials which have both a refractive index file and a known density.

Arguments:

• nk_dir::String refractive index directory

Returns:

• materials::Vector{String} sorted list of supported materials

Path to the refractive index file for a given material.

Arguments:

• material::String material name (e.g. "SiO2_amorph")
• nk_dir::String refractive index directory

Returns:

• path::String path to file

Read refractive index data from a text file.

Accepts files with three numeric columns (wavelength [micron], n, k), or more columns in which case the last three are used. Data are sorted by wavelength, and duplicated wavelengths are averaged.

Arguments:

• path::String path to txt file

Returns on success:

• λ::Vector{Float64} wavelength [m]
• n::Vector{Float64} real part of the refractive index
• k::Vector{Float64} imaginary part of the refractive index (≥ 0)

Returns on failure:

• false failure to read file

Prepare a stellar spectrum for use as a weighting function.

Sorts the spectrum, converts wavelengths to metres, and tabulates its cumulative integral using power-law segments within each band (see _segment_integral).

Arguments:

• star_wl::Vector{Float64} wavelengths [nm]
• star_fl::Vector{Float64} spectral flux (any units, per unit wavelength)

Returns on success:

• λ::Vector{Float64} sorted, unique wavelengths [m]
• f::Vector{Float64} non-negative flux at each wavelength
• C::Vector{Float64} cumulative integral of flux at each wavelength

Returns on failure:

• false failure to prepare the stellar spectrum

Cumulative integral of the stellar spectrum up to a given wavelength.

Arguments:

• star::NTuple{3,...} stellar spectrum, as returned by star_cumulative
• x::Float64 wavelength [m]

Returns:

• C::Float64 integral of the flux from the shortest wavelength up to x

This module handles chemistry, condensation, and evaporation.

Note the important distinctions between the variables which store atmospheric composition.

• gas_ovmr stores VMRs inputted by the user, which are usually constant in height.
• gas_cvmr stores the VMRs calculated by fastchem, which are used as the starting point for condensation calculations.
• gas_vmr stores the runtime gas volume mixing ratios, after all calculations are performed.

Calculate gas-phase composition at dry thermochemical equilibrium.

Uses FastChem to calculate the gas composition at each level of the atmosphere. Volatiles are converted to bulk elemental abundances, which are then provided to FastChem alongside the temperature/pressure profile. FastChem is currently called as an executable, which is not optimal.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• write_cfg::Bool write config and elements

Returns:

• state::Int64 fastchem state (0: success, 1: criticalfail, 2: elemfail, 3: convfail, 4: bothfail)

Handle sub/super-saturation aloft; required for latent heat flux calcaulation

Adjust gas VMRs according to saturation and cold-trap requirements.

Volatiles which are allowed to condense are rained-out at condensing levels until the gas is exactly saturated, not supersaturated. If evaporation is enabled here, it will lead to enhanced mixing ratios at deeper levels as rain is converted back into gas from a liquid state.

Any rain that reaches the surface without being evaporated leads to ocean formation. Disabling evaporation will lead to unclosed energy budget when calculation of latent heat fluxes is performed.

This function can be called after the fastchem calculation.

Does not update aerosols or clouds, which should be handled separately.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Handle sub/super-saturation at the surface, forming oceans.

NOTE: this function does not reset to atmos to its original state before operating.

If a condensable is supersaturated at the surface, its partial surface pressure is reduced to exactly saturation. The condensed mass is added to the ocean reservoir. If a condensable is subsaturated at the surface, its partial pressure is increased to exactly saturation, subject to the amount of ocean available. Reduces or increases the total surface pressure accordingly.

Accounts for mmw ratio when converting from partial pressures to masses: mi = (pi/g) * (mui / mutot) where mi has units [kg/m^2] and mutot is the total mixture MMW.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Returns:

• any_changed::Bool did any component condense or evaporate?

Run condensation and chemistry schemes as required.

This function is designed as a wrapper for appropriately handling these three schemes together in the correct order, so that variables are appropriately updated. Steps:

1. call _sat_surf! to handle saturation at the surface, and adjust the pressure grid
2. call _chem_gas! to handle gas-phase chemistry in the column
3. call _sat_aloft! to handle saturation aloft, above the surface.
4. update aerosols and clouds

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• do_surf::Bool do saturation cond/evap at surface
• do_chem::Bool do thermochemistry in the column
• do_aloft::Bool do saturation cond/evap aloft

Returns:

• state::Int64 fastchem state (0: success, 1: criticalfail, 2: elemfail, 3: convfail, 4: bothfail)

Normalise gas VMRs, keeping condensates unchanged

Only acts on a single model level.

Parameters:

• atmos::atmosphere.Atmos_t atmosphere structure
• i::Int64 level index to normalise

Reset gas VMRs to post-chemistry values, overwriting condensate effect on VMR

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.

Reset mixing ratios, pressures, and oceans to their original values

Wrapper module around the various solver modules.

Main multicol module for handling multiple 1D-atmospheric columns

The user should create a single instance of Atmos_t first, and then use that to instantiate the Globe_t struct.

SOCRATES is not thread-safe, so the original atmos will be modified in-place. Other variables will be copied to/from it as needed, using auxiliary atmos variables.

Check if the output of a function is considered a success

Arguments:

• out the output to check

Returns:

• Bool whether the output is successful

Wrapper for calling a function agnostically of either an atmosphere or globe

If ag is a 1D-atmosphere type, func will be called directly on it. Alternatively, if ag is a multicol globe type, func will be called for each column using call_for_globe!.

Arguments:

• ag::Union{Atmos_t,Globe_t} either an atmosphere or globe instance
• func::Function function to call, which must take an Atmos_t as its first argument
• args... additional arguments to pass to the function
• kwargs... additional keyword arguments to pass to the function

Returns:

• succ::Bool whether the function succeeded for all cases

Wrapper calling a function across multiple columns in a globe

Arguments:

• globe::Globe_t globe struct instance containing the columns
• func::Function function to call for each column, which must take an Atmos_t as its first argument
• args... additional arguments to pass to the function, after the Atmos_t argument
• kwargs... additional keyword arguments to pass to the function

Returns:

• succ::Bool whether the function succeeded for all cases

Setup the globe with the given parameters

Arguments:

• globe::Globe_t globe struct to setup
• atmos::Atmos_t original 1D-atmosphere to use as a basis
• lons::Array{Float64,1} longitudes for each column (degrees)
• lats::Array{Float64,1} latitudes for each column (degrees)
• redist_flux::Array{Float64,1} heat redistribution flux for each column [W m-2]
• redist_Pmid::Array{Float64,1} pressure midpoints for heat redistribution [Pa]
• redist_Pwid::Array{Float64,1} pressure widths for

Returns:

• Bool globe was successfully constructed

Copy arrays and other data from one atmosphere struct to another.

Arguments:

• dst::Atmos_t destination atmosphere to copy to
• src::Atmos_t source atmosphere to copy from

Returns:

• Bool whether the copy was successful

De-construct the globe

This resets the globe and deallocates memory for all atmosphere columns.

Arguments:

• globe::Globe_t the globe to de-construct

Set a quantity to be a given value, for all columns in the globe**

Arguments:

• globe::Globe_t globe struct containing the columns to update
• quantity::Symbol the quantity to set (e.g. :tmpsurf, :fluxint)
• value the value to set the quantity to for all columns

Returns:

• succ::Bool whether the update was successful

Set heat-redistribution flux profiles for globe's columns.

Update heat-redistribution fluxes and profiles for all columns in globe.

Arguments:

• globe::Globe_t globe struct containing the columns to update

Returns:

• `succ::Bool whether the update was successful

Set surface boundary condition for columns in globe

Arguments:

• globe::Globe_t globe struct containing the columns to update
• sol_type::Int64 solution type for surface boundary condition (1: Tsurf, 2: Tmagma, 3: flux_int)

Contains functions for plotting/diagnosing the atmosphere

Get x-axis limits and logarithmic ticks for a plot against wavelength.

The limits are the requested range, clipped to the range of the data. If this leaves an empty range, the full range of the data is used instead.

Arguments:

• x::Array{Float64,1} wavelengths of the plotted data (any units)
• wlmin::Float64 minimum wavelength to plot (same units as x)
• wlmax::Float64 maximum wavelength to plot (same units as x)

Returns:

• xlims::Tuple axis limits
• xticks::Array tick locations, at integer powers of ten (or the limits, if the range spans less than a decade)

Return (p_top, p_bot) pressure axis limits [bar] for a standard profile plot.

Return pressure tick mark values [bar] on a log10 scale for a standard profile plot.

Format an integer as a plain decimal string.

Plot telescope bandpasses as translucent vertical spans.

Arguments:

• plt plot object to modify
• xlims::Tuple{Float64,Float64} x-axis limits on plot
• instruments list of instruments to plot
• prs pressure level on figure y-axis
• ylims y-axis limits on plot

Plot tau=reftau isoline using precomputed taup arrays.

Apply a signed symmetric log10 transform, returning zero for |v| < thresh.

Arguments:

• v::Float64 value to transform
• thresh::Float64 threshold below which to return zero (default: 1.0)

Returns:

• Float64 log10 transformed value

Convert still-frame images into an animation

Uses FFMPEG provided by Julia library.

Arguments:

• output_dir::String folder in which to save the animation
• frames_dir::String folder containing the frames

Optional arguments:

• output_fmt::String output file format: mp4, mov, ...
• frames_fmt::String input frame format: png, jpg, ...
• duration::Float64 animation duration [seconds]

Combined multi-panel plot used for tracking behaviour of the solver at runtime.

Plot jacobian matrix

Arguments:

• b::Array{Float64,2} jacobian matrix (∂r/∂x) to plot as a colormap
• fname::String filename to save the plot
• perturb::Array{Bool,1} boolean array indicating which levels were perturbed

Plot band-averaged aerosol optical properties.

Shows the mass extinction coefficient, single scattering albedo, and asymmetry parameter of each aerosol, as stored in the spectral file.

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels
• wlmin::Float64 minimum wavelength to plot [nm]
• wlmax::Float64 maximum wavelength to plot [nm]

Plot spectral albedo (ratio of SWUP to SWDN)

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels
• wlmin::Float64 minimum wavelength to plot [nm]
• wlmax::Float64 maximum wavelength to plot [nm]

Plot the cloud and aerosol mass mixing ratios.

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels
• title::String title for the plot

Plot contribution function at different bands.

The contribution function is plotted with one line (vs pressure) per spectral band.

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels
• cf_min::Float64 minimum contribution function value to plot (log10 units)

Plot normalised contribution function, per band, versus pressure

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels
• wlmin::Float64 minimum wavelength to plot [nm]
• wlmax::Float64 maximum wavelength to plot [nm]

Plot emission spectrum at the TOA

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels
• wlmin::Float64 minimum wavelength to plot [nm]
• wlmax::Float64 maximum wavelength to plot [nm]

Plot the fluxes at each pressure level

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels
• incl_eff::Bool whether to include the intrinsic (or interior) heat flux as a dashed line
• incl_mlt::Bool whether to include the convective flux as a solid line
• incl_cdct::Bool whether to include the conductive flux as a solid line
• incl_latent::Bool whether to include the latent heating flux as a solid line
• incl_deep::Bool whether to include the deep heating flux as a solid line
• title::String title for the plot

Globe plot of multi-column atmosphere climate and energy balance.

Left panel: temperature profiles, coloured by column longitude. Right panel: heating rate profiles, coloured by column longitude.

Arguments:

• globe::multicol.Globe_t globe object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels

Plot the temperature-pressure and Kzz profile.

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels
• incl_magma::Bool include the magma temperature as a scatter point
• title::String title for the plot

Plot the radius vs pressure profile.

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels
• title::String title for the plot

Plot optical depth per band as heatmap (LW + SW)

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of each plot panel in pixels
• size_y::Int64 height of each plot panel in pixels
• wlmin::Float64 minimum wavelength to plot [nm]
• wlmax::Float64 maximum wavelength to plot [nm]

Plot the gas phase volume mixing ratios at each cell-centre location.

Arguments:

• atmos::atmosphere.Atmos_t atmosphere object
• fname::String filename to save the plot (if empty, does not save)
• size_x::Int64 width of the plot in pixels
• size_y::Int64 height of the plot in pixels

Provides self-contained physical formulae and calculations.

Calculate planetary equilibrium temperature.

https://en.wikipedia.org/wiki/Planetaryequilibriumtemperature?useskin=vector

Arguments:

• S::Float64 Bolometric instellation [W m-2]
• α::Float64 Bond albedo

Returns:

• Teq::Float64 Planetary equilibrium temperature [K]

Calculate planetary skin temperature.

https://en.wikipedia.org/wiki/Skintemperature(atmosphere)?useskin=vector

Arguments:

• S::Float64 Bolometric instellation [W m-2]
• α::Float64 Bond albedo

Returns:

• Tskin::Float64 Planetary skin temperature [K]

Calculate thermal diffusivity.

https://en.wikipedia.org/wiki/Thermal_diffusivity?useskin=vector

Arguments:

• k::Float64 Thermal conductivity [W m-1 K-1]
• ρ::Float64 Density [kg m-3]
• cp::Float64 Specific heat capacity [J K-1 kg-1]

Returns:

• α::Float64 Thermal diffusivity [m2 s-1]

Calculate radial component of centripetal acceleration.

Note that this is only the component of the centripetal acceleration which acts in the radial direction, and is relevant for calculating the effective gravity at the surface of a rotating planet. This means a_c is zero at the poles.

The full centripetal acceleration is given by the equation below, where d is the distance from the rotation axis and p is the rotation period.

a_c = 4 * pi^2 * d / p^2

The distance d is equal to r * cos(θ), so the equation can be rewritten as:

a_c = 4 * pi^2 * d * cos(θ) / p^2

And then to get the radial component, we multiply by cos(θ) again:

a_c = r * ( 2 * pi * cos(θ) / p )^2

Arguments:

• p::Float64 Axial rotation period [s]
• r::Float64 Radius of this layer [m]
• θ::Float64 Latitude of this column [degrees]

Returns:

• a_c::Float64 Centripetal acceleration [m s-2]

Evaluate the Planck function at a given wavelength and temperature.

Integrated over a hemisphere.

Arguments:

• wave::Float64 Wavelength [nm]
• tmp::Float64 Temperature [K]

Returns:

• flx::Float64 Spectral flux density [W m-2 nm-1]

Calculate gravitational acceleration.

Using the Newtonian formula for universal gravitation in spherical geometry.

Arguments:

• mass::Float64 Enclosed mass [kg]
• radius::Float64 Enclosed radius [m]

Returns:

• grav::Float64 Gravitational acceleration [m s-2]

Write atmosphere to NetCDF or CSV files

Write a string into column i of a NetCDF character variable, padded with spaces and truncated to nchars.

Write cell-edge energy fluxes to a CSV file

Arguments

• atmos::Atmos_t Atmosphere object
• fname::String Filename to write to

Write verbose atmosphere data to a NetCDF file

Note that the content of the NetCDF file is designed to be compatible with what JANUS writes. As a result, they can both be integrated into PROTEUS without incompatibility.

Check that there's sufficient space to write the file first.

Arguments:

• atmos::Atmos_t Atmosphere object
• fname::String Filename to write to

Returns:

• succ::Bool true if the file was written successfully, false otherwise

Write {Pressure, Temperature, Radius} profile to a CSV file

Arguments

• atmos::Atmos_t Atmosphere object
• fname::String Filename to write to

Module for loading atmospheric states from NetCDF and CSV files.

Load atmosphere data from a NetCDF file.

This must be called after setup! and allocate! have been called on this atmos struct. Does not overwrite energy fluxes within the atmospherem, or other wavelength-dependent properties. Only composition, temperatures, layer properties, and boundary conditions are updated by this function.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• fname::String path to the NetCDF file

Returns:

• ok::Bool loaded ok?