Python API

Be sure to read and understand the rules before reading this page.

The sample python agent implements this API

You may still use the text based API if you insist.


  1. Start the script with from qchess import *
  2. Write a class Agent that inherits from InternalAgent
  3. Make sure Agent.__init__(self, name, colour) calls InternalAgent.__init__(self, name, colour)
  4. Implement, which must return [x,y]
  5. Implement Agent.get_move(self), which must return [x,y]
  6. Read the colour of the agent from stdin, then construct an agent = Agent(colour), and call run_agent(agent)


Useful things from

You can implement your own Quantum Chess pieces and board classes if you really want. However, there are already some in

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!

I'm going to dispense with the html for a bit, because I'm sick of having to type <li> every line.


InternalAgent - What you should inherit your Agent from if you want it to work
	colour - string representing colour of the agent
	board - instance of the Board class. This is automatically updated if you use run_agent
	choice - you should set this to the Piece that you select in

Piece - Class to represent a Quantum Chess piece
	colour - string representing colour of the piece
	types[2] - list containing the two types that the piece can be, as strings
	choice - integer; either -1 (superposition), 0, or 1 to indicate what type the piece is
	current_type - string representing the current piece's type; "unknown" for a superposition

Board - Class to represent a quantum chess board. InternalAgent.board is one of these.
	pieces[] - Dictionary that maps a colour string ("white" or "black") to a list of Piece's
		 - ie: Use to get your pieces
	possible_moves(self, piece, state = None) - Return a list of possible moves for piece. 
						  - If state is None, the piece must be in a known classical state
						  - If state is not None, the state of the piece will be temporarily set
	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.
				      - Does not perform any legality checks on the move
	pop_move(self) - Restore the state of the Board to whatever it was before the most recent call to Board.push_move()
	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]
								   - Colour can be set to only include pieces of a certain colour
								   - If reject_allied is True, pieces cannot move into squares occupied by pieces of the same colour
								   - If reject_allied is False, pieces are treated as being able to move into friendly squares
	prob_is_type(self, piece, state) - Return probability that Piece p is in a state
	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()
	opponent(colour) - return "white" iff colour == "black", else return "black"



Probably the best way to learn how to use these functions is to read the source for Agent Bishop

Page last updated 2013-02-28 by matches and rvvs89

Thanks to rvvs89 for prettifying things!

Also thanks to

The UCC Website

UCC::Progcomp 2013