O2.3.6 Implicit solver for full soil model

[kmdeck]

Purpose

We need an implicit solver for the soil model (both for Richards equation alone, and the full soil system), and possibly in the future for other models as well. Currently, the implicit solver for Richards equation is implemented and in use. The full soil implicit solver is still in progress.

Components

• A way to specify separate explicit and implicit tendencies
  • Richards equation: https://github.com/CliMA/ClimaLand.jl/pull/191
• A way to set tolerances and other convergence requirements (max iters, etc)
  • Included by using ClimaTimeSteppers: https://github.com/CliMA/ClimaLand.jl/pull/218/files
• A way to specify Jacobians, and how often to update them; Function to compute Richards model Jacobian (derivation here)
  • Richards equation: https://github.com/CliMA/ClimaLand.jl/pull/190

Inputs

• For Richards equation: https://www.overleaf.com/9252289794ykktrwjxqvcj. We will be implementing modified Picard iterations.
• For full soil equation: TODO need to write out jacobian derivation

Results and deliverables/Validation

• [x] For Richards equation: plots of mass conservation and solution error vs timestep for modified Picard iterations, for constant flux and state BC test runs. Comparison to an explicit solver of the same order - obtain max dt the explicit solver runs at. - in our buildkite
• [x] Richards equation: unit test of Jacobian computed by the code with the analytic expression
• [x] Make sure the above validation results are preserved with new CTS interface
• [x] For full soil model : plots of mass conservation and solution error vs timestep for modified Picard iterations, for constant flux, moisture state BC, and for AtmosDrivenBC. Comparison to an explicit solver of the same order - obtain max dt the explicit solver runs at.
• [x] Unit tests of jacobian
• [x] flexible implementation that allows for LSM models - with many component models - to also have Jacobians specified. Start with soil/canopy model

Initial task breakdown

A preliminary list of PRs and a preliminary timeline of PRs, milestones, and key results.

• [X] Have reviewers review equations (Tapio)
• [X] Add method computing Jacobian for approximate Newton (modified Picard). Make sure A and b update every X timesteps, where X is chosen at the top-most level.
• [x] Simulations with the implicit solver using ClimaTimesteppers. comparison of approx Newton to explicit runs
• [X] State varying boundary conditions treated implicitly
• [x] Implement in general fashion #190 #191 #218
• [x] update to new ClimaTimesteppers interface #528
• [x] Add Jacobian for full soil model; repeat tests #538
• [x] Add Jacobian for an LSM model; repeat tests #538
• [ ] Time dependent BC TBD

Producers

@juliasloan25 (design and implementation) @kmdeck @dennisYatunin (design, implementation support)

Reviewers

Katherine, Dennis - PRs Tapio - SDI review (@tapios)

SDI Changelog

• 4 March 2024: SDI updated for clarity and to more accurately reflect current status (by @juliasloan25)

### step RichardsModel implicitly
- [ ] https://github.com/CliMA/ClimaLand.jl/issues/224
- [ ] https://github.com/CliMA/ClimaLand.jl/issues/268
- [ ] https://github.com/CliMA/ClimaLand.jl/issues/528
- [ ] https://github.com/CliMA/ClimaLand.jl/issues/541
- [ ] https://github.com/CliMA/ClimaLand.jl/issues/647
- [ ] smooth derivative dPsi/dtheta at theta = \nu (if needed)

### step EnergyHydrology implicitly
- [ ] #538
- [ ] #659
- [ ] #660
- [ ] #661
- [ ] #662
- [ ] https://github.com/CliMA/ClimaLand.jl/issues/663
- [ ] include boundary condition contributions (if needed)
- [ ] include contribution from drhoe_int / dtheta_l (if needed)
- [ ] Understand how to treat soil phase change implicitly

### QA
- [ ] write tutorial demonstrating how to use IMEX model