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.
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 0.02 Observation pressure level [bar] (transit radius). Must be > 0.
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 file. Set to '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?.
ini_profile str "isothermal" Shape of initial T(p) guess: 'loglinear', 'isothermal', 'dry_adiabat', 'analytic'. Choices: "loglinear", "isothermal", "dry_adiabat", "analytic".
ls_default int 2 Default linesearch method. 0: disabled, 1: goldensection, 2: backtracking. Choices: 0, 1, 2.
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 2000 Number of steps to use when calculating heights and gravity. Must be > 0.
hydrograv_maxdr float 100000000.0 Maximum step size to use when calculating heights [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?.

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]

Parameter Type Default Description
module str or none none Chemistry module. Choices: none, "vulcan", "dummy".
when str "manually" When to run the chemistry module. Options: manually, offline, online. Choices: "manually", "offline", "online".
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, outgas. Choices: "profile", "outgas".
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.

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.
  • Validate JANUS settings: spectral file selection and temperature-bound ordering.
  • 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