Skip to content

Atmosphere and chemistry

The [atmos_clim] section configures the atmospheric climate module (radiative-convective structure and surface energy balance). The [atmos_chem] section configures atmospheric chemistry (photochemical kinetics).

Submodule documentation: AGNI | SOCRATES | JANUS | VULCAN. See also Model description.

Atmosphere climate [atmos_clim]

This section carries the shared grid, spectral, radiative, and surface-boundary parameters used by every climate module; the surf_state parameter selects the surface energy balance scheme (mixed_layer, fixed, or skin).

Parameter Type Default Description
module str "agni" Which atmosphere module to use. Choices: "dummy", "agni", "janus".
spectral_group str "Honeyside" Spectral file group defining gas opacities. See https://proteus-framework.org/SOCRATES/Reference/proteus_spectral_file_reference.html.
spectral_bands str "48" Number of wavenumber bands in k-table.
spectral_cache str or none none Folder in which to reuse prepared spectral files across runs that share a stellar spectrum. None disables the cache and every run builds its own.
num_levels int 50 Number of vertical atmosphere levels. Must be >= 15.
p_top float 1e-06 Top-of-atmosphere pressure [bar]. Must be > 0.
p_obs float or Literal or none 0.02 Observation pressure level [bar] (transit radius). Set to 'none' (-> None) to instead let AGNI determine this pressure level self-consistently from the optical depth (see agni.tau_obs, agni.wl_obs); AGNI only.
overlap_method str "ee" Gas overlap method. Choices: 'ro', 'rorr', 'ee'.

Radiative properties

Parameter Type Default Description
rayleigh bool true Include Rayleigh scattering (AGNI, JANUS only).
cloud_enabled bool false Enable water cloud radiative effects (AGNI, JANUS only).
cloud_alpha float 0.0 Condensate retention fraction (0 = full rainout, 1 = fully retained). Must be >= 0 and <= 1.
aerosols_enabled bool false Enable aerosol radiative effects.
albedo_pl float 0.0 Planetary bond albedo (0 to 1). Must be >= 0 and <= 1.
surf_greyalbedo float 0.1 Grey surface albedo. Must be >= 0 and <= 1.

Surface boundary condition

Parameter Type Default Description
surf_state str "skin" Surface energy balance scheme. Choices: "mixed_layer", "fixed", "skin".
surface_d float 0.01 Conductive skin thickness [m]. Must be > 0.
surface_k float 2.0 Conductive skin thermal conductivity [W m-1 K-1]. Must be > 0.

Solver limits

Parameter Type Default Description
tmp_minimum float 0.5 Minimum temperature throughout the atmosphere [K] (AGNI, JANUS only). Must be > 0.

AGNI [atmos_clim.agni]

AGNI is a detailed radiative-convective equilibrium solver written in Julia. It iteratively solves for the atmospheric temperature-pressure profile that balances absorbed stellar radiation with outgoing thermal emission and interior heat flux. The fastchem_* parameters apply when chemistry = "eq", and the grey_opacity_* parameters when spectral_file = "greygas".

Physics

Parameter Type Default Description
solve_energy bool true Solve for an energy-conserving atmosphere solution.
convection bool true Account for convective heat transport, using MLT.
conduction bool false Account for conductive heat transport, using Fourier's law.
sens_heat bool true Include sensible heat flux at surface.
rainout bool true Enable volatile condensation and evaporation in the atmosphere.
oceans bool true Enable volatile ocean formation at the surface.
latent_heat bool false Account for latent heat from condense/evap when solving temperature profile. Requires condensation=true.
real_gas bool false Use real gas equations of state in atmosphere, where possible.
thermo_functions bool true Use temperature-dependent thermodynamic properties.
chemistry str or none none Atmospheric chemistry treatment. Choices: none, "eq".
mlt_criterion str "s" Convection criterion. Options: (l)edoux, (s)chwarzschild. Choices: "l", "s".

Surface properties

Parameter Type Default Description
surf_material str "greybody" Surface scattering material: the file name of a Hammond et al. (2024) spectrum, e.g. 'lunarmarebasalt.dat', or 'greybody' to use surf_greyalbedo.
surf_roughness float 0.001 Characteristic surface roughness scale [metres]. Must be > 0.
surf_windspeed float 2.0 Characteristic surface wind speed [m/s]. Must be > 0.

Condensation

Parameter Type Default Description
phs_timescale float 1000000.0 Relaxation timescale for phase changes (condensation/evaporation) [seconds]. Must be > 0.
evap_efficiency float 0.01 Efficiency of raindrop re-evaporation (0 to 1). Must be <= 1 and >= 0.

Solver tuning

Parameter Type Default Description
solution_atol float 0.5 Absolute tolerance on the atmosphere solution [W/m2]. Must be > 0.
solution_rtol float 0.15 Relative tolerance on the atmosphere solution. Must be > 0.
psurf_thresh float 0.1 Use the transparent-atmosphere solver when P_surf is less than this value [bar]. Must be >= 0.
dx_max float 35.0 Nominal maximum step size to T(p) during the solver process, although this is dynamic. Must be > 1.
dx_max_ini float 50.0 Initial maximum step size to T(p) when AGNI is called in the first few PROTEUS loops. Must be > 1.
max_steps int 200 Maximum number of iterations before giving up. Must be > 2.
perturb_all bool false Recalculate entire jacobian matrix at every iteration? Has no effect when broyden is enabled.
ini_profile str "isothermal" Shape of initial T(p) guess: 'loglinear', 'isothermal', 'dry_adiabat', 'analytic'. Choices: "loglinear", "isothermal", "dry_adiabat", "analytic".
ls_default int 3 Default linesearch method. 0: disabled, 1: goldensection, 2: backtracking, 3: non-monotone Armijo. Choices: 0, 1, 2, 3.
broyden bool true Update the jacobian with Broyden's method between finite-difference evaluations, to reduce the number of radiative transfer calculations. Intended for use with ls_default = 3. Disabled when PROTEUS retries a failed solve.
fdo int 2 Numerical order of finite-difference for jacobian. 2 or 4. Choices: 2, 4.
verbosity int 1 Logging and output verbosity for agni (0:none, 1:info, 2:debug). Choices: 0, 1, 2.

Spectral and gas allocation

Parameter Type Default Description
spectral_file str or none none Path to AGNI spectral file, or 'greygas' to enable the grey-gas RT scheme. If None, will use atmos_clim.spectral_group and atmos_clim.spectral_bands.
grey_opacity_lw float 10.0 Grey longwave opacity [m2 kg-1], used when spectral_file='greygas'. Must be > 0.
grey_opacity_sw float 0.0001 Grey shortwave opacity [m2 kg-1], used when spectral_file='greygas'. Must be > 0.
check_safe_gas bool true Require at least one "safe" gas (dry, has opacity, has thermo) when allocating AGNI atmosphere. Set False to allow compositions that AGNI would otherwise reject (e.g. for tests or exotic setups).

FastChem equilibrium chemistry (used when chemistry = "eq")

Parameter Type Default Description
fastchem_floor float 1000.0 Minimum temperature allowed to be sent to FC. Must be > 0.0.
fastchem_maxiter_chem int 60000 Maximum FC iterations (chemistry). Must be > 200.
fastchem_maxiter_solv int 20000 Maximum FC iterations (internal solver). Must be > 200.
fastchem_xtol_chem float 0.0001 FC solver tolerance (chemistry). Must be > 0.0.
fastchem_xtol_elem float 0.0001 FC solver tolerance (elemental). Must be > 0.0.

Hydrostatic integration

Parameter Type Default Description
hydrograv_steps int 2048 Number of steps to use when calculating heights and gravity. Must be > 0.
hydrograv_maxdr float 6335439.0 Maximum step size to use when calculating heights [m]. Must be > 0.
hydrograv_hilldr float 6335.439 Maximum step size to use beyond the Hill radius [m]. Must be > 0.
hydrograv_mindr float 1e-05 Minimum step size to use when calculating heights [m]. Must be > 0.
hydrograv_ming float 0.0001 Minimum allowed gravity in the atmosphere [m/s^2]. Must be > 0.
hydrograv_constg bool false Constant gravity with height?.
hydrograv_selfg bool true Include self-gravity of the atmosphere?.

Aerosol optics (used for auto-discovered Mie-theory aerosols)

Parameter Type Default Description
aerosol_r_eff float 1e-06 Effective radius of log-normal size distribution for Mie aerosols [m]. Must be > 1e-10 and <= 1.0.
aerosol_sigma_g float 1.65 Standard deviation of log-normal particle-size distribution for Mie aerosols. Must be >= 1.0 and <= 100.0.

Photosphere from optical depth (used when atmos_clim.p_obs='none')

Parameter Type Default Description
tau_obs float 0.02 Reference vertical optical depth defining the photosphere, used when atmos_clim.p_obs='none'. Must be > 1e-10 and <= 10000000000.0.
wl_obs float 1.125e-06 Reference wavelength [m] at which tau_obs is evaluated, used when atmos_clim.p_obs='none'. Must be > 1e-10 and <= 1.0.

JANUS [atmos_clim.janus]

JANUS is a fast 1-D radiative-convective atmosphere model. It is computationally lighter than AGNI and suitable for parameter sweeps.

Parameter Type Default Description
F_atm_bc int 0 Outgoing flux boundary: 0 (TOA) or 1 (surface). Choices: 0, 1.
tropopause str or none none Tropopause scheme. Choices: none, "skin", "dynamic".
cloud_alpha float 0.0 Condensate retention fraction (0 = full rainout, 1 = fully retained). Must be >= 0 and <= 1.
tmp_maximum float 5000.0 Solver temperature ceiling [K]. Must be > 0.

Dummy atmosphere [atmos_clim.dummy]

A grey-body parameterisation: \(T_\mathrm{rad} = T_\mathrm{surf} \cdot (1 - \gamma)\).

Parameter Type Default Description
gamma float 0.5 Atmosphere opacity factor between 0 and 1. Must be >= 0 and <= 1.
height_factor float 3.0 A multiplying factor applied to the ideal-gas scale height. Must be >= 0.
fixed_flux float -1.0 If > 0, return this constant flux [W/m2] instead of computing it. Default -1 (disabled, use the grey-body calculation).

Atmospheric chemistry [atmos_chem]

Chemistry runs after the simulation, at the snapshots set by times, either automatically (mode = "offline") or with proteus offchem. See Postprocessing and chemistry for when it runs, which snapshots it processes and the files it writes.

Parameter Type Default Description
module str or none none Chemistry module. Choices: none, "vulcan", "dummy".
mode str or none none When to run the chemistry module automatically. Options: none (only with proteus offchem), offline (after the simulation ends), online (not yet implemented). Choices: none, "offline", "online".
times str or list "end" Snapshots to run the chemistry on, with mode = 'offline' or proteus offchem. Options: end (the final state), all (every atmosphere snapshot), or a list of times [yr], each mapped to the nearest atmosphere snapshot.
photo_on bool true Use photochemistry.
Kzz_on bool true Use Kzz.
Kzz_const float or none none Constant Kzz value [cm2/s]. If 'none', Kzz is read from NetCDF file.
moldiff_on bool true Use molecular diffusion.
updraft_const float 0.0 Updraft velocity [cm/s].

VULCAN [atmos_chem.vulcan]

VULCAN solves photochemical kinetics for atmospheric composition, computing steady-state mixing ratios from a chemical reaction network.

Parameter Type Default Description
clip_fl float 1e-20 Stellar flux floor [ergs cm-2 s-1 nm-1].
clip_vmr float 1e-10 Neglect species with surface VMR < clip_vmr.
make_funs bool true Make functions from chemical network.
ini_mix str "profile" Initial mixing ratios. Options: profile (the climate profile), outgas (the surface mixing ratios at every level), previous (the result of the latest earlier chemistry snapshot, interpolated in log pressure; needs fix_surf = true; falls back to profile when there is none). Choices: "profile", "outgas", "previous".
fix_surf bool false Fix the surface mixing ratios based on outgassed composition.
network str "SNCHO" Chemical network. Options: CHO, NCHO, SNCHO. Choices: "CHO", "NCHO", "SNCHO".
save_frames bool false Save simulation state as plots.
yconv_cri float 0.05 Steady state - max change in mixing ratio over test period.
slope_cri float 0.0001 Steady state - max rate of change of mixing ratio over test period.
yconv_min float 0.5 Steady state - alternative max change in mixing ratio, accepted when the rate of change is also below VULCAN's diffusion-limited slope. Must be > 0.
st_factor float 0.5 Steady state - the test period starts at this fraction of the elapsed model time, in (0, 1). Must be > 0 and < 1.
conv_step int 100 Steady state - maximum number of solver steps the test period reaches back. Must be > 0.
use_vm_mol bool false Use the upwind scheme for molecular diffusion. Must be false, because VULCAN does not support it yet.
use_vz bool false Include vertical advection at the constant updraft velocity atmos_chem.updraft_const.
use_condense bool false Include condensation of every gas that the selected network can condense.
use_settling bool false Include gravitational settling of the condensate particles. Has an effect only with use_condense.
r_p float 0.005 Default radius of every condensate particle [cm]. Must be > 0.
runtime float 1e+22 Maximum integrated model time [s]. Must be > 0.
dttry float 1e-08 Initial solver timestep [s]. Must be > 0.
dt_min float 1e-10 Minimum solver timestep [s]. Must be > 0.
atol float 0.1 Absolute tolerance on number density [cm-3]. Must be > 0.
mtol float 1e-22 Mixing ratio below which a species is ignored in the truncation error. Must be > 0.
mtol_conv float 1e-20 Mixing ratio below which a species is ignored in the steady-state test. Must be > 0.
flux_atol float 1.0 Absolute tolerance on the actinic flux [photons cm-2 s-1 nm-1]. Must be > 0.
rtol float 0.9 Relative tolerance for adjusting the solver step size. Must be > 0.
post_conden_rtol float 0.1 Relative tolerance used once condensation stops. Must be > 0.

Constraints

Cross-field constraints enforced when the config file loads:

  • Aerosol scattering needs band-resolved RT.
  • Validate AGNI settings: pressure ordering, surface-state support, rainout, spectral file.
  • Refuse ini_mix = 'previous' unless the surface mixing ratios are fixed.
  • Validate JANUS settings: spectral file selection and temperature-bound ordering.
  • Refuse coupled chemistry, and automatic chemistry without a module.
  • p_obs is either a positive pressure [bar], or None ('none' in the config file), which lets AGNI determine the photosphere self-consistently from optical depth instead. The latter is only meaningful for AGNI.
  • Reject Rayleigh scattering with the dummy module or AGNI in grey-gas mode.
  • Reject enabling this option when the dummy atmos_clim module is selected.

See also: Atmosphere modules | Earth analogue tutorial