The TOML Parameter File Interface

Parameters for CliMA models are defined in .toml files. ClimaParams.jl works with two sources of parameters, which are merged:

1. A default parameter file: bundled with ClimaParams.jl, containing the values for the entire CliMA ecosystem. See the Parameter List.
2. A user-defined override file: provided for a specific experiment. It only needs to contain the parameters that deviate from the defaults.

Parameter Format

Each parameter is defined by its unique name as a TOML table header (e.g., [my_parameter_name]). It can have the following attributes:

ClimaParams.jl itself reads only value, type, tag, and the bookkeeping field used_in. The remaining attributes are carried through untouched for EnsembleKalmanProcesses.jl to read from the same file.

Basic Parameter Definition

At a minimum, a parameter requires a value and a type.

[molar_mass_dry_air]
value = 0.02897
type = "float"

Include a description with units and, for anything that is not a defined constant, the source it was taken from. CliMA uses SI units.

[molar_mass_dry_air]
value = 0.02897
type = "float"
description = "Molar mass of dry air (kg mol⁻¹)."

See Adding and Changing Parameters for the full conventions on names, descriptions, and units.

Parameter tags

Tags group related parameters so that a whole group can be retrieved in one call. They do not create namespaces, and all parameter names must remain globally unique. To add tags, provide a list of strings to the tag field.

A recommended convention is to tag parameters with the model component(s) where they are used.

[prandtl_number_0_grachev]
value = 0.98
type = "float"
description = "The turbulent Prandtl number in neutral conditions ($Pr_0$) for the Grachev universal functions (unitless). Source: Grachev et al. (2007), DOI: 10.1007/s10546-007-9177-6."
tag = ["SurfaceFluxes"]

Parameters with a specific tag can then be retrieved in Julia. Tag matching is case-insensitive and ignores punctuation. For more information, see the API for fuzzy_match.

# Retrieves every parameter tagged with "SurfaceFluxes"
sf_params = get_tagged_parameter_values(toml_dict, "surfacefluxes")

Override Files

When an override file is provided, its values for any given parameter take precedence over the default values. Other attributes from the default file (like description or tag) are merged if they are not present in the override file.

Override mechanism

For example, if the user's override file contains:

[molar_mass_dry_air]
value = 0.03
type = "float"

The final, merged parameter used in the simulation will be:

[molar_mass_dry_air]
value = 0.03  # <-- Overwritten by the user's value
type = "float"
description = "Molar mass of dry air (kg mol⁻¹)." # <-- Merged from the default file

An override file may also introduce parameters that are absent from the default file, which is how a downstream package adds parameters that are specific to it.

Interacting with Parameters in Julia

1. Loading parameters

The main entry point is create_toml_dict, which loads, merges, and types the parameters.

create_toml_dict(FT; override_file = nothing, default_file = ...)

The first argument, FT, must be a float type (e.g., Float64 or Float32) and determines the precision of all floating-point parameters.

A typical use case involves providing the path to a local override file:

import ClimaParams

FT = Float64
local_experiment_file = joinpath(@__DIR__, "local_exp_parameters.toml")
toml_dict = ClimaParams.create_toml_dict(FT; override_file = local_experiment_file)

If override_file is omitted, only the default parameters are loaded. A Julia Dict can be passed instead of a file path.

To combine more than two files, pass the paths as additional positional arguments; they are merged in the order given, and the merged result then overrides the defaults.

toml_dict = ClimaParams.create_toml_dict(FT, "site.toml", "local_exp_parameters.toml")

Alternatively, merge the files yourself with merge_toml_files and pass the resulting Dict as override_file.

2. Using and logging parameters

The returned toml_dict is then used to construct parameter structs for different model components.

# Retrieve values and construct the component-specific parameter struct
thermo_params = Thermodynamics.ThermodynamicsParameters(toml_dict)

# ... build the rest of the model components ...

# After all components are built, log the used parameters before running
log_file = joinpath(@__DIR__, "parameter_log.toml")
ClimaParams.log_parameter_information(toml_dict, log_file)

# ... run_model(...) ...

The function log_parameter_information performs two tasks:

1. Writes a log file: it saves a complete record of every parameter actually used in the simulation to log_file.
2. Performs sanity checks: it verifies that all parameters in your override file were used.

The log file includes a used_in field, which lists every component that requested the parameter. Continuing the example, the log file would contain:

[molar_mass_dry_air]
value = 0.03
type = "float"
description = "Molar mass of dry air (kg mol⁻¹)."
used_in = ["Thermodynamics"]