ATMOSPHERE OCEAN INTERACTIONS :: PYTHON NOTES

4. Simple Climate Modeling in Python (CliMT)

J. S. Wright
jswright@tsinghua.edu.cn

4.1 T HE CliMT MODULE

Our focus this week is on the CliMT module, which includes a number of useful atmospheric
utilities and allows us to construct basic climate models in python. The code for the CliMT
module includes a number of instructive examples of more advanced topics in python devel-
opment, including classes and the f2py wrapper for using fortran codes in python. We will
not discuss these in any detail, but feel free to download and deconstruct the module to get
some ideas. Classes in particular are a good way to extend the usefulness of your modules. You
can also check the documentation web page, although it currently doesnt have a great deal of
information beyond installation instructions and a handful of example codes. Once installed,
you can import CliMT in the usual way:

In [1]: import climt

Using netCDF4 interface for IO

4.1.1 ATMOSPHERIC THERMODYNAMICS

One of the most useful features of CliMT, which does not require using its climate mod-
eling capabilities, is the utilities it provides for atmospheric thermodynamics. These util-
ities are included in the submodule climt.thermodyn, and are based on a variety of at-
mospheric thermodynamics textbooks and published papers. Utilities include two basic
functions for the saturation vapor pressure given temperature (climt.thermodyn.es(T) and
climt.thermodyn.esflatau(T,i), where passing i=1 returns saturation over liquid water
and passing i=2 returns saturation over ice), as well as versions of both that return satu-
ration specific humidity (climt.thermodyn.qs(T, p, Rd=none, Rv=none)), water vapor
mass mixing ratio (climt.thermodyn.ws(T, p, Rd=none, Rv=none)), or relative humidity

1
(climt.thermodyn.relhum(p, T, q)). You can also use climt.thermodyn to calculate the
dewpoint temperature given pressure and specific humidity (in g kg1 ):

In [2]: climt.thermodyn.tdew(1000,10)
Out[2]: array(287.15669785364497)

or the temperature of the lifting condensation level given temperature, pressure, and specific
humidity:

In [3]: climt.thermodyn.tstar(300,1000,10)
Out[3]: array(284.2753528809979)

Other options include the potential temperature (with optional specific humidity for m ):

In [4]: climt.thermodyn.theta(255,500)
Out[4]: array(310.8877264162649)
In [5]: climt.thermodyn.qs(255,500)
Out[5]: array(1.831796780431086)
In [6]: climt.thermodyn.theta(255,500,q=1.5)
Out[6]: array(310.86421481582624)

and the equivalent potential temperature (with optional total water for ):

In [7]: climt.thermodyn.thetae(255,500)
Out[7]: array(316.35091654058607)
In [8]: climt.thermodyn.thetae(255,500,wt=2)
Out[8]: array(316.3043900724348)
In [9]: climt.thermodyn.thetae(255,500,wt=1.5)
Out[9]: array(315.3779330284849)

where the first value is assumed to be saturated but hold no condensate (equivalent to the
saturation equivalent potential temperature climt.thermodyn.thetaes(T, p)) and the
last value is calculated at the lifting condensation level (because the total water is less than
the saturation mixing ratio). The climt.thermodyn module also includes more complex
utilities, including functions for calculating pressure or temperature profiles along a dry adi-
abat (climt.thermodyn.pdryadiab() or climt.thermodyn.tdryadiab()), or the temper-
ature profile along a moist adiabat (climt.thermodyn.tmoistadiab()) or pseudoadiabat
(climt.thermodyn.pseudoadiab()). I have found the functions to calculate convective
available potential energy (CAPE) and convective inhibition energy (CINE), which are quite
challenging to program on ones own, particularly useful in my own work (although it is impor-
tant to keep in mind that methods used for calculating these quantities vary, and you must
be careful to be sure that the methods are compatible when making comparisons). CliMT
even includes a utility to plot a skew-T diagram using measured temperature and humidity
profiles (Fig. 4.1), as shown in the following script (which reads in and plots profiles measured
by launching a balloonsonde near Lhasa):

2
 100

200
Pressure [hPa]

300

400

500

600
700
800
900
1000
30 20 10 0 10 20 30 40
Temperature [C]

Figure 4.1: A skew-T diagram showing a temperature profile from Lhasa

3
  
1 import numpy as np
2 import matplotlib . pyplot as plt
3 import climt
4 import csv
5
6 # read in measured profiles from Lhasa (26 May 2012)
7 infile = profile . csv
8 Tmeas = []; pmeas = []; rmeas = []
9 with open ( infile , rb ) as csvfile :
10 reader = csv . reader ( csvfile )
11 # skip header lines
12 f o r ii i n r a n g e (2) : reader . n e x t ()
13 f o r row i n reader :
14 row = np . array ( row ) . astype ( float )
15 pmeas . append ( row [0]) # p [hPa]
16 Tmeas . append ( row [2]+273.16) # T [K]
17 rmeas . append ( row [7]*0.01) # RH [fraction]
18 Tmeas = np . array ( Tmeas )
19 pmeas = np . array ( pmeas )
20 rmeas = np . array ( rmeas )
21 # estimate specific humidity from RH and saturation SH
22 qmeas = rmeas * climt . thermodyn . qs ( Tmeas , pmeas )
23 # calculate dewpoint temperature from T and q
24 Tdew = climt . thermodyn . tdew ( Tmeas , qmeas )
25
26 # plot skewT diagram
27 climt . thermodyn . skewT ( pmeas , Tmeas -273.16 , Tdew -273.16)
28 plt . savefig ( ../ figs / skewT . png , bbox_inches = tight )
 

4.1.2 R ADIATION SCHEMES

The first CliMT class we will discuss is the radiation class. As usual, we can find out about
this class using the help() command, which lists the available input parameters:

In[10]: help(climt.radiation)
| Interface to atmospheric radiation schemes.
|
| * Instantiation:
|
| x=climt.radiation( <args> )
|
| where <args> are the following OPTIONAL arguments:
| Name Dims Meaning Units Default Notes
| scheme 0 Radiative scheme (string) cam3
| do_sw 0 Shortwave switch (integer) 1
| do_lw 0 Longwave switch (integer) 1
| scon 0 Solar constant W m-2 1367.
| orb_yr 0 Orbital year (integer) 1995

4
 | avg 0 Insolation average (string) daily
| co2 0 CO2 ppmv 330.
| n2o 0 N2O ppmv 0.
| ch4 0 CH4 ppmv 0.
| cfc11 0 CFC11 ppmv 0.
| cfc12 0 CFC12 ppmv 0.
| cfc22 0 CFC22 ppmv 0. Chou
| tauvis 0 Aerosol opt. depth (float) 0. CCM3
| tau_inf 0 Total opt. depth - 1. Greygas
| alpha_greygas 0 Tau shape parameter - 1. Greygas
| calday 0 Calendar day (float) 80.5
| lat 0-1 Latitude dgr 0.
| lon 0-1 Longitude dgr 0.
| solin 0-2 Insolation W/m2 417.4
| zen 0-2 Solar zenith angle dgr 72.2
| Ts 0-2 Surface temperature K 283.15
| ps 0-2 Surface pressure mb 1000.
| aldif 0-2 Diffuse IR albedo (frac) 0.07
| aldir 0-2 Direct IR albedo (frac) 0.07
| asdif 0-2 Diffuse UV+vis alb (frac) 0.07
| asdir 0-2 Direct UV+vis alb (frac) 0.07
| p 1-3 Atmospheric pressure mb
| T 1-3 Temperature K 283.15 Isothermal
| q 1-3 Specific humidity g/kg 1.e-5
| o3 1-3 Ozone mass mix. rat. kg/kg
| cldf 1-3 Cloud fraction frac 0.
| r_liq 1-3 Drop radius, liquid micron 10.
| r_ice 1-3 Drop radius, ice micron 30.
| clwp 1-3 Cloud liquid water path g/m2 0.
| ciwp 1-3 Cloud ice water path g/m2 -99. CAM3
| in_cld 0 Cloud water path flag - 0 CAM3
| flus 1-3 Upwelling LW at surface W/m2 -99. CAM3

usage:

| * Usage:
| Call instance directly to compute radiative fluxes and heating rates:
|
| x( <args> )
|
| where <args> are as above.

and output variables for the radiation class:

| * Output (accessible as x[swhr] etc.):

5
 | Name Meaning Units
| - Heating rates:
| swhr SW heating rate K day-1
| lwhr LW heating rate K day-1
| - Radiative fluxes
| swflx Net SW radiative flux W m-2
| lwflx Net LW radiative flux W m-2
| SwToa Top-of-atmos SW rad flux W m-2
| LwToa Top-of-atmos LW rad flux W m-2
| SwSrf Surface SW rad flux W m-2
| LwSrf Surface LW rad flux W m-2
| - Cloud forcing
| SwToaCf SW cloud forc, top of atmos W m-2
| SwSrfCf SW cloud forc, surface W m-2
| LwToaCf LW cloud forc, top of atmos W m-2
| LwSrfCf LW cloud forc, surface W m-2

Several schemes are available, including the CAM3 (the default scheme; scheme=cam3),
CCM3 (scheme=ccm3), CLIRAD (scheme=chou), RRTM (scheme=rrtm), and grey gas
(scheme=gray) radiation models. The CAM3 (Community Atmosphere Model version 3)
is a well-known atmospheric model developed in the early 2000s. Its radiation scheme is
described in the online documentation of the model formulation. The CCM3 (Community
Climate Model version 3) is a slightly older version of CAM3, but can be used if you find
that the CAM3 radiation scheme is unstable on your system. The chou radiation scheme
is a wrapper for the CLIRAD radiation scheme used in some versions of the NASA GEOS-5
(Goddard Earth Observing System version 5) model and data assimilation system, including
those used to generate the MERRA (Modern Era Retrospective-analysis for Research and
Applications) and MERRA-2 reanalyses. Online documentation is available for the shortwave
and longwave portions of this scheme. The RRTM (Rapid Radiative Transfer model) has
been developed by Atmospheric and Environmental Research, and has extensive online
documentation. Versions of RRTM are used in the ECMWF Integrated Forecast Model (IFS),
the NCEP Global Forecast System (GFS) and Climate Forecast System (CFS) models, the
CMA Global/Regional Assimilation and Prediction System (GRAPES), and a variety of climate
models. All of these radiation schemes account for variations in absorption and emission
by wavelength. The grey gas model is an exception, in which emission and absorption are
functions of pressure alone. You can think of this scheme as a modification of black body
radiation to account for imperfect absorption and emission. The grey gas scheme only includes
interaction with longwave radiation there is no absorption or scattering of solar radiation
by the grey atmosphere.
We can instantiate (create an instance of ) a radiation model simply by typing:

In[11]: rad = climt.radiation()

This will instantiate a cam3 radiation scheme, and assign default values to all of the inputs
listed above. Perhaps we feel that the default CO2 concentration (330 ppmv) is too low, and we

6
want to make it more consistent with current values (400 ppmv). We can either re-instantiate
our radiation model:

In[12]: rad = climt.radiation(co2=400)

or we can simply assign it as:

In[13]: rad[co2] = 400

Note that we can use this same syntax to see the current value of any parameter used by the
radiation scheme. For example, if we want to see the value of the solar constant, we can type:

In[14]: rad[scon]
Out[14]: array(1367.0)

There are also two sub-classes within the radiation framework, namely climt.insolation
and climt.ozone. The climt.insolation class allows you to redefine the solar irradiance
by specifying the values of various orbital parameters (namely the solar constant scon, ec-
centricity eccen, obliquity obliq, and/or precession prece). You can also set the day of year
(calday), the latitude and longitude of the point you are interested in (lat and lon), and the
type of time averaging you want to use (one of annual, inst, or daily, where annual
is the default). The climt.ozone class returns a climatological ozone profile interpolated to
specified pressure levels:

In[15]: atm = climt.ozone(p=50)

In[16]: atm.o3
Out[16]: array([[[ 3.64752485e-06]]])

If the radiation scheme you use supports ozone, then the default ozone profile will automati-
cally be populated with this climatology at the levels used by the radiation scheme.

4.1.3 C ONVECTION SCHEMES

Another useful CliMT class is the convection class. Three convection schemes are available:
the BettsMiller scheme (scheme=sbm), the Emanuel scheme (scheme=emanuel), and a
modified dry version of the Emanuel scheme that takes an optional critical lapse rate in K m1
(scheme=hard). Use of the convection schemes is a little more difficult to figure out than
the radiation schemes, as the possible input and output parameters vary quite a bit depending
on the chosen scheme. The easiest way to find lists of these is in the CliMT source code for
convection.py. For example, the instantiation routine for the hard convection scheme (def
__hard__init__(self):) contains the lines:

self.ToExtension = [lapse,g,Rd,Cpd,afc,UpdateFreq,...]
self.FromExtension = [T,theta,TdotConv]

7
These lines indicate that the convection scheme takes the optional parameters lapse (critical
lapse rate in K m1 ), g (gravitational constant), Rd (gas constant for dry air), Cpd (specific heat
for dry air), afc (the Asselin filter coefficient, a stability parameter that we will not discuss
in detail), and UpdateFreq (which specifies how often to call the convection scheme). The
scheme returns three outputs: T (the adjusted temperature profile), theta (the adjusted po-
tential temperature profile), and TdotConv (the convective temperature tendency, in K day1 ).
The other two schemes, which include moist convective processes,

4.1.4 OTHER CLASSES

CliMT contains classes for several other climate model components, including turbulent
mixing (climt.turbulence()), an axisymmetric dynamical core (climt.dynamics()), a
slab ocean model (climt.ocean()), and a simple sea ice model (climt.seaice()).
There are two choices for turbulent mixing, a simple scheme (scheme=simple) and the
turbulent mixing scheme from the CCM3 (scheme=ccm3). Depending on the scheme, the
turbulent mixing class takes the following additional optional arguments:

| Name Dims Meaning Units Default

| nuv 0 Vertical viscosity m2/s 1.
| Pr 0 Prandtl number - 1.
| Cd 0 Surface flux coeff - 1.3e-3
| u0 0 Surf. wind for flux m/s 5.
| do_srf_sen_flx 0 Switch srf sens flux on/off 1
| do_srf_lat_flx 0 Switch srf laten flux on/off 1
| do_srf_mom_flx 0 Switch srf mom flux on/off 1
| Ts 0-2 Surface temperature K 283.15
| ps 0-2 Surface pressure mb 1000.
| p 1-3 Atmospheric pressure mb
| T 1-3 Temperature K 283.15
| q 1-3 Specific humidity g/kg 1.e-5
| U 1-3 Zonal wind m/s 0.
| V 1-3 Meridional wind m/s 0.

The output includes:

| Name Meaning Units

| Tdot Turbulent heating rate K s-1
| qdot Turbulent humidification rate g/kg s-1
| Udot Turbulent drag m s-2
| Vdot Turbulent drag m s-2
| SrfSenFlx Surface sens. heat flux W m-2
| SrfLatFlx Surface lat. heat flux W m-2
| taux Surface stress Pa
| tauy Surface stress Pa

8
Although this framework in theory allows you to calculate turbulent mixing profiles for speci-
fied conditions, in practice it is typically used in tandem with other components (see below).
The axisymmetric dynamical core is a basic implementation of the fluid dynamical equa-
tions. Without this feature, we would only be able to build one-dimensional single-column
(vertical) models using CliMT. This feature allows us to also build two-dimensional zonal
mean models (like the HeldHou model for the Hadley circulation described here).
Like the axisymmetric dynamical core, the ocean and sea ice components are very simple.
The slab ocean is a well-mixed surface layer with no currents, conceptually very similar to the
one-box model. Like the one-box model, you can control the depth (Hslab), mean density
(rowl), and specific heat (Csw) of seawater in the slab when you instantiate it (or during
model integration, if youre clever). The sea ice model is effectively an extension of the slab
ocean model, which only predicts sea ice thickness. The parameters of the sea ice model
(including the albedo, which defaults to 0.5) can only be changed by directly editing the
ice1L.py source code in the CliMT distribution. Although these models are simple, they can
be used to construct informative simulations of snowball Earth.

4.1.5 C OUPLING

The CliMT module includes the federation class to couple various model components
together. For example, we could construct a simple pure radiative equilibrium model by:

In[17]: rad = climt.radiation(scheme=gray)

In[18]: dif = climt.turbulence()
In[19]: oce = climt.ocean()
In[20]: fed = climt.federation(dif, rad, oce)

Most likely we will want to also specify some keywords, such as the timestep:

In[21]: kwargs = {}
In[22]: kwargs[dt] = 3600.
In[23]: fed = climt.federation(dif, rad, oce, **kwargs)

The final input to climt.federation in line 23 is a dictionary that contains keyword argu-
ments as key : value pairs. In this case, passing **kwargs passes the value kwargs[dt] in
exactly the same way as if we passed the keyword directly (i.e., dt=3600.). This syntax is quite
useful when we have many keywords to pass, particularly if we want to pass them multiple
times.
It is generally more appropriate to use the federation class inside of a script. As an example,
the following script is a modified version of the pure radiative equilibrium test case included
with the CliMT software. It couples the grey gas radiation scheme with turbulent mixing and
a slab ocean. The turbulent mixing is necessary to maintain the sensible heat flux between
the surface and the atmosphere. What do you think happens to the atmospheric temperature
profile if the sensible heat flux is turned off? Try it and find out!

9
  
1 i m p o r t numpy as np
2 i m p o r t climt
3
4 # Parameters
5 kwargs = {}
6 # constant relative humidity at 80%
7 rh = 0.8
8 # time step is one minute
9 kwargs [ dt ] = 3600.
10 # plots to show daily
11 kwargs [ MonitorFields ] = [ T , q , TdotRad , TdotTurb ]
12 kwargs [ MonitorFreq ] = 86400.
13 # output data every ten days
14 kwargs [ OutputFile ] = radequil . nc
15 kwargs [ OutputFreq ] = 86400. * 10.
16 # suppress surface evaporative flux
17 kwargs [ do_srf_lat_flx ] = 0
18
19 # reset specific humidity based on constant RH
20 d e f getRelHum () :
21 q = climt . thermodyn . qsflatau ( fed . State [ T ] ,
22 fed . State [ p ] , 1) * rh
23 q = np . maximum (q , q *0.+1. e -16)
24 r e t u r n np . reshape (q , np . shape ( fed . State [ p ]) )
25
26 # create component models (radiation time step is 4 minutes)
27 rad = climt . radiation ( UpdateFreq =14400 , scheme = chou )
28 dif = climt . turbulence ()
29 oce = climt . ocean ()
30 # initial conditions (temp profile is set to skin temp)
31 kwargs [ q ] = np . zeros ( rad . nlev ) + 1. e -9
32 kwargs [ T ] = np . zeros ( rad . nlev ) + \
33 ( rad [ solin ]/2./ rad [ stebol ]) **0.25
34 # use federation class to couple components
35 fed = climt . federation ( dif , rad , oce , ** kwargs )
36
37 # main timestepping loop
38 RunLength = 1000. # Total length of run (days)
39 NSteps = i n t ( RunLength *86400./ fed [ dt ])
40 f o r i i n r a n g e ( NSteps ) :
41 fed . State [ q ] = getRelHum () # impose constant relative humidity
42 fed . step ()
43 time = fed . State . ElapsedTime
44 i f i n t ( time /86400.) != i n t (( time - fed [ dt ]) /86400.) :
45 p r i n t Surface temp : %10.5 f % ( fed [ Ts ])
 

We can add the dry convective component by using the hard convective parameterization,
but keeping relative humidity constant and the latent heat flux turned off. This results in a
lapse rate that is almost constant with height in the troposphere (Fig. 4.2). Alternatively, we
could eliminate the constant relative humidity requirement, keep the latent heat flux turned
off, and use any convection scheme this configuration forces a dry atmosphere (with heat

10
distribution purely by dry convection), but does not include the greenhouse effect of water
vapor, and therefore results in a much lower surface temperature.
 
1 i m p o r t numpy as np
2 i m p o r t climt
3
4 # Parameters
5 kwargs = {}
6 # constant relative humidity at 80%
7 rh = 0.8
8 # time step is one minute
9 kwargs [ dt ] = 3600.
10 # plots to show daily
11 kwargs [ MonitorFields ] = [ T , q , TdotRad , TdotConv ]
12 kwargs [ MonitorFreq ] = 86400.
13 # output data every ten days
14 kwargs [ OutputFile ] = rce_dry . nc
15 kwargs [ OutputFreq ] = 86400. * 10.
16 # suppress surface evaporative flux
17 kwargs [ do_srf_lat_flx ] = 0
18
19 # reset specific humidity based on constant RH
20 d e f getRelHum () :
21 q = climt . thermodyn . qsflatau ( fed . State [ T ] ,
22 fed . State [ p ] , 1) * rh
23 q = np . maximum (q , q *0.+1. e -16)
24 r e t u r n np . reshape (q , np . shape ( fed . State [ p ]) )
25
26 # create component models (radiation time step is 4 minutes)
27 rad = climt . radiation ( UpdateFreq =14400 , scheme = chou )
28 dif = climt . turbulence ()
29 con = climt . convection ( scheme = hard , lapse =0.009)
30 oce = climt . ocean ()
31 # initial conditions (temp profile is set to skin temp)
32 kwargs [ q ] = np . zeros ( rad . nlev ) + 1. e -9
33 kwargs [ T ] = np . zeros ( rad . nlev ) + \
34 ( rad [ solin ]/2./ rad [ stebol ]) **0.25
35 # use federation class to couple components
36 fed = climt . federation ( dif , rad , oce , con , ** kwargs )
37
38 # main timestepping loop
39 RunLength = 1000. # Total length of run (days)
40 NSteps = i n t ( RunLength *86400./ fed [ dt ])
41 f o r i i n r a n g e ( NSteps ) :
42 fed . State [ q ] = getRelHum () # impose constant relative humidity
43 fed . step ()
44 time = fed . State . ElapsedTime
45 i f i n t ( time /86400.) != i n t (( time - fed [ dt ]) /86400.) :
46 p r i n t Surface temp : %10.5 f % ( fed [ Ts ])
 

We can then add the moist convective component by turning on the latent heat flux and
using the emanuel convection scheme. Moist convection creates much stronger diabatic

11
heating in the troposphere, thereby more effectively moving heat from the lower troposphere
to the middle troposphere, but also causes cooling near the tropopause (this is caused by the
convective dynamics, and may vary if we use a different convection scheme).
 
1 i m p o r t numpy as np
2 i m p o r t climt
3
4 # Parameters
5 kwargs = {}
6 # time step is one minute
7 kwargs [ dt ] = 360.
8 # stability parameter for leapfrog type time steps
9 kwargs [ afc ] = 0.2
10 # plots to show daily
11 kwargs [ MonitorFields ] = [ T , q , TdotRad , TdotConv ]
12 kwargs [ MonitorFreq ] = 86400.
13 # output data every ten days
14 kwargs [ OutputFile ] = rce . nc
15 kwargs [ OutputFreq ] = 86400. * 10.
16
17 # create component models (radiation time step is 4 minutes)
18 rad = climt . radiation ( UpdateFreq =14400 , scheme = chou )
19 dif = climt . turbulence ()
20 con = climt . convection ( scheme = emanuel )
21 oce = climt . ocean ()
22 # initial conditions (temp profile is set to skin temp)
23 kwargs [ T ] = np . zeros ( rad . nlev ) + \
24 ( rad [ solin ]/2./ rad [ stebol ]) **0.25
25 kwargs [ q ] = np . zeros ( rad . nlev ) + 1. e -6
26 # use federation class to couple components
27 fed = climt . federation ( dif , rad , oce , con , ** kwargs )
28
29 # main timestepping loop
30 RunLength = 1000. # Total length of run (days)
31 NSteps = i n t ( RunLength *86400./ fed [ dt ])
32 f o r i i n r a n g e ( NSteps ) :
33 fed . step ()
34 time = fed . State . ElapsedTime
35 i f i n t ( time /86400.) != i n t (( time - fed [ dt ]) /86400.) :
36 p r i n t Surface temp : %10.5 f % ( fed [ Ts ])
 

12
 200

400
Pressure [hPa]

600

800 Radiative equilibrium

Dry adiabat
Dry RCE
Moist adiabat
Moist RCE
1000
100 150 200 250 300 350
Temperature [K]

Figure 4.2: Results of radiative and radiative-convective equilibrium simulations using CliMT.

13