# Omega TK

> Conformer generation and ensemble creation for small molecules and macrocycles

## Links
- [Full Documentation](https://docs.eyesopen.com/toolkits/python/omegatk/index.html)
- [Theory](https://docs.eyesopen.com/toolkits/python/omegatk/omegatheory.html)
- [Code Examples](https://docs.eyesopen.com/toolkits/python/omegatk/omegaexamples.html)
- [API Reference](https://docs.eyesopen.com/toolkits/python/omegatk/api.html)

## Core API - Function Quick Reference

### Conformer Generation - Main Classes

**OEOmega()**
  Use for: Standard conformer generation for drug-like molecules
  Example: `omega = OEOmega(); omega(mol)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenClasses/OEOmega.html

**OEOmega.Build(mol: OEMol) -> bool**
  Use for: Generate conformers for a single molecule
  Example: `success = omega.Build(mol)`
  Returns: True if conformers generated successfully

**OEOmega.operator()(mol: OEMol) -> int**
  Use for: Generate conformers and get return code
  Example: `returncode = omega(mol)`
  Returns: OEOmegaReturnCode value

**OEOmegaOptions()**
  Use for: Configure conformer generation parameters
  Example: `opts = OEOmegaOptions(); opts.SetMaxConfs(200)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenClasses/OEOmegaOptions.html

### Macrocycle Conformer Generation

**OEMacrocycleOmega()**
  Use for: Generate conformers for macrocyclic molecules
  Example: `macromega = OEMacrocycleOmega(); macromega(mol)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenClasses/OEMacrocycleOmega.html

**OEMacrocycleOmegaOptions()**
  Use for: Configure macrocycle conformer generation
  Example: `opts = OEMacrocycleOmegaOptions(); opts.SetMaxConfs(400)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenClasses/OEMacrocycleOmegaOptions.html

### Stereoisomer Enumeration

**OEFlipper(mol: OEMol, options: OEFlipperOptions, warts: bool = True) -> OEMol iterator**
  Use for: Enumerate stereoisomers from unspecified stereocenters
  Example: `for enantiomer in OEFlipper(mol, opts): process(enantiomer)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenFunctions/OEFlipper.html

**OEFlipperOptions()**
  Use for: Configure stereoisomer enumeration parameters
  Example: `opts = OEFlipperOptions(); opts.SetMaxCenters(4)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenClasses/OEFlipperOptions.html

### Torsion Driving

**OETorDriver()**
  Use for: Generate conformers by systematically driving torsions
  Example: `tordriver = OETorDriver(); tordriver(mol)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenClasses/OETorDriver.html

**OETorDriveOptions()**
  Use for: Configure torsion driving parameters
  Example: `opts = OETorDriveOptions(); opts.SetTorsionLibrary(OETorLibType_Original)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenClasses/OETorDriveOptions.html

### Fragment Library

**OEMakeFragLib()**
  Use for: Build custom fragment libraries for conformer generation
  Example: `fraglib = OEMakeFragLib(); fraglib.AddFragment(mol)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenClasses/OEMakeFragLib.html

**OEAddGlobalFragLib(fraglib: str) -> bool**
  Use for: Add a fragment library to global fragment database
  Example: `OEAddGlobalFragLib("custom_frags.oeb")`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenFunctions/OEAddGlobalFragLib.html

### Configuration Options

**OEOmegaOptions.SetMaxConfs(maxconfs: int)**
  Use for: Set maximum number of conformers to generate
  Example: `opts.SetMaxConfs(200)`
  Default: 200

**OEOmegaOptions.SetEnergyWindow(window: float)**
  Use for: Set energy window for conformer selection (kcal/mol)
  Example: `opts.SetEnergyWindow(10.0)`
  Default: 10.0 kcal/mol

**OEOmegaOptions.SetRMSThreshold(rms: float)**
  Use for: Set RMSD threshold for duplicate conformer removal
  Example: `opts.SetRMSThreshold(0.5)`
  Default: 0.8 Angstroms

**OEOmegaOptions.SetStrictStereo(strict: bool)**
  Use for: Control whether to preserve input stereochemistry
  Example: `opts.SetStrictStereo(True)`
  Default: True

**OEOmegaOptions.SetSampleHydrogens(sample: bool)**
  Use for: Enable/disable sampling of hydrogen positions
  Example: `opts.SetSampleHydrogens(True)`
  Default: False

**OEOmegaOptions.SetStrictAtomTypes(strict: bool)**
  Use for: Control strict atom typing for force field
  Example: `opts.SetStrictAtomTypes(False)`
  Default: True

### Sampling Modes

**OEOmegaOptions.SetSampling(sampling: int)**
  Use for: Set conformer sampling density
  Example: `opts.SetSampling(OEOmegaSampling_Dense)`
  Values: OEOmegaSampling_Fast, OEOmegaSampling_Dense, OEOmegaSampling_Pose
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenConstants/OEOmegaSampling.html

### Return Codes

**OEOmegaReturnCode constants**
  Use for: Interpret conformer generation results
  Values: OEOmegaReturnCode_Success, OEOmegaReturnCode_Failure, OEOmegaReturnCode_Timeout
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenConstants/OEOmegaReturnCode.html

### Utility Functions

**OEIsMacrocycle(mol: OEMol) -> bool**
  Use for: Detect if molecule is a macrocycle
  Example: `if OEIsMacrocycle(mol): use_macromega()`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenFunctions/OEIsMacrocycle.html

**OEGetOmegaError(returncode: int) -> str**
  Use for: Get error message from return code
  Example: `msg = OEGetOmegaError(returncode)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenFunctions/OEGetOmegaError.html

### GPU Support

**OEOmegaIsGPUReady() -> bool**
  Use for: Check if GPU acceleration is available
  Example: `if OEOmegaIsGPUReady(): opts.SetUseGPU(True)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenFunctions/OEOmegaIsGPUReady.html

**OEOmegaSystemHasGPU() -> bool**
  Use for: Check if system has compatible GPU hardware
  Example: `has_gpu = OEOmegaSystemHasGPU()`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenFunctions/OEOmegaSystemHasGPU.html

### Ensemble Slicing

**OESliceEnsemble(mol: OEMol, options: OESliceEnsembleOptions) -> bool**
  Use for: Reduce conformer ensemble to diverse subset
  Example: `OESliceEnsemble(mol, opts)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenFunctions/OESliceEnsemble.html

**OESliceEnsembleOptions()**
  Use for: Configure ensemble slicing parameters
  Example: `opts = OESliceEnsembleOptions(); opts.SetNumConfs(50)`
  See: https://docs.eyesopen.com/toolkits/python/omegatk/OEConfGenClasses/OESliceEnsembleOptions.html

## Common Patterns - Complete Working Examples

### Pattern: Basic Conformer Generation

```python
from openeye import oechem, oeomega

# Read input molecule
ifs = oechem.oemolistream("input.smi")
mol = oechem.OEMol()
oechem.OEReadMolecule(ifs, mol)

# Generate conformers with default settings
omega = oeomega.OEOmega()
omega.SetMaxConfs(200)
omega.SetEnergyWindow(10.0)
ret_code = omega(mol)

# Write conformers to output
ofs = oechem.oemolostream("conformers.oeb")
oechem.OEWriteMolecule(ofs, mol)
```
Use when: You need standard conformer generation for drug-like molecules with default parameters

### Pattern: Customized Conformer Generation

```python
from openeye import oechem, oeomega

# Setup custom options
opts = oeomega.OEOmegaOptions()
opts.SetMaxConfs(500)
opts.SetEnergyWindow(15.0)
opts.SetRMSThreshold(0.5)
opts.SetStrictStereo(True)
opts.SetSampleHydrogens(True)

# Create omega with custom options
omega = oeomega.OEOmega(opts)
mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "c1ccccc1CCO")
omega(mol)

# Process conformers
for conf in mol.GetConfs():
    energy = oechem.OEGetSDData(conf, "Energy")
```
Use when: You need fine control over conformer generation parameters, energy windows, or RMSD thresholds

### Pattern: Dense Sampling for Pose Prediction

```python
from openeye import oechem, oeomega

# Configure for dense sampling
opts = oeomega.OEOmegaOptions()
opts.SetSampling(oeomega.OEOmegaSampling_Dense)
opts.SetMaxConfs(1000)
opts.SetEnergyWindow(20.0)

# Generate dense conformer ensemble
omega = oeomega.OEOmega(opts)
mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "CC(C)Cc1ccc(cc1)C(C)C(O)=O")
omega.Build(mol)

# Output for docking
ofs = oechem.oemolostream("dense_conformers.oeb")
oechem.OEWriteMolecule(ofs, mol)
```
Use when: Preparing molecules for docking or pose prediction where comprehensive sampling is critical

### Pattern: Single Low-Energy Conformer

```python
from openeye import oechem, oeomega

# Configure for single conformer
opts = oeomega.OEOmegaOptions()
opts.SetMaxConfs(1)
opts.SetStrictStereo(True)

# Generate single conformer
omega = oeomega.OEOmega(opts)
mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "CCO")
omega(mol)

# Get 3D coordinates
for atom in mol.GetAtoms():
    coords = mol.GetCoords(atom)
```
Use when: You only need a single reasonable 3D structure for visualization or simple calculations

### Pattern: Macrocycle Conformer Generation

```python
from openeye import oechem, oeomega

# Read macrocycle
mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "C1CCCCCCCCCCC1")

# Check if macrocycle and use appropriate method
if oeomega.OEIsMacrocycle(mol):
    opts = oeomega.OEMacrocycleOmegaOptions()
    opts.SetMaxConfs(400)
    macromega = oeomega.OEMacrocycleOmega(opts)
    macromega(mol)
else:
    omega = oeomega.OEOmega()
    omega(mol)

# Write output
ofs = oechem.oemolostream("macro_conformers.oeb")
oechem.OEWriteMolecule(ofs, mol)
```
Use when: Working with macrocyclic molecules (rings with 12+ atoms) that require specialized sampling

### Pattern: Stereoisomer Enumeration

```python
from openeye import oechem, oeomega

# Read molecule with unspecified stereocenters
mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "CC(O)C(O)C")

# Configure flipper options
flipper_opts = oeomega.OEFlipperOptions()
flipper_opts.SetMaxCenters(4)
flipper_opts.SetEnumNitrogen(True)

# Enumerate stereoisomers
ofs = oechem.oemolostream("stereoisomers.oeb")
for enantiomer in oeomega.OEFlipper(mol, flipper_opts):
    omega = oeomega.OEOmega()
    omega(enantiomer)
    oechem.OEWriteMolecule(ofs, enantiomer)
```
Use when: Input molecules have unspecified stereochemistry and you need all possible stereoisomers

### Pattern: Torsion-Driven Conformer Generation

```python
from openeye import oechem, oeomega

# Setup torsion driving
opts = oeomega.OETorDriveOptions()
opts.SetTorsionLibrary(oeomega.OETorLibType_Original)

# Generate conformers by driving torsions
tordriver = oeomega.OETorDriver(opts)
mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "c1ccccc1CCCC")
tordriver(mol)

# Process torsion-driven ensemble
for conf in mol.GetConfs():
    rmsd = oechem.OERMSD(mol.GetActive(), conf)
```
Use when: You need systematic torsion angle sampling rather than stochastic conformer generation

### Pattern: Custom Fragment Library

```python
from openeye import oechem, oeomega

# Create fragment library from molecules
fraglib = oeomega.OEMakeFragLib()
ifs = oechem.oemolistream("fragments.smi")
for frag in ifs.GetOEMols():
    fraglib.AddFragment(frag)

# Save fragment library
fraglib.Write("custom_frags.oeb")

# Use custom fragment library
oeomega.OEAddGlobalFragLib("custom_frags.oeb")
omega = oeomega.OEOmega()
mol = oechem.OEMol()
omega(mol)
```
Use when: Default fragment library doesn't cover your chemical space or you want custom ring conformations

### Pattern: Batch Processing with Error Handling

```python
from openeye import oechem, oeomega

# Setup omega
omega = oeomega.OEOmega()
omega.SetMaxConfs(200)

# Process multiple molecules
ifs = oechem.oemolistream("input.smi")
ofs = oechem.oemolostream("output.oeb")
for mol in ifs.GetOEMols():
    ret_code = omega(mol)
    if ret_code == oeomega.OEOmegaReturnCode_Success:
        oechem.OEWriteMolecule(ofs, mol)
    else:
        error_msg = oeomega.OEGetOmegaError(ret_code)
        oechem.OEThrow.Warning(f"Failed: {mol.GetTitle()} - {error_msg}")
```
Use when: Processing large datasets where some molecules may fail and you need robust error handling

### Pattern: GPU-Accelerated Generation

```python
from openeye import oechem, oeomega

# Check GPU availability
if oeomega.OEOmegaIsGPUReady():
    opts = oeomega.OEOmegaOptions()
    opts.SetUseGPU(True)
    omega = oeomega.OEOmega(opts)
else:
    omega = oeomega.OEOmega()

# Generate conformers (GPU if available)
mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "c1ccccc1")
omega(mol)

# Process results
print(f"Generated {mol.NumConfs()} conformers")
```
Use when: Processing large datasets and GPU hardware is available for acceleration

### Pattern: Ensemble Reduction/Slicing

```python
from openeye import oechem, oeomega

# Generate large ensemble
omega = oeomega.OEOmega()
omega.SetMaxConfs(1000)
mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "c1ccccc1CCCC")
omega(mol)

# Reduce to diverse subset
slice_opts = oeomega.OESliceEnsembleOptions()
slice_opts.SetNumConfs(50)
slice_opts.SetRMSRange(0.5, 2.0)
oeomega.OESliceEnsemble(mol, slice_opts)

# Write reduced ensemble
ofs = oechem.oemolostream("sliced.oeb")
oechem.OEWriteMolecule(ofs, mol)
```
Use when: You have a large conformer ensemble and need to reduce it to a diverse, manageable subset

### Pattern: Preserving Input Stereochemistry

```python
from openeye import oechem, oeomega

# Read molecule with defined stereochemistry
mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "C[C@H](O)[C@@H](C)O")

# Configure to preserve stereochemistry
opts = oeomega.OEOmegaOptions()
opts.SetStrictStereo(True)
opts.SetMaxConfs(200)

# Generate conformers preserving stereo
omega = oeomega.OEOmega(opts)
omega(mol)

# Verify stereochemistry preserved
for conf in mol.GetConfs():
    assert oechem.OEHasAbsoluteStereo(conf)
```
Use when: Input molecules have defined stereochemistry that must be preserved in all conformers

## API Decision Guide

- **For drug-like molecules (<12 ring atoms)**: use `OEOmega` (standard conformer generation)
- **For macrocycles (≥12 ring atoms)**: use `OEMacrocycleOmega` (specialized macrocycle sampling)
- **For molecules with unspecified stereocenters**: use `OEFlipper` before conformer generation
- **For systematic torsion sampling**: use `OETorDriver` (deterministic vs stochastic)
- **For docking/pose prediction**: use `OEOmegaSampling_Dense` or `OEOmegaSampling_Pose`
- **For quick 3D structure**: use `SetMaxConfs(1)` with default settings
- **For comprehensive sampling**: use `OEOmegaSampling_Dense` with `SetMaxConfs(1000+)`
- **For custom chemical space**: create custom fragment library with `OEMakeFragLib`
- **For large datasets**: enable GPU with `SetUseGPU(True)` if `OEOmegaIsGPUReady()`
- **For reducing ensemble size**: use `OESliceEnsemble` after generation
- **OEOmega vs OEMacrocycleOmega**: use OEOmega for standard molecules, OEMacrocycleOmega when `OEIsMacrocycle()` returns True
- **Build() vs operator()**: use `Build()` for bool return, use `operator()` for detailed return code
- **SetStrictStereo(True) vs False**: use True to preserve input stereochemistry, False to allow inversion
- **SetSampleHydrogens(True) vs False**: use True for accurate hydrogen positions (slower), False for speed

## Common Parameters & Types

**OEOmegaOptions**: Configuration object for conformer generation
  - Create with: `opts = oeomega.OEOmegaOptions()`
  - Common in: OEOmega constructor, all conformer generation workflows
  - Key methods: SetMaxConfs(), SetEnergyWindow(), SetRMSThreshold(), SetSampling()
  - Gotcha: Changes to options after OEOmega construction don't affect existing instance

**OEMacrocycleOmegaOptions**: Configuration for macrocycle conformer generation
  - Create with: `opts = oeomega.OEMacrocycleOmegaOptions()`
  - Common in: OEMacrocycleOmega constructor
  - Key difference: Higher default maxconfs (400 vs 200) for macrocycles
  - Gotcha: Use only with macrocycles; check with OEIsMacrocycle() first

**OEFlipperOptions**: Configuration for stereoisomer enumeration
  - Create with: `opts = oeomega.OEFlipperOptions()`
  - Common in: OEFlipper() function
  - Key methods: SetMaxCenters(), SetEnumNitrogen(), SetEnumRingAtoms()
  - Gotcha: Can generate large numbers of stereoisomers; set MaxCenters to limit

**OETorDriveOptions**: Configuration for torsion-driven conformer generation
  - Create with: `opts = oeomega.OETorDriveOptions()`
  - Common in: OETorDriver constructor
  - Key methods: SetTorsionLibrary(), SetForceField()
  - Typical values: OETorLibType_Original, OETorLibType_GubaV21

**OESliceEnsembleOptions**: Configuration for ensemble reduction
  - Create with: `opts = oeomega.OESliceEnsembleOptions()`
  - Common in: OESliceEnsemble() function
  - Key methods: SetNumConfs(), SetRMSRange()
  - Gotcha: RMS range affects diversity; smaller range = more similar conformers

**OEOmegaSampling constants**: Predefined sampling density levels
  - Values: OEOmegaSampling_Fast, OEOmegaSampling_Dense, OEOmegaSampling_Pose
  - Common in: OEOmegaOptions.SetSampling()
  - Fast: Quick, fewer conformers; Dense: Thorough sampling; Pose: Optimized for docking
  - Gotcha: Dense and Pose modes significantly increase generation time

**OEOmegaReturnCode constants**: Status codes from conformer generation
  - Values: OEOmegaReturnCode_Success, OEOmegaReturnCode_Failure, OEOmegaReturnCode_Timeout
  - Common in: Return value from omega() and Build() methods
  - Use with: OEGetOmegaError() to get human-readable error messages
  - Gotcha: Success doesn't guarantee conformers were generated, check mol.NumConfs()

**maxconfs (int)**: Maximum number of conformers to generate
  - Typical values: 1 (single structure), 200 (default), 500-1000 (dense sampling)
  - Common in: SetMaxConfs() method
  - Gotcha: Actual number generated may be less due to energy window and RMSD filtering

## Return Types & Error Handling

```python
# Pattern 1: Boolean return from Build()
omega = oeomega.OEOmega()
mol = oechem.OEMol()
if omega.Build(mol):
    # Success - conformers in mol
    print(f"Generated {mol.NumConfs()} conformers")
else:
    # Failure - check why
    oechem.OEThrow.Warning(f"Failed to generate conformers for {mol.GetTitle()}")

# Pattern 2: Return code from operator() with detailed error handling
omega = oeomega.OEOmega()
mol = oechem.OEMol()
ret_code = omega(mol)
if ret_code == oeomega.OEOmegaReturnCode_Success:
    # Process conformers
    for conf in mol.GetConfs():
        process_conformer(conf)
elif ret_code == oeomega.OEOmegaReturnCode_Timeout:
    error_msg = oeomega.OEGetOmegaError(ret_code)
    oechem.OEThrow.Warning(f"Timeout: {error_msg}")
else:
    error_msg = oeomega.OEGetOmegaError(ret_code)
    oechem.OEThrow.Error(f"Failed: {error_msg}")

# Pattern 3: Iterator return from OEFlipper
flipper_opts = oeomega.OEFlipperOptions()
mol = oechem.OEMol()
stereoisomer_count = 0
for enantiomer in oeomega.OEFlipper(mol, flipper_opts):
    # Each iteration yields a new stereoisomer
    omega = oeomega.OEOmega()
    omega(enantiomer)
    stereoisomer_count += 1
print(f"Generated {stereoisomer_count} stereoisomers")

# Pattern 4: Checking conformer count after generation
omega = oeomega.OEOmega()
mol = oechem.OEMol()
omega(mol)
if mol.NumConfs() == 0:
    # Generation succeeded but no conformers passed filters
    oechem.OEThrow.Warning("No conformers within energy/RMSD criteria")
else:
    # Process conformers
    for conf in mol.GetConfs():
        energy = oechem.OEGetSDData(conf, "Energy")