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 Bool
s.
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`] |
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 |
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. |