HDH-example/QUICKSTART.md

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

cd examples
pip install -r requirements.txt
pip install -e ../HDH

2. Run Your First Example

# 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

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:

python3 cli.py

This provides:

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

🏃‍♂️ Quick Commands

# 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

# 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'

pip install -e ../HDH

Memory Issues: Reduce circuit sizes

python3 main.py --max-qubits 4

Visualization Issues: Set matplotlib backend

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! ⭐