doc/INTERNALS.txt

   1 INTERNALS.txt: Needless information about the internals
   2
   3 This document is unreliable, out of date and more than likely, utterly useless. But it's included anyway.
   4
   5 === Notes originally found in src/README ===
   6 Contributor instructions:
   7
   8 BaseAgent, LearningAgent and Supervisor are all implemented in uccProgComp.py.
   9 The 'select' algorithm, responsible for choosing agents for battle and
  10 determining when a round is finished, is the hottest part of the code and the
  11 most open to discussion and change.
  12
  13 Unfortunately, it is not an easy bit of code to understand. Once upon a time,
  14 in builds long past, it used friendly O(n) operations and conveniently wasted
  15 memory on simple tasks. After hours of profiling, it is a little more complex,
  16 but with a bit of background to how the supervisor operates you shouldn't have
  17 much trouble working out the rest:
  18
  19 1.) A copy of the current population list is made at the beginning of the round
  20 representing the agents who can still fight. This reduces finding valid agents
  21 from O(n) to O(1). I call it the 'remaining' list.
  22 2.) Agents must remember their index in the population list. This is because it
  23 would be O(n) to determine their index in the population list (to remove them
  24 when they die) from their index in the 'remaining' list. Agents have this value
  25 stored at the beginning of the round - O(n) at the beginning of the round is
  26 far preferable to O(n) for every death.
  27 3.) The actual removal of agents from the population list must happen all at
  28 once in reverse numeric index order at the end of the round so that the stored
  29 index that agents have does not become stale.
  30
  31 There are problems. It's not perfect, but it's relatively fast and powerful and
  32 quite easy to adjust or reimplement once you get your head around it. I'm very
  33 much open to suggestion for improvement (especially in the form of patches) and
  34 welcome all help, constructive criticism, derisive criticism and death threats.
  35
  36 Things to be done:
  37
  38 1.) Pretty graphs! Iterate () returns a collection of statistics about each of
  39 the classes, which can be seen used in simulate.py. There are plenty of
  40 plotting packages out there that can turn this information into impressive
  41 charts.
  42 2.) More built-in functionality for BaseAgent and LearningAgent. They could
  43 both do with a few more utility functions for competitors to use.
  44 3.) A more succint set of rules and documentation.
  45
  46 Thanks for reading!
  47 Luke