Inheritance diagram of climlab.convection.EmanuelConvection

A climlab process for the Emanuel convection scheme

class climlab.convection.emanuel_convection.EmanuelConvection(MINORIG=0, ELCRIT=0.0011, TLCRIT=-55.0, ENTP=1.5, SIGD=0.05, SIGS=0.12, OMTRAIN=50.0, OMTSNOW=5.5, COEFFR=1.0, COEFFS=0.8, CU=0.7, BETA=10.0, DTMAX=0.9, ALPHA=0.2, DAMP=0.1, IPBL=0, **kwargs)[source]

Bases: climlab.process.time_dependent_process.TimeDependentProcess

The climlab wrapper for Kerry Emanuel’s moist convection scheme <https://emanuel.mit.edu/FORTRAN-subroutine-convect>

From the documentation distributed with the Fortran 77 code CONVECT:

The subroutine is designed to be used in time-marching models of mesoscale to global-scale dimensions. It is meant to represent the effects of all moist convection, including shallow, non-precipitating cumulus. It also contains a dry adiabatic adjustment scheme.

Since the method of calculating the convective fluxes involves a relaxation toward quasi-equilibrium, subroutine CONVECT must be run for at least several time steps to give meaningful results. At the first time step, the tendencies and convective precipitation will be zero. If the initial sounding is unstable, these will rapidly increase over successive time steps, depending on the values of the constants ALPHA and DAMP. Thus the user interested in convective fluxes and precipitation associated with a single initial sounding (i.e., without large-scale forcing) should still march CONVECT forward enough time steps that the fluxes have returned back to zero; the net tendencies and precipitation integrated over this time interval are then the desired results. But it should be cautioned that these quantities will not necessarily be independent of other model parameters such as the time step. CONVECT is very much built on the philosophy that convection, to the extent it can be represented in terms of large-scale variables, is never very far away from statistical equilibrium with the large-scale flow. To achieve a smooth evolution of the convective forcing, CONVECT should be called at least every 20 minutes during the time integration. CONVECT will work at longer time intervals, but the convective tendencies may become noisy.

Basic characteristics:


  • Ts (surface radiative temperature – optional, and ignored)
  • Tatm (air temperature in K)
  • q (specific humidity in kg/kg)
  • U (zonal velocity in m/s – optional)
  • V (meridional velocity in m/s – optional)

Input arguments and default values (taken from convect43.f fortran source):

  • MINORIG = 0, index of lowest level from which convection may originate (zero means lowest)
  • ELCRIT = 0.0011, autoconversion threshold water content (g/g)
  • TLCRIT = -55.0, critical temperature below which the auto-conversion threshold is assumed to be zero (the autoconversion threshold varies linearly between 0 C and TLCRIT)
  • ENTP = 1.5, coefficient of mixing in the entrainment formulation
  • SIGD = 0.05, fractional area covered by unsaturated downdraft
  • SIGS = 0.12, fraction of precipitation falling outside of cloud
  • OMTRAIN = 50.0, assumed fall speed (Pa/s) of rain
  • OMTSNOW = 5.5, assumed fall speed (Pa/s) of snow
  • COEFFR = 1.0, coefficient governing the rate of evaporation of rain
  • COEFFS = 0.8, coefficient governing the rate of evaporation of snow
  • CU = 0.7, coefficient governing convective momentum transport
  • BETA = 10.0, coefficient used in downdraft velocity scale calculation
  • DTMAX = 0.9, maximum negative temperature perturbation a lifted parcel is allowed to have below its LFC
  • ALPHA = 0.2, first parameter that controls the rate of approach to quasi-equilibrium
  • DAMP = 0.1, second parameter that controls the rate of approach to quasi-equilibrium (DAMP must be less than 1)
  • IPBL = 0, switch to bypass the dry convective adjustment (bypass if IPBL==0)

Tendencies computed:

  • air temperature (K/s)
  • specific humidity (kg/kg/s)
  • optional:
    • U and V wind components (m/s/s), if U and V are included in state dictionary

Diagnostics computed:

  • CBMF (cloud base mass flux in kg/m2/s) – this is actually stored internally and used as input for subsequent timesteps
  • PRECIP (convective precipitation rate in mm/day)

Here is an example of setting up a single-column Radiative-Convective model with interactive water vapor.

This example also demonstrates asynchronous coupling: the radiation uses a longer timestep than the other model components:

import climlab
from climlab import constants as const
# Temperatures in a single column
full_state = climlab.column_state(num_lev=30, water_depth=2.5)
temperature_state = {'Tatm':full_state.Tatm,'Ts':full_state.Ts}
#  Initialize a nearly dry column (small background stratospheric humidity)
q = np.ones_like(full_state.Tatm) * 5.E-6
#  Add specific_humidity to the state dictionary
full_state['q'] = q
#  ASYNCHRONOUS COUPLING -- the radiation uses a much longer timestep
#  The top-level model
model = climlab.TimeDependentProcess(state=full_state,
#  Radiation coupled to water vapor
rad = climlab.radiation.RRTMG(state=temperature_state,
#  Convection scheme -- water vapor is a state variable
conv = climlab.convection.EmanuelConvection(state=full_state,
#  Surface heat flux processes
shf = climlab.surface.SensibleHeatFlux(state=temperature_state, Cd=0.5E-3,
lhf = climlab.surface.LatentHeatFlux(state=full_state, Cd=0.5E-3,
#  Couple all the submodels together
model.add_subprocess('Radiation', rad)
model.add_subprocess('Convection', conv)
model.add_subprocess('SHF', shf)
model.add_subprocess('LHF', lhf)

#  Run the model
#  Check for energy balance
print(model.ASR - model.OLR)

Depth at grid centers (m)


Depth at grid interfaces (m)


Dictionary access to all diagnostic variables


Dictionary access to all input variables


Latitude of grid centers (degrees North)


Latitude of grid interfaces (degrees North)


Pressure levels at grid centers (hPa or mb)


Pressure levels at grid interfaces (hPa or mb)


Longitude of grid centers (degrees)


Longitude of grid interfaces (degrees)


The amount of time over which step_forward() is integrating in unit seconds.


add_diagnostic(name[, value]) Create a new diagnostic variable called name for this process and initialize it with the given value.
add_input(name[, value]) Create a new input variable called name for this process and initialize it with the given value.
add_subprocess(name, proc) Adds a single subprocess to this process.
add_subprocesses(procdict) Adds a dictionary of subproceses to this process.
compute() Computes the tendencies for all state variables given current state and specified input.
compute_diagnostics([num_iter]) Compute all tendencies and diagnostics, but don’t update model state.
declare_diagnostics(diaglist) Add the variable names in inputlist to the list of diagnostics.
declare_input(inputlist) Add the variable names in inputlist to the list of necessary inputs.
integrate_converge([crit, verbose]) Integrates the model until model states are converging.
integrate_days([days, verbose]) Integrates the model forward for a specified number of days.
integrate_years([years, verbose]) Integrates the model by a given number of years.
remove_diagnostic(name) Removes a diagnostic from the process.diagnostic dictionary and also delete the associated process attribute.
remove_subprocess(name[, verbose]) Removes a single subprocess from this process.
set_state(name, value) Sets the variable name to a new state value.
set_timestep([timestep, num_steps_per_year]) Calculates the timestep in unit seconds and calls the setter function of timestep()
step_forward() Updates state variables with computed tendencies.
to_xarray([diagnostics]) Convert process variables to xarray.Dataset format.