t-play/autotest/README

   1 This is an 'autotest' framework for distributed play testing of Go-playing
   2 computer programs. You can run clients on as many computers as you want,
   3 to test many combinations in parallel, then display results of the pairings
   4 in an organized way.
   5
   6 It should be easily adaptable for testing of performance of other stochastic
   7 programs against a reference "opponent", just replace twogtp invocations
   8 in the scripts with your own programs.
   9
  10
  11 BASIC USAGE
  12 -----------
  13
  14 Create a networked (NFS or FUSE-sshfs) directory, copy the contents of this
  15 directory there, and customize the rc file - it is heavily commented and
  16 should be self-guiding. You will need the twogtp tool from gogui package.
  17
  18 Then on each computer, change to this directory and run:
  19
  20         nice -n 18 ./autotest-client `hostname`-1
  21
  22 where 1 should be 2, 3, 4, ... for further instances of autotest you would
  23 run on the same machine (no two instaces with the same id must be run).
  24 The `nice -n 18` prefix will make sure the client is being run with low
  25 priority, in case someone wants to use the computer for some real interaction.
  26
  27 Leave cooking, stir time by time.  You can start and stop clients as much
  28 as you wish on the fly, or edit the rc file to change pairings without any
  29 need for restarting clients.
  30
  31
  32 Time by time, you will of course want to view the results of pairings.
  33 First, you will want to run:
  34
  35         ./autotest-gather
  36
  37 This will collect the results all in one place. Then, you can repeatedly
  38 examine the results using:
  39
  40         ./autotest-show
  41 or
  42         ./autotest-show-diagram
  43
  44 That will show results from all pairings. You can also use e.g.
  45
  46         ./autotest-show 9-*
  47
  48 to show only results of 9x9 pairings. To refresh the shown results, you
  49 will need to re-run autotest-gather; if you will always want to just see
  50 fresh results, combine the two commands:
  51
  52         ./autotest-gather; ./autotest-show
  53
  54 Note that the S.D. column is standard deviation of the shown winrate;
  55 to get a 95%-confidence interval of the winrate, roughly double the S.D.
  56 value. E.g. WINRATE 30% S.D. 5% means that with 95% probability, the real
  57 winrate is 30% +-10%. The meaning of the first 'S' column is:
  58
  59         x       errors reported by twogtp
  60         ?       unknown (not in rc) active pairing (OK if temporary)
  61         /       unknown inactive pairing
  62         !       known (in rc) inactive pairing (last refresh > 2 hours ago)
  63         .       known active pairing (normal)
  64
  65 To remove results of old pairings, use:
  66
  67         ./autotest-prune pairing-name
  68
  69 pairing-name can be either simply name of the pairing, or a mask matching
  70 many pairings (up to '*' for removal of all pairing results).
  71
  72 To show status of all known clients, use:
  73
  74         ./autotest-clients
  75
  76 (To remove a gone client, just remove its subdirectory in the c/ directory.)
  77 The WFAIL column shows number of worker failures recorded in the log; examine
  78 c/<clientid>/log for details, you can remove the log to reset the WFAIL
  79 number. Usually, worker failures will result from interrupting a client.
  80
  81
  82 DISCONNECTED USAGE
  83 ------------------
  84
  85 If your clients don't share a single filesystem, you can still use autotest
  86 just fine, with two exceptions:
  87
  88 * You will need to manually synchronize the 'rc' file between all your machines
  89
  90 * You will need to manually copy over c/*/ directory tree from all your systems
  91 back to the central server (to the appropriate c/*/ directories) every time
  92 before running ./autotest-gather.
  93
  94 * You will manually need to remove old pairing results on the clients.
  95
  96
  97 IMPLEMENTATION
  98 --------------
  99
 100 Autotest keeps all the state in plain files within the filesystem.
 101
 102 ./autotest-client will basically simply keep spawning `autotest-worker`
 103 which will read the rc file, pick a random pairing and use gogui-twogtp
 104 to play one game, then store the result in a dat file (and leave the sgf
 105 file archived for future inspection).
 106
 107 The client workers will create a directory structure like:
 108
 109         c/drahokam-1/beacon     # when was the client last active
 110         c/drahokam-1/log        # various events from client's life
 111         c/drahokam-1/<pair_id>/game.dat
 112         c/drahokam-1/<pair_id>/game-<N>.sgf
 113
 114 ...where drahokam-1 is the ./autotest-client parameter and <pair_id>
 115 is basically straightforwardly mangled version of `pairing` parameters.
 116
 117
 118 ./autotest-gather will simply go through directories of all clients and rain
 119 down all pairing results to a single place:
 120
 121         r/<pair_id>.dat
 122         r/<pair_id>.beacon  # when was the pairing last active
 123         r/<pair_id>.error  # number of games reporting error
 124
 125 Then, ./autotest-show will call gogui-twogtp -analyze on the selected
 126 produced dat files.
 127
 128
 129 Copyright (c) Petr Baudis <pasky@ucw.cz>
 130 Licenced under MIT licence (close to public domain).