twixtbot-ui

twixtbot-ui is a graphical user interface on top of twixtbot. twixtbot is an engine for the game TwixT that has been developed by Jordan Lampe. It uses AlphaZero techniques, i.e. a neural network plus Monte-Carlo-Tree-Search and plays extremely strong. See its ratings at littlegolem.net. It's brilliant! Big round of applause to Jordan!

twixtbot-ui brings twixtbot to your desktop in a simple standalone python program. You can play against the bot, have it evaluate past games or have two bots play against each other using different settings.

twixtbot-ui comes with all the neccessary twixtbot files in subfolder ./backend so there is no dependency to the twixtbot repository. The twixtbot code runs as part of twixtbot-ui; no server needs to be started beforehand.

Get started

Windows Installer

For Windows 10 there is an executable installer. It will install all necessary files and create a shortcut 'twixtbot-ui' in the Start Menu. The shortcut points to a script winlaunch.py that starts twixtbot-ui. The installation requires ~1.3 GByte of free disk space.

Manual Installation

For manual installation make sure you have Python3 installed. The Python version needs to support tensorflow 2.10, e.g. Python 3.8, 3.9 and 3.10 (64bit). Consider using virtual environments to switch between multiple Python versions on your system. To check the current version, use the following commands:

python --version
python -c "import struct; print(8 * struct.calcsize('P'))"

Linux users must make sure that Tkinter is installed. The installation command for Debian based distributions is:

sudo apt-get install python3-tk

and for RPM-based distributions:

sudo yum install python3-tkinter

Clone this repository using the following command or download the repository as ZIP file and extract it.

git clone https://github.com/stevens68/twixtbot-ui

At the command line, change to the twixtbot-ui directory – or twixtbot-ui-master if you extracted a ZIP file – and install the necessary modules:

python -m pip install -r requirements.txt

Change to directory ./src and start twixtbot-ui:

cd src
python tbui.py

Ignore the tensorflow warnings (if any) and confirm the pop-up message that says that a settings file will be created. Wait a few seconds until the bots have been initialized. You should see the GUI with the TwixT board and a control bar on the right:

Play TwixT

Human move

Place pegs by clicking on the board. You are in control of player1 and player2 at any time. Pegs are linked automatically. Change the settings allow swap and allow crossing own links (File -> Settings...) to enable or disable the swap rule or crossing own links, resp. Link removal is not supported.

Bot move

There is one dedicated bot for each player. The bots can have different settings. Click Bot Move to let the bot do the next move. If you switch on auto move the bot will make its moves automatically.

Swap rule

Human players swap by clicking on the first peg. The peg will be replaced by a black peg, mirrored at the diagonal. twixtbot has its own swap policy (see ./backend/swapmodel.py). The bot will swap any first move on row 7 to 18 plus moves B6, C6, V6, W6, B19, C19, V19, W19.

Undo, Redo, Resign, Reset

Click these buttons to undo the last move, redo undone moves, resign a game or start a new game, resp. You cannot click these buttons during MCTS.

Draw

Drawn games - which are rare in TwixT - are detected automatically. A pop-up indicates that the game is over. You still can undo and redo moves. For an example of a drawn game, see drawngame.T1

Note, that draws are not detected by the bot during MCTS, i.e. the bot does not know whether it has hit a drawn position while searching the tree.

Evaluation

By default, both bots share the same neural network in folder ./model/pb. The network has been taken from twixtbot in Dec 2020. Some manual adjustments were necessary for tensorflow2 to read it. If you want to use another network that you have trained using twixtbot, have a look at the files in folder ./convert to see what needs to be adjusted before twixtbot-ui can use it. Put the network into a separate folder and configure the folder in File -> Settings....

Note that the network was trained with crossing own links allowed, which can lead to incorrect evaluations in certain cases, if allow crossing own links is set to false (default). It doesn't make a big difference though in most cases.

By default, the evaluation output of the network is displayed after each move. If you do not want to be distracted or influenced you can uncheck the evaluation checkbox. This also hides the MCTS visits bar chart.

value head

After each move, the network evaluates the board. The value head [-1.0..1.0] indicates the probability for a win of player1 and player2, resp. The value is displayed as a float number and as a vertical bar. Past values are recorded in a history bar chart.

policy head

The policy head of the network evaluates each legal move. These p-values in range [0..1] indicate how promising a move for the current player is. A bar chart on the right shows the top three moves and their p-values. Switch on the heatmap checkbox below the bar chart to visualize all p-values > 0. The bigger and greener the spots, the better the p-value. The color coding is:

• light green: close to 100% of best p
• light blue: close to 50% of best p
• dark blue: close to 0% of best p
  

Policy

By default the bots pick the best move returned by the network, i.e. the move with the highest p-value. This greedy policy can be changed to a stochastic policy by decreasing the config parameter level in the settings dialog. The lower the level, the weaker the bot, i.e the more often a weaker move is chosen.
Note that the level parameter only applies when not using MCTS.

MCTS

The network is strong enough to win against most human players. If you want the bot to play even stronger you can switch on Monte-Carlo-Tree-Search. To do so choose a number of trials > 0. The more trials, the bigger the tree, i.e. the more boards will be evaluated. twixtbot-ui starts MCTS in a separate thread. Progress info is updated every 20 trials. The top three moves with the most visits are listed.

If smart accept is switched on, the max number of trials will be reduced automatically depending on the visit difference between the leading move and the second best.

If you check the visualize checkbox, the current line with the most visits will be displayed on the board so you can get an idea in which direction the bot is "thinking". In the example below, the line is S18 (3185), R14 (230), R11 (193), etc.

In many cases MCTS will not lead to a different move than initially suggested by the network. Click Accept to accept the current best move. Click Cancel to abort; this will also set auto move to false.

Note that for the first move and the swap move the bot does not use the evaluation of the network and does not use MCTS.

Settings

All settings can be changed and saved via File -> Settings.... Most changes are effective immediately and can be applied in the middle of a game. Click button Reset to default to reset the values in all three tabs.

Parameters auto move and trials can also be changed in the control panel of the main window. These changes won't be saved when you exit the program. In the main window, to see the current settings in a tooltip, hover the mouse over the auto move checkboxes.

Tab General

• allow swap: switch on the swap rule (default: true)
• allow crossing own links: paper-and-pencil variant of TwixT (default: false),
• board size: number of pixels of a side of the board (default: 600)
• show labels: display labels for rows and columns (default: true)
• show guidelines: display lines that lead into the corners (default: false)
• show cursor label: display the coordinates in a tooltip at the mouse cursor (default: false)
• highlight last move: display a yellow circle around last peg (default: false)
• smart accept: during MCTS, reduce the max number of trials automatically according to the lead of the best move (default: true)
• resign threshold: if opponent's evaluation is bigger than this threshold the bot will resign (default: 0.95)
• log level: verbosity of log messages (default: ERROR)

Tab Player 1 / 2

• color: choose your favorite colors for the players (default: red / black)
• name: choose your favorite player names (default: Tom / Jerry)
• auto move: if true, the bot makes a move automatically (default: false)
• rotation: controls which of the four equivalent boards (rotation / mirroring) is used for evaluation (default off). The modes average, best evaluation and best p-value evaluate all four boards. The other five modes pick only one board and are faster.
  • average: uses the average evaluation and average p-values
  • best evaluation: choose board with the biggest evaluation and its p-values
  • best p-value: choose board with the biggest p-value and its evaluation
• level: this parameter controls how "greedily" the best move is picked. The lower the level, the weaker the bot. Examples:
  • 1.0 greedy: the move with the best p-value is always chosen (default)
  • 0.95 greedy: the move with the best p-value is almost always chosen
  • ...
  • 0.5 stochastic choice using the p-values, i.e. if a move has a p-value of 0.3 it will be chosen with a probability of 0.3
  • 0.0 random uniform: all legal moves have the same probability to be chosen.
• model folder: no reason to change this unless you have a second network (default: ../model/pb)
• trials: number of MCTS iterations. Set it to 0 to switch off MCTS (default: 0)
• smart root: if true, the leading move is not visited if it is more than one visit ahead. Of the remaining moves the one with the best UCB is visited instead (default: false)
• temperature: controls the policy which move is taken after MCTS:
  • 0.0: choose move with highest number of visits; random choice for tie-break (default)
  • 0.5: random choice using probability distribution of squared number of visits
  • 1.0: random choice using probability distribution of number of visits
• add noise: add dirichlet noise to P using alpha = 0.03:
  P_inew := (1 - add_noise) * P_i + add_noise * Dir(0.03)
  default: add_noise = 0, so P remains unchanged
• cpuct: MCTS constant that balances exploitation vs. exploration (default: 1.0)
  When selecting a branch down the tree, MCTS visits the node with the highest Upper Confidence Bound (UCB):
  U_i := Q_i + c_puct * P_i * sqrt(n + 1) / (n_i+1)
  where Q_i is initially 0 and updated after each visit depending on the score of the subtree:
  Q_inew := Q_i + (score_sub - Q_i) / n_i
  Decrease c_puct to move the needle towards exploitation, i.e reduce the influence of P

This site has more details on temperature, dirichlet noise and cpuct.

Loading and saving games

Choose File -> Open File... to load games stored in T1J file format (*.T1) or littlegolem.net format (*.tsgf). It will take a few seconds to re-calculate the evaluation history. After a game is loaded, the player names and the board are updated and you can continue to play as usual. See sample files in folder ./games. Note that the value of self crossing links is applied when loading a game. Choose File -> Save file... to save a game in T1J format; tsgf is not supported as a target.

T1J files

When reading a T1J file all rows except those for moves and player names are ignored. Each game is considered "unswapped" with player 1 to start. You can prepare T1J-like files in an editor: The first 13 lines need to be comments except lines 4 and 5 for the player names. Append one line per move in upper or lower case with swap and resign being valid moves. Note that these files cannot be read by T1J.

#
# 
# 
Tom # player 1
Jerry # player 2
# 
# 
# 
# 
# 
# 
# 
# 
e15
swap
f17
H18
P12
resign

Keyboard shortcuts

Menus	Buttons	Checkboxes	Sliders
File: Altf Help: Alth	Bot Move: Altb Accept: Alta Cancel: Altc Undo: Altu Redo: Altd Resign: Altg Reset: Altr	auto move 1: Alt1 auto move 2: Alt2 evaluation: Alte heatmap: Altm visualize: Altv	MCTS trials 1: Alt←, Alt→ MCTS trials 2: AltShift←, AltShift→

Contributors

• agtoever:
  Load tsgf Files, Save Files, Evaluation History, Heatmap, Init Progressbar, Highlight Last Move, Hide Evaluation, Redo, Logging