Tutorials‎ > ‎

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, the fundamental atom selection class is AtomSelection from the pMolecule package. An instance of AtomSelection contains a reference to the system to which the selection pertains and a set that contains the integer indices of the selected atoms.

The AtomSelection class has a number of class methods that allow particular selections to be generated. One is FromAtomAttributes which selects atoms that have a particular value for a particular attribute. The following two statements select all the hydrogens and all the aromatic atoms in a system:

hydrogens = AtomSelection.FromAtomAttributes ( system, "atomicNumber", 1 )
aromatics = AtomSelection.FromAtomAttributes ( system, "isAromatic", True )

A second class method is FromAtomPattern which selects atoms whose sequence paths conform to a specific pattern. 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" )

Instances of AtomSelection behave very like sets. Thus, they can undergo intersection, union, difference and symmetric difference operations using the binary operators "&", "|", "^" and "-", and their in-place equivalents "&=", "|=", "^=" and "-=". In addition, they respond to the unary operator "~" which creates a new selection that is the complement of the existing one (i.e. one that contains all atoms that were not in the original selection).

Other useful methods in the AtomSelection class that create new selections from existing ones are:
  • ByBondedNeighbor takes all atoms from the original selection and adds those to which they are covalently bound.
  • ByComponent 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.
  • Within selects all atoms that are within a given distance of the atoms in the original selection.
The AtomSelection class and its methods provide the basics of pDynamo's atom selection capability. As a complement to this, there is the SQLAtomSelector class which permits more 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 either to be built 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.