# Zap TK

> Poisson-Boltzmann electrostatic calculations for molecular systems

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

## Core API - Function Quick Reference

### Electrostatic Calculations

**OEZap** class - Main Poisson-Boltzmann solver
  Use for: Computing electrostatic potentials and energies for molecular systems
  Example: `zap = OEZap(); zap.SetMolecule(mol); energy = zap.CalcPotentialEnergy()`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

**OEZap.CalcPotentialEnergy()** -> float
  Use for: Calculate total electrostatic potential energy of a molecule
  Example: `energy = zap.CalcPotentialEnergy()`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

**OEZap.CalcSolvationEnergy()** -> float
  Use for: Calculate solvation free energy (difference between solution and vacuum)
  Example: `solv_energy = zap.CalcSolvationEnergy()`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

**OEZap.CalcAtomPotentials(potentials: OEFloatArray)** -> bool
  Use for: Get electrostatic potential at each atom position
  Example: `potentials = oechem.OEFloatArray(mol.NumAtoms()); zap.CalcAtomPotentials(potentials)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

**OEZap.CalcForces(forces: OEDoubleArray)** -> bool
  Use for: Calculate electrostatic forces on atoms (gradients)
  Example: `forces = oechem.OEDoubleArray(3*mol.NumAtoms()); zap.CalcForces(forces)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

**OEZap.GetGrid()** -> OEScalarGrid
  Use for: Access the computed electrostatic potential grid
  Example: `grid = zap.GetGrid()`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

### Binding Energy Calculations

**OEBind** class - Protein-ligand binding energy calculator
  Use for: Computing electrostatic binding energies between protein and ligand
  Example: `bind = OEBind(); results = OEBindResults(); bind.Bind(protein, ligand, results)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEBind.html

**OEBind.Bind(protein: OEMolBase, ligand: OEMolBase, results: OEBindResults)** -> bool
  Use for: Calculate binding energy between protein and ligand
  Example: `success = bind.Bind(protein, ligand, results)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEBind.html

**OEZapBind(protein: OEMolBase, ligand: OEMolBase)** -> OESimpleBindResults
  Use for: Quick binding energy calculation with default settings
  Example: `results = OEZapBind(protein, ligand); energy = results.GetBindingEnergy()`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBFunctions/OEZapBind.html

**OEBindResults.GetBindingEnergy()** -> float
  Use for: Extract total binding energy from results
  Example: `binding_energy = results.GetBindingEnergy()`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEBindResults.html

**OEBindResults.GetCoulombicEnergy()** -> float
  Use for: Get Coulombic (vacuum) component of binding energy
  Example: `coulomb = results.GetCoulombicEnergy()`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEBindResults.html

**OEBindResults.GetDesolvationEnergy()** -> float
  Use for: Get desolvation penalty component of binding energy
  Example: `desolv = results.GetDesolvationEnergy()`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEBindResults.html

### Electrostatic Similarity

**OEET** class - Electrostatic Tanimoto similarity calculator
  Use for: Comparing electrostatic potential similarity between molecules
  Example: `et = OEET(); similarity = et.Tanimoto(mol1, mol2)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEET.html

**OEET.Tanimoto(mol1: OEMolBase, mol2: OEMolBase)** -> float
  Use for: Calculate electrostatic Tanimoto similarity (0-1 scale)
  Example: `similarity = et.Tanimoto(reference_mol, query_mol)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEET.html

**OEMakeETGrid(mol: OEMolBase, grid: OEScalarGrid)** -> bool
  Use for: Create electrostatic potential grid for ET calculations
  Example: `grid = oegrid.OEScalarGrid(); OEMakeETGrid(mol, grid)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBFunctions/OEMakeETGrid.html

### Surface Area Calculations

**OEArea** class - Molecular surface area calculator
  Use for: Computing solvent accessible and molecular surface areas
  Example: `area = OEArea(); area.SetMolecule(mol); sa = area.GetArea()`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEArea.html

**OEArea.GetArea()** -> float
  Use for: Get total molecular surface area
  Example: `total_area = area.GetArea()`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEArea.html

**OEArea.GetAtomAreas(areas: OEFloatArray)** -> bool
  Use for: Get surface area contribution for each atom
  Example: `areas = oechem.OEFloatArray(mol.NumAtoms()); area.GetAtomAreas(areas)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEArea.html

### Coulombic Calculations

**OECoulombicSelfEnergy(mol: OEMolBase)** -> float
  Use for: Calculate Coulombic self-energy in vacuum
  Example: `vacuum_energy = OECoulombicSelfEnergy(mol)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBFunctions/OECoulombicSelfEnergy.html

**OECoulombicAtomPotentials(mol: OEMolBase, potentials: OEFloatArray)** -> bool
  Use for: Calculate Coulombic potential at each atom (vacuum)
  Example: `potentials = oechem.OEFloatArray(mol.NumAtoms()); OECoulombicAtomPotentials(mol, potentials)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBFunctions/OECoulombicAtomPotentials.html

**OECalculateCoulombicBinding(protein: OEMolBase, ligand: OEMolBase)** -> float
  Use for: Calculate Coulombic binding energy (vacuum, no desolvation)
  Example: `coulomb_bind = OECalculateCoulombicBinding(protein, ligand)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBFunctions/OECalculateCoulombicBinding.html

### Configuration Methods

**OEZap.SetInnerDielectric(epsilon: float)** -> bool
  Use for: Set dielectric constant for molecule interior (typically 1-4)
  Example: `zap.SetInnerDielectric(2.0)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

**OEZap.SetOuterDielectric(epsilon: float)** -> bool
  Use for: Set dielectric constant for solvent (typically 80 for water)
  Example: `zap.SetOuterDielectric(80.0)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

**OEZap.SetGridSpacing(spacing: float)** -> bool
  Use for: Set grid resolution in Angstroms (smaller = more accurate, slower)
  Example: `zap.SetGridSpacing(0.5)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

**OEZap.SetBoundarySpacing(spacing: float)** -> bool
  Use for: Set distance from molecule to grid boundary
  Example: `zap.SetBoundarySpacing(4.0)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

**OEZap.SetMolecule(mol: OEMolBase)** -> bool
  Use for: Set the molecule for electrostatic calculations
  Example: `zap.SetMolecule(mol)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEZap.html

**OEArea.SetAreaMethod(method: unsigned int)** -> bool
  Use for: Choose surface area calculation method (SASA vs molecular surface)
  Example: `area.SetAreaMethod(OEAreaMethod_SASA)`
  See: https://docs.eyesopen.com/toolkits/python/zaptk/OEPBClasses/OEArea.html

## Common Patterns - Complete Working Examples

### Pattern: Calculate Solvation Energy (PBSA)
```python
from openeye import oechem, oezap

# Read molecule and ensure it has charges
mol = oechem.OEGraphMol()
ifs = oechem.oemolistream("molecule.sdf")
oechem.OEReadMolecule(ifs, mol)
oechem.OEAssignPartialCharges(mol, oechem.OECharges_AM1BCCSym)

# Setup Zap calculation with standard settings
zap = oezap.OEZap()
zap.SetInnerDielectric(2.0)
zap.SetOuterDielectric(80.0)
zap.SetMolecule(mol)

# Calculate solvation free energy
solvation_energy = zap.CalcSolvationEnergy()
print(f"Solvation energy: {solvation_energy:.2f} kcal/mol")
```
Use when: You need the free energy of transferring a molecule from vacuum to solvent (PBSA model)

### Pattern: Calculate Protein-Ligand Binding Energy
```python
from openeye import oechem, oezap

# Read protein and ligand structures
protein = oechem.OEGraphMol()
ligand = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("protein.pdb"), protein)
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), ligand)

# Assign charges if not present
oechem.OEAssignPartialCharges(protein, oechem.OECharges_AM1BCCSym)
oechem.OEAssignPartialCharges(ligand, oechem.OECharges_AM1BCCSym)

# Calculate binding energy with default settings
results = oezap.OEZapBind(protein, ligand)
binding_energy = results.GetBindingEnergy()
coulombic = results.GetCoulombicEnergy()
desolvation = results.GetDesolvationEnergy()

print(f"Binding energy: {binding_energy:.2f} kcal/mol")
print(f"  Coulombic: {coulombic:.2f}, Desolvation: {desolvation:.2f}")
```
Use when: You need electrostatic contribution to protein-ligand binding affinity

### Pattern: Calculate Electrostatic Potentials at Atoms
```python
from openeye import oechem, oezap

# Prepare molecule with charges
mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("molecule.sdf"), mol)
oechem.OEAssignPartialCharges(mol, oechem.OECharges_AM1BCCSym)

# Setup Zap and calculate potentials
zap = oezap.OEZap()
zap.SetMolecule(mol)
potentials = oechem.OEFloatArray(mol.NumAtoms())
zap.CalcAtomPotentials(potentials)

# Print potential at each atom
for idx, atom in enumerate(mol.GetAtoms()):
    print(f"Atom {atom.GetName()}: {potentials[idx]:.3f} kT/e")
```
Use when: You need electrostatic potential values at specific atomic positions for analysis

### Pattern: Compare Electrostatic Similarity Between Molecules
```python
from openeye import oechem, oezap

# Read two molecules to compare
mol1 = oechem.OEGraphMol()
mol2 = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("reference.sdf"), mol1)
oechem.OEReadMolecule(oechem.oemolistream("query.sdf"), mol2)

# Assign charges
oechem.OEAssignPartialCharges(mol1, oechem.OECharges_AM1BCCSym)
oechem.OEAssignPartialCharges(mol2, oechem.OECharges_AM1BCCSym)

# Calculate electrostatic Tanimoto similarity
et = oezap.OEET()
similarity = et.Tanimoto(mol1, mol2)
print(f"Electrostatic similarity: {similarity:.3f}")
```
Use when: You want to find molecules with similar electrostatic properties (e.g., bioisostere search)

### Pattern: Calculate Molecular Surface Area
```python
from openeye import oechem, oezap

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

# Calculate solvent accessible surface area
area_calc = oezap.OEArea()
area_calc.SetAreaMethod(oezap.OEAreaMethod_SASA)
area_calc.SetMolecule(mol)
total_area = area_calc.GetArea()

# Get per-atom contributions
atom_areas = oechem.OEFloatArray(mol.NumAtoms())
area_calc.GetAtomAreas(atom_areas)

print(f"Total SASA: {total_area:.2f} Ų")
```
Use when: You need solvent accessible surface area for PBSA calculations or analysis

### Pattern: Calculate Electrostatic Forces on Atoms
```python
from openeye import oechem, oezap

# Prepare molecule
mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("molecule.sdf"), mol)
oechem.OEAssignPartialCharges(mol, oechem.OECharges_AM1BCCSym)

# Setup Zap and calculate forces
zap = oezap.OEZap()
zap.SetMolecule(mol)
forces = oechem.OEDoubleArray(3 * mol.NumAtoms())
zap.CalcForces(forces)

# Extract force components for each atom
for idx, atom in enumerate(mol.GetAtoms()):
    fx = forces[3*idx]
    fy = forces[3*idx + 1]
    fz = forces[3*idx + 2]
    print(f"Atom {atom.GetName()}: F=({fx:.3f}, {fy:.3f}, {fz:.3f})")
```
Use when: You need electrostatic force gradients for optimization or dynamics

### Pattern: Focused Grid Calculation for Large Systems
```python
from openeye import oechem, oezap

# Read large protein-ligand complex
complex_mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("complex.pdb"), complex_mol)
oechem.OEAssignPartialCharges(complex_mol, oechem.OECharges_AM1BCCSym)

# First pass: coarse grid for entire system
zap_coarse = oezap.OEZap()
zap_coarse.SetGridSpacing(1.0)
zap_coarse.SetMolecule(complex_mol)
zap_coarse.CalcPotentialEnergy()

# Second pass: fine grid focused on binding site
zap_fine = oezap.OEZap()
zap_fine.SetGridSpacing(0.25)
zap_fine.SetBoundarySpacing(2.0)
zap_fine.SetMolecule(complex_mol)
energy = zap_fine.CalcPotentialEnergy()
print(f"Focused grid energy: {energy:.2f} kcal/mol")
```
Use when: You need high accuracy for large systems by using focusing technique

### Pattern: Custom Dielectric Model for Membrane Protein
```python
from openeye import oechem, oezap

# Read membrane protein
protein = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("membrane_protein.pdb"), protein)
oechem.OEAssignPartialCharges(protein, oechem.OECharges_AM1BCCSym)

# Setup with membrane-appropriate dielectrics
zap = oezap.OEZap()
zap.SetInnerDielectric(4.0)  # Higher for membrane environment
zap.SetOuterDielectric(2.0)  # Lower for lipid bilayer
zap.SetMolecule(protein)

# Calculate energy in membrane environment
energy = zap.CalcPotentialEnergy()
print(f"Membrane protein energy: {energy:.2f} kcal/mol")
```
Use when: Modeling proteins in non-aqueous environments like membranes

### Pattern: Batch Calculate Solvation Energies
```python
from openeye import oechem, oezap

# Setup Zap once for reuse
zap = oezap.OEZap()
zap.SetInnerDielectric(2.0)
zap.SetOuterDielectric(80.0)

# Process multiple molecules
ifs = oechem.oemolistream("molecules.sdf")
results = []
for mol in ifs.GetOEGraphMols():
    oechem.OEAssignPartialCharges(mol, oechem.OECharges_AM1BCCSym)
    zap.SetMolecule(mol)
    solv_energy = zap.CalcSolvationEnergy()
    results.append((mol.GetTitle(), solv_energy))
    
for name, energy in results:
    print(f"{name}: {energy:.2f} kcal/mol")
```
Use when: You need to calculate solvation energies for multiple molecules efficiently

### Pattern: Extract and Visualize Electrostatic Potential Grid
```python
from openeye import oechem, oezap, oegrid

# Calculate electrostatic potential
mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("molecule.sdf"), mol)
oechem.OEAssignPartialCharges(mol, oechem.OECharges_AM1BCCSym)

zap = oezap.OEZap()
zap.SetMolecule(mol)
zap.CalcPotentialEnergy()

# Get the potential grid
grid = zap.GetGrid()

# Write grid to file for visualization
ofs = oegrid.OEGridOutputStream("potential.grd")
oegrid.OEWriteGrid(ofs, grid)
ofs.close()
print(f"Grid dimensions: {grid.GetXDim()} x {grid.GetYDim()} x {grid.GetZDim()}")
```
Use when: You need to export electrostatic potential grids for visualization or further analysis

### Pattern: Calculate Coulombic vs Solvation Components
```python
from openeye import oechem, oezap

# Prepare molecule
mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("molecule.sdf"), mol)
oechem.OEAssignPartialCharges(mol, oechem.OECharges_AM1BCCSym)

# Calculate Coulombic (vacuum) energy
coulombic_energy = oezap.OECoulombicSelfEnergy(mol)

# Calculate solvation energy (PB - Coulombic)
zap = oezap.OEZap()
zap.SetMolecule(mol)
solvation_energy = zap.CalcSolvationEnergy()

# Total energy in solution
total_energy = zap.CalcPotentialEnergy()

print(f"Coulombic: {coulombic_energy:.2f} kcal/mol")
print(f"Solvation: {solvation_energy:.2f} kcal/mol")
print(f"Total: {total_energy:.2f} kcal/mol")
```
Use when: You need to decompose electrostatic energy into vacuum and solvation components

### Pattern: Validate Charges Before Calculation
```python
from openeye import oechem, oezap

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

# Check if charges are present and valid
has_charges = True
total_charge = 0.0
for atom in mol.GetAtoms():
    if not atom.HasPartialCharge():
        has_charges = False
        break
    total_charge += atom.GetPartialCharge()

# Assign charges if needed
if not has_charges:
    print("No charges found, assigning AM1-BCC charges")
    oechem.OEAssignPartialCharges(mol, oechem.OECharges_AM1BCCSym)
else:
    print(f"Using existing charges (total: {total_charge:.3f})")

# Proceed with calculation
zap = oezap.OEZap()
zap.SetMolecule(mol)
energy = zap.CalcSolvationEnergy()
print(f"Solvation energy: {energy:.2f} kcal/mol")
```
Use when: Working with molecules from various sources where charge assignment may be inconsistent

## API Decision Guide

- **For solvation free energy**: use `OEZap.CalcSolvationEnergy()` (PBSA model, difference between solution and vacuum)
- **For total electrostatic energy in solution**: use `OEZap.CalcPotentialEnergy()` (includes both Coulombic and solvation)
- **For protein-ligand binding energy**: use `OEZapBind()` for quick calculations or `OEBind` class for more control
- **For electrostatic similarity**: use `OEET.Tanimoto()` (returns 0-1 similarity score)
- **For surface area**: use `OEArea` class with `SetAreaMethod(OEAreaMethod_SASA)` for solvent accessible or `OEAreaMethod_Molecular` for molecular surface

- **OEZap vs OEBind**: use OEZap for single molecule energies/potentials, use OEBind for protein-ligand binding calculations
- **CalcPotentialEnergy vs CalcSolvationEnergy**: CalcPotentialEnergy gives total energy in solution, CalcSolvationEnergy gives the solvation free energy (ΔG_solv)
- **OEZapBind vs OEBind**: OEZapBind is convenience function with defaults, OEBind class allows custom settings and focusing
- **OEET vs OEZap for similarity**: OEET is specialized for electrostatic similarity comparisons, OEZap is for energies

- **Grid spacing**: use 0.5 Å for standard accuracy, 0.25 Å for high accuracy (slower), 1.0 Å for quick estimates
- **Inner dielectric**: use 1.0-2.0 for small molecules, 2.0-4.0 for proteins, 4.0 for membrane proteins
- **Outer dielectric**: use 80.0 for water, 2.0-4.0 for membrane/lipid environments

- **For atom-level data**: use `CalcAtomPotentials()` for potentials, `GetAtomAreas()` for surface areas, `CalcForces()` for gradients
- **For grid data**: use `GetGrid()` to access the full 3D electrostatic potential grid

## Common Parameters & Types

**OEMolBase**: Molecule object containing structure and properties
  - Create with: `mol = oechem.OEGraphMol()` then read from file or build programmatically
  - Common in: All OEZap, OEBind, OEET, OEArea methods
  - Gotcha: Must have partial charges assigned before Zap calculations - use `oechem.OEAssignPartialCharges(mol, oechem.OECharges_AM1BCCSym)`

**OEFloatArray**: Array for storing floating-point values (atom potentials, areas)
  - Create with: `arr = oechem.OEFloatArray(size)` where size is typically `mol.NumAtoms()`
  - Common in: `CalcAtomPotentials()`, `GetAtomAreas()`, `OECoulombicAtomPotentials()`
  - Typical values: Potentials in kT/e units, areas in Ų

**OEDoubleArray**: Array for storing double-precision values (forces/gradients)
  - Create with: `arr = oechem.OEDoubleArray(size)` where size is `3 * mol.NumAtoms()` for forces
  - Common in: `CalcForces()` - stores Fx, Fy, Fz for each atom sequentially
  - Gotcha: Size must be exactly 3× number of atoms (x, y, z components)

**OEScalarGrid**: 3D grid storing scalar values (electrostatic potential)
  - Create with: `grid = oegrid.OEScalarGrid()` or obtained from `zap.GetGrid()`
  - Common in: `GetGrid()`, `OEMakeETGrid()`, grid I/O operations
  - Typical values: Electrostatic potential in kT/e units at each grid point

**OEBindResults**: Container for binding energy calculation results
  - Create with: `results = oezap.OEBindResults()` then pass to `Bind()` method
  - Common in: `OEBind.Bind()` method
  - Access with: `GetBindingEnergy()`, `GetCoulombicEnergy()`, `GetDesolvationEnergy()`

**OESimpleBindResults**: Simplified binding results from convenience function
  - Create with: Returned directly from `OEZapBind(protein, ligand)`
  - Common in: Quick binding energy calculations
  - Access with: Same methods as OEBindResults

**float (dielectric constant)**: Dielectric constant for medium
  - Typical values: 1.0 (vacuum), 2.0-4.0 (protein/membrane interior), 80.0 (water)
  - Common in: `SetInnerDielectric()`, `SetOuterDielectric()`
  - Gotcha: Inner dielectric should be lower than outer dielectric for physical systems

**float (grid spacing)**: Grid resolution in Angstroms
  - Typical values: 0.25 (high accuracy), 0.5 (standard), 1.0 (fast/coarse)
  - Common in: `SetGridSpacing()`, `SetBoundarySpacing()`
  - Gotcha: Smaller spacing = more accurate but much slower and more memory

## Return Types & Error Handling

```python
# Pattern 1: Boolean returns indicate success/failure
success = zap.SetMolecule(mol)
if not success:
    print("Failed to set molecule - check charges and structure")

# Pattern 2: Energy calculations return float values
energy = zap.CalcSolvationEnergy()
if energy == 0.0:
    # May indicate calculation failure or actual zero energy
    # Check molecule setup and charges
    pass

# Pattern 3: Array-filling methods return bool for success
potentials = oechem.OEFloatArray(mol.NumAtoms())
if zap.CalcAtomPotentials(potentials):
    # Successfully calculated, potentials array is now filled
    for i in range(mol.NumAtoms()):
        print(f"Potential {i}: {potentials[i]}")
else:
    print("Failed to calculate atom potentials")

# Pattern 4: Object returns from convenience functions
results = oezap.OEZapBind(protein, ligand)
# Results object is always returned, check energy values for validity
binding_energy = results.GetBindingEnergy()
if abs(binding_energy) < 1e-6:
    print("Warning: binding energy near zero, check input structures")

# Pattern 5: Grid access returns reference to internal grid
grid = zap.GetGrid()
if grid.GetSize() == 0:
    print("Grid not calculated yet - call CalcPotentialEnergy() first")
else:
    print(f"Grid has {grid.GetSize()}