# Eon TK

> Electrostatic and shape-based molecular overlay toolkit for comparing molecules based on 3D electrostatic properties

## Links
- [Full Documentation](https://docs.eyesopen.com/toolkits/python/eontk/index.html)
- [Theory](https://docs.eyesopen.com/toolkits/python/eontk/theory/eon_theory.html)
- [Code Examples](https://docs.eyesopen.com/toolkits/python/eontk/examples.html)
- [API Reference](https://docs.eyesopen.com/toolkits/python/eontk/api.html)

## Core API - Function Quick Reference

### Overlay and Scoring Functions

**OEEonOverlay(refmol: OEMolBase, fitmol: OEMolBase) -> OEEonOverlayResults**
  Use for: Performing electrostatic overlay between reference and fit molecules
  Example: `results = OEEonOverlay(refmol, fitmol)`
  See: [OEEonOverlay](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonOverlay.html)

**OEEonPBOverlay(refmol: OEMolBase, fitmol: OEMolBase, options: OEEonPBOptions) -> OEEonPBResults**
  Use for: Performing Poisson-Boltzmann electrostatic overlay with solvent effects
  Example: `results = OEEonPBOverlay(refmol, fitmol, pboptions)`
  See: [OEEonPBOverlay](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonPBOverlay.html)

**OEEonOverlapFunc(refmol: OEMolBase) -> OEEonOverlapFunc**
  Use for: Creating a function object to calculate electrostatic overlap scores
  Example: `overlapfunc = OEEonOverlapFunc(refmol)`
  See: [OEEonOverlapFunc](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonOverlapFunc.html)

**OEEonPBFunc(refmol: OEMolBase, options: OEEonPBOptions) -> OEEonPBFunc**
  Use for: Creating a function object for PB-based electrostatic calculations
  Example: `pbfunc = OEEonPBFunc(refmol, pboptions)`
  See: [OEEonPBFunc](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonPBFunc.html)

### Charge Calculation Functions

**OEExactChargeFunc(mol: OEMolBase) -> OEExactChargeFunc**
  Use for: Creating exact charge calculation function (slower but more accurate)
  Example: `chargefunc = OEExactChargeFunc(mol)`
  See: [OEExactChargeFunc](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEExactChargeFunc.html)

**OEGridChargeFunc(mol: OEMolBase) -> OEGridChargeFunc**
  Use for: Creating grid-based charge calculation function (faster approximation)
  Example: `chargefunc = OEGridChargeFunc(mol)`
  See: [OEGridChargeFunc](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEGridChargeFunc.html)

### Hitlist Building Functions

**OEEonHitlistBuilder(refmol: OEMolBase, options: OEEonHitlistOptions) -> OEEonHitlistBuilder**
  Use for: Building ranked hitlists from multiple overlay results
  Example: `hitlist = OEEonHitlistBuilder(refmol, options)`
  See: [OEEonHitlistBuilder](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonHitlistBuilder.html)

**OEHighestShapeTanimoto() -> OEHighestShapeTanimoto**
  Use for: Sorting hits by shape Tanimoto score (highest first)
  Example: `sorter = OEHighestShapeTanimoto()`
  See: [OEHighestShapeTanimoto](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEHighestShapeTanimoto.html)

**OEHighestChargeTanimoto() -> OEHighestChargeTanimoto**
  Use for: Sorting hits by electrostatic Tanimoto score (highest first)
  Example: `sorter = OEHighestChargeTanimoto()`
  See: [OEHighestChargeTanimoto](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEHighestChargeTanimoto.html)

**OEHighestShapeChargeTanimotoCombo() -> OEHighestShapeChargeTanimotoCombo**
  Use for: Sorting hits by combined shape and charge Tanimoto score
  Example: `sorter = OEHighestShapeChargeTanimotoCombo()`
  See: [OEHighestShapeChargeTanimotoCombo](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEHighestShapeChargeTanimotoCombo.html)

### Configuration Classes

**OEEonHitlistOptions() -> OEEonHitlistOptions**
  Use for: Configuring hitlist building parameters (max hits, cutoffs, etc.)
  Example: `options = OEEonHitlistOptions(); options.SetMaxHits(100)`
  See: [OEEonHitlistOptions](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonHitlistOptions.html)

**OEEonPBOptions() -> OEEonPBOptions**
  Use for: Configuring Poisson-Boltzmann calculation parameters
  Example: `pboptions = OEEonPBOptions(); pboptions.SetInnerDielectric(1.0)`
  See: [OEEonPBOptions](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonPBOptions.html)

### Result Access Classes

**OEEonOverlayResults**
  Use for: Accessing results from OEEonOverlay (scores, aligned molecules)
  Methods: GetShapeTanimoto(), GetChargeTanimoto(), GetOverlayConf()
  See: [OEEonOverlayResults](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonOverlayResults.html)

**OEEonPBResults**
  Use for: Accessing results from OEEonPBOverlay (PB scores, aligned molecules)
  Methods: GetPBTanimoto(), GetOverlayConf()
  See: [OEEonPBResults](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonPBResults.html)

**OEEonOverlapScore**
  Use for: Accessing detailed overlap scores from OEEonOverlapFunc
  Methods: GetShapeTanimoto(), GetChargeTanimoto(), GetComboTanimoto()
  See: [OEEonOverlapScore](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonOverlapScore.html)

**OEEonHit**
  Use for: Accessing individual hit information from hitlist
  Methods: GetMol(), GetShapeTanimoto(), GetChargeTanimoto()
  See: [OEEonHit](https://docs.eyesopen.com/toolkits/python/eontk/OEEonClasses/OEEonHit.html)

### Licensing Functions

**OEEtIsLicensed() -> bool**
  Use for: Checking if Eon TK is properly licensed
  Example: `if not OEEtIsLicensed(): raise Exception("No license")`
  See: [OEEtIsLicensed](https://docs.eyesopen.com/toolkits/python/eontk/OEEonFunctions/OEEtIsLicensed.html)

**OEEtGetVersion() -> str**
  Use for: Getting the Eon TK version string
  Example: `version = OEEtGetVersion()`
  See: [OEEtGetVersion](https://docs.eyesopen.com/toolkits/python/eontk/OEEonFunctions/OEEtGetVersion.html)

## Common Patterns - Complete Working Examples

### Pattern: Basic Electrostatic Overlay

```python
from openeye import oechem, oeeon

# Read reference and fit molecules
refmol = oechem.OEMol()
fitmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), refmol)
oechem.OEReadMolecule(oechem.oemolistream("fit.sdf"), fitmol)

# Perform overlay
results = oeeon.OEEonOverlay(refmol, fitmol)

# Get scores and aligned molecule
shape_tanimoto = results.GetShapeTanimoto()
charge_tanimoto = results.GetChargeTanimoto()
aligned_mol = results.GetOverlayConf()
oechem.OEWriteMolecule(oechem.oemolostream("aligned.sdf"), aligned_mol)
```
Use when: You need basic electrostatic overlay without solvent effects

### Pattern: Poisson-Boltzmann Overlay with Solvent

```python
from openeye import oechem, oeeon

# Read molecules
refmol = oechem.OEMol()
fitmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), refmol)
oechem.OEReadMolecule(oechem.oemolistream("fit.sdf"), fitmol)

# Configure PB options
pboptions = oeeon.OEEonPBOptions()
pboptions.SetInnerDielectric(1.0)
pboptions.SetOuterDielectric(80.0)

# Perform PB overlay
results = oeeon.OEEonPBOverlay(refmol, fitmol, pboptions)
pb_tanimoto = results.GetPBTanimoto()
aligned_mol = results.GetOverlayConf()
```
Use when: You need to account for solvent effects in electrostatic comparison

### Pattern: Computing Overlap Score Without Overlay

```python
from openeye import oechem, oeeon

# Read pre-aligned molecules
refmol = oechem.OEMol()
fitmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), refmol)
oechem.OEReadMolecule(oechem.oemolistream("fit.sdf"), fitmol)

# Create overlap function and calculate score
overlapfunc = oeeon.OEEonOverlapFunc(refmol)
score = oeeon.OEEonOverlapScore()
overlapfunc.Overlap(fitmol, score)

# Access individual scores
shape_score = score.GetShapeTanimoto()
charge_score = score.GetChargeTanimoto()
combo_score = score.GetComboTanimoto()
```
Use when: Molecules are already aligned and you only need overlap scores

### Pattern: Building a Ranked Hitlist

```python
from openeye import oechem, oeeon

# Read reference molecule
refmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), refmol)

# Configure hitlist options
options = oeeon.OEEonHitlistOptions()
options.SetMaxHits(100)
options.SetMinShapeTanimoto(0.5)

# Create hitlist builder
hitlist = oeeon.OEEonHitlistBuilder(refmol, options)

# Process database molecules
for fitmol in oechem.oemolistream("database.sdf").GetOEMols():
    hitlist.AddMol(fitmol)

# Get sorted hits
for hit in hitlist.GetHits(oeeon.OEHighestShapeChargeTanimotoCombo()):
    print(f"Shape: {hit.GetShapeTanimoto():.3f}, Charge: {hit.GetChargeTanimoto():.3f}")
```
Use when: Screening a database and need top-ranked hits by combined score

### Pattern: Using Exact vs Grid Charge Functions

```python
from openeye import oechem, oeeon

# Read molecule
mol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("mol.sdf"), mol)

# Exact charge calculation (slower, more accurate)
exact_func = oeeon.OEExactChargeFunc(mol)

# Grid-based charge calculation (faster, approximate)
grid_func = oeeon.OEGridChargeFunc(mol)

# Use in overlay
refmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), refmol)
results = oeeon.OEEonOverlay(refmol, mol)
```
Use when: You need to balance speed vs accuracy in charge calculations

### Pattern: Filtering Hits by Multiple Criteria

```python
from openeye import oechem, oeeon

refmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), refmol)

# Set multiple cutoff criteria
options = oeeon.OEEonHitlistOptions()
options.SetMaxHits(50)
options.SetMinShapeTanimoto(0.6)
options.SetMinChargeTanimoto(0.5)
options.SetMinComboTanimoto(0.7)

hitlist = oeeon.OEEonHitlistBuilder(refmol, options)

for fitmol in oechem.oemolistream("database.sdf").GetOEMols():
    hitlist.AddMol(fitmol)

# Only hits meeting all criteria are returned
for hit in hitlist.GetHits():
    mol = hit.GetMol()
    oechem.OEWriteMolecule(oechem.oemolostream("hits.sdf"), mol)
```
Use when: You need to apply multiple score thresholds simultaneously

### Pattern: Batch Processing with Progress Tracking

```python
from openeye import oechem, oeeon

refmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), refmol)

overlapfunc = oeeon.OEEonOverlapFunc(refmol)
score = oeeon.OEEonOverlapScore()

ifs = oechem.oemolistream("database.sdf")
ofs = oechem.oemolostream("results.sdf")

count = 0
for fitmol in ifs.GetOEMols():
    overlapfunc.Overlap(fitmol, score)
    oechem.OESetSDData(fitmol, "ShapeTanimoto", str(score.GetShapeTanimoto()))
    oechem.OESetSDData(fitmol, "ChargeTanimoto", str(score.GetChargeTanimoto()))
    oechem.OEWriteMolecule(ofs, fitmol)
    count += 1
    if count % 100 == 0:
        print(f"Processed {count} molecules")
```
Use when: Processing large databases and need to track progress

### Pattern: Customizing PB Calculation Parameters

```python
from openeye import oechem, oeeon

refmol = oechem.OEMol()
fitmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), refmol)
oechem.OEReadMolecule(oechem.oemolistream("fit.sdf"), fitmol)

# Customize PB parameters for specific conditions
pboptions = oeeon.OEEonPBOptions()
pboptions.SetInnerDielectric(1.0)    # Protein interior
pboptions.SetOuterDielectric(80.0)   # Water
pboptions.SetSaltConcentration(0.15) # Physiological salt

# Perform overlay with custom parameters
results = oeeon.OEEonPBOverlay(refmol, fitmol, pboptions)
pb_score = results.GetPBTanimoto()
aligned = results.GetOverlayConf()
```
Use when: You need to model specific solvent or ionic conditions

### Pattern: Comparing Multiple Conformers

```python
from openeye import oechem, oeeon, oeomega

# Generate conformers for fit molecule
fitmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("fit.sdf"), fitmol)
omega = oeomega.OEOmega()
omega.Build(fitmol)

# Read reference
refmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), refmol)

# Find best conformer overlay
best_score = 0.0
best_conf = None
for conf in fitmol.GetConfs():
    results = oeeon.OEEonOverlay(refmol, conf)
    combo = results.GetShapeTanimoto() + results.GetChargeTanimoto()
    if combo > best_score:
        best_score = combo
        best_conf = results.GetOverlayConf()

oechem.OEWriteMolecule(oechem.oemolostream("best.sdf"), best_conf)
```
Use when: You need to find the best conformer match from multiple conformations

### Pattern: Sorting Hits by Different Criteria

```python
from openeye import oechem, oeeon

refmol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), refmol)

options = oeeon.OEEonHitlistOptions()
options.SetMaxHits(100)
hitlist = oeeon.OEEonHitlistBuilder(refmol, options)

for fitmol in oechem.oemolistream("database.sdf").GetOEMols():
    hitlist.AddMol(fitmol)

# Get hits sorted by shape only
print("Top by shape:")
for hit in hitlist.GetHits(oeeon.OEHighestShapeTanimoto()):
    print(f"  Shape: {hit.GetShapeTanimoto():.3f}")

# Get hits sorted by charge only
print("Top by charge:")
for hit in hitlist.GetHits(oeeon.OEHighestChargeTanimoto()):
    print(f"  Charge: {hit.GetChargeTanimoto():.3f}")
```
Use when: You want to examine hits ranked by different scoring criteria

## API Decision Guide

- **For basic electrostatic overlay**: use `OEEonOverlay()` (fast, no solvent effects)
- **For overlay with solvent effects**: use `OEEonPBOverlay()` (slower, includes solvation)
- **For scoring pre-aligned molecules**: use `OEEonOverlapFunc()` (no optimization, just scoring)
- **For building ranked hitlists**: use `OEEonHitlistBuilder()` (handles multiple molecules, sorting, filtering)

- **OEExactChargeFunc vs OEGridChargeFunc**: use Exact for highest accuracy, use Grid for speed with large databases

- **Sorting hitlists**:
  - Use `OEHighestShapeTanimoto()` when shape similarity is most important
  - Use `OEHighestChargeTanimoto()` when electrostatic similarity is most important
  - Use `OEHighestShapeChargeTanimotoCombo()` for balanced shape+charge ranking

- **Setting cutoffs**: use `OEEonHitlistOptions.SetMinShapeTanimoto()`, `SetMinChargeTanimoto()`, or `SetMinComboTanimoto()` to filter hits by score thresholds

- **PB calculations**: use `OEEonPBOptions` to set dielectric constants (`SetInnerDielectric()`, `SetOuterDielectric()`) and salt concentration (`SetSaltConcentration()`)

## Common Parameters & Types

**OEMolBase**: Molecule object from OEChem
  - Create with: `mol = oechem.OEMol()` then `oechem.OEReadMolecule(ifs, mol)`
  - Common in: All overlay and scoring functions as reference or fit molecule
  - Gotcha: Must have 3D coordinates and partial charges assigned

**OEEonHitlistOptions**: Configuration for hitlist building
  - Create with: `options = oeeon.OEEonHitlistOptions()`
  - Common in: `OEEonHitlistBuilder()` constructor
  - Key methods: `SetMaxHits()`, `SetMinShapeTanimoto()`, `SetMinChargeTanimoto()`, `SetMinComboTanimoto()`
  - Typical values: MaxHits=100-1000, MinTanimoto=0.5-0.8

**OEEonPBOptions**: Configuration for Poisson-Boltzmann calculations
  - Create with: `pboptions = oeeon.OEEonPBOptions()`
  - Common in: `OEEonPBOverlay()` and `OEEonPBFunc()`
  - Key methods: `SetInnerDielectric()` (typically 1.0-4.0), `SetOuterDielectric()` (typically 80.0 for water), `SetSaltConcentration()` (typically 0.0-0.15 M)

**OEEonOverlayResults**: Results from overlay operation
  - Create with: Returned by `OEEonOverlay()`
  - Access scores: `GetShapeTanimoto()`, `GetChargeTanimoto()`
  - Access aligned molecule: `GetOverlayConf()`
  - Gotcha: The aligned molecule is a new conformer, not a reference to the input

**OEEonPBResults**: Results from PB overlay operation
  - Create with: Returned by `OEEonPBOverlay()`
  - Access score: `GetPBTanimoto()`
  - Access aligned molecule: `GetOverlayConf()`

**OEEonOverlapScore**: Detailed overlap scores
  - Create with: `score = oeeon.OEEonOverlapScore()`
  - Populated by: `OEEonOverlapFunc.Overlap(mol, score)`
  - Access scores: `GetShapeTanimoto()`, `GetChargeTanimoto()`, `GetComboTanimoto()`

**OEEonHit**: Individual hit from hitlist
  - Create with: Returned by iterating `OEEonHitlistBuilder.GetHits()`
  - Access molecule: `GetMol()`
  - Access scores: `GetShapeTanimoto()`, `GetChargeTanimoto()`

## Return Types & Error Handling

```python
# Pattern 1: Overlay functions return result objects
results = oeeon.OEEonOverlay(refmol, fitmol)
if results is not None:
    shape_score = results.GetShapeTanimoto()
    charge_score = results.GetChargeTanimoto()
    aligned_mol = results.GetOverlayConf()
else:
    print("Overlay failed")

# Pattern 2: Overlap scoring modifies score object in-place
score = oeeon.OEEonOverlapScore()
overlapfunc = oeeon.OEEonOverlapFunc(refmol)
success = overlapfunc.Overlap(fitmol, score)
if success:
    combo_score = score.GetComboTanimoto()

# Pattern 3: Hitlist iteration returns hit objects
hitlist = oeeon.OEEonHitlistBuilder(refmol, options)
for fitmol in database:
    hitlist.AddMol(fitmol)

for hit in hitlist.GetHits(oeeon.OEHighestShapeChargeTanimotoCombo()):
    mol = hit.GetMol()
    shape = hit.GetShapeTanimoto()
    charge = hit.GetChargeTanimoto()

# Pattern 4: License checking
if not oeeon.OEEtIsLicensed():
    raise RuntimeError("Eon TK is not licensed")

# Pattern 5: Score values are floats in range [0.0, 1.0]
# Higher values indicate better similarity
if results.GetShapeTanimoto() > 0.8:
    print("High shape similarity")