ClimaLand Model User Experience #1186
Description
Purpose
Improve the user experience of climaland by
- creating a simpler interface which allows running a default simulation in a few lines of code, while also allowing complete control over parameterizations used if the user wants to change these
- improving the documentation
Philosophy
The “model” object encodes the spatially discretized equations. It specifies a set of ODEs and also necessarily provides some information about what tendencies are implicit vs explicit, and how to create a Jacobian. Because it specifies the ODEs, it must define the parameters, prognostic variables, time dependent forcing, etc. It also depends on the domain because the equations are spatially discretized already.
A “simulation” contains the model, timestepper, diagnostics (and other callbacks not specified by the model independently), and current time/state of the system Y. Right now we do the latter using the SciML’s integrator, but this is heavy for what we need.
These two concepts should be distinct.
The simulation interface should be easily used in the majority of tutorials and experiment scripts. The model interface we develop should as well, with the possible exception of standalone soil model examples not forced by atmospheric data, for which our current constructors may be better suited. We should develop an interface that we want to use as developers.
Results and deliverables
Running a default simulation:
FT = Float64
start_date = DateTime("2000-03-01")
stop_date = DateTime("2010-03-01")
Δt = 450.0
domain = ClimaLand.ModelSetup.global_domain(FT; comms_ctx)
params = LP.LandParameters(FT)
forcing = ClimaLand.ModelSetup.era5_forcing(FT) # This currently depends on start_date, stop_date, but perhaps those should live in then simulation only, and not the model.
model = LandModel(domain, forcing; params)
simulation = LandSimulation(FT, start_date, stop_date, Δt, model; outdir)
solve!(simulation)
plot!(simulation)
Changing e.g. a single parameterization in the soil model
soil = EnergyHydrology(domain; params, runoff_scheme = NewRunoffScheme(params))
model = LandModel(domain, forcing; params, soil)
Task breakdown
- First pass at simulations module and struct added
- Make list of parameterizations that need to be modular @kmdeck
- Make parameterizations structs so that they can be changed one at a time, and are not hardcoded. Remove flat parameter structs where it makes sense in favor of parameters living in their parameterization struct (to make the parameterization modular). Will need to move some stuff to ClimaParams that has defaults specified in ClimaLand now. Use consistent names for Models vs Parameterizations @juliasloan25 @kmdeck, split up parameters and remove ModelSetup #1211
- Model setup interface, see Model setup of soil models #1170 Model specification in simulations struct #1140 split up parameters and remove ModelSetup #1211 Remove CreateParams extension, ClimaParams in Project.toml, expose roughness and emissivity #1219 # 1220 add constructors for CanopyModel + integrated models #1255 Add convenience constructors for canopy model components #1233 use get_default_parameter for canopy parameters #1256
- Use new model setup interface in tutorials and experiments use new LandModel constructors #1306 use new canopy and soil constructors in tutorials and experiments #1284
- Use simulations struct in tutorials and experiments Tr/use land simulation struct #1191
- Make it so someone can create a set of default plots easily for global simulations @kmdeck PR Default global plots using simulation struct #1199
- Make it so someone can create a set of default plots easily for fluxnet simulations PR Fluxnet plotting #1276
- Move fluxnet forcing to src PR Move forcing script from fluxnet experiments to src #1238
- Default parameters for fluxnet sites Enable reading spatial data to a point/column #1279 add FluxnetSimulations ext #1259 add lat/lon constructors for Point and Column #1237
- figure out how to remove start and stop date from the model
- Remove SciML dependence, add Y, p, t to Simulations struct: Remove direct dependency on SciMLBase #1159 Moved to new issue so I am checking off here: Remove sciml dependence #1379
- Documentation: how to install Julia, improve README, create an introduction to ClimaLand @juliasloan25 Add docs landing page #1188
- Fluxnet and global tutorials in docs Fluxnet and global run documentation #1288
- Remove existing ClimaLandSimulations
- unify callbacks Generalize callbacks #1316
- resolve callback ordering problem It is unclear what state is saved in diagnostics and saving callbacks #1241
...