Welcome. This manual walks you through everything you do as a user of SoftQuantus Compute OS — from installing it, to your first quantum program, to running on a real quantum computer. No prior quantum-computing experience is assumed. Contents

What SoftQuantus Quantum OS is
Getting it — pick your install
First launch — the desktop
The apps, one by one
Your first quantum program
Bigger simulations with a GPU
Running on a real quantum computer
Power users — terminal, SDK, CLI
Managing your jobs and results
Settings you might change
Troubleshooting & FAQ
Getting help

1. What SoftQuantus Quantum OS is

SoftQuantus Compute OS is an operating system for quantum computing. It gives you:

a desktop to run quantum programs, watch results, and manage devices;
a control plane (QCOS) that connects to simulators, GPUs, and real quantum computers behind a single interface;
a terminal and SDK for scripting and automation.

One important idea: the OS orchestrates — it prepares your circuit, picks or routes to the right machine, runs it, and returns results. The split-second physics of controlling the qubits happens on the quantum computer’s own hardware. You never have to think about that; you just choose a backend (a machine to run on) and submit a job. Everything you run is a job: a circuit + how many times to run it (shots) + which backend. Results come back as counts — how often each measurement outcome occurred.

2. Getting it — pick your install

Choose the path that matches how you want to use it. You can start on your laptop in minutes and move to a dedicated machine later.

I want to…	Install	Works on
Try it on my laptop (no VM, no reboot)	WSL distribution	Windows 10/11
Try it as an app	Desktop app	macOS / Windows / Linux
Try it quickly with containers	Docker image	any OS with Docker
Run it on a machine / server	Bootable ISO or cloud image	bare metal, VM, AWS/Azure
Just use the API from my code	SDK	any OS

Try on Windows (WSL) — fastest

Double-click SoftQuantusOS.wsl, or in PowerShell:

wsl --import SoftQuantusOS %USERPROFILE%\SoftQuantusOS SoftQuantusOS.wsl
wsl -d SoftQuantusOS

You land in the SoftQuantus shell. Type sq-status to see your system.

Try as a desktop app (Mac/Windows/Linux)

Install the SoftQuantus Desktop app (.dmg / .exe / .AppImage). Launch it and the full desktop opens. (Developers can run it from source: cd packaging/desktop && npm install && npm start.)

Try with Docker

docker run --rm -it --hostname sq-compute softquantus/compute-os:demo

Run it on a machine

Install SoftQuantus Compute OS as the machine’s operating system from the bootable USB/ISO, or launch a cloud image (AWS AMI / Azure / qcow2). See the packaging guides for building those.

Full install-channel details and downloads: docs/oem/DISTRIBUTION.md and packaging/README.md.

3. First launch — the desktop

On first launch you’ll see a boot screen — the SoftQuantus logo, then a short startup log confirming the control plane is healthy, the device catalog is loaded, and the per-device scheduler is armed. This is the OS checking itself; every line is a real check. Then the desktop appears. On the left is a column of app icons; at the bottom is a taskbar with the QCOS start button (opens the app menu), the open windows, and a clock. Windows are draggable, resizable (drag the bottom-right corner) and maximizable (green dot, or double-click the title bar).

4. The apps, one by one

🟦 SoftQuantus OS Shell

A real Linux shell (Ubuntu 24.04 under the hood, rebranded). Use it like any terminal. Two SoftQuantus commands to know:

sq-status — shows your appliance identity: edition, base, kernel, GPU runtime, the compute planes (GPU simulation, HPC, QPU providers), and the control-plane address.
everything else is standard Linux (python3, pip, ls, …).

This is where you’d install the SDK (pip install softqcos) or run your own scripts.

🖥️ QSH Terminal (Quantum Shell)

A purpose-built quantum shell. Type help to list commands:

Command	What it does
`backends`	List every machine you can run on (the live catalog).
`run <id> [shots]`	Run a Bell (2-qubit entanglement) circuit on backend `<id>`.
`run3 <id> [shots]`	Run a GHZ (3-qubit entanglement) circuit.
`estimate <id>`	Cost/credits estimate for a backend.
`cert`	Run the certification suite against the installed device driver.
`sched`	Show the per-device scheduler state.
`health` / `ready`	Control-plane health probes.
`clear`	Clear the screen.

Example — run a Bell state on the free auto-simulator, 512 shots:

qcos@oem:~$ run auto_sim 512
  job=job_... status=completed
  |11⟩ ████████████████ 257
  |00⟩ ████████████████ 255
  provider=auto_sim exec=4.1ms simulated=true

🔌 Device Manager

Shows the catalog of backends: id, class (simulator / GPU / real QPU), qubit count, supplier, and online status. A real-QPU backend only shows online once its credentials are configured (see Settings).

⚛️ Quantum Jobs — the main way to run things

The visual job runner. You get:

a backend dropdown (every available machine),
a circuit dropdown — Bell (2q), GHZ (3q), or Custom QASM (paste your own OpenQASM 2.0),
a shots box,
▶ Run job.

Click Run job and you see the outcome: job id, status, round-trip time, provider, whether it was simulated, and a histogram of measurement counts. Two buttons demonstrate the OS’s safety guarantees on real hardware:

Try without payment reservation — on a real-QPU backend the job parks in approval_required (it won’t run without payment). On a simulator it just runs.
Try unknown backend — submitting a made-up backend id fails explicitly (“No runtime provider adapter”); the OS never silently runs your circuit somewhere you didn’t ask.

🛡️ Certification

Runs the ACOS-ISA v1.0 conformance suite (10 tests) against the device driver currently installed and shows PASS/FAIL per test and the overall “QCOS Compatible” result. This is what a hardware vendor uses to prove their QPU works correctly under the OS.

📈 System Monitor

Live health of the control plane (/health, /ready), the profile, and the per-device scheduler — which devices are busy, queue depth, and jobs completed. A quantum computer runs one job at a time; this is where you see that queue.

ℹ️ About

Edition, base OS, the installed device driver, and the SDK install command.

5. Your first quantum program

Let’s create entanglement — the “hello world” of quantum computing. In the desktop (easiest):

Open Quantum Jobs.
Backend: leave auto_sim (free, instant, no setup).
Circuit: Bell (2q). Shots: 1024.
Click ▶ Run job.

You’ll see a histogram where the outcomes 00 and 11 each get roughly half the shots, and 01 / 10 almost none. That’s entanglement: the two qubits always agree. What just happened: a Bell circuit puts qubit 0 into superposition (H gate) and entangles it with qubit 1 (CX gate). Measuring gives 00 or 11 with ~50/50 probability — never 01 or 10. Custom circuits: pick Custom QASM and paste OpenQASM 2.0, e.g. a 3-qubit GHZ:

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

Run it — now 000 and 111 split the shots.

6. Bigger simulations with a GPU

Small circuits run instantly on the CPU. For larger ones, use acceleration — no code change, just pick a different backend.

auto_sim — the smart default. It looks at your circuit and the hardware and picks the fastest method available, including your GPU if one is present. For most users this is all you need.
Local GPU — if your machine has an NVIDIA GPU with CUDA/cuQuantum installed, auto_sim uses it automatically. On the SoftQuantus appliance the GPU is wired in for you; on Windows/WSL it uses your Windows NVIDIA driver.
Remote GPU pools — for very large circuits, submit to a cloud GPU backend once your operator has configured it: lumi.mps (up to 127 qubits, weakly-entangled), aws_gpu_sv, aws.gpu.mps.

Rule of thumb: entangling circuits up to ~30 qubits fit on a statevector GPU; large lightly-entangled circuits go much higher with an MPS backend (*.mps). Full backend list: Add a GPU / Simulator.

7. Running on a real quantum computer

Simulators are free and unlimited. Running on real hardware is gated — by design, so a machine that costs money and time is never used by accident. Three things must be true:

The device must be enabled by your operator (the master real-QPU switch is on).
You must have a paid reservation — provide a reservation id with the job.
Your account tier must include QPU access.

If any is missing, the job parks in approval_required or is refused with a clear message (403 real_qpu_disabled, 402 qpu_payment_required, 403 plan_qpu_access_required) — it never silently runs and never silently falls back to a simulator. In the desktop: open Quantum Jobs, pick a real-QPU backend (e.g. ibm_brisbane — shown in red as REAL QPU), and run. Without a reservation you’ll see approval_required with an explanation. With a reservation and the device enabled, it executes on the real machine and the histogram shows simulated=false. What backends are real: anything the Device Manager marks REAL QPU — cloud machines (IBM, IonQ, Rigetti, Quantinuum, PASQAL via Azure/AWS) and any on-premise device your organization has connected. Connecting new machines is covered in Add a Quantum Computer.

8. Power users — terminal, SDK, CLI

Everything the desktop does is available from code, over the same API. Python SDK:

pip install softqcos

from softqcos import Client   # see the SDK README for the exact import
client = Client(api_key="sq-...", base_url="http://localhost:8377")
job = client.jobs.submit(
    backend_id="auto_sim", shots=1024,
    qasm='OPENQASM 2.0;\ninclude "qelib1.inc";\nqreg q[2];\ncreg c[2];\nh q[0];\ncx q[0],q[1];\nmeasure q -> c;',
    confirm_cost=True,
)
print(job["result"]["counts"])   # {"00": 511, "11": 513}

TypeScript SDK: npm install @softquantus/softqcos-sdk — client.coreJobs.submitJob({...}). Raw API (curl): the full request/response shapes and every endpoint are in the User Guide. Quantum shell (QSH): inside the desktop’s QSH Terminal, run, estimate, backends, etc. (section 4).

9. Managing your jobs and results

See a job: the Quantum Jobs history list, or GET /api/v1/runtime/jobs/{id}.
List your jobs: GET /api/v1/runtime/jobs.
Cancel a running job: DELETE /api/v1/runtime/jobs/{id}.
Live progress: GET /api/v1/runtime/jobs/{id}/events?stream=true.
Download artifacts: GET /api/v1/runtime/jobs/{id}/artifacts.
Results are the counts (measurement outcome → how many shots). For real-QPU runs you also get provenance (is_real_qpu, execution_mode) and, when a reference is available, a fidelity vs. the ideal outcome.

Jobs move through states: queued → running → completed (or failed / cancelled). Priced jobs may pass through approval_required → approved first.

10. Settings you might change

Most users never change anything — the defaults run simulators for free. If you’re setting up your own instance, the few settings that matter:

I want to…	Set
Connect my IBM account	`IBM_QUANTUM_TOKEN` (then restart)
Turn on real-QPU execution	`QCOS_REAL_QPU_ENABLED=true`
Run on-premise (no cloud)	`QCOS_PROFILE=onprem`
Keep job history persistently	`QCOS_RUNTIME_STORE_URL=postgresql://…`
Require login	`QCOS_AUTH_REQUIRED=true`

Settings are environment variables applied at startup — change one, restart the OS/service. The complete list, grouped by purpose, is in Configuration.

11. Troubleshooting & FAQ

A backend shows “offline” / not available. It needs credentials. E.g. IBM needs IBM_QUANTUM_TOKEN. See Configuration. My real-QPU job says approval_required and never runs. You didn’t include a payment reservation, or real-QPU execution is disabled. Section 7. “No runtime provider adapter for backend ’…’”. The backend id doesn’t exist. Run backends (QSH) or open Device Manager to see valid ids. This error is deliberate — the OS won’t guess where to run your circuit. Results look noisy on a real QPU. That’s real quantum hardware — it has noise. Compare against a simulator, or use error mitigation / QEC options. The desktop shell says Docker is needed. The SoftQuantus OS shell app runs a real container. Start Docker, or use the QSH Terminal (which needs no container). My circuit is too big / times out. Use a GPU or MPS backend (section 6), or reduce qubits/shots. Simulators have qubit limits per method. How much does it cost? Simulators are free (0 credits). Real QPUs are priced per provider — always estimate first, and you must confirm cost and provide a reservation before a paid run.

12. Getting help

This documentation: docs/guide/ — user manual, configuration, adding QPUs and GPUs, API reference.
Connecting hardware / GPUs: Add a Quantum Computer, Add a GPU / Simulator.
For QPU manufacturers: docs/oem/ — OEM edition and vendor onboarding.
Support: https://softquantus.com

Welcome to quantum computing with SoftQuantus. Run your first Bell state and go from there.

User Manual

Quantum operating system user manual

1. What SoftQuantus Quantum OS is

2. Getting it — pick your install

Try on Windows (WSL) — fastest

Try as a desktop app (Mac/Windows/Linux)

Try with Docker

Run it on a machine

3. First launch — the desktop

4. The apps, one by one

🟦 SoftQuantus OS Shell

🖥️ QSH Terminal (Quantum Shell)

🔌 Device Manager

⚛️ Quantum Jobs — the main way to run things

🛡️ Certification

📈 System Monitor

ℹ️ About

5. Your first quantum program

6. Bigger simulations with a GPU

7. Running on a real quantum computer

8. Power users — terminal, SDK, CLI

9. Managing your jobs and results

10. Settings you might change

11. Troubleshooting & FAQ

12. Getting help

​1. What SoftQuantus Quantum OS is

​2. Getting it — pick your install

​Try on Windows (WSL) — fastest

​Try as a desktop app (Mac/Windows/Linux)

​Try with Docker

​Run it on a machine

​3. First launch — the desktop

​4. The apps, one by one

​🟦 SoftQuantus OS Shell

​🖥️ QSH Terminal (Quantum Shell)

​🔌 Device Manager

​⚛️ Quantum Jobs — the main way to run things

​🛡️ Certification

​📈 System Monitor

​ℹ️ About

​5. Your first quantum program

​6. Bigger simulations with a GPU

​7. Running on a real quantum computer

​8. Power users — terminal, SDK, CLI

​9. Managing your jobs and results

​10. Settings you might change

​11. Troubleshooting & FAQ

​12. Getting help

1. What SoftQuantus Quantum OS is

2. Getting it — pick your install

Try on Windows (WSL) — fastest

Try as a desktop app (Mac/Windows/Linux)

Try with Docker

Run it on a machine

3. First launch — the desktop

4. The apps, one by one

🟦 SoftQuantus OS Shell

🖥️ QSH Terminal (Quantum Shell)

🔌 Device Manager

⚛️ Quantum Jobs — the main way to run things

🛡️ Certification

📈 System Monitor

ℹ️ About

5. Your first quantum program

6. Bigger simulations with a GPU

7. Running on a real quantum computer

8. Power users — terminal, SDK, CLI

9. Managing your jobs and results

10. Settings you might change

11. Troubleshooting & FAQ

12. Getting help