Run a quantum circuit offline with the CLI

This page runs a real quantum circuit on your own machine and prints real sampled measurement counts. At the end you will have a Bell state simulated locally, in under a second, with no account, no credits, no queue and no network connection.

That is the concrete value: you can sanity-check a small circuit on a plane, or in a CI job with no secrets, before you ever think about hardware.

Run the Bell state example

Save this as bell.qasm:


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

Then run it:


synapsex-code lab run bell.qasm --sim --shots 100 --seed 7

Observed output:


mode=sim (local, off-ledger, $0)  file=bell.qasm
qubits=2  shots=100
counts:
  11  57  (57.0%)
  00  43  (43.0%)

The mode=sim (local, off-ledger, $0) banner is the CLI telling you exactly what happened: simulation only, on this machine, nothing billed.

The command and its defaults


synapsex-code lab run <file.qasm> --sim

--sim is also what you get when you pass no --backend, so synapsex-code lab run bell.qasm runs the local simulator too.

Flag	Default	Notes
`--sim`	off	Free local OpenQASM simulator, `$0`, off-ledger, offline
`--shots <n>`	`1024`	Clamped to the range 1–4096
`--seed <n>`	random	Simulator only; makes the sampled counts reproducible

What the simulator supports

The local simulator implements a small subset of OpenQASM 2.0, and unknown gates are silently ignored rather than reported as an error. A circuit that uses an unsupported gate will still produce a plausible-looking distribution — it will just be the wrong one. Check your gate list against the table below before you trust any result.

	Behaviour
Supported gates	`h`, `x`, `z`, `s`, `cx`
Handled structural lines	`OPENQASM`, `include`, `qreg`, `creg`, `measure`, `barrier`
Maximum qubits	24
Unknown gates	Silently ignored (no error, no warning)
Out-of-range operands	Skipped

If your circuit needs anything outside that list, this simulator is not the right tool for it — the numbers it prints would be meaningless.

Make results reproducible

Pass a fixed --seed and the sampled counts are deterministic, which is what makes this usable as a test assertion:


synapsex-code lab run bell.qasm --sim --shots 100 --seed 7

Run it twice and you get identical counts. Change the seed and you get a different sample of the same distribution.

Script it

The command exits 0 on a successful simulation and non-zero when it fails — for example when the file does not exist, or when the circuit declares more qubits than the simulator supports. That makes it safe to chain:


if synapsex-code lab run bell.qasm --sim --shots 1024 --seed 1 > counts.txt; then
  echo "simulation ok"
else
  echo "simulation failed" >&2
  exit 1
fi

What about real hardware?

Paid backends are not run from your machine. They are submitted through a server-side cost gate that estimates the cost first and parks anything over your budget policy until you confirm it, so a run cannot silently overspend.

The free local simulator documented on this page is the path that works today with nothing but the installed binary. For the local file runner — the same command shape, for Python and other source files — see Run local files through the CLI lab runner.