Bulk

class abcmodel.atmos.mixed_layer.bulk.BulkState(h_abl, theta, deltatheta, q, dq, co2, deltaCO2, wCO2, u, du, v, dv, dz_h, surf_pressure, wstar=<factory>, we=<factory>, thetav=<factory>, deltathetav=<factory>, wthetav=<factory>, wqe=<factory>, wCO2e=<factory>, wthetae=<factory>, wthetave=<factory>, lcl=<factory>, top_rh=<factory>, top_p=<factory>, top_T=<factory>, utend=<factory>, dutend=<factory>, vtend=<factory>, dvtend=<factory>, h_abl_tend=<factory>, thetatend=<factory>, deltathetatend=<factory>, qtend=<factory>, dqtend=<factory>, co2tend=<factory>, deltaCO2tend=<factory>, dztend=<factory>, ws=<factory>, wf=<factory>)

Bases: AbstractMixedLayerState

Data class for bulk mixed layer model state.

h_abl: Array

Initial atmospheric boundary layer (ABL) height [m].

theta: Array

Initial mixed-layer potential temperature [K].

deltatheta: Array

Initial temperature jump at the top of the ABL [K].

q: Array

Initial mixed-layer specific humidity [kg/kg].

dq: Array

Initial specific humidity jump at h [kg/kg].

co2: Array

Initial mixed-layer CO2 [ppm].

deltaCO2: Array

Initial CO2 jump at the top of the ABL [ppm].

wCO2: Array

Surface kinematic CO2 flux [mgC/m²/s].

u: Array

Initial mixed-layer u-wind speed [m/s].

du: Array

Initial u-wind jump at the top of the ABL [m/s].

v: Array

Initial mixed-layer v-wind speed [m/s].

dv: Array

Initial v-wind jump at the top of the ABL [m/s].

dz_h: Array

Transition layer thickness [m].

surf_pressure: Array

Surface pressure, which is actually not updated (not a state), it’s only here for simplicity [Pa].

wstar: Array

Convective velocity scale [m s-1].

we: Array

Entrainment velocity [m s-1].

thetav: Array

Mixed-layer potential temperature [K].

deltathetav: Array

Virtual temperature jump at the top of the ABL [K].

wthetav: Array

Surface kinematic virtual heat flux [K m s-1].

wqe: Array

Entrainment moisture flux [kg kg-1 m s-1].

wCO2e: Array

Entrainment CO2 flux [mgC/m²/s].

wthetae: Array

Entrainment potential temperature flux [K m s-1].

wthetave: Array

Entrainment virtual heat flux [K m s-1].

lcl: Array

Lifting condensation level [m].

top_rh: Array

Top of mixed layer relative humidity [%].

top_p: Array

Pressure at top of mixed layer [Pa].

top_T: Array

Temperature at top of mixed layer [K].

utend: Array

Zonal wind velocity tendency [m s-2].

dutend: Array

Zonal wind velocity tendency at the ABL height [m s-2].

vtend: Array

Meridional wind velocity tendency [m s-2].

dvtend: Array

Meridional wind velocity tendency at the ABL height [m/s²].

h_abl_tend: Array

Tendency of CBL [m s-1].

thetatend: Array

Tendency of mixed-layer potential temperature [K s-1].

deltathetatend: Array

Tendency of mixed-layer potential temperature at the ABL height [K s-1].

qtend: Array

Tendency of mixed-layer specific humidity [kg/kg s-1].

dqtend: Array

Tendency of mixed-layer specific humidity at the ABL height [kg/kg s-1].

co2tend: Array

Tendency of CO2 concentration [ppm s-1].

deltaCO2tend: Array

Tendency of CO2 concentration at the ABL height [ppm s-1].

dztend: Array

Tendency of transition layer thickness [m s-1].

ws: Array

Large-scale vertical velocity (subsidence) [m s-1].

wf: Array

Mixed-layer growth due to cloud top radiative divergence [m s-1].

class abcmodel.atmos.mixed_layer.bulk.BulkModel(divU=0.0, coriolis_param=0.0001, gammatheta=0.006, advtheta=0.0, beta=0.2, gammaq=0.0, advq=0.0, gammaCO2=0.0, advCO2=0.0, gammau=0.0, advu=0.0, gammav=0.0, advv=0.0, dFz=0.0, is_shear_growing=True, is_fix_free_trop=True, is_wind_prog=True)

Bases: AbstractMixedLayerModel[BulkState]

Bulk mixed layer model with full atmospheric boundary layer dynamics.

Complete mixed layer model that simulates atmospheric boundary layer evolution including entrainment, subsidence, cloud effects, and wind dynamics.

Parameters:

• divU (float) – horizontal large-scale divergence of wind [s-1]. Default is 0.0.

• coriolis_param (float) – Coriolis parameter [s-1]. Default is 1e-4.

• gammatheta (float) – free atmos potential temperature lapse rate [K m-1]. Default is 0.006.

• advtheta (float) – advection of heat [K s-1]. Default is 0.0.

• beta (float) – entrainment ratio for virtual heat [-]. Default is 0.2.

• gammaq (float) – free atmos specific humidity lapse rate [kg/kg m-1]. Default is 0.0.

• advq (float) – advection of moisture [kg/kg s-1]. Default is 0.0.

• gammaCO2 (float) – free atmos CO2 lapse rate [ppm m-1]. Default is 0.0.

• advCO2 (float) – advection of CO2 [ppm s-1]. Default is 0.0.

• gammau (float) – free atmos u-wind speed lapse rate [s-1]. Default is 0.0.

• advu (float) – advection of u-wind [m s-2]. Default is 0.0.

• gammav (float) – free atmos v-wind speed lapse rate [s-1]. Default is 0.0.

• advv (float) – advection of v-wind [m s-2]. Default is 0.0.

• dFz (float) – cloud top radiative divergence [W m-2]. Default is 0.0.

• is_shear_growing (bool) – shear growth mixed-layer switch. Default is True.

• is_fix_free_trop (bool) – fix the free-troposphere switch. Default is True.

• is_wind_prog (bool) – prognostic wind switch. Default is True.

init_state(h_abl=200.0, theta=288.0, deltatheta=1.0, q=0.008, dq=-0.001, co2=422.0, deltaCO2=-44.0, wCO2=0.0, u=6.0, du=4.0, v=-4.0, dv=4.0, dz_h=150.0, surf_pressure=101300.0)

Initialize the model state.

Parameters:

• h_abl (float) – atmospheric boundary layer height [m]. Default is 200.0.

• theta (float) – mixed-layer potential temperature [K]. Default is 288.0.

• deltatheta (float) – potential temperature jump at h [K]. Default is 1.0.

• q (float) – mixed-layer specific humidity [kg/kg]. Default is 0.008.

• dq (float) – specific humidity jump at h [kg/kg]. Default is -0.001.

• co2 (float) – mixed-layer CO2 [ppm]. Default is 422.0.

• deltaCO2 (float) – CO2 jump at h [ppm]. Default is -44.0.

• wCO2 (float) – surface kinematic CO2 flux [mgC/m²/s]. Default is 0.0.

• u (float) – mixed-layer u-wind speed [m/s]. Default is 6.0.

• du (float) – u-wind jump at h [m/s]. Default is 4.0.

• v (float) – mixed-layer v-wind speed [m/s]. Default is -4.0.

• dv (float) – v-wind jump at h [m/s]. Default is 4.0.

• dz_h (float) – transition layer thickness [m]. Default is 150.0.

• surf_pressure (float) – surface pressure [Pa]. Default is 101300.0.

Returns:

The initial mixed layer state.

run(state)

Run the model.

Parameters:

state (AbstractCoupledState)

Returns:

The updated mixed layer state.

integrate(state, dt)

Integrate mixed layer forward in time.

Parameters:

• state (BulkState) – BulkMixedLayerState (component state, not CoupledState).

• dt (float) – Time step.

compute_ws(h_abl)

Compute the large-scale subsidence velocity as

\[w_s = -\text{div}U \cdot h,\]

where \(\text{div}U\) is the horizontal large-scale divergence of wind and \(h\) is the ABL height.

compute_wf(deltatheta)

Compute the mixed-layer growth due to cloud top radiative divergence as

\[w_f = \frac{\Delta F_z}{\rho c_p \Delta \theta},\]

where \(\Delta F_z\) is the cloud top radiative divergence, \(\rho\) is air density, \(c_p\) is specific heat capacity, and \(\Delta \theta\) is the temperature jump at the top of the ABL.

compute_w_th_ft(ws)

Compute the potential temperature compensation term to fix free troposphere values as

\[w_{\theta,ft} = \gamma_\theta w_s,\]

where \(\gamma_\theta\) is the potential temperature compensation factor and \(w_s\) comes from compute_ws(). This is used in case we are fixing the free troposhere.

compute_w_q_ft(ws)

Compute humidity compensation term to fix free troposphere values as

\[w_{q,ft} = \gamma_q w_s,\]

where \(\gamma_q\) is the humidity compensation factor and \(w_s\) comes from compute_ws(). This is used in case we are fixing the free troposhere.

compute_w_CO2_ft(ws)

Compute CO2 compensation term to fix free troposphere values as

\[w_{CO2,ft} = \gamma_{CO2} w_s,\]

where \(\gamma_{CO2}\) is the CO2 compensation factor and \(w_s\) comes from compute_ws(). This is used in case we are fixing the free troposhere.

compute_wstar(h_abl, wthetav, thetav, g)

Compute the convective velocity scale, defined by

\[w_* = \left( \frac{g h (\overline{w'\theta_v'})_s}{\theta_v} \right)^{1/3},\]

where \(g\) is the gravity acceleration, \(h\) is the height of the atmospheric boundary layer, \((\overline{w'\theta_v'})_s\) is the virtual heat flux at the surface and \(\theta_v\) is the virtual potential temperature.

compute_wthetave(wthetav)

Compute the entrainment virtual heat flux as

\[(\overline{w'\theta_v'})_e = -\beta (\overline{w'\theta_v'})_s,\]

where \(\beta\) is the entrainment coefficient and \((\overline{w'\theta_v'})_s\) is the virtual heat flux at the surface.

compute_we(h_abl, wthetave, deltathetav, thetav, ustar, g)

Compute the entrainment velocity as

\[w_e = -\frac{(\overline{w'\theta_v'})_e}{\Delta \theta_v},\]

where \((\overline{w'\theta_v'})_e\) is the entrainment virtual heat flux and \(\Delta \theta_v\) is the virtual potential temperature jump at the top of the ABL.

If shear effects are included (is_shear_growing=True), an additional term is added

\[w_e = \frac{-\overline{w'\theta_v'}_e + 5 u_*^3 \theta_v / (g h)}{\Delta \theta_v},\]

where \(u_*\) is the friction velocity, and \(\theta_v\) is the virtual potential temperature, \(g\) is gravity acceleration, and \(h\) is the height of the ABL.

compute_wthetae(we, deltatheta)

Compute the entrainment heat flux as

\[(\overline{w'\theta'})_e = -w_e \Delta \theta,\]

where \(w_e\) is the entrainment velocity and \(\Delta \theta\) is the potential temperature jump at the top of the ABL.

compute_wqe(we, dq)

Compute the entrainment moisture flux as

\[(\overline{w'q'})_e = -w_e \Delta q,\]

where \(w_e\) is the entrainment velocity and \(\Delta q\) is the moisture jump at the top of the ABL.

compute_wCO2e(we, deltaCO2)

Compute the entrainment CO2 flux as

\[(\overline{w'CO_2'})_e = -w_e \Delta CO_2,\]

where \(w_e\) is the entrainment velocity and \(\Delta CO_2\) is the CO2 jump at the top of the ABL.

compute_h_abl_tend(we, ws, wf, cc_mf)

Compute the boundary layer height tendency as

\[\frac{\text{d}h}{\text{d}t} = w_e + w_s + w_f - \text{cc}_{mf},\]

where

• \(w_e\) comes from compute_we(),

• \(w_s\) comes from compute_ws(),

• \(w_f\) comes from compute_wf(),

and \(\text{cc}_{mf}\) is the cloud core mass flux from the cloud model.

compute_thetatend(h_abl, wtheta, wthetae)

Compute the mixed-layer potential temperature tendency as

\[\frac{\text{d}\theta}{\text{d}t} = \frac{(\overline{w'\theta'})_s - (\overline{w'\theta'})_e}{h} + \text{adv}_\theta,\]

where \(\overline{w'\theta'}_s\) is the surface potential temperature flux, \(\overline{w'\theta'}_e\) is the entrainment potential temperature flux, and \(\text{adv}_\theta\) is the potential temperature advection.

compute_deltathetatend(we, wf, cc_mf, thetatend, w_th_ft)

Compute the potential temperature jump at the top of the ABL tendency as

\[\frac{\text{d}\Delta \theta}{\text{d}t} = \gamma_\theta (w_e + w_f - \text{cc}_{mf}) - \frac{\text{d}\theta}{\text{d}t} + w_{\theta,ft},\]

where

compute_qtend(h_abl, wq, wqe, cc_qf)

Compute the mixed-layer specific humidity tendency as

\[\frac{\text{d}q}{\text{d}t} = \frac{\overline{w'q'}_s - \overline{w'q'}_e - \text{cc}_{qf}}{h} + \text{adv}_q\]

compute_dqtend(we, wf, cc_mf, qtend, w_q_ft)

Compute the specific humidity jump at the top of the ABL tendency as

\[\frac{\text{d}\Delta q}{\text{d}t} = \gamma_q (w_e + w_f - \text{cc}_{mf}) - \frac{\text{d}q}{\text{d}t} + w_{q,ft}\]

compute_co2tend(h_abl, wCO2, wCO2e, wCO2M)

Compute the mixed-layer CO2 tendency as

\[\frac{\text{d}CO_2}{\text{d}t} = \frac{\overline{w'CO_2'}_s - \overline{w'CO_2'}_e - \text{cc}_{CO2f}}{h} + \text{adv}_{CO2}\]

compute_deltaCO2tend(we, wf, cc_mf, co2tend, w_CO2_ft)

Compute the CO2 jump at the top of the ABL tendency as

\[\frac{\text{d}\Delta CO_2}{\text{d}t} = \gamma_{CO2} (w_e + w_f - \text{cc}_{mf}) - \frac{\text{d}CO_2}{\text{d}t} + w_{CO2,ft}\]

compute_utend(h_abl, we, uw, du, dv)

Compute the zonal wind tendency as

\[\frac{\text{d}u}{\text{d}t} = -f_c \Delta v + \frac{\overline{u'w'}_s + w_e \Delta u}{h} + \text{adv}_u\]

compute_vtend(h_abl, we, vw, du, dv)

Compute the meridional wind tendency as

\[\frac{\text{d}v}{\text{d}t} = f_c \Delta u + \frac{\overline{v'w'}_s + w_e \Delta v}{h} + \text{adv}_v\]

compute_dutend(we, wf, cc_mf, utend)

Compute zonal wind jump at the top of the ABL tendency as

\[\frac{\text{d}\Delta u}{\text{d}t} = \gamma_u (w_e + w_f - \text{cc}_{mf}) - \frac{\text{d}u}{\text{d}t}\]

compute_dvtend(we, wf, cc_mf, vtend)

Compute meridional wind jump at the top of the ABL tendency as

\[\frac{\text{d}\Delta v}{\text{d}t} = \gamma_v (w_e + w_f - \text{cc}_{mf}) - \frac{\text{d}v}{\text{d}t}\]

compute_dztend(lcl, h_abl, cc_frac, dz_h)

Compute the transition layer thickness tendency as

\[\frac{\text{d}\delta z_h}{\text{d}t} = \frac{(LCL - h) - \delta z_h}{\tau}\]

where \(\tau = 7200\) s. This is basically a relaxation term.

statistics(state, t)

Compute standard meteorological statistics and diagnostics.

compute_thetav(theta, q)

Computes the virtual potential temperature as

\[\theta_v = \theta \left(1 + 0.61\, q\right).\]

compute_wthetav(wtheta, theta, wq)

Computes the virtual potential temperature flux as

\[\overline{w'\theta_v'} = \overline{w'\theta'} + 0.61\,\theta\,\overline{w'q'}.\]

compute_deltathetav(theta, deltatheta, q, dq)

Computes the virtual potential temperature jump as

\[\Delta\theta_v = (\theta + \Delta\theta)\left(1 + 0.61\,(q + \Delta q)\right) - \theta\left(1 + 0.61\,q\right)\]

compute_top_p(surf_pressure, rho, g, h_abl)

Computes the pressure at the top of the mixed layer as

\[p_{top} = p_{surf} - \rho\, g\, h.\]

compute_top_T(theta, g, cp, h_abl)

Computes the temperature at the top of the mixed layer as

\[T_{top} = \theta - \frac{g}{c_p}\, h.\]

compute_top_rh(q, top_T, top_p)

Computes the relative humidity at the mixed-layer top as

\[\mathrm{RH}_{top} = \frac{q}{q_{sat}(T_{top},\,p_{top})}.\]

compute_lcl(h_abl, lcl, surf_pressure, theta, q, t)

Compute the lifting condensation level (LCL).

The LCL is found iteratively by finding the height where the relative humidity is 100%.