---

ObjCryst::Molecule Class Reference

Molecule : class for complex scatterer descriptions using cartesian coordinates with bond length/angle restraints, and moves either of individual atoms or using torsion bonds. More...

Inheritance diagram for ObjCryst::Molecule:

List of all members.

Public Methods
	Molecule (Crystal &cryst, const string &name="")
	Constructor.
	Molecule (const Molecule &old)
	Copy constructor.
	~Molecule ()
	Destructor.
virtual Molecule *	CreateCopy () const
virtual const string &	GetClassName () const
	Name for this class ("RefinableObj", "Crystal",...).
virtual void	Print () const
	Print some info about the scatterer (ideally this should be one line...).
virtual void	XMLOutput (ostream &os, int indent=0) const
	Output to stream in well-formed XML.
virtual void	XMLInput (istream &is, const XMLCrystTag &tag)
	Input From stream.
virtual void	BeginOptimization (const bool allowApproximations=false, const bool enableRestraints=false)
	This should be called by any optimization class at the begining of an optimization.
virtual void	RandomizeConfiguration ()
	Randomize Configuration (before a global optimization).
virtual void	GlobalOptRandomMove (const REAL mutationAmplitude, const RefParType *type)
	Make a random move of the current configuration.
virtual REAL	GetLogLikelihood () const
	Get -log(likelihood) of the current configuration for the object.
virtual void	TagNewBestConfig () const
	During a global optimization, tells the object that the current config is the latest "best" config.
virtual int	GetNbComponent () const
	Number of components in the scatterer (eg number of point scatterers).
virtual const ScatteringComponentList &	GetScatteringComponentList () const
	Get the list of all scattering components for this scatterer.
virtual string	GetComponentName (const int i) const
	Name for the i-th component of this scatterer.
virtual ostream &	POVRayDescription (ostream &os, const CrystalPOVRayOptions &options) const
	For internal use only. Output a description of the scatterer for POVRay. This should only be called by the Crystal Object to which belongs this scatterer.
virtual void	GLInitDisplayList (const bool onlyIndependentAtoms=false, const REAL xMin=-.1, const REAL xMax=1.1, const REAL yMin=-.1, const REAL yMax=1.1, const REAL zMin=-.1, const REAL zMax=1.1, const bool displayEnantiomer=false, const bool displayNames=false) const
void	AddAtom (const REAL x, const REAL y, const REAL z, const ScatteringPower *pPow, const string &name, const bool updateDisplay=true)
	Add an atom.
vector< MolAtom * >::iterator	RemoveAtom (const MolAtom &)
	Remove an atom.
void	AddBond (MolAtom &atom1, MolAtom &atom2, const REAL length, const REAL sigma, const REAL delta, const REAL bondOrder=1., const bool updateDisplay=true)
	Add a bond.
vector< MolBond * >::iterator	RemoveBond (const MolBond &)
	Remove a bond.
vector< MolBond * >::const_iterator	FindBond (const MolAtom &, const MolAtom &) const
	Searches whether a bond between two atoms already exists.
vector< MolBond * >::iterator	FindBond (const MolAtom &, const MolAtom &)
	Searches whether a bond between two atoms already exists.
void	AddBondAngle (MolAtom &atom1, MolAtom &atom2, MolAtom &atom3, const REAL angle, const REAL sigma, const REAL delta, const bool updateDisplay=true)
	Add a bond angle restraint.
vector< MolBondAngle * >::iterator	RemoveBondAngle (const MolBondAngle &)
	Remove a BondAngle.
vector< MolBondAngle * >::const_iterator	FindBondAngle (const MolAtom &at1, const MolAtom &at0, const MolAtom &at2) const
	Searches whether a bond between three atoms already exists, searching for either (at1,at2,at3) and (at3,at2,at1), as these are equivalent.
void	AddDihedralAngle (const MolAtom &atom1, const MolAtom &atom2, const MolAtom &atom3, const MolAtom &atom4, const REAL angle, const REAL sigma, const REAL delta, const bool updateDisplay=true)
	Add a dihedral angle restraint.
vector< MolDihedralAngle * >::iterator	RemoveDihedralAngle (const MolDihedralAngle &)
	Remove a dihedral angle.
vector< MolDihedralAngle * >::const_iterator	FindDihedralAngle (const MolAtom &at1, const MolAtom &at2, const MolAtom &at3, const MolAtom &at4) const
	Searches whether a dihedral between four atoms already exists, searching for either (at1,at2,at3,at4) and (at4,at3,at2,at1), as these are equivalent.
void	OptimizeConformation (const long nbTrial=10000, const REAL stopCost=0.)
	Minimize configuration from internal restraints (bond lengths, angles and dihedral angles).
void	RotateAtomGroup (const MolAtom &at1, const MolAtom &at2, const set< unsigned long > &atoms, const REAL angle)
	Rotate a group of atoms around an axis defined by two atoms.
void	RotateAtomGroup (const MolAtom &at, const REAL vx, const REAL vy, const REAL vz, const set< unsigned long > &atoms, const REAL angle)
	Rotate a group of atoms around an axis defined by one atom and a vector.
void	RestraintStatus (ostream &os) const
	Print the status of all restraints (bond length, angles...).
const map< unsigned long, set< unsigned long > > &	GetConnectivityTable () const
	Get the connectivity table.
RefinableObjClock &	GetBondListClock ()
	get the clock associated to the list of bonds
const RefinableObjClock &	GetBondListClock () const
	get the clock associated to the list of bonds
void	RigidifyWithDihedralAngles ()
	Add dihedral angles so as to rigidify the Molecule.
Private Methods
virtual void	InitRefParList ()
	Prepare refinable parameters for the scatterer object.
void	BuildRingList () const
	Build the list of rings in the molecule.
void	BuildConnectivityTable () const
	Build the Connectivity table.
void	BuildRotorGroup ()
	Build the groups of atoms that will be rotated during global optimization.
void	BuildFlipGroup ()
	Build the groups of atoms that can be flipped.
void	UpdateScattCompList () const
	Update the Molecule::mScattCompList from the cartesian coordinates of all atoms, and the orientation parameters.
vector< MolAtom * >::reverse_iterator	FindAtom (const string &name)
	Search a MolAtom from its name.
vector< MolAtom * >::const_reverse_iterator	FindAtom (const string &name) const
	Search a MolAtom from its name.
void	InitOptions ()
	Build options for this object.
void	FlipAtomGroup (const FlipGroup &)
	Flip a group of atom. See Molecule::FlipGroup.
Private Attributes
ScatteringComponentList	mScattCompList
	The list of scattering components.
vector< MolAtom * >	mvpAtom
	The list of atoms.
vector< MolBond * >	mvpBond
	The list of bonds.
vector< MolBondAngle * >	mvpBondAngle
	The list of bond angles.
vector< MolDihedralAngle * >	mvpDihedralAngle
	The list of dihedral angles.
map< MolAtom *, std::vector< MolBond * > >	mvAtomBond
	List of Bonds for each atom.
vector< MolRing >	mvRing
	The list of rings.
Quaternion	mQuat
	The unit quaternion defining the orientation.
RefObjOpt	mFlexModel
	OPtion for the different types of flexibility possible for this molecule: rigid body, free atoms + restraints, torsion angles...
RefObjOpt	mAutoOptimizeConformation
	Option to automatically optimize the starting conformation, if the total restraint cost is too high.
RefObjOpt	mOptimizeOrientation
	Option to optimize the Molecule's orientation.
map< unsigned long, set< unsigned long > >	mConnectivityTable
	Connectivity table: for each atom, keep the list of atoms bonded to it.
list< RotorGroup >	mvRotorGroupTorsion
	List of RotorGroups corresponding to free torsion bonds.
list< RotorGroup >	mvRotorGroupTorsionSingleChain
	List of RotorGroups corresponding to free torsion bonds, but with only one chain of atoms listed.
list< RotorGroup >	mvRotorGroupInternal
	List of RotorGroups for internal rotations.
list< FlipGroup >	mvFlipGroup
	The list of FlipGroups.
REAL	mLogLikelihood
	The current log(likelihood).

---

Detailed Description

Molecule : class for complex scatterer descriptions using cartesian coordinates with bond length/angle restraints, and moves either of individual atoms or using torsion bonds.

This can also be used for non-organic compounds (polyhedras etc...)

Note:

the parametrization is very different from ZScatterer: we keep a list of x,y,z which do not use limits (they must not), but the coordinates must be restrained or constrained from the expected bond lengths, angles and dihedral angles. The list of parameters is re-created in BeginOptimization() (except for the global x y z parameters for the global position of the Molecule, in fractionnal coordinates).

Note:

: all atoms must be somehow connected

---

Member Function Documentation

virtual void ObjCryst::Molecule::BeginOptimization (  const bool    allowApproximations = false, const bool    enableRestraints = false )  [virtual]

This should be called by any optimization class at the begining of an optimization. This will also check that everything is ready, eg call the RefinableObj::Prepare() function. This also affects all sub-objects. Note: this may be called several time for some objects which are used by several other objects. Parameters: allowApproximations:  if true, then the object can use faster but less precise functions during the optimization. This is useful for global optimization not using derivatives. enableRestraints:  if true, then restrained parameters will be allowed to go beyond theur hard limits. This implies that the algorithm will take into account the cost (penalty) related to the restraints. Objects which do not use restraints will simply ignore this. WARNING: this parameter may be removed with the new likelihood scheme. Reimplemented from ObjCryst::RefinableObj.

void ObjCryst::Molecule::BuildFlipGroup (    )  [private]

Build the groups of atoms that can be flipped. This is not const because we temporarily modify the molecule conformation to test which FlipGroups are forbidden by restraints (but it should be const).

void ObjCryst::Molecule::BuildRingList (    )  [private]

Build the list of rings in the molecule. The list is only rebuilt if the bond or atom list has changed,so it should be safe to call again this function. Note: So far this is a const method as the ring list just reflects the bond list and therefore is mutable (see Molecule::mvRing)... but maybe this could change...

void ObjCryst::Molecule::BuildRotorGroup (    )  [private]

Build the groups of atoms that will be rotated during global optimization. This is not const because we temporarily modify the molecule conformation to test which RotorGroups are forbidden by restraints (but it should be const).

virtual Molecule* ObjCryst::Molecule::CreateCopy (    )  [virtual]

For internal use only. so-called Virtual copy constructor, needed to make copies of arrays of Scatterers Implements ObjCryst::Scatterer.

vector<MolAtom*>::const_reverse_iterator ObjCryst::Molecule::FindAtom (  const string &    name )  const [private]

Search a MolAtom from its name. Search begins at the end, and the first match is returned. returns mvAtom.rend() if no atom matches

vector<MolAtom*>::reverse_iterator ObjCryst::Molecule::FindAtom (  const string &    name )  [private]

Search a MolAtom from its name. Search begins at the end, and the first match is returned. returns mvAtom.rend() if no atom matches

vector<MolBond*>::iterator ObjCryst::Molecule::FindBond (  const MolAtom &   , const MolAtom &    )

Searches whether a bond between two atoms already exists. If no bond is found, returns Molecule::mvpAtom.end().

vector<MolBond*>::const_iterator ObjCryst::Molecule::FindBond (  const MolAtom &   , const MolAtom &    )  const

Searches whether a bond between two atoms already exists. If no bond is found, returns Molecule::mvpAtom.end().

vector<MolBondAngle*>::const_iterator ObjCryst::Molecule::FindBondAngle (  const MolAtom &    at1, const MolAtom &    at0, const MolAtom &    at2 )  const

Searches whether a bond between three atoms already exists, searching for either (at1,at2,at3) and (at3,at2,at1), as these are equivalent. If no bond angle is found, returns Molecule::mvpBondAngle.end().

vector<MolDihedralAngle*>::const_iterator ObjCryst::Molecule::FindDihedralAngle (  const MolAtom &    at1, const MolAtom &    at2, const MolAtom &    at3, const MolAtom &    at4 )  const

Searches whether a dihedral between four atoms already exists, searching for either (at1,at2,at3,at4) and (at4,at3,at2,at1), as these are equivalent. If no dihedral angle is found, returns Molecule::mvpDihedralAngle.end().

virtual const string& ObjCryst::Molecule::GetClassName (    )  [virtual]

Name for this class ("RefinableObj", "Crystal",...). This is only useful to distinguish different classes when picking up objects from the RefinableObj Global Registry Reimplemented from ObjCryst::Scatterer.

virtual string ObjCryst::Molecule::GetComponentName (  const int    i )  const [virtual]

Name for the i-th component of this scatterer. If the component is an Atom, Then the name is that of the atom. Else, it is the name of the scatterer plus the component number in the scatterer plus the name of the ScatteringPower. Note: It would be better to return a reference, but we don't want to keep a name for all components... Weeelll, needs some more thinking... see what performance hit results (if any). Bug: does not take into account dummy atoms !! Implements ObjCryst::Scatterer.

virtual REAL ObjCryst::Molecule::GetLogLikelihood (    )  [virtual]

Get -log(likelihood) of the current configuration for the object. By default (no likelihood evaluation available), this is equal to 0. This call should not be recursive, it is the task of the algorithm to get the sum of likelihoods for all objects invlolved. Note: contrary to the old "Cost Function" approach, with log(Likelihood) there is no 'choice' of cost function, so that it is the task of the object to give the optimized likelihood (possibly with user options). \warning: this is in under heavy development, so expect changes... Reimplemented from ObjCryst::RefinableObj.

virtual const ScatteringComponentList& ObjCryst::Molecule::GetScatteringComponentList (    )  [virtual]

Get the list of all scattering components for this scatterer. This is the most important function of this class, giving the list of scattering positions along with the associated ScatteringPower. Implements ObjCryst::Scatterer.

virtual void ObjCryst::Molecule::GLInitDisplayList (  const bool    onlyIndependentAtoms = false, const REAL    xMin = -.1, const REAL    xMax = 1.1, const REAL    yMin = -.1, const REAL    yMax = 1.1, const REAL    zMin = -.1, const REAL    zMax = 1.1, const bool    displayEnantiomer = false, const bool    displayNames = false )  const [virtual]

For internal use only. Create an OpenGL Display List of the scatterer. This should only be called by a Crystal object. Parameters: noSymmetrics:  if false (the default), then all symmetrics are shown in the 3D display, within the limits defined by the min/max parameters \ param xMin,xMax,yMin,yMax,zMin,zMax: in fractionnal coordinates, the region in which we want scaterrer to be displayed. The test is made on the center of the scatterer (eg a ZScatterer (molecule) will not be 'cut' on the border). displayNames:  if true, only the names of the scatterers will be displayed, at the position of the scatterers (to actually see them, they will have to be translated with respect to the drawing of the scatterers). Implements ObjCryst::Scatterer.

virtual void ObjCryst::Molecule::GlobalOptRandomMove (  const REAL    mutationAmplitude, const RefParType *    type )  [virtual]

Make a random move of the current configuration. This is for global optimization algorithms. the moves for each parameter are less than their global optimization step, multiplied by the mutation amplitude. \warning: this makes a random move for the parameter declared for this object, and it is the duty of the object to decide whether the included objects should be moved and how. (eg an algorithm should only call for a move with the top object, and this object decides how he and his sub-objects moves). By default (RefinableObj implementation) all included objects are moved recursively. RefinableObj:: Parameters: mutationAmplitude:  multiplier for the maximum move amplitude, for all parameters type:  restrain the change exclusively to parameters of a given type (same type or descendant from this RefParType). Reimplemented from ObjCryst::RefinableObj.

virtual void ObjCryst::Molecule::InitRefParList (    )  [private, virtual]

Prepare refinable parameters for the scatterer object. For internal use only. Implements ObjCryst::Scatterer.

void ObjCryst::Molecule::OptimizeConformation (  const long    nbTrial = 10000, const REAL    stopCost = 0. )

Minimize configuration from internal restraints (bond lengths, angles and dihedral angles). Useful when adding manually atoms to get an initial reasonable configuration.

virtual void ObjCryst::Molecule::RandomizeConfiguration (    )  [virtual]

Randomize Configuration (before a global optimization). This Affects only parameters which are limited and not fixed. The randomization also affects all sub-objects (recursive). Reimplemented from ObjCryst::RefinableObj.

vector<MolAtom*>::iterator ObjCryst::Molecule::RemoveAtom (  const MolAtom &    )

Remove an atom. Returns the iterator to the next atom in the list. This also removes all corresponding bonds, bond angles, etc...

vector<MolBond*>::iterator ObjCryst::Molecule::RemoveBond (  const MolBond &    )

Remove a bond. Returns the iterator to the next bond in the list.

void ObjCryst::Molecule::RigidifyWithDihedralAngles (    )

Add dihedral angles so as to rigidify the Molecule. In practice, for every sequence of atoms A-B-C-D, add the dihedral angle defined by these 4 atoms, unless either ABC or BCD are aligned (angle below 10°). No duplicate dihedral angle is generated.

virtual void ObjCryst::Molecule::TagNewBestConfig (    )  [virtual]

During a global optimization, tells the object that the current config is the latest "best" config. This can be used by the object to make more intellingent random moves (use with caution: highly experimental !). Reimplemented from ObjCryst::RefinableObj.

virtual void ObjCryst::Molecule::XMLInput (  istream &    is, const XMLCrystTag &    tag )  [virtual]

Input From stream. Todo: Add an bool XMLInputTag(is,tag) function to recognize all the tags from the stream. So that each inherited class can use the XMLInputTag function from its parent (ie take advantage of inheritance). The children class would first try to interpret the tag, then if unsuccessful would pass it to its parent (thus allowing overloading), etc... Reimplemented from ObjCryst::RefinableObj.

virtual void ObjCryst::Molecule::XMLOutput (  ostream &    os, int    indent = 0 )  const [virtual]

Output to stream in well-formed XML. Todo: Use inheritance.. as for XMLInputTag()... Reimplemented from ObjCryst::RefinableObj.

---

Member Data Documentation

RefObjOpt ObjCryst::Molecule::mAutoOptimizeConformation [private]

Option to automatically optimize the starting conformation, if the total restraint cost is too high. This is done in BeginOptimization(). This is enabled by default, and should be disabled by people who already supply a good starting conformation for their molecule.

map<unsigned long,set<unsigned long> > ObjCryst::Molecule::mConnectivityTable [private]

Connectivity table: for each atom, keep the list of atoms bonded to it. All atoms are referenced from their index.

RefObjOpt ObjCryst::Molecule::mFlexModel [private]

OPtion for the different types of flexibility possible for this molecule: rigid body, free atoms + restraints, torsion angles... Warning: still EXPERIMENTAL !

RefObjOpt ObjCryst::Molecule::mOptimizeOrientation [private]

Option to optimize the Molecule's orientation. Useful to completely fix the Molecule.

ScatteringComponentList ObjCryst::Molecule::mScattCompList [private]

The list of scattering components. this is mutable since it only reflects the list of atoms.

map<MolAtom* , std::vector<MolBond*> > ObjCryst::Molecule::mvAtomBond [private]

List of Bonds for each atom. This duplicates the information in Molecule::mvBond

vector<MolRing> ObjCryst::Molecule::mvRing [private]

The list of rings. Note: this only reflects the bond list, so it is mutable.

list<RotorGroup> ObjCryst::Molecule::mvRotorGroupInternal [private]

List of RotorGroups for internal rotations. This lists groups of atoms that can be rotated between two given atoms. This is useful to alter the conformation of large rings, where no free torsion bonds exists, and also for long flexible chains.

list<RotorGroup> ObjCryst::Molecule::mvRotorGroupTorsion [private]

List of RotorGroups corresponding to free torsion bonds. In this list are list of atoms on one side of a bond, that can be rotated freely around this bond. Each bond is listed only once, with the side which has the smallest number of atoms.

list<RotorGroup> ObjCryst::Molecule::mvRotorGroupTorsionSingleChain [private]

List of RotorGroups corresponding to free torsion bonds, but with only one chain of atoms listed. The difference with Molecule::mRotorGroupTorsion is that if the bond is A-B, with atom A linked with atoms A1,A2,A3, in this list only one chain (starting either from A1, A2 or A3) will be rotated, instead of the 3 chains. This is useful when searching for the absolute configuration of atoms.

---

The documentation for this class was generated from the following file:

• Molecule.h

---