Merge pull request #1613 from CliMA/js/input

add Input module

Author: juliasloan25

Project.toml

@@ -4,6 +4,8 @@ authors = ["CliMA Contributors <[email protected]>"]
 version = "0.1.2"
 
 [deps]
+ArgParse = "c7e460c6-2fb9-53a9-8c5b-16f535851c63"
+ClimaAtmos = "b2c96348-7fb7-4fe0-8da9-78d88439e717"
 ClimaComms = "3a4d1b5c-c61d-41fd-a00a-5873ba7a1b0d"
 ClimaCore = "d414da3d-4745-48bb-8d80-42e94e092884"
 ClimaUtilities = "b3f4f4ca-9299-4f7f-bd9b-81e1242a7513"
@@ -14,8 +16,11 @@ SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 SurfaceFluxes = "49b00bb7-8bd4-4f2b-b78c-51cd0450215f"
 Thermodynamics = "b60c26fb-14c3-4610-9d3e-2d17fe7ff00c"
+YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
 
 [compat]
+ArgParse = "1"
+ClimaAtmos = "0.27, 0.28, 0.29, 0.30, 0.31"
 ClimaComms = "0.6.2"
 ClimaCore = "0.14.25"
 ClimaUtilities = "0.1.22"
@@ -26,4 +31,5 @@ SciMLBase = "~2.110, ~2.111, ~2.112"
 StaticArrays = "1.9.8"
 SurfaceFluxes = "0.12.3, 0.13, 0.14"
 Thermodynamics = "0.14.1, 0.15"
+YAML = "0.4"
 julia = "1.10"

docs/make.jl

@@ -63,6 +63,7 @@ experiment_pages = [
     ),
 ]
 interface_pages = [
+    "input.md",
     "checkpointer.md",
     "conservation.md",
     "fieldexchanger.md",

docs/src/input.md

@@ -0,0 +1,190 @@
+# Input
+
+The `Input` module provides functions for parsing command-line arguments and loading
+configuration files for ClimaCoupler simulations.
+
+## Providing Configuration Options
+
+ClimaCoupler simulations have a variety of configuration options, which are
+described in the section [Available Configuration Options](#available-configuration-options) below.
+
+Users can configure a coupled simulation through 2 main entry points:
+command-line arguments and configuration files. Each method, and the
+priority between them, is explained here.
+
+Note that all of these configuration are optional; a default AMIP simulation
+can be set up with the 0-argument constructor `CoupledSimulation()`.
+
+### Configuration Files
+
+Configuration files are YAML files that specify simulation parameters. They can be
+used to specify a valid setting for any configuration option.
+
+Note that since the atmosphere model has many configuration options on its own,
+we also support providing an atmosphere-specific configuration file. As a result,
+multiple configuration files can be used together:
+
+- **Coupler config file** (`--config_file`): Main configuration file for the coupled simulation
+- **Atmos config file** (`--atmos_config_file`): Optional ClimaAtmos-specific configuration
+- **TOML parameter files** (`--coupler_toml`): One or more TOML files containing model parameters
+
+When multiple config files are specified, values in the coupler config file will take
+precedence over those in the atmosphere config file. This is explained in more detail
+in the [Precendence of Config Files and CLI Arguments](#precendence-of-config-files-and-cli-arguments)
+section below.
+
+### Parameter TOML Files
+
+Analogous to configuration files, which specify simulation options such as component models or
+parameterizations to use, ClimaCoupler also accepts optional TOML files of parameter values.
+
+If a TOML file is provided, the default parameter values will be overwritten by the values
+specified in the TOML. If no TOML file is provided, default parameter values will be used.
+
+Since ClimaCoupler accepts coupler config files _and_ atmosphere config files, we may encounter
+a case where a TOML file is specified in both config files. In this case, the coupler TOML
+file takes highest priority; only if there is no coupler TOML will the atmosphere-specific
+TOML be used.
+
+### Command-Line Input (CLI) Arguments
+
+Command-line arguments can be provided when running a simulation:
+
+```bash
+julia run_amip.jl --config_file="path/to/config.yml" --job_id="amip_default"
+```
+
+Typically, we rely mostly on configuration files, and provide only the `config_file`
+and `job_id` via CLI arguments, though if desired any input can be specified in the command line.
+All available options and their defaults can be viewed by running with `--help`.
+
+### Precendence of Config Files and CLI Arguments
+
+Users have the ability to specify arguments via both CLI arguments and configuration
+files for any given simulation. If this is done, the options are merged
+with the following precedence (from lowest to highest priority):
+
+1. **ClimaAtmos defaults** - Default values from the ClimaAtmos package
+2. **ClimaCoupler defaults** - Default values defined in [`argparse_settings()`](@ref)
+3. **Command-line arguments** - Arguments passed via the command line
+4. **ClimaAtmos configuration file** - YAML file specified via `--atmos_config_file` or in the coupler config file
+5. **ClimaCoupler configuration file** - YAML file specified via `--config_file` (default: `config/ci_configs/amip_default.yml`)
+
+## Available Configuration Options
+
+The following table lists all available command-line arguments organized by category:
+
+#### Simulation-identifying information
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--config_file` | String | `config/ci_configs/amip_default.yml` | Any valid file path | YAML file used to set the configuration of the coupled model |
+| `--job_id` | String | `nothing` | Any string | A unique identifier for this run, defaults to the config file name |
+| `--print_config_dict` | Bool | `true` | `true`, `false` | Whether to print the final configuration dictionary |
+| `--mode_name` | String | `"amip"` | `cmip`, `amip`, `subseasonal`, `slabplanet`, `slabplanet_aqua`, `slabplanet_terra` | Mode of coupled simulation |
+| `--coupler_toml` | Vector{String} | `[]` | Any list of valid TOML file paths | Optional list of paths to TOML files used to overwrite default model parameters |
+
+#### Computational simulation setup
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--unique_seed` | Bool | `false` | `true`, `false` | Whether to set the random number seed to a unique value |
+| `--FLOAT_TYPE` | String | `"Float64"` | `Float64`, `Float32` | Floating point precision |
+| `--device` | String | `"auto"` | `auto`, `CPUSingleThreaded`, `CPUMultiThreaded`, `CUDADevice` | Device type to control running on CPU or GPU |
+
+#### Time information
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--use_itime` | Bool | `true` | `true`, `false` | Whether to use ClimaUtilities ITime (integer time) or Float64 |
+| `--t_end` | String | `"800secs"` | `"Nsecs"`, `"Nmins"`, `"Nhours"`, `"Ndays"`, `"Inf"` | End time of the simulation, relative to the start date |
+| `--t_start` | String | `"0secs"` | `"Nsecs"`, `"Nmins"`, `"Nhours"`, `"Ndays"`, `"Inf"` | Start time of the simulation, relative to the start date |
+| `--start_date` | String | `"20000101"` | `"YYYYMMDD"` format | Start date of the simulation |
+| `--dt_cpl` | String | `"400secs"` | `"Nsecs"`, `"Nmins"`, `"Nhours"`, `"Ndays"`, `"Inf"` | Coupling time step |
+| `--dt` | String | `"400secs"` | `"Nsecs"`, `"Nmins"`, `"Nhours"`, `"Ndays"`, `"Inf"` | Component model time step (used if individual component dt's not specified) |
+| `--dt_atmos` | String | `nothing` | `"Nsecs"`, `"Nmins"`, `"Nhours"`, `"Ndays"`, `"Inf"` | Atmos simulation time step (alternative to `dt`) |
+| `--dt_land` | String | `nothing` | `"Nsecs"`, `"Nmins"`, `"Nhours"`, `"Ndays"`, `"Inf"` | Land simulation time step (alternative to `dt`) |
+| `--dt_ocean` | String | `nothing` | `"Nsecs"`, `"Nmins"`, `"Nhours"`, `"Ndays"`, `"Inf"` | Ocean simulation time step (alternative to `dt`) |
+| `--dt_seaice` | String | `nothing` | `"Nsecs"`, `"Nmins"`, `"Nhours"`, `"Ndays"`, `"Inf"` | Sea ice simulation time step (alternative to `dt`) |
+| `--checkpoint_dt` | String | `"90days"` | `"Nsecs"`, `"Nmins"`, `"Nhours"`, `"Ndays"`, `"Inf"` | Time interval for checkpointing |
+
+Note: If any component model-specific timestep is specified, _all_ component-model
+specific timesteps should be specified, rather than only `dt`.
+
+#### Space information
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--h_elem` | Int | `16` | Any positive integer | Number of horizontal elements to use for the boundary space |
+| `--share_surface_space` | Bool | `true` | `true`, `false` | Whether to share the surface space between surface models, atmosphere, and boundary |
+
+#### Restart information
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--detect_restart_files` | Bool | `false` | `true`, `false` | Whether to automatically use restart files if available |
+| `--restart_dir` | String | `nothing` | Any valid directory path | Directory containing restart files |
+| `--restart_t` | Int | `nothing` | Any integer (seconds) | Time in seconds rounded to nearest index to use at `t_start` for restarted simulation |
+| `--restart_cache` | Bool | `true` | `true`, `false` | Whether to read the cache from the restart file if available |
+| `--save_cache` | Bool | `true` | `true`, `false` | Whether to save the state and cache or only the state when checkpointing |
+
+#### Diagnostics and output
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--use_coupler_diagnostics` | Bool | `true` | `true`, `false` | Whether to compute and output coupler diagnostics |
+| `--coupler_output_dir` | String | `"experiments/ClimaEarth/output"` | Any valid directory path | Directory to save output files |
+
+
+
+#### Conservation and RMSE checks
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--energy_check` | Bool | `false` | `true`, `false` | Whether to check energy conservation |
+| `--conservation_softfail` | Bool | `false` | `true`, `false` | Whether to soft fail on conservation errors |
+| `--rmse_check` | Bool | `false` | `true`, `false` | Whether to check RMSE of some physical fields |
+
+#### ClimaAtmos specific
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--surface_setup` | String | `"PrescribedSurface"` | `PrescribedSurface`, `DefaultMoninObukhov` | Triggers ClimaAtmos into coupled mode |
+| `--atmos_config_file` | String | `nothing` | Any valid file path | Optional YAML file used to overwrite default model parameters |
+| `--atmos_log_progress` | Bool | `false` | `true`, `false` | Use ClimaAtmos walltime logging callback instead of default ClimaCoupler one |
+| `--albedo_model` | String | `"CouplerAlbedo"` | `ConstantAlbedo`, `RegressionFunctionAlbedo`, `CouplerAlbedo` | Type of albedo model |
+| `--extra_atmos_diagnostics` | Vector{Dict{Any, Any}} | `[]` | List of dictionaries | List of dictionaries containing information about additional atmosphere diagnostics to output |
+
+#### ClimaLand specific
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--land_model` | String | `"bucket"` | `bucket`, `integrated` | Land model to use |
+| `--land_temperature_anomaly` | String | `"aquaplanet"` | `amip`, `aquaplanet`, `nothing` | Type of temperature anomaly for land model |
+| `--use_land_diagnostics` | Bool | `true` | `true`, `false` | Whether to compute and output land model diagnostics |
+| `--land_spun_up_ic` | Bool | `true` | `true`, `false` | Whether to use integrated land initial conditions from spun up state |
+| `--bucket_albedo_type` | String | `"map_static"` | `map_static`, `function`, `map_temporal` | Access bucket surface albedo information from data file |
+| `--bucket_initial_condition` | String | `""` | Any valid file path | File path for a NetCDF file (read documentation about requirements) |
+| `--era5_initial_condition_dir` | String | `nothing` | Any valid directory path | Directory containing ERA5 initial condition files (subseasonal mode). Filenames inferred from `start_date`. Generated with `https://github.com/CliMA/WeatherQuest` |
+
+#### Ice model specific
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--ice_model` | String | `"prescribed"` | `prescribed`, `clima_seaice` | Sea ice model to use |
+
+
+#### Ocean model specific
+
+| Argument | Type | Default | Valid Options | Description |
+|----------|------|---------|---------------|-------------|
+| `--evolving_ocean` | Bool | `true` | `true`, `false` | Whether to use a dynamic slab ocean model, as opposed to constant surface temperatures |
+
+## Input API
+
+```@docs
+ClimaCoupler.Input.argparse_settings
+ClimaCoupler.Input.parse_commandline
+ClimaCoupler.Input.get_coupler_config_dict
+ClimaCoupler.Input.get_coupler_args
+```

experiments/ClimaEarth/Manifest-v1.11.toml

@@ -1,8 +1,8 @@
 # This file is machine-generated - editing it directly is not advised
 
-julia_version = "1.11.5"
+julia_version = "1.11.6"
 manifest_format = "2.0"
-project_hash = "f84997fb003cca7320c93d5448b91701d73e02c0"
+project_hash = "d502ec36505df261b2f120a7277a749ea8bcd37a"
 
 [[deps.ADTypes]]
 git-tree-sha1 = "8b2b045b22740e4be20654175cc38291d48539db"
@@ -465,7 +465,7 @@ uuid = "908f55d8-4145-4867-9c14-5dad1a479e4d"
 version = "0.4.6"
 
 [[deps.ClimaCoupler]]
-deps = ["ClimaComms", "ClimaCore", "ClimaUtilities", "Dates", "JLD2", "Logging", "SciMLBase", "StaticArrays", "SurfaceFluxes", "Thermodynamics"]
+deps = ["ArgParse", "ClimaAtmos", "ClimaComms", "ClimaCore", "ClimaUtilities", "Dates", "JLD2", "Logging", "SciMLBase", "StaticArrays", "SurfaceFluxes", "Thermodynamics", "YAML"]
 path = "../.."
 uuid = "4ade58fe-a8da-486c-bd89-46df092ec0c7"
 version = "0.1.2"