Simulators and GPU accelerators are just backends — you select one with backend_id in a job. This guide lists every simulator/GPU backend, the auto-selecting engine, and how GPUs are wired into the appliance.

​
The simplest choice: auto_sim

Submit to auto_sim (aliases auto, simulate) and QCOS’s unified engine profiles your circuit and picks the best method available on the host — including GPU when present. No configuration, no credentials.

​
Every simulator / GPU backend

Pick a specific one by its backend id (any alias works):
The cloud GPU backends (lumi_*, aws_gpu_*) use an Azure Queue as job transport — that’s why they require AZURE_STORAGE_CONNECTION_STRING in addition to any cloud credentials. AWS GPU also needs AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY.

​
How the engine auto-selects (and finds the GPU)

The unified SimulationEngine (src/core/simulation/) detects hardware by import probe — no env vars: it looks for cupy, cuquantum, cudaq, reads GPU name and free memory via CuPy, and detects CPU SIMD (AVX-512/AVX2/SSE). Its decision tree, roughly:
  • Clifford-only → clifford (up to 10 000 qubits)
  • ≤ 28 qubits → C++ statevector (statevector_cpp) if the engine is built, else NumPy
  • GPU present and ≤ 40 qubits (and the state fits in free GPU memory) → GPU statevector — statevector_custatevec if cuQuantum is present, else CuPy (statevector_gpu)
  • Low entanglement, ≤ 2000 qubits → MPS (GPU MPS if cuQuantum+GPU)
  • Noisy circuits → density matrix (GPU density matrix if GPU and ≤ 16q)
Every GPU path falls back to NumPy if the GPU libraries or memory aren’t available — a job never fails just because a GPU is absent. So “adding a GPU” to local simulation is simply: make CuPy / cuQuantum importable in the runtime, and the engine uses it automatically.

​
Wiring a GPU into the appliance (bare-metal / cloud)

The SoftQuantus Compute OS provisioning (packaging/provision/softquantus-provision.sh) handles the host side:
  • Auto-detects the GPU (lspci | grep nvidia). Override with SQOS_WITH_NVIDIA=1 (force) or 0 (skip).
  • When a GPU is present it installs the NVIDIA Container Toolkit, runs nvidia-ctk runtime configure --runtime=docker, and restarts Docker — so containers get GPU passthrough (docker run --gpus all …).
  • When no GPU is found it logs “simulators run on CPU” and continues.
GPU simulation then runs inside versioned containers (the container-first model), e.g. softquantus/qiskit-aer-gpu, pennylane-lightning, cuda-q. Public backend ids use QCOS names (qcos-gpu-statevector, qcos-aer-gpu, qcos-mps, …) rather than vendor SDK names.

​
On WSL (Windows developers)

No toolkit step: GPU works through the Windows NVIDIA driver (CUDA-on-WSL). Install CUDA/cuQuantum inside the distro and the engine picks it up.

​
Choosing a GPU backend explicitly

  • Local GPU (the box QCOS runs on): submit to auto_sim — the engine uses the GPU if CuPy/cuQuantum are importable.
  • Remote GPU pool (LUMI / AWS): set the supplier’s credentials, then submit to lumi_aer_gpu, lumi.mps, aws_gpu_sv, or aws.gpu.mps.
Enabling / disabling the GPU suppliers and their exact credential variables: Configuration.