chemical shift anisotropy potential

 One normally creates CSAPot object using the create_CSAPot function within 
the <m csaPotTools> module.

constructor:   
	CSAPot(instanceName,
	       oTensor
	       restraints,
	       simulation)
  
  instanceName is a user-specified identifier. oTensor specifies an 
  orientational VarTensor object. restraints is an optional XPLOR-style
  CSA restraint table. simulation is an optional Simulation specification.

members:
  oTensor - the VarTensor orientational tensor object.

methods:
  addRestraints(restraintList) - add the specified XPLOR-style CSA
                                 restraint table. Note that this is a 
 				 string, and not a filename.

  calcEnergy()                 - calc energy, returns the energy value.
  calcEnergyAndDerivs(derivs)  - calc energy, derivs, returns the energy value.



  rms()           - return the rms of calcedShift - effShift
  numRestraints() - the number of restraints defined for this term.
  deviation()     - return average of deviation of ensemble members
  violations()    - return number of violations
  
  info()                    - current info about the state of this instance
  showViolations()          - return a string listing violated restraints.
  showRestraints(violated)  - return info on restraints. Argument violated is
                              boolean specifying whether to return only 
 			      violated restraints.


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



 The following parameters can be set [defaults in square brackets]

  verbose    - if true, sporadically spit out info [False]
  scale	     - scale factor (force constant) [1]
  threshold  - threshold in violation calculation [0]
  potType    - type of potential: "harmonic" or "square" ["harmonic"]
  sigma      - principal moments of the chemical shift tensor, in the order
	       (sigma_xx, sigma_yy, sigma_zz) along the tensor principal axes 
	       (Ux, Uy, Uz) defined below.
  DaScale    - scale factor for Da in the CSA calculations. [1]
  tensorClass- type of tensor (how to interpret beta and gamma angles).
	       Valid values are BISECT and BOND. [BISECT]
  beta       - beta rotation used in calculating the tensor principal axes
	       from the atom selections. [0]
  gamma      - gamma rotation used in calculating the tensor principal axes
	       from the atom selections. [0]
  atomOrder  - string mapping selection atoms 1, 2 and 3 onto axis definition 
	       atoms a, b, and c. "123" maps 1->a,  2->b and 3->c. Supported
 	       values are "123", "132", and "231". ["123"]
  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. [0]

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

assignment table:
  entries in the restraint list have the following form

      assign ( sel OO ) ( sel Z  ) ( sel X  ) ( sel  Y )
             ( sel a  ) ( sel b  ) ( sel c  )  obsShift error1 [error2]

  where the first four selections are present for compatibility with
  XPLOR assignment tables, and are ignored. The a, b and c selections
  specify the atoms used to define the chemical shift tensor. The
  observed chemical shift is given (in ppb) by the obsShift argument, and the
  error bounds are given by error1 and error2.  If error2 is absent,
  it defaults to error1. 

 The principal axes of the CSA tensor are calculated from the
 positions of the three selected atoms in terms of qx, qy, and qz.
     qz = (qb-qa) X (qc-qa);
          | qb+qc-2*qa , if tensorClass==BISECT
     qy = |
          | qb-qa      , if tensorClass=BOND
     qx = qy X qz
 Unit vectors along qx,qy,qz are denoted as ux,uy,uz, respectively.
 The principal axes Ux, Uy, Uz are then
	
       ( Ux,Uy,Uz ) = (ux,uy,uz) * R,

 with the orienting matrix R given by:

	R = Ry(gamma) * Rz(beta),

 where Ry and Rz are rotation matrices about the y and z axes,
 respectively.  

 The chemical shift anisotropy is then given by the equation

   calcedShift =  sum_{i,j} A_i sigma_j * cos(theta_{i,j})^2

 where A_i is a principal moment of the orientation tensor, sigma_j is
 a the principal moment of the CSA tensor, and theta_{i,j}
 is the angle between the ith orientation tensor principal axis and
 the jth CSA tensor principal axis.



 The energy function is defined as

	1/2 * scale * (calcedShift - effShift)^2

 where for potType=harmonic, effShift = obsShift. For potType=square,

       effShift = calcedShift, if 
		    obsShift-error1 < calcedShift < obsShift+error2
                = calcedShift+error1, if calcedShift < obsShift-error1
                = calcedShift-error2, if calcedShift > obsShift+error2


Restraint class

methods:
  energy() - energy due to this restraint
    
  calcd()  - calculated value of the chemical shift (ensemble average).
  obs()    - observed value of chemical shift.
  diff()   - difference between calcd and obs

  plusErr(), minusErr() - bounds for the square well potential

  Selection1() - atomSel for atom 1
  Selection2() - atomSel for atom 2
  Selection3() - atomSel for atom 3

  calced_contrib() - list of contributions due to each ensemble member.

  deviation() - measure of spread between different ensemble members

  tensor(ensembleIndex=0) - return the CSA tensor of the specified ensemble
                            member.