July 10 1992, written by Masakazu Furuichi of MITSUBISHI ELECTRIC
              Email: furuichi@isl.melco.co.jp

This README briefly describes the following ICOT Free Software.

        "PIMOS Load-balancing Utility"
        (1) Stack splitting dynamic load balancer (STB)
        (2) Multi-level dynamic load balancer (MLB)

1. Description of this software
-------------------------------

This software is a set of load-balancing utility which is applicable
to OR parallel type search programs. This utility program make it
possible for the programmers to concentrate in just writing search
part of the program, and dynamic load-balancing is done automatically
by this utility.

This software utilizes two types of load-balancing strategies as
follows. For the more detail, please refer to [1,2,3,4].

1.1 Stack splitting dynamic load balancer (STB) 

This utility program is applicable to the following type of search
program. "Search tree is described as a stack, and search is done by
the loop of popping one node data from the stack and expanding it and
pushing the child node data into stack".

Load balancing is done automatically by this system as follows.
When a processor become idle - when the stack become empty -, system steal
another data from the stack on another processor. When all of the stacks 
on every processor becomes empty, system detects the end of the execution.

User have to define following two predicates in a module "stb_solver".

  expand(NodeData,^SubNodeData,^Solutions)
	This predicate is called by the system when a NodeData
	is popped from the stack. User have to define this 
	predicate as to expand this NodeData and returns 
	expanded child data into SubNodeData, and solutions 
	into Solutions.

  combine(In,Out)
	This predicate is for to filter the solutions derived
	in a processor. This process is spawned on each processor
	by this system.  The output Out from every processors are
	merged on a processor by a merge builtin predicate.
	Sample code for this combine predicate is as follows

	* Calculate the sum of the solutions
                combine(In,Out):- true   | sum(In,0,Out).
                sum([],    S,Out):- true | Out=[S].
                sum([X|Xs],S,Out):- true | sum(Xs,~(S+X),Out).

        * Just merge the solutions
                combine(In,Out):- true | merge(In,Out).

To use this STB utility, module stb (file STB.kl1) must be compiled or
loaded. After the user defined module stb_solver is compiled, re-link
those modules before the execution.

This is the end of the explanation of STB. Please refer to [3,4] for 
the more detail of this scheme and the usage of this utility program.

1.2 Multi-level dynamic load balancer (MLB)

This utility program is applicable to the following type of search
program. "Deepening a search tree is represented as spawning child
search process. When it reaches the leaf node, process terminates and
the results are collected through merged stream". User will map
processes to idle processor, and this MLB utility gives the way to 
tell which processor is idle.

Child processes are generated by a master processor, and load
balancing is done by mapping search process to idle processor.
However, as the number of processors becomes large, a processor who
generates child process becomes bottleneck. Therefore mapping should 
be done hierarchically - Multi-level -.

This is the end of the explanation of STB. Please refer to [1,2,4] for 
the more detail of this scheme and the usage of this utility program.

2. Environment
--------------

This utility program is run on the following system.
	STB: Multi PSI, PIM/m, PIM/p(probably)
	MLB: Multi PSI, PIM/m, PIM/p

	PIMOS 3.0 or later version
This utility program can be run on Pseudo Multi-PSI or Pseudo PIM/m,
but the load balancing is not done in correct.

3. Files
--------

1) Stack splitting dynamic load balancer STB:

    Source program: STB.kl1         (module name: stb )
                    STB_SOL.kl1     (module name: stb_solver)

    Note: STB_SOL.kl1 contains dummy module, and user have to 
	  define expand/3 and combine/2 predicates in this module.

2) Multi-level dynamic load balancer MLB:

    Source program: MLB.kl1         (module name: multi_level_load_balancer)

3) Documents 
        README.j        README file (in Japanese)
        README          this file
        INSTALL.j       installation guide (in Japanese)
        INSTALL         installation guide
        balman.ps       reference manual [4] in postscript 
			(in Japanese)
4. Install
----------

1) Stack splitting dynamic load balancer (STB)

  Just compile MLB.kl1. 

2) Multi-level dynamic load balancer (MLB)

  Compile STB.kl1 and STB_SOL.kl1.
  User have to redefine stb_solver module (STB_SOL.kl1) to use your 
  program.


5. References
-------------

[1] M. Furuichi, K. Taki, and N. Ichiyoshi
     ``A Multi-Level Load Balancing Scheme for OR-Parallel Exhaustive
       Search Programs on the Multi-PSI'' 
    In Proc. of the 2nd ACM SIGPLAN Symposium on Principles and
    Practice of Parallel Programming}, pp. 50-59, Mar. 1990


[2] M. Furuichi, K. Taki and N. Ichiyoshi
     ``$BAB7k9gJBNs7W;;5!>e$G$N(B OR$BJBNsLdBj$KE,$7$?(B $BF0E*Ii2YJ,;6J}<0$H(B
       $B$=$NI>2A(B''.
     In Proceedings of KL1 Programming Workshop '90, pages 1-9, 
     Mar.1990. (In Japanese)

[3] M. Furuichi, K. Nakajima, H. Nakashima, and N. Ichiyoshi
      ``$B%9%?%C%/J,3dF0E*Ii2YJ,;6J}<0$H%^%k%A(BPSI$B>e$G$NI>2A(B''.
     In Proceedings of KL1 Programming Workshop '91, pages 51-58, 
     Mar. 1990. (In Japanese)

[4] M. Furuichi
        PIMOS $BIi2Y%P%i%s%9%f!<%F%#%j%F%#%^%K%e%"%k(B
                $B%9%?%C%/J,3dF0E*Ii2Y%P%i%s%5!<(B (STB)
                $B%^%k%A%l%Y%kF0E*Ii2Y%P%i%s%5!<(B (MLB)        
     It will be published as ICOT TM.
     The source of this document is contained in this directory
     as balman.ps(Postscript).

