an ensemble of structures

A simulation which replicates the molecular structure in a given 
<m simulation>.Simulation, and allows structure calculations to be
performed on the simulation, optionally executing in parallel. This
module is described in 

    G.M. Clore and C.D. Schwieters, ``How much backbone motion in
    ubiquitin is required to be consistent with dipolar coupling data
    measured in multiple alignment media as assessed by independent
    cross-validation,'' J. Am. Chem. Soc. 126, 2923-2938 (2004).

Constructor:

 EnsembleSimulation(name,size,numThreads,simulation) -
     required parameters are the name of the new simulation, and the
     ensemble size. numThreads defaults to 1. On multiprocessor machines 
     this may be increased for approximate linear speedup. The
     ensemble is based on the simulation argument, which defaults to
     the current simulation. This ensemble should normally be constructed 
     before defining any potential terms, or <m ivm>.IVM objects. Any
     EnsemblePot (including PotList) will try to detect whether it was
     created before EnsembleSimulation(), and explicitly crash in the
     next call to its calcEnergy method.

Methods:

  This objects contains all of the methods of the <m simulation>.Simulation 
class. In addition, it contains the following:


  meanAtomPosArr() - return array of ensemble-averaged atom positions.

  members(memberIndex) - return Simulation corresponding to ensemble member.

  member()             - member associated with the current process

  multiThread() - call to terminate a single threaded region.

  numThreads() - the number of threads which execute simulataneously.

  singleThread() - used to enter a single threaded region in which only 
                   the master thread executes. Returns 1 for the master 
		   process and 0 otherwise. Example use:
 
                       if singleThread():
                         #perform action in only one thread
                       multiThread() #after this statement all threads run

  singleThreaded() - returns 1 if in a singleThreaded region.

  size() - size of ensemble.

  subSim() - simulation upon which the ensemble is based.

  weight(memberIndex) - return the weight of the given member.

less used methods:

  barrier() - used to synchronize threads of execution. All threads will
              reach this point before one continues on.

  sharedString() - return a SharedString object shared across the ensemble. 
                   It's usually preferable to use a SharedObj object from
                   the <m ensembleSharedObj> module.

  shutdown() - explicitly shutdown threads.



class EnsembleMemberSimulation

  this class is returned by the member() and members() methods of
EnsembleSimulation. It contains all the methods of the Simulation
class. In addition, there are

  pid() - return the id of the process which performs calculations on
          this member.

  memberIndex() - the index corresponding to this member.

  weight() - weight for this member

  ensembleSim() - the ensembleSimulation for this member.
  subSim()      - the Simulation on which this member is based.


The following <m atomSelAction>.AtomSelAction helper function
calculates RMSD between the ensemble members.

class  EnsembleRMSD

methods:
  rmsd() : return overall RMSD between ensemble members
  byResidue(): return a dictionary with keys being residue ids, and
               values being per-residue RMSDs.

the RMSD is defined as

  sqrt( 1/N sum_ijk w_i * w_j * |q_ik - q_jk|^2 )

where q_ik is the position of atom k in ensemble i, N is the number of
atoms and w_i is the weight on ensemble member i.


Helper Functions

  There are three module-level helper functions which can be used
whether or not an EnsembleSimulation is defined:

  singleThread - general version of EnsembleSimulation.singleThread
  multiThread  - general version of EnsembleSimulation.multiThread
  commBarrier  - EnsembleSimulation-safe <m socketComm>.SocketComm barrier