rdkit.Chem.rdDistGeom module — The RDKit 2025.09.6 documentation

# rdkit.Chem.rdDistGeom module

Module containing functions to compute atomic coordinates in 3D using distance geometry

rdkit.Chem.rdDistGeom.ETDG() → EmbedParameters :

  Returns an EmbedParameters object for the ETDG method.

  C++ signature :

    (anonymous namespace)::PyEmbedParameters* ETDG()

rdkit.Chem.rdDistGeom.ETDGv2() → EmbedParameters :

  Returns an EmbedParameters object for the ETDG method - version 2.

  C++ signature :

    (anonymous namespace)::PyEmbedParameters* ETDGv2()

rdkit.Chem.rdDistGeom.ETKDG() → EmbedParameters :

  Returns an EmbedParameters object for the ETKDG method - version 1.

  C++ signature :

    (anonymous namespace)::PyEmbedParameters* ETKDG()

rdkit.Chem.rdDistGeom.ETKDGv2() → EmbedParameters :

  Returns an EmbedParameters object for the ETKDG method - version 2.

  C++ signature :

    (anonymous namespace)::PyEmbedParameters* ETKDGv2()

rdkit.Chem.rdDistGeom.ETKDGv3() → EmbedParameters :

  Returns an EmbedParameters object for the ETKDG method - version 3 (macrocycles).

  C++ signature :

    (anonymous namespace)::PyEmbedParameters* ETKDGv3()

class rdkit.Chem.rdDistGeom.EmbedFailureCauses

  Bases: `enum`

  BAD_DOUBLE_BOND_STEREO = rdkit.Chem.rdDistGeom.EmbedFailureCauses.BAD_DOUBLE_BOND_STEREO
  CHECK_CHIRAL_CENTERS = rdkit.Chem.rdDistGeom.EmbedFailureCauses.CHECK_CHIRAL_CENTERS
  CHECK_CHIRAL_CENTERS2 = rdkit.Chem.rdDistGeom.EmbedFailureCauses.CHECK_CHIRAL_CENTERS2
  CHECK_TETRAHEDRAL_CENTERS = rdkit.Chem.rdDistGeom.EmbedFailureCauses.CHECK_TETRAHEDRAL_CENTERS
  ETK_MINIMIZATION = rdkit.Chem.rdDistGeom.EmbedFailureCauses.ETK_MINIMIZATION
  EXCEEDED_TIMEOUT = rdkit.Chem.rdDistGeom.EmbedFailureCauses.EXCEEDED_TIMEOUT
  FINAL_CENTER_IN_VOLUME = rdkit.Chem.rdDistGeom.EmbedFailureCauses.FINAL_CENTER_IN_VOLUME
  FINAL_CHIRAL_BOUNDS = rdkit.Chem.rdDistGeom.EmbedFailureCauses.FINAL_CHIRAL_BOUNDS
  FIRST_MINIMIZATION = rdkit.Chem.rdDistGeom.EmbedFailureCauses.FIRST_MINIMIZATION
  INITIAL_COORDS = rdkit.Chem.rdDistGeom.EmbedFailureCauses.INITIAL_COORDS
  LINEAR_DOUBLE_BOND = rdkit.Chem.rdDistGeom.EmbedFailureCauses.LINEAR_DOUBLE_BOND
  MINIMIZE_FOURTH_DIMENSION = rdkit.Chem.rdDistGeom.EmbedFailureCauses.MINIMIZE_FOURTH_DIMENSION
  names = {'BAD_DOUBLE_BOND_STEREO': rdkit.Chem.rdDistGeom.EmbedFailureCauses.BAD_DOUBLE_BOND_STEREO, 'CHECK_CHIRAL_CENTERS': rdkit.Chem.rdDistGeom.EmbedFailureCauses.CHECK_CHIRAL_CENTERS, 'CHECK_CHIRAL_CENTERS2': rdkit.Chem.rdDistGeom.EmbedFailureCauses.CHECK_CHIRAL_CENTERS2, 'CHECK_TETRAHEDRAL_CENTERS': rdkit.Chem.rdDistGeom.EmbedFailureCauses.CHECK_TETRAHEDRAL_CENTERS, 'ETK_MINIMIZATION': rdkit.Chem.rdDistGeom.EmbedFailureCauses.ETK_MINIMIZATION, 'EXCEEDED_TIMEOUT': rdkit.Chem.rdDistGeom.EmbedFailureCauses.EXCEEDED_TIMEOUT, 'FINAL_CENTER_IN_VOLUME': rdkit.Chem.rdDistGeom.EmbedFailureCauses.FINAL_CENTER_IN_VOLUME, 'FINAL_CHIRAL_BOUNDS': rdkit.Chem.rdDistGeom.EmbedFailureCauses.FINAL_CHIRAL_BOUNDS, 'FIRST_MINIMIZATION': rdkit.Chem.rdDistGeom.EmbedFailureCauses.FIRST_MINIMIZATION, 'INITIAL_COORDS': rdkit.Chem.rdDistGeom.EmbedFailureCauses.INITIAL_COORDS, 'LINEAR_DOUBLE_BOND': rdkit.Chem.rdDistGeom.EmbedFailureCauses.LINEAR_DOUBLE_BOND, 'MINIMIZE_FOURTH_DIMENSION': rdkit.Chem.rdDistGeom.EmbedFailureCauses.MINIMIZE_FOURTH_DIMENSION}
  values = {0: rdkit.Chem.rdDistGeom.EmbedFailureCauses.INITIAL_COORDS, 1: rdkit.Chem.rdDistGeom.EmbedFailureCauses.FIRST_MINIMIZATION, 2: rdkit.Chem.rdDistGeom.EmbedFailureCauses.CHECK_TETRAHEDRAL_CENTERS, 3: rdkit.Chem.rdDistGeom.EmbedFailureCauses.CHECK_CHIRAL_CENTERS, 4: rdkit.Chem.rdDistGeom.EmbedFailureCauses.MINIMIZE_FOURTH_DIMENSION, 5: rdkit.Chem.rdDistGeom.EmbedFailureCauses.ETK_MINIMIZATION, 6: rdkit.Chem.rdDistGeom.EmbedFailureCauses.FINAL_CHIRAL_BOUNDS, 7: rdkit.Chem.rdDistGeom.EmbedFailureCauses.FINAL_CENTER_IN_VOLUME, 8: rdkit.Chem.rdDistGeom.EmbedFailureCauses.LINEAR_DOUBLE_BOND, 9: rdkit.Chem.rdDistGeom.EmbedFailureCauses.BAD_DOUBLE_BOND_STEREO, 10: rdkit.Chem.rdDistGeom.EmbedFailureCauses.CHECK_CHIRAL_CENTERS2, 11: rdkit.Chem.rdDistGeom.EmbedFailureCauses.EXCEEDED_TIMEOUT}

rdkit.Chem.rdDistGeom.EmbedMolecule((rdkit.Chem.rdchem.Mol)mol[, (int)maxAttempts=0[, (int)randomSeed=-1[, (bool)clearConfs=True[, (bool)useRandomCoords=False[, (float)boxSizeMult=2.0[, (bool)randNegEig=True[, (int)numZeroFail=1[, (dict)coordMap={}[, (float)forceTol=0.001[, (bool)ignoreSmoothingFailures=False[, (bool)enforceChirality=True[, (bool)useExpTorsionAnglePrefs=True[, (bool)useBasicKnowledge=True[, (bool)printExpTorsionAngles=False[, (bool)useSmallRingTorsions=False[, (bool)useMacrocycleTorsions=True[, (int)ETversion=2[, (bool)useMacrocycle14config=True]]]]]]]]]]]]]]]]]]) → int :
  Use distance geometry to obtain initial

    > coordinates for a molecule

    > ARGUMENTS:

    > > - mol : the molecule of interest

    > > - maxAttempts : maximum number of embedding attempts to use for a single conformation

    > > - randomSeedprovide a seed for the random number generator

    > >     so that the same coordinates can be obtained for a molecule on multiple runs. If -1, the RNG will not be seeded.

    > > - clearConfs : clear all existing conformations on the molecule

    > > - useRandomCoordsStart the embedding from random coordinates instead of

    > >     using eigenvalues of the distance matrix.

    > > - boxSizeMultDetermines the size of the box that is used for

    > >     random coordinates. If this is a positive number, the side length will equal the largest element of the distance matrix times boxSizeMult. If this is a negative number, the side length will equal -boxSizeMult (i.e. independent of the elements of the distance matrix).

    > > - randNegEigIf the embedding yields a negative eigenvalue,

    > >     pick coordinates that correspond to this component at random

    > > - numZeroFail : fail embedding if we have at least this many zero eigenvalues

    > > - coordMapa dictionary mapping atom IDs->coordinates. Use this to

    > >     require some atoms to have fixed coordinates in the resulting conformation.

    > > - forceToltolerance to be used during the force-field minimization with

    > >     the distance geometry force field.

    > > - ignoreSmoothingFailurestry to embed the molecule even if triangle smoothing

    > >     of the bounds matrix fails.

    > > - enforceChirality : enforce the correct chirality if chiral centers are present.

    > > - useExpTorsionAnglePrefs : impose experimental torsion angle preferences

    > > - useBasicKnowledge : impose basic knowledge such as flat rings

    > > - printExpTorsionAngles : print the output from the experimental torsion angles

    > > - useMacrocycleTorsions : use additional torsion profiles for macrocycles

    > > - ETversionversion of the standard torsion definitions to use. NOTE for both

    > >     ETKDGv2 and ETKDGv3 this should be 2 since ETKDGv3 uses the ETKDGv2 definitions for standard torsions

    > > - useMacrocycle14config : use the 1-4 distance bounds from ETKDGv3

    > RETURNS:

    > > ID of the new conformation added to the molecule or -1 if the embedding fails.

    C++ signature :

      int EmbedMolecule(RDKit::ROMol {lvalue} [,unsigned int=0 [,int=-1 [,bool=True [,bool=False [,double=2.0 [,bool=True [,unsigned int=1 [,boost::python::dict {lvalue}={} [,double=0.001 [,bool=False [,bool=True [,bool=True [,bool=True [,bool=False [,bool=False [,bool=True [,unsigned int=2 [,bool=True]]]]]]]]]]]]]]]]]])

  EmbedMolecule( (rdkit.Chem.rdchem.Mol)mol, (EmbedParameters)params) -> int :
    Use distance geometry to obtain intial

      coordinates for a molecule

      ARGUMENTS:

      > - mol : the molecule of interest

      > - params : an EmbedParameters object

      RETURNS:

      > ID of the new conformation added to the molecule or -1 if the embedding fails.

    C++ signature :

      int EmbedMolecule(RDKit::ROMol {lvalue},RDKit::DGeomHelpers::EmbedParameters {lvalue})

rdkit.Chem.rdDistGeom.EmbedMultipleConfs((rdkit.Chem.rdchem.Mol)mol[, (int)numConfs=10[, (int)maxAttempts=0[, (int)randomSeed=-1[, (bool)clearConfs=True[, (bool)useRandomCoords=False[, (float)boxSizeMult=2.0[, (bool)randNegEig=True[, (int)numZeroFail=1[, (float)pruneRmsThresh=-1.0[, (dict)coordMap={}[, (float)forceTol=0.001[, (bool)ignoreSmoothingFailures=False[, (bool)enforceChirality=True[, (int)numThreads=1[, (bool)useExpTorsionAnglePrefs=True[, (bool)useBasicKnowledge=True[, (bool)printExpTorsionAngles=False[, (bool)useSmallRingTorsions=False[, (bool)useMacrocycleTorsions=True[, (int)ETversion=2[, (bool)useMacrocycle14config=True]]]]]]]]]]]]]]]]]]]]]) → rdkit.rdBase._vecti :
  Use distance geometry to obtain multiple sets of

    > coordinates for a molecule

    > ARGUMENTS:

    > > - mol : the molecule of interest

    > > - numConfs : the number of conformers to generate

    > > - maxAttempts : maximum number of embedding attempts to use for a single conformation

    > > - randomSeedprovide a seed for the random number generator

    > >     so that the same coordinates can be obtained for a molecule on multiple runs. If -1, the RNG will not be seeded.

    > > - clearConfs : clear all existing conformations on the molecule

    > > - useRandomCoordsStart the embedding from random coordinates instead of

    > >     using eigenvalues of the distance matrix.

    > > - boxSizeMult Determines the size of the box that is used for

    > >     random coordinates. If this is a positive number, the side length will equal the largest element of the distance matrix times boxSizeMult. If this is a negative number, the side length will equal -boxSizeMult (i.e. independent of the elements of the distance matrix).

    > > - randNegEigIf the embedding yields a negative eigenvalue,

    > >     pick coordinates that correspond to this component at random

    > > - numZeroFail : fail embedding if we have at least this many zero eigenvalues

    > > - pruneRmsThreshRetain only the conformations out of ‘numConfs’

    > >     after embedding that are at least this far apart from each other. RMSD is computed on the heavy atoms. Pruning is greedy; i.e. the first embedded conformation is retained and from then on only those that are at least pruneRmsThresh away from all retained conformations are kept. The pruning is done after embedding and bounds violation minimization. No pruning by default.

    > > - coordMapa dictionary mapping atom IDs->coordinates. Use this to

    > >     require some atoms to have fixed coordinates in the resulting conformation.

    > > - forceToltolerance to be used during the force-field minimization with

    > >     the distance geometry force field.

    > > - ignoreSmoothingFailurestry to embed the molecule even if triangle smoothing

    > >     of the bounds matrix fails.

    > > - enforceChirality : enforce the correct chirality if chiral centers are present.

    > > - numThreadsnumber of threads to use while embedding. This only has an effect if the RDKit

    > >     > was built with multi-thread support.

    > >     If set to zero, the max supported by the system will be used.

    > > - useExpTorsionAnglePrefs : impose experimental torsion angle preferences

    > > - useBasicKnowledge : impose basic knowledge such as flat rings

    > > - printExpTorsionAngles : print the output from the experimental torsion angles

    > RETURNS:

    > > Iterator which yields new conformation IDs

    C++ signature :

      std::vector<int, std::allocator<int> > EmbedMultipleConfs(RDKit::ROMol {lvalue} [,unsigned int=10 [,unsigned int=0 [,int=-1 [,bool=True [,bool=False [,double=2.0 [,bool=True [,unsigned int=1 [,double=-1.0 [,boost::python::dict {lvalue}={} [,double=0.001 [,bool=False [,bool=True [,int=1 [,bool=True [,bool=True [,bool=False [,bool=False [,bool=True [,unsigned int=2 [,bool=True]]]]]]]]]]]]]]]]]]]]])

  EmbedMultipleConfs( (rdkit.Chem.rdchem.Mol)mol, (int)numConfs, (EmbedParameters)params) -> rdkit.rdBase._vecti :
    Use distance geometry to obtain multiple sets of

      coordinates for a molecule

      ARGUMENTS:

      > - mol : the molecule of interest

      > - numConfs : the number of conformers to generate

      > - params : an EmbedParameters object

      RETURNS:

      > Iterator which yields new conformation IDs

    C++ signature :

      std::vector<int, std::allocator<int> > EmbedMultipleConfs(RDKit::ROMol {lvalue},unsigned int,RDKit::DGeomHelpers::EmbedParameters {lvalue})

class rdkit.Chem.rdDistGeom.EmbedParameters((object)arg1) → None :

  Bases: `instance`

  Parameters controlling embedding

  C++ signature :

    void __init__(_object*)

  property ETversion

    version of the experimental torsion-angle preferences

  GetFailureCounts((EmbedParameters)self) → tuple :

    returns the counts of each failure type

    C++ signature :

      boost::python::tuple GetFailureCounts((anonymous namespace)::PyEmbedParameters {lvalue})

  SetBoundsMat((EmbedParameters)self, (object)boundsMatArg) → None :

    set the distance-bounds matrix to be used (no triangle smoothing will be done on this) from a Numpy array

    C++ signature :

      void SetBoundsMat((anonymous namespace)::PyEmbedParameters {lvalue},boost::python::api::object)

  SetCPCI((EmbedParameters)self, (dict)CPCIdict) → None :

    set the customised pairwise Columb-like interaction to atom pairs.used during structural minimisation stage

    C++ signature :

      void SetCPCI((anonymous namespace)::PyEmbedParameters {lvalue},boost::python::dict)

  SetCoordMap((EmbedParameters)arg1, (dict)self) → None :

    sets the coordmap to be used

    C++ signature :

      void SetCoordMap((anonymous namespace)::PyEmbedParameters {lvalue},boost::python::dict)

  property basinThresh

    set the basin threshold for the DGeom force field.

  property boundsMatForceScaling

    scale the weights of the atom pair distance restraints relative to the other types of restraints

  property boxSizeMult

    determines the size of the box used for random coordinates

  property clearConfs

    clear all existing conformations on the molecule

  property embedFragmentsSeparately

    split the molecule into fragments and embed them separately

  property enableSequentialRandomSeeds

    handle random number seeds so that conformer generation can be restarted

  property enforceChirality

    enforce correct chirilaty if chiral centers are present

  property forceTransAmides

    constrain amide bonds to be trans

  property ignoreSmoothingFailures

    try and embed the molecule if if triangle smoothing of the bounds matrix fails

  property maxIterations

    maximum number of embedding attempts to use for a single conformation

  property numThreads

    number of threads to use when embedding multiple conformations

  property numZeroFail

    fail embedding if we have at least this many zero eigenvalues

  property onlyHeavyAtomsForRMS

    Only consider heavy atoms when doing RMS filtering

  property optimizerForceTol

    the tolerance to be used during the distance-geometry force field minimization

  property pruneRmsThresh

    keep only conformations that are at least this far apart from each other

    Type:

      used to filter multiple conformations

  property randNegEig

    if the embedding yields a negative eigenvalue, pick coordinates that correspond to this component at random

  property randomSeed

    seed for the random number generator

  property symmetrizeConjugatedTerminalGroupsForPruning

    symmetrize terminal conjugated groups for RMSD pruning

  property timeout

    maximum time in seconds to generate a conformer for a single molecule fragment. If set to 0, no timeout is set

  property trackFailures

    keep track of which checks during the embedding process fail

  property useBasicKnowledge

    impose basic-knowledge constraints such as flat rings

  property useExpTorsionAnglePrefs

    impose experimental torsion angle preferences

  property useMacrocycle14config

    use the 1-4 distance bounds from ETKDGv3

  property useMacrocycleTorsions

    impose macrocycle torsion angle preferences

  property useRandomCoords

    start the embedding from random coordinates instead of using eigenvalues of the distance matrix

  property useSmallRingTorsions

    impose small ring torsion angle preferences

  property useSymmetryForPruning

    use molecule symmetry when doing the RMSD pruning. Note that this option automatically also sets onlyHeavyAtomsForRMS to true.

  property verbose

    be verbose about configuration

rdkit.Chem.rdDistGeom.EmbedParametersToJSON((EmbedParameters)embedParameters) → str :

  Returns json string containing embedParameters attributes

  > ARGUMENTS:

  > > - embedParameters : the Params object you want serialized

  > RETURNS:

  > > The Params object as json string

  C++ signature :

    boost::python::str EmbedParametersToJSON(RDKit::DGeomHelpers::EmbedParameters)

rdkit.Chem.rdDistGeom.GetExperimentalTorsions((rdkit.Chem.rdchem.Mol)mol[, (bool)useExpTorsionAnglePrefs=True[, (bool)useSmallRingTorsions=False[, (bool)useMacrocycleTorsions=True[, (bool)useBasicKnowledge=True[, (int)ETversion=2[, (bool)printExpTorsionAngles=False]]]]]]) → tuple :

  returns information about the bonds corresponding to experimental torsions

  > C++ signature :

  >   boost::python::tuple GetExperimentalTorsions(RDKit::ROMol [,bool=True [,bool=False [,bool=True [,bool=True [,unsigned int=2 [,bool=False]]]]]])

  GetExperimentalTorsions( (rdkit.Chem.rdchem.Mol)mol, (EmbedParameters)embedParams) -> tuple :

    returns information about the bonds corresponding to experimental torsions

    C++ signature :

      boost::python::tuple GetExperimentalTorsions(RDKit::ROMol,RDKit::DGeomHelpers::EmbedParameters)

rdkit.Chem.rdDistGeom.GetMoleculeBoundsMatrix((rdkit.Chem.rdchem.Mol)mol[, (bool)set15bounds=True[, (bool)scaleVDW=False[, (bool)doTriangleSmoothing=True[, (bool)useMacrocycle14config=False]]]]) → object :

  Returns the distance bounds matrix for a molecule

  > ARGUMENTS:

  > > - mol : the molecule of interest

  > > - set15boundsset bounds for 1-5 atom distances based on

  > >     topology (otherwise stop at 1-4s)

  > > - scaleVDWscale down the sum of VDW radii when setting the

  > >     lower bounds for atoms less than 5 bonds apart

  > > - doTriangleSmoothingrun triangle smoothing on the bounds

  > >     matrix before returning it

  > RETURNS:

  > > the bounds matrix as a Numeric array with lower bounds in the lower triangle and upper bounds in the upper triangle

  C++ signature :

    _object* GetMoleculeBoundsMatrix(RDKit::ROMol {lvalue} [,bool=True [,bool=False [,bool=True [,bool=False]]]])

rdkit.Chem.rdDistGeom.KDG() → EmbedParameters :

  Returns an EmbedParameters object for the KDG method.

  C++ signature :

    (anonymous namespace)::PyEmbedParameters* KDG()

rdkit.Chem.rdDistGeom.srETKDGv3() → EmbedParameters :

  Returns an EmbedParameters object for the ETKDG method - version 3 (small rings).

  C++ signature :

    (anonymous namespace)::PyEmbedParameters* srETKDGv3()