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

ArgumentTypeDescription
dz_bottomFloat64Model bottom grid depth. Default: 500m
z_stretchBoolStretch grid in z-direction. [`true` (default), `false`]
h_elemInt64number of elements per edge on a cubed sphere
x_elemInt64number of horizontal elements in the x-direction
x_maxFloat64Model domain size, x direction. Default: 300km
y_elemInt64number of horizontal elements in the y-direction
y_maxFloat64Model domain size, y direction. Default: 300km
z_elemInt64number of vertical elements
z_maxFloat64Model top height. Default: 30km
vorticity_hyperdiffusion_coefficientFloat64Hyperdiffusion coefficient for vorticity (m s-1)
scalar_hyperdiffusion_coefficientFloat64Hyperdiffusion coefficient for scalar (m s-1)
topographyStringDefine the surface elevation profile [`NoWarp` (default),`Earth`,`DCMIP200`,`Agnesi`, `Schar`, `Hughes2023`]
mesh_warp_typeStringSets the interior mesh warp method [`Linear`, `SLEVE`]
sleve_etaFloat64If SLEVE coordinates are chosen, sets the `ηₕ` parameter (if z/z_top > ηₕ, no warping is applied)
sleve_sFloat64If SLEVE coordinates are chosen, sets `s`, the warping decay scale parameter
topo_smoothingBoolChoose whether to order-2 smoothing on the LGL mesh
topography_damping_factorInt64Factor by which smallest resolved length-scale is to be damped
use_newton_rtolBoolWhether 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_rtolFloat64Relative tolerance of Newton's method (only for ClimaTimeSteppers.jl; only used when `use_newton_rtol` is `true`)
surface_thermo_state_typeStringSurface thermo state type [`GCMSurfaceThermoState` (default), `PrescribedThermoState`]
split_odeBoolUse split of ODE problem. Examples: [`true` (implicit, default), `false` (explicit)]
use_krylov_methodBoolWhether to use a Krylov method to solve the linear system in Newton's method (only for ClimaTimeSteppers.jl)
use_dynamic_krylov_rtolBoolWhether to use Eisenstat-Walker forcing instead of a constant relative tolerance in the Krylov method (only for ClimaTimeSteppers.jl)
max_newton_iters_odeInt64Maximum number of Newton's method iterations (only for ODE algorithms that use Newton's method)
ode_algoStringODE algorithm [`ARS343` (default), `SSP333`, `IMKG343a`, etc.]
krylov_rtolFloat64Relative tolerance of the Krylov method (only for ClimaTimeSteppers.jl; only used if `use_krylov_method` is `true`)
eisenstat_walker_forcing_alphaFloat64Value 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_adjustmentFloat64Amount 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`)
radNothingRadiation model [`nothing` (default), `gray`, `clearsky`, `allsky`, `allskywithclear`]
idealized_h2oBoolUse idealized H2O in radiation model [`false` (default), `true`]
dt_radStringTime between calling radiation callback for sphere configurations
idealized_cloudsBoolUse idealized clouds in radiation model [`false` (default), `true`]
prescribe_clouds_in_radiationBoolUse 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`]
insolationStringInsolation used in radiation model [`idealized` (default), `timevarying`, `rcemipii`]
add_isothermal_boundary_layerBoolAdd an isothermal boundary layer above the domain top for radiation [`false`, `true` (default)]
aerosol_radiationBoolUse aerosols in radiation [`false` (default)]
dt_cloud_fractionStringTime between calling cloud fraction update
configStringSpatial configuration [`sphere` (default), `column`, `box`, `plane`]
FLOAT_TYPEStringFloat type
dtStringSimulation time step. Examples: [`10secs`, `1hours`]
t_endStringSimulation end time. Examples: [`1200days`, `40secs`]
output_dirNothingOutput directory
output_dir_styleStringWhat 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`]
deviceStringDevice type to use [`auto` (default) `CPUSingleThreaded`, `CPUMultiThreaded`, `CUDADevice`]
reference_job_idNothingIdentifier 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_diffBoolVertical diffusion [`false` (default), `VerticalDiffusion`, `true` (defaults to `VerticalDiffusion`), `FriersonDiffusion`, `DecayWithHeightDiffusion`]
hyperdiffStringHyperdiffusion [`ClimaHyperdiffusion` (or `true`; default), `none` (or `false`)]
smagorinsky_lillyBoolSmagorinsky-Lilly diffusive closure [`false` (default), `true`]
bubbleBoolEnable bubble correction for more accurate surface areas
start_dateStringStart date of the simulation
forcingNothingForcing [`nothing` (default), `held_suarez`]
test_dycore_consistencyBoolTest dycore consistency [`false` (default), `true`]
dt_save_state_to_diskStringTime between saving the state to disk. Examples: [`10secs`, `1hours`, `1months`, `Inf` (do not save)]
dt_save_to_solStringTime between saving solution. Examples: [`10days`, `1hours`, `Inf` (do not save)]
moistStringMoisture model [`dry` (default), `equil`, `nonequil`]
divergence_damping_factorFloat64Divergence damping factor
rayleigh_spongeBoolRayleigh sponge [`true`, `false` (default)]
surface_setupStringSurface flux scheme [`DefaultExchangeCoefficients` (default), `DefaultMoninObukhov`]
surface_temperatureStringPrescribed surface temperature functional form ['ZonallySymmetric' (default), 'ZonallyAsymmetric', 'RCEMIPII']
initial_conditionStringInitial condition [`DryBaroclinicWave`, `MoistBaroclinicWave`, `DecayingProfile`, `IsothermalProfile`, `Bomex`, `DryDensityCurrentProfile`, `AgnesiHProfile`, `ScharProfile`, `RisingThermalBubbleProfile`, `ISDAC`]
perturb_initstateBoolAdd a perturbation to the initial condition [`false`, `true` (default)]
discrete_hydrostatic_balanceBoolSet the initial state to discrete hydrostatic balance
apply_limiterBoolApply a horizontal limiter to every tracer [`false` (default), `true`]
precip_modelNothingPrecipitation model [`nothing` (default), `0M`]
cloud_modelStringCloud model [`grid_scale`, `quadrature` (default), `quadrature_sgs`]
perf_summaryBoolFlag for collecting performance summary information
viscous_spongeBoolViscous sponge [`true`, `false` (default)]
tracer_upwindingStringTracer upwinding mode [`none` (default), `first_order` , `third_order`, `boris_book`, `zalesak`]
energy_upwindingStringEnergy upwinding mode [`none` (default), `first_order` , `third_order`, `boris_book`, `zalesak`]
orographic_gravity_waveNothingOrographic drag on horizontal mean flow [`nothing` (default), `gfdl_restart`, `raw_topo`]
non_orographic_gravity_waveBoolApply parameterization for convective gravity wave forcing on horizontal mean flow [`false` (default), `true`]
nh_polyInt64Horizontal polynomial degree. Note: The number of quadrature points in 1D within each horizontal element is then Nq = <–nh_poly> + 1
reproducibility_testBool(Bool) perform reproducibility test
check_conservationBoolCheck conservation of mass and energy [`false` (default), `true`]
ls_advNothingLarge-scale advection [`nothing` (default), `Bomex`, `LifeCycleTan2018`, `Rico`, `ARM_SGP`, `GATE_III`]
external_forcingNothingExternal forcing for single column experiments [`nothing` (default), `GCM`]
external_forcing_fileNothingExternal forcing file containing large-scale forcings, initial conditions, and boundary conditions [`nothing` (default), `path/to/file`]
cfsite_numberStringcfsite 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`]
subsidenceNothingSubsidence [`nothing` (default), `Bomex`, `LifeCycleTan2018`, `Rico`, `DYCOMS`, `ISDAC`]
tomlVector{Any}TOML file(s) used to override model parameters
prognostic_tkeBoolA flag for prognostic TKE [`false` (default), `true`]
prognostic_surfaceBoolDetermines if surface temperature is prognostic [`false` (default), , `true`, `PrognosticSurfaceTemperature`, `PrescribedSurfaceTemperature`]
albedo_modelStringVariable surface albedo [`ConstantAlbedo` (default), `RegressionFunctionAlbedo`, `CouplerAlbedo`]
implicit_diffusionBoolWhether to treat the vertical diffusion tendency implicitly [`false` (default), `true`]
approximate_linear_solve_itersInt64Number of iterations for the approximate linear solve (used when `implicit_diffusion` is true)
override_precip_timescaleBoolIf true, sets τ_precip to dt. Otherwise, τ_precip is set to the value in the toml dictionary
output_default_diagnosticsBoolOutput the default diagnostics associated to the selected atmospheric model
enable_diagnosticsBoolSet to false to fully disable the diagnostics
netcdf_output_at_levelsBoolDo not perform any vertical interpolation in the output NetCDF files. Instead, interpolate horizontally and output the level.
netcdf_interpolation_num_pointsNothingOverride 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_everyInt64Check if the state contains NaNs every this number of iterations
log_progressBoolLog simulation progress, including wall-time estimates
deep_atmosphereBoolIf true, use deep atmosphere equations and metric terms, otherwise assume columns are cylindrical (shallow atmosphere) [`true`, `false` (default)]
restart_fileNothingPath to HDF5 file to use as simulation starting point
prescribe_ozoneBoolPrescribe time and spatially varying ozone from a file [`false` (default), `true`]
detect_restart_fileBoolWhen true, try finding a restart file and use it to restart the simulation. Only works with ActiveLink.
prescribed_aerosolsVector{Any}Which aerosols to add. List of keys from the data file (e.g., CB1, CB2).
call_cloud_diagnostics_per_stageBoolA temporary Bool for calling cloud diagnostics every stage
turbconvNothingTurbulence convection scheme [`nothing` (default), 'prognostic_edmfx', 'diagnostic_edmfx']
advection_testBoolSwitches off all grid-scale and subgrid-scale momentum tendencies [`false` (default), `true`]
zero_tendencyNothingTurns off tendencies [`nothing` (default), `grid_scale`, `subgrid_scale`]
implicit_sgs_advectionBoolWhether to treat the subgrid-scale vertical advection tendency implicitly [`false` (default), `true`]
edmf_coriolisNothingEDMF coriolis [`nothing` (default), `Bomex`,`LifeCycleTan2018`,`Rico`,`ARM_SGP`,`DYCOMS_RF01`,`DYCOMS_RF02`,`GABLS`]
edmfx_filterBoolIf set to true, it switches on the relaxation of negative velocity in EDMFX. [`true`, `false` (default)]
edmfx_nh_pressureBoolIf set to true, it switches on EDMFX pressure drag closure. [`true`, `false` (default)]
edmfx_entr_modelNothingEDMFX entrainment closure. [`nothing` (default), `PiGroups`, `Generalized`, `GeneralizedHarmonics`]
edmfx_detr_modelNothingEDMFX detrainment closure. [`nothing` (default), `PiGroups`, `Generalized`, `GeneralizedHarmonics`]
edmfx_upwindingStringEDMFX upwinding mode [`none` (default), `first_order`, `third_order`]
edmfx_sgsflux_upwindingStringEDMFX SGS mass flux upwinding mode [`none` (default), `first_order`, `third_order`]
edmfx_sgs_mass_fluxBoolIf set to true, it switches on EDMFX SGS mass flux. [`true`, `false` (default)]
edmfx_sgs_diffusive_fluxBoolIf set to true, it switches on EDMFX SGS diffusive flux. [`true`, `false` (default)]
updraft_numberInt64Sets the number of updrafts for the EDMF scheme
radiation_reset_rng_seedBoolReset 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.