Alpha_complex_of_molecular_model

Authors: F. Cazals and T. Dreyfus

Introduction

A molecular structure has two components:

the molecular systems provide a hierarchy of groups of the particles of the molecular structure,

the geometric model provides geometric features for each particle of the molecular structure, such as a shape and coordinates.

When particles are represented by 3D balls, a natural way to model the shape of a molecule is the 3D weighted $\alpha$ -complex : it is a simplicial complex whose topology is exactly the one of the union of the particles.

This package provides wrappers for using the CGAL 3D $\alpha$ -complex data structures over a collection of particles.

(Advanced) The $\alpha$ -complex requires initial atomic radii for the input atoms. The choice of radii may impact the status of simplices, namely exterior, singular, regular, or interior. The case of 0-simplices i.e. vertices is of special interest. Indeed, depending on the atomic radii used, vertices corresponding to hydrogen atoms may be hidden or exterior. The first case corresponds to a hydrogen atom which does not have a Voronoi cell in the power diagram. The second one corresponds to a hydrogen atom which has a cell, yet, such that the restriction of this ball is empty. Such cases are rarely found and should trigger a careful inspection of the atomic coordinates.

Implementation

This package was designed with a two-fold aim:

being as most as possible generic: the $\alpha$ -complex of particles data structure can be highly customized; in particular, the CGAL library defines two different data structures for representing the $\alpha$ -complex: both can be used for representing the $\alpha$ -complex of particles;

being as most as possible simple: except the representation of a particle, all template parameters have a default type.

In the following, we introduce the main classes, then the different functionality of the package Alpha_complex_of_molecular_model .

Main Classes

The main class is SBL::CSB::T_Alpha_complex_of_molecular_model< ParticleTraits, TAlphaComplexVertexBase , TAlphaComplexCellBase , TAlphaComplexBase > . It inherits from the template parameter TAlphaComplexBase and adds the functionality for inserting a particle whose type is provided by the concept ParticleTraits. The four template parameters are:

ParticleTraits : concept that defines the type of the particle (Particle_type), the geometric primitives to use (Geometric_kernel) and the geometric representation of the particle (Get_geometric_representation).

TAlphaComplexBase : base representation of the $\alpha$ -complex templated by its underlying triangulation and a tag checking if critical values of $\alpha$ are exactly compared during the algorithm computing the $\alpha$ -complex. Two models exist: (i) the CGAL class CGAL::Alpha_shape_3, or (ii) the SBL class SBL::CSB::T_Alpha_complex_base_3 that directly inherits from the CGAL class CGAL::Fixed_alpha_shape_3. While (i) allows to dynamically change the $\alpha$ -value, (ii) is faster. The default type is (ii).

TAlphaComplexVertexBase : base representation of a vertex in the underlying triangulation of the $\alpha$ -complex. It is templated itself such that tow models can be used: (i) the CGAL class CGAL::Alpha_shape_vertex_base_3 or (ii) the SBL class SBL::CSB::T_Alpha_complex_vertex_base_3 that directly inherits from the CGAL class CGAL::Fixed_alpha_shape_vertex_base_3. The default type is (ii).

TAlphaComplexCellBase : base representation of a cell in the underlying triangulation of the $\alpha$ -complex. It is templated itself such that tow models can be used: (i) the CGAL class CGAL::Alpha_shape_cell_base_3 or (ii) the SBL class SBL::CSB::T_Alpha_complex_cell_base_3 that directly inherits from the CGAL class CGAL::Fixed_alpha_shape_cell_base_3. The default type is (ii).

The type of the underlying triangulation is the class SBL::CSB::T_Triangulation_of_molecular_model< ParticleTraits, TAlphaComplexVertexBase , TAlphaComplexCellBase >, whose template parameters were already described.

Finally, types such as geometric and combinatorial primitives, and the base data structure of the 3D triangulation are automatically instantiated from the traits class SBL::CSB::T_Alpha_complex_of_molecular_model_traits< ParticleTraits, TAlphaComplexVertexBase , TAlphaComplexCellBase >, where the template parameters are the same as the class SBL::CSB::T_Triangulation_of_molecular_model.

Three examples are given for illustrating the different possibilities of use of the class SBL::CSB::T_Alpha_complex_of_molecular_model :

the simplest case is shown in section A Simple Example .

a case using the CGAL class CGAL::Alpha_shape_3 is shown in section Varying Alpha .

a case with a custom particle type is shown in section Running Union-Find over the Vertices .

Serialization

Vertices of the CGAL $\alpha$ -complex data structures are partially serialized from the package Alpha_complexes_extensions. In addition, the base class SBL::CSB::T_Particle_vertex_base, used for representing vertices in the $\alpha$ -complex with an attached particle, is serialized. In order to use the serialization of the vertices, one just has to include the file "SBL/IO/Alpha_complex_of_molecular_model_serialize.hpp" in its own source file.

Molecular Viewers

Vertices, edges and faces of the $\alpha$ -complex of particles are drawable by including the file "SBL/IO/Alpha_complex_of_molecular_model_molecular_draw.hpp", as explained in the package Molecular_viewers. An example of use is shown on in section Drawing the Simplices

Module

This package provides also the module SBL::CSB:T_Alpha_complex_of_molecular_model_module< ModuleTraits > that computes the $\alpha$ -complex of an input container of particles and computes statistics on the topology of the output $\alpha$ -complex. The parameter ModuleTraits just has to define the input container type (Particles_container) and the output $\alpha$ -complex type (Alpha_complex). An example of use is shown on in section Using the Module

This module requires that particles has a radius, that generally can be modified via options of the program. For example, default radii of atoms as defined in the package ParticleAnnotator are increased by $1.4 \AA$ to define the Solvent Accessible Model of the input molecule. This value can be modified with the option -r <value>. Note that this option differs from the option –alpha <value> of this module, which adds a fixed weight (homogeneous to a squared radius) to all balls during the computation of the $\alpha$ -complex.

Examples

A Simple Example

In this example, atoms of a molecule are loaded from a PDB file, then annotated with default radii, and finally inserted in a $\alpha$ -complex data structure. The number of finite simplices is printed at the end of calculations.

Varying Alpha

This example presents the CGAL class CGAL::Alpha_shape_3 with the SBL class SBL::CSB:T_Alpha_complex_of_molecular_model for varying the parameter $\alpha$ after constructing the $\alpha$ -complex. This example is very similar to the example of section A Simple Example, except for three steps:

the template parameters of SBL::CSB::T_Alpha_complex_of_molecular_model now involve the classes CGAL::Alpha_shape_vertex_base_3, CGAL::Alpha_shape_cell_base_3 and CGAL::Alpha_shape_3.

the CGAL class CGAL::Alpha_shape_3 has a default mode called REGULARIZED such that singular simplices in the $\alpha$ -complex are skipped: this mode is set to GENERAL in our case.

if the user gives an $\alpha$ value, the $\alpha$ value of the $\alpha$ -complex is changed and statistics are computed again.

Running Union-Find over the Vertices

This example shows how to compute the $\alpha$ -complex of a container of custom particle types. In particular, it adds a Union-Find structure to the particles and compute the number of connected component in the $\alpha$ -complex.

Drawing the Simplices

This example shows how to draw the simplices of an $\alpha$ -complex in a visualization state file for VMD. In particular, it uses the molecular viewer SBL::IO::VMD_viewer and does the following steps:

cloning an existing PDB file in VMD for selecting the atoms of this PDB file,

setting the representation of atoms to van der Waals, that is a 3D ball with van der Waals radius,

setting the color of atoms and simplices to blue,

drawing the atoms,

drawing the edges and faces of the $\alpha$ -complex.

Using the Module

This example presents the module SBL::Modules::T_Alpha_complex_of_molecular_model_module with the particle type SBL::Models::T_Atom_with_hierarchical_info_and_annotations_traits.

First, the Module_traits class has to define the type Alpha_complex and the type Particles_container. In order to avoid any duplication of particles, the type Particles_container is defined as a wrapper of the class Molecular_system::Molecular_model that contains all the loaded atoms. Then, the $\alpha$ -complex module is parametrized by the Module_traits class.

Second, the particles are loaded and annotated, and the module is created and initialized with the input atoms.

Third, the module is run and statistics are printed.

Applications

This package also offers the following application(s):

sbl-alpha-complex-of-molecular-model.exe: a program computing the alpha complex of a molecular model from a PDB file, and dumping information on vertices (atom id and their status in the alpha-complex) and edges (pairs of atom ids) found in the alpha-complex for the given alpha.

Table of Contents