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