heat-transfer.tcl   	version 0.9		June 26, 1998
-----------------------------------------------------------------------------
USAGE: heat-transfer.tcl [cmap <file>] [#]

	where cmap indicates the user wants to use a custom color map
	(indexed form -- use icol), and file is the filename of the
	color map

	and where # is a numerical value, stating the number of image
	files the user wishes to have created.


  heat-transfer.tcl is an interface for a heat-transfer simulation 
program.  The simulation was written by Wenlong Dai, and the interface 
was designed and written by Christopher White.

  When starting the program, the user has a choice of command-line
arguments.  These include:

  A number: States how many image files are desired.  The higher the 
            number, the smoother the resulting movie will be, but the
            more hard drive space is required; there is little speed
            difference however.

  cmap <filename>: The keyword 'cmap' followed by a filename containing
                   a colormap.  The program will then use that color-map
                   when displaying the movie.  Make sure the colormap is
                   in indexed form!  Use 'icol' to create it.

  After the user starts the program, they are presented with a list of 
materials.  They must select one of these materials to be the "base" 
material for the simulation.  Think of this as a plate where other 
objects of various temperatures will be placed.

  Next, the main display screen will appear.  This is a large square 
surrounded by four sliders.  Each slider represents the temperature being 
applied to the side of the plate.  The user can now add more objects to 
the plate.

1) Put the mouse cursor over the large square.  
	- Notice that the arrow now becomes a pen.

2) Click and hold the left mouse button
	- This places the first corner of the box

3) Drag the mouse around (with the mouse button still down!)
	- This draws the box on the main plate.  The size and shape of
	  the box is displayed, and can be changed until the left mouse
	  button is released.

4) Release left mouse button
	- Once the left mouse button is released, the box is placed, and 
	  the material list is presented again.  This dialog refers to the
	  material you just placed on the main plate.

  The user may add as many objects onto the main plate as they wish.  
After all desired objects have been placed, the user must click on the 
"Start" button located in the lower right hand corner of the main window.
This will bring up a dialog box indicating that the image files are being 
created.  Since this process is very time consuming, the user has the 
option of viewing the movie at any time by clicking the "Movie" button.  
This will call the xraz program (see REQUIREMENTS), which will display 
all frames that have been computed.  The user may exit xraz, then click 
on the "Movie" button again to view more frames, since the frames are 
still being calculated as the movie is being shown.  To stop the 
simulation, click the "Stop" button.  When all of the images have been 
created, the "Stop" button changes to "Done" and is to be clicked when 
the user is done viewing the movie, or wants to save the script/movie.

  After stopping the program, the user can either quit the program, edit 
the existing design, save the current movie, or save the current script 
used to create the movie.

FILE MENU

  Under the FILE menu are 5 choices:

	1) Run Script ----- This is used to load in a previously saved script
			    to create the movie again.  This is slower than
			    saving the actual movie, since the movie must be
                            recreated to be viewed again, but uses much less
                            disk space.

	2) Save Script As - This saves your current script; note that you
			    must be finished with the design before saving,
			    as there is no way to modify a saved script (see
			    LIMITATIONS).

	3) Open Movie ----- This option will display a previously saved movie.
			    This is much faster than running a script, since
			    the image files are already saved, but takes up
			    much more disk space.

	4) Save Movie ----- This option is used after you have created a
			    movie and wish to save it.  Be aware that the
			    more frames the movie contains, the more disk
			    space is required.

	5) Quit ----------- End the program; this is the same as the Quit
			    button in the lower left hand corner of the 
			    main screen.


REQUIREMENTS

  WISH8.0

 	In order to run this program, wish8.0 must be installed on the
	system.  By default, the program looks in /go/local/bin/wish8.0.
	Edit the first line of heat-transfer.tcl to point to the location
	of wish8.0 on the system.  Be sure to leave the first two characters
	of the line alone (#!).

  RAZ/XRAZ

	raz and xraz must both be available on the system, and both should
	be in the user's PATH variable.  If not, then the movie will not
	be shown.

  X128/X256

        These two files are the main binary program which do the actual
        calculations.  If you're having problems running the program, try
        recompiling the binaries.  The source code is located in the /src
        directory, along with a script, compile-heat2d.  Run the script,
        which will recompile the two binaries and automatically place them
        in the main heat-transfer directory.  Although the pre-compiled
        binaries should work for most people, it will not work under all
        architectures.

INCLUDED FILES

  README

	This file!

  cmap_convert, creatCbar, origcmap, make-tbar

	These files are used to create the colorbar when you are viewing
	the movie.

  x128/x256

	This is the main program which does all of the computations.  While
	it can be run interactively, it is highly recommended that you use
	the heat-transfer.tcl interface instead.  Some features are only
	available through that interface.

  heat-transfer.tcl

	This is the main interface which controls the heat2d program.  This
	is the only program the user will need to worry about, as it makes
	calls to all of the other programs.

  xrazscript.128/xrazscript.256

	This is a configuration file used to start up xraz.  Do not modify
	it.

  ./src/*.*

	This directory includes the source code for the heat2d program.  If
	you receive an error when starting this program, please recompile
	the fortran code (using the compile-heat2d script).  The resulting
	executable will be instantly put in the main directory, and you
	can run the heat-transfer.tcl interface again.


LIMITATIONS/IDEAS FOR FUTURE VERSIONS

	1) Once a box is drawn on the screen, its properties (size, temp,
	   material, location) can not be changed.

	2) If a box is started, and then the user changes their mind and
	   no longer wants the box, there is no way to back out; a kludge
	   to this is to simply set the new material to the same material
	   and temperature as the main material.  However, if the box
	   overlapped several other boxes, this no longer works.

	3) If the user closes the raz window instead of the xraz window,
	   the heat-transfer program, as well as xraz, crashes.  ALWAYS
	   USE THE EXIT OPTION IN THE XRAZ PROGRAM!  This is a bug in xraz.

	4) When creating the movie files, the user may click "Movie" to 
	   view the movie up to the current point.  Multiple clicks will
	   bring up multiple copies of xraz, which is unnecessary.

	5) When selecting a colormap file, the colormap MUST be in
	   indexed form, or the colormap will fail.

	6) The movie does not display in real-time; you must click the
	   "movie" button to view the progress up to that point.

	7) The program must be run from a users' home directory.

HEAT-TRANSFER CONCEPTS

	For more information on the process of heat-transfer, please see 
the paper:

Numerical Simulations for Nonlinear Heat Transfer in a System of Multimaterials
By: Wenlong Dai and Paul R. Woodward,
Journal of Computational Physics, vol.139, pp.58-78, 1998.

BUG REPORTS

	Please report bugs/comments/suggestions to:
		white@lcse.umn.edu
		wenlong@lcse.umn.edu

Heat-Transfer, version 0.8
Copyright 1998, All Rights Reserved
