                                                                    8/8/89
                      Santa Fe Institute's
       D O U B L E   A U C T I O N   T O U R N A M E N T


                   CHAPTER 4 -- THE MONITOR
                   ------------------------

This chapter explains how to use the monitor, and how to interpret its
output.  The latter is useful not only to participants running a local
monitor, but also to those using the Santa Fe Token Exchange (SFTE); the
SFTE monitor mails its main (listfile) output back to each participant.
Instructions for compiling the monitor are not given here; see the README
file in the monitor source directory.


                   4.1 Starting the monitor
                   ------------------------
On an IBM PC two executable versions of the monitor are provided, called
'dmon' and 'gdmon'.  The difference is that 'gdmon' has graphics
built in, and turned on by default.  'dmon' is smaller and has no
graphics capability.  On other computers without graphics capability
the monitor is normally called 'dmon'.

Before running the monitor you must set up the game file and players file
in the same directory as the monitor.  The versions provided, called 'game'
and 'players' respectively, contain comments that document the format of
these files, and some example entries.

The game file specifies the basic parameters for the game, including the
number of rounds and periods etc, token generation parameters, and timing
parameters.  See the supplied 'game' file for details.

The players file specifies all local players (network players are controlled
by parameters in the game file, if you have the full networking software).
Each local player is specified by a directory name and a file name.  The
directory specification is relative to the monitor's own directory, so
for example a directory 'playdir' means subdirectory playdir of the monitor's
directory.  It is recommended (for speed) that all players either be in such
immediate subdirectories or be in the monitor's own directory, but other
directory specifications (and, for the PC, drive specifications) are allowed.
Examples are given in the supplied 'players' file.  Note that all file-based
players must have distinct pathnames, whereas pipe-based players may be
specified more than once on Unix systems.

Each player may also be given one or more option flags in the players file.
It is crucial that these be assigned correctly.  See the description and
examples in the supplied 'players' file.

Once the game file and players file are set up correctly, the monitor
may be started with a command of the form

      dmon [options] [ listfile [ logfile [ gamefile [ playerfile ]]]]

It is essential that the current directory is set to the monitor's directory;
starting the monitor from another directory will NOT work.

The options will be discussed later.  The four optional file names have the
following meanings and defaults:

listfile    Main output listing of the game.  Defaults to stdout.

logfile     Initial setup report and error messages.  Defaults
            to stdout.

gamefile    File specifying game parameters.  Defaults to 'game'.

playerfile  File specifying local players.  Defaults to 'players'.

Any of these filenames may be specified as - to mean the default.  A +
preceding logfile (e.g. "+log") implies append to the end.  logfile may be
specified as = to mean the same as listfile.  If listfile or logfile contain
any #'s they will be replaced by digits of the game number.  E.g. out###
becomes out284 for game 284 (or 1284).

Examples (for game 538):

      dmon                      everything goes to stdout
      dmon out###               main report to out538, log to stdout
      dmon out### log###        main report to out538, log to log538
      dmon out### +dmonlog      main to out538, log appended to dmonlog
      dmon out### =             everything to out538
      dmon - - newgame dummies  everything to stdout; game and players files
                                specified as 'newgame' and 'dummies'

Output redirection with > is not recommended for the monitor output.  The
monitor tries to write sensible things to its listfile and logfile
depending on whether or not they go to files, and whether or not they
go the same place; using redirection prevents this.

The following options may be specified:

    -b  Turns off terminal input.  MUST be used to run the monitor
        in background/batch.
    -g  Turns on all graphics, if available.  Currently only
        available on the PC.  This is the default for 'gdmon'.
    -g1 Restricts graphics to display only the supply and demand
        curves at the start of each round.
    -g2 Restricts graphics to display only the transaction data
        (with supply and demand curves) at end of each period.
    -ga Makes graphics automatic -- it displays whatever you
        selected with the above options without asking you first.
    -g0 Turns off graphics if on by default.
        Note: -g options may be concatenated.  E.g.  -g2a

-ppath  Specifies PC directory where the .BGI and .CHR graphics
        files are located.  E.g. -p\tc2.  The default for the
        precompiled versions of the monitor is \tc.  If the files
        are not found in the specified or default directory, they
        are searched for in the monitor's own directory.  Note that
        the .BGI and .CHR files are provided on the floppy disk with
        dmon, but you probably already have copies on your hard disk
        if you have Turbo-C.

Example with options:

      dmon -b out#### +log &

(The & is a Unix special character that makes the job run in the background.)


                          4.2 Runtime commands
                          --------------------
If no player uses the terminal (no -t or -h flag in the players file), and
there is no -b flag on the dmon command line, the following single-letter
commands are available while the monitor is running:

A. While waiting for network players (inet version only):

    s       start the game now
    a or q  abort the game

B. During the main game:

    t   make this the last time step of this period (after next BS step).
    p   make this the last period of this round.
    r   make this the last round of the game.
    e   end the game; equivalent to 'rpt'.
    q   quit; like 'e', but suppresses mailback and any final graphic display.
    k   kill any players we're waiting for now.
    c   continue; force the next step now (may mark some players as late).

These commands do not echo and take effect immediately (though output may
be backlogged, making an apparent delay).  Any other character rings
the bell.  Use 'k' only when the monitor is stuck waiting for a player who
is not responding.


                          4.3 VaX/VMS Notes
                          -----------------
The monitor should work correctly on a VaX/VMS system.  The treatment of
file-based players is straightforward and should cause no problem, but may
be very slow on a busy system.  Pipe-based players are much more efficient,
and thus faster, but more fragile.  Each pipe-based player is started up as
a sub-process of the monitor, and communicates with it via VMS "mailboxes".
If something goes wrong it is possible for the player subprocess to continue
running (in a wait state) even after the monitor exits or aborts.  You can
check for subprocesses with the command  "SHOW PROCESS/SUB" -- the player
sub-processes are called PLAYER1, PLAYER2, etc.  If you see any of these in
the process tree, you can kill them with "STOP PLAYERn".  The monitor will
refuse to run a player if its chosen sub-process name already exists.

Note that you must have the TMPMBX and NETMBX process privileges, and a
non-zero subprocess quota, to run the monitor.  Most users will have these.

Be patient when starting a game.  VaX/VMS takes a relatively long time
to start up a subprocess when the system is busy.


             4.4 Explanation of Monitor "Listfile" Output
             --------------------------------------------
The main output of the monitor is a concise summary of the game parameters,
the players involved, and the actual play of the game.  It is produced in
the "listfile" output of the monitor, which defaults to stdout.  In network
games run at the Santa Fe Token Exchange, the listfile output is
automatically e-mailed back to participants after successful game completion.

PARAMETER SECTION

The first section of the listfile output gives the parameters used in the
game.  For example:

      DA game 1738  Sun Jun  4 19:52:45 1989
      --------------------------------------
      files:  out1738  -  game  players
      protocol:        5   monitor:       385   gametype:        1
      nrounds:         2   nperiods:        2   ntimes:         50
      minprice:        1   maxprice:     1000   ntokens:         4
      ran1:          500   ran2:            0   ran3:           50
      ran4:            5   deadsteps:       0   timeout:        30
      btokens:       450   375   250   175
      stokens:        50   150   225   275
      timefactors:  1000   500   500   500   500   500   250

The heading gives the game number (gameid) and the date and time that
the game began.

The 'files:' line gives the names of the files used for the listfile,
logfile, gamefile, and playerfile, in that order.  See the monitor's README
file for details.  The - in the above example means that the logfile output
was sent to stdout.

'protocol' and 'monitor' give the version numbers of the message-passing
protocol and monitor program respectively.  They can normally be ignored.

The remaining parameter values are all specified in the gamefile.  They
are explained by comments in the distributed version of this file, called
'game'.

The internet version of the monitor (as used at the Santa Fe Token Exchange)
adds several more parameters to the above list.  The additional parameters
are all concerned with controlling the waiting period for players, and the
maximum and minimum number of players required for a game.  They should not
be important unless you have the internet version of the monitor, in which
case you will find an explanation in the extended version of the 'game'
file.

PLAYER SECTION

The second section of the listfile output lists the players involved in
the game.  For example:

      id   num  flags             location            name/comment
      --   ---  -----             --------            ------------
      B1   500  p               playdir/qp            Pipe C skeleton
      B2  9999  isH      palmer@physics.phy.duke.edu  Richard Palmer
      S1   502  p               fortran/pplayer       Fortran skeleton
      S2   501  f               playdir/qf            File C skeleton
      2 buyers, 2 sellers

The 'id' column gives the name used for each player, starting with B for
buyers and S for sellers.

The 'num' column gives the player-number of each player; this should
uniquely identify the player and the strategy.  Participants are assigned
a range of values to use.  9999 is used for human players.  0 means that a
correct value is unknown or has not been assigned; participants should
ask for a correct assignment rather than using 0 except temporarily.

The 'flags' show various status flags for each player.  Most of these
are specified or implied by the player descriptions in the playerfile;
see the comments in the distributed version of this file called 'players'.
The first column of flags describes the communication method, and may
be f (file-based), p (pipe-based), a (pipe-based with descriptors passed
in the argument string), or i (internet-based).  The second column
describes the timing option, and may be s (slow), w (wait), or blank
(default).  The third column describes the player/connection/output type,
and may be blank (default), t (player requires terminal), h (human player),
H (human player via internet), d (connected via DANI), or c (C-player via
internet).

The 'location' gives the directory and filename (relative to the monitor's
directory) for a local player, or the internet address of a network player.
The internet address is not necessarily that at which the player is
located, but is normally a suitable mailing address for the player.  A
numerical address enclosed in square brackets (e.g. fred@[192.12.12.2])
may be used with most mailers.  An address or comment appearing in
parentheses (e.g. joe@(local)) is NOT suitable for e-mail.

The 'name/comment' column gives the comments from the playerfile for local
players, and the player or program name for network players.  DANI and
the human network interface both ask the player for his/her name, while
the C internet-based player has a player name built into the program.

GAME SECTION -- TOKEN DISTRIBUTION

The main game report consists of token-distribution headings, step-by-step
lines, and summaries.  The token-distribution headings appear at the start
of each period.  For example:

      +----------------------------------------------------+
      |                 Round  1, period 1                 |
      +-------+-------------+-------------+----------------+
      | token |   B1    B2  |   S1    S2  |   Equilibrium  |
      +-------+-------------+-------------+----------------+
      |   a   |  816+  816+ |  429+  427+ |   641 to 650   |
      |   b   |  762+  765+ |  553+  553+ |   av:  645.5   |
      |   c   |  658+  661+ |  641+  640+ |   trades:  6   |
      |   d   |  555-  553- |  650-  653- |                |
      +-------+-------------+-------------+----------------+

The tokens assigned to each player are labeled a, b, etc., with values
as given in the table.  Each value has a + or a - appended to it,
depending on whether (+) or not (-) it would be traded if all trades
occurred at the theoretical average equilibrium price.  An = is used
if the token value is equal to the average equilibrium price.

The 'Equilibrium' column shows the equilibrium price range and its
average.  There is often a finite range because the supply and demand curves
usually have a vertical segment in common.  The number of trades expected
in equilibrium is also shown; this is normally equal to the number of +
suffixes in both the buyer and the seller columns.  '*no crossing*'
appears below 'trades' if the supply and demand curves do not cross.

GAME SECTION -- STEP-BY-STEP LINES

Each bid-offer and buy-sell step is summarized on a line.  For example:

      +-------+-------------+-------------+----------------+
      |t  step|   B1    B2  |   S1    S2  | cbid coff price|
      +-------+-------------+-------------+----------------+
      |1  BO  |  476*  469  |  717*  722  |  476  717      |
      |     BS|             |             |  476  717      |
      |2  BO  |  549*  541  |  644*  645  |  549  644      |
      |     BS|   a<A       |    <A       |            644 |
      |3  BO  |  476*  469  |  717*  729  |  476  717      |
      |     BS|             |             |  476  717      |
      |4  BO  |  549   550* |  667   654* |  550  654      |
      |     BS|             |             |  550  654      |
      |5  BO  |  581   585* |  623   623* |  585  623      |
      |     BS|         a<A |         a<A |            623 |
       . . . . . . . . . . . . . . . . . . . . . . . . . .
      |29 BO  |  639*       |  644*   D   |  639  644      |
      |     BS|             |         D   |  639  644      |
      |30 BO  |  641*       |  642*   D   |  641  642      |
      |     BS|             |         D   |  641  642      |
      |31 BO  |  642*       |    "    D   |  642  642 =    |
      |     BS|   c>C       |   c>C   D   |            642 |
      +-------+-------------+-------------+----------------+

The leftmost columns show the time t and whether the step is a bid-offer
(BO) or buy-sell (BS) step.  The rightmost columns show the current bid
and current offer, if any, at the conclusion of each step, and the price
of any transaction that occurred.  An = sign or ! sign follows the current
offer column if the current bid is equal to (=) or greater than (!) the
current offer.

For bid-offer steps the central columns show the bids and offers made by
each player.  The current (highest) bid and current (lowest) offer are
indicated by a * suffix.  If there are no new current bids but one is
left over from the previous bid-offer step it is shown by a double quote ("),
and similarly for offers.

For buy-sell steps the central columns indicate requests to buy or sell
by lower-case letters, and actual tokens sold by upper-case letters.  The
letter used identifies the token concerned.  The direction of a transaction
is indicated by the < or > symbols, which point like arrows from the
accepted bid or offer to the acceptor; < means a buy request was
accepted and > means a sell request was accepted.  Thus for example in
step 5 BS, both B2 and S2 made buy/sell requests and B2 'won' the random
50-50 tie break, so a 'buy' trade was executed at the current offer
price.  Note that it is in fact better to 'lose' such a random tie break
unless the current bid is greater than or equal to the current offer.

Several other symbols may appear in the central columns in either bid-offer
or buy-sell steps:

  D   means that the player is 'dead', for one of many reasons.  Death is
      irreversible.  The D symbol may also appear in the summaries
      described in the next section.

  X   means that the player's response was unacceptable, such as a bid
      below the current bid, or a buy request when there is no current
      offer.

  N   means that the player is non-responsive -- no reply was received
      for this step.

  L   means that the player made a 'late' response, presumably to a
      previous step.  A response is marked as late, and otherwise
      ignored, following any non-responsive (N) step.

  ?   means that the response was invalid or unrecognized.

Note that the above symbols marking abnormal situations may be combined with
some of the normal symbols.  For example D" could occur in a bid-offer
step if the holder of the current offer died and no other offer was made, and
could be followed by D<B if a buyer subsequently accepted this offer, thus
buying the 'dead' player's second (B) token.

A line is drawn across the output when no further mutual profit is possible.
If the 'deadsteps' parameter is set to 0 this will cause the period to be
ended, but if deadsteps > 0 further steps may appear after the line.

GAME SECTION -- SUMMARIES

Summaries appear at the end of every period, and at the end of every round,
and at the end of the game.  The three types have basically the same
appearance but apply to the preceding period, round, or game respectively.
For example:

                  B1    B2      S1    S2
      +----------------------------------------------------+
      |                  Round  1 summary                  |
      +-------+-------------+-------------+-----Market-----+
      |Trades |  6/6   6/6  |  7/6   5/6  |     24/24      |
      |Profit |  667   697  |  559   532  |     2455       |
      |Eqlbrm |  599   611  |  627   633  |     2470       |
      |Effncy |  111%  114% |   89%   84% |       99%      |
      +-------+-------------+-------------+----------------+

The 'Trades' row shows the number of trades made by each player, out of
the number predicted if all trades occurred at the theoretical equilibrium
prices.  The final 'Market' column shows the same information for the
whole market (buyers plus sellers).

The 'Profit' row shows the actual profits made.  The 'Eqlbrm' row shows
the profits predicted if all trades occurred at the theoretical equilibrium
prices.  A . following an Eqlbrm value means 0.5 (e.g. 585. would
mean 585.5).

The 'Effncy' row shows the 'Profit' row as a percentage of the 'Eqlbrm'
row.  The 'Effncy' may be shown as 0/0 (if Profit and Eqlbrm are both 0),
or as 'inf' (if Eqlbrm is 0 but Profit is not), or as 'huge' (if greater
than 9999%).


        4.5 Explanation of Monitor "Logfile" Output
        -------------------------------------------
The monitor's "logfile" output is used to display the startup phase of the
game, and to display error messages.  It may be sent to the same file as
the listfile output (in which case error messages are interpolated into
the game report), or to a different file.  Depending on whether the files
are the same or different, and whether the output is to a named file or
to stdout (the default), the logfile output also shows more or less
information on the progress of the game.

STARTUP PHASE

During the startup phase the logfile shows one line for each player that
the monitor tries to start.  For example:

        dat@192.12.12.1: connected -- S1   C skeleton player
        palmer@192.12.12.1: connected -- B1   Richard Palmer
        fortran/fplayer: verified -- S2
        playdir/refuser: started -- B2
        fortran/pplayer: started -- S3
        playdir/pq: non-existent or non-readable
        playdir/qf: verified -- B3

This example shows that two network players connected, and then the monitor
tried to start five local players, though one of these (playdir/pq) didn't
actually exist.  The numerical address given for the network players is the
actual internet address from which they connected.  For the local players
'started' implies that a pipe-based player was successfully started, while
'verified' implies that a file-based player was checked for existence and
accessibility.  Players are tentatively assigned identification numbers (S1,
B1, etc), though they may be renumbered later.

At a second stage of the startup phase players are told the game parameters
and asked if they want to play.  Any refusals produce messages in the
logfile such as:

        B2  refused to play -- nrounds unacceptable
                            -- maxtokens unacceptable

This will then cause renumbering of the remaining players before the main
listing of players that appears in the listfile.

ERROR MESSAGES

Error messages from the monitor are intended to be self-explanatory.  Some
typical ones are:

        ** error reading 'ntimes' from 'game': non-digit found
        ** error reading 'ntokens' from 'game': value too large
        ** S1  died in INIT2 0 0 0 -- fatal error
        ** B1  died in BIDOFF 1 1 1 -- quit
        ** S2  died in BUYSELL 1 2 8 -- connection broken
        ** B2  died in BIDOFF 2 2 1 -- killed by operator
        *** no active buyers left -- game ended

Many of the messages show the step in which the error occurred, such as
the 'BUYSELL 1 2 8' above, which means the buy-sell step at time 8 of
period 2 of round 1.  There are many possible reasons for a player dying,
and the difference between reasons like 'read error', 'connection broken',
'write error' and 'unresponsive' should only concern an expert; in each case
the player program stopped responding properly.  The reason 'fatal error'
means that the player program itself detected an error and called the 'error'
subroutine.  An interrupt can also cause this error.  The reason 'quit'
means that the player intentionally quit the game; this is normally only
used by the human interface.

LOG INFORMATION

If the logfile and listfile are not identical, the logfile shows the progress
of the game as it runs.  More information is shown if the logfile is
defaulted to stdout than if it is sent to a named file.  In the stdout case
an example is:

        DA game 1745  Mon Jun  5 17:06:22 1989
        --------------------------------------
        files:  out1745  -  game  players
        Initialization-1
        Initialization-2
        Round 1
           period 1
        *-*<*-*-*>*-*-*<*-*-*<*-*-*-*-*-*-*<*-*-*-*-*-*-*<|
           period 2
        *-*<*-*<*-*-*<*-*-*<*-*-*-*-*-*-*<*-*-*-*-*-*-*<|
        Round 2
           period 1
        *-*-*<*-*-*>*-*-*<*-*-*<*-*-*-*-*-*-*-*-*<*-*-*-*-*-*-*-*-*-*<|
           period 2
        *-*-*<*-*-*<*-*-*>*-*-*<*-*-*-*-*-*-*-*-*<*-*-*-*-*-*-*-*-*-*<|
        End of game 1745 -- output is in out1745

The heading and 'files:' line are identical to those in the listfile.
The 'Initialization', 'Round', and 'period' lines log the major divisions
of the game.

The lines with asterisks are produced one symbol at a time if output is to
stdout.  One symbol is shown for each bid-offer and each buy-sell step.  For
a bid-offer step a * is shown if there were any bids or offers; otherwise
a . is shown.  For a buy-sell step a < is shown for a buy transaction,
a > is shown for a sell transaction, and a - is shown if no transaction
occurred.  A | is shown when no more mutual profit can be made.

