1. Introduction

1.1. What is ABCluster?

ABCluster is one of the most successful, powerful, and popular program for the global optimization of chemical cluster structures. The essential artificial bee colony algorithm of ABCluster enables the following tasks to be routine for every chemist:

  • Conformation search for molecules: find the conformation of the lowest energy for a flexible molecule (both bond rotations and ring deformations can be considered);

  • Global optimization of clusters: find the structure of the lowest energy for the aggregates of any rigid and flexible structural units;

  • Structure sampling: sample on the potential energy surface to generate structures of high diversities;

  • Structure generator: rapidly generate clusters of assigned flexibilities (some bond rotations can be frozen) and complicated topology (like bi-phase, micelle, ligated) for subsequent studies.

ABCluster can treat clusters of arbitrarily complicated components and topologies like:

  • Atomic clusters;

  • Molecular clusters;

  • Atomic clusters upon ligation;

  • Clusters supported on surfaces or nanoparticles;

  • A single flexible molecule;

  • Aggregates of many flexible and rigid molecules;

  • Biomacromolecules;

  • And more …

ABCluster can do global optimization of clusters with:

  • Internally-supported force fields: like Coulomb-Born-Mayer, Coulomb-Lennard-Jones, Morse, Coulomb-Morse-Repulsion, Z Girifalco, Gupta, Sutton-Chen, and Tersoff potentials.

  • Internally-supported computational chemical modules: like xTB and CHARMM.

  • External computational chemistry programs: like Gaussian, CP2K, VASP, Gromacs, and Lammps.

One can connect ABCluster with the program that is most suitable for your own chemical systems. ABCluster provides programming interfaces, enabling you to connect ABCluster with any program!

Besides efficient CPU implementation, part of ABCluster can also be accelerated by single or multiple GPU cards!

1.2. ABCluster Information

ABCluster was initiated by Dr. Jun Zhang since 2015 and is still actively developed. If you have any bug reports, comments, suggestions or the possibility of cooperation on ABCluster, please feel free to contact to Dr. Jun Zhang via E-mail:

mailto:zhangjun@szbl.ac.cn

The latest version of ABCluster can be obtained from:

http://www.zhjun-sci.com/abcluster.html

ABCluster has been applied to a number of chemical problems by chemists from broad fields:

http://www.zhjun-sci.com/abcluster-applications.html

1.3. ABCluster Citation

Attention

The best way to support the development of ABCluster is that in any published works using ABCluster, please include the following references:

1.4. Support ABCluster

ABCluster is a free program and I am working continuously to improve it. I would be very appreciated if you could help me. Besides citations, there are two ways:

Tip

If you have built your own molecular force field files that are absent in ABCluster distribution, I would appreciate if you could send them to me.

Tip

While I have provided a lot of interfaces to third-party programs for ABCluster, there are of course a lot of other programs for which interfaces are not available, like ADF, etc. If you have written one and think it works well, I would appreciate if you could send them to me.

I would put these files and interfaces in the next release of ABCluster upon you agreement. Your contribution will be highly acknowledged. People share and gain! Thank you!

1.5. Installation of ABCluster

ABCluster is an out-of-box program. When you download ABCluster, it is a .zip or .tar.gz file. Once you decompress it, ABCluster is ready to work so actually no installation is needed. Please note that the current version of ABCluster does not have a graphic user interface (GUI). One must use it in the command line of Windows or Linux.

Below are some tips about running ABCluster.

1.5.1. For Windows Users

You can call ABCluster with its absolute path every time, or set path variable to the directory where ABCluster resides.

Assume you put ABCluster (atom.exe, etc) in the directory D:\ABCluster, then right-click This PC and click Properties, Advanced System Settings, and Environment Variables. In System variables, select PATH and click Edit. In the editbox, add ;D:\ABCluster at the end of the texts in it, and click OK to confirm it.

Tip

Now, you can press Shift and right-click in any explorer window and click Open cmd window here to call the command line. Type atom or other ABCluster executable names to confirm that you can already call ABCluster commands.

1.5.2. For Linux Users

You can call ABCluster with its absolute path every time, or set path variable to the directory where ABCluster resides.

Assume you put ABCluster (atom, etc) in the directory /home/you/bin/abcluster, then open your .bashrc and at the end of the file, add the following statement:

.bashrc
1export PATH=$PATH:/home/you/bin/abcluster
2export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/you/bin/abcluster

then run source ~/.bashrc. Type atom or other ABCluster executable names to confirm that you can already call ABCluster commands.

Sometimes you may encounter some errors during running ABCluster on Linux. Here are some useful tips.

Tip

Error occurs: Receive signal: SIGSEGV: Segment violation (Value: 11).

The precompiled executables are not compatible with your operating systems. Please compile ABCluster on your system. The source code can be downloaded here and the compilation instructions can be found in Compilation of ABCluster.

Tip

/usr/lib64/libstdc++.so.6: version `GLIBCXX 3.4.21’ not found

Please install or activate a GCC of higher version, like GCC 8.1.0. Sometimes you can try commands like module load gcc/8.1.0 to solve this problem.

Tip

Incorrect format near …

If you prepare an input file on Windows and copy it to Linux, ABCluster may not recognize its format and report such an error. In this case, please transform the Windows file format into Linux one by dos2unix or using :set fileformat=unix in VIM.

1.5.3. For xTB Crash Bug

The current version of xTB has a bug leading to crash for calculations of large molecules (Segment fault), which may affect ABCluster. To prevent this, try to run the following command before running geom or isomer:

$ export OMP_STACKSIZE=4G

Many thanks to Prof. Haohao Fu for reporting this bug.

1.5.4. For OpenMP

ABCluster is parallelized by OpenMP. By default, it will use up all the CPU cores by default. If you want to change this behavior, please set OMP_NUM_THREADS variable to the number of CPU cores you want to use.

1.5.5. For GPU Acceleration

The GPU acceleration is currently only available for Linux version and can be run on arbitrarily number of GPU cards. You should have NVIDIA GPU cards and CUDA toolkit well configured before running GPU accelerated ABCluster.

Hardware requirement: CUDA version >= 11.0; compute capability >= 7.0.

Tip

For different compute capability, you should download different ABCluster. First, check the compute capability from https://developer.nvidia.com/cuda-gpus. For example, if you have a NVIDIA A30 Tensor Core GPU, then you can find that its compute capability is 8.0, so you should download -Linux-GPU80 version. An inconsistent version of ABCluster may raise some errors like:

Error occurs: Fail to call the CUDA kernel function. Reason: no kernel image is available for execution on the device.

Error occurs: Fail to call XX. Reason: the provided PTX was compiled with an unsupported toolchain.

1.6. Compilation of ABCluster

You can download ABCluster source code and compile it on your own system.

1.6.1. System requirement

You should have the following items installed on your system:

  • gcc version > 8.0

  • cmake version > 3.10

1.6.2. One-key Compilation

You can use this link to download ABCluster development environment: http://zhjun-sci.com/abcluster/src/abcluster-source-env.tar.gz. Then:

$ tar -xvzf abcluster-source-env.tar.gz
$ cd abcluster-source-env
$ ./build.sh

Then, you can find all ABClsuter executables in abcluster-source-env/Release.

You can optimize ABCluster by changing compilation options, e.g., using intel compiler to compile xTB and ABCluster, use MKL to replace OpenBlas.

If you want to clean the cache files before rebuilding ABCluster, you can run:

$ ./build.sh clean

1.6.3. Lean Source Code

You can use this link to download lean ABCluster source code: http://zhjun-sci.com/abcluster/src/abcluster-source.tar.gz

1.7. ABCluster Files

When you decompress ABCluster, you will find several files, including executables and some plain text files:

  • atom It carries out the global optimization of atomic clusters using internally-supported force fields.

  • abcinp It generates input files for atom.

  • rigidmol It carries out the global optimization of rigid molecular clusters with CHARMM-like force fields.

  • isomer It carries out the global optimization of atomic clusters with third-party programs.

  • geom It carries out the global optimization and conformation search of any chemical structures by itself or with third-party programs.

  • topgen It generates topology information for a molecule to be calculated with rigidmol or geom.

  • xyz2gaussian An auxiliary program for ABCluster to connect Gaussian.

  • gaussian2xyz An auxiliary program for ABCluster to connect Gaussian.

  • testfiles Files for testing ABCluster functions.

  • misc/atomic-force-field.txt Some collected force field parameters for atom.

  • misc/charmm36 Some collected CHARMM force field parameter files for rigidmol.

  • Other files in misc Scripts for ABCluster to connect with third-party programs.

Note that from ABCluster 3.0, no PDF manual is provided in the distribution package. You are recommended to refer to the online documentation, but you can also download a PDF manual (may not be as up-to-date as the online version).