modelutil: A Python Package of Model Utilities for Climate Modeling

Introduction

This package contains a collection of model utilities to help with climate modeling. Utilities include objects to define atmospheric constants, manage variable fields and states, and a generic model class from which to build models. These tools are designed for use in climate models ranging from single-column models (SCMs) to full-scale general circulation models (GCMs). The current version is an alpha-release (0.1.1).

Although we've used these routines in our own research, we cannot guarantee that they will work for your purposes. In particular, the generic framework for modeling requires substantially more testing before it can advance to beta-release. More disclaimers and other fine print is below.

Web site index:

Home Package Description Help, Examples, and FAQ Version History (bugs, updates)

Module Listing Downloading and Installing the Package Reference Manual Copyright and Licensing

If you don't find the information you're looking for on this home page, see the reference manual.

Package Description

General

The utility classes and functions described in this package define atmospheric constants, manage variable fields and states, and define a generic model class from which a set of interchangeable climate models and submodels can be defined. These climate models can be written entirely in Python, compiled C or Fortran, or a mix of the three.

The most important purpose of this package is to define a framework to manage model variables, states, and time stepping for climate models. This framework is simple to use and flexible; the goal was to develop a framework whose methods and objects were few enough and intuitive enough that users could memorize its components. Unlike more complex and comprehensive frameworks (such as the Earth System Modeling Framework), it does not aim to be all things to all people. It does, however, enable modular climate modeling components to be developed that utilize modern object-oriented programming techniques to make error-resistant code.

Atmospheric model variables (such as zonal wind, temperature, etc.) are defined as Field objects. Collections of Field objects at a given timestep are instances of a State object. Collection of State objects are StateSet objects. And all models are subclasses of the GenericModel class, which are StateSet objects with additional methods. GenericModel can be used for models and submodels of all kinds. For instance, in the seaice suite of sea-ice models, GenericModel is used for both the submodel that calculates equilibrium surface temperature in the Semtner thermodynamic sea-ice model as well as the full Semtner sea-ice model. Details are found in the manual discussion on the structure of models.

Importing the Package

The __init__ module in the package does not generally import package submodules, and thus classes and functions defined in those submodules need to be referred by their full paths.

The key modeling framework classes (Field, State, StateSet, and GenericModel) as well as the atmospheric constants class (AtmConst) are found in modules of similar names (i.e. field, state, stateset, generic_model, and atmconst, respectively).

Thus, to import the Field class, type:

import modelutil.field.Field

[Back up top to the Introduction.]

Help, Examples, and FAQ

The module listing section includes pydoc generated documentation of the modules in the package. The Python interactive help method provides similar functionality:

• help(modelutil): Help for the package. A list of all modules in this package is found in the "Package Contents" section of the help output.
• help(modelutil.M): Details of each module "M", where "M" is the module's name.

Example web pages of using modelutil classes to:

• Define atmospheric constants
• Define a simple thermodynamic sea-ice model

Additional documentation:

• Frequently Asked Questions
• Reference Manual: Covers model programming logic, class and function structure, module unit testing, future work, etc.

[Back up top to the Introduction.]

Downloading and Installing the Package

Platforms

This package has only been tested on a GNU/Linux system, though it should work on any Unix platform that runs Python with Numpy or numarray.

Dependencies

Python: modelutil has been tested on and works on v2.3.3.

Full functionality of modelutil requires the following packages and modules be installed on your system and findable via your sys.path:

• gemath: "Good enough" array manipulation and mathematics package (v0.2.1 or higher)
• Array and masked array operations package: Either the Numerical Python (Numpy) or numarray package.

Numpy includes the Numeric (v22.1 or higher) and MA (v11.2.1 or higher) packages. Numarray includes the numarray (v0.9 or higher) and ma (v12.2.0 or higher) packages. gemath is distributed by Johnny Lin.

See the module list for information regarding dependencies for each module.

Package modelutil itself is written entirely in the Python language.

Downloading and Installing

First, get the following file:

• modelutil-0.1.1.tar.gz

Expansion of the tar file will create the directory modelutil-0.1.1. This directory contains the source code, the full documentation (HTML as well as images), a copy of the license, and example scripts.

To unzip and expand the tar file, execute at the command line:

gunzip modelutil-0.1.1.tar.gz
tar xvf modelutil-0.1.1.tar

There are a few ways you can install the package. For all these methods, first go into the modelutil-0.1.1 directory:

• Best way: Type:

  python setup.py install

  This will install the package modelutil in the default site-packages directory in your default Python. You'll probably need administrator privileges, however, in order to do this install.

• Next best way: Type:

  python setup.py install --home=~

  This will install the package modelutil in the directory ~/lib/python/modelutil (where ~ means your home directory). However, you'll need to make sure ~/lib/python is on your path.

• Alternately, you can just make a directory modelutil anywhere you want and just copy the contents of ./lib into that directory. There is no compiled code in this package, so the import modelutil command only looks for a directory named modelutil on your Python path and executes the __init__.py file in it. Of course, you'll have to make sure the directory modelutil is in is on your path.

You can append entries to your path by:

import sys
sys.path.append('newpath')

Where 'newpath' is the full path of the location you're appending to your Python path. Thus, if the directory modelutil is in a directory /home/jlin/lib/python, 'newpath' is '/home/jlin/lib/python'. You can automate this by making the proper settings in a user customized .pythonrc.py file.

That's it!

Installing a Local Copy of the Documentation

The modelutil-0.1.1 directory contains a complete copy of the documentation for the package, including images. Keep this directory around (you can rename it) if you'd like to have a local copy of the documentation. The front page for all documentation is the doc/index.html file in modelutil-0.1.1. The most recent copy of the documentation is located online here.

[Back up top to the Introduction.]

Copyright and Licensing

Software License

Unless otherwise stated, the Python, Fortran, and/or C++ routines described on this page or which reference this page are copyright © 2004-2005 by Johnny Lin and constitute 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 the University of Chicago, Department of the Geophysical Sciences, 5734 S. Ellis Ave., Chicago, IL 60637, USA.

A copy of the GNU LGPL can be found here. Please note that the LGPL disclaimers of warranty supercede and replace any implied or explicit warranties or claims found in the text of the routine source code.

Documentation License

The referring web page is part of the documentation of the modelutil package and is copyright © 2004-2005 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. The Transparent copy of this document is located at http://geosci.uchicago.edu/csc/modelutil/doc/index.html.

[Back up top to the Introduction.]