Combat

A python script to run engine vs engine game matches.

Requirements

• Python 3.7.x or later
• Python-chess 0.30.1

Guide

1. Help

combat.py -h or combat.py --help

usage: combat [-h] [--engine-config-file ENGINE_CONFIG_FILE] [--engine [ENGINE [ENGINE ...]]]
              [--opening [OPENING [OPENING ...]]] [--round ROUND] [--reverse] [--parallel PARALLEL]
              [--win-adjudication [WIN_ADJUDICATION [WIN_ADJUDICATION ...]]] [--output OUTPUT]
              [--log-filename LOG_FILENAME] [--engine-log] [--gauntlet-color GAUNTLET_COLOR] [-v]

Run engine vs engine match

optional arguments:
  -h, --help            show this help message and exit
  --engine-config-file ENGINE_CONFIG_FILE
                        This is used to define the file where
                        engine configurations are located. You may use included file combat.json
                        or you can use engines.json from cutechess.
                        example:
                        --engine-config-file combat.json
                        or using the engines.json from cutechess
                        --engine-config-file "d:/chess/cutechess/engines.json"
                        default is combat.json
  --engine [ENGINE [ENGINE ...]]
                        This option is used to define the engines
                        playing in the match. It also include tc or time control. You need to call
                        this twice. See example below.
                        format:
                        --engine config-name=E1 tc=btms1+itms1 --engine config-name=E2 tc=btms2+itms2
                        where:
                            E1 = engine name from combat.json or engine config file
                            btms1 = base time in ms for engine 1
                            itms1 = increment time in ms for engine 1
                        example:
                        --engine config-name="Deuterium v2019.2" tc=60000+100 --engine config-name="Deuterium v2019.2 mobility130" tc=60000+100
                        note:
                            * engine1 will play as black, in the example above
                              this is Deuterium v2019.2
                            * engine2 will play as white
                            * When round reverse is true the side is reversed that is
                              engine1 will play as white and engine2 will play as black
  --opening [OPENING [OPENING ...]]
                        Opening file is used by engine to start the game. You
                        may use pgn or epd or fen formats.
                        example:
                        --opening file=start.pgn random=true
                        or with file path
                        --opening file="d:/chess/opening_start.pgn" random=true
                        or with epd file
                        --opening file="d:/chess/opening.epd" random=true
                        or to not use random
                        --opening file="d:/chess/opening.epd" random=false
                        command line default value is ["file=grand_swiss_2019_6plies.pgn", "random=False"]
  --round ROUND         number of games to play, twice if reverse is true
  --reverse             A flag to reverse start side.
  --parallel PARALLEL   Option to run game matches in parallel
                        example:
                        --parallel 1
                        default is 1, but if your cpu has more than 1 cores or threads
                        lets say 8, you may use
                        --parallel 7
  --win-adjudication [WIN_ADJUDICATION [WIN_ADJUDICATION ...]]
                        Option to stop the game when one side is
                        already ahead on score. Both engines would agree that one side
                        is winning and the other side is lossing.
                        example:
                        --win-adjudication score=700 count=4
                        where:
                            score: engine score in cp
                            count: number of times the score is recorded
  --output OUTPUT       Save output games, default=output_games.pgn
  --log-filename LOG_FILENAME
                        A filename to save its logs. default=combat_log.txt
  --engine-log          A flag to save engine log to a file.
  --gauntlet-color GAUNTLET_COLOR
                        Set the color of gauntlet to either white or black. Example --gauntlet-color white
  -v, --version         show program's version number and exit

combat v1.27

2. Command line

combat.py --engine-config-file combat.json ^
--engine config-name="Deuterium v2019.2" tc=60000+100 --engine config-name="Deuterium v2019.2 mobility130" tc=60000+100 ^
--opening file="grand_swiss_2019_6plies.pgn" random=true ^
--round 8 ^
--reverse ^
--win-adjudication score=700 count=4 ^
--parallel 1

To enable engine logging and saved in engine_log.txt, use the --engine-log flag.
combat.py --engine-config-name ... --engine-log

All logs are saved in combat_log.txt, to save in a different log, use the --log-filename option.
combat.py --engine-config-name ... --log-filename mylog.txt

Also check the windows batch file run_combat.bat which can be found in this repo. You can modify and run it.

2.1 Command line in batch file with gauntlet match

The first engine is the gauntlet, the player that plays against other engines. In this case it is Deuterium v2019.2 Elo 2000

combat.py --engine-config-file combat.json ^
--engine config-name="Deuterium v2019.2 Elo 1900" tc=5000+50 ^
--engine config-name="Deuterium v2019.2 Elo 1800" tc=5000+50 ^
--engine config-name="Deuterium v2019.2 Elo 1700" tc=5000+50 ^
--opening file="grand_swiss_2019_6plies.pgn" random=true ^
--round 100 ^
--reverse ^
--win-adjudication score=700 count=4 ^
--parallel 6

Typical result table:

                      name     score     games score%   win%  draw%   tf
Deuterium v2019.2 Elo 1900      17.0        26   65.4   65.4    0.0    0
Deuterium v2019.2 Elo 1800       5.0        13   38.5   38.5    0.0    0
Deuterium v2019.2 Elo 1700       4.0        13   30.8   30.8    0.0    0

3. Using match.ini to run game matches

Sample match.ini is included in the repo.

[COMBAT]
# Engine settings file
engine config file = combat.json

# Games = rounds x 2 if reverse is true
round = 8
reverse = true

# Opening file and random
opening file = grand_swiss_2019_6plies.pgn
randomize position = true

# Adjudication
win adjudication enable = true
win adjudication score = 700
win adjudication count = 4

# Run game matches in parallel, value >= 1
parallel = 1

# Write engine logs to engine_log.txt. default = false, values can true or false
engine logging = true


[ENGINE1]
# name is from engine config file or combat.json or engines.json
name = Deuterium v2019.2

# tc or time control as base_time+inc_time, all in ms
tc = 10000+100


[ENGINE2]
name = Deuterium v2019.2 mobility130
tc = 10000+100

Then run the program with combat.py

4. How to find the config-name in combat.json file?

Open combat.json file and find a name key. Example below.

[
    {
        "command": "Deuterium_v2019.2.37.73_64bit_pop.exe",
        "workingDirectory": "./engines",
        "name": "Deuterium v2019.2",
        "protocol": "uci",
        "options": [
            {
                "name": "Hash",
                "default": 128,
                "value": 128,
                "type": "spin",
                "min": 8,
                "max": 2048
            },
        ......
        ......

That Deuterium v2019.2 will be the engine's config-name.

5. Sample run

combat v1.11
Preparing start opening from my_startpos.pgn ...
status: done, games prepared: 6, elapse: 0h:00m:00s:005ms

rounds           : 6
reverse side     : True
total games      : 12
opening file     : D:\Chess\CuteChess-CLI\pos\my_startpos.pgn
randomize fen    : True
base time(ms)    : 10000
inc time(ms)     : 10
win adjudication : True
win score cp     : 700
win score count  : 4
parallel         : 6

Starting, game: 2 / 12, round: 1.2, players: Deuterium v2019.2 mobility130 vs Deuterium v2019.2
Starting, game: 1 / 12, round: 1.1, players: Deuterium v2019.2 vs Deuterium v2019.2 mobility130
Starting, game: 3 / 12, round: 2.1, players: Deuterium v2019.2 vs Deuterium v2019.2 mobility130
Starting, game: 5 / 12, round: 3.1, players: Deuterium v2019.2 vs Deuterium v2019.2 mobility130
Starting, game: 4 / 12, round: 2.2, players: Deuterium v2019.2 mobility130 vs Deuterium v2019.2
Starting, game: 6 / 12, round: 3.2, players: Deuterium v2019.2 mobility130 vs Deuterium v2019.2
Done, game: 5, round: 3.1, elapse: 0h:00m:14s:417ms
players: Deuterium v2019.2 vs Deuterium v2019.2 mobility130
result: 0-1 (adjudication: good score for black)

name                              score     games  score%   Draw%   tf
Deuterium v2019.2 mobility130       1.0         1   100.0     0.0    0
Deuterium v2019.2                   0.0         1     0.0     0.0    0

Starting, game: 7 / 12, round: 4.1, players: Deuterium v2019.2 vs Deuterium v2019.2 mobility130
Done, game: 3, round: 2.1, elapse: 0h:00m:17s:179ms
players: Deuterium v2019.2 vs Deuterium v2019.2 mobility130
result: 0-1 (adjudication: good score for black)

name                              score     games  score%   Draw%   tf
Deuterium v2019.2 mobility130       2.0         2   100.0     0.0    0
Deuterium v2019.2                   0.0         2     0.0     0.0    0

Starting, game: 8 / 12, round: 4.2, players: Deuterium v2019.2 mobility130 vs Deuterium v2019.2
Done, game: 6, round: 3.2, elapse: 0h:00m:17s:436ms
players: Deuterium v2019.2 mobility130 vs Deuterium v2019.2
result: 0-1 (adjudication: good score for black)

name                              score     games  score%   Draw%   tf
Deuterium v2019.2 mobility130       2.0         3    66.7     0.0    0
Deuterium v2019.2                   1.0