                                                                     8/7/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 5 -- THE PLAYER PROGRAMS
                --------------------------------

This chapter explains how to use the player programs, including the human
interface.  Compilation instructions are not included here; see the
appropriate README files and makefiles.


                5.1 Starting the Player Programs
                --------------------------------

INTERNET-BASED PLAYERS

To start an internet-based player (including a human/internet player), simply
run the program.  There are no options or arguments (unless you have the full
networking software, in which case a hostname may be specified as an argument).
The human/internet player will ask for your name (maximum 30 characters) and
whether you want to be a buyer or a seller.  If the program successfully
connects to the monitor you will then receive one of four types of message
from the monitor:

1. A description of the game schedule in a box of *'s, followed by the time
   at the monitor's location.  This means that no game is presently
   starting; try again at the appropriate time.
2. A "Waiting for ..." message.  This means that a game will start as
   soon as the condition is satisfied.  Further waiting messages will be sent
   every 30 seconds until the game starts or is abandoned.
3. A "Game starting" message.  This means that your connection satisfied
   the condition for a game, which is now starting.
4. A "Sorry, ..." message.  This means that a game is about to start, but
   that you cannot join it for the reason given.

Note that all messages before the beginning of the game itself are sent to
stderr, not stdout.  This implies for example that the messages will come
to the screen even if you redirect the main (stdout) output to a file, as
may be appropriate for a game run in background.  If you start up several
players, with all but one in background, you will see multiple copies of
the messages, one from each player.

It may be useful on a Unix system to copy the main (stdout) output to a
file as well as sending it to the screen.  Pipe the output into 'tee' to
do this.  E.g.:

    di | tee output

Here 'di' is the name of the internet player, and 'output' is the name
of the output file.


PIPE-BASED OR FILE-BASED PLAYERS

You do not normally run pipe-based or file-based player programs by themselves,
but expect the monitor to do so.  The "monitor" chapter of the documentation
explains how this is done.

The human interface is used like the machine players except for the
following:
  a. The -h flag is required in the playerfile.
  b. The monitor's listfile output must be sent to a file, not the screen.
     Specify the filename on the command line.  E.g.  "dmon outfile".

Using the human player via DANI is not recommended.  Instead make an inetbased
version of the human player itself (with DISPLAY turned on in define.h).
If you DO use a human player via DANI, you must use the -a and -q flags
if pipebased (-f and -q if filebased).

If in doubt as to whether the players are working correctly it may be useful
to run them directly.  A useful test is to send the player the 15 character
message ...31.1234....0 (where each . represents one space); the response
should be ...31.1234 (possibly with one extra leading space).  For the pipe-
based case the messages are simply sent to and from stdin and stdout.  For the
file-based case the messages must come from the file xxxx.in and are sent to
xxxx.out, where xxxx is the player program's name.  After performing this
test in the pipe-based case you must abort the player program, or send it
a nonsense message to make it abort.


        5.2 Explanation of human player and C-player output
        ---------------------------------------------------
The skeleton players written in C can optionally display the game as it
progresses.  This is a compile-time option (see the README file and
comments in the programs), and is mainly intended for use in the human
player.  It may also be useful with machine players, especially with
internet-based communication.  Note that using DANI is an alternative
in this case however, and has a more compact output format.  The only
difference between the output of the human player and of a C-player with
output display is the prompts and responses used with the human player.
These are discussed separately below.

The output display consists of initial headings, the detailed play of
the game, and various summaries.

INITIAL HEADINGS

The first part of the output gives basic game parameters and a list of
player numbers.  For example:

        DA game 1760  Tue Jun  6 21:32:20 1989
        --------------------------------------
        nrounds: 2   nperiods: 2   ntimes: 50   price range: 1-1000

         2 buyers:     B1   501    B2  9999
         2 sellers:    S1   502    S2     0
        You are seller S1, otherwise known as YOU

The parameters and game-id (1760 in the example) should be self-explanatory.
Note that the date and time is local to the player's location, which may be
in a different time-zone than that of the monitor itself.

The lists of buyers and sellers give their player numbers, or 0 if unknown
or anonymous.  These numbers may be useful in identifying strategies you
have and have not played against.  9999 is used for a human player.

MAIN GAME

The main game is displayed step by step.  The format is less concise than
DANI's, and takes 6 lines per time step.  For example, showing three time
steps:

      ----- round 1 ----------- period 2 ---------- time 6 -------------
      cbid: (none)   coffer: (none)          tokens:  542  450  303  264
                    B1/c YOU/a    S1/b  S2/b
      bettered      183*  173     378*  395
      no trade

      ----- round 1 ----------- period 2 ---------- time 7 -------------
      cbid:  183/B1  coffer:  378/S1         tokens:  542  450  303  264
                    B1/c YOU/a    S1/b  S2/b
      winner        218   247*    330*  333
      profit:  212          <     330<

      ----- round 1 ----------- period 2 ---------- time 8 -------------
      cbid: (none)   coffer: (none)          tokens:    -  450  303  264
                    B1/c YOU/b    S1/c  S2/b
      lost tie      183*  183     392   383*
      no trade

The first line at each time gives the round, period, and time.

The second line gives the current bid and offer, if any, and the player's
tokens.  Note that the owners of the current bid and offer are given if
applicable.  Note also that tokens that have been traded are replaced by
dashes (-).

The third line lists the player names (with "YOU" for the present player),
with a lower-case letter showing which token they will trade next (a = first,
b = second, etc.)

The fourth line shows the bids and offers in the bid-offer step, with an
asterisk marking the current bid and current offer.  A current bid or
offer carried over from the previous step (in the absence of any new ones)
would be shown with a # instead of a *.  On the left is shown the
disposition of your own bid or offer request if you made one.  "winner" means
you had the best (or equal best) bid or offer, and now hold the current
bid or offer.  "bettered" means that someone else had a better bid or
offer.  "lost tie" means that you had an equal best bid or offer, but
lost the resulting random tie-break.

The fifth line shows the result of the buy-sell step.  If a trade occurs
it is shown by a pair of <'s for a buy or a pair of >'s for a sell.  The
price is shown under the current bid or offer that it derived from.  On
the left is shown any profit that you made, or "no trade" if no trade
occurred, or blank if a trade occurred in which you were not involved.
"lost draw" means that you lost a random tie break involving other
buyers or sellers (the same as you) who also made buy or sell requests.

In either the bid-offer or the buy-sell line the left column can also
show **illegal** or **late**.  **illegal** means that the your
response was illegal, such as a bid below the current bid, or a request to
buy when there was no current offer.  **late** means that you missed
responding to one or more steps, so the actual response was to a previous
step and was ignored.  Note that if this occurs, subsequent information about
the number of tokens traded (a, b, etc), and some summary information,
may be incorrect because relevant information was missed.  See the
description of the variables in the skeleton programs for a more detailed
discussion.

SUMMARIES

At the end of each period a short summary appears:

        You made 3 trades, making a total profit of 286 in this period
        Summary of trade prices (* = yours):
          538*   545    521*   535    513*   509

The number of trades and the profit are just for the period that just
ended.

At the end of each round the number of trades and profit is summarized
for the current player for each period of the round.  For example:

        ==================== End of round 1 ====================
        Summary:   period  trades  profit
                      1       3      286
                      2       3      293
                    total     6      579

At the end of the whole game a final summary appears too:

        ======================== End of game 1760 =========================
        Total profit: 1186
        Efficiency: 109%

The total profit is the total reported by the monitor.  If that differs from
the amount computed by adding up the individual profits for each round, the
message will look like:

    Total profit: 1186  (1037 accounted for)

This can occur if the player was **late** and missed a transaction.

The 'Efficiency' is the performance figure of merit reported by the monitor;
the ratio of actual profit to that expected if all trades occurred at the
theoretical equilibrium price.  Higher values represent better performance.


        5.3 Prompts and Responses in the Human Player
        ---------------------------------------------
The previous section describes the display output of the human player besides
the prompts and responses.  Normally the human player asks for your decision
once in each bid-offer and buy-sell step.

There are two types of prompts:

  1. Prompts ending in a ? expect a substantive reply, either a number or
     a 'y' for yes or 'n' for no.

  2. Prompts ending in a > are merely informational, and expect only a
     carriage return in response.

At either of these types of prompt, various options or commands can be
specified instead of the expected response.  The prompt is then repeated.

BID-OFFER PROMPTS

In a bid-offer step the usual prompts are:

    bid [n]?        for a buyer
or  offer [n]?      for a seller

These invite you to type in a bid or offer value respectively.  If you don't
want to make a bid or offer you can type an n (none), or just press return.
The '[n]' reminds you that the default action is 'none'.

Instead of one of the above prompts you may receive one of the informational
prompts:

    nothing to trade    if you've traded all your tokens
or  unwise to bid       if the current bid is above your next token
or  unwise to offer     if the current offer is below your next token

The last two 'unwise' messages only appear if you set the 'u' option
discussed below.

BUY-SELL PROMPTS

In a buy-sell step the usual ? prompts are:

    buy at xxx [n]?     for a buyer
or  sell at xxx [n]?    for a seller

Here xxx is the current offer or current bid price respectively.  Your
response should be y for yes or n for no.  The default if you just press
return is shown in square brackets (n for no in the example, but this can
be reversed with the 'a' option).

Instead of one of the above prompts you may receive one of the following
informational prompts:

    not bidder>         for a buyer not holding the current bid
or  not offerer>        for a seller not holding the current offer
or  nothing to buy>     for a buyer when there's no current offer
or  nothing to sell>    for a seller when there's no current bid
or  nothing to trade>   if you've traded all your tokens
or  unwise to buy>      for a buyer who'd make a loss by buying
or  unwise to sell>     for a seller who'd make a loss by selling

The last two 'unwise' messages only appear if you set the 'u' option
discussed below.

OPTIONS AND COMMANDS

At any prompt you may set or reset any of the following options.  To set
them simply type their letter.  To reset them type a - and then their
letter.  Options can be concatenated, and a - applies to all subsequent
options.  For example, u-aw would set u and reset a and w.

    u   prevent 'unwise' choices likely to lead to a loss.  This enables the
        'unwise to ...' prompts detailed above, and refuses to accept any
        bid or offer that would result in a loss if accepted.

    a   accept bids or offers by default on the buy-sell step.  This makes
        y (yes) the default for the 'buy at ...' and 'sell at ...' prompts.

    f   fast.  Removes the wait for a carriage return (or timeout) at all
        '>' prompts.  The message is shown without the '>', but no response
        is needed or allowed.  Note that this may lead to rapid scrolling of
        the game on the screen, and does not let you enter further options
        or commands until a ? prompt next occurs.

    w   wait.  This turns off the automatic timeout and waits for ever for
        your response.  On most systems the human player types one '.' every
        second (or a ':' in the last five seconds) and then defaults your
        response (as if you had just pressed return) after a certain time.
        If you turn this off with the w option you may exceed the time
        that the monitor allows for your response, which may lead to a
        **late** disposition or even to you being 'killed'.

    P   Pass.  This causes every prompt (both ? and > types) to be defaulted
        for the rest of this period.  Note that P is upper-case.

The P option is reset at the start of each period but the other options
are not.

Besides the above options which may be toggled on or off, the following
commands may be given to any prompt:

  quit  Quits the game, which then continues without you.

  help  Prints a summary of these options and commands.

    ?   Tells you what you can do in response to the current prompt.

    t   Shows your token values and the current bid and offer values.

    $   Shows the transaction prices so far in this period.

    h   Shows a 'history' summary of the last few steps.  The output is
        described in more detail below.


               5.4 History Display in the Human Player
               ---------------------------------------
The human player can display a compact summary of the previous N steps in the
current period, where N is a compile-time option.  Use 'h' in response to
any prompt to obtain the history display.  The output combines each bid-offer
and buy-sell step into a single line.  For example:


        t     YOU     B2     S1     S2   price
        1     400*   321    514    510*
        2     435*>  433    476*>  477     435
        3     400*   338    514*   518
        4     430    436*<  479*<  484     479
        5            339*   514*   527
        6     390*>  383    488    463*>   390
        7     350*   336    514    510*
        8            399*   485    472*
        9     425*>  423    459    446*>   425
        12 !  395    415*<  470    469*<   469
        13    350*   330    514*   523
        14    380*   378    488*   497
        15 *  392    399*   470*   478

The leftmost column shows the time t.  This may be shown as a ? if
unknown because of a 'late' condition.  The time column may be followed
by a !, calling attention to the fact that some steps were missed, or
a *, meaning that the information on this line is incomplete.  Late
responses can cause either of these conditions, but * is also normal
on the last line if only the bid-offer step has occurred so far.

The columns for each player show the bid or offer values, followed by a
* marking the current bid or offer, and a < for a buy or a > for a
sell.  The actual transaction price is repeated in the last column.
A # is used instead of a * for a current bid or offer that was carried
forward from a previous bid-offer step.

