restraint restraint
Jump to Description or
Examples; explanation of how
commands are documented.
Operation Description Arguments
create Create a new restraint object varName of restraint type varName restraintType. The number of arguments depends on restraintType restraintType (see Restraint Types). For restraint types other arg1 than btcl, one n-tuple subset or n atom specifications are ?arg2 ...? required as arguments. function Set the function and parameters used by restraint varName to varName calculate the restraint energy contribution. The number and function types of parameter arguments required depend on the value of param1 function (see Restraint Functions). ?param2 ...? target Set the target values used by restraint varName to calculate varName the restraint energy contribution. The number of value ?relative? arguments required is usually zero or one, depending on the ?value1 ...? restraint type (see Restraint Types). Two arguments are required if the function for restraint varName is flatBottomed, and two, four, six, or eight arguments are required if the function is j3dihedral (see also Restraint Functions). scale Set the scale factor for a particular restraint object (varName | varName, or for all restraints in the current system database -all | (if -all is specified), or for all restraints of a given type -type (if -type restraintType is specified) to value. The scale restraintType) factor of a restraint object scales the energy and derivative value contributions from that restraint and has a value 1.0 by default. The scale must be non-negative, and a value of 0 stops the energy function from being called (this is important to remember when using btcl type restraints). clear Delete all restraint objects from the current system database. To delete a particular restraint object use unset varName. get Return information about an existing restraint object varName. varName This information is returned by the command as a TCL string keyword and/or in BTCL objects arg1, arg2, etc., depending on the ?arg1 ...? value of keyword (see restraint get Keywords).
Restraint Number of Default function Target value description type arguments and parameters
chiral 1 flatBottomed^ A string object whose items value 100.0 100.0 1000.0 must be one of A (as is), I (invert), R, or S. tether 1 quadratic^ Either a coordinate vector or an 100.0 1000.0 atom spec. (Tethering to a target is called template forcing.) distance* 1 or 2 quadratic A vector of distances in 100.0 1000.0 angstroms. angle* 1 or 3 cosine A vector of angles in degrees. 100.0 1 torsion* 1 or 4 cosine A vector of angles in degrees. 100.0 1 outOfPlane* 1 or 4 cosine A vector of angles in degrees. (or oop) 100.0 1 btcl 1 or more arg1 You may not use restraint ?arg2 ...? target/function commands. These parameters are implicit to the user btcl function, arg1, which has arguments arg2, arg3, etc.
Jump to Syntax or
ExamplesThe restraint create command is used to create a new restraint object, varName. This restraint object becomes active immediately to add an extra function (a restraint) to the Discover energy calculation routine for the current (default) system database. You may define as many restraints for as many databases as you want.
A restraint object is similar to a BTCL object in that the value of $varName is a restraint object handle. Hence the restraint is deleted if variable varName is re-assigned or unset and is only recognized as a restraint object by restraint commands.
When a restraint object is first created, all the restraint qualities, such as target values, energy function, function parameters, etc., are given default values such that the restraint varName restrains the target set of atoms to their current geometries. (See Restraint Types.) For example:
BTCL > restraint create rst1 angle myang BTCL > restraint create rst2 chiral *:(3,5):CAIn this example two restraint objects, called rst1 and rst2, are created in the default system database. Restraint rst1 is an angle type restraint for the existing angle subset called myang. These angles are now restrained to their current values using a cosine function with default parameters (see Restraint Types). Restraint rst2 is a chiral restraint on the chiral (or prochiral) alpha carbon atoms of monomers 3 and 5 of the molecule(s) in the current system database. The chiralities at these atoms are now restrained to their current values (either R or S).
Once a restraint object has been created, other restraint commands may be used to change that restraint object's qualities. (See restraint Command Operations.) The most usual quality that you would want to change is the restraint target value(s) so that later minimization or dynamics runs can be used to change the geometry of a molecule. This is achieved using the restraint target command, for example:
BTCL > restraint target rst1 60 BTCL > restraint target rst2 "R S"In this example, all the angles specified by restraint rst1 (the subset myang) are to be restrained to 60 degrees, and the two chiralities specified by restraint rst2 are restrained to the R and S configurations, respectively. When the restraint target uses real numbers, the restraint target command may include the keyword relative, which indicates that the target value is to be set to the current value (the restraint measure) plus the argument value(s), for example:
BTCL > restraint target rst1 relative 10In this example, the angles specified by restraint rst1 are set to whatever their current values are plus 10 degrees. Note that this is not relative to the current target value (60 degrees). For restraints of type tether, you may set the target value to a set of coordinates defined by a vector object specification or another set of atoms. For example:
BTCL > restraint create rst3 tether "*:3:Atom;*"
BTCL > restraint target rst3 $atoms
BTCL > restraint target rst3 $atomCoords
BTCL > restraint target rst3 relative "{1 0 0}"
In this example, tethering restraint rst3 is first created for all the
atoms in monomer 3 of the molecule(s). This would tether these atoms
to their current coordinates. The restraint target is then changed to
new coordinates taken from the atoms defined by $atoms, which must
specify the same number of atoms. These atoms could originate from a
different database. (A tethering restraint which has a (nondefault)
target is often called a template forcing restraint.) The
restraint target is then changed to a set of coordinates defined by
$atomCoords, which must have the same number of coordinates as there
are atoms specified by restraint rst3. The restraint target is then
changed again to finally set the target coordinates to be +1 in the x
direction from their current values. You may also choose to change the function or function parameters used by a restraint using the restraint function command. For example:
BTCL > restraint function rst1 quadratic 100 500 BTCL > restraint function rst2 flatBottomed 5 5 100Notice in this example that, when a restraint function command is used, the function and all its parameters must be specified (see Restraint Functions). For restraint rst1, the function is changed to quadratic with a force constant value of 100 and a maximum derivative value of 500. For restraint types tether and chiral, it is illegal to use a restraint function other than the default, but the default may be re-specified in order to change the function parameters, as with restraint rst2 in this last example. It is important to note here that the restraint function command may change the target value(s) of a restraint. For example, conversion of a flatBottomed function to a quadratic function will set the quadratic target to the mean of the upper and lower flat-bottomed targets. In many cases, you may want to follow a restraint function command with a restraint target command reflecting your own target choice. For a conversion from a quadratic function to a flat-bottomed function, for example, the upper and lower targets are both set to the quadratic target value.
Although the force of a particular restraint (in, e.g., a minimization) may be changed by changing the function parameters, it is usually easier to scale the restraint function using the restraint scale command (see restraint Command Operations). This sets the scale parameter of a restraint object, which has the default value of 1. If the new scale value is 0, then the restraint specified no longer contributes to the energy calculation. In fact, the energy function is not even called, which is important to note (for performance reasons) when the restraint type is btcl. The scaling may be applied to all restraints defined in a system database by using the keyword -all where varName would usually appear. This is useful for disabling all restraints, resetting all the scaling factors back to 1, or as in the example below, where all restraints are disabled except for one:
BTCL > restraint scale -all 0 BTCL > restraint scale rst1 1You can also scale all restraints of a given type with a command like the following:
BTCL > restraint scale -type chiral 3.0Note that the scale set by a restraint scale command is absolute, not relative to the previous scaling.
To remove all the current restraints on a system, rather than disabling them, use the restraint clear command.
You may want to interrogate an existing restraint object using the restraint get command. All data associated with a restraint may be accessed through this command by specifying the appropriate keyword and supplying variable names to which this information is returned (see restraint get Keywords). For example:
BTCL > echo [restraint rst1 get type] angle BTCL > echo [restraint rst1 get function] quadratic BTCL > restraint rst1 get parameters p1 p2 BTCL > echo [object p1] [object p2] 100.0 500.0In particular, the restraint get command is useful for returning the sum and component energies of a restraint, which are calculated independently of the Discover energy command, and for returning the current values associated with a restraint, i.e., the measure. The latter operation requires the measure keyword and can be used to retrieve quantities such as torsion angles, interatomic distances, etc. and, in particular, the chirality (or prochirality) of a chiral atom, which is not currently available through other BTCL commands.
The restraint get command is restricted as to what information can be returned for a restraint object of type btcl (see restraint get Keywords). This is because this type of restraint allows you to specify your own energy function in the form of a BTCL procedure. The first argument after a restraint create btcl command must be the procedure name. However, the existence of this procedure is not checked, so that you may define, or redefine, this procedure after the restraint has been set up. The following arguments are passed to the BTCL procedure when that procedure is called as the restraint is applied, i.e., during a Discover system energy calculation. It should be noted that these arguments are fixed but could be, for example, atom specifications or variable names.
The procedure that the restraint object of type btcl calls is linked to the energy code via an energyContribution command (see Example 5). Having multiple calls to energyContribution in the procedure is not recommended, since only the first of these is scaled by the scale factor.
Restraint Arguments^ Energy expression* function
quadratic k mD E = scale * k * (V - V0)^2 cosine k sym E = scale * k/2 * (1 - cos(sym * (V - V0))) flatBottomed k1 k2 mD E(V <= V0) = scale * k * (V - V0)^2 E(V0 < V < V1) = 0.0 E(V >= V1) = scale * k * (V - V1)^2 cis k E = scale * k/2 * (1 - cos(V)) trans k E = scale * k/2 * (1 + cos(V)) cis/trans k E = scale * k/2 * (1 - cos(2*V)) j3dihedral k1 k2 mD Like flatBottomed function, except that V0 and V1 are selected from the 2, 4, 6, or 8 target values that you specify. Which pair of values to select is decided the first time that the restraint is applied, according to which flat-bottomed potential (using these values as V0 and V1) is closest to the initial value of V.
Keyword Operation
type Return the restraint type as a TCL string. function Return the restraint function as a TCL string. Not available for restraints of type btcl. parameters Requires 1, 2, or 3 extra arguments. These are variable names to BTCL objects that are created, containing the function parameters. The number of arguments depends on the restraint function. (See Restraint Functions.) Not available for restraints of type btcl. target Usually requires 1 extra argument, which is the variable for a BTCL object returned containing the restraint's target values. If the restraint function is flatBottomed or j3dihedral, this operation requires two arguments to return both sets of target values (the post-initial set for j3dihedral--see Restraint Functions). Not available for restraints of types btcl, cis, trans, or cis/trans. measure Requires 1 extra argument. A BTCL object is created with this name and containing the current values for the restraint, e.g., for a restraint object of type angle, this would return the angle values for the restraint's atom sets in their current geometry. Not available for restraints of type btcl. scale Return the scale factor of a restraint as a TCL string. database Returns the database number that a restraint is defined for, as a TCL string. subset Requires 1 extra argument. A BTCL object is created with this name and contains the subset of atoms or angles, etc., used to define the restraint. For restraints of type chiral, the initial specification of chiral atoms is augmented by lists of atoms that these are connected to. Not available for restraints of type btcl. energies Return the total energy that a restraint contributes to the energy of the system. If an extra argument is provided, a BTCL object is returned with this variable name, which contains the individual energy components for each atom, distance, etc., that the restraint is defined for. Not available for restraints of type btcl. derivatives Requires 1 extra argument. A BTCL object is created with this name and contains individual derivative components for each atom, angle, etc., for which the restraint is defined. Not available for restraints of type btcl.
Jump to Syntax or
Description
BTCL > restraint create rst1 distance *:1:CA *:2:CA BTCL > restraint function rst1 quadratic 100.0 500.0 BTCL > restraint target rst1 4.0These commands create a distance restraint named rst1 between CA atoms in monomers 1 and 2. The form of the restraint is quadratic and the restraint parameters are:
k = 100.0
mD = 500.0
V0 = 4.0
BTCL > restraint create rst2 distance *:1:CA *:2:CA BTCL > restraint function rst2 quadratic 100.0 500.0 BTCL > restraint target rst1 relative 4.0These commands create a restraint rst2 which is like restraint rst1, except that the relative keyword has been used. If each monomer has one CA atom, and they are separated by 1.5 Å when rst2 is created, then the restraint parameters are:
k = 100.0
mD = 500.0
V0 = 5.5
BTCL > restraint create rst3 angle *:1:CA *:2:CA *:2:O BTCL > restraint function rst3 quadratic 100.0 500.0 BTCL > restraint target rst3 60 BTCL > restraint create rst4 angle *:1:CA *:1:O *:2:CA BTCL > restraint function rst4 cosine 100.0 1.0 BTCL > restraint target rst4 60These commands create two angle restraints, rst3 and rst4. Restraint rst3 is quadratic, and rst4 is a cosine restraint with parameters:
k = 100.0
sym = 1.0
V0 = 60.0
BTCL > vector v "10.0 20.0" BTCL > restraint create rst5 torsion *:*:N *:*:CA *:*:C *:*:O BTCL > restraint function rst5 cis $vThis example assumes that the atom specifications in the restraint create command yield atom lists of length 2 corresponding to 2 torsions. The cis form requires only one parameter, k, and use of the vector $v in the parameter list causes the use of k = 10.0 for the first torsion and k = 20.0 for the second torsion. Note that use of a target command is not permissible with the cis form.
The same restraint could also be created with the following commands:
BTCL > subset define tor "{*:*:N} {*:*:CA} {*:*:C} {*:*:O}"
BTCL > restraint create rst5 torsion tor
BTCL > restraint function rst5 cis $v
BTCL > restraint create rst_user btcl myEner *:1:CThis command creates a user-defined restraint which is based on a user-defined BTCL procedure named myEner. The BTCL procedure might look like:
proc myEner {spec} {
subset get obj $spec
database handle system_h System. db_n
$system_h get coord Coord $obj
vector r euclidean_norm $coord
vector eterms multiply $r $r
vector esum sum $eterms
vector egrad multiply 2.0 $coord
energyContribution atom $esum $egrad $obj
}
This procedure computes energy and gradient increments directly in
BTCL and feeds them back into the Discover program with the
energyContribution
command.
Main
access page 
Advanced-Use access.
List of BTCL commands
reset command
select command
Copyright Biosym/MSI