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
  42 That will show results from all pairings. You can also use e.g.
  43
  44         ./autotest-show 9-*
  45
  46 to show only results of 9x9 pairings. To refresh the shown results, you
  47 will need to re-run autotest-gather; if you will always want to just see
  48 fresh results, combine the two commands:
  49
  50         ./autotest-gather; ./autotest-show
  51
  52 Note that the S.D. column is standard deviation of the shown winrate;
  53 to get a 95%-confidence interval of the winrate, roughly double the S.D.
  54 value. E.g. WINRATE 30% S.D. 5% means that with 95% probability, the real
  55 winrate is 30% +-10%. The meaning of the first 'S' column is:
  56
  57         x       errors reported by twogtp
  58         ?       unknown (not in rc) active pairing (OK if temporary)
  59         /       unknown inactive pairing
  60         !       known (in rc) inactive pairing (last refresh > 2 hours ago)
  61         .       known active pairing (normal)
  62
  63 To remove results of old pairings, use:
  64
  65         ./autotest-prune pairing-name
  66
  67 pairing-name can be either simply name of the pairing, or a mask matching
  68 many pairings (up to '*' for removal of all pairing results).
  69
  70 To show status of all known clients, use:
  71
  72         ./autotest-clients
  73
  74 (To remove a gone client, just remove its subdirectory in the c/ directory.)
  75 The WFAIL column shows number of worker failures recorded in the log; examine
  76 c/<clientid>/log for details, you can remove the log to reset the WFAIL
  77 number. Usually, worker failures will result from interrupting a client.
  78
  79
  80 DISCONNECTED USAGE
  81 ------------------
  82
  83 If your clients don't share a single filesystem, you can still use autotest
  84 just fine, with two exceptions:
  85
  86 * You will need to manually synchronize the 'rc' file between all your machines
  87
  88 * You will need to manually copy over c/*/ directory tree from all your systems
  89 back to the central server (to the appropriate c/*/ directories) every time
  90 before running ./autotest-gather.
  91
  92 * You will manually need to remove old pairing results on the clients.
  93
  94
  95 IMPLEMENTATION
  96 --------------
  97
  98 Autotest keeps all the state in plain files within the filesystem.
  99
 100 ./autotest-client will basically simply keep spawning `autotest-worker`
 101 which will read the rc file, pick a random pairing and use gogui-twogtp
 102 to play one game, then store the result in a dat file (and leave the sgf
 103 file archived for future inspection).
 104
 105 The client workers will create a directory structure like:
 106
 107         c/drahokam-1/beacon     # when was the client last active
 108         c/drahokam-1/log        # various events from client's life
 109         c/drahokam-1/<pair_id>/game.dat
 110         c/drahokam-1/<pair_id>/game-<N>.sgf
 111
 112 ...where drahokam-1 is the ./autotest-client parameter and <pair_id>
 113 is basically straightforwardly mangled version of `pairing` parameters.
 114
 115
 116 ./autotest-gather will simply go through directories of all clients and rain
 117 down all pairing results to a single place:
 118
 119         r/<pair_id>.dat
 120         r/<pair_id>.beacon  # when was the pairing last active
 121         r/<pair_id>.error  # number of games reporting error
 122
 123 Then, ./autotest-show will call gogui-twogtp -analyze on the selected
 124 produced dat files.
 125
 126
 127 Copyright (c) Petr Baudis <pasky@ucw.cz>
 128 Licenced under MIT licence (close to public domain).