# Szybki TK

> Fast molecular mechanics, geometry optimization, and free energy calculations for small molecules and protein-ligand complexes

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

## Core API - Function Quick Reference

### Molecular Optimization

**OESzybki(mol: OEMolBase, opts: OESzybkiOptions) -> bool**
  Use for: Energy minimization and geometry optimization of molecules
  Example: `sz = OESzybki(opts); sz(mol)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OESzybki.html

**OESzybki.GetEnergy() -> float**
  Use for: Retrieve energy after optimization
  Example: `energy = sz.GetEnergy()`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OESzybki.html

**OESzybki.GetResults() -> OESzybkiResults**
  Use for: Get detailed results including energy components
  Example: `results = sz.GetResults()`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OESzybki.html

### Protein-Ligand Optimization

**OEFixedProteinLigandOptimizer(opts: OEProteinLigandOptOptions) -> OEFixedProteinLigandOptimizer**
  Use for: Optimize ligand in rigid protein binding site
  Example: `opt = OEFixedProteinLigandOptimizer(opts); opt(protein, ligand, results)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OEFixedProteinLigandOptimizer.html

**OEFlexProteinLigandOptimizer(opts: OEProteinLigandOptOptions) -> OEFlexProteinLigandOptimizer**
  Use for: Optimize ligand with flexible protein side chains
  Example: `opt = OEFlexProteinLigandOptimizer(opts); opt(protein, ligand, results)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OEFlexProteinLigandOptimizer.html

### Entropy Calculations

**OELigandEntropy(mol: OEMolBase, opts: OELigandEntropyOptions, results: OEEntropyResults) -> bool**
  Use for: Calculate solution ligand entropy
  Example: `OELigandEntropy(mol, opts, results)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzFunctions/OEEntropy.html

**OEBoundLigandEntropy(protein: OEMolBase, ligand: OEMolBase, opts: OEBoundEntropyOptions, results: OEEntropyResults) -> bool**
  Use for: Calculate bound ligand entropy in protein complex
  Example: `OEBoundLigandEntropy(protein, ligand, opts, results)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzFunctions/OEEntropy.html

### Free Energy Calculations

**OEEstimateConfFreeEnergies(mol: OEMolBase, opts: OEFreeFormConfOptions, results: OEFreeFormConfResults) -> int**
  Use for: Estimate conformational free energies
  Example: `OEEstimateConfFreeEnergies(mol, opts, results)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzFunctions/OEEstimateConfFreeEnergies.html

**OEEstimateSolvFreeEnergy(mol: OEMolBase, opts: OEFreeFormSolvOptions, results: OEFreeFormSolvResults) -> int**
  Use for: Estimate solvation free energy
  Example: `OEEstimateSolvFreeEnergy(mol, opts, results)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzFunctions/OEEstimateSolvFreeEnergy.html

**OEFreeFormConf(mol: OEMolBase, opts: OEFreeFormConfOptions) -> OEFreeFormConf**
  Use for: Advanced conformational free energy calculations
  Example: `ff = OEFreeFormConf(opts); ff.GetFreeEnergies(mol, results)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OEFreeFormConf.html

### Torsion Scanning

**OETorsionScan(mol: OEMolBase, opts: OETorsionScanOptions, results: OETorsionScanResult) -> bool**
  Use for: Perform torsion angle scan
  Example: `OETorsionScan(mol, opts, results)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzFunctions/OETorsionScan.html

**OETorsionScanner(opts: OETorsionScanOptions) -> OETorsionScanner**
  Use for: Create reusable torsion scanner object
  Example: `scanner = OETorsionScanner(opts); scanner(mol, results)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OETorsionScanner.html

### Configuration Classes

**OESzybkiOptions() -> OESzybkiOptions**
  Use for: Configure Szybki optimization settings
  Example: `opts = OESzybkiOptions(); opts.SetForceFieldType(OEForceFieldType_MMFF94Smod)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OESzybkiOptions.html

**OEProteinLigandOptOptions() -> OEProteinLigandOptOptions**
  Use for: Configure protein-ligand optimization
  Example: `opts = OEProteinLigandOptOptions(); opts.GetProteinOptions().SetForceFieldType(OEForceFieldType_AMBER_FF14SB)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OEProteinLigandOptOptions.html

**OEFreeFormConfOptions() -> OEFreeFormConfOptions**
  Use for: Configure conformational free energy calculations
  Example: `opts = OEFreeFormConfOptions(); opts.SetTemperature(300.0)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OEFreeFormConfOptions.html

**OELigandEntropyOptions() -> OELigandEntropyOptions**
  Use for: Configure ligand entropy calculations
  Example: `opts = OELigandEntropyOptions(); opts.SetEntropyMethod(OEEntropyMethod_Analytic)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OELigandEntropyOptions.html

### Results Classes

**OESzybkiResults.GetTotalEnergy() -> float**
  Use for: Get total energy from optimization
  Example: `total_energy = results.GetTotalEnergy()`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OESzybkiResults.html

**OEProteinLigandOptResults.GetLigandEnergy() -> float**
  Use for: Get ligand energy from protein-ligand optimization
  Example: `lig_energy = results.GetLigandEnergy()`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OEProteinLigandOptResults.html

**OEEntropyResults.GetEntropy() -> float**
  Use for: Get calculated entropy value
  Example: `entropy = results.GetEntropy()`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OEEntropyResults.html

**OEFreeFormConfResults.GetFreeEnergy(idx: int) -> float**
  Use for: Get free energy for specific conformer
  Example: `fe = results.GetFreeEnergy(0)`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzClasses/OEFreeFormConfResults.html

### Utility Functions

**OEGetSzybkiError() -> str**
  Use for: Get last error message from Szybki operations
  Example: `error_msg = OEGetSzybkiError()`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzFunctions/OEGetSzybkiError.html

**OEGetFreeFormError() -> str**
  Use for: Get last error message from FreeForm operations
  Example: `error_msg = OEGetFreeFormError()`
  See: https://docs.eyesopen.com/toolkits/python/szybkitk/OESzFunctions/OEGetFreeFormError.html

## Common Patterns - Complete Working Examples

### Pattern: Basic Ligand Optimization in Vacuum

```python
from openeye import oechem, oeszybki

mol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)

opts = oeszybki.OESzybkiOptions()
opts.SetForceFieldType(oeszybki.OEForceFieldType_MMFF94Smod)
sz = oeszybki.OESzybki(opts)
sz(mol)

energy = sz.GetEnergy()
print(f"Optimized energy: {energy:.2f} kcal/mol")
oechem.OEWriteMolecule(oechem.oemolostream("optimized.sdf"), mol)
```
Use when: You need to minimize a small molecule structure in vacuum using MMFF94S force field

### Pattern: Ligand Optimization with Solvent Model

```python
from openeye import oechem, oeszybki

mol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)

opts = oeszybki.OESzybkiOptions()
opts.GetSolventOptions().SetSolventModel(oeszybki.OESolventModel_Sheffield)
sz = oeszybki.OESzybki(opts)
sz(mol)

results = oeszybki.OESzybkiResults()
sz.GetResults(results)
print(f"Total energy: {results.GetTotalEnergy():.2f} kcal/mol")
oechem.OEWriteMolecule(oechem.oemolostream("optimized.sdf"), mol)
```
Use when: You need to optimize a molecule in implicit solvent (Sheffield model)

### Pattern: Optimize Multiple Ligands

```python
from openeye import oechem, oeszybki

ifs = oechem.oemolistream("ligands.sdf")
ofs = oechem.oemolostream("optimized.sdf")

opts = oeszybki.OESzybkiOptions()
sz = oeszybki.OESzybki(opts)

for mol in ifs.GetOEMols():
    sz(mol)
    energy = sz.GetEnergy()
    oechem.OESetSDData(mol, "Energy", f"{energy:.2f}")
    oechem.OEWriteMolecule(ofs, mol)
```
Use when: You need to batch optimize multiple molecules from a file

### Pattern: Rigid Protein-Ligand Optimization

```python
from openeye import oechem, oeszybki

protein = oechem.OEGraphMol()
ligand = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("protein.pdb"), protein)
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), ligand)

opts = oeszybki.OEProteinLigandOptOptions()
opts.GetProteinOptions().SetForceFieldType(oeszybki.OEForceFieldType_AMBER_FF14SB)
optimizer = oeszybki.OEFixedProteinLigandOptimizer(opts)

results = oeszybki.OEProteinLigandOptResults()
optimizer(protein, ligand, results)
print(f"Ligand energy: {results.GetLigandEnergy():.2f} kcal/mol")
oechem.OEWriteMolecule(oechem.oemolostream("optimized_ligand.sdf"), ligand)
```
Use when: You need to optimize a ligand in a rigid protein binding site

### Pattern: Flexible Protein-Ligand Optimization

```python
from openeye import oechem, oeszybki

protein = oechem.OEGraphMol()
ligand = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("protein.pdb"), protein)
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), ligand)

opts = oeszybki.OEProteinLigandOptOptions()
opts.GetProteinFlexOptions().SetFlexType(oeszybki.OEProtFlex_SideChains)
opts.GetProteinFlexOptions().SetFlexDistance(5.0)
optimizer = oeszybki.OEFlexProteinLigandOptimizer(opts)

results = oeszybki.OEProteinLigandOptResults()
optimizer(protein, ligand, results)
print(f"Total energy: {results.GetTotalEnergy():.2f} kcal/mol")
oechem.OEWriteMolecule(oechem.oemolostream("optimized_complex.pdb"), protein)
```
Use when: You need to optimize ligand with flexible protein side chains within specified distance

### Pattern: Calculate Solution Ligand Entropy

```python
from openeye import oechem, oeszybki

mol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)

opts = oeszybki.OELigandEntropyOptions()
opts.SetEntropyMethod(oeszybki.OEEntropyMethod_Analytic)
opts.SetTemperature(300.0)

results = oeszybki.OEEntropyResults()
oeszybki.OELigandEntropy(mol, opts, results)

entropy = results.GetEntropy()
print(f"Ligand entropy: {entropy:.2f} cal/(mol*K)")
```
Use when: You need to calculate conformational entropy of a ligand in solution

### Pattern: Calculate Bound Ligand Entropy

```python
from openeye import oechem, oeszybki

protein = oechem.OEGraphMol()
ligand = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("protein.pdb"), protein)
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), ligand)

opts = oeszybki.OEBoundEntropyOptions()
opts.SetEntropyMethod(oeszybki.OEEntropyMethod_Analytic)

results = oeszybki.OEEntropyResults()
oeszybki.OEBoundLigandEntropy(protein, ligand, opts, results)

entropy = results.GetEntropy()
print(f"Bound ligand entropy: {entropy:.2f} cal/(mol*K)")
```
Use when: You need to calculate entropy of a ligand bound to a protein

### Pattern: Estimate Solvation Free Energy

```python
from openeye import oechem, oeszybki

mol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)

opts = oeszybki.OEFreeFormSolvOptions()
opts.SetSolventModel(oeszybki.OESolventModel_Sheffield)

results = oeszybki.OEFreeFormSolvResults()
retcode = oeszybki.OEEstimateSolvFreeEnergy(mol, opts, results)

if retcode == oeszybki.OEFreeFormReturnCode_Success:
    dg_solv = results.GetSolvFreeEnergy()
    print(f"Solvation free energy: {dg_solv:.2f} kcal/mol")
```
Use when: You need to estimate the free energy of solvation for a molecule

### Pattern: Estimate Conformational Free Energies

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

mol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)

omega = oeomega.OEOmega()
omega(mol)

opts = oeszybki.OEFreeFormConfOptions()
results = oeszybki.OEFreeFormConfResults()
retcode = oeszybki.OEEstimateConfFreeEnergies(mol, opts, results)

if retcode == oeszybki.OEFreeFormReturnCode_Success:
    for i, conf in enumerate(mol.GetConfs()):
        fe = results.GetFreeEnergy(i)
        print(f"Conformer {i}: {fe:.2f} kcal/mol")
```
Use when: You need to calculate relative free energies of different conformers

### Pattern: Torsion Scan

```python
from openeye import oechem, oeszybki

mol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)

bond = mol.GetBond(oechem.OEHasAtomIdx(2), oechem.OEHasAtomIdx(3))

opts = oeszybki.OETorsionScanOptions()
opts.SetTorsion(bond)
opts.SetNumPoints(36)

results = oeszybki.OETorsionScanResult()
oeszybki.OETorsionScan(mol, opts, results)

for i in range(results.GetNumPoints()):
    angle = results.GetAngle(i)
    energy = results.GetEnergy(i)
    print(f"Angle: {angle:.1f}, Energy: {energy:.2f} kcal/mol")
```
Use when: You need to scan a torsion angle and get energy profile

### Pattern: Optimize with Newton-Raphson Method

```python
from openeye import oechem, oeszybki

mol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)

opts = oeszybki.OESzybkiOptions()
opts.GetOptOptions().SetOptType(oeszybki.OEOptType_NEWTON)
opts.GetOptOptions().SetMaxIter(500)

sz = oeszybki.OESzybki(opts)
sz(mol)

results = oeszybki.OESzybkiResults()
sz.GetResults(results)
print(f"Final energy: {results.GetTotalEnergy():.2f} kcal/mol")
oechem.OEWriteMolecule(oechem.oemolostream("optimized.sdf"), mol)
```
Use when: You need more accurate optimization using second derivatives (slower but more precise)

### Pattern: Optimize All Conformers

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

mol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)

omega = oeomega.OEOmega()
omega(mol)

opts = oeszybki.OESzybkiOptions()
sz = oeszybki.OESzybki(opts)

for conf in mol.GetConfs():
    sz(conf)
    energy = sz.GetEnergy()
    conf.SetEnergy(energy)

mol.SortConfs(oechem.OEAbsoluteConfEnergyComp())
oechem.OEWriteMolecule(oechem.oemolostream("optimized_confs.sdf"), mol)
```
Use when: You need to optimize all conformers of a molecule and rank by energy

## API Decision Guide

- **For basic ligand optimization**: use `OESzybki` with `OESzybkiOptions`
- **For protein-ligand optimization with rigid protein**: use `OEFixedProteinLigandOptimizer`
- **For protein-ligand optimization with flexible side chains**: use `OEFlexProteinLigandOptimizer`
- **For entropy calculations in solution**: use `OELigandEntropy`
- **For entropy calculations in protein complex**: use `OEBoundLigandEntropy`
- **For solvation free energy**: use `OEEstimateSolvFreeEnergy`
- **For conformational free energies**: use `OEEstimateConfFreeEnergies`
- **For torsion angle scanning**: use `OETorsionScan` or `OETorsionScanner`

- **OESzybki vs OEFixedProteinLigandOptimizer**: use OESzybki for standalone ligands, use OEFixedProteinLigandOptimizer for ligands in protein binding sites
- **OEFixedProteinLigandOptimizer vs OEFlexProteinLigandOptimizer**: use Fixed when protein is rigid, use Flex when side chains should move
- **OEEstimateConfFreeEnergies vs OEFreeFormConf**: use OEEstimateConfFreeEnergies for simple calculations, use OEFreeFormConf for advanced control and custom settings
- **Analytic vs Numeric entropy**: use Analytic (faster) for most cases, use Numeric for higher accuracy when needed

- **Force field selection**: 
  - Use `OEForceFieldType_MMFF94Smod` for small molecules (default, fast)
  - Use `OEForceFieldType_AMBER_FF14SB` for proteins
  - Use `OEForceFieldType_SMIRNOFF` for OpenFF Parsley force field
  
- **Solvent model selection**:
  - Use `OESolventModel_Sheffield` for implicit solvent (fast)
  - Use `OESolventModel_PB` for Poisson-Boltzmann (more accurate, slower)
  - Use vacuum (no solvent) for gas phase calculations

## Common Parameters & Types

**OESzybkiOptions**: Configuration for molecular optimization
  - Create with: `opts = OESzybkiOptions()`
  - Common in: `OESzybki` constructor
  - Key methods: `SetForceFieldType()`, `GetSolventOptions()`, `GetOptOptions()`
  - Gotcha: Must set force field type before creating OESzybki object

**OEProteinLigandOptOptions**: Configuration for protein-ligand optimization
  - Create with: `opts = OEProteinLigandOptOptions()`
  - Common in: `OEFixedProteinLigandOptimizer`, `OEFlexProteinLigandOptimizer`
  - Key methods: `GetProteinOptions()`, `GetLigandOptions()`, `GetProteinFlexOptions()`
  - Gotcha: Protein and ligand have separate force field settings accessed via GetProteinOptions() and GetLigandOptions()

**OEFreeFormConfOptions**: Configuration for conformational free energy calculations
  - Create with: `opts = OEFreeFormConfOptions()`
  - Common in: `OEEstimateConfFreeEnergies`, `OEFreeFormConf`
  - Key methods: `SetTemperature()`, `SetSolventModel()`, `SetCorrSolventOptions()`
  - Typical values: Temperature 300.0 K (default), solvent model Sheffield or PB

**OEEntropyOptions** (base class for OELigandEntropyOptions, OEBoundEntropyOptions): Configuration for entropy calculations
  - Create with: `opts = OELigandEntropyOptions()` or `opts = OEBoundEntropyOptions()`
  - Common in: `OELigandEntropy`, `OEBoundLigandEntropy`
  - Key methods: `SetEntropyMethod()`, `SetTemperature()`
  - Typical values: `OEEntropyMethod_Analytic` (fast), `OEEntropyMethod_Numeric` (accurate)

**OESzybkiResults**: Results from optimization
  - Create with: `results = OESzybkiResults()`
  - Common in: `OESzybki.GetResults()`
  - Key methods: `GetTotalEnergy()`, `GetStrainEnergy()`, `GetSolventEnergy()`
  - Gotcha: Must call GetResults() after optimization to populate this object

**OEProteinLigandOptResults**: Results from protein-ligand optimization
  - Create with: `results = OEProteinLigandOptResults()`
  - Common in: `OEFixedProteinLigandOptimizer()`, `OEFlexProteinLigandOptimizer()`
  - Key methods: `GetLigandEnergy()`, `GetProteinEnergy()`, `GetTotalEnergy()`
  - Gotcha: Energy components are separated (ligand, protein, interaction)

**OEEntropyResults**: Results from entropy calculations
  - Create with: `results = OEEntropyResults()`
  - Common in: `OELigandEntropy`, `OEBoundLigandEntropy`
  - Key methods: `GetEntropy()`, `GetVibrationalEntropy()`, `GetRotationalEntropy()`
  - Units: Entropy in cal/(mol*K)

**OEFreeFormConfResults**: Results from conformational free energy calculations
  - Create with: `results = OEFreeFormConfResults()`
  - Common in: `OEEstimateConfFreeEnergies`
  - Key methods: `GetFreeEnergy(idx)`, `GetNumConfs()`, `GetBoltzmannWeight(idx)`
  - Gotcha: Index corresponds to conformer order in molecule

## Return Types & Error Handling

```python
# Pattern 1: Boolean returns from optimization functions
from openeye import oechem, oeszybki

mol = oechem.OEMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)

sz = oeszybki.OESzybki()
success = sz(mol)  # Returns bool
if not success:
    error_msg = oeszybki.OEGetSzybkiError()
    print(f"Optimization failed: {error_msg}")
else:
    energy = sz.GetEnergy()
    print(f"Success! Energy: {energy:.2f} kcal/mol")

# Pattern 2: Return codes from FreeForm functions
from openeye import oeszybki

results = oeszybki.OEFreeFormSolvResults()
retcode = oeszybki.OEEstimateSolvFreeEnergy(mol, opts, results)

if retcode == oeszybki.OEFreeFormReturnCode_Success:
    dg = results.GetSolvFreeEnergy()
    print(f"Solvation free energy: {dg:.2f} kcal/mol")
elif retcode == oeszybki.OEFreeFormReturnCode_Warning:
    error_msg = oeszybki.OEGetFreeFormError()
    print(f"Warning: {error_msg}")
    # Results may still be usable
else:
    error_msg = oeszybki.OEGetFreeFormError()
    print(f"Error: {error_msg}")

# Pattern 3: Results objects passed by reference
from openeye import oeszybki

protein = oechem.OEGraphMol()
ligand = oechem.OEGraphMol()
# ... load protein and ligand ...

optimizer = oeszybki.OEFixedProteinLigandOptimizer()
results = oeszybki.OEProteinLigandOptResults()  # Create empty results object
optimizer(protein, ligand, results)  # Results populated by reference

# Now access results
lig_energy = results.GetLigandEnergy()
total_energy = results.GetTotalEnergy()