energy

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

Purpose

The energy command performs a single energy evaluation. It can be used to return the value of the current energy to the BTCL script. It also calculates first and second derivatives by finite difference, which is used internally by Biosym/MSI for validation. This feature can also be used by users who add their own energy and derivative calculations.

Syntax


Path/Keyword          Values    Default        Meaning


print

  en*ergies          Boolean    false     Print to the output file the total 
                                          energy and all of its components.

  first_d*erivative  Boolean    false     Print to the output file the first 
                                          derivatives of the energy with 
                                          respect to the coordinates (and cell 
                                          parameters  if it is periodic). The 
                                          calculation uses fractional 
                                          coordinates for periodic systems.   

  second_d*erivative Boolean    false     Print to the output file the second 
                                          derivatives of the energy with 
                                          respect to the coordinates (and cell 
                                          parameters if it is periodic). The 
                                          calculation uses fractional 
                                          coordinates for periodic systems.

  hessian            Boolean    false     Print out a Hessian file (default is 
                                          $PROJECT.hessian). This file contains 
                                          a list of all the atoms in the 
                                          molecule together with their 
                                          elements, followed by a Hessian 
                                          (second derivative) matrix. This 
                                          Hessian may, for instance, be used as 
                                          input to a minimization using DMol.


finite_difference

  first_d*erivative  Boolean    false     Print to the output file the first 
                                          derivatives of the energy with 
                                          respect to the coordinates (and cell 
                                          parameters if it is periodic) 
                                          calculated by two-sided finite 
                                          differencing. In addition to the 
                                          derivatives, this command prints the 
                                          rms difference from the analytic 
                                          derivatives.

  second_d*erivative Boolean    false     Print to the output file the second 
                                          derivatives of the energy with 
                                          respect to the coordinates (and cell 
                                          parameters if it is periodic) 
                                          calculated by two-sided finite 
                                          differencing. In addition to the 
                                          second derivatives, this command 
                                          prints the rms difference from the 
                                          analytic second derivatives.

  value              double     2.5e-6    Step size for finite difference.


filename             string     ""        Used to override the default name of 
                                          the Hessian file ($PROJECT.hessian).

Description

Jump to Syntax or Examples

The energy command is used to perform a single energy evaluation. The return value from the command is the value of the energy. This can be used in BTCL scripts as in Example 1. The finite-difference capabilities of this command are used internally at Biosym/MSI to test new energy codes. They may also be used by users who add their own energy terms.

Example 1

Jump to Syntax or Description

   ...

   for {$phi = -180} {$phi <= 180} {incr phi 20} {
        molGeom set torsion $phi $tors

        set energyValue [energy]

        puts $file "$tors       $energyValue"
   }

This example is in the middle of a script that performs a systematic conformational search on a torsion, $tors. There is some initial setup that defines the torsion (see the subset define command) and opens the output file, $file. Then at each iteration, the torsion is rotated to $phi degrees and the energy is determined and stored in the variable energyValue. The torsion angle and energy are then printed to the file $file.

To control the precision of the energy value, the TCL variable tcl_precision may be used. For instance:

set tcl_precision 8

ensures that the energy is returned with 8 significant figures.

Example 2

   energy print +energies +hessian filename = ".hess"

This example calculates the energy, prints the energy total and components to the output file, and writes a Hessian file with the name $PROJECT.hess.

Main access page

Advanced-Use access.

List of BTCL commands dynamics command energyContribution command