# Land Model

## Land Model

`ClimateMachine.Land.LandModel`

— Type`LandModel{PS, S, SF, LBC, SRC, SRCDT, IS} <: BalanceLaw`

A BalanceLaw for land modeling. Users may over-ride prescribed default values for each field.

**Usage**

```
LandModel(
param_set,
soil;
surface,
boundary_conditions,
source,
source_dt,
init_state_prognostic
)
```

**Fields**

`param_set`

Parameter set

`soil`

Soil model

`surface`

Surface Flow model

`boundary_conditions`

struct of boundary conditions

`source`

Source Terms (Problem specific source terms)

`source_dt`

DispatchedTuple of sources

`init_state_prognostic`

Initial Condition (Function to assign initial values of state variables)

## Soil

`ClimateMachine.Land.SoilModel`

— Type`SoilModel{PF, W, H} <: BalanceLaw`

A BalanceLaw for soil modeling. Users may over-ride prescribed default values for each field.

**Usage**

```
SoilModel(
param_functions,
water,
heat,
)
```

**Fields**

`param_functions`

Soil Parameter Functions

`water`

Water model

`heat`

Heat model

`ClimateMachine.Land.SoilWaterModel`

— Type`SoilWaterModel{FT, IF, VF, MF, HM, Fiϑl, Fiθi} <: AbstractWaterModel`

The necessary components for solving the equations for water (liquid or ice) in soil.

Without freeze/thaw source terms added (separately), this model reduces to Richard's equation for liquid water. Note that the default for `θ_i`

is zero. Without freeze/thaw source terms added to both the liquid and ice equations, the default should never be changed, because we do not enforce that the total volumetric water fraction is less than or equal to porosity otherwise.

When freeze/thaw source terms are included, this model encompasses water in both liquid and ice form, and water content is conserved upon phase change.

**Fields**

`impedance_factor`

Impedance Factor - will be 1 or ice dependent

`viscosity_factor`

Viscosity Factor - will be 1 or temperature dependent

`moisture_factor`

Moisture Factor - will be 1 or moisture dependent

`hydraulics`

Hydraulics Model - used in matric potential and moisture factor of hydraulic conductivity

`initialϑ_l`

Initial condition: augmented liquid fraction

`initialθ_i`

Initial condition: volumetric ice fraction

`ClimateMachine.Land.PrescribedWaterModel`

— Type`PrescribedWaterModel{F1, F2} <: AbstractWaterModel`

Model structure for a prescribed water content model.

The user supplies functions of space and time for both `ϑ_l`

and `θ_i`

. No auxiliary or state variables are added, no PDE is solved. The defaults are no moisture anywhere, for all time.

**Fields**

`ϑ_l`

Augmented liquid fraction

`θ_i`

Volumetric fraction of ice

`ClimateMachine.Land.SoilHeatModel`

— Type`SoilHeatModel{FT, FiT} <: AbstractHeatModel`

The necessary components for the Heat Equation in a soil water matrix.

**Fields**

`initialT`

Initial conditions for temperature

`ClimateMachine.Land.PrescribedTemperatureModel`

— Type`PrescribedTemperatureModel{F1} <: AbstractHeatModel`

Model structure for a prescribed temperature model.

`ClimateMachine.Land.SoilWaterParameterizations`

— Module`SoilWaterParameterizations`

van Genuchten, Brooks and Corey, and Haverkamp parameters for and formulation of

- hydraulic conductivity
- matric potential

Hydraulic conductivity can be chosen to be dependent or independent of impedance, viscosity and moisture.

Functions for hydraulic head, effective saturation, pressure head, matric potential, and the relationship between augmented liquid fraction and liquid fraction are also included.

`ClimateMachine.Land.SoilHeatParameterizations`

— Module`SoilHeatParameterizations`

Functions for volumetric heat capacity, temperature as a function of volumetric internal energy, saturated thermal conductivity, thermal conductivity, relative saturation and the Kersten number are included. Heat capacities denoted by `ρc_`

are volumetric, while `cp_`

denotes an isobaric specific heat capacity.

`ClimateMachine.Land.SoilParamFunctions`

— Type```
SoilParamFunctions{FT, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, WP}
<: AbstractSoilParameterFunctions{FT}
```

Necessary parameters for the soil model. Heat parameters to be moved to their own structure in next iteration.

**Fields**

`porosity`

Aggregate porosity of the soil

`ν_ss_gravel`

Volume fraction of gravels, relative to soil solids only; unitless.

`ν_ss_om`

Volume fraction of SOM, relative to soil solids only; unitless.

`ν_ss_quartz`

Volume fraction of quartz, relative to soil solids only; unitless.

`ρc_ds`

Bulk volumetric heat capacity of dry soil. Units of J m-3 K-1.

`ρp`

Particle density for soil solids. Units of kg m-3

`κ_solid`

Thermal conductivity of the soil solids. Units of W m-1 K-1.

`κ_sat_unfrozen`

Saturated thermal conductivity for unfrozen soil. Units of W m-1 K-1.

`κ_sat_frozen`

Saturated thermal conductivity for frozen soil. Units of W m-1 K-1.

`a`

Adjustable scale parameter for determining Kersten number in the Balland and Arp formulation; unitless.

`b`

Adjustable scale parameter for determining Kersten number in the Balland and Arp formulation; unitless.

`κ_dry_parameter`

Parameter used in the Balland and Arp formulation for κ_dry; unitless

`water`

Hydrology parameter functions

`ClimateMachine.Land.WaterParamFunctions`

— Type`WaterParamFunctions{FT, TK, TS, TR} <: AbstractSoilParameterFunctions{FT}`

Necessary parameters for the soil water model. These can be floating point parameters or functions of space (via the auxiliary variable `aux`

). Internally, they will be converted to type FT or altered so that the functions return type FT.

This is not a complete list - the hydraulic parameters necessary for specifying the van Genuchten or Brooks and Corey functions are stored in the hydraulics model.

**Fields**

`Ksat`

Saturated conductivity. Units of m s-1.

`S_s`

Specific storage. Units of m s-1.

`θ_r`

Residual Water Fraction - default is zero; unitless.

`ClimateMachine.Land.get_water_content`

— Function```
get_water_content(
water::SoilWaterModel,
aux::Vars,
state::Vars,
t::Real
)
```

Return the moisture variables for the balance law soil water model.

```
get_water_content(
water::PrescribedWaterModel,
aux::Vars,
state::Vars,
t::Real
)
```

Return the moisture variables for the prescribed soil water model.

`ClimateMachine.Land.get_temperature`

— Function```
get_temperature(
heat::SoilHeatModel
aux::Vars,
t::Real
)
```

Returns the temperature when the heat model chosen is the dynamical SoilHeatModel. This is necessary for fully coupling heat and water.

```
get_temperature(
heat::PrescribedTemperatureModel,
aux::Vars,
t::Real
)
```

Returns the temperature when the heat model chosen is a user prescribed one. This is useful for driving Richard's equation without a back reaction on temperature.

`ClimateMachine.Land.PhaseChange`

— Type`PhaseChange <: TendencyDef{Source}`

The function which computes the freeze/thaw source term for Richard's equation.

## Boundary Conditions

`ClimateMachine.Land.LandDomainBC`

— Type`LandDomainBC{TBC, BBC, LBC}`

A container for the land boundary conditions, with options for surface boundary conditions, bottom boundary conditions, or lateral face boundary conditions.

The user should supply an instance of `LandComponentBC`

for each piece, as needed. If none is supplied, the default for is `NoBC`

for each subcomponent. At a minimum, both top and bottom boundary conditions should be supplied. Whether or not to include the lateral faces depends on the configuration of the domain.

`ClimateMachine.Land.LandComponentBC`

— Type`LandComponentBC{SW, SH, SF}`

An object that holds the boundary conditions for each of the subcomponents of the land model.

The boundary conditions supplied should be of type `AbstractBoundaryConditions`

. The default is `NoBC`

for each component, so that the user only needs to define the BC for the components they wish to model.

`ClimateMachine.Land.NoBC`

— Type`NoBC <: AbstractBoundaryConditions`

This type is used for dispatch when no boundary condition needs to be enforced - for example, if no prognostic variables are included for a subcomponent, or for lateral faces when a 1D vertical setup is used.

`ClimateMachine.Land.SurfaceDrivenWaterBoundaryConditions`

— Type`SurfaceDrivenWaterBoundaryConditions{FT, PD, RD} <: AbstractBoundaryConditions`

Boundary condition type to be used when the user wishes to apply physical fluxes of water at the top of the domain, normal to the surface. The flux can be inwards or outwards, depending on the magnitude of infiltration, evaporation, and precipitation.

Precipitation is assumed to be in the ẑ direction, P⃗ = Pẑ, while evaporation is along the normal direction, E⃗ = En̂. The applied boundary flux is F⃗ = f n̂, and the magnitude f is determined internally from P⃗, E⃗, and soil conditions.

**Fields**

`precip_model`

Precipitation model

`runoff_model`

Runoff model

`ClimateMachine.Land.SurfaceDrivenHeatBoundaryConditions`

— Type`SurfaceDrivenHeatBoundaryConditions{FT, SWD} <: AbstractBoundaryConditions`

Boundary condition type to be used when the user wishes to apply normal fluxes of heat at the top of the domain (according to radiative energy fluxes).

**Fields**

`nswf_model`

Net short wave flux model

`ClimateMachine.Land.Dirichlet`

— Type`Dirichlet{Fs} <: AbstractBoundaryConditions`

A concrete type to hold the state variable function, if Dirichlet boundary conditions are desired.

**Fields**

`state_bc`

state boundary condition

`ClimateMachine.Land.Neumann`

— Type`Neumann{Ff} <: AbstractBoundaryConditions`

A concrete type for specifying the magnitude of an inward diffusive flux, normal to the domain boundary, from which a Neumann boundary condition is determined and applied.

For the soil water model, the Darcy flux is defined as F⃗(Darcy) = -K∇h. With the `Neumann`

boundary condition type, the user supplies a scalar `f`

such that the applied flux boundary conditon is F⃗(Darcy, boundary) = -f n̂, where n̂ is the normal vector pointing out of the domain. For the soil heat model, the same rule applies, except now we have a conductive heat flux F⃗(Conductive, boundary) = -κ∇T = -f n̂.

**Fields**

`scalar_flux_bc`

Scalar flux boundary condition