analyzeNonbond

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

Purpose

The analyzeNonbond command allows the calculation and examination of repulsive, dispersive, and electrostatic energy components of individual atoms and the total nonbond interaction energies and forces between sets of atoms.

Syntax

analyzeNonbond operation ?arg1 arg2? ...



Operation       Arguments       Description


create          setName1        Create the tables NonbondInteractionEnergy- 
                setName2        and NonbondInteractionForce- in the energy 
                ?-name          database. If tableSuffix is given for this pair 
                 tableSuffix?   of sets, it is appended to the above table 
                                names. tableSuffix is required if there are 
                                more than one pair of sets, i.e., the create 
                                command is used more than once. The two sets 
                                may be the same or different. Note that an 
                                atom can appear only once in a set.

delete          ?-name          Delete the tables NonbondInteractionEnergy- 
                 tableSuffix?   and NonbondInteractionForce- and any other 
                                related information from the energy database 
                                and the system database. tableSuffix is 
                                required only if it is used in the 
                                analyzeNonbond create command.

on                              Set the proper flags in the Energy database
                                to turn on nonbond energy analyses. After an
                                analyzeNonbond on command, nonbond energy
                                analyses are done for every energy evaluation
                                until an analyzeNonbond off command is issued.
                                Note that if the analyzeNonbond create command 
                                has not been used prior to this operation, only 
                                repulsive, dispersive, and electrostatic energy 
                                components of individual atoms are calculated.

off                             Turn off nonbond energy analyses.

-row            rowIndex        Send a row in the table 
                varName         NonbondInteractionEnergy- in the energy 
                ?-name          database to an object array varName. 
                 tableSuffix?   analyzeNonbond create and analyzeNonbond on 
                                must have been used prior to this operation. If 
                                tableSuffix is not used in the create operation, 
                                it should not be used here. The row indices 
                                range from 1 to the number of groups in set1. 
                                Additionally, for the extracted results to make 
                                sense, at least one energy evaluation must have 
                                been performed.

-column         columnIndex     Similar to the analyzeNonbond -row command, 
                varName         but sends a column in the table 
                ?-name          NonbondInteractionEnergy- in the energy 
                 tableSuffix?   database to an object array varName. The 
                                column indices range from 1 to the number of 
                                groups in set2 plus one. The last column 
                                contains the interaction energies between 
                                groups of set1 and all atoms that are not in 
                                set2.

-element        rowIndex        Similar to the analyzeNonbond -row command, 
                columnIndex     but sends an element in the table 
                varName         NonbondInteractionEnergy- in the energy 
                ?-name          database to an object array varName.
                 tableSuffix?

Description

Jump to Syntax or Examples

Background

The per-atom nonbond energy is the nonbond interaction energy between an atom and all the other atoms in the system. It is decomposed into repulsive, dispersive, and electrostatic components. The sum of the per-atom energies over all atoms gives the total nonbond energy.

The nonbond interaction energies are the energies between groups of atoms in two separate sets. For example, if there are M groups of atoms in set1 and N groups of atoms in set2, there are (M) x (N + 1) nonbond interaction energy terms. The interactions are organized as the rows (groups of set1) and columns (groups of set2) of a matrix. The extra column represents the interaction of each of the groups in set1 with a special group which is the complement of set2. That is, all the atoms not in set2 are represented in the last column of the matrix. A group in a set may be a molecule, a monomer, or an arbitrary group of atoms in the system. Note that the per-atom nonbond energies may also be obtained as a special case of the nonbond interaction energy calculation. The nonbond interaction energy calculation does not separate repulsive, dispersive, and electrostatic components, as does the per-atom nonbond energy calculation.

The nonbond interaction forces between the same groups of atoms are calculated similar to the nonbond interaction energies.

Due to the nature of the Ewald sum and cell multipole methods, nonbond interaction energies cannot be calculated. When these methods are used, the per-atom energy is calculated by using the Ewald sum or cell multipole method, and the nonbond interaction energy is calculated using the group-based method. You can specify cutoffs for the group-based method of nonbond analysis. A large cutoff in the group-based method may give reasonably accurate energies compared to the Ewald sum and the cell multipole methods.

Notes

The setName arguments following the create operation represent object arrays containing grouped rids which reference atoms in the MainCell/Atom table of the System database. Sets may be created by using the select or $dbHandle select commands.

Each create operation creates two columns of flags indicating the grouping of the selected atoms in the MainCell/Atom table of the System database. The flags are integers ranging from 0 to the number of groups. In the column corresponding to set1, 0 indicates the atoms that are not selected. In the column corresponding to set2, the largest number (i.e., the number of groups) indicates the atoms that are not in set2.

The create operation then creates the table NonbondInteractionTable in the System database. NonbondInteractionTable contains the name of the pair, the name of each set in the pair, the corresponding interaction energy and force table names, and the size of the energy and force tables. Each row in NonbondInteractionTable defines a collection of nonbond interactions. The names of the sets are used to locate the flag columns in the MainCell/Atom table of the System database.

The create operation also creates the interaction energy and force tables based on the optional tableSuffix given above. These tables generally contain rectangular matrices. The rows are labeled by the groups in the first set; columns are labeled by the groups in the second set. Additionally, the last column contains nonbond contributions from any atoms not in set2. The table entries are initialized to zero.

The on operation creates a row (if it does not already exist) in the Global table of the System database and sets the entry name to AnalyzeNonbondOn and the corresponding value to true. The off operation sets its value to false. The Discover program's energy evaluation code looks at this flag and decides whether or not to do nonbond energy analyses. The nonbond energy analyses are done at every energy evaluation after the on operation, until the off operation is encountered.

Performance is slowed when nonbond analysis is requested. It is a good idea to do nonbond analyses only when necessary, e.g., every certain number of steps of dynamics or minimization.

For your convenience, -row, -column, and -element operations are also supplied. These operations send a row or a column or an element in the nonbond interaction energy table to an object array, which can be printed out by using the object print command. Computations on the vector of energies can be performed using the vector command.

Example 1

Jump to Syntax or Description

BTCL > database handle dbSystem System.
BTCL > database handle dbEnergy Energy.
BTCL > $dbSystem select -regexp {^C ^H} Atom.Name set1
BTCL > select set2 "*:*:H*"
BTCL > analyzeNonbond create $set1 $set2
BTCL > database print $dbSystem
BTCL > database print $dbEnergy
BTCL > analyzeNonbond on
BTCL > energy 
BTCL > analyzeNonbond off
BTCL > database print $dbEnergy

In this example, two database handles are created first. Then two sets are created by using the select command. There are two groups in the first set and only one group in the second. The two groups of set1 consist of all atoms with names beginning with ``C'' and all atoms with names beginning with ``H'', respectively. Set2 contains all atoms beginning with ``H''. The analyzeNonbond command creates two columns of flags in the MainCell/Atom table of the System database as well as nonbond interaction tables in the Energy database. Since no -name flag was used, the name of the nonbond interaction energy table will be NonbondInteraction. These columns and tables are printed out by the database print command. The nonbond analysis flag is turned on and off before and after an energy calculation. The per-atom energies for the repulsive, dispersive, and electrostatic components and the total nonbond interaction energies are printed by the last database print command.

Example 2

BTCL > database handle dbSystem System.
BTCL > database handle dbEnergy Energy.
BTCL > $dbSystem select -regexp {^C ^H} Atom.Name set1
BTCL > select set2 "*:*:H*"
BTCL > select set3 "*:*:N*"
BTCL > $dbSystem select -regexp {.*} Atom.Name set4
BTCL > analyzeNonbond create $set1 $set1 -name i
BTCL > analyzeNonbond create $set1 $set2 -name j
BTCL > analyzeNonbond create $set2 $set3 -name k
BTCL > analyzeNonbond create $set3 $set4 -name l
BTCL > database print $dbSystem
BTCL > database print $dbEnergy
BTCL > analyzeNonbond on
BTCL > energy 
BTCL > analyzeNonbond off
BTCL > analyzeNonbond -row 1 firstrow -name l
BTCL > puts [vector firstrow]
BTCL > analyzeNonbond -column 1 firstcolumn -name l
BTCL > puts [vector firstcolumn]
BTCL > database print $dbEnergy

In this example, two more sets are created in addition to the two sets created in Example 1. Set3 has one group that consists of all atoms beginning with ``N''. Set4 contains all the atoms in the system, as one group. Then four interaction pairs are set up. There are four nonbond interaction energy tables in the energy database as printed out by the database print command before and after the energy evaluation. In addition, the first row and the first column in the interaction table NonbondInteraction-l are sent to object arrays called firstrow and firstcolumn and then printed out.

Example 3

BTCL > database handle dbSystem System.
BTCL > database handle dbEnergy Energy.
BTCL > set bindingList (57,99,189,190,195)
BTCL > select binding "*:$bindingList:Atom;*"
BTCL > select bulk "*:!$bindingList:Atom;*"
BTCL > analyzeNonbond create $binding $bulk
BTCL > analyzeNonbond on
BTCL > energy print energies = 1
BTCL > database print $dbEnergy

This example first creates a list of monomer numbers in the system and then creates two sets, called binding and bulk. The binding set contains atoms that belong to the monomers in the list, and the bulk set contains atoms that do not belong to the monomers in the list. The nonbond interaction energy between the binding group and the bulk group will be calculated.

Example 4

BTCL > database handle dbEnergy Energy.
BTCL > $dbEnergy get repulsive_energy Atom.Repulsive
BTCL > object repulsive_energy print

In this example, an energy database handle called dbEnergy is created first. Then the $dbEnergy get command is used to get the per-atom nonbond repulsive energy from the Atom table of the energy database into an object array called repulsive_energy. Finally, the object print command is used to print out the object array called repulsive_energy.

Main access page

Advanced-Use access.

List of BTCL commands atomCoordinates command