0
# 3D Structure Generation
1

2
3D conformer generation, molecular embedding, and 3D descriptor calculations for spatial molecular analysis. These capabilities enable three-dimensional molecular modeling, conformational analysis, and calculation of geometry-dependent molecular properties essential for drug design and molecular recognition studies.
3

4
## Capabilities
5

6
### 2D Coordinate Generation
7

8
Generate 2D coordinates for molecular visualization and drawing.
9

10
```python { .api }
11
def Compute2DCoords(mol: Mol, canonOrient: bool = True, 
12
                    clearConfs: bool = True, coordMap: dict = None, 
13
                    nFlipsPerSample: int = 0, nSample: int = 1, 
14
                    sampleSeed: int = 0, permuteDeg4Nodes: bool = False) -> None:
15
    """
16
    Generate 2D coordinates for a molecule.
17
    
18
    Parameters:
19
    - mol: Input molecule (modified in place)
20
    - canonOrient: Use canonical orientation (default True)
21
    - clearConfs: Clear existing conformers (default True)
22
    - coordMap: Dictionary mapping atom indices to fixed coordinates
23
    - nFlipsPerSample: Number of flips per sample for optimization
24
    - nSample: Number of samples to generate
25
    - sampleSeed: Random seed for reproducibility
26
    - permuteDeg4Nodes: Permute degree-4 nodes during generation
27
    
28
    Returns:
29
    None (modifies molecule in place)
30
    """
31
```
32

33
### 3D Conformer Generation
34

35
Generate three-dimensional molecular conformations using distance geometry algorithms.
36

37
```python { .api }
38
def EmbedMolecule(mol: Mol, maxAttempts: int = 10, randomSeed: int = -1,
39
                  clearConfs: bool = True, useExpTorsionAnglePrefs: bool = True,
40
                  useBasicKnowledge: bool = True, enforceChirality: bool = True,
41
                  useRandomCoords: bool = False, numZeroFail: int = 1,
42
                  pruneRmsThresh: float = -1.0, coordMap: dict = None,
43
                  forceTol: float = 0.001, ignoreSmoothingFailures: bool = False,
44
                  useSmallRingTorsions: bool = False, useMacrocycleTorsions: bool = False,
45
                  ETversion: int = 1, onlyHeavyAtomsForRMS: bool = False) -> int:
46
    """
47
    Generate a single 3D conformer using distance geometry.
48
    
49
    Parameters:
50
    - mol: Input molecule (modified in place)
51
    - maxAttempts: Maximum embedding attempts (default 10)
52
    - randomSeed: Random seed for reproducibility (default -1 for random)
53
    - clearConfs: Clear existing conformers (default True)
54
    - useExpTorsionAnglePrefs: Use experimental torsion preferences (default True)
55
    - useBasicKnowledge: Use basic chemical knowledge (default True)
56
    - enforceChirality: Enforce stereochemistry (default True)
57
    - useRandomCoords: Use random starting coordinates (default False)
58
    - numZeroFail: Number of zero-distance failures allowed (default 1)
59
    - pruneRmsThresh: RMS threshold for conformer pruning (default -1.0)
60
    - coordMap: Dictionary mapping atom indices to fixed coordinates
61
    - forceTol: Force tolerance for optimization (default 0.001)
62
    - ignoreSmoothingFailures: Ignore smoothing failures (default False)
63
    - useSmallRingTorsions: Use small ring torsion preferences (default False)
64
    - useMacrocycleTorsions: Use macrocycle torsion preferences (default False)
65
    - ETversion: Embedding algorithm version (default 1)
66
    - onlyHeavyAtomsForRMS: Only use heavy atoms for RMS calculations (default False)
67
    
68
    Returns:
69
    Conformer ID of generated conformer (-1 if failed)
70
    """
71

72
def EmbedMultipleConfs(mol: Mol, numConfs: int = 1, maxAttempts: int = 30,
73
                       pruneRmsThresh: float = 2.0, useExpTorsionAnglePrefs: bool = True,
74
                       useBasicKnowledge: bool = True, enforceChirality: bool = True,
75
                       numThreads: int = 1, randomSeed: int = -1, 
76
                       clearConfs: bool = True, **kwargs) -> list:
77
    """
78
    Generate multiple 3D conformers using distance geometry.
79
    
80
    Parameters:
81
    - mol: Input molecule (modified in place)
82
    - numConfs: Number of conformers to generate (default 1)
83
    - maxAttempts: Maximum attempts per conformer (default 30)
84
    - pruneRmsThresh: RMS threshold for duplicate removal (default 2.0)
85
    - useExpTorsionAnglePrefs: Use experimental torsion preferences (default True)
86
    - useBasicKnowledge: Use basic chemical knowledge (default True)
87
    - enforceChirality: Enforce stereochemistry (default True)
88
    - numThreads: Number of parallel threads (default 1)
89
    - randomSeed: Random seed for reproducibility (default -1)
90
    - clearConfs: Clear existing conformers (default True)
91
    
92
    Returns:
93
    List of conformer IDs generated
94
    """
95
```
96

97
### Conformer Optimization
98

99
Optimize 3D conformers using molecular mechanics force fields.
100

101
```python { .api }
102
def MMFFOptimizeMolecule(mol: Mol, confId: int = -1, maxIters: int = 200,
103
                         nonBondedThresh: float = 100.0, ignoreInterfragInteractions: bool = True) -> int:
104
    """
105
    Optimize a conformer using the MMFF force field.
106
    
107
    Parameters:
108
    - mol: Input molecule with conformer
109
    - confId: Conformer ID to optimize (default -1 for default conformer)
110
    - maxIters: Maximum optimization iterations (default 200)
111
    - nonBondedThresh: Non-bonded interaction threshold (default 100.0)
112
    - ignoreInterfragInteractions: Ignore inter-fragment interactions (default True)
113
    
114
    Returns:
115
    0 if successful, 1 if not converged, -1 if failed
116
    """
117

118
def UFFOptimizeMolecule(mol: Mol, confId: int = -1, maxIters: int = 200,
119
                        vdwThresh: float = 10.0, confTol: float = 1e-4,
120
                        energyTol: float = 1e-6, ignoreInterfragInteractions: bool = True) -> int:
121
    """
122
    Optimize a conformer using the UFF force field.
123
    
124
    Parameters:
125
    - mol: Input molecule with conformer
126
    - confId: Conformer ID to optimize (default -1 for default conformer)
127
    - maxIters: Maximum optimization iterations (default 200)
128
    - vdwThresh: Van der Waals threshold (default 10.0)
129
    - confTol: Conformer tolerance (default 1e-4)
130
    - energyTol: Energy tolerance (default 1e-6)
131
    - ignoreInterfragInteractions: Ignore inter-fragment interactions (default True)
132
    
133
    Returns:
134
    0 if successful, 1 if not converged, -1 if failed
135
    """
136
```
137

138
### 3D Descriptor Calculations
139

140
Calculate 3D molecular descriptors that depend on three-dimensional structure.
141

142
```python { .api }
143
def CalcMolDescriptors3D(mol: Mol, confId: int = -1, force: bool = True) -> dict:
144
    """
145
    Calculate all available 3D molecular descriptors.
146
    
147
    Parameters:
148
    - mol: Input molecule with 3D coordinates
149
    - confId: Conformer ID to use (default -1 for default conformer)
150
    - force: Force calculation even if descriptors exist (default True)
151
    
152
    Returns:
153
    Dictionary mapping 3D descriptor names to values
154
    """
155

156
def PMI1(mol: Mol, confId: int = -1, force: bool = True) -> float:
157
    """
158
    Calculate first principal moment of inertia.
159
    
160
    Parameters:
161
    - mol: Input molecule with 3D coordinates
162
    - confId: Conformer ID to use (default -1)
163
    - force: Force calculation (default True)
164
    
165
    Returns:
166
    PMI1 value
167
    """
168

169
def PMI2(mol: Mol, confId: int = -1, force: bool = True) -> float:
170
    """
171
    Calculate second principal moment of inertia.
172
    
173
    Parameters:
174
    - mol: Input molecule with 3D coordinates
175
    - confId: Conformer ID to use (default -1)
176
    - force: Force calculation (default True)
177
    
178
    Returns:
179
    PMI2 value
180
    """
181

182
def PMI3(mol: Mol, confId: int = -1, force: bool = True) -> float:
183
    """
184
    Calculate third principal moment of inertia.
185
    
186
    Parameters:
187
    - mol: Input molecule with 3D coordinates
188
    - confId: Conformer ID to use (default -1)
189
    - force: Force calculation (default True)
190
    
191
    Returns:
192
    PMI3 value
193
    """
194

195
def InertialShapeFactor(mol: Mol, confId: int = -1, force: bool = True) -> float:
196
    """
197
    Calculate inertial shape factor.
198
    
199
    Parameters:
200
    - mol: Input molecule with 3D coordinates
201
    - confId: Conformer ID to use (default -1)
202
    - force: Force calculation (default True)
203
    
204
    Returns:
205
    Inertial shape factor value
206
    """
207

208
def Eccentricity(mol: Mol, confId: int = -1, force: bool = True) -> float:
209
    """
210
    Calculate molecular eccentricity.
211
    
212
    Parameters:
213
    - mol: Input molecule with 3D coordinates
214
    - confId: Conformer ID to use (default -1)
215
    - force: Force calculation (default True)
216
    
217
    Returns:
218
    Eccentricity value
219
    """
220

221
def SpherocityIndex(mol: Mol, confId: int = -1, force: bool = True) -> float:
222
    """
223
    Calculate spherocity index.
224
    
225
    Parameters:
226
    - mol: Input molecule with 3D coordinates
227
    - confId: Conformer ID to use (default -1)
228
    - force: Force calculation (default True)
229
    
230
    Returns:
231
    Spherocity index value
232
    """
233
```
234

235
### Conformer Analysis
236

237
Functions for analyzing and comparing molecular conformations.
238

239
```python { .api }
240
def GetConformerRMS(mol: Mol, confId1: int, confId2: int, 
241
                    atomIds: list = None, prealigned: bool = False) -> float:
242
    """
243
    Calculate RMS distance between two conformers.
244
    
245
    Parameters:
246
    - mol: Input molecule with multiple conformers
247
    - confId1: First conformer ID
248
    - confId2: Second conformer ID
249
    - atomIds: List of atom indices to include (default all)
250
    - prealigned: Whether conformers are already aligned (default False)
251
    
252
    Returns:
253
    RMS distance between conformers
254
    """
255

256
def AlignMol(prbMol: Mol, refMol: Mol, prbConfId: int = -1, 
257
             refConfId: int = -1, atomMap: list = None, 
258
             weights: list = None, reflect: bool = False, 
259
             maxIters: int = 50) -> float:
260
    """
261
    Align probe molecule to reference molecule.
262
    
263
    Parameters:
264
    - prbMol: Probe molecule to align
265
    - refMol: Reference molecule
266
    - prbConfId: Probe conformer ID (default -1)
267
    - refConfId: Reference conformer ID (default -1)
268
    - atomMap: List of (probe_idx, ref_idx) atom pairs
269
    - weights: List of weights for alignment atoms
270
    - reflect: Allow reflection during alignment (default False)
271
    - maxIters: Maximum alignment iterations (default 50)
272
    
273
    Returns:
274
    RMS distance after alignment
275
    """
276
```
277

278
## Usage Examples
279

280
### Basic 3D Structure Generation
281

282
```python
283
from rdkit import Chem
284
from rdkit.Chem import AllChem
285

286
# Generate 3D coordinates
287
mol = Chem.MolFromSmiles('CCCO')  # Propanol
288
confId = AllChem.EmbedMolecule(mol, randomSeed=42)
289

290
if confId >= 0:
291
    print("3D coordinates generated successfully")
292
    # Optimize the geometry
293
    result = AllChem.MMFFOptimizeMolecule(mol)
294
    if result == 0:
295
        print("Optimization converged")
296
    else:
297
        print(f"Optimization result: {result}")
298
else:
299
    print("Failed to generate 3D coordinates")
300
```
301

302
### Multiple Conformer Generation
303

304
```python
305
from rdkit import Chem
306
from rdkit.Chem import AllChem
307

308
# Generate multiple conformers
309
mol = Chem.MolFromSmiles('CCCCCCCC')  # Octane (flexible chain)
310
confIds = AllChem.EmbedMultipleConfs(mol, numConfs=10, randomSeed=42)
311

312
print(f"Generated {len(confIds)} conformers")
313

314
# Optimize all conformers
315
for confId in confIds:
316
    AllChem.MMFFOptimizeMolecule(mol, confId=confId)
317

318
print("All conformers optimized")
319
```
320

321
### 3D Descriptor Calculations
322

323
```python
324
from rdkit import Chem
325
from rdkit.Chem import AllChem, Descriptors3D
326

327
# Generate 3D structure
328
mol = Chem.MolFromSmiles('CCCO')
329
AllChem.EmbedMolecule(mol, randomSeed=42)
330
AllChem.MMFFOptimizeMolecule(mol)
331

332
# Calculate 3D descriptors
333
descriptors_3d = Descriptors3D.CalcMolDescriptors3D(mol)
334
print(f"Calculated {len(descriptors_3d)} 3D descriptors")
335

336
# Access specific 3D descriptors
337
pmi1 = Descriptors3D.PMI1(mol)
338
pmi2 = Descriptors3D.PMI2(mol)
339
pmi3 = Descriptors3D.PMI3(mol)
340
inertial_shape = Descriptors3D.InertialShapeFactor(mol)
341

342
print(f"PMI1: {pmi1:.3f}")
343
print(f"PMI2: {pmi2:.3f}")
344
print(f"PMI3: {pmi3:.3f}")
345
print(f"Inertial Shape Factor: {inertial_shape:.3f}")
346
```
347

348
### Conformer Comparison
349

350
```python
351
from rdkit import Chem
352
from rdkit.Chem import AllChem
353

354
# Generate two conformers
355
mol = Chem.MolFromSmiles('CCCCCCC')
356
confIds = AllChem.EmbedMultipleConfs(mol, numConfs=2, randomSeed=42)
357

358
# Optimize conformers
359
for confId in confIds:
360
    AllChem.MMFFOptimizeMolecule(mol, confId=confId)
361

362
# Calculate RMS difference between conformers
363
if len(confIds) >= 2:
364
    rms = AllChem.GetConformerRMS(mol, confIds[0], confIds[1])
365
    print(f"RMS between conformers: {rms:.3f} Ų")
366
```
367

368
### 2D Coordinate Generation for Visualization
369

370
```python
371
from rdkit import Chem
372
from rdkit.Chem import AllChem
373

374
# Generate 2D coordinates for drawing
375
mol = Chem.MolFromSmiles('CCO')
376
AllChem.Compute2DCoords(mol)
377

378
# Now the molecule has 2D coordinates suitable for drawing
379
print(f"Molecule has {mol.GetNumConformers()} conformer(s)")
380
```