API

ParamDict{FT}

A concrete parameter dictionary that stores parameter data from TOML files.

This struct holds the effective set of parameters (defaults merged with any overrides) and tracks which override parameters have been used.

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.

Base.getindex(pd::ParamDict, key)

Retrieves a parameter by its key, converting it to the type specified in the TOML file.

This allows for direct, dictionary-like access to the typed value of a parameter.

Arguments

• pd::ParamDict: The parameter dictionary.
• key: The name of the parameter to retrieve.

Returns

• The parameter's value, cast to the type defined in its metadata (e.g., Float64, Int, Bool).

Examples

toml_dict = CP.create_toml_dict(Float64)
param_value = toml_dict["planet_radius"]  # Returns the value, e.g., 6.371e6

float_type(pd::ParamDict)

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

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

Creates 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 a default_file and optionally an override_file, with parameters from the override file taking precedence. The sources can be file paths or already-parsed Julia Dicts.

Arguments

• FT::{Type{<:AbstractFloat}}: The floating-point type to be used for all "float" parameters.

Keywords

• override_file: Path to a TOML file or a Dict containing override parameters.
• default_file: Path to the default TOML file or a Dict containing default parameters. Defaults to the parameters.toml file in the package directory.

Returns

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

merge_toml_files(filepaths; override::Bool=false)

Parses and merges 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.

get_parameter_values(pd, names, [component])
get_parameter_values(pd, name_map, [component])

Retrieves parameter values from the dictionary pd, returning them in a NamedTuple. This function has two main methods:

1. Retrieve parameters by a list of names.
2. Retrieve and rename parameters using a name_map.

If a component string is provided, it also logs the parameters as being used by that component.

Arguments

• pd::ParamDict: The parameter dictionary.
• names::Union{String,Vector{String}}: A single name or vector of names to retrieve.
• name_map: A Dict or other iterable of Pairs mapping the parameter name in the TOML file to the desired variable name in the code (e.g., "long_name_in_toml" => "short_name_in_code").
• component::Union{AbstractString, Nothing}: An optional string to log which model component uses these parameters.

Returns

• A NamedTuple where keys are the parameter names (or the renamed variable names) and values are the corresponding typed parameter values.

Examples

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

# Method 2: Retrieve and rename
name_map = Dict("gravitational_acceleration" => "g", "planet_radius" => "R_p")
params_renamed = get_parameter_values(toml_dict, name_map)
# params_renamed.g = 9.81

get_tagged_parameter_values(pd::ParamDict, tag)

Retrieves the values of all parameters associated with a given tag or list of tags.

Arguments

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

Returns

• A NamedTuple of the tagged parameters, where keys are parameter names and values are their typed values.

get_tagged_parameter_names(pd::ParamDict, tag)

Retrieves the names of all parameters associated with a given tag or list of tags.

Tag matching is case-insensitive and ignores punctuation and whitespace.

Arguments

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

Returns

• Vector{String}: A list of parameter names that have the specified tag(s).

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

Compares 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)

A convenience function that performs end-of-run parameter handling.

It calls write_log_file to save used parameters and then check_override_parameter_usage to validate that all override parameters were used.

Arguments

• pd::ParamDict: The parameter dictionary.
• filepath::{AbstractString}: The path for the output log file.
• strict::Bool: If true, errors if override parameters are unused.

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

Saves all used parameters to a TOML file at the specified filepath.

This function filters the dictionary to include only parameters that have been logged with log_component!, creating a file that can be used to reproduce an experiment with the exact same parameter set.

Arguments

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

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

Verifies that all parameters supplied in an override file were actually used during the simulation by checking for the "used_in" log entry.

Arguments

• pd::{ParamDict}: The parameter dictionary to check.
• strict::Bool: If true, throws an error if any override parameter is unused. If false, only a warning is issued.

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

Logs that a set of parameters are used by a specific 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::{ParamDict}: The parameter dictionary to be modified.
• names: A vector or tuple of strings with the names of parameters to log.
• component::{AbstractString}: The name of the model component using the parameters.

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

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

This function retrieves all necessary parameter values using a name_map and instantiates the 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.