examples/README.md

# Example Files for Docking@HOME

This directory contains example ligand and receptor files in PDBQT format for testing the Docking@HOME platform.

## Files

### `example_ligand.pdbqt`
- **Type**: Small molecule ligand
- **Format**: PDBQT (AutoDock format with partial charges and atom types)
- **Rotatable Bonds**: 2
- **Atoms**: 5
- **Purpose**: Simple test ligand for quick docking runs

### `example_receptor.pdbqt`
- **Type**: Protein receptor
- **Format**: PDBQT
- **Residues**: 4 (ALA, GLY, VAL, LEU)
- **Atoms**: 24
- **Purpose**: Simple test receptor for demonstration

## How to Use

### Web GUI

1. Start the server:
   ```bash
   python start.py
   ```

2. Open browser to `http://localhost:8080`

3. Upload files:
   - Click "Choose File" for Ligand → Select `example_ligand.pdbqt`
   - Click "Choose File" for Receptor → Select `example_receptor.pdbqt`

4. Configure parameters:
   - Runs: 100 (or your choice)
   - GPU: Enable if available

5. Click "🚀 Start Docking"

### Command Line

```bash
docking-at-home dock \
  -l examples/example_ligand.pdbqt \
  -r examples/example_receptor.pdbqt \
  -n 100 \
  --gpu
```

### Python API

```python
from docking_at_home.server import job_manager, initialize_server
import asyncio

async def main():
    await initialize_server()
    
    job_id = await job_manager.submit_job(
        ligand_file="examples/example_ligand.pdbqt",
        receptor_file="examples/example_receptor.pdbqt",
        num_runs=100,
        use_gpu=True
    )
    
    print(f"Job submitted: {job_id}")

asyncio.run(main())
```

## Expected Results

When running docking with these example files, you should expect:

- **Binding Energies**: -12 to -6 kcal/mol (simulation mode)
- **Poses**: As many as requested runs
- **Execution Time**: 
  - Simulation mode: ~1-2 seconds for 100 runs
  - Real AutoDock (CPU): ~30-60 minutes for 100 runs
  - Real AutoDock (GPU): ~2-5 minutes for 100 runs

## Converting Your Own Files

These example files are in PDBQT format. To convert your own PDB files:

### Using AutoDockTools (Python 2.7)

```bash
# Install AutoDockTools
pip install numpy
# Download from: http://autodock.scripps.edu/downloads

# Prepare ligand
pythonsh prepare_ligand4.py -l molecule.pdb -o molecule.pdbqt

# Prepare receptor
pythonsh prepare_receptor4.py -r protein.pdb -o protein.pdbqt
```

### Using Open Babel

```bash
# Install Open Babel
# Ubuntu/Debian: sudo apt-get install openbabel
# Mac: brew install open-babel
# Windows: Download from http://openbabel.org/

# Convert ligand (add hydrogens and charges)
obabel molecule.pdb -O molecule.pdbqt -h --partialcharge gasteiger

# Convert receptor
obabel protein.pdb -O protein.pdbqt -h
```

### Using PyMOL

```python
# In PyMOL
load molecule.pdb
h_add
save molecule.pdbqt
```

## File Format Details

### PDBQT Format

PDBQT is an extension of PDB format that includes:
- **Atom types** (C.3, N.pl3, O.2, etc.)
- **Partial charges** (Gasteiger or other methods)
- **Rotatable bonds** (TORSDOF)
- **Flexible residues** (for receptor flexibility)

### Example PDBQT Structure:

```
REMARK  Name = Example Ligand
REMARK  2 active torsions
ROOT
ATOM      1  C   UNL     1       0.000   0.000   0.000  0.00  0.00    +0.000 C 
ATOM      2  C   UNL     1       1.540   0.000   0.000  0.00  0.00    +0.000 C 
ENDROOT
BRANCH   2   3
ATOM      3  C   UNL     1       2.078   1.421   0.000  0.00  0.00    +0.000 C 
ENDBRANCH   2   3
TORSDOF 2
```

Key elements:
- `REMARK`: Comments and metadata
- `ROOT/ENDROOT`: Non-rotatable core structure
- `BRANCH/ENDBRANCH`: Rotatable bonds
- `TORSDOF`: Number of rotatable bonds (degrees of freedom)
- Coordinates: X, Y, Z in Ångströms
- Charges: Partial atomic charges

## More Examples

For more example structures:

1. **PDB Database**: https://www.rcsb.org/
   - Download crystal structures
   - Convert to PDBQT

2. **PubChem**: https://pubchem.ncbi.nlm.nih.gov/
   - Download small molecules
   - Convert to PDBQT

3. **AutoDock Website**: https://autodock.scripps.edu/
   - Example files
   - Tutorials
   - Documentation

## Troubleshooting

### File Not Recognized?

Make sure your PDBQT file has:
- `.pdbqt` extension
- Proper ATOM/HETATM records
- Gasteiger charges
- Correct atom types

### Invalid Coordinates?

Check that:
- Coordinates are in Ångströms
- Values are reasonable (not NaN or infinity)
- Structure is 3D (not 2D)

### Missing Charges?

Add charges using:
```bash
obabel input.pdb -O output.pdbqt --partialcharge gasteiger
```

## Support

- 📧 Email: [email protected]
- 🤗 Issues: https://huggingface.co/OpenPeerAI/DockingAtHOME/discussions
- 📚 AutoDock Docs: https://autodock.scripps.edu/

---

**Authors**: OpenPeer AI, Riemann Computing Inc., Bleunomics, Andrew Magdy Kamal