Atom Selections

Being able to select atoms in a system that satisfy specific criteria is an important feature of any modeling and simulation program. In pDynamo, basic atom selecting employs the Selection class from the pCore package and the AtomSelection module from the pMolecule package.

Instances of the Selection class behave very like immutable Python sets, except that their members are non-negative integers that are sorted in ascending order. Like Python sets, they can undergo intersection, union, difference and symmetric difference operations using the binary operators "&", "|", "^" and "-", respectively. In addition, they respond to the unary operator "~" which creates a new selection that contains all integers that were not in the original selection. The latter assumes that the range of allowed values for the new selection is fixed by the largest index in the input selection. When this is not large enough, the upper bound can be explicitly specified by using the Complement method. For example:

new = old.Complement ( upperBound = someMaximumValue )

The AtomSelection module contains a variety of functions that allow particular types of selection to be generated for a given system. All these functions have a System instance as their first argument and return an instance of the Selection class. The functions include:

• ByBondedNeighbor ( system, inSelection, iterations = 1 ) takes all atoms from inSelection and augments it by those to which they are covalently bound. The iterations argument specifies the number of bonds away from the inSelection atoms to consider when creating the new selection.

• ByComponent ( system, inSelection ) expands the original selection by including all atoms of all components that had an atom in the original. The methods ByEntity, ByIsolate, ByLinearPolymer and ByRingSet work similarly except that they apply to entities, isolates, linear polymers and ring sets, respectively.

• FromAtomPattern ( system, atomPattern ) selects atoms whose sequence paths conform to a specific pattern. For example, the following statements select all atoms from entity A, all waters and all alpha-carbons, respectively:

entityA = AtomSelection.FromAtomPattern ( system, "A:*:*" )

waters = AtomSelection.FromAtomPattern ( system, "*:HOH.*:*" )

alphaCarbons = AtomSelection.FromAtomPattern ( system, "*:*:CA" )

• Within ( system, inSelection, distance, excludeSelf = False ) selects all atoms that are within a given distance of the atoms in inSelection. The excludeSelf argument indicates whether the indices of the original atoms are to be included in the new selection or not.

The AtomSelection functions provide the basics of pDynamo's atom selection capability. In addition to this, there is also the SQLAtomSelector class which permits further flexibility when generating selections. Briefly this works by creating an SQL database that contains all the relevant data about the atoms in a system, and then querying it using the database's own powerful query language. The current implementation of the class uses Python's sqlite3 module which allows the database to be built either in memory or to reside in a file on disk, and so available for future use.

The following example shows how to create the database and then to query it using the atom selector's Where method:

selector = SQLAtomSelector ( system )

firstRow = selector.Where ( "atomicNumber BETWEEN 3 AND 10" )

hydrogens = selector.Where ( "atomicNumber = 1" )

nearOrigin = selector.Where ( "X*X + Y*Y + Z*Z < 25.0" )

postivelyCharged = selector.Where ( "charge > 0.0" )

In addition to the Where method, instances of SQLAtomSelector have a number of default selections that are provided as attributes. Examples are:

selector.boundaryAtoms # . QC/MM boundary atoms.

selector.counterions # . Counterions.

selector.heavyAtoms # . Non-hydrogen atoms.

selector.protein # . Protein atoms.

selector.water # . Water atoms.

A full list of the available defaults, and their corresponding SQL queries, are defined in an instance's patterns attribute. Likewise, the names of the columns of data in the SQL database, and hence the keywords that may be used in Where query commands, are listed in an instance's atomsColumns attribute.