2. Installing Pizza.py

Unpack the Pizza.py distribution by typing the following:

gunzip pizza.tar.gz
tar xvf pizza.tar 

The Pizza.py main directory should then contain the following directories:

Because Python is an interpreted language, there is no need to compile or "make" Pizza.py. You run Pizza.py by executing the src/pizza.py file directly, as described below. However there are 3 issues to consider: (a) you must have Python installed on your machine, (b) some Pizza.py tools require your Python to be extended with additional Python packages, and (c) some Pizza.py tools are wrappers on other software which needs to be available on your system.

If you don't plan to use a particular Pizza.py tool, you don't need to install additional Python packages or other software it requires.

Note that we cannot provide help on installing the various software packages described here. If you have problems, you'll need to talk to a local expert who can help you with your machine. If you find that instructions on this page are incorrect or incomplete or you can provide a better description of the install procedure, please send an email to sjplimp@sandia.gov.

Installing Python

Python is open-source software available for Unix, Macintosh, and Windows machines. If you have a Linux box or Mac it is probably already installed. If the python executable is in your path, typing "python" should give you a Python prompt ">>>" and tell you what version you are running. Version 2.4 or newer is sufficiently current to run Pizza.py, though older versions may work as well.

If Python is not installed on your machine, go to www.python.org to download a binary or source-code version and then build and/or install it.

On my Linux box, this was as easy as

./configure; make; sudo make install 

To use the Pizza.py tools that have GUIs, you need to insure your Python supports Tcl/Tk via the Tkinter module. You can test if this is the case by typing the following from your Python prompt:

>>> import Tkinter
>>> Tkinter._test() 

If this fails, see further instructions below for Tkinter.

IMPORTANT NOTE: If you are installing a new version of Python, read the Tkinter section first, since it describes how to make sure the Tcl/Tk and Togl libraries are installed. If you want to use the Pizza.py tools that require them, you need to do this step before building Python.

Running Pizza.py

Typically Pizza.py should be run from the directory where your LAMMPS or other data files are. Like any Python program, Pizza.py can be run in one of 2 ways, by typing either

python -i ~/pizza/src/pizza.py
~/pizza/src/pizza.py 

where the last argument is the full pathname of the pizza.py file.

The -i switch leaves Python in interactive mode (instead of exiting) after the pizza.py script is run. In the 2nd case, if the src dir is in your path, just pizza.py could be typed. For the 2nd case, you must also set src/pizza.py to be an executable file (chmod +x pizza.py) and edit the 1st line of pizza.py to reflect where Python lives on your system (find it by typing "which python"), e.g.

#!/usr/local/bin/python -i 

Putting a definition like one of the following in your .cshrc file (or equivalent syntax for other Unix shell start-up files) will let you simply type "pizza" at the command-line to start Pizza.py.

alias pizza python -i ~/pizza/src/pizza.py alias pizza ~/pizza/src/pizza.py

Pizza.py accepts several command-line options; they are described in this section of the documentation.

When Pizza.py starts, it reads a few values from the src/DEFAULTS.py file (described below) and imports the *.py files from the src directory as Python modules. These are the Pizza.py tools. Error messages will be printed if your Python has not been extended with a Python package that a tool requires. If you don't plan to use the tool you can ignore the message, or exclude that tool via the command-line switch "-x".

Once all tools have been loaded and any initial scripts and commands have been run (via command-line arguments) you should see the Pizza.py ">" prompt. From this point on, everything you type is a Python command. Python interprets what you type, operates on your data, and produces output or error messages, just as if you were typing in response to Python's interactive prompt ">>>".

You can also type special commands that have been added to the Python interpreter by Pizza.py or commands that invoke Pizza.py tools. More details about these options are explained in this section of the documentation.

As with Python, type Ctrl-D to exit Pizza.py at any time.

Setting up the DEFAULTS.py file

When Pizza.py starts it reads 3 values from the src/DEFAULTS.py file:

These are designed to allow users to augment Pizza.py with their own tools and scripts, which need not be stored in the directories of the Pizza.py pacakge. Follow the instructions in the DEFAULTS.py file for using these options.

The DEFAULTS.py files also contains various variables that specify the name and path of programs that Pizza.py tools will execute on your system. In some cases the variables contain settings that are used by these programs. Read the comments in the DEFAULTS.py file for more information.

The following table lists the keywords in the DEFAULTS.py, the program or setting that will be used by default if the keyword line is commented out, and the Pizza.py tools that use the keyword. If the program is not in your path or you wish to use an alternate program or setting, you must edit the DEFAULTS.py file accordingly. If you don't plan to use any tool that needs the keyword, you can ignore its setting.

Installing additional Python packages

This is the list of extra Python packages various Pizza.py tools require. If a tool is not listed it requires no extra packages. Instructions on where to find the Python extensions and how to install them are listed below.

Numeric or Numpy

Numeric and its follow-on NumPy enables Python to process vectors and arrays of numbers efficiently, both in terms of memory and CPU speed. It's an extremely useful extension to have in your Python if you do any numerical work on large data sets. Pizza.py can use either Numeric or NumPy.

If Numeric or NumPy is already installed in your Python, you should be able to type one of the following without getting an error:

>>> import Numeric
>>> import numpy 

Numeric can be downloaded from this site on SourceForge and NumPy from this site. Numeric version 24.2 is fine for Pizza.py as is a current version of NumPy. Once unpacked, you can type the following from the Numeric or NumPy directories to install it in your Python.

sudo python setup.py install 

Note: on my Linux box, when Numeric installed itself under the Python lib in /usr/local, it did not set all file permsissions correctly to allow a user to import it. So I also needed to do this:

sudo chmod -R 755 /usr/local/lib/python2.5/site-packages/Numeric 

pexpect

Pexpect in a pure Python implementation of the Expect capability of the Tcl language. It allows Python to send commands to another program, and handshake the interaction between them, one command at a time.

If pexpect is already installed in your Python, you should be able to type the following without getting an error:

>>> import pexpect 

Pexpect can be downloaded from this site. As of Nov 2010, Version 2.4 is fine. On my Linux box, this command installed it:

sudo python setup.py install 

PIL

The PIL (Python Imaging Library) allows Python to read image files, manipulate them, and convert between several common image formats.

If PIL is already installed in your Python, you should be able to type the following without getting an error:

>>> import Image,ImageTk 

PIL can be downloaded from this site. As of July 2007, Version 1.1.6 is fine. On my Linux box, this command installed it:

sudo python setup.py install 

with a notice that Tkinter and ZLIB (PNG) support were enabled. If you want the Pizza.py tools to recognize other image formats (e.g. JPEG), then look at the README for further details, if the PIL build did not find the correct libraries.

Pmw

Pmw (Python mega-widgets) is a common Tkinter extension that provides a host of more powerful GUI widgets.

If Pmw is already installed in your Python, you should be able to type the following without getting an error:

>>> import Pmw 

Pmw can be downloaded from this site. As of July 2007, Version 1.2 is fine. On my Linux box, these commands installed it:

cd Pmw.1.3.2/src
sudo python setup.py install 

PyOpenGL

The PyOpenGL package is a wrapper on the ubiquitous OpenGL graphics library and allows a Python program to make graphics calls in standard OpenGL syntax. It also includes Togl support for opening a Tk OpenGL widget, assuming your Python has Tkinter intstalled and that Tkinter was built with Togl. The Pizza.py tools that use PyOpenGL require this capability.

If PyOpenGL is already installed in your Python, you should be able to type the following without getting an error:

>>> import OpenGL 

If your PyOpenGL supports Togl, you should be able to type the following without getting an error:

>>> from OpenGL.Tk import *
>>> from OpenGL.GLUT import * 

PyOpenGL can be downloaded from this site on SourceForge. You want the latest PyOpenGL release (not OpenGLContext). As of July 2007, Version 3.0.0a6 is what I used.

IMPORTANT NOTE: I had many problems installing earlier versions of PyOpenGL on various boxes. But the 3.0 release was much easier to install on my Linux box, as outlined here. Note that version 3.0 requires Python 2.4 or later.

IMPORTANT NOTE #2: By default, your Python may or may not have Tkinter installed. Even if Tkinter is installed, it probably was not built with Togl. If this is the case, you should install them first before installing PyOpenGl, otherwise you may get errors when you try to use the Pizza.py tools that use PyOpenGL, because they require Tkinter and Togl. See the Tkinter section below for instructions on installing Tkinter and Togl in your Python.

Once Tcl/Tk and Togl were in place, Installing PyOpenGL on my Linux box was as simple as:

sudo python setup.py install 

(Sep 2012) A user reports, you can also then do this:

cd src sudo python togl.py

which should enable Togl with PyOpenGL

readline

The readline library is part of Python but is not supported on all systems. If it works in your Python, then Pizza.py (and Python) prompts are more shell-like and should support arrow keys, Emacs-style editing, command history, etc. If you get an error "No module named readline" when Pizza.py starts up, you can ignore it, or comment out the line "import readline" in src/pizza.py.

If readline is already installed in your Python, you should be able to type the following without getting an error:

>>> import readline 

The readline library can be downloaded from this site. After building the library, I believe you then have to rebuild Python itself.

Tkinter and Togl

The Tkinter package is part of Python but is not always enabled when Python is built, typically due to not finding the Tcl/Tk libraries. If you can type the following without an error message in your Python, then Tkinter is operational in your Python:

>>> import Tkinter
>>> Tkinter._test() 

If this fails, you need to rebuild Python and either insure it finds the Tcl/Tk libraries or build those libraries first as described here. Since I wanted a more current Python then was installed with Linux on my box, I download the latest Python (Python 2.5.1 as of July 2007) and installed it under /usr/local.

IMPORTANT NOTE: If you want to use any of the Pizza.py tools that use PyOpenGL, you also need the Togl library installed in the same directory as your Tcl/Tk libraries, so that Tcl/Tk can find it when it runs. Thus you should also install Togl, after building the Tcl/Tk libraries, and do both before re-building Python, as outlined in the following 3 steps.

(1) Building Tcl/Tk libraries

You can download the latest versions of Tcl and Tk here:

As of Oct 2011, version 8.5 is fine. After unpacking the two tarballs I did the following:

cd tcl8.5.10/unix
./configure; make; sudo make install 
cd tk8.5.10/unix
./configure; make; sudo make install 

(2) Installing Togl

To intstall Togl, download it from this site on SourceForge. As of Oct 2011, Version 2.0 is fine.

After unpacking the tarball, try typing the following to install it:

./configure

The first time I did this, it complained about not finding the Tcl and Tk strings it needed to point to Tcl/Tk. I fixed this by installing the tcl-devel package via yum.

I then noticed that "configure" was finding the system Tcl/Tk instead of the one I had installed. So I typed this instead:

configure --with-tcl=/usr/local/lib/tcl8.5 --with-tk=/usr/local/lib/tk8.5 

You should also make sure that "configure" prints a "prefix" string that points to the correct directory where you want Togl installed. For example, in my case, I did not want it installed in /usr/lib to use with the system Python, but in /usr/local/lib to be loaded by my own installed Python version.

Using the with Tcl/Tk options on the configure command fixed this as well.

(3) Rebuilding Python

Now you can re-build Python (as described above) and it should find the correct Tcl/Tk libraries under /usr/local, so that you have Tkinter and Togl working with your Python as well. Note that when you run ./configure as the first step in building Python, it will tell you what it found for Tcl/Tk.

Installing other software

Some Pizza.py tools invoke other software which must be installed on your system for the tool to work. This is an alphabetic list of the needed software. Except where noted, it is freely available for download on the WWW. The Pizza.py tools that use this software are listed above in this section. To see if you already have the software on your box, type "which command", e.g. "which display".

ImageMagick display, convert, montage commands

Several Pizza.py tools display image files. The ImageMagick "display" program can be used for this purpose. Likewise, the ImageMagick "convert" and "montage" comands are used by the image tool. The ImageMagick toolkit can be downloaded from this site and contains a variety of useful image conversion and manipulation software.

GnuPlot

The Pizza.py gnu tool is a wrapper on the open-source GnuPlot program. GnuPlot can be downloaded from this site.

Gunzip

Gunzip is invoked by Python to read compressed (*.gz) data and dump files. It is almost certainly on your Unix system. If not if can be downloaded from this site.

Label3d

The Pizza.py tool raster uses the label3d and render programs from the Raster3d visualization package to produce high-quality ray-traced images. See the description of "Render" below for information about Raster3d.

MatLab

The Pizza.py matlab tool is a wrapper on MatLab which is a widely-used commercial numerical analysis package that also produces nice plots. Further information is available at the MathWorks WWW site. When MatLab is installed on your system and the appropriate environment variables are set, the command "matlab" should launch the program.

RasMol

The Pizza.py rasmol tool invokes the RasMol visualization package to view molecular systems and produce nice images. RasMol can be downloaded from this site, which is for the original open-source version of RasMol, not the Protein Explorer derivative version of RasMol.

Note that when using RasMol on a Mac, you will need to launch X11 first (or run Pizza.py from an X11 xterm) to get RasMol to display properly.

Render

The Pizza.py tool raster uses the render and label3d programs from the Raster3d visualization package to produce high-quality ray-traced images. Raster3d can be downloaded from this site.

For Macs, Raster3d is available for download via Fink as an unstable package.

VMD

The Pizza.py vmd tool is a simple wrapper on the VMD visualization package which is a popular tool for visualizing the output of molecular dynamics simulations. VMD can be downloaded from this site.