gemath: A Python Package for "Good Enough" Array Manipulation and Mathematics

Introduction

This package contains methods and function to conduct some array manipulation, numerical analysis and mathematical calculations that are commonly encountered in the atmospheric sciences. This package can be thought of as a limited API of numerical analysis routines written in Python as well as other packages utilizing compiled code. The current version is 0.1.1.

Although I've used these routines in my own research, I cannot guarantee that they will work for your purposes. More disclaimers and other fine print is below.

If you email me your email address, however, I'll let you know of any major bugs that are found in this package.

The page is subdivided into these categories:

Package Description Function Listing By Function Type Help and Examples

Module Listing Downloading and Installing the Package Copyright and Licensing

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

Package Description

General

Although there are many packages for using Python for array manipulation and numerical analysis, some problems that arise in using those packages include: (1) not being able to find exactly the routine you want, (2) adequate documentation that tells you how to use the routine, (3) the hassles associated when what you need is spread-out over many different packages that you don't have installed on your system, (4) some of those packages aren't very stable, and so you're not sure if you write code using them whether your code will be usable later on, and (5) some of the packages do not handle missing values.

To deal with this situation I've compiled this package of array manipulation and basic numerical analysis tools that have algorithms that are "good enough" to get the job done. This means that they only depend on other packages (there is no called C or Fortran code), that they work, but they are not optimized or tested as rigorously as in a standard library like LAPACK. These routines also enable me write more "portable" code: if I find another module that uses a substantially better algorithm than I've implemented, I can just import and call that module in the code of my gemath routine, without having to change the code of programs that call the gemath routine. Other modules and packages I've written use gemath, which enables those modules to be more stable than might otherwise be the case.

This package is meant to be a supplement to existing Python numerics packages, including: FFT, LinearAlgebra, MLab, and RandomArray (all in Numerical Python), and transcendental. Note that I do not access or reference SciPy routines at this time because I've had problems installing them on my machine.

Importing the Package

"Key" functions can be imported in a few ways. For instance:

• from gemath import *
  This permits all key functions to be specified by name only, e.g. a = findgen(5).
• import gemath as G
  Just append G to the function name, e.g. a = G.findgen(5).

The rest of the functions should be imported explicitly. For instance, to make can_use_sphere, available, use:

from gemath.can_use_sphere import can_use_sphere

Then can_use_sphere is available without qualifiers, e.g.:

a = can_use_sphere(longitude, latitude)

Because I've written the package so that each module (besides __init__ and gemath_version) contains a single public function of the same name as the module, the module listing provides a comprehensive listing of which functions are and are not "key".

Function Input/Output

The package's functions input and output are, in general, Numeric floating point or integer arrays. Most routines allow "missing values" to be included in function input/output, by specifying the argument missing in the calling line. Some, though few, gemath functions will also allow the missing argument to be set to None, and will interpret such a setting as meaning the input does not have missing values. In general, missing should be set to a floating or integer type.

A number of functions also accept the keyword algorithm, which allows you to select which algorithm you wish to use. Of course, different algorithms have different names; however, all routines with this option have one algorithm named 'default', which is the default value of the algorithm keyword.

Summary of Bug Fixes, Updates, and Version History

A summary list of bugs and fixes, updates to the package, and a summary of the version history (with links to gzipped tar files of previous releases of the package) is found here.

[Back up top to the Introduction.]

Function Listing By Function Type

Here is a list of all key (those which are readily available via a from gemath import * statement) package public functions sorted by function type. See the module listing for an alphabetical sort by name:

• Array Creation:
  • dindgen: Returns double-precision floating point array filled with ravel()ed indices.
  • findgen: Returns single-precision floating point array filled with ravel()ed indices.
  • lindgen: Returns long integer array filled with ravel()ed indices.

• Array Information:
  • has_close: Test if array has any values "equal" to a given value.
  • is_monotonic_decr: Check whether a vector is monotonically decreasing.
  • is_monotonic_incr: Check whether a vector is monotonically increasing.
  • is_numeric_float: Check whether a variable is a Numeric array of floating point type.
  • where_close: Mask of where x and y are element-wise "equal" to each other.

• Interpolation:
  • interp: Simple linear interpolation (handles missing values).

• Operations:
  • curl_2d: Calculate curl on a 2-D grid (handles missing values).
  • deriv: Calculate derivative (handles missing values).

[Back up top to the Introduction.]

Help and Examples

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

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

Example web pages of using gemath functions:

• Array Creation and Information
• Calculating Curl (with curl_2d)

The manual has additional details regarding how the classes and functions in this package are structured. Topics include: module unit testing, future work, etc.

[Back up top to the Introduction.]

Module Listing

All modules in the package are listed below. Each module (besides __init__ and gemath_version) contains a single public function of the same name as the module. The columns contain the following:

• Module Name: Module name and link to the source code.
• Pydoc: Link to the HTML documentation produced from the module docstrings by the pydoc tool.
• Key: Notes whether the module contains key package commands or not (key commands are those which are readily available via a from gemath import * statement).
• Depend: Notes if the module has package dependencies beyond built-in Python, Numpy, and other gemath modules; if the module has no such dependencies, the column is filled with "None".
• Description: Description of the public function in the module.

For a detailed description of the entire package, see the pydoc generated documentation for __init__.py.

Module Name	Pydoc	Key	Depend	Description
__init__.py	HTML	N	None	Initialize package.
can_use_sphere.py	HTML	N	None	Test if the domain and Python package configuration allows use of the NCAR SPHEREPACK 3.0 package.
curl_2d.py	HTML	Y	sphere1	Calculate curl on a 2-D grid.
deriv.py	HTML	Y	None	Calculate derivative.
dindgen.py	HTML	Y	None	Returns double-precision floating point array filled with ravel()ed indices.
findgen.py	HTML	Y	None	Returns single-precision floating point array filled with ravel()ed indices.
gemath_version.py	HTML	N	None	Package version information.
has_close.py	HTML	Y	None	Test if array has any values "equal" to a given value.
interp.py	HTML	Y	None	Simple linear interpolation for ordinate with missing values.
is_monotonic_decr.py	HTML	Y	None	Check whether a vector is monotonically decreasing.
is_monotonic_incr.py	HTML	Y	None	Check whether a vector is monotonically increasing.
is_numeric_float.py	HTML	Y	None	Check whether a variable is a Numeric array of floating point type.
lindgen.py	HTML	Y	None	Returns long integer array filled with ravel()ed indices.
where_close.py	HTML	Y	None	Mask of where x and y are element-wise "equal" to each other.
Module Name	Pydoc	Key	Depend	Description

¹This dependency is required by a subset of options for the module. Default actions of the module will still work without this dependency.

[Back up top to the Introduction.]

Downloading and Installing the Package

Platforms

I've only tested gemath on a GNU/Linux system, though it should work on any Unix platform that runs Python with Numpy.

Since I'm distributing the package as a gzipped tar file, if you're using Windows email me about getting the source code or download the modules one at a time from the module listing section above.

Dependencies

Python: gemath has been tested on and works on v2.2.2 and 2.3.3.

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

• MA: Masked arrays operations package (v11.2.1 or higher)
• Numeric: Array operations package (v22.1 or higher)
• sphere: Python module accessing SPHEREPACK

sphere is a contributed package to the Climate Data Analysis Tools (CDAT) suite. Numeric and MA are part of the Numerical Python (Numpy) package.

Installation of Numpy is trivial. Installation of CDAT contributed packages, on the other hand, is more difficult (see their web site for details). However, almost all of gemath's functionality only requires Numpy. See the module list for information regarding dependencies for each module.

Package gemath itself is written entirely in the Python language.

Downloading and Installing

First, get the following file:

• gemath-0.1.1.tar.gz

Expansion of the tar file will create the directory gemath-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 gemath-0.1.1.tar.gz
tar xvf gemath-0.1.1.tar

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

• Best way: Type:

  python setup.py install

  This will install the package gemath 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 gemath in the directory ~/lib/python/gemath (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 gemath anywhere you want and just copy the contents of ./lib into that directory. There is no compiled code in this package, so the import gemath command only looks for a directory named gemath on your Python path and executes the __init__.py file in it. Of course, you'll have to make sure the directory gemath 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 gemath 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 gemath-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 gemath-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 © 2003-2004 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 gemath package and is copyright © 2003-2004 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://www.johnny-lin.com/py_pkgs/gemath/doc/index.html.

[Back up top to the Introduction.]