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