=========================================================
|| XPMAP => X-interfaced Parallel running MAPping tool ||
=========================================================


===========	=====	=====	=====
Instalation
===========	=====	=====	=====


1.
Unzip and untar all (23+) files into some empty folder.

2.
Set the environment variable BINDIR to path where your PVM binaries are
stored. Set it either in shell or in the first line in the Makefile.

3.
Run "make" (and then "make install" to save disk space by stripping binaries).
Make will built 2 binaries: pmap and xpmap in the BINDIR folder.
(Or only first one if your system has not Motif 1.2 libraries
 -> mapping will run without X interface.)

4.
If the BINDIR folder is not on the path, add path to it or 'cd' to it.

5.
You can change file names, but they must follow this order:
1-st binary (without X-interface): 
	name must begin with character OTHER than 'x' or 'X'
2-nd binary (with X-interface running distributed on the PVM):
	name must be compound of 'x' (or 'X') and name_of_1-st_binary

6.
In the PVM_root host (where is running GRED) both these binaries must be
correctly installed. In the other PVM hosts only 1-st binary must be
installed and its name must be the same for all of PVM hosts.
Correct installation should be done in the way, that any PVM host will spawn
this binary successfully. It means that this binary should be on the
pvmd spawn path (either default or specified by ep=...). If it is not true,
program will tell it.

7.
Remark: If you wish to run our mapping tool without PVM, i.e. only sequential,
use "make mx" (and then ,ake "install") instead of "make". It may run faster
because of the PVM starting process overhead and PVM communication.

8.
Remark.2: This package contain also supporting programs, like "pvmadd", "pvmhalt",
"trace", "map" (without PVM and without X), "xmap" (as in 7.). 

9.
For installing it into GRADE/GRED environment, you shuld copy or link these
two scripts into GRADE_ROOT directory:
	gred-mp
	gred-hw
and start mapping with Options/Mapping menu or with Option/HW Config. menu.


=======	=====	=====	=====	=====
Usage
=======	=====	=====	=====	=====

xpmap app_name [method]
pmap app_name [method]

Result: 1) stored back into the application file (in GRP format)
	2) file $BINDIR/app_name.map for static/dynamic load balancer

Usage in the GRADE/GRED:

gred-mp app_name app_file grpsocket animsocket

the mapping starts by Options/Mapping menu
 and 
the HW-graph reading by Option/HW Config. menu.



Example of using "xpmap"
========================

Run command:

xpmap test.grp

The tool window appears on your display (the environment variable DISPLAY
should be correctly set).

If the 'question' window appears, choose OK.

Possible user actions:

- clicking on the "HW" button shows number of PVM hosts running
- clicking on the up/down arrows change the mapping "Method" (10 in 3 groups)
- clicking on the "View" button shows the extra window for view purpose
- clicking on the "OK" button starts/stops/restarts mapping process


Showed information:

- #HW, #Neighbr	- target size	(16-node 4-hypercube)
- #Tsk, #Chn 	- task size	(51-process task)
- chosen method			(one from 10 methods)
- LoadBal	- on/off	(switch for external dynamic load balancer)
- Estim, Elaps	- progress	(iteration, step, ...)


Example of using "pmap" (without X)
===================================

Run command:

pmap p7to4.grp a

All the implemented methods will map 7-process task onto 4-processor HW.


==============	=====	=====	=====
Extra features
==============	=====	=====	=====

The tool can obtain a HW-graph from running live PVM. It measures
connections and processor speed. The measured info is saved back into the
application GRP-file if there was no previous HW-info or user has choosen
not to use the previously stored HW-info and mapping was done with real running
live PVM instead.

When the tool is invoked with '-' (sign) instead of file name, the measured
HW-info will be saved into '_hw_.grp' file. This file can be used for
manual merging with some other GRP-application_file.

The tool autodetects input file format. The default is GRP-file. If the
input file has not the GRP syntax, the tool try use it as old-format SW-graph
file. In that case the second command line parameter (if any) should be the 
HW-graph file and potential third parameter can be the choosen mapping method. 
Next, if the mapping with that old format succeeds, the tool converts all the
input info and mapping result into GRP-file format. The name of this file will
be derived from the input file name.

If you want to generate an old-format HW-graph, then instead of '-' (minus sign)
use "-swhw" option. After this first parameter you may specify the output filename.

In the GRADE the command line has more parameters. The tool detects this
case and it correctly uses potentially different application_name and
application_file_name.

Extra usage:

xpmap -
pmap -
xpmap SW_graph_file [HW_graph_file [method]]
pmap SW_graph_file [HW_graph_file [method]]


=======	=====	=====	=====	=====
History
=======	=====	=====	=====	=====

Ver 0.3: Hg, Ng and ff are implemented as 2-dim.array: memory wasted.
Ver 0.4: Hg is implemented as 2-dimensional array: memory wasted. Ng is not
         transferred - decentralisation.
Ver 0.5: All the arrays are dynamic allocated + simple GRP-file parser added
Ver 0.53: int scroll is not boolean, but it means #lines of display
Ver 0.54: if .grp suffix is missing, program try to read with that suffix if
	  ordinary read fails
Ver 0.55: {}braces in GRP-file are counted and checked
Ver 0.56: GREDPATH environment variable is used in opening thr GRP-file
	  bad spawning path is managed -> tool runs in seq.mode
Ver 0.57: merging GRP-file is done via "grppars -G"
Ver 0.58: HW source conflict (from file / live PVM) is left up to user
Ver 0.6: Added input file format convertor, automatic detection of this
         format. Added automatic creator for missing ProgramPart.
Ver 0.7: Daniel's parser option -t is used instead of 'parsing' ProgramPart.
         Imbalance is computed in double precision (HME is slowed down).
         Mapping section is copied into temporary file and parsed in it.
Ver 0.8: fixed result filename, non-distributed versions were added,
	 DLB (LoadBal) switch was added, last result can be read
Ver 0.88: read trace file result - use fixed file names only
	  (trace.trf, pgrc, pgmap in $HOME directory)
Ver 0.88.4: last attempt to use VXP v2.0 : good bye!

Ver 0.9: Also master process will be managed (one without communication)
Ver 0.9.3: PG_PVM monitoring possibility added
Ver 0.9.4: Distributed versions of Simulated Annealing and HME methods are
	faster (slow worker can skip iteration or iteration can be killed)
Ver 0.9.5: Backward incompatible for HW-graph measuring! Also computing
	efficiency (power) is measured. Version checking added.
Ver 0.9.6: Mapping methods rely on the HW-graph "speed_time" values.
	Old-fashioned HW-graph output for "-swhw" option is added.
Ver 0.9.7: n-picl trace filter is added. Memory alloc bug in SA has
	been fixed (free(CC);CC=NULL;).
Ver 0.9.8: Master process communications are managed. Any filenames for trace
	can be used by environment variables (TRACEDIR, TRACE001, TRACE002
	TRACE003).  Waiting for stable trace file (until not growing) added.
Bug discovered while developing 0.9.8: order of linked Xm Xt X11 libs!
Memory write bug in SA has been fixed ( {}brackets were missing in for(i...)).

Ver 0.9.9: ?
