# BioSimulagent Example Notebooks

This directory contains comprehensive Jupyter notebooks demonstrating the full capabilities of the BioSimulagent client.

## 📚 Notebooks Overview

### [01_getting_started.ipynb](01_getting_started.ipynb)
**Level:** Beginner
**Duration:** 10-15 minutes

Learn the basics of BioSimulagent:
- Installation and setup
- Connecting to the backend
- Basic tool usage (literature, simulation, design, neural)
- Error handling and best practices
- Connection lifecycle management

**Prerequisites:** None

---

### [02_literature_review.ipynb](02_literature_review.ipynb)
**Level:** Intermediate
**Duration:** 20-30 minutes

Master literature search and analysis:
- PubMed literature search with advanced filters
- Patent database queries
- Article indexing for semantic search
- Citation analysis and visualization
- Knowledge extraction from papers
- Export results in multiple formats (CSV, BibTeX)

**Prerequisites:** 01_getting_started.ipynb

---

### [03_protein_structure.ipynb](03_protein_structure.ipynb)
**Level:** Intermediate
**Duration:** 30-45 minutes

Predict and analyze protein structures:
- Structure prediction from sequence (AlphaFold)
- Interactive 3D visualization with NGL Viewer
- Quality assessment (pLDDT, Ramachandran)
- Structural analysis (secondary structure, SASA)
- Comparison with experimental structures
- Binding site prediction

**Prerequisites:** 01_getting_started.ipynb
**Required packages:** `nglview`, `mdtraj`, `matplotlib`

---

### [04_ligand_design.ipynb](04_ligand_design.ipynb)
**Level:** Advanced
**Duration:** 45-60 minutes

Complete drug design workflow:
- De novo ligand generation with constraints
- Physicochemical property analysis
- Binding affinity prediction (docking)
- ADMET profiling (absorption, toxicity, etc.)
- Lead optimization
- Binding mode visualization
- Export to SDF format

**Prerequisites:** 01_getting_started.ipynb, 03_protein_structure.ipynb
**Required packages:** `nglview`, `matplotlib`, `pandas`

---

### [05_md_simulation.ipynb](05_md_simulation.ipynb)
**Level:** Advanced
**Duration:** 1-2 hours (includes simulation runtime)

Molecular dynamics simulation and analysis:
- MD simulation setup and execution (10 ns)
- RMSD/RMSF trajectory analysis
- Hydrogen bond tracking
- Protein-ligand contact analysis
- Energy analysis
- Principal Component Analysis (PCA)
- Interactive trajectory visualization

**Prerequisites:** 01_getting_started.ipynb, 04_ligand_design.ipynb
**Required packages:** `nglview`, `mdtraj`, `matplotlib`, `numpy`
**Note:** MD simulation takes 30-60 minutes to complete

---

### [06_advanced_workflows.ipynb](06_advanced_workflows.ipynb)
**Level:** Advanced
**Duration:** 60-90 minutes

Complete drug discovery pipeline with optimization:
- End-to-end workflow: Literature → Structure → Design → Affinity → ADMET → MD
- Parallel task execution with `asyncio.gather()`
- Result caching with pickle for ~3x speedup
- Checkpoint-based error recovery
- Comprehensive report generation
- Multi-format export (JSON, CSV, pickle)

**Prerequisites:** All notebooks 01-05
**Required packages:** `nglview`, `matplotlib`, `pandas`, `plotly`
**Note:** Demonstrates production-ready workflow patterns

---

### [07_custom_analysis.ipynb](07_custom_analysis.ipynb)
**Level:** Advanced
**Duration:** 45-60 minutes

Advanced trajectory analysis techniques:
- Custom RMSD matrix calculations
- Principal Component Analysis (PCA) for dominant motions
- Hierarchical clustering for conformational states
- Free energy landscape (2D and 3D)
- Contact persistence analysis
- Custom metrics (radius of gyration, SASA)
- Multi-format data export (CSV, HDF5, Parquet)
- Trajectory animation generation

**Prerequisites:** 01_getting_started.ipynb, 05_md_simulation.ipynb
**Required packages:** `mdtraj`, `matplotlib`, `numpy`, `scipy`, `sklearn`, `pandas`, `tables`, `pyarrow`

---

### [08_production_tips.ipynb](08_production_tips.ipynb)
**Level:** Advanced
**Duration:** 60+ minutes

Production-ready application best practices:
- Configuration management with environment variables
- Structured logging with `structlog` (JSON format)
- Error handling: retry with exponential backoff + circuit breaker
- Memory management for large trajectories (chunking, GC)
- Performance optimization (caching, profiling)
- Reproducibility (random seeds, environment recording)
- Complete ProductionWorkflow class
- Production deployment checklist

**Prerequisites:** 01_getting_started.ipynb, 06_advanced_workflows.ipynb
**Required packages:** `python-dotenv`, `structlog`, `psutil`, `memory-profiler`
**Note:** Essential for production deployments

---

## 🚀 Quick Start

### 1. Install Dependencies

```bash
# Core package
pip install bio-simulagent-client

# Visualization dependencies (optional but recommended)
pip install nglview mdtraj plotly matplotlib pandas numpy

# Enable nglview in Jupyter
jupyter-nbextension enable nglview --py --sys-prefix
```

### 2. Launch Jupyter

```bash
cd bio_simulagent_client/examples
jupyter notebook
```

### 3. Start with the First Notebook

Open [01_getting_started.ipynb](01_getting_started.ipynb) and follow along!

---

## 📦 Required Packages

### Core Requirements
- `bio-simulagent-client>=0.2.0`
- `ipython>=8.0.0`
- `nest-asyncio>=1.5.0` (for async in Jupyter)

### Visualization (Optional)
- `nglview>=3.0.0` - 3D molecular structure visualization
- `mdtraj>=1.9.0` - Trajectory analysis and manipulation
- `plotly>=5.0.0` - Interactive plots
- `matplotlib>=3.5.0` - Static plots
- `pandas>=1.5.0` - Data analysis
- `numpy>=1.21.0` - Numerical computing

### Advanced Analysis (For notebooks 06-08)
- `scikit-learn>=1.0.0` - PCA and clustering analysis
- `scipy>=1.7.0` - Scientific computing and hierarchical clustering
- `tables>=3.7.0` - HDF5 file format support
- `pyarrow>=10.0.0` - Parquet file format support
- `python-dotenv>=0.19.0` - Environment variable management
- `structlog>=21.0.0` - Structured logging
- `psutil>=5.8.0` - System and process monitoring
- `memory-profiler>=0.60.0` - Memory profiling (optional)

### Installation

```bash
# Install all dependencies (recommended)
pip install bio-simulagent-client[jupyter,viz,advanced]

# Or install core + visualization only
pip install bio-simulagent-client[jupyter,viz]

# Or install selectively
pip install bio-simulagent-client
pip install nglview mdtraj plotly matplotlib pandas numpy
pip install scikit-learn scipy tables pyarrow python-dotenv structlog psutil
```

---

## 🎯 Learning Path

### For Beginners
1. Start with **01_getting_started.ipynb** to learn the basics
2. Try **02_literature_review.ipynb** for simple literature searches
3. Gradually explore other notebooks based on your interests

### For Researchers
1. **01_getting_started.ipynb** - Quick overview
2. **02_literature_review.ipynb** - Literature search for your target
3. **03_protein_structure.ipynb** - Predict your protein structure
4. **04_ligand_design.ipynb** - Design ligands for your target
5. **05_md_simulation.ipynb** - Validate binding stability
6. **06_advanced_workflows.ipynb** - Complete end-to-end pipeline
7. **07_custom_analysis.ipynb** - Advanced trajectory analysis

### For Production Deployment
1. **01_getting_started.ipynb** - Learn the basics
2. **06_advanced_workflows.ipynb** - Optimized workflow patterns
3. **08_production_tips.ipynb** - Production best practices
4. Implement error handling, logging, and monitoring
5. Set up configuration management and reproducibility
6. Review production checklist before deployment

### For Developers
Review all notebooks to understand:
- Client API patterns
- Async programming with MCP tools
- Error handling strategies
- Visualization integration
- Workflow orchestration
- Performance optimization
- Production deployment

---

## 💡 Usage Tips

### Running Notebooks

1. **Execute cells in order** - Notebooks are designed to run sequentially
2. **Check prerequisites** - Some notebooks require outputs from earlier ones
3. **Save intermediate results** - Long-running cells (MD simulation) should save outputs
4. **Restart kernel if needed** - Use `Kernel > Restart & Clear Output` to start fresh

### Working with Large Data

- MD trajectories can be **large** (>1 GB)
- Use `trajectory_subset.dcd` exports for quick visualization
- Clean up temporary files after analysis
- Consider using external storage for long simulations

### Troubleshooting

**Backend connection fails:**
```python
# Check backend path
from bio_simulagent_client import create_config
config = create_config()
print(f"Backend: {config.backend_path}")

# Try manual connection
client = await BioSimulagent.connect(
    backend_path="backend.main",
    timeout=60
)
```

**Visualization not working:**
```bash
# Reinstall nglview
pip uninstall nglview -y
pip install nglview
jupyter-nbextension enable nglview --py --sys-prefix

# Restart Jupyter
```

**Async errors in Jupyter:**
```python
# Add at the top of notebook
import nest_asyncio
nest_asyncio.apply()
```

---

## 🔗 Related Resources

- **Client Documentation:** [README.md](../README.md)
- **API Reference:** [API Docs](https://bio-simulagent.readthedocs.io)
- **Backend Setup:** [Backend Documentation](../../backend/README.md)
- **Report Issues:** [GitHub Issues](https://github.com/yourusername/bio-simulagent/issues)

---

## 📝 Notebook Structure

Each notebook follows a consistent structure:

1. **Introduction** - Overview and learning objectives
2. **Setup** - Import libraries and connect to backend
3. **Main Content** - Step-by-step examples with explanations
4. **Visualization** - Interactive and static visualizations
5. **Analysis** - Results interpretation and statistics
6. **Export** - Save results for further use
7. **Summary** - Key takeaways and next steps
8. **Cleanup** - Close connections and free resources

---

## 🤝 Contributing

Found an error or want to improve these notebooks?

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add clear markdown explanations
5. Test all cells execute without errors
6. Submit a pull request

**Guidelines:**
- Keep explanations clear and concise
- Add citations for scientific concepts
- Include error handling examples
- Provide expected outputs in markdown
- Test with clean Jupyter environment

---

## 📄 License

These notebooks are part of the BioSimulagent project and are distributed under the MIT License.

---

## 🙏 Acknowledgments

- **AlphaFold** - Protein structure prediction
- **NGL Viewer** - Molecular visualization
- **MDTraj** - Trajectory analysis
- **PubMed** - Literature database
- **RDKit** - Cheminformatics toolkit

---

**Happy Learning! 🚀**

For questions or support, please open an issue on GitHub or contact the maintainers.
