				  HEISENBERG

				      by

    Mark B. Phillips          William M. Goldman          Robert R. Miner     
      Mathematics	        Department of              Department of      
   & Computer Science	         Mathematics                Mathematics       
 University of Richmond     University of Maryland     University of Maryland 
  Richmond, VA  23173	   College Park, MD  20742    College Park, MD  20742 
			                                                      
  mbp@lakisis.umd.edu	      wmg@sofya.umd.edu          lena@sofya.umd.edu   
     (804) 289-8090	        (301) 454-2924             (301) 454-2991     


 ***************************************************************************
 *                          Copyright (C) 1990 by                          *
 *        Mark B. Phillips, William M. Goldman, and Robert R. Miner        *
 *                                                                         *
 *  Permission to use, copy, modify, and distribute this software, its     *
 *  documentation, and any images it generates for any purpose and without *
 *  fee is hereby granted, provided that                                   *
 *                                                                         *
 *  (1) the above copyright notice appear in all copies and that both that *
 *      copyright notice and this permission notice appear in supporting   *
 *      documentation, and that the names of Mark B.  Phillips, William M. *
 *      Goldman, Robert R.  Miner, or the University of Maryland not be    *
 *      used in advertising or publicity pertaining to distribution of the *
 *      software without specific, written prior permission.               *
 *                                                                         *
 *  (2) Explicit written credit be given to the authors Mark B. Phillips,  *
 *      William M. Goldman, and Robert R. Miner in any publication which   *
 *      uses part or all of any image produced by this software.           *
 *                                                                         *
 * This software is provided "as is" without express or implied warranty.  *
 ***************************************************************************

Heisenberg is an interactive graphics program for computation and
graphics in complex hyperbolic geometry.  It draws pictures in
Heisenberg space, the boundary of complex hyperbolic 2-space.  It runs
on Sun and IRIS workstations.

Heisenberg consists of two parts:

	(1) The graphics part, which runs on Sun and IRIS workstations.
	    This is in the 'graphics' subdirectory.

	(2) The Mathematica part, which runs on any computer running
	    Berkeley Unix and Mathematica.  This is in the
	    'Mathematic' subdirectory.

The two parts communicate with each other via Unix sockets, which allow
them to run on separate computers.  In general, Heisenberg will work on
a pair of computers if they can 'rlogin' to each other; the userids do
not have to be the same on both computers.  As a special case, of
course, the computers may be one and the same.

We call the computer on which the graphics part runs the 'graphics
host', and the one on which the Mathematica part runs the 'Mathematica
host'.  The graphics host must be a Sun workstation on which you can run
Suntools, or an IRIS 4D workstation.  You run Heisenberg while sitting
at this workstation.  The Mathematica host can be any Berkeley unix
computer which has Mathematica and to which you can rlogin from the
graphics host.

			     INSTALLATION

The installation and execution of Heisenberg is somewhat complicated by
the fact that the graphics part and the Mathematica part may run on
different computers.  In general, you must do two installations: one on
the graphics host, and one on the Mathematica host.  The process is
further complicated due to some inadequaces in Mathematica and in the
Suntools window system.  I apologize for this confusing state of things;
believe me, I have tried to make things as simple as possible given all
the possible configurations!  In the simplest case, where the graphics
host and Mathematica host are the same, installation and execution can
both be done with a single command each.

If the graphics host and the Mathematica host are the same computer, or
are of the same architecture (i.e. both Sun 3's, or both Sun 4's, or
both IRISes) and share a filesystem, you can use the master makefile in
this directory to do both installations at once.  Examine and modify as
necessary the configuration section at the top of this makefile, and
type 'make install'.  There should be no need to modify any of the other
makefiles in the distribution --- this makefile passes the configuration
settings down to them when it calls them.  If you do the installation
this way, you can skip the rest of these installation instructions.

If the graphics host and Mathematica host do not share the same
filesystem, or are of different architectures, you must do two separate
installations.

First, copy the entire Mathematica subdirectory to the Mathematica host.
Edit the configuration section at the top of the Makefile in that
directory, and type 'make install'.

Then copy the entire graphics subdirectory to the graphics host.  Edit
the configuration section at the top of the Makefile in that directory,
and type 'make install'.

Installation should now be complete.  The final products of the
installation are:

	on the graphics host:
		heisenberg:	executable graphics program
		elbowd:		executable daemon program
		startheis:	shell script for starting daemon
		heisenberg.help:	help file (needed at run-time)

	on the Mathematica host:
		Mathematica/Packages:
				directory containing Heisenberg
				Mathematica packages
		mathpipe:	pipe communication program
		Heisenberg:	shell script for starting Heisenberg
				(both parts)
		HeisMath:	shell script for starting just
				Mathematica part of Heisenberg

These files are installed in locations which you specify in the
makefile configuration section(s).  Do not move these files from their
installed locations; these locations have now been compiled into the
program, so the program will not work if you move them.


			  STARTING HEISENBERG

The way in which you start Heisenberg depends on the relationship
between the graphics host and the Mathematica host.  After you have done
the installation, the executable files which start heisenberg will be
located in the directory you specified in the Makefile(s) for
executables (make macro BINDIR).  If you used the default, this will be
either ./bin ( . is this directory ) if you compiled both the
Mathematica part and the graphics part at the same time, or
Mathematica/bin and graphics/bin if you compiled them separately.

If the graphics host and the Mathematica host are the same, you can just
execute the 'Heisenberg' shell script.  To run it, type

	Heisenberg <hostname>

where <hostname> is the name of the graphics/Mathematica host.  This
will start Mathematica and initialize both parts of Heisenberg.  The
graphics window will appear several (sometimes as long as 15 or 30)
seconds after Mathematica comes up.

If the graphics host and the Mathematica host are different but you have
the ability to 'rsh' to the graphics host from the Mathematica host
WITHOUT HAVING TO SPECIFY A PASSWORD, you can start Heisenberg by
running the 'Heisenberg' shell script on the Mathematica host. To do
this,

	(1) login at the console of the graphics host and start
	    the window system (Suntools on Suns, 4sight on IRISes).

	(2) open a shell window on the graphics host and rlogin
	    to the Mathematica host

	(3) in this rlogin session on the Mathematica host, run the
	    Heisenberg shell script with the command

		Heisenberg <hostname>

	    where <hostname> is the name of the graphics host.

If you do not have the ability to do password-less rsh between the two
hosts, you must do the following

	(1) login at the console of the graphics host and start
	    the window system (Suntools on Suns, 4sight on IRISes).

	(2) open a shell window on the graphics host

	(3) in this shell on the graphics host, run the shell script
	    'startheis'.

	(4) in this (or another) shell window, rlogin to the
	    Mathematica host

	(5) in this rlogin session on the Mathematica host, run the
	    HeisMath shell script with the command

		HeisMath <hostname>

	    where <hostname> is the name of the graphics host.

If you always use the same graphics host, you can eliminate the need to
pass that hostname to the Heisenberg or HeisMath shell scripts by
setting the environment variable ELBOWHOST.  Give the command

	setenv ELBOWHOST <hostname>

where <hostname> is the name of the graphics host; or put this command
in your .login to avoid ever having to give it again.

If the Mathematica host does not know the graphics host by name, you may
use the numeric Internet address (such as 128.8.134.19) of the graphics
host instead of its name.


			   USING HEISENBERG

Once the program is up and running, you should have two windows on the
screen associated with Heisenberg.  In one of them Mathematica is
running.  The other one is the Heisenberg graphics window.  In the
Mathematica window you can do computations as in any Mathematica
session, and you can use the graphics commands like gDraw, gErase, etc
to interact with the picture.  See the various example files in the
Mathematica/Packages directory.

In the graphics window you can interact with the picture in various
ways.  On Suns, the graphics window works like any other Suntools
program --- use the mouse to interact with the buttons, sliders, etc, in
the control panel.  For instructions on how to use the control panel,
hit the '?'  button; this causes a help window to appear.  For
instructions on how to use the IRIS graphics window, see the file
graphics/lgd/iris4/INSTRUCTIONS.


			  BEHIND THE SCENES

This section explains in more detail what the various shell scripts
which start Heisenberg do.  It is meant to help you in situations where
problems arise, or if you want to customize the startup process.

Before the Mathematica host can establish a connection to the graphics
program running on the graphics host, there must be an instance of the
'graphics daemon' running on the graphics host.  This is the program
'elbowd'; its purpose is to listen for connection requests on a certain
port number (1115 by default).

What really happens when you start Heisenberg, regardless of which shell
script(s) you use, is the following:

	(1) An elbowd is started on the graphics host; on Suns,
	    this must be done in the Suntools environment
	(2) Mathematica is started on the Mathematica host
	(3) The main Heisenberg package, Heisenberg.m, is read into
	    the Mathematica session
	(4) The command 'gConnect[]' is given in the Mathematica
	    session.  This initializes the connection to the
	    graphics host and starts the graphics program.

The 'Heisenberg' shell script uses 'rsh' to start an elbowd process on
the graphics host.  It then calls 'HeisMath' to start up Mathematica and
initialize the connection.

The 'startheis' shell script is for use on the graphics host in
situations where the Mathematica host can't use rsh to start the daemon.
'startheis' simply calls elbowd with the appropriate arguments.

The 'HeisMath' shell script assumes that the graphics daemon is already
running on the graphics host.  It starts Mathematica, and on the
Mathematica command line it tells Mathematica to read in Heisenberg.m,
and then give the command 'gConnect[]' before turning control over to
the user.

The gConnect[] and gDisconnect[] commands can be used to start and
terminate several connections to the Heisenberg graphcis program within
the same Mathematica session (but only one connection is allowed at a
time).  gDisconnect[] will shut down the graphics program and close
the connection.  gConnect will start up a connection to a new graphics
program.  There must be a graphics daemon waiting on the graphics host
before each gConnect[] command, however.  Since under normal usage the
graphics daemon terminates as soon as the graphics program starts
(i.e. in response to the gConnect[] Mathematica command), usually a
new daemon must be started on the graphics host before another
gConnect[] command can be given.

If you want the daemon to remain alive after starting the graphics
program, you can give the -cont argument to the elbowd program, or the
-immortal argument to the startheis shell script.  In this case the
daemon sticks around until you kill it.  It even survives
logins/logouts.  This way you can start the thing once and then forget
about it.  If you do this, you will not be able to use the Heisenberg
shell script, since this shell script always starts a new daemon.
Use HeisMath instead.

The graphics daemon monopolizes a Unix port, which means that there can
only be one daemon running on a given host at any given time.  If you
have trouble using the default port number (1115), see the comments in
the 'startheis' shell script for instructions on how to use an
alternate port numeber.

