Package: gym-chess
gym-chess: OpenAI Gym environments for ChessTable of ContentsIntroductionInstallationChess-v0ChessAlphaZero-v0AcknowledgementsIntroductiongym-chess providesOpenAI Gymenvironments for the
game of Chess. It comes with an implementation of the board and move
encoding used inAlphaZero,
yet leaves you the freedom to define your own encodings via wrappers.Let's watch a random agent play against itself:>>>importgym>>>importgym_chess>>>importrandom>>>env=gym.make('Chess-v0')>>>print(env.render())>>>env.reset()>>>done=False>>>whilenotdone:>>>action=random.sample(env.legal_moves)>>>env.step(action)>>>print(env.render(mode='unicode'))>>>env.close()Installationgym-chess requires Python 3.6 or later.To install gym-chess, run:$pipinstallgym-chessImporting gym-chess will automatically register theChess-v0andChessAlphaZero-v0envs with gym:>>>importgym>>>importgym_chess>>>gym.envs.registry.all()dict_values([...EnvSpec(Chess-v0),EnvSpec(ChessAlphaZero-v0)])Chess-v0gym-chess defines a basicChess-v0environment which represents
observations and actions as objects of typechess.Boardandchess.Move,
respectively. These classes come from thepython-chesspackage which implements
the game logic.>>>env=gym.make('Chess-v0')>>>state=env.reset()>>>type(state)chess.Board>>>print(env.render(mode='unicode'))♜♞♝♛♚♝♞♜♟♟♟♟♟♟♟♟⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘♙♙♙♙♙♙♙♙♖♘♗♕♔♗♘♖>>>move=chess.Move.from_uci('e2e4')>>>env.step(move)>>>print(env.render(mode='unicode'))♜♞♝♛♚♝♞♜♟♟♟♟♟♟♟♟⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘♙⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘⭘♙♙♙♙⭘♙♙♙♖♘♗♕♔♗♘♖A list of legal moves for the current position is exposed via thelegal_movesproperty:>>> env.reset()
>>> env.legal_moves
[Move.from_uci('g1h3'),
 Move.from_uci('g1f3'),
 Move.from_uci('b1c3'),
 Move.from_uci('b1a3'),
 Move.from_uci('h2h3'),
 Move.from_uci('g2g3'),
 Move.from_uci('f2f3'),
 Move.from_uci('e2e3'),
 Move.from_uci('d2d3'),
 Move.from_uci('c2c3'),
 Move.from_uci('b2b3'),
 Move.from_uci('a2a3'),
 Move.from_uci('h2h4'),
 Move.from_uci('g2g4'),
 Move.from_uci('f2f4'),
 Move.from_uci('e2e4'),
 Move.from_uci('d2d4'),
 Move.from_uci('c2c4'),
 Move.from_uci('b2b4'),
 Move.from_uci('a2a4')]Using ordinary Python objects (rather than NumPy arrays) as an agent interface
is arguably unorthodox. An immideate consequence of this approach is thatChess-v0has no well-definedobservation_spaceandaction_space; hence
these member variables are set toNone. However, this design allows us to
seperate the game'simplementationfrom itsrepresentation, which is left to
wrapper classes.The agent plays for both players, blackandwhite, by making moves
for either color in turn. An episode ends when a player wins (i.e. the agent
makes a move that puts the opponent player into checkmate), or the game results
in a draw (e.g. by reaching a stalemate position, insufficient material, or one
or more other draw conditions according to theFIDE Rules of Chess).
Note that there is currently no option for the agent to let a player resign or
offer a draw voluntarily.The agent receives a reward of +1 when the white player makes a winning move,
and a reward of -1 when the black player makes a winning move. All other rewards
are zero.ChessAlphaZero-v0gym-chess ships with an implementation of the board and move encoding proposed
byAlphaZero(seeSilver et al., 2017).>>>env=gym.make('ChessAlphaZero-v0')>>>env.observation_spaceBox(8,8,119)>>>env.action_spaceDiscrete(4672)For a detailed description of how these encodings work, consider reading the
paper or consult the docstring of the respective classes.In addition tolegal_moves, ChessAlphaZero-v0 also exposes a list of all
legal actions (i.e. encoded legal moves):>>>env.legal_actions[494,501,129,136,1095,1022,949,876,803,730,657,584,1096,1023,950,877,804,731,658,585]Moves can be converted to actions and vice versawith theencodeanddecodemethods, which may facilitate debugging and experimentation:>>> move = chess.Move.from_uci('e2e4')
>>> env.encode(move)
877
>>> env.encode(move) in env.legal_actions
True

>>> env.decode(877)
Move.from_uci('e2e4')Internally, the encoding is implemented via wrapper classes
(gym_chess.alphazero.BoardEncodingandgym_chess.alphazero.MoveEncoding,
respectively), which can be used independently of one another. This gives you
the flexibility to define your own board and move representations, and easily
switch between them.>>>importgym_chess>>>fromgym_chess.alphazeroimportBoardEncoding>>>env=gym.make('Chess-v0')>>>env=BoardEncoding(env,history_length=4)>>>env=MyEsotericMoveEncoding(env)AcknowledgementsThanks to @niklasf for providing the awesomepython-chesspackage.