Canopy Model Tutorial Improvements

[Espeer5]

I've written draft tutorials for using the CanopyModel in both standalone mode and as a part of the SoilPlantHydrologyModel (Related to #240) and would love some feedback on what I can improve in the tutorials, visible on the branch "canopy-tutorials":

• Standalone tutorial: https://github.com/CliMA/ClimaLSM.jl/blob/canopy-tutorials/docs/tutorials/Canopy/canopy_tutorial.jl
• SoilPlantHydrologyModel tutorial: https://github.com/CliMA/ClimaLSM.jl/blob/canopy-tutorials/docs/tutorials/Canopy/soil_plant_hydrology_tutorial.jl

In particular:

• The tutorials for the soil model each include discussion of the equations relevant to the model. For the canopy model, there are a lot more equations since each of the photosynthesis, plant hydraulics, and radiative transfer models have a set of equations, so I'm wondering what should be included here: https://github.com/CliMA/ClimaLSM.jl/blob/1fe5909a9820c2b2eb3aa6b02ba591a4aa845860/docs/tutorials/Canopy/canopy_tutorial.jl#L18
  • Since the relevant equations for each component are going to be fully explained in the dynamic docs, perhaps this could cite each component of the canopy model along with a link to those docs? (e.g "For an explanation of the equations used for photosynthesis refer to Farquhar Model")
• What other plotting examples would be useful/demonstrative to show other than the ones I've included in each tutorial?
• Anything else that can be improved

Thanks!

[AlexisRenchon]

Hey Edward, just FYI, if you create a PR, you will be able to preview your docs. Don't hesitate to open a PR! For example the Farquhar model example you linked is from PR #214.

One thing I plan to do for tutorial & visualization is embed a web app in those docs (similarly to the interactive figure in Farquhar page) where a user can for example change [a parameter value or the domain or timestepper,...] then click on a [run] button and it generates an animation of a time series of various things (e.g., GPP, ET, precip, SWC, etc.), then the user can change things again, reclick on run, etc.

I do this with Makie and JSServe and host the web app on an Amazon Azure Ubuntu server.

If that sounds of interest to you and if Renato is happy with you spending some time on this I can help you with it.

[braghiere]

That looks great, @Espeer5! Thanks!

I think it is a great idea to cite each component of the canopy model along with a link to the dynamic docs. It becomes very clear and well exemplified.

Some other useful plots could be the ones that @kmdeck show here, particularly the ones for soil temperature and soil water content.

I like @AlexisRenchon 's suggestion to create a PR, so we can preview your docs. Also, when we have the two-stream coded up, you can work on a dynamic doc for it using Makie. It is a great new tool that has been broadly used by the community and super helpful to understand what the function is actually doing.

[Espeer5]

I've opened a PR for these tutorials (see #258), however I cannot yet view a preview of the tutorials yet because of a package issue. The tutorials need to load data from the Ozark experiment, which requires using the package Dierckx, which is properly imported but doesn't seem to be installed in the runtime for building the docs. I'm not sure how to fix this, could anyone help me to resolve this issue? (See the docBuild test failure for PR mentioned above)

[kmdeck]

I've opened a PR for these tutorials (see #258), however I cannot yet view a preview of the tutorials yet because of a package issue. The tutorials need to load data from the Ozark experiment, which requires using the package Dierckx, which is properly imported but doesn't seem to be installed in the runtime for building the docs. I'm not sure how to fix this, could anyone help me to resolve this issue? (See the docBuild test failure for PR mentioned above)

hey! so, you need to update the Project.toml in the docs directory to include Dierckx: https://github.com/CliMA/ClimaLSM.jl/blob/main/docs/Project.toml To do so, go to ClimaLSM.jl/docs julia --project ]add Dierckx

then, leave Julia. when you type "git status" you'll see that both that Project.toml and Manifest.toml in docs/ have changed. you would add them both to the PR & commit/push up, and it should run then.

[Espeer5]

Canopy Tutorial previews:

• Standalone: https://clima.github.io/ClimaLSM.jl/previews/PR258/generated/Canopy/canopy_tutorial/
• soil_plant_hydrology model: https://clima.github.io/ClimaLSM.jl/previews/PR258/generated/Canopy/soil_plant_hydrology_tutorial/