Introduction

How to Read This Manual

Most users: Just read (1) the installation instructions in Chapter 2, (2) Chapter 3, which tells you all you need to get started using qtcm, and (3) examples in Section 4.10 that give a feel for how you can use the model.

Users having problems: Chapter 5 provides troubleshooting tips for a few problems. The detailed description of how the package functions, in Chapter 4, will probably be more useful.

Developers: If you want to change the source code, please read Chapter 6. Chapter 7 describes all the things I'd like to do to improve the package, but haven't gotten to yet.

About the Package

The single-baroclinic mode Neelin-Zeng Quasi-Equilibrium Tropical Circulation Model (QTCM1) is a primitive equation-based intermediate-level atmospheric model that focuses on simulating the tropical atmosphere. Being more complicated than a simple model, the model has full non-linearity with a basic representation of baroclinic instability, includes a radiative-convective feedback package, and includes a simple land soil moisture routine (but does not include topography). A brief, but more detailed, description of QTCM1 is given in Section 1.6.

Python is an interpreted, object-oriented, multi-platform, open-source language that is used in a variety of software applications, ranging from game development to bioinformatics. In climate studies, Python has been used as the core language for data analysis (e.g., Climate Data Analysis Tools), visualization (e.g., Matplotlib), and modeling (e.g., PyCCSM).

In comparison to traditional compiled languages like Fortran, Python's lack of a separate compile step greatly simplifies the debugging and testing phases of development, because code snippets can be testing as code is written. Python's extensive suite of higher-level tools (e.g., statistics, visualization, string and file manipulation) accessible at runtime enables modeling and analysis to occur concurrently.

The qtcm package is an implementation of the Neelin-Zeng QTCM1 in a Python object-oriented environment. The conversion package f2py is used to wrap the QTCM1 Fortran model routines and manage model execution using Python datatypes and utilities. The result is a modeling package where order and choice of subroutine execution can be altered at runtime. Model analysis and visualization can also be integrated with model execution at runtime.

Conventions In This Manual

Audience

In this manual I assume you have a rudimentary knowledge of Python. Thus, I do not describe basic Python data types (e.g., dictionaries, lists), object framework and syntax (e.g., classes, methods, attributes, instantiation), module and package importing. If you need to brush up (or learn) Python, I'd recommend the following resources:

• Python Tutorial: This tutorial was written by Guido van Rossum, Python's original author.

• Instant Hacking: Learn how to program with Python.

• Dive Into Python: Reasonably complete and cohesive. The entire book is available for free online.

• Handbook of the Physics Computing Course: Written for a science audience. Recommended.

• CDAT/Python Tips for Earth Scientists: This web site is a FAQ of sorts for people using Python and the Climate Data Analysis Tools (CDAT) in the earth sciences, and thus focuses on using Python to do science rather than the computer science aspects of the language.

The purpose of this package is to make the QTCM1 model easier to use. In order to interpret the results, however, you still need to have a robust sense of what climate models can and cannot tell you. A starting point for the QTCM1 model is the brief description of the model in Section 1.6. After that, I would read the original papers describing the model formulation and results [3,5], and papers citing the model formulation work. Being an intermediate-level model using the quasi-equilibrium assumption, QTCM1 (and thus qtcm) has distinct strengths and limitations; please be aware of them.

Typographic Conventions

commands		to be typed at the command-line are rendered in a blue, serif, fixed-width typewriter font (e.g., make _qtcm_full_365).
dummy arguments		coupled with code or screen display is rendered in a serif, proportional, italicized font (e.g., Error-Value too long in variable).
file and directory names		are rendered in a sans-serif, italicized font (e.g., setbypy.F90).
screen display		is rendered in a green, serif, fixed-width typewriter font.
module, method, and subroutine names		are rendered in a blue, serif, fixed-width typewriter font.
variable and attribute names		are rendered in a blue, serif, fixed-width typewriter font.
class names		are rendered in a blue, serif, fixed-width typewriter font.

Blocks of code (usually commands, screen display, and module, variable, and class names) are displayed in a blue, serif, fixed-width typewriter font.

Terminology

attribute and method references:

If there is any possibility of confusion, I will give the class that an attribute or method comes from when that attribute or method is referenced. If no class is mentioned by name or context, assume that the attribute/method comes from the Qtcm class.

``compiled QTCM1 model'':

This usually is used to denote when I'm talking about compiled Fortran QTCM1 routines and variables therein, as an extension module to the Python qtcm package.. Thus, ``compiled QTCM1 model u1'' is the value of variable u1 in the Fortran model, not the value at the Python-level. Sometimes I refer to the compiled QTCM1 model as just ``QTCM1'' or as ``compiled QTCM1 Fortran model''.

``pure-Fortran QTCM1'':

This refers to the Neelin-Zeng QTCM1 model in it's original Fortran form, not as an extension module to the Python qtcm package.

``Python-level'':

This usually denotes the value of a variable as an attribute of a Qtcm instance. This variable is stored at the Python interpreter level.

Qtcm:

This refers to the Python Qtcm class (note the capitalized first letter).

qtcm:

This refers to the Python qtcm package.

QTCM1 vs. QTCM:

Although the QTCM1 is currently the only version of a quasi-equilibrium tropical circulation model (QTCM), in principle one can construct a QTCM with any number of baroclinic modes. In anticipation of this, the names of the Python package and class do not end in a numeral. In this manual and the qtcm docstrings, QTCM and QTCM1 are used interchangably. Usually either of these phrases mean the quasi-equilibrium tropical circulation model in a generic sense, regardless of its form of implementation.

Current Version Information and Acknowledgments

This manual describes version 0.1.2 (dated September 12, 2008), of package qtcm. Johnny Lin is the primary author of the package. The qtcm package is built upon the pure-Fortran QTCM1 model, version 2.3 (August 2002), with a few minor changes. Those changes are described in detail in Section 6.2.

The homepage for the qtcm package is http://www.johnny-lin.com/py_pkgs/qtcm. All Python code in this package, and the Fortran files setbypy.F90 and wrapcall.F90, are © 2003-2008 by Johnny Lin and constitutes a library that is covered under the GNU Lesser General Public License (LGPL):

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

You can contact Johnny Lin at his email address or at North Park University, Physics Department, 3225 W. Foster Ave., Chicago, IL 60625, USA.

All other Fortran code in this package, as well as the makefiles, are covered by licenses (if any) chosen by their respective owners.

This manual, in all forms (e.g., HTML, PDF, L^ATEX), is part of the documentation of the qtcm package and is © 2007-2008 by Johnny Lin. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found here.

Transparent copies of this document are located online in PDF and HTML formats. The L^ATEX source files are distributed with the qtcmdistribution. While the HTML version is nearly identical to the PDF and L^ATEX versions, not every feature in the manual was successfully converted. This is particularly true with figures, which are unnumbered in the HTML version and may be formatted differently than the authoritative PDF version. Thus, please consider the L^ATEX version as the authoritative version.

Acknowledgements: Thanks to David Neelin and Ning Zeng and the Climate Systems Interactions Group at UCLA for their encouragement and help. On the Python side, thanks to Alexis Zubrow, Christian Dieterich, Rodrigo Caballero, Michael Tobis, and Ray Pierrehumbert for steering me straight. Early versions of some of this work was carried out at the University of Chicago Climate Systems Center, funded by the National Science Foundation (NSF) Information Technology Research Program under grant ATM-0121028. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author and do not necessarily reflect the views of the NSF.

Intel and Xeon are registered trademarks of Intel Corporation. Matlab is a registered trademark of The MathWorks. UNIX is a registered trademark of The Open Group.

Summary of Release History

• 2008 Sep 12: Version 0.1.2 released. Summary of changes:
  • Create Qtcm method get_qtcm1_item. This method is effectively an alias of method get_qtcm_item.
  • Create Qtcm method set_qtcm1_item. This method is effectively an alias of method set_qtcm_item.
  • Update User's Guide to phase out references to the get_qtcm_item and set_qtcm_item methods. Adding the ``1'' to the method names makes the purpose of the methods clearer.
  • Add unit tests to cover methods get_qtcm1_item and set_qtcm1_item.

• 2008 Jul 30: Updates to the User's Guide (just the online versions, not the copies released with the tarball).

• 2008 Jul 15: First publicly available distribution released (v0.1.1).

A Brief Description of The QTCM1

This description is copied from Ch. 3 of Lin [2], with minor revisions. Model formulation is fully described in Neelin & Zeng [3] and model results are described in Zeng et al. [5]. Neelin & Zeng [3] is based upon v2.0 of QTCM1 and Zeng et al. [5] is based on QTCM1 v2.1. The QTCM1 manual [4] describes the details of model implementation.

QTCM1 differs from most full-scale GCMs primarily in how the vertical temperature, humidity, and velocity structure of the atmosphere is represented. First, instead of representing the vertical structure by finite-differenced levels, the model uses a Galerkin expansion in the vertical. The vertical basis functions are chosen according to analytical solutions under convective quasi-equilibrium conditions, so only a few need be retained. Temperature and humidity are each described by separate vertical basis functions ($a_1$ and $b_1$, respectively). Low-level variations in the humidity basis are larger than in the temperature basis. For velocity, QTCM1 uses a single baroclinic basis function ($V_1$) defined consistently with the temperature basis function, as well as a barotropic velocity mode ($V_0$). The vertical profiles of $a_1$, $b_1$, and $V_1$ are given in Figure 1.1. Currently, QTCM1 does not include a separate vertical degree of freedom describing the PBL. The horizontal grid spacing of the model is $5.625^{\circ}$ longitude by $3.75^{\circ}$ latitude.

$\parbox{70ex}{\footnotesize{Figure \re... ... $b_1$\ (dashed) and (b) baroclinic component of horizontal velocity $V_1$.}}$

These modes are chosen to accurately capture deep convective regions. Outside deep convective regions the mode is simply a highly truncated Galerkin representation. The system is much more tightly constrained than a full-scale GCM, yet hopefully retains the essential dynamics and nonlinear feedbacks. The result is that QTCM1 is easier to diagnose than a GCM, and is computationally fast (about 8 minutes per year on a Sun Ultra 2 workstation). Zeng et al. [5] show results indicating this intermediate-level model does a reasonable job simulating tropical climatology and ENSO variability.

Below is a summary of the main model equations [3]:

$$\partial_t \mathbf{v}_1 + \ensuremath{\mathcal{D}}_{V1} (... ...1 - \epsilon_1 \mathbf{v}_1 - \epsilon_{01} \mathbf{v}_0$$ (1.1)

$$\partial_t \zeta_0 + \mathrm{curl}_z (\ensuremath{\mathca... ...mathbf{v}_0) - \mathrm{curl}_z (\epsilon_{10} \mathbf{v}_1)$$ (1.2)

$$\ensuremath{\widehat{a_1}}(\partial_t + \ensuremath{\mathca... ...R^\uparrow_t -R^\downarrow_s + R^\uparrow_s + S_t - S_s + H)$$ (1.3)

$$\ensuremath{\widehat{b_1}}(\partial_t + \ensuremath{\mathca... ...\nabla \cdot {\bf v}_1 = \langle Q_q \rangle + (g/p_T) E$$ (1.4)

where (1.1) describes the baroclinic wind component, (1.2) describes the barotropic wind component, (1.3) is the temperature equation, and (1.4) is the moisture equation.

In the simplest formulation, the vertically integrated convective heating and moisture sink are assumed to be equal and opposite, so:

$$-\langle Q_q \rangle = \langle Q_c \rangle = \epsilon^\ast_c (q_1 - T_1)$$ (1.5)

For its convective parameterization for $Q_c$, this model uses the Betts-Miller [1] moist convective adjustment scheme, a scheme that is also used in some GCMs. In the convective parameterization, the coefficient $\epsilon^\ast_c$ is defined as:

$$\epsilon^\ast_c \equiv \ensuremath{\widehat{a_1}}\ensur... ...1}})^{-1} \tau_c^{-1} \mathcal{H}( \mathit{C}_{\mathrm{1}} )$$ (1.6)

where $\mathcal{H}( \mathit{C}_{\mathrm{1}} )$ is zero for $C_{1} \leq 0$, and one for $C_{1} > 0$, and $C_{1}$ is a measure of the convective available potential energy (CAPE), projected onto the model's temperature and moisture basis functions.

Sensible heat ($H$) and evaporation ($E$) are given as bulk-aerodynamic formulations:

$$H = \rho_a C_D \mathrm{V}_s (T_s - (T_{rs} + a_{1s} T_1))$$ (1.7)

$$E = \rho_a C_D \mathrm{V}_s (q_\mathit{sat} (T_s) - (q_{rs} + b_{1s} q_1))$$ (1.8)

Longwave radiation components are denoted by $R$, and net shortwave radiation is denoted by $S$. The terms $\ensuremath{\mathcal{D}}_{V1}$ and $\ensuremath{\mathcal{D}}_{V0}$ are the advection-diffusion operators for the momentum equations (projected onto $V_0$ and $V_1 (p)$, respectively). The terms $\ensuremath{\mathcal{D}}_{T1}$ and $\ensuremath{\mathcal{D}}_{q1}$ are the advection-diffusion operators for the temperature and moisture equations, respectively, using a vertical average projection. The $\langle X \rangle$ and $\widehat{X}$ operators are equivalent and denote vertically integration over the troposphere. Please see Neelin & Zeng [3] and Zeng et al. [5] for a more complete description of equations and coefficients.