Skip to main content

Quick Start Guide

Get up and running with ORAQL in 15 minutes.

Prerequisites​

  • GitHub account with ORAQL organization access
  • Python 3.10+ installed
  • Git command-line tools

Step 1: Clone the Repository​

# Clone the main ORAQL repository
git clone https://github.com/dirkenglund/202508.NQVL.git
cd 202508.NQVL

# For open stack development
git clone https://github.com/[oraql-org]/oraql-open-stack.git
cd oraql-open-stack

Step 2: Set Up Your Environment​

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Step 3: Verify Installation​

# Run tests to verify setup
pytest tests/ -v

# Should see all tests passing

Step 4: Access Digital Twin (Optional)​

# Set up credentials (request from your PI)
export DIGITAL_TWIN_API_KEY="your-api-key-here"

# Test connection
python scripts/test_digital_twin_connection.py

Step 5: Create Your First Issue​

  1. Go to GitHub Issues
  2. Click "New Issue"
  3. Select your template (Hardware/Theory/Software/Admin)
  4. Fill in the details
  5. Assign to yourself and add labels
  6. Submit!

Quick Examples​

Example 1: Run a Simple Circuit (Simulation)​

from oraql import Circuit, RydbergGate

# Create a 5-qubit circuit
circuit = Circuit(num_qubits=5)

# Add gates
circuit.h(0)  # Hadamard on qubit 0
circuit.rydberg_cz(0, 1)  # Rydberg CZ between 0 and 1
circuit.measure_all()

# Run simulation
result = circuit.run_simulation(shots=1000)
print(result.counts)

Example 2: Query Digital Twin Performance Data​

from oraql.digital_twin import DigitalTwinAPI

# Initialize API
dt = DigitalTwinAPI(api_key=os.getenv("DIGITAL_TWIN_API_KEY"))

# Get latest gate fidelity data
fidelity_data = dt.get_gate_fidelities(
    gate_type="2Q",
    institution="Harvard",
    date_range="last_30_days"
)

print(f"Average 2Q fidelity: {fidelity_data.mean():.4f}")

Example 3: Submit Data to Digital Twin​

from oraql.digital_twin import DigitalTwinAPI
from datetime import datetime

dt = DigitalTwinAPI(api_key=os.getenv("DIGITAL_TWIN_API_KEY"))

# Log experimental result
dt.log_experiment(
    experiment_id="HVDL_2024_11_20_001",
    institution="Harvard",
    demonstrator_track="Logical Qubits",
    parameters={
        "num_qubits": 280,
        "gate_type": "2Q_Rydberg_CZ",
        "fidelity": 0.9952,
        "reloading_rate": 98500
    },
    timestamp=datetime.now(),
    notes="Continuous operation test with loss detection"
)

Common Tasks​

Check Issue Status​

# List your issues
gh issue list --assignee @me

# View specific issue
gh issue view 42

Run Tests​

# All tests
pytest tests/ -v

# Specific test file
pytest tests/test_circuits.py -v

# With coverage
pytest tests/ --cov=oraql --cov-report=html

Lint Code​

# Python code
black oraql/
ruff check oraql/

# Markdown docs
markdownlint documentation/

Next Steps​

Troubleshooting​

Issue: ModuleNotFoundError: No module named 'oraql'

  • Solution: Ensure virtual environment is activated and dependencies are installed

Issue: Digital Twin API connection fails

  • Solution: Verify your API key is set correctly: echo $DIGITAL_TWIN_API_KEY

Issue: GitHub authentication fails

  • Solution: Run gh auth login to re-authenticate

Getting Help​

  • GitHub Discussions: Ask questions in the community forum
  • Slack/Teams: Post in #help channel
  • Documentation: Search this site for detailed guides
  • Issues: Open a bug report if you find problems

You're all set! Start contributing to ORAQL.