Potential term restraining distances expected to be symmetric. This is
approximately the same functionality as that of the XPLOR NOE SYMMetry
routine. The primary difference is that this term will correctly treat
<n ensembleSimulation>.EnsembleSimulation averaging.


Constructor:

  It is suggested that this potential term be created using the helper 
  function <m distSymmTools>.create_DistSymmPot().


  DistSymmPot(instanceName,   - creates a potential term with the given name. 
              simulation  )     The simulation argument is optional- it omitted
	     		 	<m simulation>.defaultSimulation() will be used.

  
Methods:

  addRestraint(listOfTuples) - list of two-membered tuples of atom
                                selections, each of which specifies a
                                distance which should be
                                restrained. E.g. for a dimer, the list
                                should contain two sets of dimers.

  rms()                      - returns a measure of RMSD of distance
  			       symmetry violation (see below).

  violations()               - returns number of violated distance
                               symmetry restraints

  numRestraints()            - return the number of restraints

  info()                    - current info about the state of this instance
  showViolations()          - return string containing pretty-printed info
                              on all violated restraints.

  restraints()              - return a list of restraints. See the description 
  			      of the Restraint class below.


 Read-Write accessors:
  scale             - scale factor (force constant) for the potential term.
  ensembleAveType   - "none" or "average" - controls whether to enforce
                      symmetry restraints on each ensemble member- or to
		      enforce only overall ensemble symmetry (see below).
  threshold         - amount of violation of restraint greater than which 
  		      the restraint is considered violated [0.2 angstrom]
  showAllRestraints - boolean which changes the behavior of showViolations. If 
                      this parameter is set to True, the behavior of
		      showViolations is modified such that all restraints are
      	              printed. Violated restraints are indicated by an
                      asterisk in the first column. [False]
  

 the above quantities may be retrieved using the member function form
 quantity(), while they are set using the form setQuantity(value).


class DistSymmPot_Restraint:

methods:
    
public:
  energy() - return current energy
  name()   - restraint name (String)

raw members:

  tol      - error tolerance for this restraint

  distAtom1 - list of lists of atoms. These contain atoms specified by
  distAtom2   addRestraints.

  
  contrib    - array containing the contribution to energy from each ensemble 
               member

  aveDistIntra - ave. dist. within an ensemble member
  deltaIntra     
  aveDistInter -  distance between atom1 in different ensemble members
  deltaInter1
  aveDistInter2 - distance between atom2 in different ensemble members
  deltaInter2

The potential term is defined as

  E = scale() * sum_r E_r

with
 
  E_r being the contribution from each restraint.

For averageType="none", each restraint's energy is a sum over
contributions from each ensemble member i:

   E_r = sum_i w_i ( ca_i + sum_i' w_i' (cr1_ii' + cr2_ii') ),

with w_i being the ensemble member's weight,

  ca_i = < d_i^2 >_j - < d_i >_j^2        (averaged over all distances)

   with  d_ij = |q1_ij - q2_ij|
   and q1_ij, the position of the atom corresponding to the first
   selection of the jth entry in the restraint's distAtom1 in ensemble
   member i.

  cr1_ii' = < dr1_ii'^2 >_j - < dr1_ii' >_j^2 
  cr2_ii' = < dr2_ii'^2 >_j - < dr2_ii' >_j^2 

    with dr1_ii'j = |q1_ij - q2_i'j|

The RMSD is calculated as

   sqrt( sum_r E_r / N_r )

  where N_r is the number of restraints.