release 0.3

SenteRelease 0.3.1

Arthur Wesley

Dec 16, 2021

TUTORIAL

1 Getting Started 31.1 Further Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Building & Contributing 52.1 Building documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Python Module Index 27

Index 29

i

Sente, Release 0.3.1

Sente (from the Japanese /) is a general-purpose open-source python library for the ancient chinese board gameGo/Badok/Weiqi. It allows for python code to simulate and play a game of Go and also read, edit and create SGFfiles. Sente is designed to be a Python 3 replacement for the gomill library. In addition to supporting Python 3, Senteis written in C++ which allows AIs that use Sente to take advantage of C++’s superior performance.

Sente runs on any operating system with python 3.5, 3.8 and 3.9 and can be installed via pip.

$ pip install sente

– or –

$ python3 -m pip install sente

TUTORIAL 1

sente_logo.svg

https://badge.fury.io/py/sente

https://sente.readthedocs.io/en/latest/

https://github.com/atw1020/sente/actions/workflows/tests.yml/badge.svg

https://pypi.org/project/sente/

https://github.com/mattheww/gomill


2 TUTORIAL

CHAPTER

ONE

GETTING STARTED

The Basic element in Sente is the sente.Game object which represents a Simple Game.

>>> import sente>>> game = sente.Game()

By default, sente creates a 19x19 game with Chinese Rules. 9x9 and 13x13 board sizes and Japanese rules can bespecified if desired.

note: japanese rules are not reccomended as sente does not currently include automatic dead stone removal.

>>> game = sente.Game(13)>>> game = sente.Game(19, sente.rules.JAPANESE)

moves can be played on the game using the play() method, and the board can be printed using the python print()function.

>>> game.play(4, 4)>>> game.play(16, 4)>>> game.play(4, 17)>>> print(game)

1 . . . . . . . . . . . . . . . . . . .2 . . . . . . . . . . . . . . . . . . .3 . . . . . . . . . . . . . . . . . . .4 . . . . . . . . * . . . . . * . .5 . . . . . . . . . . . . . . . . . . .6 . . . . . . . . . . . . . . . . . . .7 . . . . . . . . . . . . . . . . . . .8 . . . . . . . . . . . . . . . . . . .9 . . . . . . . . . . . . . . . . . . .10 . . . * . . . . . * . . . . . * . . .11 . . . . . . . . . . . . . . . . . . .12 . . . . . . . . . . . . . . . . . . .13 . . . . . . . . . . . . . . . . . . .14 . . . . . . . . . . . . . . . . . . .15 . . . . . . . . . . . . . . . . . . .16 . . . . . . . . * . . . . . * . . .17 . . . . . . . . . . . . . . . . . . .18 . . . . . . . . . . . . . . . . . . .19 . . . . . . . . . . . . . . . . . . .

A B C D E F G H J K L M N O P Q R S T

3


The text created by printing a Sente board is designed to be similar to the gomill ascii boards output. Unlike Gomillhowever, Sente uses unicode characters to represent black and white stones to make complex board positions morevisible and also plots star points.

Finally, Sente also provides utilities for reading and saving SGF files using the sente.SGF module

>>> from sente import sgf>>> game = sgf.load("Lee Sedol ladder game.sgf")>>> move_sequence = game.get_default_sequence()[:95]>>> game.play_sequence(move_sequence)>>> print(game)1 . . . . . . . . . . . . . . . . . . .2 . . . . . . . . . . . . . . . .3 . . . . . . . . . . . . . . .4 . . . . . . . * . . . . . . . .5 . . . . . . . . . . . . . . . . .6 . . . . . . . . . . . . . . . .7 . . . . . . . . . . . . . . .8 . . . . . . . . . . . . . . .9 . . . . . . . . . . . . . . .10 . . . * . * . . . . . * . .11 . . . . . . . . . . . .12 . . . . . . . . . .13 . . . . . . . . .14 . . . . . . . . .15 . . . . . . . . . .16 . . . * . . . . . * . . . . .17 . . . . . . . . . . .18 . . . . . . . . . . . . . . . .19 . . . . . . . . . . . . . . . . . .


1.1 Further Reading

• Game Trees

• SFG file reader

• NumPy conversion

• `GTP (Go Text Protocol) <>`_ (Coming Soon!)

• `Automatic Dead Stone removal <>`_ (Coming Soon!)

4 Chapter 1. Getting Started

https://mjw.woodcraft.me.uk/gomill/doc/0.7/ascii_boards.html

https://sente.readthedocs.io/en/latest/tutorial/game%20tree%20navigation.html

https://sente.readthedocs.io/en/latest/tutorial/sgf.html

https://sente.readthedocs.io/en/latest/tutorial/numpy.html

CHAPTER

TWO

BUILDING & CONTRIBUTING

Sente uses CMake, git and C++11. In order to build the library, you will need CMake, and a C++ compiler that supportsC++11. You can install these using a software package installer like homebrew or apt.

OSx

$ brew install git$ brew install cmake$ brew install clang++

Debian/Ubuntu

$ sudo apt-get install git$ sudo apt-get install cmake$ sudo apt-get install g++

A sente binary can be built by running the setup script.

$ python3 setup.py develop

To import the resulting .so file, simply import sente in a local python interpreter

$ python3 setup.py develop$ python3

Python 3.8.10 (v3.8.10:3d8993a744, May 3 2021, 09:09:08)[Clang 12.0.5 (clang-1205.0.22.9)] on darwinType "help", "copyright", "credits" or "license" for more information.>>> import sente>>>

2.1 Building documentation

in order to build the documentation, you will need to have sphinx installed and build a development version of sente.

$ pip install -r requirements.txt # install sphinx$ python setup.py develop # build a development version of sente$ cd docs$ make html # make the html

5

https://cmake.org

https://git-scm.com

https://www.sphinx-doc.org/en/master/


2.1.1 Docs

Basics

Installation

Sente runs on any operating system with python 3.x and can be installed via pip.

$ pip install sente

– or –

$ python3 -m install sente

Getting Started

The Basic element in Sente is the sente.Game object which represents a Simple Game.

>>> import sente>>> game = sente.Game()

By default, sente creates a 19x19 game with Chinese Rules. 9x9 and 13x13 board sizes and Japanese rules can bespecified if desired.

>>> game = sente.Game(13)>>> game = sente.Game(19, sente.rules.JAPANESE)

Warning: Japanese rules may not be advisable because sente has no means of automatic dead stone detection (atpresent)

Moves can be played on the game using the play() method, and the board can be printed using the python print()function.

>>> game.play(4, 4)>>> game.play(16, 4)>>> game.play(4, 17)>>> print(game)1 . . . . . . . . . . . . . . . . . . .2 . . . . . . . . . . . . . . . . . . .3 . . . . . . . . . . . . . . . . . . .4 . . . . . . . . * . . . . . * . .5 . . . . . . . . . . . . . . . . . . .6 . . . . . . . . . . . . . . . . . . .7 . . . . . . . . . . . . . . . . . . .8 . . . . . . . . . . . . . . . . . . .9 . . . . . . . . . . . . . . . . . . .10 . . . * . . . . . * . . . . . * . . .11 . . . . . . . . . . . . . . . . . . .12 . . . . . . . . . . . . . . . . . . .13 . . . . . . . . . . . . . . . . . . .

(continues on next page)

6 Chapter 2. Building & Contributing


(continued from previous page)

14 . . . . . . . . . . . . . . . . . . .15 . . . . . . . . . . . . . . . . . . .16 . . . . . . . . * . . . . . * . . .17 . . . . . . . . . . . . . . . . . . .18 . . . . . . . . . . . . . . . . . . .19 . . . . . . . . . . . . . . . . . . .


The text created by printing a Sente board is designed to be similar to the [gomill ascii boards output](https://mjw.woodcraft.me.uk/gomill/doc/0.7/ascii_boards.html). Unlike Gomill however, Sente uses Unicode characters to repre-sent black and white stones to make complex board positions more visible and plot star points.

Finally, Sente also provides utilities for reading and saving SGF files using the sente.SGF module

>>> from sente import sgf>>> game = sgf.load("Lee Sedol ladder game.sgf")>>> move_sequence = game.get_default_sequence()[:95]>>> game.play_sequence(move_sequence)>>> print(game)1 . . . . . . . . . . . . . . . . . . .2 . . . . . . . . . . . . . . . .3 . . . . . . . . . . . . . . .4 . . . . . . . * . . . . . . . .5 . . . . . . . . . . . . . . . . .6 . . . . . . . . . . . . . . . .7 . . . . . . . . . . . . . . .8 . . . . . . . . . . . . . . .9 . . . . . . . . . . . . . . .10 . . . * . * . . . . . * . .11 . . . . . . . . . . . .12 . . . . . . . . . .13 . . . . . . . . .14 . . . . . . . . .15 . . . . . . . . . .16 . . . * . . . . . * . . . . .17 . . . . . . . . . . .18 . . . . . . . . . . . . . . . .19 . . . . . . . . . . . . . . . . . .A B C D E F G H J K L M N O P Q R S T

2.1. Building documentation 7




Game Tree Navigation

The sente.game object records all of the moves played in a tree structure. Sente provides utilities for navigatingaround this tree with the game.play(), game.step_up() and game.get_branches() methods.

Playing Stones

The game.play() method plays at a given point on the board.

>>> import sente>>> game = sente.Game(9) # creates a 9x9 board>>> game.play(4, 4) # plays a stone on the 4-4 point>>> print(game)1 . . . . . . . . .2 . . . . . . . . .3 . . * . . . * . .4 . . . . . . . .5 . . . . * . . . .6 . . . . . . . . .7 . . * . . . * . .8 . . . . . . . . .9 . . . . . . . . .

A B C D E F G H J

Undoing Moves

On the other hand, the game.step_up() method undoes the previous move played on the board.

>>> game = sente.Game(9)>>> game.play(4, 4)>>> game.step_up() # undo the previous move>>> print(game)1 . . . . . . . . .2 . . . . . . . . .3 . . * . . . * . .4 . . . . . . . . .5 . . . . * . . . .6 . . . . . . . . .7 . . * . . . * . .8 . . . . . . . . .9 . . . . . . . . .

A B C D E F G H J

Repeatedly calling step_up() can be tedious and slow, so the number of steps that step_up() takes can be specifiedas an argument.

>>> game = sente.Game(9)>>> game.play(4, 4)>>> game.play(7, 7)>>> game.play(7, 4)>>> game.step_up(2) # undo two moves





>>> print(game)1 . . . . . . . . .2 . . . . . . . . .3 . . * . . . * . .4 . . . . . . . .5 . . . . * . . . .6 . . . . . . . . .7 . . * . . . * . .8 . . . . . . . . .9 . . . . . . . . .

A B C D E F G H J

Another alternative to the step_up() method is the advance_to_root() method, which simply undoes every movein the game, leaving the board empty.

>>> game = sente.Game(9)>>> game.play(4, 4)>>> game.play(7, 7)>>> game.play(7, 4)>>> game.advance_to_root()>>> print(game)1 . . . . . . . . .2 . . . . . . . . .3 . . * . . . * . .4 . . . . . . . . .5 . . . . * . . . .6 . . . . . . . . .7 . . * . . . * . .8 . . . . . . . . .9 . . . . . . . . .

A B C D E F G H J

Once moves have been undone, the move(s) played at a given tree node can be obtained using the get_branches()method.

>>> game = sente.Game(9)>>> game.play(4, 4)>>> game.play(7, 7)>>> game.step_up()>>> print(game.get_branches())[<sente.Move W[gg]>]

The sente.Move object is an object that can be passed to the game.play() method to play the specified move. Theget_branches() method returns a python list containing all of the moves played at the current nod.

>>> game = sente.Game(9)>>> game.play(4, 4)>>> game.play(7, 7)>>> game.step_up()>>> branches = game.get_branches()>>> game.play(branches[0])>>> print(game)1 . . . . . . . . .





2 . . . . . . . . .3 . . * . . . * . .4 . . . . . . . .5 . . . . * . . . .6 . . . . . . . . .7 . . * . . . . .8 . . . . . . . . .9 . . . . . . . . .

A B C D E F G H J

If multiple branches exist from the current node, then get_branches() will return a list containing all of them.

Move Comments

Each node of the Game tree is allowed to have a “comment” associated with it. These comments typically includecommentary on the game and can also include messages sent by the players during the game. The comment associatedwith the current node can be accessed through the comment attribute.

>>> game = sente.Game()>>> game.comment = "the start of the game">>> print(game.comment)the start of the game>>> game.play(4, 4)>>> print(game.comment) # the comment from the start of the game is still stored,

>>> game.comment = "the first move of the game">>> print(game.comment)the first move of the game>>> game.step_up()>>> print(game.comment)the start of the game

Move Sequences

When undoing moves in sente, it can be tricky to keep track of the sequence of moves that leads to a given board position.To make game tree navigation more straightforward, the sente.Game Object contains a method called get_sequencethat generates a python list containing the sequence of moves that have been played in the game so far.

>>> game.play(4, 4)>>> game.play(15, 4)>>> game.play(15, 15)>>> print(game.get_sequence())[<sente.Move B[dd]>, <sente.Move W[od]>, <sente.Move B[oo]>]

If the moves in a sequence are undone, the board position can be restored by using the play_sequence() method.

>>> print(game)1 . . . . . . . . . . . . . . . . . . .2 . . . . . . . . . . . . . . . . . . .3 . . . . . . . . . . . . . . . . . . .





4 . . . . . . . . * . . . . . * . . .5 . . . . . . . . . . . . . . . . . . .6 . . . . . . . . . . . . . . . . . . .7 . . . . . . . . . . . . . . . . . . .8 . . . . . . . . . . . . . . . . . . .9 . . . . . . . . . . . . . . . . . . .10 . . . * . . . . . * . . . . . * . . .11 . . . . . . . . . . . . . . . . . . .12 . . . . . . . . . . . . . . . . . . .13 . . . . . . . . . . . . . . . . . . .14 . . . . . . . . . . . . . . . . . . .15 . . . . . . . . . . . . . . . . .16 . . . * . . . . . * . . . . . * . . .17 . . . . . . . . . . . . . . . . . . .18 . . . . . . . . . . . . . . . . . . .19 . . . . . . . . . . . . . . . . . . .

A B C D E F G H J K L M N O P Q R S T>>> move_sequence = game.get_sequence()>>> game.step_up(3) # alternatively, you could use the advance_to_root() method>>> game.play_sequence(move_sequence)>>> print(game)1 . . . . . . . . . . . . . . . . . . .2 . . . . . . . . . . . . . . . . . . .3 . . . . . . . . . . . . . . . . . . .4 . . . . . . . . * . . . . . * . . .5 . . . . . . . . . . . . . . . . . . .6 . . . . . . . . . . . . . . . . . . .7 . . . . . . . . . . . . . . . . . . .8 . . . . . . . . . . . . . . . . . . .9 . . . . . . . . . . . . . . . . . . .10 . . . * . . . . . * . . . . . * . . .11 . . . . . . . . . . . . . . . . . . .12 . . . . . . . . . . . . . . . . . . .13 . . . . . . . . . . . . . . . . . . .14 . . . . . . . . . . . . . . . . . . .15 . . . . . . . . . . . . . . . . .16 . . . * . . . . . * . . . . . * . . .17 . . . . . . . . . . . . . . . . . . .18 . . . . . . . . . . . . . . . . . . .19 . . . . . . . . . . . . . . . . . . .


Additionally, because the get_sequence method returns a python list, python list slicing is supported.



The sgf (Smart Game Format) Module

The sente.sgf module contains functions for parsing SGF (Smart Game Format) Files. SGF is a standard encodingfor go games that is capable of encoding “forked” go matches in addition to a raw sequence of moves. SGF files canbe viewed in programs like CGoban or Sabaki.

Note: sente is a library for Go and cannot be used for other games.

Loading Games

SGF files can be loaded into sente using the sgf.load function. sgf.load returns a sente.Game object with a movetree that has been populated with the game tree in the SGF file.

>>> from sente import sgf>>> game = sgf.load("Lee Sedol ladder game.sgf")

Note: The SGF.load() (and SGF.dump()) functions can accept python path objects from the built in os and pathlibmodules.

When sente loads an SGF file, it does not play out the sequence of moves in the game. It populates an internal gametree with the moves played, but it does not play them on the board. After the game is loaded, the game will still havean empty board. However, if the get_children method is called, we can see that the opening move will be populated

>>> print(game) # the board is empty but the SGF file is loaded1 . . . . . . . . . . . . . . . . . . .2 . . . . . . . . . . . . . . . . . . .3 . . . . . . . . . . . . . . . . . . .4 . . . * . . . . . * . . . . . * . . .5 . . . . . . . . . . . . . . . . . . .6 . . . . . . . . . . . . . . . . . . .7 . . . . . . . . . . . . . . . . . . .8 . . . . . . . . . . . . . . . . . . .9 . . . . . . . . . . . . . . . . . . .10 . . . * . . . . . * . . . . . * . . .11 . . . . . . . . . . . . . . . . . . .12 . . . . . . . . . . . . . . . . . . .13 . . . . . . . . . . . . . . . . . . .14 . . . . . . . . . . . . . . . . . . .15 . . . . . . . . . . . . . . . . . . .16 . . . * . . . . . * . . . . . * . . .17 . . . . . . . . . . . . . . . . . . .18 . . . . . . . . . . . . . . . . . . .19 . . . . . . . . . . . . . . . . . . .

A B C D E F G H J K L M N O P Q R S T>>> game.get_branches() # if we use get_branches() we can see that a branch has been␣→˓initiated[<sente.Move B[dp]>]

It can be pretty tedious to play through every move by calling get_branches() and selecting the first branch everytime, so sente provides the get_default_sequence() and play_default_sequence() methods to make it easier


https://www.gokgs.com/download.jsp

https://sabaki.yichuanshen.de


to play through games. If we wish to play the game through Hong Jansik’s resignation at move 212, we can use theplay_default_sequence() method to play out the main branch of the game.

>>> game.play_default_sequence()>>> print(game)1 . . . . . . . . . . . . . . . . . .2 . . . . . . . . . . . .3 . . . . . . . .4 . . . . . . . . . .5 . . . . . . . . . . . . .6 . . . . . . . . . . . . . . . .7 . . . . . . . . . . . . .8 . . . . . . . . . . . . . . .9 . . . . . . . . . . . .10 . * . . . . * . .11 . . . . . .12 . . . . .13 . . .14 . . .15 . . .16 . . . .17 . . . .18 . . . . . . .19 . . . . . . . . . . .


Alternatively, sente also provides the get_default_sequence() method, which returns the sequence of moves ratherthan playing them out. Because the sequence of moves is a python list, it is subject to python list slicing, which can beused to play the first X moves of the game if desired.

>>> game.advance_to_root()>>> sequence = game.get_default_sequence()>>> game.play_sequence(sequence[:95]) # Lee Sedol's famous ladder sequence>>> print(game)1 . . . . . . . . . . . . . . . . . . .2 . . . . . . . . . . . . . . . .3 . . . . . . . . . . . . . . .4 . . . . . . . * . . . . . . . .5 . . . . . . . . . . . . . . . . .6 . . . . . . . . . . . . . . . .7 . . . . . . . . . . . . . . .8 . . . . . . . . . . . . . . .9 . . . . . . . . . . . . . . .10 . . . * . * . . . . . * . .11 . . . . . . . . . . . .12 . . . . . . . . . .13 . . . . . . . . .14 . . . . . . . . .15 . . . . . . . . . .16 . . . * . . . . . * . . . . .17 . . . . . . . . . . .18 . . . . . . . . . . . . . . . .19 . . . . . . . . . . . . . . . . . .




Saving Games

Once a game has been played out, the sgf.dump() function can save a SGF of the file. If it is desired to add SGFmetadata to the file, such as the player’s names and ranks, it must be done before dumping the game. See SGF Metadatafor more details

>>> game.play_sequence(long_sequence)>>> sgf.dump(game, "my game.sgf")

loads and dumps

SGF files are a kind of raw text file similarly to .py, .csv and .json files. Because of this, Sente’s internal file readercan decode plain text, and the sgf module provides this utility in the form of the sgf.loads and sgf.dumps functions.This is similar to how python’s built-in json library works.

SGF Metadata

In addition to containing a record of the sequence of moves in a game, SGF files contain metadata associated with thegames. This metadata might include things like the name of the black player, the Komi the match was played with, or apoint on the board marked with a circle. Each such piece of metadata is called a “property” in the SGF file format. Eachproperty has a two-capitol-letter code that uniquely identifies that property called the “property code.” For example,the “KM” property code refers to the place where the komi of the game is recorded.

A complete list of all legal properties and their descriptions may be found at this red-bean archive. A partial list ofproperties is given below.

Table 1: SGF PropertiesCode Root or Node MeaningFF Root SGF format standard (usually SGF 4)KM Root The Komi of the gamePB Root Player Black (the name of the black player ie. “Honinbo Shusaku”PW Root Player White (the name of the white player ie. “Gennan Inseki”)RU Root The ruleset to use (ie. “Chinese”)SZ Root The size of the board the game was played on (ie. 19)C Node The comment associated with the current SGF node.CR Node Mark a point with a CircleTR Node mark a point with a TriangleAB Node Add a Black stone at the specified point.AW Node Add a White stone at the specified point.

Sente divides properties into two categories: Root properties and Node properties

• Root Properties: information associated with the game as a whole.– KM (the amount of Komi associated with the game)

– PB (the name of the person playing with the black stones)

– RU (the ruleset of the game)

• Node Properties: information associated with the current node of the game tree.– C (puts a comment on the node)

– CR (marks a point on the board with a circle)


https://en.wikipedia.org/wiki/Plain_text

https://docs.python.org/3/library/json.html

https://www.red-bean.com/sgf/properties.html


– AB (adds a white stone to the board, regardless of whose turn it currently is)

To obtain metadata properties from a sente.Game Object, call the get_properties

Reading metadata

The Game.get_properties() method can obtain metadata from an SGF file.

For example, say we have an SGF file containing a game record of the Honinbo Shusaku’s famous “Ear-ReddeningGame.”

>>> game = sgf.load("ear reddening game.sgf")>>> game.get_properties(){'PB': 'Yasuda Shusaku', # PB: Name of the black player'BR': '4d', # BR: Rank of the black player'PW': 'Inoue Gennan Inseki', # PW: Name of the white player'RE': 'B+2', # RE: Result of the game (Black wins by 2 points)'WR': '8d', # WR: Rank of the white player'DT': '1846-09-11,14,15'} # DT: Date(s) the game was played

As seen above, the resulting dictionary will map from the property code to the value associated with the property. Thisvalue is typically a string, but in some cases, it may be a list of strings if the property is associated with multiple values.

The get_properties() method will return all of the root properties of the game as well as properties associated withthe currently active node in the SGF tree. Thus, while the root properties will be the same no matter what move of thegame you are on, the node properties will change as you step through a game.

Setting metadata

Sente can set the metadata properties of a Game object using the set_property() method.

>>> game = sente.Game()>>> game.set_property("PB", "Arthur Wesley")>>> game.set_property("PW", "Lucas Wesley")>>> game.get_properties(){'FF': '4','SZ': '19','PB': 'Arthur Wesley','RU': 'Chinese','PW': 'Lucas Wesley'}

As mentioned above, Sente strictly enforces conformity to the official SGF file format, and custom SGF properties arenot permitted as metadata. Thus, setting a property not defined by the standard will result in an error.

>>> game = sente.Game()>>> game.set_property("JD", "Kaei 5-11-17")Traceback (most recent call last):File "<stdin>", line 1, in <module>

sente.exceptions.InvalidSGFException: unknown SGF Property "JD"



Numpy Conversion

For deep learning applications, it is often desirable to represent a board as a NumPy array to be passed to a deeplearning library such as TensorFlow or PyTorch. The sente.game object provides the numpy() method to create anumpy representation of the board.

>>> import sente>>> game = sente.Game()>>> numpy_array = game.numpy()>>> print(numpy_array)[[[0 0 1 0][0 0 1 0][0 0 1 0]...[0 0 1 0][0 0 1 0][0 0 1 0]]

...

[[0 0 1 0][0 0 1 0][0 0 1 0]...[0 0 1 0][0 0 1 0][0 0 1 0]]]

Sente converts a game to a NumPy array by creating several 19x19 (or 9x9 or 13x13 respectively) NumPy array thatcontains some feature associated with each point on the board. These features are 1-hot encoded facts about the board,such as the presence of a black or white stone or whether or not the point in question is a Ko point.

By default, the numpy() method uses four such features, namely the presence of white stones, black stones, emptypoints, and ko points. However, if a different set of features is desired, it is possible to pass the numpy() method a listof strings specifying the desired characteristics.

>>> import sente>>> game = sente.Game()>>> array = game.numpy(["black_stones", "white_stones"])>>> array.shape(19, 19, 2)

Thus, the Game.numpy() method returns an NxNxF NumPy array where N denotes the size of the board (i.e., 19) andF denotes the number of features per point on the board.


https://www.tensorflow.org

https://pytorch.org


Gotchas

This page contains some easy-to-make mistakes that come up when writing code using sente.

Boards vs Games

Sente provides two different constructs that represent go boards: the sente.Game object and the various sente.Board<9, 13, 19> objects. On the surface, it seems like these objects are similar to each other because both representa position on a go board and both have a play method.

TL;DR just use sente.Game.

The difference between the two is that a sente.Board contains only the location of the stones on the board and nothingelse. The sente.Board Objects do not know anything about capturing stones, Whose turn it is, or Kos. sente.Boardobjects only exist in sente if for some reason you need to ignore the rules of the game.

Internal vs external Co-ordinates

Internally, Sente represents coordinates on a go board with zero-based indexing. This means that internally, a stone onthe 1-1 corner point would actually be located at the index (0, 0) rather than (1, 1). The Game.play() methodhides this from you by automatically subtracting 1 from the coordinates that you specify. However sente.Move objectsuse Internal Indexing and thus if you wish to instantiate a sente.Move Object, the coordinates must zero-indexed.

>>> move = sente.Move(0, 0, sente.stone.WHITE) # move is actually on the 1-1 point>>> game.play(1, 1)>>> game.play(move)Traceback (most recent call last):File "<stdin>", line 1, in <module>

sente.exceptions.IllegalMoveException: The Desired move W[aa] lies on an occupied point

Because of this, Instantiating the sente.Move object directly is inadvisable and using sente.play(x, y) is preferred.

Sente library

Documentation for the Contents of the sente library

stone

class sente.stone

An enumeration for a Go stone.

>>> stone = sente.stone.BLACK>>> print(stone)stone.BLACK

Members:

BLACK : Represents a Black Go Stone.


https://en.wikipedia.org/wiki/Zero-based_numbering


WHITE : Represents a White Go Stone.

EMPTY : Represents an empty point on the grid.

property name

rules

class sente.rules

An enumeration for a Go Rules Set.

>>> rules = sente.rules.CHINESE>>> print(rules)rules.CHINESE

Members:

CHINESE : The Chinese rules for go.

JAPANESE : The Japanese rules for go.

KOREAN : The Korean rules for go.

property name

results

class sente.results

get_black_points(self: sente.results)→ intgets the number of points that black scored

Returns the number of points that black scored

get_white_points(self: sente.results)→ floatgets the number of points that white scored

Returns the number of points that black scored

get_winner(self: sente.results)→ sente.stonegets the winner of the game

Returns sente.stone of the winner of the game

Move

class sente.MoveA class that represents a move that can be played on a go board, consisting of a position and a stone.

Membersget_stone(self: sente.Move)→ sente.stone

get the stone that the player will place on the board

Returns sente.stone object that the move contains

get_x(self: sente.Move)→ intget the x-coordinate of the move (internal indices)


https://senseis.xmp.net/?ChineseRules

https://senseis.xmp.net/?JapaneseRules

https://senseis.xmp.net/?KoreanRules


Returns x-coordinate of the move

get_y(self: sente.Move)→ intget the y-coordinate of the move (internal indices) AFWEIJOIEJFUIF

Returns y-coordinate of the move

Board Classes

class sente.Board9

get_side(self: sente.Board9)→ intget the length of the side of the board

Returns the length of the side of the board (9)

get_stone(self: sente.Board9, arg0: int, arg1: int)→ sente.stoneget the stone located on the specified point.

Parameters• x – The x co-ordinate to get the stone for.

• y – The y co-ordinate to get the stone for.

Returns the stone located at specified point

play(self: sente.Board9, move: sente.Move)→ Noneplay a stone on the board

Parameters move – the move object to play

class sente.Board13









class sente.Board19











Game

class sente.GameThe Sente Game object.

The sente.Game Object differs from the sente.Board object in that it accounts for the rules of Go and iscapable of capturing stones and deeming ko moves invalid. For more on the difference between sente.Gameand sente.Board see Boards vs Games.

advance_to_root(self: sente.Game)→ NoneAdvance the board tree position to the root of the tree (ie. an empty board).

property commentThe comment associated with the given node

get_active_player(self: sente.Game)→ sente.stoneget the stone color of the active player (the player whose turn it is right now).

Returns the stone color of the active player.

get_all_sequences(self: sente.Game)→ List[List[sente.Move]]generates a list of all variations currently in the game

the “default” sequences is the first element in this list

Returns a list of lists of moves where each move is the move sequence.

get_board(self: sente.Game)→ sente::_boardGet the board object that the game is updating internally.

Returns a sente.Board object that represents the board to be played.

get_branches(self: sente.Game)→ List[sente.Move]generates a list of the branches at the current node of the game tree.

Returns list of branches at the current node of the tree

get_current_sequence(self: sente.Game)→ List[sente.Move]generate the sequence of moves that leads to the current board position

Returns a python list containing the moves that lead to this position.

get_default_sequence(self: sente.Game)→ List[sente.Move]generates a list of the moves in the default branch.

Returns the sequence of moves that leads to the current board position.



get_legal_moves(self: sente.Game)→ List[sente.Move]generates a list of all legal moves

Returns list of legal moves on the current board

get_point(self: sente.Game, x: int, y: int)→ sente.stoneget move played at the specified position.

Parameters• x – x co-ordinate of the point to locate.

• y – y co-ordinate of the point to locate.

Returns a sente.stone object representing the specified point

get_properties(self: sente.Game)→ dictGet all of the properties from the SGF file.

Returns a python dictionary that maps from metadata parameters (ie. SZ[], FF[]) to their values

get_results(self: sente.Game)→ sente.resultsreturns a results object for a game.

Warning: This method does not remove dead stones

Returns sente.results object.

get_winner(self: sente.Game)→ sente.stonedetermines the winner of the game.

Warning: This method does not remove dead stones.

Returns sente.stone of the winner of the game.

is_at_root(self: sente.Game)→ boolDetermine if the board is currently at the root of the tree.

Returns whether or not the board is at the root of the tree.

is_legal(*args, **kwargs)Overloaded function.

1. is_legal(self: sente.Game, x: int, y: int) -> bool

Checks to see if a move is legal.

Sente checks five conditions to see if a move is illegal

1. Are the coordinates of the move located on the board?

2. Does the move lie on an occupied point?

3. Is it the person playing the stone’s turn?

4. Does the move result in self-capture?

5. Is the move illegal because of a Ko?

param x The x co-ordinate of the move.



param y The y co-ordinate of the move.

return whether or not the move satisfies the above conditions.

2. is_legal(self: sente.Game, x: int, y: int, stone: sente.stone) -> bool


Sente checks five conditions to see if a move is illegal (see above).

param x The x co-ordinate of the move.

param y The y co-ordinate of the move.

param stone The color of the player making the move.


3. is_legal(self: sente.Game, move: sente.Move) -> bool


Sente checks five conditions to see if a move is illegal (see above).

param move A move object to play


4. is_legal(self: sente.Game, arg0: object) -> bool

An overloaded extension of the is_legalmethod accepts None as an argument. Using game.play(None) is interpreted as passing, and this method ensures that such a move is legal.

param move A move object to play


is_over(self: sente.Game)→ booldetermine if the game is over yet

Returns whether or not the game has ended

numpy(*args, **kwargs)Overloaded function.

1. numpy(self: sente.Game, arg0: List[str]) -> numpy.ndarray[numpy.uint8]

2. numpy(self: sente.Game) -> numpy.ndarray[numpy.uint8]

play(*args, **kwargs)Overloaded function.

1. play(self: sente.Game, x: int, y: int) -> None

Plays a stone on the board at the specified location and Captures and stones

param x The x co-ordinate of the move to play.

param y The y co-ordinate of the move to play:

raises IllegalMoveException If the move is illegal. (see Game.is_legal)

2. play(self: sente.Game, x: int, y: int, stone: sente.stone) -> None


param x The x co-ordinate of the move to play.

param y The y co-ordinate of the move to play:



param stones The color of the stone to play.


3. play(self: sente.Game, move: sente.Move) -> None


param move The Move object to play


4. play(self: sente.Game, arg0: object) -> None


param move The Move object to play


raises ValueError If a valid Move object is not passed

play_default_sequence(self: sente.Game)→ Noneplays out the moves in the default (first) branch of the tree

play_sequence(self: sente.Game, moves: List[sente.Move])→ Noneplays all of the moves in a given list of moves

Parameters moves – a list of move objects to play

Raises IllegalMoveException – If any move in the sequence is illegal

pss(self: sente.Game)→ Nonecauses the current active player to pass.

resign(self: sente.Game)→ Nonecauses the current active player to resign.

score(self: sente.Game)→ sente.resultsscores a game and returns the results.

Warning: This method does not remove dead stones

Returns sente.results object.

set_property(*args, **kwargs)Overloaded function.

1. set_property(self: sente.Game, arg0: str, arg1: float) -> None

Adds the specified property to the game

param property SGF property to set the value of

param value value to set the metadata to

return None

2. set_property(self: sente.Game, arg0: str, arg1: str) -> None






return None

3. set_property(self: sente.Game, arg0: str, arg1: List[str]) -> None




return None

step_up(self: sente.Game, steps: int = 1)→ Nonestep up the tree the specified number of steps. ie. undo the specified number of moves

Parameters steps – the number to steps to step up

The sgf Module

utilities for parsing SGF (Smart Game Format) files

sente.sgf.dump(game: sente.Game, file_name: str)→ Nonesaves a game as an SGF

sente.sgf.dumps(game: sente.Game)→ strSerialize a string as an SGF

sente.sgf.load(filename: str, disable_warnings: bool = False, ignore_illegal_properties: bool = True,fix_file_format: bool = True)→ sente.Game

Loads a go game from an SGF file.

Parameters• filename – the name of the file

• disable_warnings – whether to ignore warnings when loading an illegal SGF file

• ignore_illegal_properties – whether or not to ignore illegal SGF properties

• fix_file_format – whether or not to fix the file format if it is wrong

Returns a sente.Game object populated with data from the SGF file

sente.sgf.loads(sgf_text: str, disable_warnings: bool = False, ignore_illegal_properties: bool = True,fix_file_format: bool = True)→ sente.Game

Loads a go game from an SGF file.

Parameters• sgf_text – the text of the SGF file to read from

• disable_warnings – whether to ignore warnings when loading an illegal SGF file

• ignore_illegal_properties – whether or not to ignore illegal SGF properties

• fix_file_format – whether or not to fix the file format if it is wrong

Returns a sente.Game object populated with data from the SGF file



Sente Exceptions

various exceptions used by sente

exception sente.exceptions.FileNotFoundError

exception sente.exceptions.IllegalMoveException

exception sente.exceptions.InvalidSGFException

2.1.2 Indices and tables

• genindex

• modindex

• search


PYTHON MODULE INDEX

ssente, 17sente.exceptions, 25sente.sgf, 24

27


28 Python Module Index

INDEX

Aadvance_to_root() (sente.Game method), 20

BBoard13 (class in sente), 19Board19 (class in sente), 19Board9 (class in sente), 19

Ccomment (sente.Game property), 20

Ddump() (in module sente.sgf ), 24dumps() (in module sente.sgf ), 24

FFileNotFoundError, 25

GGame (class in sente), 20get_active_player() (sente.Game method), 20get_all_sequences() (sente.Game method), 20get_black_points() (sente.results method), 18get_board() (sente.Game method), 20get_branches() (sente.Game method), 20get_current_sequence() (sente.Game method), 20get_default_sequence() (sente.Game method), 20get_legal_moves() (sente.Game method), 20get_point() (sente.Game method), 21get_properties() (sente.Game method), 21get_results() (sente.Game method), 21get_side() (sente.Board13 method), 19get_side() (sente.Board19 method), 19get_side() (sente.Board9 method), 19get_stone() (sente.Board13 method), 19get_stone() (sente.Board19 method), 19get_stone() (sente.Board9 method), 19get_stone() (sente.Move method), 18get_white_points() (sente.results method), 18get_winner() (sente.Game method), 21get_winner() (sente.results method), 18

get_x() (sente.Move method), 18get_y() (sente.Move method), 19

IIllegalMoveException, 25InvalidSGFException, 25is_at_root() (sente.Game method), 21is_legal() (sente.Game method), 21is_over() (sente.Game method), 22

Lload() (in module sente.sgf ), 24loads() (in module sente.sgf ), 24

Mmodule

sente, 17sente.exceptions, 25sente.sgf, 24

Move (class in sente), 18

Nname (sente.rules property), 18name (sente.stone property), 18numpy() (sente.Game method), 22

Pplay() (sente.Board13 method), 19play() (sente.Board19 method), 20play() (sente.Board9 method), 19play() (sente.Game method), 22play_default_sequence() (sente.Game method), 23play_sequence() (sente.Game method), 23pss() (sente.Game method), 23

Rresign() (sente.Game method), 23results (class in sente), 18rules (class in sente), 18

Sscore() (sente.Game method), 23

29


sentemodule, 17

sente.exceptionsmodule, 25

sente.sgfmodule, 24

set_property() (sente.Game method), 23step_up() (sente.Game method), 24stone (class in sente), 17

30 Index

release 0.3

Documents