CHARMM c42b2 shapes.doc

            
                               Shape Descriptors

A CHARMM section to deal with shapes and charge distributions
for small molecules.

                 By Bernard R. Brooks and Yuhong Zhang - NIH
Overview

A shape descriptor facility has been developed with several goals in mind;

      - Best fit two or more molecules based on shape. 
      - Docking small molecules into an active site.
      - Optimize the conformation of a molecule to achieve
          a particular shape.
      - Optimize the conformation of two molecules so that
          they give the same shape.
      - Generate descriptors of a molecule for QSAR applications.
      - To provide a simple graphic representation of a molecule.

It also provides the capability for:
      - Rigid body minimizations
      - Rigid body dynamics
      - Rigid and flexible docking
      - Structural analysis of miscellaneous properties
                 (e.g. hydrophobic moments)
      - Searching a trajectory for frames with a given property/shape
      - High volume screening when coupled with a structural database

This is achieved by representing a molecule's shape and charge distribution
(and other properties) as series of a polynomic expansion in cartesian space.

A new data structure, Shape Descriptors, has been created.  The following
commands and command features have been added to CHARMM to manipulate
and utilize this data structure;

Syntax:
--------------------------------------------------------------------------------
Commands defining the shape descriptor tables:

SHAPe { CLEAr  [PROPerties]                } - clear the descriptor data
      { ORDER integer                      } - specify the expansion order
      {                                    }
      { PROP integer  name  property-spec  } - add or modify a property
      {                                    }
      { DESC name* { [STATic] } [atom-sel] } - Add or modify a descriptor
      {            { FLEXible }   [COMP]   }
      {            { RIGId    }            }
      {                                    }
      { DELEte name*                       } - delete one descriptor table
      { WEIGht  weight-spec                } - specify weighting table values

###   { GRID    grid-spec                  } - specify a grid for searching
                                               volume

--------------------------------------------------------------------------------
I/O commands for shape descriptors

SHAPe { PRINt {name}  [ ORDEr integer]     } - print the selected descriptor(s)
      {       {ALL }                       }
###   { STAT  {name}  [ PROP int ]         } - print statistics about a shape
###   {       {ALL }                       }
      { LIST                               } - list all active descriptors
      {                                    }
      { WRITe  [UNIT integer]              } - write the descriptor data
      { READ [UNIT int] [APPEnd]           } - read a saved descriptor dataset

###   { DISPlay name PROPerty int [UNIT integer] [TOLErance real] }
###                                        - Display descriptors as shaped blob

--------------------------------------------------------------------------------
Manipulation commands for shape descriptors

SHAPe { ROTAte  name* vector-spec PHI real } - rotate a descriptor
      { TRANslate name* vector-spec        } - translate a descriptor
      { CENTer name1 [PROPerty num] [name2]} - Center a shape at origin
      {                    [NONChiral]     }           (or at another shape)
      {                                    }
      { COMPare  name1 name2  [PROP int]   } - print the fit of two descriptors
      {                                    }
      { AXIS name  [ NORM  ]  [PROP int]   } - define an axis
      {            [ MAJOr ]               }    (see corman.doc: AXIS and LSQP)
      {            [ MINOr ]               }

--------------------------------------------------------------------------------
Manipulation commands for shape descriptors

SHAPe { COPY      name name   [PROP int]   } - copy from second to first
      { SUM       name name   [PROP int]   } - add two shape factors together
      { DIFF      name name   [PROP int]   } - subtract two shape factors
      { SCALe     name real   [PROP int]   } - scale a single shape factor
      { DUPLIcate name name                } - make another copy of an existing
                                               shape
--------------------------------------------------------------------------------
Commands to setup a shape restraint

SHAPe { RESTraint { CLEAR                        } } -Clear all shape restraints
      {           { ADD name1 name2 [FORCE real] } } -Add a shape restraint
      {           { MODIfy name1 name2 FORCE real} } -Change a force constant

--------------------------------------------------------------------------------

###   { PARTition  .... } - Cut a shape into two subshapes based on a planar cut

--------------------------------------------------------------------------------

name* ::= { a descriptor name } - process one descriptor
          { ALL               } - process all descriptors

property-spec::=  { array } [EXPOnent integer] { POINt   }  { [RAW]      }
                  { ZERO  }                    { HOMOgen }  { NORMalized }
                  { ONE   }                    { GAUSsian}  { CENTered   } 
                                               { GRID    } 
                                               { NONE    } 

array::= {any CHARMM array name from the atom-selection "PROP" list}


vector-spec::= { [XDIR real] [YDIR real] [ZDIR real]   } [DISTance real]
               {   [XCEN real] [YCEN real] [ZCEN real] }   [FACTor real]
               {                                       }
               {  AXIS                                 }

weight-spec::= [PRINt] repeat( ELEMent element-spec [ORDEr int] [SCALe] real )
         element-spec::=  iiii  
               i ::= { *     }
                     { digit }   (element-spec examples:  020*  ***1  1102 )
                           (indicies given as: x,y,z,prop)

--------------------------------------------------------------------------------
### means: not yet finished...




================================================================================
================================================================================


                             THE SHAPE SUBCOMMANDS

--------------------------------------------------------------------------------
SHAPe  CLEAr  [PROPerties] 

      This command clears the descriptor data by removing all shapes.  It also
removes all allocated heap data.  It will not "forget" the shape property
definitions unless the "PROPerties" keyword is specified.   

--------------------------------------------------------------------------------
SHAPe  ORDER integer

      This command specifies the order of the polynomial expansion for each
property.  This is not a value that should be changed while manipulating
shapes.  It is not possible (at present) to mix shapes with different
orders.  WARNING: When the order is changes ALL existing shapes are deleted.
The minimum order value is 2 and the maximimum is MAXORD (currently 10).
The cost for manipulating shapes is worse than factorial in the order.

--------------------------------------------------------------------------------
SHAPe  PROPerty int name { array } [EXPOnent int] { POINt   }  { [RAW]      }
                         { ZERO  }                { HOMOgen }  { NORMalized }
                         { ONE   }                { GAUSsian}  { CENTered   } 
                                                  { GRID    } 
                                                  { NONE    } 

      This command will add or modify a single property.  The integer indicates
which property number to use (must be specified in sequence) or modify.
This number corresponds to the column number when printing shapes.
The maximum number of properties is MAXPRP (currently 10).

      The array name identifies the data source and this may be any CHARMM array
name from the atom-selection "PROP" list.  This list currently contains:
      X        Y        Z        WMAIn    XCOMp    YCOMp    ZCOMp    WCOMp   
      DX       DY       DZ       ECONt    EPCOnt   MASS     CHARge   CONStrai
      XREF     YREF     ZREF     FBETa    MOVE     TYPE     IGNOre   ASPValue
      VDWSurfa ALPHa    EFFEct   RADIus   RSCAle   FDIM     FDCOns   FDEQ
      SCA1     SCA2     SCA3     SCA4     SCA5     SCA6     SCA7     SCA8
      SCA9     ZERO     ONE
The exponent (default 1) determines what power to raise the values in the
selected data array.

      For each property, there are two subtypes.  The first subtype determines
how atoms are treated.  The second subtype indicates how data is processed.
The allowed the first subtypes include:
       { POINt      } - Atoms are treated as point sources.
       { HOMOgen    } - Atoms are treated as homogeneous spheres
       { GAUSsian   } - Atoms are treated as a 3-d normalized gaussian
       { GRID       } - Atoms are used to compute grid points (see COOR SEARch)
                        and the grid points are used to determine shape values
       { NONE       } - This is an error condition (treated as 'POINt')
For all options other than "POINt", the atomic "radii" are stored in SCA9
(scalar array number 9) which may be filled by the command:
                        "SCALar array-name STORe 9"

The allowed second subtypes include:
       { [RAW]      } - Data is not further processed in any way (the default)
       { NORMalized } - All descriptor elements are scaled by the reciprocal
                        of the total property value for all selected atoms.
                        This is used to get "center of mass" or "center of
                        geometry" information instead of "total mass" data.
       { CENTered   } - All descriptor elements of order 2 or higher are
                        expanded about the values of the first order moments.
                        With this option, the higher order moments are invariant
                        to net translation of the shape (or associated atoms).

................................................................................

Elements of the "RAW" subtype are given by:

 element        = sum      { X**j * Y**k * Z**l *value    **  exponent      }
    j,k,l,iprop     atom-i    i      i      i       iprop,i         iprop 

................................................................................

Elements of the "NORMalized" subtype are given by:

 norm           = sum      {value    **  exponent      }
      iprop         atom-i     iprop,i         iprop 

                    when(j+k+l >0)
 element        = sum      { X**j * Y**k * Z**l *value    **  exponent   }/norm
    j,k,l,iprop     atom-i    i      i      i       iprop,i         iprop 

                    when(j+k+l =0)
                = norm

................................................................................

Elements of the "CENTered" subtype are given by:

                    when(j+k+l <2)
 element        = sum      { X**j * Y**k * Z**l *value    **  exponent      }
    j,k,l,iprop     atom-i    i      i      i       iprop,i         iprop 

                    when(j+k+l >1)
                = sum    { (X-XC)**j * (Y-YC)**k * (Z-ZC)**l *value**exponent }
                    atom-i   i           i            i           iprop,i  iprop
                  
where:       XC = sum      { X   *value    **  exponent      }
                    atom-i    i       iprop,i         iprop       

             YC =    "       Y        "
             XC =    "       Z        "

--------------------------------------------------------------------------------
SHAPe DESCriptor { name } { [STATic] } [atom-selection] [COMP]
                 { ALL  } { FLEXible }    
                          { RIGId    }           
                                        
The DESCriptor subcommand will add one descriptor, or modify existing
descriptors.  Descriptors are referred to by name (properties by number).
The maximum number of shapes is given by MAXSHP (currently 20).
There are three type of descriptors which determine how and when the descriptor
data is used:

 { STATic  } - Only recompute when done explicitly.
 { FLEXible} - Always recompute based on current positions and data.
 { RIGId   } - Do not recompute, but force atoms to move as a rigid body.

The default type is "STATic". This type of descriptor is computed once for each
"SHAPe DESC" command and is never recomputed from atomic data, but can be
modified (e.g. SHAPE ROTAte) or otherwise manipulated (e.g. SHAPe ADD)

The "FLEXible" type is recomputed whenever its associated atoms move.  This is
useful for forcing a set of atoms to adopt a particular shape.  This can also be
used in searching through a trajectory file for a frame that best represents
a particular shape.  For this subtype, it is useful to think of the shape as
an active propery of the atoms positions.  Also note: If any of the associated
data array are modified (e.g. the CHARge array and one or more property is
assigned to the charge, then the shape decscriptor will also change).

The "RIGId" subtype forces the atoms to behave as a rigid body.  Whenever the
shape rotates or translates, its associates atoms will undergo the same
operation.  This option changes the number of degrees of freedom for
minimization and dynamics.  Each RIGId shape adds 6 degrees of freedom and
removes 3N (where N is the number of associated atoms).  This option should
only be used when 3 or more atoms are used to define a shape.

Atom selection restrictions:
   WARNING: An atom may belong to one non-STATic shape (type FLEXible or RIGId)!
   If an atom already assigned to a shape is reassigend to a new
   shape, the former shape becomes inactive (i.e. type "NONE") and is disabled.

--------------------------------------------------------------------------------
SHAPe  DELEte { name }
              { ALL  }

The "DELEte" subcommand will delete one (or ALL) of the existing shapes.  This
is different from the "SHAPe CLEAr" command in that the weighting array is
not modified.
Note: It is not possible to delete a shape property, but one can be disabled by:
using "SHAPe PROPerty integer name  ZERO NONE"

--------------------------------------------------------------------------------
SHAPe  WEIGht  [PRINt]  repeat( ELEMent element-spec [ORDEr int] [SCALe] real )
         element-spec::=  iiii     (indicies given as: x,y,z,prop)
               i ::= { *     }
                     { digit }   
  (element-spec examples:  020*  ***1  1102 )

The "WEIGht" subcommand is used in setting up the weighting table values.
The weighting tables are used for comparing shapes and also used as element
prefactors in the shapew restraint energy.  The default value for this
array is zero for all elements.

Some examples of element-spec:
       020*  - Modify or set all Y**2 elements for all properties.
       ***3  - Modify or set all weighting elements for the 3rd property.
       1102  - Modify or set the X*Y element for the second propery.

An example of this command:
     shape weight elem **** 0.0   ! make sure it is all zero
     shape weight elem **** order 1 1.0 -
                  elem **** order 2 0.5 -
                  elem **** order 3 0.2 -
                  elem **** order 4 0.01
     shape weight elem **** scale 0.001
     shape weight elem ***1 scale 10.0  print

--------------------------------------------------------------------------------
SHAPe GRID ...
###  This command has not yet been fully developed...

--------------------------------------------------------------------------------
SHAPe  PRINt {name}  [ORDEr integer] 
             {ALL }                  

The "PRINt" subcommand will print one or ALL of the existing descriptors.
By default, all elements will be listed.  If the "ORDEr" value is specified,
only elements with a sum of exponents less than or equal to the specified order
will be printed.

--------------------------------------------------------------------------------
SHAPe  STATistics  {name}  [ PROP int ]
                   {ALL }              

The "STATistics" subcommand will print various statistics about one or ALL
of the current shapes.

--------------------------------------------------------------------------------
SHAPe  LIST

The "LIST" subcommand will list all active descriptors, all of the active
properties, and all of the shape restraints.

--------------------------------------------------------------------------------
SHAPe { WRITe          } [UNIT integer] 
      { READ  [APPEnd] }

The I/O subcommands allow a set of shapes to be saved to a disk and subsequently
retrieved.  There are restrictions to the "READ APPEnd" option (the order and
all properties must match).  

--------------------------------------------------------------------------------
SHAPe  DISPlay name PROPerty int [UNIT integer] [TOLErance real] }

The "DISPlay" subcommand is used to display descriptors as shaped blob within
CHARMM graphics (or other graphics packages).

### NOTE: This command is not yet finished

--------------------------------------------------------------------------------
SHAPe { ROTAte PHI real }  name  { center-specs } [ DISTance real ]
      { TRANslate       }        { AXIS         } [ FACTor real   ]

center-specs: [XDIR real] [YDIR real] [ZDIR real]  -
                 [XCEN real] [YCEN real] [ZCEN real]
               
The "TRANslate" and "ROTAte" subcommands are used to move shapes about, either
with or without associated atoms.  The "SHAPe AXIS" command may be used to
define an axis vector for rotation or translation.  .

--------------------------------------------------------------------------------
SHAPe  CENTer name1 [PROPerty num] [ name2  [NONChiral] ]    

The "CENTer" subcommand has two modes of operation.  If a single shape name is
specified, then that shape is centered at coordinate origin based on the values
of the specified property.  The usual property subtypes are:
          ONE   EXPOnent 1  POINt  NORMalized  - Center of geometry
          MASS  EXPOnent 1  POINt  NORMalized  - Center of mass
but others are, of course, possible.

If a second name is specified, them a best fit is performed based by; (a) moving
the first shape so that it has a common center with the second, (b) then
rotating the first shape so that the principal axis align, (c) rotating and/or
inverting the first shape by 180 degrees, to find the best overall fit where
the pincipal axis are aligned.  If the "NONChiral" keyword is specified, it also
tries a set of mirror image best fits.  If there are atoms associated with
the shape (type "RIGId") then they will also move as part of the best-fit
operation.  With the "NONChiral" option, the chirality of the selected atoms
may invert (still rigid, but opposite chirality!).

--------------------------------------------------------------------------------
SHAPe  COMPare  name1 name2  [PROP int]   - print the fit of two descriptors

The "COMPare" subcommand will print the fit of two shapes for one (or all)
properties.  This command does not modify any shape (only prints result).
The result is given as the square-root of the "ssq" value (see below).
The value of the fit is stored in the "?SFIT" substitution variable.

--------------------------------------------------------------------------------
SHAPe  AXIS name  [ NORM  ]  [PROP int] 
                  [ MAJOr ]             
                  [ MINOr ]             

The "AXIS" subcommand will determine an axis for subsequent use.  This is
same axis created by the "COOR AXIS" and the "COOR LSQP" commands.  The
resultant axis will be centered at the data center of the shape, and the
direction of the axis will along one of the principal axis directions.
The largest moment is "MAJOr" the secons is "MINOr" and the smallest is
"NORMal".  This usage is the same as that of the "COOR LSQP" command.

--------------------------------------------------------------------------------
SHAPe { COPY      name1 name2   [PROP int]   } - copy from second to first
      { SUM       name1 name2   [PROP int]   } - add two shape factors together
      { DIFF      name1 name2   [PROP int]   } - subtract two shape factors
      { SCALe     name1 real    [PROP int]   } - scale a single shape factor

These commands manipulate a particular shape for one (if specified) or all
properties.  The shape, name1, is the one which is modified.  The shape, name2,
is used as a data source.  This is what it does;
      COPY     name1 = name2
      SUM      name1 = name1 + name2
      DIFF     name1 = name1 - name2
      SCALe    name1 = name1 * real

--------------------------------------------------------------------------------
SHAPe  DUPLIcate name1 name2 

The "DUPLicate" command is like the "COPY" command, except that a new shape is
added.  If the original shape has associated atoms (type "RIGId" or "FLEX"),
these will NOT be assigned to the new shape (and a warning issued).
                                        
--------------------------------------------------------------------------------
SHAPe  RESTraint { CLEAR                        }   - Clear all shape restraints
                 { ADD name1 name2 [FORCE real] }   - Add a shape restraint
                 { MODIfy name1 name2 FORCE real}   - Change a force constant

The "RESTrain" subcommand manipulates which pairs of shapes make up the
shape restraint energy term.  This energy term is symmetric (i.e. the order
of the names doesn't matter).  The form of the energy is

      Energy    = sum    { 0.5 * K  * ssq  )
          shape    rest-i         i      i

      ssq  = sum      {  weight     * ( elem(i1)     - elem(i2)     )**2
         i     j,k,l,prop    j,k,l,prop    j,k,l,prop   j,k,l,prop

Commands to setup a shape restraint
The maximum number of shape restraints is given by MAXESH (currently 10).

--------------------------------------------------------------------------------
###   { PARTition  .... } - Cut a shape into two subshapes based on a planar cut

Shape partitioning is still in development.... (coming soon..hopefully)

--------------------------------------------------------------------------------
End.

NIH Helix/Biowulf Systems
charmm.org Homepage

CHARMM Documentation / Rick_Venable@nih.gov