$Id: README 689 2003-03-08 16:59:39Z travo $
README for pygist-1.5*
------------------------------------------------------------------------
Original documentation by Lee Busby and Zane Motteler:
------------------------------------------------------------------------

Python Gist

The Python Gist Scientific Graphics Package, version 1.5, written by
Lee Busby and Zane Motteler of Lawrence Livermore National Laboratory,
is a set of Python modules for production of general scientific graphics.
We abbreviate the name to "PyGist" here and elsewhere.

Description

Gist is a scientific graphics library written by David H. Munro of Lawrence
Livermore National Laboratory. It features support for three common
graphics output devices: X-Windows, (Color) PostScript, and ANSI/ISO
Standard Computer Graphics Metafiles (CGM). The library is small
(written directly to Xlib), portable, efficient, and full-featured. It
produces x-vs-y plots with ``good'' tick marks and tick labels,
2-D quadrilateral mesh plots with contours, vector fields, or pseudocolor
maps on such meshes, and a selection of 3-D plots.

The Python Gist module utilizes the ``Numerical'' package due to
J. Hugunin and others.  It is therefore fast and able to handle large
datasets. The Gist module includes an X-windows event dispatcher which
can be dynamically added to the Python interpreter. This makes fast
mouse-controlled zoom, pan, and other graphic operations available to
the researcher while maintaining the usual Python command-line interface.

------------------------------------------------------------------------
IMPLEMENTATION APPROACHES / CURRENT STATUS (11/19/02)
------------------------------------------------------------------------

Four approaches have been tried for linking Gist to Python:

- Setting rl_getc_function to u_getc

- Setting PyOS_InputHook (rl_event_hook) to u_waiter and commenting out
  if (!serviced event) test in u_waiter.

- Setting PyOS_inputHook (rl_event_hook) to u_enterloop (wrapper for u_getc),  
  but make sure u_getc does not actually retrieve characters from stdin,
  because Python will do that.  

- Setting PyOS_inputHook (rl_event_hook) to u_wait_stdin (Yorick 1.5.13).

The first (rl_getc_function) approach works on tru64_5, Solaris, IRIX64,
and Linux, but not AIX.  With ASCI AIX machines, this approach is not 
useful for LLNL.

The PyOS_InputHook/u_waiter approach works on Compaq (OSF/1), alpha Linux, 
Intel Linux, Solaris, IRIX64, AIX 5.x (frost), and cygwin (the last confirmed 
by Michiel de Hoon (U. of Tokyo), who found this approach), but has some 
performance issues (such as update of the coordinates of the cursor position 
when the mouse moves in the window).

Michiel also came up with a better third approach, which addresses Munro's
concern about the if-test eliminated in u_waiter as well as the performance
issue mentioned.  This approach is now the default and works everywhere 
tested (as does the second).   

Finally, Munro provided an interface u_wait_stdin for PyGist.  PyOS_InputHook
is set to this routine, and the other approaches have been removed with
the update to Yorick 1.5.13.

NOTE:
When we say that PYGIST does not work, we mean it gives blank or incomplete 
displays (usually in plots 1 through 8 of the gistdemolow.py test).

------------------------------------------------------------------------
READLINE REQUIREMENT
------------------------------------------------------------------------

Python 2.0 required one to edit Modules/Setup to enable READLINE, but later
versions handled this automatically.  However, ...

Initially, it appeared as if there were problems with this second 
approach on one Linux server (rooster on the closed side), Solaris, and 
IRIX64, but the culprit was found to be the fact that the Python configuration 
did not find the readline library.  When Modules/Setup was changed to give 
the location of the static libreadline.a, pygist then worked on these 
platforms.

On Linux (if readline is not enabled):

   readline -I/usr/include readline.c -Bstatic -L/usr/lib -lreadline \
      -Bdynamic -ltermcap

On tr64_5, Solaris, and IRIX64, edit Modules/Setup to include:

   readline -I/usr/local/lib readline.c -Bstatic -L/usr/local/lib -lreadline \
      -Bdynamic -ltermcap

On AIX, use:
   readline -I/usr/local/lib readline.c /usr/local/lib/libreadline.a -ltermcap

Touch the readline.c files, and remake python:
   touch Modules/readline.c
   gmake install

Use of static libreadline.a avoid problems with different versions of 
libreadline.so on machines with essentially the OS.  

------------------------------------------------------------------------
INSTALLATION
------------------------------------------------------------------------

Scripts to facilitate installation described below:

- ./install      (for generic install)
- ./llnl_install (for public installation at LLNL)

NOTE:  At LLNL SCF (Sapling cluster), the public python is compiled with
       the vendor C compiler, which has been changed.

       setenv DEC_CC -nodtk
       
       before running llnl_install.

Prerequisites:

- We assume that you have Python (2.1 or later) with the Numeric package 
  installed.  
- Furthermore, pygist requires the Gnu readline package. In previous
  versions of Python, it was necessary to edit Modules/Setup to turn 
  readline on and tell it where the library is.  However, current installation
  determines whether the library exists during configuration and the feature
  is enabled if it exists.
  On some platforms, it is necessary to edit Modules/Setup to indicate
  the location of the readline library.

pygist depends on portions of the Yorick library.  To avoid a 
complete installation of yorick, the relevant subdirectories (gist and play)
have been extracted from Yorick and placed in the src directory of the
pygist distribution.  

In addition to installing the extension and Python modules in the appropriate 
place in the Python installation, the installation also installs Gist data
files in a subdirectory ``g'' and the gist browser in the ``bin'' directory
of the Python installation directory. 

Suppose the Python installation directory is /usr/apps/python/opt.

   setenv PYTHONHOME /usr/apps/python/opt

On Cygwin, Windows, and Mac OS X:

   python setup.py config 
   python setup.py install

Due to a bug in python distutils, it is necessary to use the former
configuration step on Unix/Linux:

   cd src; make config; cd ..
   python setup.py install

To install the gist viewer:

   cd src; make Y_SITE=${PYTHONHOME} ysite; make config; make; make install


LLNL NOTE:  Run fixPygistPermissions to ensure permissions are correct
            after installation. 

LLNL NOTE: On local A-net, use the global path, e.g.,

   setenv PYTHONHOME /usr/gapps/python/redhat_7_ia32/opt

because the /usr/apps soft links to /usr/gapps are only available on the 
server machines, so users on other machines will not have the correct 
path to style files. 

------------------------------------------------------------------------
SAMPLE ENVIRONMENT SETTINGS for LLNL:
------------------------------------------------------------------------

setenv PYTHONHOME /usr/apps/python/opt

set path = ( ${PYTHONHOME}/bin $path )

setenv PYTHONPATH .:${PYTHONHOME}/lib/python2.2:${PYTHONHOME}/lib/python2.2/lib-
tk:${PYTHONHOME}/lib/python2.2/lib-dynload:${PYTHONHOME}/lib/python2.2/site-pack
ages:${PYTHONHOME}/lib

------------------------------------------------------------------------
INTERNAL DETAILS
------------------------------------------------------------------------

The setup.py script will make a dependent library libpyg.a as well as 
the gist browser.  It also install the browser and some data files. 
So in the setup.py is a system call to do the following:

   cd src
   make Y_SITE=${PYTHONHOME} ysite (not required because GISTPATH is now 
                passed as a define to setup in setup.py)
   make config
   make
   make install

The extension module gistCmodule.so to be created depends on libpyg.a 
just produced and the external libX11.a, part of the standards 
X11 distribution.  

Test:
-----

To test pygist:

  python
  import gistdemolow
  gistdemomlow.run()
  (ctrl-d)

For online help:

  python
  from gist import *
  help(plm)    for info on plm (plot mesh)

Problem with installation with Cygwin:
-------------------------------------- 

FPU_GCC_I86 does not work.

   cd src/play/win
   (Edit config.h, hardwire(#define FPU_IGNORE), and proceed with make.)

Problem with installation on AIX: (fixed in Python 2.2.1)
---------------------------------

First,
You may encounter the following problem when running python setup.py:

building 'gistCmodule' extension
skipping src/gistCmodule.c (build/temp.aix-4.3-2.1/gistCmodule.o up-to-date)
/g/g16/chase/aix/lib/python2.1/ld_so_aix cc_r -bI:/g/g16/chase/aix/lib/python2.1
/python.exp build/temp.aix-4.3-2.1/gistCmodule.o -L. -Lsrc -lpyg -lX11 -o build/
lib.aix-4.3-2.1/gistCmodule.so
ld_so_aix: Import file '/g/g16/chase/aix/lib/python2.1/python.exp' not found or
not readable; exiting.
error: command '/g/g16/chase/aix/lib/python2.1/ld_so_aix' failed with exit status 2

The problem can be fixed by going into the python installed and fixing two 
incorrect links:

   cd /g/g16/chase/aix/lib/python2.1
   rm makexp_aix
   ln -s config/makexp_aix makexp_aix
   rm python.exp
   ln -s config/python.exp python.exp

The installation incorrectly linked them to ../config instead of config.

Second,
AIX does not seem to pick up libreadline.a automatically. Uncomment the
two lines indicated in setup.py before doing python setup.py build.


Lila Chase
lchase@llnl.gov
Lawrence Livermore National Laboratory
Box 808 L-22 
Livermore, CA, USA 94551