PSolPot - solvent PREs as structural restraints
 
  The algorithm used to compute solvent PREs is described in
 
   Zhou Gong, C.D. Schwieters and Chun Tang, ``Theory and
   practice of using solvent paramagnetic relaxation enhancement
   to characterize protein conformational dynamics,'' Methods,
   148, 48-56 (2018) PMID: 29656079
 
 
Constructor:
 
  PSolPot(instanceName,
          selection,
          radii,
          restraints="")
 
   Return a PSolPot object with the given instance name. The selection
   argument is a string or atomSel.AtomSel object, while radii is
   an array of atomic radii to use for each atom in selection. Restraint
   assignments can be specified in the restraints argument.
 
 
Methods:
 
  selection()           - return the selection given in the constructor.
 
  addRestraints(string) - add restraints given in the string argument
 
  findImportantAtoms()  - for each restraint, determine which atoms contribute
                          significantly to the integrand.
 
  correlation()         - return the correlation between calculated and
                          observed solvent PREs.
 
  rms()                 - return root mean square deviation between calculated
                          and observed solvent PRE.
 
  qFactor()             - return the quality factor:
                                 rms / < obs^2 >
 
  violations()          - return the number of violated restraints.
 
  numRestraints()       - return the number of restraints.
 
  info()                - return an informational string.
 
  showRestraints(violated) - return string with info on restraints. If the
                             argument is True, only report on violated
                             restraints.
 
  showViolations()      - return an string with info on each restraint.
                          if showAllRestraints==True this will be all
                          restraints, otherwise it reports only on violated
                          restraints.
 
  surfInstance() - return the associated surf.Surf object.
  tessellation() - return the associated surfTessellation.SurfTessellation
                   object.
 
  restraints() - return a list of PsolRestraint objects- described below.
 
  retessellateIfNecessary(force=False)
                        - Regenerate the surface-describing triangles if the
                          atoms have moved more than surfTess.moveTol() since
                          the last tessellation. If force=True, always
                          retessellate. This function returns True if the
                          tessellation is performed, else False.
 
  kForOpt()  -   prefactor coefficient used in tauc optimization. May be
                 redundant.
 
 
  //
  // parameters specific for PSol
  //
 
  radii         - vector of atomic radii, of size len(selection()).
  radiusNoise   - small value added to each atomic radius to try to avoid
                  numerical instabilities. Further, if a bad tessellation
                  is detected, a different random value between
                  0 and radiusNoise is used. [10^{-8}]
  probeRadius   - solute radius, used to generate tessellated surface
                  for surface integration. [5.4 angstrom]
  radiusOffset  - amount added to VdW radii given in radii for use in
                  generating the tessellated surface  [5.4 angstrom].
  rmin         -  min distance from surface to nuclear center. The
                  value actually used depends on physicalAtoms(). If the
                  later is True the actual rmin used is the larger of rmin and
                  radii[i]+radiusOffset-centerOffset [0.8 angstrom].
  physicalAtoms-  a boolean value. Please see the docs for the rmin
                  accessor. [True]
  centerOffset -  center offset of solute - for off-center paramagnetic
                  center [0. angstrom]
 
 
 
  targetType    - Whether energy term targets differences in observed and
                  calculated solvent PRE, or the correlation of observed to
                  calculated: "gamma" or "correlation". ["correlation"]
  potType       - energy form for the energy term: "soft" or "hard" ["hard].
  rlxType       - specification of relaxation type: "r2dd" or "r1dd".
                  This is used in computation of the constant prefactor, 
                  and has no effect for correlation target type.  ["r2dd"]
  funType       - takes a value of "square" or "harmonic". The former value 
                  results in zero energy in a range of obs()+/-err().
                  ["harmonic"]
  sclType       - controls how the restraint energy is scaled: "none" for no
                  scaling (weight=1), "sigma" for 1/err^2 scaling, and 
                  obs/obs_max/err^2 for "obsig" ["const"]
 
  showAllRestraints - boolean. See the entry for the showViolations() method.
 
  hardExp       - exponential for hard potType [2].
  rSwitch       - parameters
  softExp       - for
  asympSlope    - soft potType.
  weightMax     - maximum restraint scale factor for sigma or obsig sclType.
 
  tauc          - tauc [ns]
  freqI         - nuclear frequency  [MHz]
  sqn           -  electron spin quantum number
  gfac          - g-factor
  gammaI        - gyromagnetic ratio [10^7 Ts-1]
  rho0          - conc. of paramagnetic solute [mM]
 
  coeff         - constant PRE prefactor. If setCoeff is called with a
                  negative prefactor, it is computed via the appropriate 
                  expression given below, otherwise it is set to the given 
                  value. 
 
  atomContribThreshold - ratio used in findImportantAtoms. For each restraint,
                         only atoms whose sums add up to this ratio of the
                         total for each calculated solvent PRE value are
                         used in energy and gradient calculations.
 
  fixTauc  - If True, fix tau_c. If False, parameters for tau_c optimization
             should be specified - this feature is not well tested.
 
             Parameters for tauc optimization
  tcmax    -  max of tauc [ns]
  tcmin    -  min of tauc [ns]
  toAtom   - pseudo-atoms for tauc optimization
  taAtom 
  tbAtom
 
  verbose  - set to True for verbose output [False].
 
 
 
Class PSolRestraint
 
Accessors:
 
  obs    - observed solvent PRE value
  err    - error in observed solvent PRE value
  weight - per-restraint energy scale factor - this is set via the 
           pot.setCoeff method and depends on the value of pot.sclType.
           See above. [ This should be setable with pot.sclType="none", but
           isn't yet. ]
 
 
Members/Methods:
 
  calcd()              - the calculated solventPRE value.
 
  minDist(ensIndex=-1) - the minimum distance of the first atom in the
                         selection to the tessellated surace. The optional
                         argument is used for ensembleSimulation
                         calculations to access the minimum distance for
                         each ensemeble member. An ensIndex of -1 will return
                         the shortest distance over the ensemble.
                        
  name()               - This should be a unique (within this term)
                         restraint name. It is currently the selection
                         string book-ended by parentheses.
 
  sel()                - The atomSel.AtomSel selection for this
                         restraint.
                         
  comment()            - return any per-restraint comment specified in the
                         input restraint list.
 
  importantAtoms       - list of indices of atoms making significant
                         constributions to the restraint's
                         corresponding sPRE value. The indices are into
                         the atomSelAtomSel pot->selection().
 
  missingAtomFactor    - For this restraint, the inverse of the fraction
                         of the sPRE value contributed by all surface 
                         contributions of atoms in importantAtoms relative
                         to the contribution of all atoms.
 
  triSpeedupFactor     - The ratio of the number of triangles corresponding 
                         to those of importantAtoms to the total number of
                         triangles.
  
  itgIr6()             - The computed value of the volume integral, without
                         multiplication by missingAtomFactor.
 
  // ensemble info
  //  double deviation(); FIX ??
 
Currently, support for non-stereospecifically assigned protons (mostly 
involving glycine HA atoms) is not supported.
 
 
We use the expression for solvent PRE given by 
 
 \gamma = k \int dv r^{-6}
 
where $r$ is the distance between the paramagnetic center of the
co-solute and the target nucleus, and the integral is over all space
accessible to the co-solute molecule. We approximate this expression
as
 
 \gamma = k/9 \sum_i a_i n_i \cdot r_i |r_i|^{-6}
 
with the sum over all vertices of all triangles of a tessellated
molecular surface, $a_i$ the area of triangle $i$,  $r_i$ a vector
from vertex $i$ to the target nucleus, and $n_i$ an outward-facing
unit surface normal vector. In this implementation, the sum is over
those atoms (importantAtoms) whose sums provide atomContribThreshold
of the total of the sum.
 
The prefactor, for correlation targetType, the energy does not depend
on the value of $k$. For gamma targetType, $k$ can be allowed to float
between tcmin and tcmax using psuedo-atoms toAtom, taAtom and tbAtom.
 
If not set explicitly, the prefactor is given by:
 
 for rlxType = R2DD
  coeff = Na \rho_0 \tau_c (4 + 3/(1+(\omega\tau_c)^2) +
                            13 / (1+(\omega_e\tau_c)^2))
 for rlxType = R1DD
  coeff = Na \rho_0 \tau_c ( 3/(1+(\omega\tau_c)^2) +
                             7/(1+(\omega_e\tau_c)^2))
  
  where Na is Avogadro's number, \rho_0 is the concentration of
  solute, \omega is the Larmor frequency and \omega_e is the electron
  spin characteristic frequency. 
 
The value of \rho_0 is frequently not known, so uncertainty is rolled
into the value of \tau_c, if optimized. Most typically, correlation
targetType is used, and then least squared used to determine the
appropriate prefactor, which is then set.
 
 
 
 
# This file was automatically generated by SWIG (http://www.swig.org).
# Version 4.0.2
#
# Do not make changes to this file unless you know what you are doing--modify
# the SWIG interface file instead.