docs

docs/make.jl

@@ -3,7 +3,7 @@ using CLIMAParameters, Documenter
 pages = Any[
     "Home" => "index.md",
     "TOML file interface" => "toml.md",
-    "TOML dicts" => "toml_dicts.md",
+    "Parameter retrieval" => "param_retrieval.md",
     "API" => "API.md",
 ]
 

docs/src/toml_dicts.md → docs/src/param_retrieval.md

@@ -1,3 +1,47 @@
+# Basic Parameter Retrieval
+
+The basic flow combines two functions:
+- `create_toml_dict` constructs a TOML dictionary which stores parameters,
+- `get_parameter_values` retrieves parameters from the TOML dictionary.
+
+To construct a TOML dictionary, pass in the desired floating point type:
+```julia
+import CLIMAParameters as CP
+toml_dict = CP.create_toml_dict(Float64)
+```
+To retrieve parameters, pass in the dictionary and the name(s) of parameters:
+```julia
+params = CP.create_parameters(toml_dict, ["gravitational_acceleration", "gas_constant"])
+params.gravitational_acceleration
+params.gas_constant
+```
+You can also pass in a single parameter name:
+```julia
+params = CP.create_parameters(toml_dict, "gravitational_acceleration")
+params.gravitational_acceleration
+```
+
+# Name Maps
+Name maps provide a way to map from long descriptive parameter names to short variable names
+found in code. 
+A name map is any pair-based iterable that maps from long parameter names to short variable names.
+To use a name map, pass it into `get_parameter_values`, which will return the 
+parameters with your given variable names.
+
+Here is an example:
+```julia
+name_map = Dict(
+    "gravitational_acceleration" => "g",
+    "angular_velocity_planet_rotation" => "omega"
+)
+params = CP.get_parameter_values(toml_dict, name_map)
+params.g
+params.omega
+```
+
+
+
+
 # Parameter Dictionaries
 
 Parameters are stored in objects that reflect the model component construction. Definitions should be inserted into the model component source code.

src/file_parsing.jl

@@ -132,18 +132,19 @@ end
         component::String
     )
 
-Given a toml dict and a list of parameter names, returns a NamedTuple of the 
-parameters and their values. If a component is specified, the parameter is
-logged as being used in that component.
-
     get_parameter_values(
         pd::AbstractTOMLDict,
-        name_map,
+        name_map::Union{Dict, Vector{Pair}, NTuple{N, Pair}, Vararg{Pair}},
         component::String
     )
-Instead of a list of parameter names, takes in a mapping from long parameter names
-to variable names in code. Retrieves all parameters in the mapping and returns 
-a NamedTuple where the keys are the variable names.
+
+Given a toml dict and a list of parameter names, returns a NamedTuple of the 
+parameters and their values. If a component is specified, the parameter is
+logged as being used in that component.
+
+Instead of a list of parameter names, this can take an iterable mapping from
+parameter names to variable names in code. Then, this function retrieves all parameters 
+from the long names and returns a NamedTuple where the keys are the variable names.
 """
 function get_parameter_values(
     pd::AbstractTOMLDict,

test/test_merge.jl

@@ -22,20 +22,18 @@ import CLIMAParameters as CP
     # Test merging
     merged_dict = CP.merge_toml_files([toml_1, toml_2]; override = true)
     merged_toml_dict = CP.create_toml_dict(FT, default_file = merged_dict)
-    (; a) = CP.get_parameter_values(merged_toml_dict, "a")
+    (; a, b) = CP.get_parameter_values(merged_toml_dict, ["a", "b"])
     @test a == 2
     @test a isa Int
-    (; b) = CP.get_parameter_values(merged_toml_dict, "b")
     @test b == 3.0
     @test b isa FT
 
     # Swap merge order
     merged_dict = CP.merge_toml_files([toml_2, toml_1]; override = true)
     merged_toml_dict = CP.create_toml_dict(FT, default_file = merged_dict)
-    (; a) = CP.get_parameter_values(merged_toml_dict, "a")
+    (; a, b) = CP.get_parameter_values(merged_toml_dict, ["a", "b"])
     @test a == 0.0
     @test a isa FT
-    (; b) = CP.get_parameter_values(merged_toml_dict, "b")
     @test b == 3.0
     @test b isa FT
 end