class OEBestOverlay

This class is used to optimize the overlap between 2 molecules. Both molecules can contain one or more conformers. The reference molecule is held rigid and the fit molecule orientation is calculated to maximize overlap. Each conformer of the fit molecule is optimized against each conformer of the reference molecule, resulting in a large number of results that can be returned. The OEBestOverlayResults and OEBestOverlayScore classes are used to make handling this large amount of results easier.

Additionally, the reference or fit shape can be a grid instead of a molecule.

Since an OEBestOverlay optimization can result in numerous final results, one for each starting position, the OEBestOverlayResults class is a container to hold all the results for a fit conformer against a reference conformer. This class is essentially a container for one or more OEBestOverlayScore instances. The actual number of scores depends on the OEBOOrientation used in the OEBestOverlay.

For OEBOOrientation.Inertial, there will be 4, 8 or 20 scores per ref-fit conformer pair, depending on the symmetry of each conformer. For OEBOOrientation.AsIs, there will be just 1 OEBestOverlayScore inside each OEBestOverlayResults instance. And for OEBOOrientation.Random, then there will be 1 OEBestOverlayScore for each of the N random starts.

When dealing with the results from OEBestOverlay, the user can either use a double loop, i.e. loop over all the OEBestOverlayResults instances for each ref-fit conformer pair then loop over each OEBestOverlayScore inside each OEBestOverlayResults instance. In this case, the results also come out in conformer order.

Or, there is a free function OESortOverlayScores, that takes an iterator of OEBestOverlayResults and returns a single, sorted iterator of OEBestOverlayScores that can be used in a single loop.


OEBestOverlay(const OEBestOverlay &)
OEBestOverlay(const OEChem::OEMCMolBase &refmol)
OEBestOverlay(const OESystem::OEScalarGrid &refgrid, float interpolate=0.5f)

An empty OEBestOverlay class instance can be created, or a new instance can take the reference molecule or grid as an argument. Note that by default, grids that have a resolution larger that 0.5 Å will be interpolated to that resolution.


void ClearColorForceField()

Clear out any color force field. No color scores will be calculated.


void ClearUserStarts()

Set the number of User Starts back to zero.


bool GetAllColor() const


float GetCarbonRadius() const

Return the current value for the carbon radius approximation.


unsigned int GetInertialAxialDivisions() const


unsigned int GetInitialOrientation() const

Get the current value for initial orientation. Possible values are from the OEBOOrientation namespace.


float GetMaxRandomTranslation() const

Get the value in Å of maximum random translation.


unsigned int GetMethod() const

Return the current value of overlap method.


unsigned int GetMinimizeType() const

Get the current value for minimize type. Possible values are from the OEBOMinType namespace.


unsigned int GetNumRandomStarts() const

Get the current number of random starts.


unsigned int GetNumUserStarts() const

Get the number of user starts currently set. Note that these are not actually used unless OEBOOrientation.UserInertialStarts is also set.


unsigned int GetRadiiApproximation() const

Return the current value of the radii approximation.


unsigned int GetRandomSeed() const

Get the current value of the random seed.


const OESystem::OEScalarGrid *GetRefGrid() const


const OEChem::OEMCMolBase *GetRefMol() const


float GetRefSelfColor()

Return the self color score of the reference molecule.


unsigned int GetRefSymmetry(unsigned int confIdx) const


unsigned int GetRepresentationLevel() const

Return the current representation level.


float GetSymmetryThreshold() const


bool GetUseHydrogens() const

Return the status of hydrogen use in OEBestOverlay.


bool GetUserStarts(float *xyz) const

Extract the coordinates of the user starts. xyz should be sized to 3 * GetNumUserStarts().


OESystem::OEIterBase<OEBestOverlayResults> *
  Overlay(const OEChem::OEMCMolBase &fitmol)
OESystem::OEIterBase<OEBestOverlayResults> *
  Overlay(const OESystem::OEScalarGrid &fitgrid)

Perform the calculation and return the an iterator of the results.


void SetAllColor(bool state)


void SetCarbonRadius(float cradius)

Set the radius to use when using OEOverlapRadii.Carbon. By default this is set to 1.7 Å.


bool SetColorForceField(unsigned int type)
bool SetColorForceField(OEPlatform::oeistream &is)
bool SetColorForceField(const std::string &filename)
bool SetColorForceField(const OEColorForceField &cff)

Set the color force field to be used. Once set, color scores will be calculated and included in the results. Color gradients will not be included in the optimization unless specifically set using SetColorOptimize(true).


void SetColorOptimize(bool state)

Add color gradients to shape gradients in the optimization. Has no effect unless a color force field is also set via OEBestOverlay.SetColorForceField.


void SetInertialAxialDivisions(unsigned int divisions)


void SetInitialOrientation(unsigned int orient)

Determines the initial orientation (starting position) for each optimization. The default is OEBOOrientation.Inertial. Alternatives are defined in the OEBOOrientation namespace.


void SetMaxRandomTranslation(float trans)

If using random starts, this set the maximum distance (in Å) that the center of mass of the fit molecule will be moved away from the center calculated for inertial frame alignment.


void SetMethod(unsigned int method)

Set the method used to calculate overlap. The default for OEBestOverlay is OEOverlapMethod.Grid. Alternatives are defined in the OEOverlapMethod namespace.


void SetMinimizeType(unsigned int type)

Set the score to use in the optimization. Options are in the OEBOMinType namespace.


void SetNumRandomStarts(unsigned int n)

If SetInitialOrientation is set to OEBOOrientation.Random, this method sets the number of random starting positions that will be used.


void SetRadiiApproximation(unsigned int type)

Set the radius approximation used to calculate overlap. The default for OEBestOverlay is OEOverlapRadii.Carbon. Alternatives are defined in the OEOverlapRadii namespace.


void SetRandomSeed(unsigned int seed)

Set a random seed value to allow reproducible random searches.


bool SetRefGrid(const OESystem::OEScalarGrid &refgrid, float interpolate=0.5f)

Set a reference grid for the calculation. OEBestOverlay makes an internal copy. Pre-existing reference molecules or grids are replaced.


bool SetRefMol(const OEChem::OEMCMolBase &refmol)

Set a reference molecule for the calculation. OEBestOverlay makes an internal copy. Pre-existing reference molecules or grids are replaced.


void SetRepresentationLevel(unsigned int type)

Set the representation level for the Gaussians in OEBestOverlay. The default is OEOverlapRepresentation.Atomic. Alternatives are defined in the OEOverlapRepresentation namespace.


void SetSymmetryThreshold(float threshold)


void SetUseHydrogens(bool state)

Boolean to determine whether hydrogens are included in the shape calculation. By default this is false and hydrogens are ignored.


void SetUserStarts(const float *xyz, unsigned int nstarts)

Set a set of 3D coordinates for doing separate inertial starts. xyz should be 3 * nstarts. These are not used unless OEBOOrientation.UserInertialStarts is also set.