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 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.