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.

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

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. Thermal conductivity: W m-1 K-1.

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)

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.

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.
• 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]

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.

Set non-finite values in an array equal to a given fill value.

Arguments:

• arr array potentially containing non-finite values
• fill replacement value to fill with

Solve RT using double grey-gas formulation

Simple two-stream double grey RT solver which integrates fluxes from the TOA and BOA. Uses two opacity values to represent the LW and SW components of the flux field. Loosely following this tutorial, which is based on Pierrehumbert (2010). https://brian-rose.github.io/ClimateLaboratoryBook/courseware/radiative-transfer/

• Optical depth across each layer, τ = κ * (p_bot - p_top) / g
• Transmissivity of each layer, T = exp(-τ)
• Emissivity of each layer, ε = 1 - T
• Where κ is the opacity, p is pressure, and g is gravity.

Arguments:

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

Solve radiative transfer using SOCRATES

Imports SOCRATES wrapper from the atmosphere module, rather than loading it twice.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• lw::Bool True: longwave calculation. False: shortwave calculation.

Optional arguments:

• calc_cf::Bool calculate contribution function and store optical depths?
• gauss_ir::Bool using gaussian angular integration in IR, otherwise uses two-stream approximation
• rescale_pf::Bool perform rescaling on phase function

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.

Arguments:

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

Calculate dry convective fluxes using mixing length theory.

Convective energy transport fluxes are calculated at every level edge, just like the radiative fluxes. This is not compatible with moist convection. By using MLT to parameterise convection, we can also calculate Kzz directly.

Uses the mixing length formulation outlined by Joyce & Tayar (2023), which was also implemented in Lee et al. (2024), and also partially outlined in the review by Robinson & Marley (2014). https://arxiv.org/abs/2303.09596 https://doi.org/10.1093/mnras/stae537 https://ui.adsabs.harvard.edu/abs/1962JGR....67.3095B/abstract

The adiabatic lapse rate is formulated as: ∇_ad = dln(T)/dln(P) = (P/T)*(dT/dP) = (P/T)*(1/[ρ c_p]) for an ideal gas, this becomes: ∇_ad = R / (μ c_p)

The mixing length is set to asymptotically approach H (for z>>H) or z (for z<H) as per Blackadar (1962). Alternatively, it can be set equal to H. https://doi.org/10.1029/JZ067i008p03095

The scale height is formulated as: Hp = P / (ρ g) Where ρ is obtained from the equation of state.

To account for convective stability due to compositional gradients, we can use the Ledoux criterion rather than the Schwarzschild criterion. This is described nicely in Gabriel et al. (2014), as well as Salaris & Cassisi (2017). http://dx.doi.org/10.1051/0004-6361/201423442 https://doi.org/10.1098/rsos.170192

In the ideal gas regime, the Ledoux criterion can be simply written as: ∇_ld = ∇_ad + dln(μ)/dln(P) Using Equation (10) of Gabriel+14. Taking β=Pg/P=1 means the gas pressure equals the total pressure, neglecting pressure contributions from ions and electrons.

Arguments:

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

Returns:

• Bool whether the calculation succeeded

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.

Arguments:

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

Returns:

• C_d::Float64 TKE exchange coefficient [dimensionless]

Fill Kzz values for remaining regions of profile.

This function is called after the convective fluxes have been calculated. The Kzz value in the convective regions are already calculated in the MLT scheme.

This function calculates Kzz in the non-convective regions, by extending the Kzz values from the convective region through various parameters.

Arguments:

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

Returns:

• Bool function executed successfully

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

Calculate radiative fluxes using the desired scheme.

Uses the configuration inside the atmos struct. Can either do LW or SW calculation, set by lw function argument.

Arguments:

• atmos::Atmos_t the atmosphere struct instance to be used.
• lw::Bool longwave calculation? Else: shortwave
• calc_cf::Bool=false calculate contribution function and optical depths?

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].

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.

Contains functions for plotting/diagnosing the atmosphere

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 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

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
• wl_max::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
• wl_max::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
• wl_max::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 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

Arguments

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

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?