# API

## Initial conditions

### General

`ClimaAtmos.InitialConditions.InitialCondition`

— Type`InitialCondition`

A mechanism for specifying the `LocalState`

of an `AtmosModel`

at every point in the domain. Given some `initial_condition`

, calling `initial_condition(params)`

returns a function of the form `local_state(local_geometry)::LocalState`

.

`ClimaAtmos.InitialConditions.IsothermalProfile`

— Type`IsothermalProfile(; temperature = 300)`

An `InitialCondition`

with a uniform temperature profile.

`ClimaAtmos.InitialConditions.DecayingProfile`

— Type`DecayingProfile(; perturb = true)`

An `InitialCondition`

with a decaying temperature profile, and with an optional perturbation to the temperature.

`ClimaAtmos.InitialConditions.hydrostatic_pressure_profile`

— Function`hydrostatic_pressure_profile(; thermo_params, p_0, [T, θ, q_tot, z_max])`

Solves the initial value problem `p'(z) = -g * ρ(z)`

for all `z ∈ [0, z_max]`

, given `p(0)`

, either `T(z)`

or `θ(z)`

, and optionally also `q_tot(z)`

. If `q_tot(z)`

is not given, it is assumed to be 0. If `z_max`

is not given, it is assumed to be 30 km. Note that `z_max`

should be the maximum elevation to which the specified profiles T(z), θ(z), and/or q_tot(z) are valid.

### Plane / Box

`ClimaAtmos.InitialConditions.AgnesiHProfile`

— Type`AgnesiHProfile(; perturb = false)`

An `InitialCondition`

with a decaying temperature profile

`ClimaAtmos.InitialConditions.ScharProfile`

— Type`ScharProfile(; perturb = false)`

An `InitialCondition`

with a prescribed Brunt-Vaisala Frequency

`ClimaAtmos.InitialConditions.DryDensityCurrentProfile`

— Type`DryDensityCurrentProfile(; perturb = false)`

An `InitialCondition`

with an isothermal background profile, with a negatively buoyant bubble, and with an optional perturbation to the temperature.

`ClimaAtmos.InitialConditions.RisingThermalBubbleProfile`

— Type`RisingThermalBubbleProfile(; perturb = false)`

An `InitialCondition`

with an isothermal background profile, with a positively buoyant bubble, and with an optional perturbation to the temperature.

### Sphere

`ClimaAtmos.InitialConditions.DryBaroclinicWave`

— Type`DryBaroclinicWave(; perturb = true, deep_atmosphere = false)`

An `InitialCondition`

with a dry baroclinic wave, and with an optional perturbation to the horizontal velocity.

`ClimaAtmos.InitialConditions.MoistBaroclinicWaveWithEDMF`

— Type`MoistBaroclinicWaveWithEDMF(; perturb = true, deep_atmosphere = false)`

The same `InitialCondition`

as `MoistBaroclinicWave`

, except with an initial TKE of 0 and an initial draft area fraction of 0.2.

`ClimaAtmos.InitialConditions.MoistAdiabaticProfileEDMFX`

— Type`MoistAdiabaticProfileEDMFX(; perturb = true)`

An `InitialCondition`

with a moist adiabatic temperature profile, and with an optional perturbation to the temperature.

### Cases from literature

`ClimaAtmos.InitialConditions.Nieuwstadt`

— Type`Nieuwstadt`

The `InitialCondition`

described in [7], but with a hydrostatically balanced pressure profile.

`ClimaAtmos.InitialConditions.GABLS`

— Type`GABLS`

The `InitialCondition`

described in [8], but with a hydrostatically balanced pressure profile.

`ClimaAtmos.InitialConditions.GATE_III`

— Type`GATE_III`

The `InitialCondition`

described in [9], but with a hydrostatically balanced pressure profile.

`ClimaAtmos.InitialConditions.ARM_SGP`

— Type`ARM_SGP`

The `InitialCondition`

described in [10], but with a hydrostatically balanced pressure profile.

`ClimaAtmos.InitialConditions.DYCOMS_RF01`

— Type`DYCOMS_RF01`

The `InitialCondition`

described in [11], but with a hydrostatically balanced pressure profile.

`ClimaAtmos.InitialConditions.DYCOMS_RF02`

— Type`DYCOMS_RF02`

The `InitialCondition`

described in [12], but with a hydrostatically balanced pressure profile.

`ClimaAtmos.InitialConditions.Rico`

— Type`Rico`

The `InitialCondition`

described in [13], but with a hydrostatically balanced pressure profile.

`ClimaAtmos.InitialConditions.TRMM_LBA`

— Type`TRMM_LBA`

The `InitialCondition`

described in [14], but with a hydrostatically balanced pressure profile.

`ClimaAtmos.InitialConditions.LifeCycleTan2018`

— Type`LifeCycleTan2018`

The `InitialCondition`

described in [15], but with a hydrostatically balanced pressure profile.

`ClimaAtmos.InitialConditions.Bomex`

— Type`Bomex`

The `InitialCondition`

described in [16], but with a hydrostatically balanced pressure profile.

`ClimaAtmos.InitialConditions.Soares`

— Type`Soares`

The `InitialCondition`

described in [17], but with a hydrostatically balanced pressure profile.

### Implicit Solver

`ClimaAtmos.ImplicitEquationJacobian`

— Type```
ImplicitEquationJacobian(
Y, atmos;
approximate_solve_iters, diffusion_flag, topography_flag, sgs_advection_flag, transform_flag
)
```

A wrapper for the matrix $∂E/∂Y$, where $E(Y)$ is the "error" of the implicit step with the state $Y$.

**Background**

When we use an implicit or split implicit-explicit (IMEX) timestepping scheme, we end up with a nonlinear equation of the form $E(Y) = 0$, where

\[ E(Y) = Y_{imp}(Y) - Y = \hat{Y} + Δt * T_{imp}(Y) - Y.\]

In this expression, $Y_{imp}(Y)$ denotes the state at some time $t + Δt$. This can be expressed as the sum of $\hat{Y}$, the contribution from the state at time $t$ (and possibly also at earlier times, depending on the order of the timestepping scheme), and $Δt * T_{imp}(Y)$, the contribution from the implicit tendency $T_{imp}$ between times $t$ and $t + Δt$. The new state at the end of each implicit step in the timestepping scheme is the value of $Y$ that solves this equation, i.e., the value of $Y$ that is consistent with the state $Y_{imp}(Y)$ predicted by the implicit step.

Note: When we use a higher-order timestepping scheme, the full step $Δt$ is divided into several sub-steps or "stages", where the duration of stage $i$ is $Δt * γ_i$ for some constant $γ_i$ between 0 and 1.

In order to solve this equation using Newton's method, we must specify the derivative $∂E/∂Y$. Since $\hat{Y}$ does not depend on $Y$ (it is only a function of the state at or before time $t$), this derivative is

\[ E'(Y) = Δt * T_{imp}'(Y) - I.\]

In addition, we must specify how to divide $E(Y)$ by this derivative, i.e., how to solve the linear equation

\[ E'(Y) * ΔY = E(Y).\]

Note: This equation comes from assuming that there is some $ΔY$ such that $E(Y - ΔY) = 0$ and making the first-order approximation

\[ E(Y - ΔY) \approx E(Y) - E'(Y) * ΔY.\]

After initializing $Y$ to $Y[0] = \hat{Y}$, Newton's method executes the following steps:

- Compute the derivative $E'(Y[0])$.
- Compute the implicit tendency $T_{imp}(Y[0])$ and use it to get $E(Y[0])$.
- Solve the linear equation $E'(Y[0]) * ΔY[0] = E(Y[0])$ for $ΔY[0]$.
- Update $Y$ to $Y[1] = Y[0] - ΔY[0]$.

If the number of Newton iterations is limited to 1, this new value of $Y$ is taken to be the solution of the implicit equation. Otherwise, this sequence of steps is repeated, i.e., $ΔY[1]$ is computed and used to update $Y$ to $Y[2] = Y[1] - ΔY[1]$, then $ΔY[2]$ is computed and used to update $Y$ to $Y[3] = Y[2] - ΔY[2]$, and so on. The iterative process is terminated either when the error $E(Y)$ is sufficiently close to 0 (according to the convergence condition passed to Newton's method), or when the maximum number of iterations is reached.

**Arguments**

`Y::FieldVector`

: the state of the simulation`atmos::AtmosModel`

: the model configuration`approximate_solve_iters::Int`

: number of iterations to take for the approximate linear solve required when`diffusion_flag = UseDerivative()`

`diffusion_flag::DerivativeFlag`

: whether the derivative of the diffusion tendency with respect to the quantities being diffused should be computed or approximated as 0; must be either`UseDerivative()`

or`IgnoreDerivative()`

instead of a`Bool`

to ensure type-stability`topography_flag::DerivativeFlag`

: whether the derivative of vertical contravariant velocity with respect to horizontal covariant velocity should be computed or approximated as 0; must be either`UseDerivative()`

or`IgnoreDerivative()`

instead of a`Bool`

to ensure type-stability`sgs_advection_flag::DerivativeFlag`

: whether the derivative of the subgrid-scale advection tendency with respect to the updraft quantities should be computed or approximated as 0; must be either`UseDerivative()`

or`IgnoreDerivative()`

instead of a`Bool`

to ensure type-stability`transform_flag::Bool`

: whether the error should be transformed from $E(Y)$ to $E(Y)/Δt$, which is required for non-Rosenbrock timestepping schemes from OrdinaryDiffEq.jl

### Helper

`ClimaAtmos.InitialConditions.ColumnInterpolatableField`

— Type`ColumnInterpolatableField(::Fields.ColumnField)`

A column field object that can be interpolated in the z-coordinate. For example:

```
cif = ColumnInterpolatableField(column_field)
z = 1.0
column_field_at_z = cif(z)
```

This function allocates and is not GPU-compatible so please avoid using this inside `step!`

only use this for initialization.