                           Project Riemann Code


INTRODUCTION

Dr. Franz-Erich Wolter developed algorithms to compute the geodesics and
curvature lines on algebraic surfaces.  We, his research assistants, turned 
the algorithms into the C source code that you currently have.  This file 
describes what geodesics and curvature lines are, what our programs do, how
to compile these programs, how to print the documentation, and what's in all of
the directories that you've received.  This file also includes some history of 
the project and acknowledgements.  If you have any problems you can send me, 
Bret Johnson, E-mail at johnson@medusa.cs.purdue.edu or 
gaq@mentor.cc.purdue.edu.  With luck, one of these accounts will be active when
you send the mail.

A geodesic is a curve that traces the shortest distance between two points 
on a surface.  Both the points and the curve are on the surface.  Our geodesics
programs start with an initial point and "shoot out" geodesics from that point,
thus giving something of the appearance of spokes on a bicycle wheel.  The
distance on the surface between the endpoint of each geodesic and the initial
point is the minimum distance on the surface between those two points.

A curvature line is a curve on a surface such that the curvature of the
surface at each point on the curve is constant.  Our curvature line programs
compute several curvature lines in two orthogonal directions to generate a
mesh of curvature lines on the surface.  The appearance is something like if
a fishing net were superimposed on a algebraic surface.


PROGRAMS

This package contains five principal programs: symgeod, numgeod, impcurv, 
parcurv, and xdisp.  Symgeod and numgeod generate geodesics on implicitly 
defined surfaces.  Symgeod does its work symbolically while numgeod does its
work numerically.  Impcurv generates the curvature lines on implicitly defined
surfaces.  Parcurv generates the curvature lines on parametrically defined 
surfaces.  We didn't complete the program which generates geodesics on 
parametrically defined surfaces, so it is not in this package.  All four of the
math programs generate their output in a format that can be read by a person or
by our X-Windows Version 11 graphics display program xdisp.


COMPILING THE SOURCE

To compile the source, simply change to the src directory and type 
"make install".  This will compile all of the math source code and install the
symgeod, numgeod, impcurv, and parcurv executables in the bin directory.  To
compile xdisp, change to the src/xdisp directory and type "make install".  This
will compile the xdisp executable and install it in the bin directory.  Note 
that to use the xdisp program, you must have a workstation that runs X-Windows
Version 11.  You may wish to customize the make files so that the C compiler is 
invoked with special floating point options, make runs in parallel on Sequent 
Symmetries, and so on.  You may also wish to run "make clean" in the src and
src/xdisp directories to clean out any old object files, executables, tag files,
and the like before compiling the programs.

The xdisp executable is compiled separately from the other executables because
some users may choose to compile it on a different machine.  The math programs
run best on a large computer, preferably one with fast floating point 
operations.  The xdisp program runs best on a fast graphics workstation.  
However, because X-Windows is a network transparent system, you can run xdisp on
a mainframe (or any computer that has X11 libraries and is on the network), 
using your X11 workstation more-or-less as a terminal.  In order to pipe the 
output of the math programs to xdisp, all the programs must run on the same 
machine.  The only disadvantage of running xdisp on a computer other than the 
graphics workstation that you sit in front of is that sometimes having to send 
lots of information over the network slows down X-Windows programs.

The parametric curvature line code contains parts that are only compiled if the
MOEBIUS is defined.  MOEBIUS is not defined by default.  This code was added by
Jim Lambers in an attempt to compute the curvature lines on a Moebius strip.  We
managed to compute some of the curvature lines but Jim later figured out that
there is no way to compute the curvature lines all the way around the strip with
just one parameterization.  Nevertheless, I've left the code in in case it is of
interest to anyone, including Jim.


RUNNING THE PROGRAMS

In order to run the programs, it is convenient to put the bin directory in your
path.  The programs are easy to run; see DOCUMENTATION below.

In order to run xdisp, you first must run X-Windows Version 11 and preferably a
window manager.  Then you must set the DISPLAY environment variable to tell the
computer what graphics workstation to send its output to.  If you are running 
xdisp locally, you should probably set DISPLAY to "unix:0.0" on your local 
workstation.  If your are running xdisp remotely, you should probably set 
DISPLAY to "hostname:0.0" on the remote machine, where "hostname" is the name of
the local machine.  Also, if you are running xdisp remotely then you must give 
the local machine permission to accept data from the remote machine via the 
xhost command.  To do this type "xhost +hostname" on the local machine where 
"hostname" is the name of the remote machine.  You can refer to the X and xhost
man pages for more information.


DOCUMENTATION

To view the documentation on the screen, change to the docs directory and type
"nroff -man file | more" where "file" is "geodesics", "curvature", or "xdisp".
To print the documentation on a PostScript printer, change to the docs directory
and type "troff -Pprinter -man file" where "printer" is the name of the 
PostScript printer and "file" is one of the three previously mentioned files.


DIRECTORIES & FILES

bin     - This directory is where the executables are installed by "make
          install".  This is a good directory to put in your path.

data    - This directory contains some sample output files generated by our
	  programs.  Curvature line files end in ".cl" while geodesics files
	  end in ".g".  You can look at these files with xdisp.

docs	- This directory contains the nroff and troff source files for the 
          documentation.

src     - This directory contains all of the source code.  The standards file
	  in this directory is a list of programming style standards, including
          a description of all of the type prefixes.


HISTORY AND ACKNOWLEDGEMENTS

Steve Cutchin and Tom Hausman wrote the forerunners of these programs in Common
LISP in the summer of 1988.  They utilized Cornell math routines.  In the fall
of 1988 we decided to convert the programs to C.  I (Bret Johnson) wrote some
vector routines, the user interface, the output routines, the polynomial
parser, and the xdisp program.  Scott Goehring wrote the expression parser and
many expression routines.  Jim Lambers wrote the main code for our four math
programs.  

Come the summer of 1989 most of the code was finished.  Jim Lambers and Scott 
Goehring went home for this summer but I stayed to finish polishing the code.  I
didn't try to understand most of Jim or Scott's code but did make some changes 
to it.  Mostly I polished my own code and that is the reason that I think you
will find my code to be better documented and perhaps more bug-free than Jim
or Scott's.  I also wrote all of the documentation.

