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/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.ncTo 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
include("config_table.jl");Default configuration
┌──────────────────────────────────────┬─────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Argument │ Type │ Description │
├──────────────────────────────────────┼─────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ dz_bottom │ Float64 │ Model bottom grid depth. Default: 500m │
│ dz_top │ Float64 │ Model top grid depth. Default: 5000m │
│ 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`,`Earth`,`DCMIP200`,`Agnesi`] │
│ 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 │
│ smoothing_order │ Int64 │ Define the surface smoothing kernel factor (integer) [`3 (default)`] │
│ 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`] │
│ 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`] │
│ hyperdiff │ String │ Hyperdiffusion [`ClimaHyperdiffusion` (or `true`; default), `none` (or `false`)] │
│ 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`, `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`] │
│ 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`] │
│ energy_upwinding │ String │ Energy upwinding mode [`none` (default), `first_order` , `third_order`, `boris_book`, `zalesak`] │
│ 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 │
│ regression_test │ Bool │ (Bool) perform regression 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 │ 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`] │
│ 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 │
└──────────────────────────────────────┴─────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘