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 where 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 where 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 where 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 where 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.