                                                                       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 6 -- DANI
                        -----------------

This chapter explains how to use the Double Auction Network Interface (DANI),
and how to interpret its output.  Compilation instructions are not given here;
see the README file in DANI's source directory.


                   6.1 Communication Methods
                   -------------------------
DANI acts as an interface between a monitor on the internet -- normally the
Santa Fe Token Exchange (SFTE) -- and a local player.  DANI communicates
with the monitor via sockets over the internet, and with the player program
by one of the following methods:

  pipe-based    DANI starts up the player program once (as a child process)
                and attaches pipes between it and the player's stdin and
                stdout.

  arg-based     This is just like pipe-based except that the pipes are
                attached to special descriptors specified as arguments on
                the player's command line instead of using stdin and stdout.
                For C players only.  Useful for players that need to use stdin
                and stdout themselves.

  file-based    DANI starts up the player program for each step of the game,
                reading and writing files for communication.

  user-based    DANI does not start up the player itself, but reads and
                writes messages to the player on its stdin and stdout.  Used
                for players on remote machines (e.g. dial-up lines) that
                can talk to DANI directly.

There is considerable overlap between this chapter and chapter 5, because
DANI's display and startup messages are similar to those of the internet-
based C players.


                          6.2 Starting DANI
                          -----------------
Before starting DANI (except to inquire about the current status at the SFTE),
you must compile and link your player program as well as  DANI itself.  Then
start DANI with a command of the form:

    dani [options] [playername] [hostname]

The options are explained below.  The other parameters are:

playername  the name of the player program to be started.  This must
            be in the current working directory (though DANI needn't be).
            'playername' cannot be specified if you use the -u option.
            Otherwise if you omit it, DANI just inquires about the current
            status at the Santa Fe Token Exchange or elsewhere.

hostname    the name of the host to connect to on the internet.  This
            only works if you have the full networking software, which is
            not normally distributed.  Otherwise the host is taken as
            sfi.santafe.edu, for the SFTE.  'hostname' must be the second
            argument (after playername) unless the -u option is used.
            See also the -h option below.

OPTIONS

    -b  Insist on being a buyer.

    -s  Insist on being a seller.

        If neither -b nor -s is specified the monitor will assign
        your role as buyer or seller.

    -p  Use pipe-based communication.

    -a  Use arg-based communication.

    -f  Use file-based communication.

    -u  Use user-based communication.  This inhibits display or log
        output unless redirected with -o.

        If none of -p, -a, -f, or -u is specified the default depends
        on a choice made when dani was compiled.

    -n name
        Specifies the name of the player.  If this is not supplied
        DANI will ask for it with "Enter your name:".

    -h hostname
        An alternative way of specifying a hostname if you
        have the full networking software.

    -d  Turns on display of the game as it progresses.

    -q  Turns off display of the game ('quiet').

        If neither -d nor -q is specified the default depends on a
        choice made when dani was compiled.

    -o output
        Sends the display or log output to file 'output'.
        Defaults to stdout.  Redirection with > may also be used,
        but -o may be useful if the player program also produces
        stdout output (in which case you must use -a or -f).
        -o MUST be used if you want to produce display or log
        output with user-based (-u) communication.

    -l  Log messages.  For debugging only.  Implies -q.  Messages
        generated by DANI itself are prefixed by a *.

    -k  Don't send KILLED messages to player.  For debugging in the
        filebased case -- to prevent the player deleting its files.


After starting and testing the player, DANI will ask for your name (maximum
30 characters) unless you already specified with the -n option, or are only
inquiring about the status (no playername given).  Then, if it 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 or the -o file.


                        6.3 VaX/VMS Notes
                        -----------------
DANI should work correctly on a VaX/VMS system as long as the Wollongong
WIN/TCP networking software is available.  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.  The player is started up as a sub-process
of DANI, 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 DANI exits or aborts.  You can check for
subprocesses with the command  "SHOW PROCESS/SUB" -- the player sub-process
is always called PLAYER.  If you see PLAYER in the process tree, you can
kill it with "STOP PLAYER".  DANI will refuse to run again if PLAYER already
exists.

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

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


              6.4 Explanation of DANI's display output
              ----------------------------------------
DANI is able to display the progress of a game as it interfaces between
the monitor and a player.  This is enabled by the -d option and disabled
by the -q option; it may or may not be the default, as fixed before
compilation.

DANI's display output consists of initial headings, the main game, and
various summaries.  The initial headings and summaries are identical to
those of the internet-based C players, but the main game display is different.

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 DANI's location, which may be in a
different time-zone than 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

Each period of a game consists of headings and then one line for each
bid-offer and each buy-sell step.  For example:

      ----- round 1 ------ period 1 ---------- tokens:  323  457  506  537

      t         profit   B1    B2     YOU    S2   price
      -------------------------------------------------
      1   winner        392*  380  |  602*  614
          no                       |   .
      2   winner        455   465* |  538*  543
          (yes)    215          <A |   .<A          538
      3   winner        392   405* |  602*  616
          no                       |   .
      4   bettered      465*  450  |  558   545*
                          <A       |   .      <A    545
      5   bettered      392   400* |  602   595*
                                   |   .
      6   bettered      464   465* |  553   546*
                                   |   .
      7   winner        490*  480  |  521*  525
          no        64    <B       |   .<B          521
      8   winner        392   400* |  602*  609
      . . . . . . . . . . . . . . . . . . . . . . . . .
      16  lost tie      507   510* |  518   518*
                                   |   .
      17  bettered      511   512* |  514   513*
                                   |   .
      18  winner        513*  513  |  512*  512
          yes        7    >C       |   .>C          513
      . . . . . . . . . . . . . . . . . . . . . . . . .
      --- end of period 1 of round 1 ------------------------------------

The heading line shows the round and period number, and the assigned
token values.  Note that these token values are usually scrolled off the
screen as the game progresses, and may be worth writing down.

Bid-offer steps are labeled on the left with the time; buy-sell steps
are unnumbered.  A vertical bar (|) always appears between the buyers
and the sellers, and a period (.) appears in the column for the current
player ("YOU") in each buy-sell step; these are useful after the headings
have scrolled off the screen.

Each bid and offer is shown in a bid-offer step, with asterisks (*)
marking the current bid and offer.  If there is no new bid, but a previous
current bid is still outstanding, it is shown in the bidder's column with
a # instead of a *, and similarly for offers.

To the left of the bids in a bid-offer step is shown the disposition
of the current player's bid/offer/none request.  'winner' means that the
bid or offer was the best (or equal best) and thus became the current bid
or offer.  'bettered' means that a better bid or offer was received.
'lost tie' means that the bid or offer was equal best, but the current
player lost the resulting random tie-break.

In a buy-sell step a transaction is shown by a pair of <'s for a buy,
or a pair of >'s for a sell.  The token traded for each player is shown
by an upper-case letter (A = first, B = second, etc.).  The transaction
price is given in the rightmost column.  This price column is omitted
if there are the maximum number of players; the price is easily deduced
from the preceding current bid or offer.

To the left of the transaction information in a buy-sell step is shown
the disposition of the current player's buy/sell/none request.  'yes'
means that a buy or sell request was made and carried out.  '(yes)' means
that a buy or sell request was made, but was not accepted because another
player also made a valid request and won the random tie-break.  This is
usually better than 'yes' if you are the current bidder or offerer,
because the trade occurs at YOUR price.  'no' means that a buy or sell
request was permitted but was not made.  The space is left blank if no
buy or sell request was permitted.

If any profit was made it is shown in the profit column in the appropriate
buy-sell step.  Note that this can occur with a disposition of 'yes',
'(yes)', 'no', and even blank.

The dispositions '**bad**' and '**late**' can appear in either step.
'**bad**' means that the current player's 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 the player 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
token number traded (A, B, etc), and summary information described below,
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.

