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.