Bucket diagnostics

[AlexisRenchon]

Purpose

This PR adds diagnostics to ClimaLand, as a new module in /src.
This module is built on ClimaDiagnostics.jl, which is also used by
ClimaAtmos. It contains default diagnostics methods for different
ClimaLand models (for now, BucketModel and SoilCanopyModel), those
diagnostics contains metadata such as where diagnostics variables are
stored in those models, what is there names (short, long, standard)
and physical units, with additional comments. It creates a Dict of those
variables, and also default Scheduling methods, such as hourly average
or monthly maximum. Users can define their own diagnostic variables or
scheduling, and developpers can add defaults. More information are
available in the documentation.

[AlexisRenchon]

@Sbozzolo

Do you know why ClimaLandSimulations CI fail?
The error is

Run julia --project= -e 'using Pkg; Pkg.develop(path="$(pwd())"); Pkg.develop(path="$(pwd())/lib/ClimaLandSimulations")'
   Resolving package versions...
ERROR: Unsatisfiable requirements detected for package ClimaDiagnostics [1ecacbb8]:
 ClimaDiagnostics [1ecacbb8] log:
 ├─possible versions are: 0.0.1-0.0.5 or uninstalled
 └─restricted to versions 0.2 by ClimaLand [08f[4](https://github.com/CliMA/ClimaLand.jl/actions/runs/9321596680/job/25660930914?pr=628#step:5:5)d4ce] — no versions left
   └─ClimaLand [08f4d4ce] log:
     ├─possible versions are: 0.12.2 or uninstalled
     └─ClimaLand [08f4d4ce] is fixed to version 0.12.2

But if I run

julia --project= -e 'using Pkg; Pkg.develop(path="$(pwd())"); Pkg.develop(path="$(pwd())/lib/ClimaLandSimulations")'

locally, it works just fine

[Sbozzolo]

Maybe you have to add ClimaDiagnostics to the Project.toml for ClimaLandSimulations?

[AlexisRenchon]

@kmdeck Could you just look at src/Diagnostics/define_diagnostics.jl and check if the names, units, and comments look good? No need to review the full PR!

Thank you!!

[AlexisRenchon]

@Sbozzolo

• I moved the experiment to test (there is nothing new in experiment now). The idea is having a global bucket model in test that then calls some Diagnostic functions and test them. To do that, I had to add SciMLBase and ClimaTimeSteppers to the test Project.toml, I am not sure if this is something we are trying to avoid.
• I added comments and changed some names to src/Diagnostics/define_diagnostics.jl
• I added your macro to generate error functions
• Docs: available_diagnostics works well
• Docs: I added more content to developers and users documentation page, but there is still more to add (and add more links)
• All CI checks passed

[Sbozzolo]

You can try uncommenting this

[AlexisRenchon]

Let's go back to this at some point, as discussed, this still doesn't work

[Sbozzolo]

Maybe leave a comment on why this is commented out

[Sbozzolo]

Did this work?

Let's add tests to check that it works and let's add comments to explain how this works.

[AlexisRenchon]

the test didn't work, let's discuss this when we meet

[Sbozzolo]

@Sbozzolo

• I moved the experiment to test (there is nothing new in experiment now). The idea is having a global bucket model in test that then calls some Diagnostic functions and test them. To do that, I had to add SciMLBase and ClimaTimeSteppers to the test Project.toml, I am not sure if this is something we are trying to avoid.

We should try to have more isolated unit tests that test the various functions, instead of a full experiment.

[Sbozzolo]

This should probably not be here

[Sbozzolo]

For your reference, as discussed

@test_throws ErrorException get_diagnostic_variable("bob")

[AlexisRenchon]

I added that test, BUT, currently we do not call define_diagnostics! inside src (only in docs), so get_diagnostic_variable would throw an error with any variable...

[Sbozzolo]

You can call define_diagnostics in your test

[Sbozzolo]

To test this

@test_throws ErrorException("cannot albedo with nothing") compute_albedo!(_, _, _, _, nothing)

Also check that compute_albedo! is defined

[AlexisRenchon]

julia> using Test

julia> using ClimaLand

julia> @test isdefined(ClimaLand.Diagnostics, :compute_albedo!)
Test Passed

julia> @test_throws ErrorException("cannot albedo with nothing") ClimaLand.Diagnostics.comput
e_albedo!(_, _, _, _, nothing)
ERROR: syntax: all-underscore identifier used as rvalue around REPL[9]:1
Stacktrace:
 [1] top-level scope
   @ REPL[9]:1

[Sbozzolo]

What if I want to compute some existing diagnostics but with different Writers? Or with different frequencies?

[AlexisRenchon]

Let's discuss the Bucket experiment a bit, we want to use an existing experiment, but it would be good if variables vary in space at least... I am not sure it is the case with global_bucket_function.jl (our heatmap plots are 1 color), maybe we should use another. We were using global_bucket_temporalmap.jl because of this, which has albedo varying in space (read from a file), but it defines the bucket model inside a function that I commented out before... and we want to not change the previous code but add diagnostics to it. Anyway, let's discuss.

[Sbozzolo]

Let's not forget about the issue on @generate_error_functions

[Sbozzolo]

Some work is left for a future PR, but this looks good!

Thank you very much!