Introduction ============ 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**! 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: ``_ 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 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: - Zhang, J.; Dolg, M. `ABCluster: The Artificial Bee Colony Algorithm for Cluster Global Optimization. `_ *Phys. Chem. Chem. Phys.* **2015**, *17*, 24173-24181. - Zhang, J.; Dolg, M. `Global Optimization of Clusters of Rigid Molecules Using the Artificial Bee Colony Algorithm. `_ *Phys. Chem. Chem. Phys.* **2016**, *18*, 3003-3010. 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! 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. 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 :guilabel:`This PC` and click :guilabel:`Properties`, :guilabel:`Advanced System Settings`, and :guilabel:`Environment Variables`. In ``System variables``, select ``PATH`` and click :guilabel:`Edit`. In the editbox, add ``;D:\ABCluster`` at the end of the texts in it, and click :guilabel:`OK` to confirm it. .. tip:: Now, you can press :kbd:`Shift` and right-click in any explorer window and click :guilabel:`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. 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: .. code-block:: bash :linenos: :caption: .bashrc export PATH=$PATH:/home/you/bin/abcluster export 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 :ref:`download-abcluster-source`. .. 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. 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``: .. code-block:: bash $ export OMP_STACKSIZE=4G Many thanks to Prof. Haohao Fu for reporting this bug. 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. 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 ``_. 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.** .. _download-abcluster-source: Compilation of ABCluster --------------------------- You can `download ABCluster source code `_ and compile it on your own system. System requirement ++++++++++++++++++++++++++ You should have the following items installed on your system: - ``gcc`` version > 8.0 - ``cmake`` version > 3.10 One-key Compilation +++++++++++++++++++++++++++++ You can use this link to download ABCluster development environment: ``_. Then: .. code-block:: bash $ 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: .. code-block:: bash $ ./build.sh clean Lean Source Code +++++++++++++++++++++++++++++ You can use this link to download **lean** ABCluster source code: ``_ 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).