diff --git a/.gitignore b/.gitignore index f7ba7f5fd59..4cf65a220c6 100644 --- a/.gitignore +++ b/.gitignore @@ -19,8 +19,10 @@ deps/usr/ deps/src/ # Build artifacts for creating documentation generated by the Documenter package +# and running docs/make.jl docs/build/ docs/site/ +docs/src/config.md # File generated by Pkg, the package manager, based on a corresponding Project.toml # It records a fixed state of all packages used by the project. As such, it should not be diff --git a/docs/src/config.md b/docs/src/config.md deleted file mode 100644 index 18892e95740..00000000000 --- a/docs/src/config.md +++ /dev/null @@ -1,181 +0,0 @@ - -# 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/driver.jl --config_file ` - -### 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](https://github.com/CliMA/ClimaArtifacts). - -To add a new configuration argument/key, open `.buildkite/default_config.yml`. -Add an entry with the following format: -``` -: - value: - help: -``` -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\`,\`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\`, \`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 | 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. |