Aquarium really shines when it comes to managing chess playing engines. It is designed in such a way that related features are grouped together and you will never have to search through all its buttons and menus to find what you are looking for. Engine mode is an example of this. You switch to Engine mode by clicking the Engines button in the sidebar.

Switch to Engine mode

The following screen-shot shows the working area of Engine mode with the three most commonly used windows.

The Engine mode working area

• The Engine List window is organized like a spreadsheet, where each line contains one chess engine and some of its parameters in the columns. Here you can modify the engine name, its hash size, whether or not it uses tablebases, etc.
• The Engine Personality window lists all available engine options, except for those which are displayed in the Engine List window. Its left column shows the name of the option and the right column contains its value.
• The Advanced Engine Options window allows you to save the engine analysis to a specific tree /position database and it also has options affecting the engine interaction with IDeA projects.

You can arrange these three windows as you like and there is also a fourth window, as you can see if you open the Layout Menu by clicking the small black triangle at the bottom of the sidebar.

The Layout Menu

The menu displays a list of all available windows in Engine mode and I have highlighted the window missing from the display above: “Engine statistics.” If one of the windows is hidden, you can restore it by selecting it from this menu. I will describe each of these windows in greater detail below.

The Ribbon contains buttons and menus that are relevant for managing chess engines.

The Engine mode Ribbon

Note that the Ribbon only displays buttons that are needed for managing chess engines. All other features of Aquarium are hidden from view.

Add installs a new engine in Aquarium.

Folder Add installs all engines stored in the specified folder (and its sub-folders). Aquarium can automatically determine if the engine is a Winboard or a UCI engine. When using this option, make sure that there are no programs besides chess engines in the folders because Aquarium needs to run every executable file it finds.

Remove removes the selected engine(s) from Aquarium.

Setup defines the default parameters to be used when installing new engines. This includes the Nalimov tablebase path, the default opening book, the default engine folder, hash size, etc. Setting the correct parameters here can save you a lot of time when installing engines.

Import allows you to import engine definitions that you previously saved with Export.

Export allows you to export selected engine definitions to an XML file (see Import).

Verify Selected verifies that the selected engines are working correctly.

Remove All Invalid removes all engines that did not install correctly.

Start Play starts a match or a tournament between the highlighted engines.

Load. This button loads the selected engines into memory. Its main use is for engines that use a large collection of six-piece endgame tablebases. It can take a long time (and plenty of memory) to load the full set of three- to six-piece Nalimov tablebases.

The buttons are split into two groups: “Engine operations” on the left and “Selection” on the right.

The Engine operations group

Here you see the “Engine operations” group. Before you start adding chess engines to Aquarium you should click the Setup button, which brings up the Engine Defaults dialog box.

The Engine Defaults dialog box

The Engine Defaults is split into three panes, each of which serves a different purpose. “Common engine options” specifies options that apply to all installed engines, new and old.

NalimovPath is the location of your Nalimov endgame tablebases. If you have an engine configured to use tablebases, it will automatically acquire their location from this field. In Aquarium 2011 you can extend the Nalimov path to include sub-directories. Let’s say that you have stored your Nalimov endgame tablebases in three sub-directories within D:\chess\tbs and you want the chess engines to use the tablebases in all of them. You have two options. You can either list each of the three directories with semicolons between them in the NalimovPath field, or you can append a “*” to a tablebase path. In the example shown in the image above, the NalimovPath is specified as D:\chess\tbs\*, which means that Aquarium will automatically include the three sub-directories below D:\chess\tbs.

NalimovCache sets the amount of memory (in megabytes) used to cache endgame tablebases. Any engine that uses Nalimov tablebases will use this value, unless you override it by specifying a different value in the engine parameters.

Log UCI Commands. If this option is selected, the UCI commands that go between Aquarium and all installed chess engines will be logged. A cleared check box shows that no UCI commands will be logged for any installed chess engine. You can also log the UCI commands for specific engines, in which case the check box indicates the mixed state of the engines. Make sure that the Log UCI Commands check box is cleared unless you need the engine logs for debugging purposes.

The “Engine adding options” panel contains options that are applied only when a new engine is installed in Aquarium. In other words, changes to these options have no effect on engines that are already installed when the changes are made.

Options that are applied to new engines

Opening book is the default opening book, which is assigned when a new engine is installed.

Engine Folder points to the folder where the most recently installed chess engine was located.

Hash Size specifies the default size of hash tables (in megabytes) when installing new chess engines. A hash table is used by a chess engine to keep track of positions its already analyzed along with their evaluation. A chess engine may run into the same board position several times while it is calculating its next move. In such cases the chess engine can look up the previously calculated value in the hash table, which is faster than recalculating.

One of the most common questions of chess engine users is how big the hash table should be. The simple answer is “as large as possible.” But, as can be expected, it is a bit more complicated than that.

Make sure that the hashtable isn’t so big that the computer starts “thrashing” (constantly shuffling blocks of data between internal memory (RAM) and disks), as then performance drops dramatically. This is the most important rule. An indicator of thrashing would be increased disk activity and a drop in nodes per second.

If you set the hashtable size to more than half the size of the RAM, then be very careful that the computer doesn’t start thrashing. Some prefer to set the hashtable size to ¼ (or less) of the RAM size.

Be extra careful if you plan to play engine matches. Then the hashtables for both engines need to fit into the RAM at the same time. In that case it would clearly be a mistake to set the hashtable size to half the size of the RAM, as thrashing would be inevitable.

Similarly, if you run infinite analysis with several engines at the same time (e.g., by using Analysis Presets), you must make sure that the total hash size of all running engines doesn’t exceed the recommendations above.

Note that some engines don’t allow you to specify hash size in increments of one megabyte. This applies to Rybka, for instance, which rounds the hashtable size down to the next power of two, so use 32MB, 64MB, 128MB, 256MB, 512MB, etc. Specifying a hashtable size of, say, 700MB will result in actual size of 512MB.

Don’t expect much increase in playing strength for very large hashtables. In general, the shorter the time-control for a game, the less you will gain from a large hashtable. For playing very short games, such as bullet games (one minute per side), use no more than 256MB for hashtables.

Engine type detection parameters

The final two parameters in the Engine Defaults dialog box, the “Type detection options,” are used when a new chess engine is being installed in Aquarium.

Timeout (s) is the important parameter here and determines how long Aquarium will wait for a response from the engine before giving up. Sensitivity (ms) affects how responsive Aquarium is while attempting to start the engine.

I still haven’t run into a chess engine that requires changes to these parameters.

After setting the “Engine Defaults” to your liking you will hardly ever need to change these parameters again.

Adding New Engines to Aquarium

If you want to add a new engine to Aquarium, click the Add button highlighted in the screen-shot below.

Adding a chess engine to Aquarium

Type is the type of the chess engine that you are going to add to Aquarium. If you select “autodetect,” as in the example above, Aquarium will determine if the chess engine is a UCI (Universal Chess Interface) or a WinBoard engine. All the strongest chess engines are UCI engines and Aquarium has full support for the UCI protocol. This means that there are hundreds of free and commercial chess engines that can be used in Aquarium. Aquarium also supports other protocols, such as Auto 232 (explained in Version 3.1) and Remote UCI, which was explained in Networked Computers with Aquarium 2010.

Engine path is the location of the engine that you are going to install. Click the button on the right-hand side of the field to locate and select the engine that you want to install.

Name is the name that the engine will be given in Aquarium. If you are adding a UCI engine and select “Get name for UCI engines from ‘id name’ option,” the internal name of the engine will be used. This is the name that the engine author has assigned to it. If you want to edit the name, simply remove the check mark from this option. You can also change the name after you have added the engine.

If you want to add several chess engines from the same folder (and its sub-folders), you must click the Add button highlighted below.

Add all engines in a folder

First you will be asked to select the folder containing the engines and then the “Add Engines Folder” dialog box will be displayed. Make sure that the folder you choose doesn’t contain any programs other than chess engines.

Add Engines Folder

Here you see a list of all the chess engines found in the folder and its sub-folders. The first column (File) contains a check box and the name of the file (including the relative path). When the list is displayed first, all the engines are selected. The second column (Name) shows the name of the engine. It is equivalent to the “Name” field described above when adding a single engine. Also, note the familiar check box “Get name for UCI engines from ‘id name’ option,” which is displayed below the list. The third column (Type) is also equivalent to the field by the same name described above. Its default value is “auto,” meaning that Aquarium itself will determine of what type each engine is. Since I know that these are all UCI engines, I have changed it by selecting “UCI” from the drop-down list on the right-hand side of the dialog box and then clicking the Change button (highlighted). There are three other buttons that affect the selection of engines: “Select All” marks all engines for inclusion; “Select None” clears all the check boxes in the File column; and “Invert Selection” toggles the status of each check box.

After you have decided which engines in the list you want to add, click OK and Aquarium will check each engine and add it to its engine list.

The engine list

The following columns are displayed in this view:

Status. The green icon in the leftmost column shows that the engine installed successfully. If the icon is red, it means that there is some problem with the installation. In that case click the icon and Aquarium will try to fix the problem. If the problem persists, click the Remove All Invalid button in the Ribbon.

Type. This column shows the engine type. Usually, there is no need to change the engine type, but if you double-click the cell, you can choose any of the supported engine types from a list.

Engine corresponds to the Name column when you installed the engine. Currently the list is sorted by engine name as the small triangle in the column header shows. You can sort the list by a different column by clicking its header. You can modify the engine name by double-clicking the cell.

Priority is the engine priority and it is set to Low by default. This priority level was chosen with analysis in mind as it keeps Aquarium more responsive when the engines are running. If you use Aquarium mainly for engine matches and tournaments, it is better to set the priority of the engines to Normal by double clicking this column and choosing the higher priority from the drop-down list. This will give better results at shorter time controls where a low priority engine is much more likely to lose on time.

Hash (MB). This is the hash size in megabytes. It was discussed above, but here you can change the value you at any time after you install the engine. If you want to edit the current value, double-click the cell to open the field for editing.

Rating shows the current rating of the chess engine. You can assign a rating to an engine by double-clicking the cell. The rating can also be automatically updated based on the results of engine matches and tournaments that you play in Aquarium.

NoTB indicates if the engine is allowed to use tablebases or not. If this check box is selected, the engine will not use tablebases. Note that some engines can’t use tablebases at all in which case this check box has no effect.

Timout (sec). Aquarium uses the timeout specified here (in seconds) to determine how long it should wait until it gets a response from the engine. I have never had to change this from the default value of twenty seconds.

Book is the default external opening book used by the engine when playing. When setting up a new match or a tournament, you can choose a different book without changing the value specified here. For an explanation see Aquarium Engine Matches and Tournaments, Part One and Aquarium Engine Matches and Tournaments, Part Two.

Engine Path shows the path to the engine; i.e., where it is stored on your hard drive.

After you have added a new engine and set the options in the Engine List window, you can modify other engine parameters in the Engine Personality window.

The engine options

When you select an engine in the Engine List window, the options for that engine are displayed in the Engine Personality window. You must read the engine documentation to know what the different options mean, the values they can take, and so on.

The first column displays the name of the engine option and the second column shows its current value. You can change the value of an option by clicking the cell you want to change. In some cases a limited set of values is available through a drop-down list as in the case of NalimovUsage in the example above. The up/down arrows can be used to increase/decrease numeric values, although it is usually more convenient to type the new value into the cell.

Some options are found in many engines under the same or a similar name. NalimovCache and NalimovPath are two of them. In Aquarium, you normally don’t change these options for individual engines. If you leave them at their default values (0 for NalimovCache and ‘*NalimovPath’ for NalimovPath), they will be replaced with the values you entered in the Engine Defaults described above. This means that if you ever move the tablebases to a new location or add a new directory with tablebases, you only have to indicate the changes in the Engine Defaults instead of modifying each engine to point to the new location.

Aquarium users can easily share engine settings. Let’s say that one of your friends has found ultra-aggressive settings for an engine and you want to try them out. He can send you an XML-file with the relevant parameter settings, which you can load into Aquarium.

Here is how:

Exporting selected engine options

Your friend would select the engine in the Engine List window and then highlight the relevant engine options in the Engine Personality window. Right-click one of the highlighted options and select Export from the menu. A standard Save As dialog box will be displayed, where you can choose a name and save the exported settings to an XML file.

You can use all the usual methods to select options. Click an option to select it, hold down the Shift key and click another one to select a range of options or use Ctrl+click to select multiple options from anywhere in the list. Finally, you can press Ctrl+A to select all available options.

After you receive such a file, select the corresponding engine in the Engine List window, right-click in the Engine Personality window and choose Import from the menu.

This feature is very convenient when users want to exchange parameter settings. You can, for instance, upload your favorite settings to a forum, where other users can download and install them without having to type in the values. It can also be useful when you run multiple engine matches (perhaps on different computers) and want to make sure that the engine settings are the same in all matches.

The final step of adding a new engine to Aquarium is to configure the Advanced Engine Options.

Advanced Engine Options window

This is an optional step, but strongly recommended, especially if you use Aquarium’s IDeA analysis method or if you want to keep track of the infinite analysis results of different engines. Detailed information about these options can be found in Aquarium 2011, Part One.

Verifying Engines

Sometimes you may want to verify that an engine is working correctly. The most common case is that of Remote UCI engines, which are not tested automatically when they are added to Aquarium. The purpose is to allow you to add remote engines even if they are not available at that moment.

Here is an example:

Verifying a remote chess engine

The blue icon in the Status column shows that the engine hasn’t been verified. This is a remote engine as can be seen in the Type column. After the engine has been started on the remote server, select it in the engine list and click Verify Selected in the Ribbon. If the verification is successful, the icon in the Status column will turn green.

Adding Two Instances of the Same Engine

If you want to add two instances of the same engine in Aquarium, just go ahead and install it the second time. There is no need to make a copy of the exe-file. In other words, two installed engines can point to the same executable file. This is a time-saver if you want to create different personalities or test different settings for the same engine.

Some engine authors don’t provide a single core version of their engine. That’s a shame because a single-core version is important for various analysis tasks, such as IDeA and Analysis Presets. This problem is easily overcome by installing a second instance of the engine and configuring it so that it only uses one core for analysis. You should also modify its name to indicate that it only uses one core.

Two installed instances of the same engine

Here you see an example, where two instances of Critter have been added to Aquarium. I have appended “1CPU” to the name to indicate that the second instance will only use one core. I have also set the hash size of the single core version to a lower value. One of the reasons is that I often use Analysis Presets to run several single core engines at the same time.

Removing Engines from AquariumRemoving Engines from Aquarium

If you want to remove an engine from Aquarium, simply select it in the Engine List window and click the Remove button.

Remove one or more installed engines

You can use the same method if you want to remove several engines in one operation. Start by selecting the engines you want to remove by using the Ctrl-click or Shift-click methods described above. When you have selected the engines click the Remove button.

It may happen that Aquarium is unable to add an engine and verify that it is working correctly. Such engines are marked with a red icon in the status bar.

Remove invalid engines

You can remove all such engines by clicking Remove All Invalid in the Ribbon.

Import/Export Engine Definitions

Besides exporting specific engine options, you can also export the full engine configuration from Aquarium. As an example, you can export all your engine configurations to a single XML file for backup purposes. Later on you can restore the backup if needed.

Import/Export a complete engine setup

As usual, start by selecting the engines you want to export in the Engine List window. You can select a single engine or any number of engines by using the Ctrl-click and Shift-click methods described above. Ctrl+A selects all installed engines. When you have selected the engines, click Export and select the location and name of the output file.

If you have already exported one or more engines, you can import them again with the Import button. Note that the files created by this method are less suitable for sharing than the files containing specific engine options (see description above). One of the reasons is that they contain the path to the engines and it is likely that different users are storing their engines in different locations. Therefore, the engines would not be found when another user tries to import a file that you have exported.

Log Function and Engine Statistics

If the “Engine statistics” window isn’t visible, you can open it by using the Layout Menu, as explained above. This window shows various events related to engine analysis, as well as a log of the communication between Aquarium and chess engines for which logging is enabled.

Engine log

On the left hand side of the window, you see a list of active and recently used engines. If you click on an engine, you will see the UCI tab, where you can monitor the command and information exchanges between Aquarium and the selected engine.

This information is mostly useful for debugging purposes, so if you ever run into a problem with a chess engine, you might want to take a look here. If you don’t have the technical knowledge to understand what this information means, you have another option. Right-click the engine in the Engine List window and select Log UCI Commands from the menu. After this, a complete log of Aquarium’s interaction with the engine will be written to a text file with the same name as the engine. You will find the file in the Logs subdirectory of the AquariumData directory. When you have collected enough data you can, for instance, post the file on the Aquarium support forum and describe the issue that you are having. There are many people on the forum who are experts at reading such logs and they will be able to help you.

Dadi Jonsson