web/agent_python.html

   1
   2 <html>
   3
   4 <head>
   5 <title> UCC::Progcomp 2013 - Writing an Agent - python </title>
   6
   7 <style>
   8 div.python > ul
   9 {
  10     list-style-type: none;
  11 }
  12
  13 .python .de1, .python .de2 {-moz-user-select: text;-khtml-user-select: text;-webkit-user-select: text;-ms-user-select: text;user-select: text;
  14 margin:0; padding: 0 5px; background:none; vertical-align:top;color:#000;border-left: 1px solid #ccc; margin: 0 0 0 -7px; position: relative; background: #ffffff;}
  15 .python  {color:#ACACAC;}
  16 .python .imp {font-weight: bold; color: red;}
  17 .python li, .python .li1 {-moz-user-select: -moz-none;-khtml-user-select: none;-webkit-user-select: none;-ms-user-select: none;user-select: none;
  18 }
  19 .python .ln {width:1px;text-align:right;margin:0;padding:0 2px;vertical-align:top;}
  20 .python .kw1 {color: #ff7700;font-weight:bold;}
  21 .python .kw2 {color: #008000;}
  22 .python .kw3 {color: #dc143c;}
  23 .python .kw4 {color: #0000cd;}
  24 .python .co1 {color: #808080; font-style: italic;}
  25 .python .coMULTI {color: #808080; font-style: italic;}
  26 .python .es0 {color: #000099; font-weight: bold;}
  27 .python .br0 {color: black;}
  28 .python .sy0 {color: #66cc66;}
  29 .python .st0 {color: #483d8b;}
  30 .python .nu0 {color: #ff4500;}
  31 .python .me1 {color: black;}
  32 .python .ln-xtra, .python li.ln-xtra, .python div.ln-xtra {color:black;background:#FFFF88;}
  33 .python span.xtra { display:block; }
  34
  35 </style>
  36
  37 </head>
  38
  39
  40
  41 <body bgcolor=white>
  42
  43 <h1> Python API </h1>
  44
  45 <p> Be sure to read and understand <a href="http://research.cs.queensu.ca/Parallel/QuantumChess/QuantumChess.html"/>the rules</a> before reading this page. </p>
  46 <p> </p>
  47 <p> The <a href="../agents/python"/>sample python agent</a> implements this API </p>
  48 <p> You may still use the <a href="agent_text.html"/>text based API</a> if you insist. </p>
  49
  50
  51 <h2> Overview </h2>
  52
  53 <ol>
  54         <li> Start the script with <code>from qchess import *</code> </li>
  55         <li> Write a class <code>Agent</code> that inherits from <code>InternalAgent</code> </li>
  56         <li> Make sure <code>Agent.__init__(self, name, colour)</code> calls <code>InternalAgent.__init__(self, name, colour)</code> </li>
  57         <li> Implement <code>Agent.select(self)</code>, which must return <code>[x,y]</code> </li>
  58         <ul>
  59                 <li> Where <code>x</code> and <code>y</code> are the x and y coordinates of the piece you want to select </li>
  60                 <li> <code>x</code> and <code>y</code> must be between <code>0</code> and <code>7</code> </li>
  61         </ul>
  62         <li> Implement <code>Agent.get_move(self)</code>, which must return <code>[x,y]</code> </li>
  63         <ul>
  64                 <li> Where <code>x</code> and <code>y</code> are the x and y coordinates of the square you wish to move the previously selected piece into. </li>
  65                 <li> <code>x</code> and <code>y</code> must be between <code>0</code> and <code>7</code> </li>
  66         </ul>
  67         <li> Read the colour of the agent from stdin, then construct an <code>agent = Agent(colour)</code>, and call <code>run_agent(agent)</code>
  68
  69 </ol>
  70
  71 <hr>
  72
  73 <h2> Skeleton </h2>
  74
  75 <code><div class="python"><ul><li class="li1"><div class="de1"><span class="co1">#!/usr/bin/python</span></div></li>
  76 <li class="li2"><div class="de2"><span class="kw1">from</span> qchess <span class="kw1">import</span> *</div></li>
  77 <li class="li1"><div class="de1"><span class="kw1">class</span> Agent<span class="br0">&#40;</span>InternalAgent<span class="br0">&#41;</span>:</div></li>
  78 <li class="li2"><div class="de2">&nbsp; &nbsp; &nbsp; &nbsp; <span class="kw1">def</span> <span class="kw4">__init__</span><span class="br0">&#40;</span><span class="kw2">self</span><span class="sy0">,</span> name<span class="sy0">,</span> colour<span class="br0">&#41;</span>:</div></li>
  79 <li class="li1"><div class="de1">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; InternalAgent.<span class="kw4">__init__</span><span class="br0">&#40;</span><span class="kw2">self</span><span class="sy0">,</span> name<span class="sy0">,</span> colour<span class="br0">&#41;</span></div></li>
  80 <li class="li2"><div class="de2">&nbsp; &nbsp; &nbsp; &nbsp; </div></li>
  81 <li class="li1"><div class="de1">&nbsp; &nbsp; &nbsp; &nbsp; <span class="kw1">def</span> <span class="kw3">select</span><span class="br0">&#40;</span><span class="kw2">self</span><span class="br0">&#41;</span>:</div></li>
  82 <li class="li2"><div class="de2">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <span class="co1">#TODO: Implement me!</span></div></li>
  83 <li class="li1"><div class="de1">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <span class="kw2">self</span>.<span class="me1">choice</span> <span class="sy0">=</span> <span class="co1">#a piece that you want to move</span></div></li>
  84 <li class="li1"><div class="de1">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <span class="kw1">return</span> <span class="br0">&#91;</span><span class="kw2">self</span>.choice.x<span class="sy0">,</span><span class="kw2">self</span>.choice.y<span class="br0">&#93;</span></div></li>
  85 <li class="li2"><div class="de2">&nbsp;</div></li>
  86 <li class="li1"><div class="de1">&nbsp; &nbsp; &nbsp; &nbsp; <span class="kw1">def</span> get_move<span class="br0">&#40;</span><span class="kw2">self</span><span class="br0">&#41;</span>:</div></li>
  87 <li class="li2"><div class="de2">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <span class="co1">#TODO: Implement me!</span></div></li>
  88 <li class="li2"><div class="de2">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <span class="co1">#      (ie: Find a move for self.choice)</span></div></li>
  89 <li class="li1"><div class="de1">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <span class="kw1">return</span> <span class="br0">&#91;</span>x<span class="sy0">,</span>y<span class="br0">&#93;</span></div></li>
  90 <li class="li2"><div class="de2">&nbsp; &nbsp; &nbsp; &nbsp; </div></li>
  91 <li class="li2"><div class="de2">&nbsp; &nbsp; &nbsp; &nbsp; </div></li>
  92 <li class="li1"><div class="de1"><span class="kw1">if</span> __name__ <span class="sy0">==</span> <span class="st0">&quot;__main__&quot;</span>:</div></li>
  93 <li class="li2"><div class="de2">&nbsp; &nbsp; &nbsp; &nbsp; colour <span class="sy0">=</span> <span class="kw3">sys</span>.<span class="me1">stdin</span>.<span class="kw3">readline</span><span class="br0">&#40;</span><span class="br0">&#41;</span>.<span class="me1">strip</span><span class="br0">&#40;</span><span class="st0">&quot; <span class="es0">\r</span><span class="es0">\n</span>&quot;</span><span class="br0">&#41;</span></div></li>
  94 <li class="li1"><div class="de1">&nbsp; &nbsp; &nbsp; &nbsp; agent <span class="sy0">=</span> Agent<span class="br0">&#40;</span>colour<span class="br0">&#41;</span></div></li>
  95 <li class="li2"><div class="de2">&nbsp; &nbsp; &nbsp; &nbsp; run_agent<span class="br0">&#40;</span>agent<span class="br0">&#41;</span></div></li>
  96 </ul></div></code>
  97
  98
  99 <hr>
 100
 101 <h2> Useful things from <code>qchess.py</code> </h2>
 102
 103 <p> You can implement your own Quantum Chess pieces and board classes if you really want. However, there are already some in <a href="../qchess/qchess.py"/>qchess.py</a> </p>
 104 <p> Don't worry, you don't have to read that file, because I will describe the things that it is safe to use right here! </p>
 105
 106 <p> I'm going to dispense with the html for a bit, because I'm sick of having to type &lt;li&gt; every line. </p>
 107
 108 <pre> <code>
 109
 110 InternalAgent - What you should inherit your Agent from if you want it to work
 111         colour - string representing colour of the agent
 112         board - instance of the Board class. This is automatically updated if you use run_agent
 113         choice - you should set this to the Piece that you select in Agent.select()
 114
 115 Piece - Class to represent a Quantum Chess piece
 116         colour - string representing colour of the piece
 117         types[2] - list containing the two types that the piece can be, as strings
 118         choice - integer; either -1 (superposition), 0, or 1 to indicate what type the piece is
 119         current_type - string representing the current piece's type; "unknown" for a superposition
 120
 121 Board - Class to represent a quantum chess board. InternalAgent.board is one of these.
 122         pieces[] - Dictionary that maps a colour string ("white" or "black") to a list of Piece's
 123                  - ie: Use to get your pieces
 124         possible_moves(self, piece, state = None) - Return a list of possible moves for piece.
 125                                                   - If state is None, the piece must be in a known classical state
 126                                                   - If state is not None, the state of the piece will be temporarily set
 127         push_move(self, piece, x, y) - *Temporarily* move piece to position [x,y]. If the square is occupied, the piece that was there is temporarily removed.
 128                                       - Does not perform any legality checks on the move
 129         pop_move(self) - Restore the state of the Board to whatever it was before the most recent call to Board.push_move()
 130         coverage(self, x, y, colour = None, reject_allied = True) - Returns a dictionary that maps pieces which could move to [x,y] to the probability they could move to [x,y]
 131                                                                    - Colour can be set to only include pieces of a certain colour
 132                                                                    - If reject_allied is True, pieces cannot move into squares occupied by pieces of the same colour
 133                                                                    - If reject_allied is False, pieces are treated as being able to move into friendly squares
 134         prob_is_type(self, piece, state) - Return probability that Piece p is in a state
 135         probability_grid(self, piece, reject_allied = True) - Return probability that piece can move into [x,y] for each [x,y] on the board. reject_allied is as in Board.coverage()
 136         opponent(colour) - return "white" iff colour == "black", else return "black"
 137
 138 </code> </pre>
 139
 140 <h2> Examples </h2>
 141
 142 <p> Probably the best way to learn how to use these functions is to read the source for <a href="../qchess/src/agent_bishop.py"/>Agent Bishop</a> </p>
 143
 144
 145 <hr>
 146
 147 <p> Page last updated 2013-02-28 by matches and rvvs89 </p>
 148 <p> <b> Thanks </b> to rvvs89 for prettifying things! </p>
 149 <p> Also thanks to <a href="http://pastebin.com">pastebin.com</a> </p>
 150
 151 <hr>
 152
 153 <p> <a href="http://www.ucc.asn.au">The UCC Website</a> </p>
 154 <p> <a href="http://progcomp.ucc.asn.au/2013/web">UCC::Progcomp 2013</a> </p>
 155
 156 </html>