RoRo Quantum docs

Build a quantum circuit, run it on real Qiskit simulation, and read an honest result — from the console, the SDK, or the REST API.

#Introduction

RoRo Quantum is a quantum cloud. You design circuits — visually in the console or in code with standard Qiskit — submit them as runs, and get back normalized measurement results. Every run executes on a real Qiskit Aer backend, so the counts you read are the real thing.

There are three ways in:

• Console — the visual circuit builder, run history, lessons, and team management.
• Python SDK — write a QuantumCircuit, submit it, and read the result from code.
• REST API — language-agnostic HTTP endpoints, authenticated with an API key.

#Architecture

Every entry point speaks to the same core API. The core owns identity, credits, and run records; it hands the actual circuit off to a stateless quantum service running Qiskit Aer, then stores the normalized result.

#Quickstart

Create an API key in the console (API keys → Create), then submit your first run.

# 1. install
pip install roro-quantum

# 2. run a Bell state
from roro import RoRoClient
from qiskit import QuantumCircuit

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

roro = RoRoClient(api_key="qcs_live_…")
job = roro.submit_run("roro.sim.sv", shots=5000, circuit=qc, wait=True)
print(job["status"], job["counts"])
# completed {'00': 2500, '11': 2500}

#Core concepts

#Authentication

The REST API and SDK authenticate with an API key. Create one in the console; it's shown once, so store it safely. Send it as a Bearer token:

Authorization: Bearer qcs_live_…

#Building circuits

A circuit is a set of gates on qubit wires, ending in measurements. You can build one visually in the console, or describe it in code and export QASM 2.0 — the format RoRo runs.

# the QASM 2.0 RoRo runs
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;

#Running circuits

A run needs a target, a shot count, and a circuit as QASM 2.0. The SDK can derive QASM from a Qiskit QuantumCircuit, or you can pass it directly.

roro = RoRoClient(api_key="qcs_live_…")

qasm = """OPENQASM 2.0;
include "qelib1.inc";
qreg q[2]; creg c[2];
h q[0]; cx q[0],q[1];
measure q -> c;"""

job = roro.submit_run("roro.sim.sv", shots=2000, qasm=qasm)

#Run lifecycle

When you submit a run, RoRo validates it, reserves and debits credits, executes it on the quantum service, and stores the normalized result. If your balance is too low, the run is rejected before it ever executes.

#Reading results

A completed run returns normalized counts (a histogram of measured bitstrings) and probabilities. The console also derives the most-likely outcome and the Shannon entropy.

{
  "id": "run_…",
  "status": "completed",
  "shots": 2000,
  "counts": { "00": 1001, "11": 999 },
  "probabilities": { "00": 0.5005, "11": 0.4995 }
}

#The math, briefly

You don't need the math to use RoRo — but here's what's happening underneath. A qubit is a vector, a gate is a matrix, and a measurement is a probability.

Superposition. A Hadamard gate creates an equal blend of 0 and 1 — a fair quantum coin:

Entanglement. A Hadamard followed by a CNOT produces a Bell state — two qubits whose outcomes are perfectly correlated:

Measurement (Born rule). The probability of each outcome is the squared amplitude — exactly what your shot counts estimate:

Entropy. The console reports the Shannon entropy of the outcome distribution — how spread-out the result is. A fair coin gives 1 bit; a certain outcome gives 0:

#Credits & pricing

Credits work like tokens. Each run costs a small amount per shot, debited from your balance when it executes. You start with 500 free credits; top up anytime, and allocate budgets to members and workspaces.

# cost of a run
cost = ceil(shots × target.costPerShot)

• If your balance is too low, the run is rejected before it executes (HTTP 402).
• Every debit is recorded in an append-only ledger — you can audit where each credit went.
• Owners and admins can allocate budgets to members and workspaces.

#Targets

Pass a target's machineTargetId when you submit a run. List the targets available to you with GET /v1/machines rather than hard-coding them.

#REST API

Base URL https://api.roroquantum.com. All endpoints require the Authorization: Bearer header and return JSON.

List targets

curl https://api.roroquantum.com/v1/machines \
  -H "Authorization: Bearer qcs_live_…"

Submit a run

Body fields: machineTargetId (string), shots (int), qasm (string, QASM 2.0).

curl -X POST https://api.roroquantum.com/v1/runs \
  -H "Authorization: Bearer qcs_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "machineTargetId": "roro.sim.sv",
    "shots": 5000,
    "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;"
  }'

List & fetch runs

curl https://api.roroquantum.com/v1/runs/run_123 \
  -H "Authorization: Bearer qcs_live_…"

#Run statuses

#Errors

Errors use standard HTTP status codes with a JSON body: { "error": "message" }.

#Python SDK

The official SDK wraps the REST API with a small, Qiskit-friendly client. It's open source and published on PyPI.

PyPI · roro-quantum v0.3.0 Source on GitHub

# REST client only
pip install roro-quantum
# + Qiskit BackendV2 provider
pip install "roro-quantum[qiskit]"

from roro import RoRoClient
from qiskit import QuantumCircuit

roro = RoRoClient(api_key="qcs_live_…")

# discover targets
for m in roro.machines():
    print(m["targetId"], m["qubits"])

# build + submit a GHZ state, block until it finishes
qc = QuantumCircuit(3, 3)
qc.h(0); qc.cx(0, 1); qc.cx(1, 2)
qc.measure_all()
job = roro.submit_run("roro.sim.sv", shots=4000, circuit=qc, wait=True)
print(job["counts"])

# or submit without blocking, then poll yourself
job = roro.submit_run("roro.sim.sv", shots=4000, circuit=qc)
job = roro.wait_for_run(job["id"])  # or roro.run(job["id"])

Already on Qiskit? Use RoRo as a drop-in BackendV2 provider:

from qiskit import QuantumCircuit
from roro.provider import RoRoProvider

qc = QuantumCircuit(2, 2)
qc.h(0); qc.cx(0, 1); qc.measure_all()

backend = RoRoProvider(api_key="qcs_live_…").get_backend("roro.sim.sv")
result = backend.run(qc, shots=5000).result()
print(result.get_counts())

#JavaScript / TypeScript SDK

Roadmap  An isomorphic client for Node and the browser. The code lives in the repo and isn't on npm yet — until it ships, call the REST API directly (it's a couple of fetch calls). Here's the shape it will have:

// (coming soon) npm install @roro/quantum
import { RoRoClient } from "@roro/quantum";

const roro = new RoRoClient({ apiKey: "qcs_live_…" });

// submit a Bell state (OpenQASM 2.0)
const qasm = `OPENQASM 2.0;
include "qelib1.inc";
qreg q[2]; creg c[2];
h q[0]; cx q[0],q[1];
measure q -> c;`;
const job = await roro.submitAndWait("roro.sim.sv", { shots: 5000, qasm });
console.log(job.status, job.counts);
// completed { '00': 2500, '11': 2500 }

#Glossary