csu-xiao-an / molecularvolume

Utilities for molecular volume calculation

Molecular volume calculations

Purpose

This software implements voxel-based volume calculations for molecular systems, via a Python interface.

The volume is defined as the region of space that is not accessible to solvent molecules; more exactly, the volume is calculated as the sum of the volumes of those voxels such that a (spherical) solvent molecule of radius r positioned at the center of the voxel does not intersect any solute atom i, which is represented as a sphere of radius s_i and position p_i. The solvent radius r, and the radius s_i and position p_i of each solute atom is specified by the user. A flood-fill algorithm (think of the paint bucket in MS Paint, except in three dimensions) is used to determine which voxels are accessible to solvent, such that void space in the interior of the solute is included as part of the volume.

Requirements:

Software requirements:

• gcc (version >=6.3)
• Python (version 2.7 or 3.6)

Required Python packages:

• Numpy
• Cython
• argparse
• distutils

Hardware requirements:

• 12+ GB ram

Installation

After cloning this git repository, navigate to the ./src directory via a command line, and run make install.

Following installation, navigate to the ./test directory, make sure that python is in your $PATH, and run python test.py. All of the tests should pass; note that a large amount of memory (8+ GB) is needed for some of the tests.

Python interace to volume calculations

Installation produces a shared object volume.so (or a similarly named .so file) that may be imported from Python as:

import volume

Multiple functions are provided by the volume object:

volume.volume_explicit_sol: Positions of solvent molecules must be explicitely provided, and the flood-fill algorithm extends from the position of every solvent molecule. Voids in the solute with clathrate solvent are thus not included in the volume, while voids not occupied by solvent are included in the volume.

-----------
Parameters
-----------
_solute_pos: shape (n,3) array of (x,y,z) coordinates of solute atoms
_solute_rad: shape (n,) array of solute atom radii
_solvent_pos: shape (m,3) array of (x,y,z) coordinates of solvent atoms
_solvent_rad: solvent molecule radius; solvent is approximated as sphere
_voxel_len: edge length of voxels

-------------
Returns
-------------
The volume that is accessible to the centers of the water molecules

volume.volume: Assumes all provided atomic coordinates correspond to solute; the flood-fill algorithm extends from the region exterior to the provided atoms. Since the mesh of voxels need not be large enough to include solvent molecules, this function will be faster than volume_explicit_sol.

-----------
Parameters
-----------
_solute_pos: shape (n,3) array of (x,y,z) coordinates of solute atoms
_solute_rad: shape (n,) array of solute atom radii
_solvent_rad: solvent molecule radius; solvent is approximated as sphere
_voxel_len: edge length of voxels

-------------
Returns
-------------
The volume that is accessible to the centers of a water molecule on the 
exterior of the protein.

Additional tools

genradiilib.py: This tool in combination with pdb2volume.py facilitates calculation of molecular volumes of proteins simulated using the Amber software package. genradiilib.py reads an Amber parameter file (.parm7) and calculates the van der Waals radii of each atom used in the simulation. This information is written to a file (radii.lib by default) that may be loaded by pdb2volume.py. Run python genradiilib.py --help for more information on specific command line arguments.

pdb2volume.py: This tool calculates the volume of a molecule(s) specified by a PDB file. The tool requires a radii.lib file, which may be generated by genradiilib.py, or by hand. The radii.lib file should be formatted as follows:

• columns 1-3: three-letter residue identifier (e.g., ALA, ARG, ...)
• columns 5-8: one to four letter atom name (see test/radii.lib for examples).
• columns 9-14: van der Waals radius (in whatever units you desire)

Run python pdb2volume.py --help for more information on specific command line arguments.