What do you need to install?
To run the courseware, you need to install python and the array-handline package numpy. This page deals only with the basic Python installation. Installation and use of the courseware modules is described under Courseware. In order to display graphics within Python, you will also need to install a graphics package, as described under Graphics. For basic information on starting up the python interpreter and writing and running scripts, see Learning Python. You can write scripts using any text editor you like, and run them using the basic command-line interpreter, but almost all installations of Python come with a very nice integrated development environment called idle, which offers a smarter interpreter window and also an easy-to-use editor that's aware of Python syntax. idle needs to be run in a windowing environment that displays graphics. You do not need to install a graphics package to run idle, since any modern computer will have a suitable windowing system. On Linux systems, idle uses the x11 windowing system, which is also the native windowing system for Linux. This is useful, because it allows idle to be run on a server but put up a window on your own computer over the network. Mac OS X comes shipped with both x11 and its native windowing system; the current versions of Python for the Mac use the native windowing system to run idle, and Windows implementations also use the native Windows windowing environment. If you are using Python by logging into a server, you will need x11 on your own machine in order to use idle, or indeed to see any graphics on your own screen.
[** Page needs some internal navigation to subheadings.]]
Do you already have Python?
This section is only for Mac and Linux users who want a quick-start without needing to do a Python installation of their own. It is highly recommended to do a fresh installation, so most users should just skip to the next section.
All Mac OSX operating systems since 10.4 come shipped with a version of Python installed, and the versions since 10.5 are very complete, generally including both numpy and idle. Most Linux systems also come with a complete and usable Python installation. On a Mac, and to a lesser extent on Linux, it is recommended that you do a separate Python installation of your own, so you have better control of which version you are using and so you don't have to mess with stuff in the operating system directories. On Mac OS10.6 and higher you also have to keep in mind that the pre-installed version is 64-bit, and so will only work with compiled add-on modules that are also 64-bit (most of the courseware modules and chapter scripts will work fine, though, since only a few of these require compiled add-ons). Nonetheless, to get started learning the language, and for doing basic computations, the pre-installed versions are fine. As far as I am aware, Windows never comes shipped with Python, so the following instructions in this topic apply only to Mac and Linux. If you have a pre-installed version, that's enough to get you started with the language, but chances are you'll soon want to scroll down to the Installing Python heading below, and learn how to install a customized version.
To find whether you have Python, and which version, open a terminal window (that's any window on Linux, and the window you get with either the Terminal utility or x11 on Mac) and type
followed by a return, at the prompt. This will bring you into the python interpreter, and you will get a python prompt. If the computer complains that the command wasn't found, then python isn't installed. (or, it is installed, but the location isn't in your default search path for finding commands). If you get the prompt, it will also tell you what version of Python you have, and what version of the compiler it was built with (which matters for a few compiled add-on modules). Assuming that you have gotten the Python prompt, to find if you have numpy, just type
If everything is OK, you'll just get the Python prompt back with no message. If numpy isn't installed Python will tell you it can't find the module. Now you can quit Python by typing control-D, and check to see if you have idle installed. To do that, go to a terminal window and type
If you are on a Mac with a relatively recent operating system or installation of Python, this will work regardless of whether you are using a plain terminal window or an x11 terminal window (an xterm), since once it starts up idle, the native Mac windowing system is used. (On older installations idle uses x11 for windowing, and you need to start idle from an xterm, but Python never came pre-installed with idle on the older systems anyway). If you are starting idle on a remote server to which you are logged on through a terminal window, then you must be logged on via an xterm (use ssh -Y to log in, or ssh -X on older systems), otherwise idle can't put up its window. Either way, if everything is OK, you should get an idle Python shell window, with an idle menu bar either in the window or at the top of your screen, depending on the system.
Which version of Python?
You should stay with a 2.X version, since Python 3.X is not backward compatible (mostly because of some stupid changes they made to the print statement). The current production version of Python is 2.7, and it is now working fine with the courseware, though 2.6 should also work.
You also need to decide whether to do a 32-bit or 64-bit installation of Python (look here for an explanation). 64 bit installations are available for Python 2.7 and later, with some availability for Python 2.6 as well. I am generally recommending staying with 32-bits if possible, but 64 bit versions of the necessary libraries are gradually becoming widely available, so soon 64 bits will become the installation of choice. For now, the main problem with going to 64 bit involves the use of the Climt_lite interface to the ccm radiation model, which so far we have only compiled for 32 bits on the Mac; on Linux you can easily build it for your own system, and so far we haven't ported it to Windows at all. The PyNgl graphics package is now available in both 32 bit and 64 bit versions.
By far the easiest way to install the basic Python software you need to run the courseware is to use the Enthought distribution, which is available in 32 and 64 bit versions for Mac, Linux and Windows and installs easily using a one-click installer. This distribution gives you Python and numpy, and also gives you the excellent MatPlotLib graphics package. With MatPlotLib, you don't even really need to install PyNGL. Currently, my ClimateGraphics.py module can only use PyNGL as a graphics driver, but MatPlotLib is so easy to use you can easily write your own graphing commands, while waiting for my next release of ClimateGraphics.py, which will support MatPlotLib. Using MatPlotLib with the Enthought distribution is by far the simplest way to go if you want to use graphics on a Windows machine, since then you won't have to install CygWin to get the the x11 windowing system (used by PyNgl). There have been some problems reported in installing PyNgl on Debian Linux systems, and the Enthought distribution with MatPlotLib may be the solution of choice in that case as well. Note that the Enthought distribution is FREE for academic users.
If you want to use PyNGL with the Enthought distribution, you can install it on top of Enthought in precisely the same way you would if installing it on top of the Sourceforge Python distribution described below.
Python for all systems can be downloaded from python.org here . Version 2.6 of Python can be downloaded here. The precompiled binaries for 2.6 on Mac OSX are all 32-bit versions. If you want to make the leap to a 64 bit world, you should look for a precompiled 2.7 or higher version that is explicitly flagged as 64 bit for your operating system (OS 10.6 or higher on the Mac). By the way, the version of Python that ships with Mac OSX is a 64 bit version, and will work only with add-on software built for 64 bit. The Mac OS 10.6 Python already ships with a compatible
numpy, so the compatibility only affects your installation of Climt_lite and PyNGL. However, I do recommend installing a fresh version of Python (as described below), since that gives you more flexibility in upgrading things and picking versions, without having to mess with your operating system directories (always a hazard to do). The Python installation also installs the idle integrated development editor.
The download page comes up showing only the latest release of Python, which is presently Python 2.7. If you want it, you can find Python 2.6.6 here; the later release of Python 2.6 does not include binary installers, and in fact the 2.6.6 release is no longer linked even on the "earlier releases" link, but the link given above still seems to work. Look for a single-click binary installer; most users will not want to build Python from source code.
- Installing on Mac OSX: The distribution is in the form of a Mac Installer disk image (.dmg) file. After you download it from the directory for the release you want, just click on the disk image to mount it, then click on the installer to install it, and follow the directions. The installer installs Python in the /Library/Frameworks/Python.framework directory, which becomes the root directory for anything else you add on to Python. It does not affect the version of Python that ships with the system. The installer also puts a link to the python command in the directory /usr/local/bin , so that when you type the command python or idle in a terminal window, it executes the most recent version of Python that you installed. (Note that for the Mac distribution, idle uses the native Mac windowing system rather than x11). To check which version of Python you are using, type the command which python or which idle into a command window. The first command should return /usr/local/bin/python , for example, and if you then issue the command ls -l /usr/local/bin/python you will see the original file it points to. Some versions of the installer may point directy to /Library/Frameworks/Python.framework/Versions/Current/bin/python. The installer also puts a Python2.X folder in your Applications folder, which contains an icon that you can double-click to start idle (which also gives you a Python interpreter window). Advanced users can alternately download the source code tarball (which is system independent) and build Python from source, but there is little point in doing so unless you have a special configuration not covered by any of the precompiled releases.
- Installing on Linux: Download the sourcecode tarball and build from source. It may also be possible to install Python and idle directly from the command line using Debian tools, without going through Sourceforge.
- Installing on Windows:Clickable installers are provided for both 32 and 64 bit Windows versions. Just download and execute, then follow instructions. General tips on installing and using Python on Windows are found here. Note that (as far as I can tell), the 32 bit version will refuse to install if you are using a 64 bit version of Windows, so you will have to install the 64 bit version in that case.
Which python am I using?
[**Installer should set the default executable path to the version you just installed. How to check that. What to do to set the path if /usr/local/bin/python isn't coming up as the default version to use. link to ShellsNStuff]
numpy for all systems is available from the Sourceforge Numpy Site . For most systems, precompiled binaries are available. On the Sourceforge page, you'll see various folders. Open (or expand) the Numpy folder (listed under the heading "All Files"), and then the folder for the version that you want. Distributions for all operating systems are given in the same folder. If you are staying with a 32 bit world on Mac OSX, then I recommend Version 1.3.0 or 1.4.1 with Python 2.6.
The package f2py is distributed as part of numpy. f2py is a powerful tool for advanced users, since it allows one to very simply turn compiled Fortran (and some kinds of c) code into a new Python command. You need to have installed a compatible Fortran compiler (e.g. gfortran ). f2py is used to build the courseware module CliMT , which provides an interface to the ccm radiation code. Documentation on use of f2py can be found here.
- Installing on Mac OSX: The distribution is in the form of a disk image (.dmg) file. After you download it, just click on the disk image to mount it, then click on the installer to install it, and follow the directions. You need to have first installed a compatible version of Python. (The installer will tell you if you haven't done this). For 32 bit Python 2.6, the file you want is numpy-1.3.0-py2.6-macosx10.5.dmg for numpy1.3, or numpy-1.4.1-py2.6-python.org.dmg for numpy1.4.1. I have not yet tried the latter version, so I recommend using numpy1.3 for now. If you have decided to make the leap to a 64 bit world, and have installed a 64 bit OS10.6 version of Python, then you may have to build a compatible version of numpy from one of the source distributions given on the Sourceforge site, until a precompiled binary becomes available. If you have installed Python 2.7, you should look for a compatible version of numpy. Earlier versions should also work with Python 2.7, but the installer may have some trouble figuring out where to put it.
- Installing on Linux: For Linux the recommended practice when using the Sourceforge distribution is to build numpy from source files. These are available in the directories for individual versions with names like numpy-1.4.1.tar.gz . Various Linux distributions, especially Debian, offer command-line tools to simplify installation of add-on software, and there is a good chance that numpy is available through this channel as well.
- Installing on Windows: Executable installers are available with file names like numpy-1.4.1-win32-superpack-python2.6.exe . The "superpack" designation means that numpy is installed along with various other goodies useful for scientific work. See the release notes for details. At the time of writing, Sourceforge does not offer a 64 bit binary, so if you are working with 64 bit Python for one reason or another, by far your best alternative is to use the Enthought distribution (which is probably your best alternative anyway, regardless of what system you are using, unless you aren't eligible for the free academic download and don't want to spend the $180 for a commercial license, though even then Enthought Free probably has everything you need except (currently) 64-bit support for Windows.).