search

CliMA / SurfaceFluxes.jl

A package for computing surface fluxes between the atmosphere, ocean and land models.
https://clima.github.io/SurfaceFluxes.jl/dev/
Apache License 2.0
17 stars 4 forks source link

tutorial #139

Open kmdeck opened 11 months ago

kmdeck commented 11 months ago

Purpose

Close #134 - though some of the discussion around displacement height may be specific to land, where u = 0.

Deploys here: https://clima.github.io/SurfaceFluxes.jl/previews/PR139/basic_usage/index.html

To-do

figure out why CI fails thought I do not touch src, tomls make sure it deploys with correct url

Content

add a markdown doc

Review checklist

I have:

In the Content, I have included

glwagner commented 11 months ago

What do you think about me trying to turn this into a script that I can try to run and putting it in a new directory examples? If that seems like a nice idea I am happy to put the work into that. I think this is extremely helpful already so it's not necessary, but having a script that can be executed I think would accelerate getting up and started with this package even further?

kmdeck commented 11 months ago

What do you think about me trying to turn this into a script that I can try to run and putting it in a new directory examples? If that seems like a nice idea I am happy to put the work into that. I think this is extremely helpful already so it's not necessary, but having a script that can be executed I think would accelerate getting up and started with this package even further?

sure! A script would for be easier to start from. I also thought about making a Literate tutorial (julia script that runs but also appears in the docs with markdown). That is a little more involved but we have examples of how to update the make.jl to handle it. it might be nice if we envision a couple of tutorials being helpful?

glwagner commented 11 months ago

Do you distinguish between examples and tutorials or are they the same thing? I find that example scripts are the most useful. Docs tutorials are also helpful for many (but less for me, as a developer in addition to user). I also like Literate to save some effort and code.

kmdeck commented 11 months ago

hm, in ClimaLSM we have docs tutorials (simple examples, intro to interface, etc, using Literate) and experiments (longer simulations more relevant to earth system modeling, not rendered as docs). Im not sure how to use Literate outside of the docs, though.

glwagner commented 11 months ago

I'm just clarifying! We refer to examples as a script that can be executed and illustrates an entire workflow, like this:

https://github.com/CliMA/Oceananigans.jl/blob/main/examples/two_dimensional_turbulence.jl

A "tutorial" is a bit different in that it goes a bit more slowly and pedagogically and may not go through the entire workflow. Usually packages distinguish between "examples" and "tutorials" so I wanted to make sure we were talking about the same thing.

As for Literate, I think that is most relevant for examples, since it may not be useful to execute a tutorial anyways (but it's definitely possible to write a tutorial that way). But Literate allows us to write a script like any other but also include that script with output in the docs, maximizing its utility.

glwagner commented 11 months ago

So just to summarize what's in this PR is great, I only wanted to ask if it would make sense to transfer its content to a script that could be executed (which I'm happy to do as well as setting up Literate).

I can also put a little atmos/ocean data into the example and then make a figure like I've done on https://github.com/CliMA/Thermodynamics.jl/pull/172

kmdeck commented 11 months ago

So just to summarize what's in this PR is great, I only wanted to ask if it would make sense to transfer its content to a script that could be executed (which I'm happy to do as well as setting up Literate).

I can also put a little atmos/ocean data into the example and then make a figure like I've done on CliMA/Thermodynamics.jl#172

that all sounds great! Id learn from seeing literate set up from scratch.

These also provide a nice way to communicate with the atmos folks and make sure everyone is on the same page re usage.

glwagner commented 10 months ago

So just to summarize what's in this PR is great, I only wanted to ask if it would make sense to transfer its content to a script that could be executed (which I'm happy to do as well as setting up Literate). I can also put a little atmos/ocean data into the example and then make a figure like I've done on CliMA/Thermodynamics.jl#172

that all sounds great! Id learn from seeing literate set up from scratch.

These also provide a nice way to communicate with the atmos folks and make sure everyone is on the same page re usage.

Ok! I can add to this PR (but I'd need to be a collaborator) or can start a new PR once this is merged.