src/README

   1 Hi there,
   2
   3 Thanks for taking interest in the UCC Programming Competition 2008. If you
   4 don't already know what it's all about, check out the information provided in
   5 the docs directory, which contains a full and authoritative* description for
   6 the running of the competition.
   7
   8 This file is by no means complete, and not ready for circulation.
   9
  10 The first thing you'll probably want to do is see it work. Try running:
  11
  12 ./simulate -v
  13
  14 to see the sample agents duke it out for up to 150 rounds (the current sample
  15 agents suck - rounds either go for seconds or for ages). After that, take a
  16 look at sampleAgents.py to see how agents are implemented on top of the
  17 BaseAgent and LearningAgent classes. When you're ready to try out your own,
  18 edit the first few lines of simulate.py to include your agent.
  19
  20 ...and if all you're interested in is participating, that's it! You can stop
  21 reading, and start work on the agent that will outsmart them all!
  22
  23 Contributor instructions:
  24
  25 BaseAgent, LearningAgent and Supervisor are all implemented in uccProgComp.py.
  26 The 'select' algorithm, responsible for choosing agents for battle and
  27 determining when a round is finished, is the hottest part of the code and the
  28 most open to discussion and change.
  29
  30 Unfortunately, it is not an easy bit of code to understand. Once upon a time,
  31 in builds long past, it used friendly O(n) operations and conveniently wasted
  32 memory on simple tasks. After hours of profiling, it is a little more complex,
  33 but with a bit of background to how the supervisor operates you shouldn't have
  34 much trouble working out the rest:
  35
  36 1.) A copy of the current population list is made at the beginning of the round
  37 representing the agents who can still fight. This reduces finding valid agents
  38 from O(n) to O(1). I call it the 'remaining' list.
  39 2.) Agents must remember their index in the population list. This is because it
  40 would be O(n) to determine their index in the population list (to remove them
  41 when they die) from their index in the 'remaining' list. Agents have this value
  42 stored at the beginning of the round - O(n) at the beginning of the round is
  43 far preferable to O(n) for every death.
  44 3.) The actual removal of agents from the population list must happen all at
  45 once in reverse numeric index order at the end of the round so that the stored
  46 index that agents have does not become stale.
  47
  48 There are problems. It's not perfect, but it's relatively fast and powerful and
  49 quite easy to adjust or reimplement once you get your head around it. I'm very
  50 much open to suggestion for improvement (especially in the form of patches) and
  51 welcome all help, constructive criticism, derisive criticism and death threats.
  52
  53 Things to be done:
  54
  55 1.) Pretty graphs! Iterate () returns a collection of statistics about each of
  56 the classes, which can be seen used in simulate.py. There are plenty of
  57 plotting packages out there that can turn this information into impressive
  58 charts.
  59 2.) More built-in functionality for BaseAgent and LearningAgent. They could
  60 both do with a few more utility functions for competitors to use.
  61 3.) A more succint set of rules and documentation.
  62
  63 Thanks for reading!
  64 Luke
  65
  66 * Or rather, it wil by the time this package is ready for distribution.