Creating custom configurations

To create a custom configuration, first make a .yml file. In the file, you can set configuration arguments as key: value pairs to override the default config. YAML parsing is fairly forgiving – values will generally be parsed to the correct type. The only exception is true/false strings. These need quotes around them, or they will be parsed to Bools.

To start the model with a custom configuration, run:

julia --project=examples examples/hybrid/driver.jl --config_file <yaml>

Example

Below is the default Bomex configuration:

job_id: "prognostic_edmfx_bomex_box"
initial_condition: "Bomex"
subsidence: "Bomex"
edmf_coriolis: "Bomex"
ls_adv: "Bomex"
surface_setup: "Bomex"
turbconv: "prognostic_edmfx"
edmfx_upwinding: first_order
edmfx_entr_model: "Generalized"
edmfx_detr_model: "Generalized"
edmfx_sgs_mass_flux: true
edmfx_sgs_diffusive_flux: true
edmfx_nh_pressure: true
prognostic_tke: false
moist: "equil"
config: "box"
hyperdiff: true
x_max: 1e8
y_max: 1e8
z_max: 3e3
x_elem: 2
y_elem: 2
z_elem: 60
z_stretch: false
perturb_initstate: false
dt: "5secs"
t_end: "6hours"
dt_save_state_to_disk: "10mins"
toml: [toml/prognostic_edmfx.toml]

Keys can also point to artifacts. As artifacts are folders, we specify both the artifact name, as we would from the REPL, and file to read from, separated by a /. For example, to drive a single column model with an external forcing file from GCM output, we include the following lines in the configuration:

insolation: "gcmdriven"
external_forcing_file: artifact"cfsite_gcm_forcing"/HadGEM2-A_amip.2004-2008.07.nc

To learn more about artifacts and how they're used in CliMA, visit ClimaArtifacts.jl.

To add a new configuration argument/key, open .buildkite/default_config.yml. Add an entry with the following format:

<argument_name>:
    value: <argument_value>
    help: <help string>

The help field is optional if you don't plan on making a permanent change to the configuration argument.

See below for the full list of configuration arguments.

Default Configuration

Argument	Type	Description
dz_bottom	Float64	Model bottom grid depth. Default: 500m
z_stretch	Bool	Stretch grid in z-direction. [`true` (default), `false`]
h_elem	Int64	number of elements per edge on a cubed sphere
x_elem	Int64	number of horizontal elements in the x-direction
x_max	Float64	Model domain size, x direction. Default: 300km
y_elem	Int64	number of horizontal elements in the y-direction
y_max	Float64	Model domain size, y direction. Default: 300km
z_elem	Int64	number of vertical elements
z_max	Float64	Model top height. Default: 30km
vorticity_hyperdiffusion_coefficient	Float64	Hyperdiffusion coefficient for vorticity (m s-1)
scalar_hyperdiffusion_coefficient	Float64	Hyperdiffusion coefficient for scalar (m s-1)
topography	String	Define the surface elevation profile [`NoWarp` (default),`Earth`,`DCMIP200`,`Agnesi`, `Schar`, `Hughes2023`]
mesh_warp_type	String	Sets the interior mesh warp method [`Linear`, `SLEVE`]
sleve_eta	Float64	If SLEVE coordinates are chosen, sets the `ηₕ` parameter (if z/z_top > ηₕ, no warping is applied)
sleve_s	Float64	If SLEVE coordinates are chosen, sets `s`, the warping decay scale parameter
topo_smoothing	Bool	Choose whether to order-2 smoothing on the LGL mesh
topography_damping_factor	Int64	Factor by which smallest resolved length-scale is to be damped
use_newton_rtol	Bool	Whether to check if the current iteration of Newton's method has an error within a relative tolerance, instead of always taking the maximum number of iterations (only for ClimaTimeSteppers.jl)
newton_rtol	Float64	Relative tolerance of Newton's method (only for ClimaTimeSteppers.jl; only used when `use_newton_rtol` is `true`)
surface_thermo_state_type	String	Surface thermo state type [`GCMSurfaceThermoState` (default), `PrescribedThermoState`]
split_ode	Bool	Use split of ODE problem. Examples: [`true` (implicit, default), `false` (explicit)]
use_krylov_method	Bool	Whether to use a Krylov method to solve the linear system in Newton's method (only for ClimaTimeSteppers.jl)
use_dynamic_krylov_rtol	Bool	Whether to use Eisenstat-Walker forcing instead of a constant relative tolerance in the Krylov method (only for ClimaTimeSteppers.jl)
max_newton_iters_ode	Int64	Maximum number of Newton's method iterations (only for ODE algorithms that use Newton's method)
ode_algo	String	ODE algorithm [`ARS343` (default), `SSP333`, `IMKG343a`, etc.]
krylov_rtol	Float64	Relative tolerance of the Krylov method (only for ClimaTimeSteppers.jl; only used if `use_krylov_method` is `true`)
eisenstat_walker_forcing_alpha	Float64	Value of alpha to use for Eisenstat-Walker forcing (only for ClimaTimeSteppers.jl; only used if `use_krylov_method` and `use_dynamic_krylov_rtol` are `true`)
jvp_step_adjustment	Float64	Amount by which the step size of the forward difference approximation of the Jacobian-vector product in the Krylov method should be scaled (only used if `use_krylov_method` is `true`)
rad	Nothing	Radiation model [`nothing` (default), `gray`, `clearsky`, `allsky`, `allskywithclear`]
idealized_h2o	Bool	Use idealized H2O in radiation model [`false` (default), `true`]
dt_rad	String	Time between calling radiation callback for sphere configurations
idealized_clouds	Bool	Use idealized clouds in radiation model [`false` (default), `true`]
prescribe_clouds_in_radiation	Bool	Use prescribed clouds in radiation model. Clouds are read from ERA5 data and updated every time radiation is called. The year 2010 is used and continuously repeated. This mode only affect radiation and is only relevant for the RRTGMP mode. [`false` (default), `true`]
insolation	String	Insolation used in radiation model [`idealized` (default), `timevarying`, `rcemipii`]
add_isothermal_boundary_layer	Bool	Add an isothermal boundary layer above the domain top for radiation [`false`, `true` (default)]
aerosol_radiation	Bool	Use aerosols in radiation [`false` (default)]
dt_cloud_fraction	String	Time between calling cloud fraction update
config	String	Spatial configuration [`sphere` (default), `column`, `box`, `plane`]
FLOAT_TYPE	String	Float type
dt	String	Simulation time step. Examples: [`10secs`, `1hours`]
t_end	String	Simulation end time. Examples: [`1200days`, `40secs`]
output_dir	Nothing	Output directory
output_dir_style	String	What to do when `output_dir` already exists. With `RemovePreexisting`, `output_dir` is overwritten with a new one. With `ActiveLink`, `output_dir` is treated as a base folder and numbered subfolders are created inside. A new subfolder is created every time a simulation is run, with `output_dir/output_active` pointing to the most recent results. Check out ClimaUtilities.OutputPathGenerator for more information. [`ActiveLink` (default), `RemovePreexisting`]
device	String	Device type to use [`auto` (default) `CPUSingleThreaded`, `CPUMultiThreaded`, `CUDADevice`]
reference_job_id	Nothing	Identifier of job to use as the "reference" solution in the quicklook plot; the current job's results get compared to the results of the quicklook job on the main branch
vert_diff	Bool	Vertical diffusion [`false` (default), `VerticalDiffusion`, `true` (defaults to `VerticalDiffusion`), `FriersonDiffusion`, `DecayWithHeightDiffusion`]
hyperdiff	String	Hyperdiffusion [`ClimaHyperdiffusion` (or `true`; default), `none` (or `false`)]
smagorinsky_lilly	Bool	Smagorinsky-Lilly diffusive closure [`false` (default), `true`]
bubble	Bool	Enable bubble correction for more accurate surface areas
start_date	String	Start date of the simulation
forcing	Nothing	Forcing [`nothing` (default), `held_suarez`]
test_dycore_consistency	Bool	Test dycore consistency [`false` (default), `true`]
dt_save_state_to_disk	String	Time between saving the state to disk. Examples: [`10secs`, `1hours`, `1months`, `Inf` (do not save)]
dt_save_to_sol	String	Time between saving solution. Examples: [`10days`, `1hours`, `Inf` (do not save)]
moist	String	Moisture model [`dry` (default), `equil`, `nonequil`]
divergence_damping_factor	Float64	Divergence damping factor
rayleigh_sponge	Bool	Rayleigh sponge [`true`, `false` (default)]
surface_setup	String	Surface flux scheme [`DefaultExchangeCoefficients` (default), `DefaultMoninObukhov`]
surface_temperature	String	Prescribed surface temperature functional form ['ZonallySymmetric' (default), 'ZonallyAsymmetric', 'RCEMIPII']
initial_condition	String	Initial condition [`DryBaroclinicWave`, `MoistBaroclinicWave`, `DecayingProfile`, `IsothermalProfile`, `Bomex`, `DryDensityCurrentProfile`, `AgnesiHProfile`, `ScharProfile`, `RisingThermalBubbleProfile`, `ISDAC`], or a file path for a NetCDF file (read documentation about requirements).
perturb_initstate	Bool	Add a perturbation to the initial condition [`false`, `true` (default)]
discrete_hydrostatic_balance	Bool	Set the initial state to discrete hydrostatic balance
apply_limiter	Bool	Apply a horizontal limiter to every tracer [`false` (default), `true`]
precip_model	Nothing	Precipitation model [`nothing` (default), `0M`]
cloud_model	String	Cloud model [`grid_scale`, `quadrature` (default), `quadrature_sgs`]
perf_summary	Bool	Flag for collecting performance summary information
viscous_sponge	Bool	Viscous sponge [`true`, `false` (default)]
tracer_upwinding	String	Tracer upwinding mode [`none` (default), `first_order` , `third_order`, `boris_book`, `zalesak`, `vanleer_limiter`]
energy_upwinding	String	Energy upwinding mode [`none` (default), `first_order` , `third_order`, `boris_book`, `zalesak`, `vanleer_limiter`]
orographic_gravity_wave	Nothing	Orographic drag on horizontal mean flow [`nothing` (default), `gfdl_restart`, `raw_topo`]
non_orographic_gravity_wave	Bool	Apply parameterization for convective gravity wave forcing on horizontal mean flow [`false` (default), `true`]
nh_poly	Int64	Horizontal polynomial degree. Note: The number of quadrature points in 1D within each horizontal element is then Nq = <–nh_poly> + 1
reproducibility_test	Bool	(Bool) perform reproducibility test
check_conservation	Bool	Check conservation of mass and energy [`false` (default), `true`]
ls_adv	Nothing	Large-scale advection [`nothing` (default), `Bomex`, `LifeCycleTan2018`, `Rico`, `ARM_SGP`, `GATE_III`]
external_forcing	Nothing	External forcing for single column experiments [`nothing` (default), `GCM`]
external_forcing_file	Nothing	External forcing file containing large-scale forcings, initial conditions, and boundary conditions [`nothing` (default), `path/to/file`]
cfsite_number	String	cfsite identifier for single column forcing from `external_forcing_file`, specified as siteN. For site details see Shen et al. 2022 `https://doi.org/10.1029/2021MS002631`. [`site23` (default), `siteN`]
subsidence	Nothing	Subsidence [`nothing` (default), `Bomex`, `LifeCycleTan2018`, `Rico`, `DYCOMS`, `ISDAC`]
toml	Vector{Any}	TOML file(s) used to override model parameters
prognostic_tke	Bool	A flag for prognostic TKE [`false` (default), `true`]
prognostic_surface	Bool	Determines if surface temperature is prognostic [`false` (default), , `true`, `PrognosticSurfaceTemperature`, `PrescribedSurfaceTemperature`]
albedo_model	String	Variable surface albedo [`ConstantAlbedo` (default), `RegressionFunctionAlbedo`, `CouplerAlbedo`]
implicit_diffusion	Bool	Whether to treat the vertical diffusion tendency implicitly [`false` (default), `true`]
approximate_linear_solve_iters	Int64	Number of iterations for the approximate linear solve (used when `implicit_diffusion` is true)
override_precip_timescale	Bool	If true, sets τ_precip to dt. Otherwise, τ_precip is set to the value in the toml dictionary
output_default_diagnostics	Bool	Output the default diagnostics associated to the selected atmospheric model
enable_diagnostics	Bool	Set to false to fully disable the diagnostics
netcdf_output_at_levels	Bool	Do not perform any vertical interpolation in the output NetCDF files. Instead, interpolate horizontally and output the level.
netcdf_interpolation_num_points	Nothing	Override the number of interpolation point for the NetCDF output. This configuration has to be a list of integers, e.g. [180, 90, 10].
check_nan_every	Int64	Check if the state contains NaNs every this number of iterations
log_progress	Bool	Log simulation progress, including wall-time estimates
deep_atmosphere	Bool	If true, use deep atmosphere equations and metric terms, otherwise assume columns are cylindrical (shallow atmosphere) [`true`, `false` (default)]
restart_file	Nothing	Path to HDF5 file to use as simulation starting point
prescribe_ozone	Bool	Prescribe time and spatially varying ozone from a file [`false` (default), `true`]
detect_restart_file	Bool	When true, try finding a restart file and use it to restart the simulation. Only works with ActiveLink.
prescribed_aerosols	Vector{Any}	Which aerosols to add. List of keys from the data file (e.g., CB1, CB2).
call_cloud_diagnostics_per_stage	Bool	A temporary Bool for calling cloud diagnostics every stage
turbconv	Nothing	Turbulence convection scheme [`nothing` (default), 'prognostic_edmfx', 'diagnostic_edmfx']
advection_test	Bool	Switches off all grid-scale and subgrid-scale momentum tendencies [`false` (default), `true`]
zero_tendency	Nothing	Turns off tendencies [`nothing` (default), `grid_scale`, `subgrid_scale`]
implicit_sgs_advection	Bool	Whether to treat the subgrid-scale vertical advection tendency implicitly [`false` (default), `true`]
edmf_coriolis	Nothing	EDMF coriolis [`nothing` (default), `Bomex`,`LifeCycleTan2018`,`Rico`,`ARM_SGP`,`DYCOMS_RF01`,`DYCOMS_RF02`,`GABLS`]
edmfx_filter	Bool	If set to true, it switches on the relaxation of negative velocity in EDMFX. [`true`, `false` (default)]
edmfx_nh_pressure	Bool	If set to true, it switches on EDMFX pressure drag closure. [`true`, `false` (default)]
edmfx_entr_model	Nothing	EDMFX entrainment closure. [`nothing` (default), `PiGroups`, `Generalized`, `GeneralizedHarmonics`]
edmfx_detr_model	Nothing	EDMFX detrainment closure. [`nothing` (default), `PiGroups`, `Generalized`, `GeneralizedHarmonics`]
edmfx_upwinding	String	EDMFX upwinding mode [`none` (default), `first_order`, `third_order`]
edmfx_sgsflux_upwinding	String	EDMFX SGS mass flux upwinding mode [`none` (default), `first_order`, `third_order`]
edmfx_sgs_mass_flux	Bool	If set to true, it switches on EDMFX SGS mass flux. [`true`, `false` (default)]
edmfx_sgs_diffusive_flux	Bool	If set to true, it switches on EDMFX SGS diffusive flux. [`true`, `false` (default)]
updraft_number	Int64	Sets the number of updrafts for the EDMF scheme
radiation_reset_rng_seed	Bool	Reset the RNG seed before calling RRTGMP to a known value (the timestep number). When modeling cloud optics, RRTGMP uses a random number generator. Resetting the seed every time RRTGMP is called to a deterministic value ensures that the simulation is fully reproducible and can be restarted in a reproducible way. Disable this option when running production runs. Please note that this flag is only used for `AllSkyRadiation` and `AllSkyRadiationWithClearSkyDiagnostics` radiation modes.