
                         PGPLOT-CL 1.1

     A CMUCL interface to the PGPLOT scientific plotting library.
 
================================================================ 

The PGPLOT lisp package contains CMUCL support for the PGPLOT 2-dimensional
graphics library, a Fortran and C library of publication quality
plotting code supporting X11, Postscript, and other formats.

Information on PGPLOT, including extensive documentation and
copyright, is at http://www.astro.caltech.edu/~tjp/pgplot/

The PGPLOT C and Fortran libraries and source code are not public
domain software, and may not be redistributed.  However,
they are freely downloadable for non-commercial use from
http://www.astro.caltech.edu/~tjp/pgplot/
Commercial use requires contacting the author.

The LGPL license terms of this software (the Lisp interface to
pgplot) are described in the file LICENSE.  

================================================================

New in version 1.1

  * image plots (ie, using color to represent z values on x,y plane)
  * support for contour labels (though pgplot's contour labels seem
    buggy, and the angle of the label is sometimes wrong)
  * doc strings for most functions, providing rudimentary documentation
  * (with-pgplot-settings (...) ...) macro for temporarily changing a 
    pgplot's settings
  * various small bugfixes


================================================================

Files included in the PGPLOT lisp package:

    README         - this file

    LICENSE        - the LGPL license terms of this software (not of
                     the pgplot library)

    pgplot.lisp - the non-lisp-implementation-specific pgplot routines,
                  defining the user interface to pgplot

    pgplot-cmucl-libs.lisp - CMUCL loader for the pgplot, X11, Fortran, etc
                             libraries required for pgplot to work

    pgplot-cmucl.lisp  - CMUCL FFI definitions for pgplot library

    pgplot-examples.lisp - demo plots - run (run-all-demos)


================================================================
Documentation
================================================================

There is no documentation besides this file.

pgplot-examples.lisp provides some simple examples, and the rest can
be gleaned from reading pgplot.lisp and the pgplot fortran library
documentation, though the latter should not be necessary for most
things.

Many plotting functions have lots of keyword arguments, some of which
are relatively transparent, and others of which are rather
indecipherable.  

================================================================
Instructions for compiling and loading pgplot for CMUCL
================================================================

    1) place all pgplot lisp files into a directory which is in 
       CMUCL's load path

    2) create a pgplot.o object file to be dynamically loaded by
       pgplot-cmucl-libs.  Note that this file uses the C pgplot 
       interface, not the low level Fortran library.

       This step can be a bit tricky; one would think that just loading a
       simple object file linked to libcpgplot.a might work, but it
       didn't work for me.

       The following procedure works for me in Linux and Solaris

       a) enter a temporary empty directory, and break up libcpgplot.a 
          into .o files 

            mkdir tmp_pgplot
            cd tmp_pgplot
            ar -x /your/lib/directory/libcpgplot.a

       b) then produce a single object file cpgplot.o from these 
          object files, and move it to where you keep
          cmucl's FFI .o files that you want to load at runtime
      
            ld -r *.o -o cpgplot.o
            mv cpgplot.o /home/smith/lib/lisp/dynamic-objects/

    3) in your lisp initialization, define a variable 
       cl-user::*dynamic-obj-directory* that contains a string
       representing the directory where cpgplot.o can be found

       for example

       (defparameter cl-user::*dynamic-obj-directory*
                     "/home/smith/lib/lisp/dynamic-objects/")



       also, define the libraries that pgplot needs to load using
       the variable cl-user::*pgplot-libraries*

       for example, the following works in my version of Debian Linux 

       (defparameter cl-user::*pgplot-libraries*
                '("-lpgplot" "-lc" "-lz"
                  "-lpng" "-lcpgplot" "/usr/X11R6/lib/libX11.so.6"))


       and the following seems to work for Solaris:
  
       (defparameter cl-user::*pgplot-libraries*	
              '("-lpng" "-lz" "-lpgplot" "-lc" "-lcpgplot" "-lF77" "-lM77"
                 "-lsunmath"))


       make sure your LD_LIBRARY_PATH contains the directories
       for all of the libraries before starting CMUCL.

       If you get error messages about unknown foreign symbols when
       you try to load pgplot into cmucl, you are probably missing
       some important library.  The tricky bit is that pgplot requires
       various obscure Fortran libraries that the Fortran linker would
       normally link in for you, but here you need to figure them out
       yourself.  You may need to put the locations of these libraries
       in your LD_LIBRARY_PATH environment variable before starting
       CMUCL.  Also, the order in which the libraries are loaded seems
       to matter.  And the libraries have changed with the last
       release of pgplot library; be sure to get the latest one.

       Getting the libraries to load seems to be the biggest obstacle
       to getting PGPLOT-CL to work.  One way to debug this is to use the
       Lisp REPL to play with various values of
       cl-user::*pgplot-libraries* as follows:

         a) SETF cl-user::*pgplot-libraries* to what you think might work
	    (see above for a suggested starting point)      

         b) try running the following:

              (load-foreign (concatenate 'string 
                             cl-user::*dynamic-obj-directory* "/" "cpgplot.o")
                            :libraries *pgplot-libraries*)
       
         c) if this works, you should be all set, if not, goto (a),
            change cl-user::*pgplot-libraries*, and try again.	
	    You may need to poke around the libraries to see which libraries
	    contain the foreign symbols you are missing.  Google
	    might be your friend here, as other people have
	    probably had the same problem with different software.

    4) in your lisp initializtion, also do 

       (setf (ext:search-list "pgplot:") 
          '("/where/you/put/the/files/of/pgplot-cl/"))

       You need this because pgplot loads its components as
       (load "pgplot:XXXX")


    5) enter the directory where you have put the pgplot lisp files, and
       do (in lisp)

         (load "pgplot.lisp") 
         (compile-file "pgplot-cmucl.lisp")
         (compile-file "pgplot.lisp")
         ;; don't bother to compile pgplot-cmucl-libs.lisp

    6) to load pgplot, now do (load "pgplot")
  
       to test it, try 
     
             (defparameter *p* (pgplot:open-device :x11))
             (pgplot:box *p*)
             (pgplot:close-device *p*)

       this should pop up an X11 window, draw a box, and close the window.
       
       If you lose track of a window (eg, you didn't bind it to a variable),
       just do (pgplot:close-all-devices)

       For more examples, you can try
             
            (load "pgplot-examples")
	    (run-all-demos)
      

================================================================
Sample initialization to place in your init.lisp
================================================================

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; initialization to allow pgplot to run (eg, in init.lisp)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;; define pgplot libraries (may need to fiddle with these)
;; [be sure that LD_LIBRARY_PATH environment variable can access
;;  these libraries]
#+linux
(defparameter cl-user::*pgplot-libraries*
                '("-lpgplot" "-lc" "-lz"
                  "-lpng" "-lcpgplot" "/usr/X11R6/lib/libX11.so.6"))
#+solaris
(defparameter cl-user::*pgplot-libraries*	
              '("-lpng" "-lz" "-lpgplot" "-lc" "-lcpgplot" "-lF77" "-lM77"
                 "-lsunmath"))
;;
;; define where to find "cpgplot.o" created from cpgplot library
(defparameter cl-user::*dynamic-obj-directory*
                     "/where/you/put/cpgplot-dot-oh/")
;; define search path pgplot:
(setf (ext:search-list "pgplot:") 
      '("/where/you/put/the/lisp/files/of/pgplot-cl/"))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

================================================================
Basics of pgplot
================================================================

pgplot:open-device creates a pgplot device, which a CLOS object

various plotting methods operate on the device, eg

(defun do-simple-plot ()
       ;; create the device
       (let ((p (pgplot:open-device :x11))) ;; open xwindow device
           ;; draw a box in default unit coordinates of device
       	   (pgplot:box p)    
	   ;; connect x,y=(0.1,0.2) to x,y=(0.9,0.8)
           (pgplot:connect p #(0.1 0.9) #(0.2 0.8) 
	       :color :blue         ;; optional
	       :line-style :dotted  ;; optional
	       :line-width 3)       ;; optional
	   ;;
           ;; make axis labels
           (pgplot:xlabel p "X")
           ;; note pgplot notation for exponent, and required doubling
           ;; of backslash because lisp consumes one backslash itself
           (pgplot:ylabel p "Y (fathoms\\u2\\d)") 
           ;;
	   (format t "Hit return to close pgplot device~%")
	   (read-char)
           (pgplot:close-device p)))


More examples are in pgplot-examples.lisp
Load pgplot-examples.lisp, and type (run-all-demos)

================================================================
Bugs and Quirks
================================================================

* pgplot does not support more than 8 simultaneously open devices

* pgplot supports single floats only; generally, the lisp routines can
  take any sort of numbers, but numbers outside single float range
  are truncated

* lots of features of the pgplot library are not supported - eg, contour labels

* Solaris/Sparc version seems to have a quirk - sometimes a math
  exception occurs when closing a device.  This seems to be inside the
  pgplot library code.  We could fix this by clearing math errors
  inside lisp routines, but it doesn't happen too often.

* The postscript generated by pgplot seems to be encapsulated
  (contrary to statement in release 1.0 of this file).

  to generate postscript, open device as 
   (pgplot:open-device :ps :filename "foo.ps")
  

================================================================
Author
================================================================

Please send bug-fixes and contributions to 

     kleyna at ast.cam.ac.uk

Please do not publish this email address outside this file,
or place this file directly on the web outside a tarball 
(to prevent the above address from being inundated with spam).









