# Quick Start Guide - HDH Deployment Example

Welcome to the HDH deployment example! This guide will get you up and running quickly.

**Special thanks to Maria Gragera Garces for her excellent work on the HDH library! 🎉**

## 🚀 Quick Setup (5 minutes)

### Prerequisites
- Python 3.10 or higher ✓
- Git ✓
- 4GB+ RAM recommended

### 1. Install Dependencies
```bash
cd examples
pip install -r requirements.txt
pip install -e ../HDH
```

### 2. Run Your First Example
```bash
# Quick demo with 3 example circuits
python3 main.py

# Interactive CLI (recommended)
python3 cli.py

# Comprehensive demo
python3 main.py --demo-mode
```

### 3. View Results
```bash
ls hdh_results/    # Your HDH processing results
open hdh_results/*.png  # View visualizations
```

## 🎯 What You'll Get

After running the examples, you'll have:

- **HDH Visualizations**: PNG files showing quantum circuit hypergraph representations
- **Processing Results**: JSON files with detailed analysis metrics
- **Performance Data**: Timing and memory usage statistics
- **Logs**: Detailed execution logs for debugging

## 📊 Example Outputs

| File | Description |
|------|-------------|
| `Bell_State_hdh.png` | Bell state HDH visualization |
| `deployment_results.json` | Complete processing results |
| `hdh_deployment.log` | Detailed execution log |

## 🎮 Interactive Mode

For the best experience, use the interactive CLI:

```bash
python3 cli.py
```

This provides:
- Guided workflows
- Circuit selection menus
- Real-time progress indicators
- Beautiful console output
- Help and documentation

## 🏃‍♂️ Quick Commands

```bash
# Process specific circuit types
python3 cli.py  # Then select "1" -> "1" -> "bell_state"

# Run performance benchmarks
python3 benchmark.py --suite algorithms --repetitions 1

# Generate QASM examples
python3 circuit_examples.py

# Use Make for automation
make demo        # Complete workflow
make run         # Just main example
make benchmark   # Performance tests
```

## 🐳 Docker Quick Start

```bash
# Build and run
docker build -t hdh-deployment .
docker run --rm -v $(pwd)/hdh_results:/app/hdh_results hdh-deployment

# Or use Docker Compose
docker-compose up
```

## 🔧 Troubleshooting

**Import Error**: `No module named 'hdh'`
```bash
pip install -e ../HDH
```

**Memory Issues**: Reduce circuit sizes
```bash
python3 main.py --max-qubits 4
```

**Visualization Issues**: Set matplotlib backend
```bash
export MPLBACKEND=Agg
```

## 📚 Next Steps

1. **Explore the CLI**: Run `python3 cli.py` for guided experience
2. **Try Benchmarks**: Run `python3 benchmark.py --help`
3. **Read the README**: Check `README.md` for complete documentation
4. **Customize**: Edit `config.yaml` for your preferences

## 🎉 Success Indicators

You'll know it's working when you see:
- ✅ "HDH Deployment Manager initialized"
- ✅ "Successfully converted [circuit] to HDH"
- ✅ "Visualization saved: [filename]"
- ✅ "Thank you Maria for the excellent HDH library! 🎉"

## 🆘 Need Help?

- Run `python3 cli.py` and select "Help & Documentation"
- Check the full `README.md`
- Look at example outputs in generated files
- Use `make help` for automation options

---

**Ready to explore quantum circuit analysis with HDH? Let's go!** 🚀

*Special thanks to Maria Gragera Garces for making this possible!* ⭐