pseudoAtom

Jump to Description or Examples; explanation of how commands are documented.

Purpose

The pseudoAtom command is used to create, access, and update pseudoatoms whose coordinates are defined by the position of atoms existing in the Discover environment.

Syntax

pseudoAtom operation arg1 ?arg2 ...?


Operation               Description
   Arguments

define                  Define new pseudoatoms in the Atom table with names
   path:name            name which are accessed at the system database
   (spec                hierarchy level path. The coordinates of a pseudoatom
    ?weight             are the centroid of the coordinates of the subset of
    (weightVec|column)? atoms specified by path and spec. When the keyword
   |coord xyzVectors)    weight is given, then the atoms may be weighted by a
   ?varName?            vector of weights weightVec or by the (scalar) values
                        in a column on the Atom table (e.g. column is Mass,
                        Charge, etc.). If the spec argument is the keyword
                        coord, then the pseudoatoms are positioned independent
                        of any real atoms at fixed coordinates specified by
                        the following vector object specification xyzVector.
                        One new pseudoatom is created for each match to path,
                        but an error occurs if spec produces an empty list for 
                        any path instance. Any subsets specified in spec are 
                        expanded to their component objects prior to any 
                        pseudoatom creation. If the varName argument is 
                        supplied, an object is returned with this name 
                        containing a list of the new pseudoatoms.

update                  Update the coordinates of all pseudoatoms in the
                        current system database from their definition subsets.

getDefinition           Get the list of atoms defining pseudoatoms specified 
  varName               by spec as an object varName. An error is produced 
  spec                  if spec specifies anything other than existing 
  ?objName?             pseudoatoms. If a variable name,objName, is 
                        specified, then this is set to weight the object 
                        used to define the pseudoatom. This is either the 
                        set of scalar weights for user-weighted pseudoatoms, 
                        a string object containing the column name for 
                        column-weighted pseudoatoms, the xyz coordinates for 
                        fixed pseudoatoms (the object returned in varName 
                        will be empty), or empty for non-weighted pseudoatoms.

Description

Jump to Syntax or Examples

Pseudoatoms are very useful in molecular modelling for, e.g., for accessing key features of molecular geometry or simplifying energy calculations. A pseudoatom may have the same properties as a real atom, and so pseudoatoms are stored in the Atom table of the Discover system database in which they are defined. The pseudoAtom command is similar to the subset command and the definition atoms (spec in the above table) are recorded as a subset. (These subsets are only available via the PseudoAtom table, which links the pseudoatoms in the Atom table to their definition subsets.)

Once a pseudoatom is created using the pseudoAtom define command, they are specified in an entirely analogous way to subsets (see the subset command). For example, *:psu specifies all the pseudoatoms with the name psu which are accessible at the monomer level of the current system database (assuming that no monomers also have this name). Similarly, *:*:* would specify all the atoms and pseudoatoms (and subsets if they exist) at the atom level of the current system database, whereas *:*:PseudoAtom;* would specify just the pseudoatoms at this level.

The pseudoAtom update command causes the coordinates of all the pseudoatoms in the current system database to be recalculated from the coordinates of the objects in their definition subsets. This command should always be performed after any operation (or series of operations) that alter the geometry of the molecule(s) in the current system database.

The pseudoAtom getDefinition command is used to retrieve all the objects (usually atoms) that define a pseudoatom. The spec argument may specify only valid pseudoatoms, and the object returned as varName will contain grouping information so that each group corresponds to each pseudoatom specified. (If an original pseudoatom definition involved subsets, these are expanded into their component objects prior to creating the pseudoatom subsets, and therefore the pseudoAtom getDefinition command returns the expanded list.)

How Pseudoatoms are Used. During a simulation (single-point energy, minimize, or dynamics), the energy due to the pseudoatom and the derivatives of the energy with respect to the pseudoatom coordinates are computed. The particular functional form used to describe the partial dependence of the energy on the pseudoatom coordinates is determined by what type of restraint(s) is imposed on the pseudoatom. The pseudoatom energy contribution appears in the Restraint portion of the energy hierarchy. Once the pseudoatom derivatives have been computed, the contributions are mapped back onto the energy derivatives with respect to real atom coordinates. The mapping depends on the type of pseudoatom, as follows:

F: fixed - no mapping (derivative is zero)
A: geometric centroid - average pseudoatom gradient values are added to each of the constiuent atoms, i.e.:
grad(constiuent atom) + grad(pseudoatom)/N
where N is the total number of constiuent atoms.
C: mass weight - weighted average of pseudoatom gradient values are added to each of the constiuent atoms. The weights, W_i, are obtained from the Pseudoatom Table column, PseudoAtom.Weight of type OA_OA, which contains the explicit weights for each pseudoatom or the name of a column in the Atom table where weights can be obtained. For each constiuent atom we have:
grad(constiuent atom_i) + W_i*grad(pseudoatom)/SUM(W_i)
where SUM(Wi) is the sum of all weighting factors.

For this release, no processing is implemented for second derivatives.

Example 1

Jump to Syntax or Description

BTCL > pseudoAtom define mol:(6,10):psu "CA,N,HN"
BTCL > pseudoAtom define top_psu "mol:(6,10):(CA,N,HN)"
BTCL > database handle dbh ; $dbh get coords Coord "top_psu, *:*:psu"
BTCL > object coords
 {24.383842 8.953845 0.135386} {17.498986 6.778482 0.076494} {31.268697 11.129208 0.194278}

This example shows two pseudoAtom define commands which define three pseudoatoms, followed by a database handle operation to retrieve their coordinates. In the first definition, two pseudoatoms were created with the path:name specifications mol:6:psu and mol:10:psu. Both pseudoatoms have the centroids of three atoms: CA, N, and HN, in the corresponding monomers, i.e., monomers 6 and 10 of the molecule called mol. In the second definition, a pseudoatom is defined with the name top_psu and is accessed at the molecule hierarchy level. Its definition uses the same atoms specified as the other two pseudoatoms but its coordinates are the centroid of all six of these atoms. Note that the coordinates for the top_psu pseudoatom is the average of the coordinates for the two psu pseudoatoms.

Example 2

BTCL > pseudoAtom define top_psu2 "*:*:psu"
BTCL > subset define Subset top_sub "mol:6:(CA,N,HN)"
BTCL > pseudoAtom define top_psu3 top_sub
BTCL > $dbh get coords Coord "top_psu2,top_psu3"
BTCL > object coords
 {24.383842 8.953845 0.135386} {17.498986 6.778482 0.076494}

This example continues from the previous one and shows the definition of two more pseudoatoms, top_psu2 and top_psu3, which are both accessed at the molecule hierarchy level. The first pseudoAtom define command shows top_psu2 being defined from the two psu pseudoatoms. The second shows top_psu3 being defined from a subset that actually contains the same atoms used to define the mol:6:psu pseudoatom. Naturally, the coordinates for top_psu2 and top_psu3 are the same as those for top_psu and mol:6:psu, respectively.

Example 3

BTCL > pseudoAtom getDefinition psu_bases "mol:6:psu, top_psu3, top_psu, top_psu2"
BTCL > $dbh get options grouping psu_base_names Name $psu_bases
BTCL > object psu_base_names get groups
 {CA N HN} {CA N HN} {CA CA N N HN HN} {psu psu}

This example shows the use of the pseudoAtom getDefinition command. It is used here to obtain a list of the atoms which defined the pseudoatoms mol:6:psu, top_psu3, top_psu, and top_psu2. The following database handle operation is used to get the atom names from the corresponding atom objects in psu_bases. Note the use of the grouping option on the get operation to preserve the grouping information from object variable psu_bases to object variable psu_base_names. From the results of the object command, it is seen that, although top_psu3 was defined from a subset (top_sub), this subset was expanded to its component atoms so that the definition atoms are the same as for mol:6:psu. However, although top_psu2 was defined from the two psu pseudoatoms, which were themselves defined from the same atoms that defined top_psu, these were not expanded. This is because, once a pseudoatom has been defined, it is treated almost like an ordinary atom and not a subset.

Example 4

BTCL > molGeom set distance relative 0.5 "mol:6:CA" "mol:6:N"
BTCL > pseudoAtom update
BTCL > $dbh get new_coords Coord "*:*:psu"
BTCL > object new_coords
{17.266647 6.540354 0.055878} {31.268697 11.129208 0.194278}

This example shows the use of the pseudoAtom update command. The molGeom command is first used to increase the bond distance between atoms CA and N of monomer 6 of molecule mol. The pseudoAtom update command is then used to update the coordinates of all the pseudoatoms in the default system database. These are then displayed for the psu pseudoatoms. It is seen that the coordinates for mol:6:psu have changed slightly from their original values (see Example 1) as a result of two of the definition atoms having moved after the molGeom command. (The coordinates for mol:10:psu are unchanged, as expected.)

Example 5

BTCL > pseudoAtom define gly_1_com "*:GLY_3:Atom;*" weight Mass

This example shows the definition of a pseudoatom using mass-weighted atom coordinates; specifically, a pseudoatom on the third GLY residue of a molecule.

Example 6

BTCL > pseudoAtom define gly_2_usr "*:GLY_3:Atom;*" weight {1 1 1 3 1 1 1}

This example shows the definition of a pseudoatom using user-weighted atom coordinates; specifically, a pseudoatom on the third GLY residue of a molecule for which the fourth atom coordinate (of seven atoms) is given 3 times as much weighting.

Example 7

BTCL > pseudoAtom define gly_3_fix coord {{1 1.5 -0.3}}

This example shows the definition of a fixed pseudoatom. Here, no atom specification is needed, and one pseudoatom is created at the fixed coordinates (1.0 1.5 -0.3) (relative to the current system).

Note that if the path specifies more than one context for the pseudoatom to be defined in (e.g., *:*:FIX), then the last argument must specify as many coordinate vectors as there are valid contexts. For example:

BTCL > pseudoAtom define "*:GLY_*:fixed" coord {{0 0 0} {1 1 1} {2 2 2} {3 3 3}}

creates pseudoatoms at the monomer level with the name, fixed, for each GLY-type residue (assuming that there are exactly four such residues).

Main access page

Advanced-Use access.

List of BTCL commands print command rattle command