
  +---------------------------------------------------------------------+
  |  To users of the program:						|
  |    Group Problem Solving System for Task Allocation Problems	|
  |    (No.60, gpsstap)							|
  |									|
  |  **************** PLEASE READ THIS FILE FIRST ********************  |
  +---------------------------------------------------------------------+

				Mitstubishi Electric Corp.
				    Seiichi Shindo (shindo@sys.crl.melco.co.jp)
				    Masato Sumida  (sumida@sys.crl.melco.co.jp)


This file contains
* the outline of the function of the program: 
  You can get the further information on the algorithms of the program,
  by the reference at the end of this file.
* how to get the program run:
  For installation of our program, refer to another file "INSTALL".


=====<< 1. FUNCTION >>=========================================================

# OVERVIEW

  Our system searches for semi-optimal solutions for task allocation problems.

  We treat the following problem:

  GIVEN
    * a set of resources(e.g., workers),
    * a set of tasks(e.g., jobs) and
    * task evaluation functions defined by each resources(e.g., overtime),

  THEN
    find the allocation of tasks to resources which minimize the sum of the
    resources' task evaluation function values.

  For this problem, our system assigns random task allocation to
  agents(corresponding to resources one to one).  Then the agents try to change
  their task allocations, toward the globally optimal allocation, by iteration
  of task migrations among them, through the exchanges of messages.

  We have developed two algorithms.  One is called ITM-S(Iterative Task
  Migration-Synchronous), where a group of agents works in a synchronous way.
  The other is called ITM-A(Iterative Task MIgration-Asynchronous), where a
  group of agents works in an asynchronous way.  Both of them are realized in
  our program.  You must specify which algorithm to run, before getting the
  program run.

# EXAMPLE

  In our program, we take a transportation problem, as an example. Consider a
  delivery center, where they have received delivery requests of shipment with
  due-time from many shops.  The problem is to find the shipments allocation
  to trucks, to satisfy the delivery requests.  We have the following
  correspondence:

  * a truck <---> an agent(a resource)
  * a task <---> a delivery request
  * task evaluation function <---> the total over-due-time of the shipments
    allocated to the truck. This value depends on the routing of the truck,
    i.e., the order of visiting the destination shops, as well as which
    delivery request to do.

  Our program finds the semi-optimal solution minimizing the total
  over-due-time of all shipments.

# IMPLEMENTATION ON Multi-PSI

  Our agents are rather independent. There is no global data area and they
  send and receive messages to share some information, which is suitable for
  implementation on Multi-PSI.  In our program, the processing of trucks is
  equally distributed to PEs(Processing Elements).  For instance, if the
  number of PEs and trucks are equal to 15 and 60 respectively, each PE has a
  work for 4 trucks.


=====<< 2. HOW TO GET THE PROGRAM RUN >>=======================================

# MACHINE

  Multi-PSI with the language KL1

# HOW TO GET THE PROGRAM RUN

  First, initialization such as initial shipment allocations to trucks and
  work assignment to each PE, has to be done.  AT this phase, some
  initialization files have to be read.  Then, the main program improves the
  initial shipment allocations, toward the better solution. The main program
  works as ITM-S or ITM-A.

  (1) HOW TO GET ITM-A PROGRAM RUN

    (1-1) Login PIMOS.
    (1-2) In SHELL, input the followings:

		Shell>> cd "DIR:async"		<----- see **
		        --------------
		Shell>> load("async")
                        -------------

	NOTE:
	*:  Input the underlined parts above.
	**: Use the full path for DIR:. 
	    For instance, if DIR: is defined as >sys>user>hendrix, what you
            should actually type is

		cd ">sys>user>hendrix>async"

    (1-3) In LISTENER:
      [1] input the followings:

		Listener>> getPlan0("DIR:ex**>ex**map30.plan",
        	                    "DIR:ex**>ex**rt$$.plan",    <-- see NOTE2
                	            "DIR:ex**",
                        	    0,time,PE).
                           ------------------------------------  <-- see NOTE1

	NOTE:
	1: Input the underlined parts above.
	2: Specify the full path for DIR:. 
           Specify PE, for the number of Processor Element you use.
           Specify ** and $$, according to the examle you want to try
           by checking the following table:

                ----------------------------------------------------
		type of example		value for **	value for $$
                ----------------------------------------------------
		with  15 trucks		          15              25
		with  30 trucks		          30              45
		with  60 trucks		          60              90
		with 120 trucks		         120             180
                ----------------------------------------------------

	    For instance, 
            if
              you are going to try an example with 60 trucks,
              with 16 PEs, and
              DIR: is defined as >sys>user>hendrix, 
            then what you should actually type is

		getPlan0(">sys>user>hendrixex60>ex60map30.plan",
     	                 ">sys>user>hendrixex60>ex60rt90.plan",
    	                 ">sys>user>hendrixex60",
                         0,time,16).

      [2] After a few minutes, you have a new menu, then select "do_it"
          in the menu.

  (2) HOW TO GET ITM-S PROGRAM RUN

    By replacing the term "async" in the description for ITM-A by the term
    "sync", exactly the same as the case of ITM-A.


=====<< 3. TABLE OF NECESSARY FILES >>=========================================

* FILES FOR MAIN PROGRAM:

  - DIRECTORY: async	< for ITM-A >
    FILE:
	actionC.kl1	async.com	doAction.kl1
	planAData.kl1	planAgent.kl1	planDevice.kl1
	planDm.kl1	planPort.kl1	planSim.kl1
	planTop.kl1	planUtil.kl1

  - DIRECTORY: sync     < for ITM-S >
    FILE:
	s-agentName.kl1	s-doAction.kl1	s-planAData.kl1
	s-planAgent.kl1	s-planCmes.kl1	s-planDev.kl1
	s-planDm.kl1	s-planEfm.kl1	s-planPort.kl1
	s-planSim.kl1	s-planTop.kl1	s-planUtil.kl1
	sync.com
	
  - DIRECTORY: esp      < for ESP >
    FILE:
	pAgentEG.esp	pAgentEW.esp	pAgentPE.esp
	pInterF.esp	pPWWS.esp	pPersonal.esp
	pPlanMCM.esp	pSaveLoad.esp	pTop.esp
	pTop2.esp	pTotalEW.esp

* FILES FOR INITIALIZATION:

  - DIRECTORY: ex15	< for example with 15 trucks >
    FILE:
	agent10.plan0	agent12.plan0	agent14.plan0
	agent15.plan0	agent17.plan0	agent20.plan0
	agent21.plan0	agent22.plan0	agent23.plan0
	agent24.plan0	agent3.plan0	agent4.plan0
	agent7.plan0	agent8.plan0	agent9.plan0
	ex15map30.plan	ex15rt25.plan

  - DIRECTORY: ex30	< for example with 30 trucks >
    FILE:
	agent10.plan0	agent11.plan0	agent12.plan0
	agent13.plan0	agent16.plan0	agent17.plan0
	agent18.plan0	agent19.plan0	agent2.plan0
	agent20.plan0	agent22.plan0	agent23.plan0
	agent25.plan0	agent26.plan0	agent27.plan0
	agent28.plan0	agent29.plan0	agent30.plan0
	agent32.plan0	agent34.plan0	agent35.plan0
	agent38.plan0	agent4.plan0	agent42.plan0
	agent43.plan0	agent45.plan0	agent6.plan0
	agent7.plan0	agent8.plan0	agent9.plan0
	ex30map30.plan	ex30rt45.plan

  - DIRECTORY: ex60	< for example with 60 trucks >
    FILE:
	agent1.plan0	agent10.plan0	agent12.plan0
	agent16.plan0	agent17.plan0	agent19.plan0
	agent22.plan0	agent23.plan0	agent25.plan0
	agent27.plan0	agent29.plan0	agent3.plan0
	agent30.plan0	agent31.plan0	agent32.plan0
	agent33.plan0	agent35.plan0	agent37.plan0
	agent39.plan0	agent4.plan0	agent40.plan0
	agent41.plan0	agent42.plan0	agent43.plan0
	agent44.plan0	agent47.plan0	agent48.plan0
	agent49.plan0	agent53.plan0	agent54.plan0
	agent55.plan0	agent56.plan0	agent57.plan0
	agent58.plan0	agent60.plan0	agent62.plan0
	agent63.plan0	agent65.plan0	agent66.plan0
	agent67.plan0	agent68.plan0	agent69.plan0
	agent7.plan0	agent70.plan0	agent71.plan0
	agent74.plan0	agent76.plan0	agent77.plan0
	agent78.plan0	agent79.plan0	agent8.plan0
	agent80.plan0	agent81.plan0	agent82.plan0
	agent84.plan0	agent85.plan0	agent86.plan0
	agent87.plan0	agent9.plan0	agent90.plan0
	ex60map30.plan	ex60rt90.plan

  - DIRECTORY: ex120	< for example with 120 trucks >
    FILE:
	agent1.plan0	agent10.plan0	agent100.plan0
	agent101.plan0	agent102.plan0	agent103.plan0
	agent106.plan0	agent107.plan0	agent11.plan0
	agent110.plan0	agent111.plan0	agent113.plan0
	agent115.plan0	agent117.plan0	agent119.plan0
	agent12.plan0	agent122.plan0	agent124.plan0
	agent125.plan0	agent126.plan0	agent127.plan0
	agent128.plan0	agent129.plan0	agent13.plan0
	agent130.plan0	agent131.plan0	agent136.plan0
	agent137.plan0	agent138.plan0	agent14.plan0
	agent142.plan0	agent144.plan0	agent145.plan0
	agent146.plan0	agent147.plan0	agent149.plan0
	agent15.plan0	agent151.plan0	agent152.plan0
	agent153.plan0	agent154.plan0	agent156.plan0
	agent157.plan0	agent159.plan0	agent16.plan0
	agent160.plan0	agent161.plan0	agent162.plan0
	agent163.plan0	agent164.plan0	agent165.plan0
	agent166.plan0	agent167.plan0	agent168.plan0
	agent169.plan0	agent17.plan0	agent170.plan0
	agent175.plan0	agent176.plan0	agent177.plan0
	agent178.plan0	agent179.plan0	agent18.plan0
	agent19.plan0	agent20.plan0	agent22.plan0
	agent23.plan0	agent24.plan0	agent27.plan0
	agent28.plan0	agent3.plan0	agent31.plan0
	agent32.plan0	agent33.plan0	agent35.plan0
	agent36.plan0	agent37.plan0	agent38.plan0
	agent39.plan0	agent4.plan0	agent42.plan0
	agent43.plan0	agent44.plan0	agent45.plan0
	agent46.plan0	agent49.plan0	agent5.plan0
	agent54.plan0	agent55.plan0	agent56.plan0
	agent57.plan0	agent58.plan0	agent59.plan0
	agent63.plan0	agent64.plan0	agent65.plan0
	agent66.plan0	agent69.plan0	agent7.plan0
	agent71.plan0	agent72.plan0	agent73.plan0
	agent75.plan0	agent76.plan0	agent77.plan0
	agent78.plan0	agent79.plan0	agent81.plan0
	agent82.plan0	agent84.plan0	agent86.plan0
	agent87.plan0	agent88.plan0	agent91.plan0
	agent93.plan0	agent94.plan0	agent95.plan0
	agent96.plan0	agent98.plan0	agent99.plan0
	ex120map30.plan	ex120rt180.plan


=====<< REFERENCES >>==========================================================

* Shindo,S., Sumida,M.,
  "Group Problem Solving by Autonomous Agents for Task Allocation Problem",
  proc. of IASTED International Conference MODELLING & SIMULATION,
  ACTA TRESS, 1991, pp.59-63. Also available as ICOT TM-1063, 1991.


