The Acquire Project
Final Version
Running Instructions.

This is the final version of the Acquire Project for the purposes of
the class Software Engineering Workshop II.  To run the final version,
please follow the instructions below under "Running the
System".  Before this, we give a summary of the features introduced
in the beta-test version, this version, and a list of software you
need to have to run the system.

Features Introduced in the Beta-Test Version
--------------------------------------------
* Capability for up to 6 agents to play Acquire from any Unix system.
* Agents play a full game of Acquire picking random tiles and stocks to buy.  Agents able to deal with stock merging, trading, and stock purchasing.
* Complete output file which indicates who played what tile in what order and who won the game at the end of the game.
* Comprehensive outputting of the server's moves and agent's moves while playing the game.
* Capability to play any number of games in a session, not limited to only one game.

Features Introduced in the Final Version
----------------------------------------
* Agent's game play is done with a pseudo-intelligent one-step look-ahead heuristic.
* Capability to run the entire system on one machine as well as on separate machines.

What you need to run the demonstration
--------------------------------------
* ACL Lisp (/usr/local/bin/acl on queen.mcs.drexel.edu)
* CMU Lisp (/usr/local/bin/lisp on queen.mcs.drexel.edu)
* Java, version 1.3.0 or greater (/usr/local/gpl/java2-sdk-1.3.0/bin/java on queen.mcs.drexel.edu)

Running the System
------------------
There are two ways to invoke the system:

* All on one machine: The final version allows you to start everything
  up from one machine with one command.  We added this based on
  comments mentioned in our beta-test review.  The advantage to this
  is avoiding the mess of starting up all the servers, agents, and the
  user controller by hand.  This is great for testing purposes; we
  recommend you use this when testing the system.  However, the
  disadvantages to this are that, because everything is run on one
  machine, things will slow down a lot, in combination with network
  latency issues that already exist.
  See "All on One Machine" below.

* Each agent, server, and the user controller separately: This is how
  you would invoke the system piece by piece, allowing the servers,
  agents, and the user controller to be on any machine connected to
  the Internet.  The advantages are that you can pick and choose which
  machines (which speeds) you want these pieces to run on.  The
  disadvantages are the complexity of the startup, and it requires several console windows to be monitored.
  See "All on Different Machines" below.

All on One Machine
------------------
Open up an x-terminal, or telnet window (session) to the Unix machine where you installed the software.

1.) From the directory where this README is, cd into /com

2.) Run the commmand:

java -classpath . LocalSystem (machine name) (port) (acl location) (cmu location) (cmu location) (number of agents) (number of games)

Parameter information ::

* machine name : The name of the machine you are on.
		Example: brillig.mcs.drexel.edu
* port : A port number, this port number and the port above it must be free.
		Example: 8888
* acl location : The location of ACL lisp on your machine.  On queen it is just "acl" from the command prompt.  It might be different on your machine.
		Example: /usr/local/bin/acl
* cmu location : The location of CMU lisp on your machine.  On queen it is just "lisp" from the command prompt.  It might be different on your machine.
		Example: /usr/local/bin/lisp
* number of agents: A number from 1 to 6, any other number will result in an error.
		Example: 2
* number of games: A number from 1 to 200, any other number will result in an error or 200 games being played.
		Example: 5

Example run:

java -classpath . LocalSystem brillig.mcs.drexel.edu 8888 acl lisp lisp 2 1

- Runs the LocalSystem on brillig.mcs.drexel.edu, on ports 8888 and 8889.  It uses the command line call "acl" for ACL Lisp, and "lisp" for CMU Lisp.  There are 2 agents and 1 game will be played.

3.) When the session is finished, the results will be located in GameHistory.text.  See "Game Output".


All on Different Machines
-------------------------

Running the demonstration requires you to have several telnet windows open, or x-terminals open, a minimum of 5 will be needed.  Open up 5 telnet sessions or 5 x-terminals now. 

1.) Set up the first game server ::
***********************************
First you need to run two copies of the game server.  The game server houses the Acquire engine and is necessary to be running before anything else (as it is the server). 

Run the first game server ::
In the FIRST x-terminal/telnet window, do this: 

1. cd into /com from this directory.

2. Then start the engine by calling: java -classpath /<<path to this directory>>/com/ Server <<Name of this machine>> <<Port>> <<ACL Lisp Location>>

For example:

java -classpath /pse1/umczajko/Classes/SEWRK/acquire/src/com/ Server brillig.mcs.drexel.edu 8888 acl

This runs the server 
	located at /pse1/umczajko/Classes/SEWRK/acquire/src/com/ 
	on the machine brillig.mcs.drexel.edu 
	at port 8888
	using the command "acl" as the ACL lisp.

2.) Run the second game server :: 
*********************************

This server is necessary for the agents to connect to, it is their
"Player's Engine" which allows the agents to experiment with
move.  Right now, the player's engine is deactivated but the agents
still need to connect to it.

In the SECOND x-terminal/telnet window, do this: 

1. cd into /com from this directory.

2. Then start the engine by calling: java -classpath /<<path to this directory>>/com/ Server <<Name of this machine>> <<Port>> <<ACL Lisp>>

For example:

java -classpath /pse1/umczajko/Classes/SEWRK/acquire/src/com/ Server brillig.mcs.drexel.edu 8889 acl

Make sure that you run the server on a different port than the game server in step 1.

3.) Run the UserController Software::
*************************************
Now the game server needs to have a user controller object attached to it.  The user controller starts the games and keeps track of the outcome of games.

In the THIRD x-terminal/telnet window, do this: 

1. cd into /com from this directory.

2. Then start the engine by calling: java -classpath /<<path to this directory>>/com/ UserController <<Name of the machine game server is on>> <<Port of game server>> <<Number of Agents>> <<Number of Games>> <<CMU Lisp>>

For example:

java -classpath /pse1/umczajko/Classes/SEWRK/acquire/src/com/ UserController brillig.mcs.drexel.edu 8888 2 1 lisp

This runs the UserController:
	at the location: /pse1/umczajko/Classes/SEWRK/acquire/src/com/
	with the game server: brillig.mcs.drexel.edu
	with the game server port: 8888
	with the number of agents: 2
	with the number of games: 1
	with the location of CMU Lisp: "lisp"

4.) Start the agents.
*********************
In step three we indicated we wanted 2 agents, to get more, just repeat this step.

To start an agent you do the following.

In the FOURTH/FIFTH/(etc.) x-terminal/telnet window, do this: 

1. cd into /com from this directory.

2. Then start the engine by calling: java -classpath /<<path to this directory>>/com/ Agent <<Name of the machine with player's engine>> <<Port of the player's engine>> <<Name of the machine with game server engine>> <<Port of the game server engine>> <<CMU Lisp Location>>

For instance:

java -classpath /pse1/umczajko/Classes/SEWRK/acquire/src/com/ Agent brillig.mcs.drexel.edu 8889 brillig.mcs.drexel.edu 8888 lisp

This runs an agent at:
	location /pse1/umczajko/Classes/SEWRK/acquire/src/com/
	whose players engine is located at: brillig.mcs.drexel.edu
	whose players engine is on port: 8889
	whose game server engine is located at: brillig.mcs.drexel.edu
	whose game server engine is on port: 8888
	with the location of CMU lisp as: "lisp"

Note that the game server example in step 1 and the players engine in step 2 were used in this example for the agent.

*** THE GAME BEGINS WHEN ALL AGENTS HAVE CONNECTED ***

This means that if you asked for 2 agents to be playing in step 3, the
game server will NOT begin until 2 agents have connected.  Once 2
agents have connected, the game will begin and a lot of messages will
fly by.   One game will take approximately 10 minutes.

The server, agent, and user controller are in verbose mode, you will
see every interaction fly by.  These messages act as feedback to let
the user know something is going on, but reading them is not necessary
since the transcript of the game session itself is written to a file.


The Game Output
---------------

All of the data from the game that was played is located in
/com/GameHistory.text.  Inside this file you will see each agent's
move and the total money that they had at the end of the game in the
order in which they placed overall.


NOTE ----

Due to the complexity of the computation the agents perform during a
game, you will likely see a great deal of LISP Garbage Collecting
output in your console.  We were unable to find a way to force this to
be quiet.  It does not reflect a weakness in the system, however,
because the GC will take care of any memory management issues.


As a note, sometimes at the end of the game, we experience
synchronicity problems with the LISP and Java processes being killed.
This may cause some errors to appear in your console about LISP
SIGPIPEs.  We respectfully request that you disregard these at this
time, as the majority of the promised functionality *does* exist,
minus this one small bug.



Thats all there is to it, we hope you enjoy using the Acquire system.

Team Four,
The Acquire Project
Software Engineering Workshop II





