API

ClimaParams

Centralized parameter management for the CliMA ecosystem.

ClimaParams reads physical constants and tunable model parameters from TOML files and returns them as typed Julia values. A default file bundled with the package (src/parameters.toml) holds the ecosystem-wide values; experiments layer override files on top of it.

The entry point is create_toml_dict, which returns a ParamDict. Values are read out with get_parameter_values or by indexing. Every read is recorded, so log_parameter_information can write a reproducible record of the parameters a simulation used.

Examples

import ClimaParams as CP

toml_dict = CP.create_toml_dict(Float64)
params = CP.get_parameter_values(toml_dict, ["gravitational_acceleration"])
params.gravitational_acceleration

ParamDict{FT}

A parameter dictionary holding the effective set of parameters read from TOML files: the defaults merged with any overrides.

FT is the floating-point type that "float" parameters are converted to. The dictionary also tracks which override parameters have been read, which log_parameter_information uses to catch typos in override files.

Construct one with create_toml_dict rather than calling the inner constructor directly.

Fields

• data::Dict: The main dictionary holding the complete, merged set of parameter values and their metadata.
• override_dict::Union{Nothing, Dict}: A dictionary containing only the parameters from an override file, used for tracking purposes. Is nothing if no override file was provided.

float_type(pd::ParamDict)

Return the float type FT with which the parameter dictionary pd was initialized.

Downstream constructors should derive FT from this function rather than hard-coding a float type.

Examples

toml_dict = CP.create_toml_dict(Float32)
CP.float_type(toml_dict)  # Float32

create_toml_dict(
    FT;
    override_file::Union{String, Dict, Nothing}=nothing,
    default_file::Union{String, Dict}="parameters.toml",
)

Create a ParamDict{FT} by reading and merging default and override parameter sources.

This is the main entry point for constructing a parameter dictionary. It reads default_file and, optionally, override_file, with parameters from the override file taking precedence. Either source may be a file path or an already-parsed Julia Dict.

Arguments

• FT: The floating-point type used for all "float" parameters.

Keyword Arguments

• override_file = nothing: Path to a TOML file, or a Dict, of override parameters.
• default_file: Path to the default TOML file, or a Dict, of default parameters. Defaults to the parameters.toml file bundled with the package.

Returns

A ParamDict{FT} containing the merged and typed parameters.

Examples

toml_dict = CP.create_toml_dict(Float64)

toml_dict = CP.create_toml_dict(
    Float32;
    override_file = joinpath(@__DIR__, "my_experiment.toml"),
)

create_toml_dict(
    ::Type{FT},
    override_files::String...;
    default_file::Union{String, Dict} = joinpath(@__DIR__, "parameters.toml"),
)

Create a ParamDict{FT} from the default file and any number of override files, given as positional arguments.

The override files are merged in the order given, so a parameter set in more than one file takes its value from the last file that defines it; each such duplicate raises a warning. The merged result then overrides default_file.

Arguments

• FT: The floating-point type used for all "float" parameters.
• override_files: Paths to TOML files. Each path must end in .toml. Unlike the single-file method, this method does not accept Dicts; merge them yourself and pass the result as override_file.

Keyword Arguments

• default_file: Path to the default TOML file, or a Dict, of default parameters. Defaults to the parameters.toml file bundled with the package.

Returns

A ParamDict{FT} containing the merged and typed parameters.

Examples

toml_dict = CP.create_toml_dict(Float64, "site_parameters.toml", "experiment.toml")

See also merge_toml_files.

merge_toml_files(filepaths; override::Bool=false)

Parse and merge multiple TOML files into a single dictionary.

Arguments

• filepaths: An iterable of strings, where each string is a path to a TOML file.
• override::Bool: If false (the default), an error is thrown for duplicate parameter entries across files. If true, a warning is issued and later files in the filepaths list will overwrite earlier entries.

Returns

• Dict{String, Any}: A dictionary containing the merged data from all TOML files.

merge_override_default_values(override_toml_dict, default_toml_dict)

Merge two ParamDict objects, with entries from override_toml_dict taking precedence over those in default_toml_dict.

Merging is per-attribute: an override that sets only value keeps the description and any other metadata from the default entry.

Called from create_toml_dict.

get_parameter_values(pd, name, [component])
get_parameter_values(pd, names, [component])
get_parameter_values(pd, name_map, [component])
get_parameter_values(pd, name_map...; component = nothing)

Retrieve parameter values from pd as a NamedTuple, converted to the types declared in the TOML file.

Parameters can be requested either by name, in which case the TOML names become the NamedTuple keys, or through a name_map, which renames them to shorter local names.

If component is given, the parameters are also logged as used by that component, so they appear with a used_in entry in the file written by write_log_file.

Arguments

• name::AbstractString: A single parameter name.
• names: A Vector or Tuple of parameter names.
• name_map: A Dict, NamedTuple, or iterable of Pairs mapping the TOML parameter name to the desired local name, e.g. "gravitational_acceleration" => "g". Keys and values may be Strings or Symbols.
• component: The name of the model component reading these parameters. In the varargs method it is a keyword argument; in all others it is the third positional argument.

Returns

A NamedTuple keyed by the parameter names, or by the local names when a name_map is used.

Examples

# Retrieve by name
params = CP.get_parameter_values(
    toml_dict,
    ["gravitational_acceleration", "planet_radius"],
)
params.gravitational_acceleration  # 9.81

# Retrieve, rename, and log the use
params = CP.get_parameter_values(
    toml_dict,
    Dict("gravitational_acceleration" => "g"),
    "Thermodynamics",
)
params.g  # 9.81

# Varargs form; `component` is a keyword argument here
params = CP.get_parameter_values(
    toml_dict,
    :gravitational_acceleration => :g,
    :planet_radius => :R_p;
    component = "Thermodynamics",
)

See also get_tagged_parameter_values and create_parameter_struct.

getindex(pd::ParamDict, name)

Retrieve the parameter name, converted to the type declared in the TOML file.

The parameter is logged as used by the component "getindex", so values read this way still appear in the file written by write_log_file.

Arguments

• name: The name of the parameter to retrieve.

Returns

The parameter's value, cast to the type given by its type metadata (e.g. FT, Int, String, Bool, DateTime). Array-valued parameters return a Vector of that type.

Examples

toml_dict = CP.create_toml_dict(Float64)
toml_dict["planet_radius"]  # 6.371e6

See also get_parameter_values.

create_parameter_struct(param_struct_type, toml_dict, name_map, [nested_structs])

Construct an instance of a parameter struct from a TOML dictionary.

Retrieve all required parameter values using name_map and instantiate param_struct_type, including any nested_structs.

This function makes several assumptions about the parameter struct:

• It has a constructor that accepts keyword arguments for its fields.
• Its first type parameter is the floating-point type (e.g., MyParams{FT}).
• All nested parameter structs required by the constructor are passed via nested_structs.

Arguments

• param_struct_type: The type of the parameter struct to be created (e.g., MyParams).
• toml_dict::ParamDict: The TOML dictionary containing the parameter values.
• name_map: A Dict or other iterable of Pairs to map TOML names to struct field names.
• nested_structs: A NamedTuple of already-constructed nested parameter structs, if any.

Examples

Base.@kwdef struct GravityParameters{FT}
    g::FT
    planet_radius::FT
end

name_map = Dict("gravitational_acceleration" => "g", "planet_radius" => "planet_radius")
params = CP.create_parameter_struct(GravityParameters, toml_dict, name_map)

get_tagged_parameter_values(pd::ParamDict, tag)

Return the values of all parameters carrying the given tag, or any of the given tags.

Arguments

• tag::Union{AbstractString, Vector{<:AbstractString}}: The tag, or vector of tags, to search for.

Returns

A NamedTuple keyed by parameter name. Empty if no parameter carries the tag.

Examples

toml_dict = CP.create_toml_dict(Float64; override_file = "tagged_parameters.toml")
CP.get_tagged_parameter_values(toml_dict, "SurfaceFluxes")

See also get_tagged_parameter_names.

get_tagged_parameter_names(pd::ParamDict, tag)

Return the names of all parameters carrying the given tag, or any of the given tags.

Tag matching is case-insensitive and ignores punctuation and whitespace; see fuzzy_match.

Arguments

• tag::Union{AbstractString, Vector{<:AbstractString}}: The tag, or vector of tags, to search for.

Returns

Vector{String}: the names of the parameters carrying the tag(s), in unspecified order. Empty if no parameter carries the tag.

fuzzy_match(s1::AbstractString, s2::AbstractString)

Compare two strings for equality, ignoring case and select punctuation.

The characters [' ', '_', '*', '.', ',', '-', '(', ')'] are stripped from both strings before comparison.

log_parameter_information(pd::ParamDict, filepath; strict::Bool = false)

Perform end-of-setup parameter handling: write the log file and check the override file for unused entries.

Calls write_log_file to save the used parameters, then check_override_parameter_usage to verify that every override parameter was read by some component. Call it after all parameter structs have been constructed and before the run starts.

Arguments

• filepath: The path for the output log file.

Keyword Arguments

• strict = false: If true, error when override parameters are unused; otherwise warn.

Examples

toml_dict = CP.create_toml_dict(Float64; override_file = "my_experiment.toml")
# ... construct parameter structs ...
CP.log_parameter_information(toml_dict, "parameter_log.toml")

write_log_file(pd::ParamDict, filepath::AbstractString)

Save all used parameters to a TOML file at filepath.

Only parameters that have been logged with log_component! are written, so the result is a record of the parameters an experiment read. The file is itself a valid parameter file and can be passed back as an override_file to reproduce the run.

Arguments

• pd: The parameter dictionary containing usage logs.
• filepath: The path where the log file will be saved.

check_override_parameter_usage(pd::ParamDict, strict::Bool)

Verify that every parameter supplied in an override file was used during the simulation, by checking for the "used_in" log entry.

Does nothing when pd was created without an override file.

Arguments

• strict: If true, throw an error when any override parameter is unused. If false, only warn.

check_override_parameter_usage(pd::ParamDict, params, strict::Bool)

Verify that the subset of override parameters listed in params was used during the simulation, by checking for the "used_in" log entry.

Throws an error if pd was created without an override file, or if any name in params is absent from it.

Arguments

• params: An iterable of parameter names, each of which must appear in the override file.
• strict: If true, throw an error when any of these parameters is unused. If false, only warn.

log_component!(pd::ParamDict, names::NAMESTYPE, component::AbstractString)

Log that a set of parameters is used by the model component.

This function modifies the parameter dictionary in-place by adding or appending the component string to a "used_in" entry for each parameter specified in names. This is crucial for tracking which parameters are active in a simulation.

Arguments

• pd: The parameter dictionary to be modified.
• names: A vector or tuple of strings with the names of parameters to log.
• component: The name of the model component using the parameters.

iterate(pd::ParamDict, [state])

Iterate over the underlying name => metadata pairs of pd.

The second element of each pair is the raw metadata Dict read from the TOML file ("value", "type", "description", ...), not the typed value. Use Base.getindex or get_parameter_values to obtain typed values.

print(pd::ParamDict, io = stdout)

Print the full contents of pd, including all metadata, as TOML.

The arguments are in the opposite order to the Julia convention. There is deliberately no print(io::IO, pd) method: defining one would also capture println(pd), string(pd), and string interpolation, which fall through to show and give a one-line summary.

Use write_log_file to write only the parameters that were used.

show(io::IO, pd::ParamDict)

Show a one-line summary of pd: its float type and the number of parameters it holds.

==(pd1::ParamDict, pd2::ParamDict)

Compare two parameter dictionaries.

Two ParamDicts are equal when they share a float type and hold identical parameter data and override data. Because usage logging writes a used_in entry into the data, two dictionaries built from the same files compare unequal once different parameters have been read from them.