Overhaul ClimaParameters

[nefrathenrici]

The Climate Modeling Alliance

Software Design Issue 📜

Purpose

ClimaParameters is starting to become difficult to use as we scale up the number of parameters and our needs for the interface change. This will address usability, naming conventions, and overriding parameters as particular pain points.

Cost/Benefits/Risks

The primary risk stems from breaking changes that require people to update downstream repositories. We want to get the interface changes right the first time so that downstream repos don't have to keep changing how they use ClimaParameters.

The secondary risk is introducing bugs as we add complexity. This will require extensive testing.

People and Personnel

• Lead: @nefrathenrici
• Collaborators: @odunbar
• Reviewers:

Components

Change naming conventions

The current format requires each parameter to have a long, descriptive name and a shorter alias which gets used in code. These both have to be unique, and it forces different models to use the same names in-code. This creates issues for writing clean code: there are currently four parameters that have some variation of the name T_min: T_min, T_min_ref, T_min_hs, H2SO4_sol_T_min. Since these are all used in different repositories, they could all be called T_min if they didn't have to be unique.

To fix this, the current functionality of the alias field and the AliasParamDict type will be removed. This functionality will be replaced by parameter name mappings, which form a bijective map from names in the parameters.toml file to the names used by packages in-code. This will allow each package to define their own parameters names, so that they don't have to be unique across packages. We will provide a default map so that packages don't need to provide their own name mapping to use climaparameters. This will be based off of the current proper names and aliases.

Overriding

The current override syntax is clunky and overly verbose.
Consider the gravity parameter.

[gravitational_acceleration]
alias = "grav"
value = 9.81
type = "float"

To override this, a separate file or dictionary must be provided with all of the same fields:

[gravitational_acceleration]
alias = "grav"
value = 400
type = "float"

We should remove the default type and error if no type is provided. This will provide enough safety for the following override syntax, which already works but has been discouraged:

[gravitational_acceleration]
value = 400

This is concise enough syntax while keeping the normal TOML format.

Searching parameters

We don't have any support for searching through or segmenting the full parameter set. For now, it is sufficient to set up a simple tagging system which is already partially implemented, but is not widely used. Each parameter can be tagged for the model(s) that use it. To keep tag names standardized, we could provide a list of model components or names in the documentation for devs to draw from. To start, I will manually fill in this field for most parameters, and add functions to search parameters by tags. After that, devs will have to manually add tags unless we provide some sort of automatic infrastructure. This will also enable us to ensure parameters are being used properly, since we can flag unused parameters.

Array Parameters

This is a minor issue, but array parameters are poorly defined at the moment. The documentation conflicts with the code and needs to be updated.

Inputs

Results and Deliverables

Task Breakdown And Schedule

• Name map
• Parameter search
• Override syntax and array parameters

SDI Revision Log

Revised 2.6.24

CC

@tapios @simonbyrne @cmbengue

[tapios]

Looks good to me. Looks like this would be good to finish before bringing ClimaParameters consistently to ClimaLSM.

[trontrytel]

Hi @nefrathenrici - thank you for doing that. I have 2 questions:

1. Could you provide a code snippet example of this parameter mapping map? @sriharshakandala and me recently spent some time overhauling the parameters in CloudMicrophysics.jl (we have a lot of them there). We ended up creating a bunch of structs that hold small numbers of parameters for different parameterizations/modules. See for example here:https://github.com/CliMA/CloudMicrophysics.jl/blame/2207d173052a6247da98681606bd0b7a0029b3a9/src/parameters/aerosol_illite.jl#L9-L23
   Would that be compatible? Is that what you have in mind?

2. Would that be a good time to add more units and DOI links to parameter descriptions? (I can take it on for CloudMicrophysics.jl parameters)

[odunbar]

Also should include Renaming the repo to ClimaParameters.jl?

[trontrytel]

Also should include Renaming the repo to ClimaParameters.jl?

I think it's hard to rename once you register a package. Maybe it's ok to leave it be?

[glwagner]

Also should include Renaming the repo to ClimaParameters.jl?

I think it's hard to rename once you register a package. Maybe it's ok to leave it be?

It's not hard to rename a package (it effectively becomes a new package): https://github.com/JuliaRegistries/General#how-do-i-rename-an-existing-registered-package

The irritating part is that you cannot remove the old name.

[nefrathenrici]

With the package renamed, we can close this as completed.