theseus

Fragment-based generative chemistry model for ligand optimization

Usage

Here's how to use the Theseus class to perform common molecule generation tasks:

Instantiation

First, create an instance of the Theseus class, providing the server address of your BioNeMo API:

from theseus import Theseus

# Replace with your server address
server_address = "http://localhost:8000"
theseus = Theseus(server_address)

Mutate Molecule

To mutate a molecule, provide a SMILES string. Theseus will fragment the molecule, sample new fragments, and reassemble them to create a list of mutated molecules.

smi = "COc1cc(N2CCC[C@H]2C2=CCC2(C)C)n2cccc2n1"
mutated_molecules = theseus.mutate_molecule(smi)
print(mutated_molecules)

Grow Molecule

To grow a molecule, provide a SMILES string. If the molecule has a wildcard (*), it will be used as the growth point. Otherwise, a random growth point will be selected.

smi = "COc1cc(N2CCC[C@H]2C2=CCC2(C)C)n2cccc2n1"
grown_molecules = theseus.grow_molecule(smi)
print(grown_molecules)

Shrink Molecule

To shrink a molecule, provide a SMILES string. Theseus will remove one fragment at a time to generate a list of smaller molecules.

smi = "COc1cc(N2CCC[C@H]2C2=CCC2(C)C)n2cccc2n1"
shrunken_molecules = theseus.shrink_molecule(smi)
print(shrunken_molecules)

Docking Framework

Theseus includes an interoperable docking framework that allows you to integrate molecular docking with molecule generation for structure-based optimization.

Quick Start

from theseus import Theseus
from theseus.docking import DockingWorkflow, DockingConfig, AutoDockBackend

# Initialize Theseus and docking backend
theseus = Theseus("http://localhost:8000")
docking_backend = AutoDockBackend()

# Configure docking
docking_config = DockingConfig(
    receptor_file="receptor.pdbqt",
    center=[0.0, 0.0, 0.0],
    size=[20.0, 20.0, 20.0]
)

# Create workflow and optimize
workflow = DockingWorkflow(theseus, docking_backend, docking_config)
results = workflow.optimize(initial_smiles="CCO")

Features

• Interoperable: Works with any docking software through a simple interface
• Easy Integration: Simple API for combining docking with molecule generation
• Extensible: Easy to add new docking backends
• Production Ready: Includes error handling, logging, and validation

Supported Backends

• AutoDock Vina: Full implementation included
• Custom Backends: Easy to add your own (see theseus/docking/backends/example.py)

Documentation

For detailed documentation, see:

• Docking Framework README
• Example Scripts

Creating Custom Backends

To integrate a new docking software, inherit from DockingBackend:

from theseus.docking import DockingBackend, DockingResult, DockingConfig

class MyDockingBackend(DockingBackend):
    def dock(self, smiles: str, config: DockingConfig) -> List[DockingResult]:
        # Your implementation here
        pass
    
    def dock_batch(self, smiles_list: List[str], config: DockingConfig):
        # Batch docking implementation
        pass
    
    def is_available(self) -> bool:
        # Check if your software is installed
        return True

See theseus/docking/backends/example.py for a complete template.