The RigidCLL library


The RigidCLL Documentation

Introduction

This package is a C++ implemenation of the RigidCLL algorithm described in

In short, this library implements an efficient way to identify the set of non-bonded interacting atoms (i.e., not-connected atoms closer than a given cutoff distance) when the atoms are organized in rigid clusters. The algorithm takes advantage of the presence of rigid groups of atoms to avoid considering the interaction between atoms in the same cluster (i.e., atoms whose relative distance never changes). This results in a significant speed up, as shown in the paper. Please, check the paper for further details.

Note that this is not the implementation we used to obtain the results reported in the paper. The original implementation was embedded in the PSF-AMC library. The current implemention is a standalone library and here the focus is on clarity more than on efficiency.

Note that the RigidCLL can have many variants. The version implemented here closely follows the description in the paper but for two features:

  • It allows to defined a fixed (i.e., estatic) rigid cluster. This cluster will never move and, thus, once inserted in the grid it will never be removed.
  • We introduce the possibility of activating/deactivating the collision between particular rigids. Note that this information might be used to reduce the number of Insert/Query operations, but this is not implemented yet.

The current implementation is based on defining a large grid (implemented as a fixed-size 3D array) covering the area where the rigids groups of atoms can reasonably move. If any rigid group leave this area, an exception will be triggered. It is possible to define a variant of the algorithm where the grid is not represented as an array with fixed size, but with a hash table. In this case the working area where can be dynamically adapted.

The library is agnostic with respect to the semantic of the interacting elements (they can be balls, isolated particles, actual atoms in a protein,...). It is the responsability of the user to process the detected interactions as necessary: i.e., in some domains interactions between particular elements in different rigid clusters might not make sense. This semantic escapes the scope of this library. Moreover, as mentioned in the paper, the order of at which the rigids are defined matters: it is convinient to define the largest rigid cluster in the first place (or the even as the 'fixed' cluster, if possible), and to define the second larger cluster in the last place. Up to now the library does not take care of this re-ordering: the user has to define the rigid groups in the correct order, if desired.

License

The library has been developed by the KRD group at IRI and is licensed under GPLv3 License.

Download

You can download the sources from here.

Compilation

Unpack the package and move to the build folder

  • tar xzf RigidCLL.tar.gz
  • cd RigidCLL/build

Generate the makefiles

  • cmake -DCMAKE_BUILD_TYPE=Release ..

Compile the package

  • make

At this point the library is available localy in lib folder and a minimalistic testRigidCLL program is available in the bin folder. This testRigidCLL program can be used as:

In the first case we use the default cutoff (2) and in the second we select 1 as a cutoff value. The program reads the input files, randomly move the rigids, and checks for steric clashes, and for interactions in the given cutoff threshold, comparing the output of the RigidCLL approach with a standar CLL algorihtm and a (rigid-based) brute-force approch. Moreover, the program compares the execution time of the RigidCLL and the standard CLL approaches. The execution can take some time since the experiments are repeated many times to get significant average values.

To install the library into the system folders execute

  • make install

The default installation folder is /usr/local. This can be changed by setting the environment variable CMAKE_INSTALL_PREFIX.

The documentation for the library can be generated executing

  • make doc

in the build directory. The documentation can be browsed from the file doc/html/index.html.