This month I take a brief look at the Aquarium 2011 directory structure. A general understanding of where Aquarium files are stored is useful for performing various tasks, such as backing up important data, and transferring databases and trees from one computer to another, etc. It also helps you to find the most appropriate place to store your personal databases, analysis trees, etc. within the Aquarium directory structure.

A Separate Data Directory

When you install Aquarium 2011 you are given the option to store the program and the data in different directories. I recommend that you do so and in the following I assume that the Aquarium data is stored in a separate directory.

Typically, you would store the Aquarium 2011 binaries in C:\Program Files\Aquarium2011 (or C:\Program Files (x86)\Aquarium2011 on a 64-bit Windows system). Some users prefer to install Aquarium outside the Program Files directory, such as in D:\Aquarium2011.

As for the Aquarium data directory, the main requirement is that you have enough free disk space. Initially 4GB should be enough, but when you start analyzing and adding more databases, trees, opening books, etc. the space requirements will increase. Since Aquarium automatically stores all your analysis results, it is not unusual to see data directories of long-term Aquarium users much larger than this. Therefore, it is a good idea to install the Aquarium data on a disk with as much free space as possible.

I would normally install the data for Aquarium 2011 in D:\Aquarium2011Data, but most other directories are also fine. Just make sure that you don’t try to store it within the Program Files directory.

One advantage of a separate Aquarium data directory is that backup and restore becomes easier and you also have more flexibility when upgrading to new versions of Aquarium.

If you bought the download version of Aquarium, you should make sure that you have a backup of the setup program, serial number, and installation instructions stored in a safe place in case you need them at a later time. Note that if you reinstall Aquarium, it will not overwrite your data in the Aquarium data directory although some options may be reset to their default value.

The Aquarium Program Directory

The files that are stored in the Aquarium program directory are never updated by Aquarium after they are installed and no new files are created there. Aquarium itself is stored there along with the programs and utilities that belong to Aquarium. This includes XfccPlay (for playing correspondence chess), AquariumTreeUtils (for managing trees and EPD files), and the client for playing online chess on the ChessOK server. All the external programs can be started from the Aquarium Menu.

Since the files in the Aquarium program directory are never updated automatically, there is no need to back them up regularly. It is enough to back them up once after each Aquarium update. In case you accidentally delete some of the files, you can restore them from the backup.

The most interesting file for users is “aquarium.dir.” It is a simple text file that can be edited with an editor such as Notepad.

This file tells Aquarium where the data directory is located. Initially it points to the data directory that you selected during installation. If you have moved your Aquarium data to a different directory, you can update the line starting with “DataDir=” to point to the new directory. In some cases this can also be useful after upgrading to a new Aquarium version.

In many cases you will see the Aquarium program directory referred to as AquariumExe.

The Aquarium Data Directory

The Aquarium data directory (often referred to as AquariumData) stores configuration files, databases, trees, chess engines, scripts, log files, temporary files, etc. A typical Aquarium session will access and update many files within the Aquarium data directory. Therefore, you should never touch the files there unless you exit Aquarium first.

Since the Aquarium data directory contains important data you should make regular backups of all important files in the directory. The easiest method is to back up the whole directory. That is fine if you have plenty of disk space, but you can also be more selective and save disk space by only backing up the most important files (as described below in “Backing Up Your Data”).

You should keep in mind that Aquarium accumulates a lot of analysis data over time. This data is very valuable, as it may be the result of months of analysis time. The few minutes you take for backing up this data are well spent.

AquariumData. The AquariumData root folder contains EPD backup files of your IDeA and infinite analysis. The IDeA backup is stored in deep_analysis*.epd and infinite analysis in infinite_analysis*.epd.

If an error occurs in Aquarium, it writes an error log in the AquariumData directory. The name of this file is Aquarium.elf. When you report the error, you should attach this file to your post. After that you should delete it. A similar file is written by the XfccPlay correspondence chess module (XfccPlay.elf).

I describe the contents of some of the more important sub-directories of AquariumData below.

AquariumData\ABases. This is a place to store your game databases. It is a good idea to create a sub-directory for databases that you plan to backup regularly. I prefer to have each database in its own sub-directory. As an example, you could store a database of your correspondence games in the subdirectory ABases\MyCorrGames and a database of your tournament games in ABases\MyOTBGames. If you follow this rule, and you want to copy a database from one computer to another, you can simply copy the subdirectory containing the database. The same applies when you want to back up the database.

AquariumData\AScripts. This directory contains numerous Aquarium scripts. You can also store your own scripts there or scripts that you download from the Aquarium forum.

AquariumData\ATrees. This directory (and its sub-directories) contains all the Aquarium trees and opening books. The trees are displayed in Aquarium through tree configurations (see above) that allow you to view data from several trees at the same time. You should back up all your analysis trees frequently, since this is where most of your analysis is stored. There is no need to back up the standard Aquarium trees if you have a copy of them from the time when you purchased Aquarium.

Each tree consists of two files; one has the extension .elm and the other one .hsh. As an example, the CAP tree that contains millions of analyzed positions is stored in cap.elm and cap.hsh. Another important tree in this directory is infinite_analysis, which stores the results of your infinite analysis.

Note that the infinite_analysis tree is actually stored in four files (two .elm/.hsh pairs): infinite_analysis, which is the more important pair and infinite_analysis$1. If you want to backup or transfer the tree to another location, it is best to copy all four files.

The infinite_analysis tree is used extensively in Aquarium. The infinite analysis history displayed in the status bar comes from this tree and it is also used in many tree configurations. Therefore, you will notice immediately if there is something wrong with it. If most operations in Aquarium return an error, this tree is a likely source of the error. In that case you should rename it or delete it.

It is a good idea to compress infinite_analysis from time to time. You can see the size of the tree by hovering with the mouse pointer over the infinite analysis history field in the status bar.

When you right-click the infinite analysis history field, the menu shown in the screen-shot is displayed. Selecting “Compress trees” will compress infinite_analysis. This allows you to collect your analysis over a longer period of time before the file hits the 2GB limit.

If you want to store the infinite analysis results of each engine in a separate tree, you can also do that in Aquarium 2011 as I described in the April 2011 column. I created a new directory, ATrees\EngineIA, where I store all the engine trees. You can add these trees to your tree configurations, so you can view the evaluations of several engines at the same time.

AquariumData\ATrees\GameAnalysis is used by “Find Blunders” and “Game Analysis” during analysis.

AquariumData\ATrees\IDeA. This is the directory where I store all my IDeA trees. Others prefer to put them into ATrees, but I like to have them in their own directory where they are easier to manage and back up, etc.

AquariumData\ATrees\Backup. IDeA has a built-in backup system that keeps backups of several recent versions of your analysis tree. If you need to restore a backup, you will find them in the subdirectories of ATrees\Backup. IDeA only backs up the trees of active projects. The time stamp of the tree files in the backup directories shows their backup time.

If the latest backup versions of your tree are clearly too small to contain any analysis data (The .elm file is just a few KBs), there is no need to check them further and you must check the next directory. Before restoring a tree you should check it with TreeUtils to make sure that it isn’t damaged.

The names of the sub-directories indicate how old the backups are. Check the sub-directories one by one from newest to oldest until you find a good version of your analysis tree: ● LastVersions\0 ● LastVersions\1 ● LastVersions\2 ● Backup0_1_days ● Backup1_7_days ● Backup2_30_days

When you find a valid backup of your tree, copy the backup files (both .elm and .hsh) over the damaged tree files. You may also need to delete the corresponding “$1” files if they are damaged.

AquariumData\BoardImages is used for storing chessboard images when you right-click over the board in Aquarium and select “Save board image.”

AquariumData\BoardThemes contains the various board themes you can choose from when you right-click over the chess board and select “Theme.”

AquariumData\Config. This sub-directory of AquariumData contains all Aquarium, XfccPlay and TreeUtils settings. This whole directory should be included in your backup routine. The settings are stored in XML files that can be edited with a text editor, such as Notepad or with an XML editor. As an example, engines.xml contains settings for all chess engines that have been installed in Aquarium.

In case you run into problems when starting Aquarium it may help to delete lastsession.xml in the Config directory.

AquariumData\Config\TreeConfig. This directory contains one XML file for each tree configuration in Aquarium. Since each tree configuration is contained in a separate file, you can transfer a tree configuration between computers by copying its XML file. You may also need to copy some of the trees that are referenced in the configuration if they don’t exist on the destination computer.

AquariumData\Engines. The engines that are included with Aquarium are installed in this directory. You can install additional engines there. You would normally create a new sub-directory for each engine. Some users prefer to have the engines installed outside AquariumData.

AquariumData\html. This directory contains files that are required for the HTML export. An advanced user can modify the files and create a customized HTML export.

AquariumData\idea. This directory contains information about your IDeA projects, default values for new projects and the infinite analysis results for each project.

AquariumData\idea\Projects. There is one XML file in this directory for each of your projects. The file name is based on the project description in Aquarium. The file contains information about the root nodes in the project, the analysis queue, project statistics, project options, and the position Note Lists (Good, Interesting, Critical and Dubious). If you want to transfer an IDeA project to another computer, you need to copy the project XML file from this directory and the project tree and place them in the corresponding directories on the destination computer.

AquariumData\idea\Results. As IDeA expands the analysis tree of a project, each new position is analyzed with infinite analysis. The results are stored in an EPD file in this directory. The file name is based on the project description in Aquarium. In case the file becomes larger than 1.8GB it is renamed by adding a sequential number to its name and a new file is created. Therefore, in big analysis projects, you may see several sequentially numbered EPD files for the same project. These files are used if you want to restore the project tree. The restore operation is on the Manage menu in IDeA’s Stage Status window. Another method of restoring the tree is to use the automatically created project tree backups described above.

AquariumData\InternetClub. The data for the ChessOK Playing Zone is stored in this directory.

AquariumData\Logs. Aquarium writes various log files to this directory. The most important are the chess engine log files, which can be helpful for troubleshooting. You can turn on logging for a specific engine by switching to Engines mode, right-clicking the engine, and selecting “Log UCI Commands.” You can also switch logging on/off for all installed engines by clicking the Setup button and select/clear “Log UCI Commands” in the “Common engine options.”

AquariumData\PieceThemes contains the available piece sets. You can switch between them by right-clicking over the board and selecting “Theme.”

Upgrade Strategy

When you upgrade to a new major Aquarium version (such as Aquarium 2011) you must decide where to install both the program and the Aquarium data. Should you install over the previous version or install into new directories? I prefer the latter method.

One advantage of installing into new directories is that the old version is still intact. If something goes wrong with the upgrade, you can continue using the old version until you get the new one working. Another advantage is that you don’t pile up obsolete files from previous versions – you get a clean installation.

After installing the new version (including all data such as game databases and trees), you must copy your personal game databases, analysis trees, etc. to the new version.

Databases. If you stored your game databases in AquariumData\ABases, you need to copy them over to the corresponding directory in the new version. If you stored each database in its own directory within ABases, this should be easy as was described above. There is no need to copy the standard databases that come with Aquarium since each new version comes with updated databases. Just make sure that you download and install the new databases if you bought the download version of Aquarium.

Trees. You must copy your analysis trees from AquariumData\ATrees over to the corresponding directory in the new version. If you stored your IDeA trees in AquariumData\ATrees\IDeA, just copy the whole directory. You may also want to copy the infinite_analysis tree from the ATrees directory and the engine specific analysis trees (see above). If you have installed Jiri’s Rybka 4 book, you should also copy the whole Rybka4book directory. The same goes for other trees you have created or added after the initial installation of Aquarium. Again, there is no need to copy the standard trees, such as the CAP tree.

Tree configurations. You should copy all the files from AquariumData\Config\TreeConfig to the new version. After that you can use all the same configurations in the new version as you had in the old version (assuming that you have already copied the required trees over).

Chess engines. You can transfer AquariumData\Config\engines.xml to the new Config directory if you want to have all the same engines installed in the new version. This assumes that you are installing the new version on the same computer. The only thing that can go awry is the path to the engines, but Aquarium 2011 uses relative paths for engines within AquariumData but absolute paths for engines outside the directory (see the “path” property in engines.xml). Therefore, you must copy all engines that you have stored in AquariumData\Engines to the same directory in the new version.

Backing Up Your Data

The Aquarium data that you need to back up is basically the same data that you need to transfer when you upgrade to a new major version (see “Upgrade Strategy” above). The only difference is that you should back up the whole AquariumData\Config directory (and its sub-directories). Note that the tree configurations are stored in one of its sub-directories.

Transferring Data to a Different Computer

This is also similar to transferring data from an older version of Aquarium when a new major version comes out.

Database. If you want to transfer a single database to a new computer you must realize it consists of several files and you must copy all the files to the new destination. Here is an example showing a database called “Freestyle.”

If you store each database in its own directory, it is easy to see which files should be copied – you simply copy the whole directory. If there are several databases stored in the same directory, you must select and copy all the files that belong to the database. They all have the same name, but different file extensions.

Tree. If you want to copy a single tree to a new location you must copy two files (*.hsh and *.elm). Let’s say that you want to copy the CAP tree. Then you must copy both cap.elm and cap.hsh.

Tree configuration. If you want to copy a tree configuration to a new location, you must copy the XML file from AquariumData\Config\TreeConfig. It has the same name as the tree configuration and the file extension .xml. If you want to use the configuration in another Aquarium installation, you must also make sure that you copy all the required trees.

Removing Redundant Files

Aquarium keeps backups of many files, in particular those that result from your analysis. Some of those can be quite large and you may want to delete such files when it is clear that they are no longer useful. As always, make sure that Aquarium isn’t running when you copy, delete, or modify files in the Aquarium data directory.

AquariumData. If Aquarium is running smoothly, you can safely delete all EPD files and log files from this directory (*.epd and *.log).

AquariumData\Logs. These files are mostly useful for troubleshooting. If Aquarium is running without problems, you can delete all the files in this directory from time to time.

AquariumData\idea\Results. It is best to keep these EPD files around for projects that are still of interest, because you can use them to rebuild the project tree (though you may also have backups of the tree itself in the IDeA backup directory AquariumData\ATrees\Backup). If, however, you are sure you don’t need the EPD backup for a project, you can delete its EPD backup file(s) in this directory.

Conclusion

The purpose of this column is to give the reader an insight into the Aquarium directory structure. We have seen how an understanding of the structure can help Aquarium users when upgrading to new versions, backing up important files, transferring files between computers, and deleting data that is no longer needed.