Quantinuumclaw

Stack at a Glance

Quick Start (One Command)

From the repo root:

python3 scripts/create_quantum_app.py \
  --app-name "clinical-demo" \
  --use-case "chemistry" \
  --description "Clinical molecular simulation" \
  --deploy

Then set VITE_API_URL in the frontend to your Fly.io app URL (e.g. https://clinical-demo.fly.dev).

Clinical use-case → --use-case mapping:

General use cases (portfolio, finance, etc.) also use optimization, chemistry, ml, random, crypto, or finance. See references/clinical-use-cases.md for detailed clinical mappings.

Full Workflow: Creating a Quantum Application

Step 1: Define the use case

Identify the problem (optimization, simulation, ML, cryptography, clinical, etc.).

Step 2: Create Selene backend

python3 scripts/setup_selene_service.py \
  --app-name "my-quantum-app" \
  --use-case "chemistry" \
  --description "Quantum chemistry simulator"

This creates a backend dir with FastAPI, health check, Dockerfile, and fly.toml.

Step 3: Implement your Guppy circuit

Edit my-quantum-app/main.py → QuantumService._run_real_quantum(). Use references/guppy_guide.md for syntax. For clinical: chemistry (molecule, shots, precision), optimization (objective, constraints), ML (features, epochs).

Step 4: Deploy to Fly.io

python3 scripts/flyio_deploy.py --app-name "my-quantum-app" --service-dir "my-quantum-app" --region "lhr"

Set secrets with fly secrets set; use emulator for demos if preferred.

Step 5: Frontend

Use assets/lovable-template/ or run:

python3 scripts/lovable_integrate.py \
  --app-name "my-frontend" \
  --backend-url "https://my-quantum-app.fly.dev" \
  --quantum-use-case "chemistry"

Then npm install and npm run dev in the frontend dir.

Step 6: Connect and test

Point frontend VITE_API_URL to the Fly.io backend; hit /health to verify.

Clinical Use Case Cheat Sheet

• Drug discovery / molecular simulation: chemistry — VQE-style energy/property in Guppy; expose molecule type and params via API.
• Treatment / resource optimization: optimization — Define objective (cost, wait time); run QAOA in Selene; display results in UI.
• Patient stratification / classification: ml — Map patient features to model inputs; return risk/stratum or classification.
• Randomization (e.g. trials): random — Quantum RNG from Guppy; expose bits/shots in API.
• Security / key material: crypto — Key generation or quantum-safe primitives; keep keys on backend only.

Data and Compliance (Clinical / Hackathon)

• Demos: Use synthetic or de-identified data only. Do not send real PHI to quantum backends or store in Fly.io without a compliance plan.
• API keys: Store in Fly.io secrets (fly secrets set), never in code or frontend.
• Production: Add auth, rate limiting, and consider HIPAA/DPA; restrict CORS in Selene.

Resources

scripts/

• create_quantum_app.py — All-in-one: backend + deploy + frontend
• setup_selene_service.py — Scaffold Selene backend
• flyio_deploy.py — Deploy to Fly.io
• lovable_integrate.py — Frontend wired to backend URL

references/

• guppy_guide.md — Guppy syntax, gates, circuits, examples
• selene_api.md — Endpoints, request/response, errors, jobs
• flyio_config.md — Fly.io scaling, regions, secrets, monitoring
• lovable_patterns.md — Frontend patterns, dashboard, API client
• clinical-use-cases.md — Detailed clinical use-case mappings and compliance notes

assets/

• selene-template/ — Backend boilerplate (main.py, Dockerfile, fly.toml, .env.example)
• lovable-template/ — React/TS frontend with QuantumDashboard and API client

Advanced: Multi-Quantum Use Cases

• Optimization dashboard: Selene + QAOA/VQE; Lovable with sliders; Fly.io with scaling.
• Chemistry explorer: Guppy molecular simulations; 3D viewer; optional persistent storage.
• Quantum ML API: Selene exposing QNN/QSVM; Lovable for training/predictions; Fly.io (GPU if needed).

Performance, Cost, and Security

• Queuing: Use job queues for long-running quantum jobs; WebSockets or polling in frontend.
• Caching: Cache identical computations to reduce quantum hardware cost.
• Fly.io: Scale to zero when idle (min_machines_running = 0); use references/flyio_config.md for VM sizing.
• Security: No API keys in frontend; rate limiting on Selene; HTTPS in production; see references/selene_api.md for auth patterns.

Troubleshooting

• Guppy import error: pip install guppy in backend; or use mock mode for demos.
• Selene not starting: Check fly.toml, fly logs, and env vars.
• Frontend can’t connect: Verify VITE_API_URL, CORS in Selene, and curl .../health.
• Fly.io deploy fails: fly deploy --clean; fly logs --phase build; ensure fly auth login.
• Quantum results wrong: Validate circuit logic and measurement; test with emulator first.

Next Steps

After initial setup: monitor quantum usage/costs; add auth to Selene if public; improve error handling and logging; consider persistence for job history.

For detailed clinical use-case specs and compliance reminders, see references/clinical-use-cases.md.