Implements a single column example

[glwagner]

This PR implements an example of how CLIMAParameters would be used to configure an Oceananigans simulation.

The simulation is implemented within a function that takes the parameter values as keyword arguments.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 94.19%. Comparing base (ec828db) to head (945f3a5).

:exclamation: Current head 945f3a5 differs from pull request most recent head 43a0617

Please upload reports for the commit 43a0617 to get more accurate results.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #151      +/-   ##
==========================================
- Coverage   98.50%   94.19%   -4.32%     
==========================================
  Files           2        1       -1     
  Lines         134      155      +21     
==========================================
+ Hits          132      146      +14     
- Misses          2        9       +7     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[glwagner]

Executing run_single_column_simulation should load parameter values from both default_parameters.toml and my_parameters.toml, and then runs a simulation, and then produces this animation:

https://github.com/CliMA/CLIMAParameters.jl/assets/15271942/f77ab862-a19f-485e-81fc-e59456ddec6d

[glwagner]

We could also add some CATKE parameters to this example, if folks think it would be useful. Also, I'm not sure exactly how one is supposed to use the component argument to get_parameter_values! (here set arbitrarily to "Ocean"):

https://github.com/glwagner/CLIMAParameters.jl/blob/624681b3ad2151750994e7c0c32e705290af12cd/examples/SingleColumnSimulation/run_single_column_simulation.jl#L12C2-L12C82

so maybe some feedback on that would be useful.

[trontrytel]

It's amazing how very few parameters you actually need :)

I'm wondering if this example would fit better into ClimaOcean.jl repo? I thought that was the iinterface layer between Ocenaningans and all the CliMA overhead?

[glwagner]

It's amazing how very few parameters you actually need :)

There are a number of CATKE parameters that also matter, I can add them to increase the number! It seemed that few parameters helps make it easier to read for this simple example.

I'm wondering if this example would fit better into ClimaOcean.jl repo? I thought that was the iinterface layer between Ocenaningans and all the CliMA overhead?

This particular example isn't useful in ClimaOcean... it's supposed to serve as a guide for people developing parameter interfaces. But ultimately, there will be something similar to this. The thing we don't have is something (useful) that is the analog of single_column_simulation.

[glwagner]

@trontrytel check it out, I added 19 more parameters! Perhaps things seem more familiar now.

We could also add a sea ice example, which might have thermodynamic parameters that would have to be consistent with microphysics, like the latent heat of fusion at some reference temperature?

[trontrytel]

That looks more familiar 😅

I like the idea of a consistency check between different modules. I'm still not sure if it should live here.

At the very minimum we should check that we are using the same constants across modules. Even better, a consistency check different modules compute the same thing for example when faced with a chunk of ice that melts.

[glwagner]

That looks more familiar 😅

I like the idea of a consistency check between different modules. I'm still not sure if it should live here.

At the very minimum we should check that we are using the same constants across modules. Even better, a consistency check different modules compute the same thing for example when faced with a chunk of ice that melts.

One possibility is that when (if?) ClimaAtmos has an interface like this one, then it would be the responsibility of a function such as earth_system_simulation to enforce that thermodynamic parameters are consistently dispersed among the component models.

This requirement already exists in Oceananigans. It's possible to use two different gravitational accelerations --- one for the free surface, and another for buoyancy (this is intentional and important to allow for testing and reproducibility). So it's the responsibility of the "setup function" such as ocean_sea_ice_simulation to ensure that gravitational_acceleration is correctly set in both the buoyancy and free surface components.

[glwagner]

Should we also demonstrate in this PR how to use values from the file at https://github.com/CliMA/CLIMAParameters.jl/blob/main/src/parameters.toml ? I'm not entirely sure this is what we would want to do for a "single_column_simulation" like the one implemented here. @LenkaNovak has thoughts I know!

[glwagner]

This looks good! I left a few comments. One overall change: the folder name should be changed to something more Oceananigans-specific in case we want to add other examples in the future. We should also add a section in the docs to point users to this example. I can do this in a later PR.

Changes made.

Happy to load the example into the docs (via Literate?) but maybe best for a future PR given the changes already

[nefrathenrici]

Happy to load the example into the docs (via Literate?) but maybe best for a future PR given the changes already

Maybe @odunbar wants to take a look, but I think this PR is ready to merge once it's been formatted and squashed.