Myracle Chess Engine Tournament Manager by Martin Sedlák
Public Version Documentation (v1.0)

NOTE: This documentation is a work in progress. It may contain errors and/or important omissions, and any of it may change in future versions.

===========================

The first time you launch Myracle, you should go to "Tools -> Settings" and set the GUI up to suit your needs. These are all global settings that will be applied by default to every tournament, and will be saved when you exit Myracle. As you set up Myracle, note that some controls have "status tips" that will display additional information at the bottom of the main window when you hover your mouse over a control.

Here are the top-level options in the Settings dialog:
Adjudication - If you want Myracle to automatically adjudicate games (as opposed to letting them finish by rule), then check one or more of the boxes.
For "Draw adjudication", "Move number" is the minimum number of moves (by both engines) before adjudication, "Move count" is the minimum number of moves where the score by both engines is within the Threshold (positive or negative). For example, the default Threshold is 10cp, which will trigger if both engines have scores within the range of [-10cp, 10cp].
For "Resign adjudication", "Move count" is the minimum number of moves where the score by the winning engines is greater than the Threshold. If you check "Both must agree", then both engines need to have scores above the Threshold (from the winning engine's perspective).
For "Tablebase adjudication", select the maximum number of men on the board before Syzygy tablebases are checked for a result. (The path to the Syzygy tablebase data is set in the "Paths" option in Settings).
For "Move count adjudication", the settings are similar to those in "Resign adjudication".

Analysis - Pick an engine from your list of installed engines to use as an analysis engine. Engines are installed in the "Engines" option in Settings (see below). You can start the analysis engine at any time from the main menu, but the tournament scheduler may prevent the analysis engine from starting due to concurrency constraints (see below).

Appearance - Choose various settings to suit your visual tastes.

Book - Select a path to an opening book file (either PGN or Polyglot BIN format) for all engines to use in a tournament. Note the buttons at the bottom of this dialog numbered zero through nine. You can have up to ten "default" books, and you can select any one of them (or none) when setting up a tournament.

Concurrency - When Myracle is run for the first time, it sets game concurrency defaults depending on your computer's hardware, but you can change any of them. Note that it is likely dangerous to increase any of the defaults selected by Myracle, but it is fine to decrease any of them. "Core budget" will be the number of engine cores that are run simultaneously, assuming one CPU per engine. For example, if Core budget is set to 16, and you start a tournament with engines using four CPUs each, and ponder is off, then Myracle will play four simultaneous games. If ponder is on, then the number of simultaneous games will be divided by two. "Memory budget" is set to 75% of your computer's total RAM. Note that very large hash table sizes (which are set on a per-engine basis) can cause the tournament scheduler to reduce the number of concurrent games based on the Memory budget. "IO core budget" is only used when the GUI is opening several large PGN files simultaneously, and it defaults to 4.

Engines - If you have used Cutechess or Banksia, then you do not need to enter all of their installed engines again into Myracle one-by-one. Instead, use the "Import" top-level menu item to import engines from either (or both!) of those programs. Myracle will automatically locate the engines file from either of those programs. Just select it and press "OK" to import the engines.
To add a single engine into Myracle, press the "+" button. On the "Basic" tab, select the engine's binary file via the "..." button on the right of the "Command" field. If the engine successfully loads and identifies itself, then Myracle will auto-detect the communication protocol (uci or xboard), the engine's name, and various supported options. Note that auto-detecting an xboard engine can take ten or more seconds in some cases. After importing, go to the "Options" tab to configure any parameters you wish. The "Debug" tab mimics a commandline console, where you can test if the engine loads properly and responds correctly to various commands that you type into.

General - A catch-all tab for various options related to display and sound.

Paths - "Engine default path" should be set to the top level folder where all of your engines are stored. This will save time when manually importing engines. "Syzygy path" is used if you have "Tablebase adjudication" enabled.

Rendering - For those who are excited about anti-aliasing in their chess tournament manager.

Sprt - The default values used for an sprt test. There are ten customizable sets of values, just like on the "Book" dialog.

Time Control - Set up time control values for use in a tournament. Again, there are ten customizable sets of values which can be individually named.

Tournament - Currently just settings regarding the tournament crosstable display, and if you want the crosstable to be saved to disk.

===========================

Now that you've setting everything up and imported your engines, it's time to run your first tournament. Go to "Tournament -> New Tournament" in the menu. "Event" and "Site" are PGN tags that will be filled in for each game. "File" is the name of the PGN file created for the tournament. If you leave "File" blank, Myracle will create a default filename using the date and time that the tournament started. All files related to a tournament (PGN, crosstable, etc.) will be saved in the "tournaments" folder under the main Myracle runtime folder.
Next, select a tournament type. "Round Robin" plays all engines against each other an equal number of cycles (a "cycle" is when an engine pair plays each other twice, alternating colors), "Gauntlet" plays the top engine in the list against all other engines once for each cycle, and "Sprt" is used to test two engines against each other and uses the sprt settings to determine which engine is stronger.

Then, select various other settings, such as time control, book, and adjudication (remember, you can choose any of the up to ten sets that you've defined!). Finally modify the checkboxes at the bottom as needed (note the status tips).

Next, select the engines that will participate in the tournament. Double-clicking an engine will add it to the tournament, and double-clicking an engine in the tournament will remove it.

Once you have selected your engines, if this is a list of engines that you will regularly add to a tournament, press the "Save Engines" button to create a file that can be loaded later to save time setting up your tournament. The "Load Engines" button merely appends the engines in the saved file to the tournament; it will not overwrite engines that you have already added.

Press the "OK" button to start the tournament. Normally, each game will have its own tab that you can navigate to. These tabs will automatically close when the game is over. If you don't want to watch any games, use the "Quiet mode" option, either when setting up the tournament, or after the tournament has started. Additionally, the tournament itself will have its own tab, showing the results in a crosstable and the complete list of games in the tournament. This tab will remain open as long as the tournament is active. To navigate through the tabs of a tournament, use the mousewheel on the top tab bar. Note that tabs will appear/disappear as games are ended/started. The "oldest" game will always be the left-most tab.

Above the crosstable are some important controls. First is the "Pause" checkbox, which will "soft pause" the tournament by waiting for all current games to complete, and then not start any more games until the tournament is unpaused by unchecking the same checkbox. Next is the "Hard stop" button, which will stop all games immediately, but leave the tournament active. Finally, the "Abort" button stops all games and shuts down the tournament.

Below the crosstable is the tournament schedule. Here you can select the "Filter" dropdown list to show all games in the tournament, only the active games, or only games that have caused an "Anomaly" (see below). Additionally, if you highlight a finished game and press the "Replay game" button, the game will be replayed, with the previous game and result being removed from the tournament. Finally, if the tournament is paused (either soft or hard-paused), you can edit the engines in a tournament by pressing the "Edit Tournament" button.

Since tournaments are saved with each completed game, it is possible to load an unfinished tournament and continue it. Simply use "File -> Open", change the filter to ".tour", and navigate to the "tournaments" subfolder to load the tournament. Or drag/drop the tournament file onto Myracle. Note that tournaments loaded this way will automatically be paused, and you will need to unpause the tournament to continue it.

Anomalies
When an anomalous event occurs when playing a tournament (e.g. an engine times out, plays an illegal move or disconnects), the last 4k lines of communication between the engine and Myracle are automatically saved in .anomaly.txt log in the tournaments subfolder, along with timestamps of the GUI-to-engine communication, as well as the game's pgn up to that point, to help engine authors find and fix bugs easily. Anomalies are shown as red in the game list. Additionally, you can press the '~' key to open the Debug console, which will summarize all anomalies in the tournament so far.

Viewing games in a PGN file
Myracle can also be used to view games in a PGN file. Simply use "File -> Open" to open the PGN file that you wish to view, or drag/drop the file onto Myracle.

The "View" menu also contains various visual settings.

If you like Myracle and want to send a monetary thank you to the author via Paypal, select the "Help -> Donate" menu item. It would be very much appreciated.
