Energy Database

Jump to Descriptions of Contents or of Accessing the Database or Examples; explanation of how keywords are documented.

Introduction

A read-only energy database is created whenever a begin or reset command is encountered in a BTCL script (the .inp file). The energy database is of type Energy in the CurrentDatabase table. The purpose of the Energy database is to provide script-level access to important energy-related quantities in the program. Any quantity stored in the database can be recovered via BTCL commands and manipulated or output as you want.

Contents of the Energy Database

Two tables, Values and Atom, are always created in the energy database. Additionally, a Misc table is created to store the virial coefficients and the Hessian if either is created during the current energy computation. Additional tables named EnergyControl, NonbondInteractionTable, and NonbondInteraction-* are created if nonbond analysis is requested (see the analyzeNonbond command).

Values Table

There are four (4) columns in the Values table:

 Name   (type string)
 Parent (type rid)
 Value  (type double)
 Print  (type short)

Thus, a row specifies the name of an energy term, its immediate parent, and the numerical value of the energy term. The Value column is updated after every energy calculation. The Print column is used to control the output of rows with an energy value of 0.0 (see the examples below).

The purpose of the Parent column is to define a hierarchy of energies. For example, Bond energy is a child of Internal energy. All children of Internal energy are summed to form the total value for Internal energy. Therefore, only leaves on the tree (i.e., final ends, or rows with no children referring to them) are independent energy values. These values are extracted from the current energy calculation and recursively summed into their parents to finally provide the Total energy row.

Atom Table

The Atom table always contains four (4) columns:

 Coord        (type double)
 Gradient     (type double)
 Nonbond-A    (type double)
 Nonbond-B    (type double)

These columns contain the coordinates, gradients, and the nonbond parameters A (or r) and B (or

). The columns Repulsive, Dispersive and Electrostatic are created (all of type double) specifying the repulsive, dispersive, and electrostatic energies for each atom in the system, respectively, after the analyzeNonbond command is executed with the on keyword for an energy calculation. The per-atom energy is defined such that the sum of all per-atom energies equals the total nonbond energy of the system.

Accessing the Energy Database

Currently, the energy database is intended to be read-only. Changing values (for example an energy term) has no effect on the current calculation. Energy database values are overwritten with new values from the internal energy structures at each energy evaluation.

The energy database is deleted when the Discover program is finished running or when a reset or begin command is issued.

Example 1: Print Commands

The Values table can be obtained and printed out by simple BTCL commands. A sample output may be:

BTCL > database handle ener_h Energy.
BTCL > energy
BTCL > $ener_h print Values

"Values"
{
    Row  Name               Parent  Value    Print  
    ---  -----------------  ------  -------  -----  
     0)  Total                   .  -18.530      0
     1)  Internal                0    5.607      0
     2)  Bond                    1    2.759      0
     3)  Angle                   1    2.849      0
     4)  Torsion                 1    0.000      0
     5)  OutOfPlane              1    0.000      0
     6)  Cross                   1    0.000      1
     7)  BondBond                6    0.000      0
     8)  BondAngle               6    0.000      0
     9)  EndBondTorsion          6    0.000      0
    10)  MiddleBondTorsion       6    0.000      0
    11)  AngleTorsion            6    0.000      0
    12)  AngleAngleTorsion       6    0.000      0
    13)  BondBond-1-3            6    0.000      0
    14)  AngleAngle              6    0.000      0
    15)  Nonbond                 0  -24.137      0
    16)  Vdw                    15    3.727      0
    17)  Repulsive              16    8.964      0
    18)  Dispersive             16   -5.237      0
    19)  Electrostatic          15  -27.865      0
    20)  Hydrogenbond           15    0.000      0
    21)  Restraint               0    0.000      1
    22)  External                0    0.000      1
    23)  Diffraction            22    0.000      0
}

Other commands that request energy printout, e.g., energy print energies = 1, use the data stored in the Values table to form a hierarchy of energy values:

Energy components             kcal/mol
Total:                      -18.530128
  Internal:                   5.607232
    Bond:                     2.758628
    Angle:                    2.848604
    Torsion:                  0.000000
    OutOfPlane:               0.000000
  Nonbond:                  -24.137360
    Vdw:                      3.727446
      Repulsive:              8.964310
      Dispersive:            -5.236864
    Electrostatic:          -27.864806
    Hydrogenbond:             0.000000

Additionally, the Print column dictates how 0.0 values are collapsed:

   If the value is:    Then

   0                   Always print the term.

   1                   Look at the term and its descendants and
                       print them out if any of them are not zero.

   2                   Do not print the term; do not look at its
                       descendants.

Example 2: Accessing Data

You can access the Hessian, stored in the Misc table, and perform a diagonalization by using the BTCL script procedure Utility_CastHessianMatrix (this script is found in the file $BIOSYM/data discover/script/energyAtom.tcl) and the BTCL vector command.

BTCL > database handle ener_h Energy.
BTCL > energy print first_deriv = 1 print second_deriv = 1
BTCL > $ener_h get hess Misc.Hessian
BTCL > Utility_CastHessianMatrix hess
BTCL > vector e_values diagonalize -eigenvectors e_vectors $hess
BTCL > echo eigen-values= [vector e_values]
BTCL > echo eigen-vectors= [vector e_vectors]

Example 3: Specialized Output

In this example, the user wants to output the electrostatic energy every 10 steps of a minimization. Additionally, the output is to be placed in a separate file created by the script.

BTCL > database handle ener_h Energy.
BTCL > set fileHandle [open electrostatic.list w]
BTCL > proc getElectrostaticEnergy {ener_h} {
         $ener_h select Electrostatic Values.Name row_n
         $ener_h get e_energy .Value $row_n
         return [object e_energy]
      }
BTCL > minimize \
        execute frequency = 10 \
        command = {puts $fileHandle [getElectrostaticEnergy $ener_h]}
BTCL > close $fileHandle

Example 4: Decomposition of Internal Energy

Internal energies and derivatives can be decomposed into the more basic components of individual bonds, angles, torsions, and out-of-plane angles by setting the internalEnergyDecomposition name in the Global table. This can be activated through the BTCL command System_SetGlobal (this script is found in the file $BIOSYM/data/discover/script/systemAtom.tcl):

BTCL > System_SetGlobal internalEnergyDecomposition 1

Any subsequent energy evaluations tabulate the individual energies and derivatives in the Bond, Angle, Torsion, and Oop tables of the Energy database.

BTCL > energy
BTCL > database handle edb Energy.
BTCL > $edb print Bond

"Bond"
{
    Row  Atom1  Atom2  Energy    dE/dBnd  
    ---  -----  -----  --------  -------  
     0)      0      1   0.04539    8.046
     1)      0      2   0.00180    1.816
     2)      0      3   0.00023    0.644
     3)      1      4   0.00458    2.498
     4)      1      5   0.03620    6.403
     5)      1      8   0.00117    1.230
     6)      5      7   0.00386    3.082
     7)      5      6   0.00006   -0.297
     8)      8      9   0.00088    1.093
     9)      8     10   0.00167    1.507
    10)      8     11   0.00155    1.191
    11)     11     12   0.00070    0.875
}

The example above shows the decomposition of the bond internal energy. These energy values include the bond energy as well as the contributions from the bond crossterms. Each crossterm energy is distributed completely into the internals that make up the crossterm. For example, a bond/angle crossterm contributes half of its energy to the bond and the other half of its energy to the angle. Below is a summary of how each of the crossterms' energies are factored:

        bond-bond       1/2 bond1       1/2 bond2
        bond-angle      1/2 bond        1/2 angle
        angle-angle     1/2 angle1      1/2 angle2
        bond1-torsion*  1/2 bond        1/2 torsion
        bond2-torsion+  1/4 bond1       1/4 bond2       1/2 torsion
        angle-torsion   1/2 angle       1/2 torsion
        ang-ang-tors    1/3 angle1      1/3 angle2      1/3 torsion

        * middle-bond/torsion crossterm
        + endbond-torsion-endbond crossterm

There is a little overhead in bookkeeping for the decomposition; therefore, when the energy breakdown is no longer needed, the option should be unset with:

BTCL > System_SetGlobal internalEnergyDecomposition 0

Main access page

Advanced-Use access.

BTCL Databases access