Getting Started with QSDK

The Qniverse SDK is a Python-based toolkit developed and maintained by the Centre for Development of Advanced Computing (C-DAC) that enables users to model, visualize, and execute quantum circuits on a variety of simulators. It provides intuitive APIs for gate-level circuit construction, quantum register management, transpilation to various backends, and seamless remote job submission. The SDK features advanced gate validation, module composition, and circuit drawing capabilities, making it an ideal tool for education, prototyping, and research in quantum computing.

The SDK is the primary software interface to the Qniverse platform enabling users to run quantum workloads on CPU, GPU and backed simulators hosted on PARAM Supercomputers and the QACC cluster. It also provides a structured and extensible workflow that covers the complete quantum program lifecycle—from circuit construction and gate application to backend execution and result analysis. It abstracts low-level backend details while maintaining flexibility for advanced customization.

Changelog

This changelog records all notable changes to the Qniverse SDK organized by version. The SDK follows semantic versioning (MAJOR.MINOR.PATCH).

[1.0.0] - 2026-03-05

Added

• Initial release of qniverse

• Basic package structure

• Core dependencies

Installation and Troubleshooting

The Qniverse SDK requires Python 3.8 or higher.The Qniverse SDK is distributed as a standard Python package. The installation process is identical across all platforms and uses pip, the Python package installer.

Installation on Windows

Ensure Python 3.8+ is installed and added to the PATH environment variable during setup.

1. Open Command Prompt or PowerShell as Administrator

2. Verify Python installation:

python --version
# Expected: Python 3.8.x or higher

3. Verify pip is available:

pip --version
# Expected: pip 21.x or higher

4. Install the Qniverse SDK:

pip install qniverse

5. Verify the installation:

qniverse --version

Windows Troubleshooting

• ‘python’ not recognized: Python is not in PATH. Re-run the Python installer, tick ‘Add Python to PATH’, or manually add C:Users<YourName>AppDataLocalProgramsPythonPython3xto the PATH environment variable.

• ‘pip’ not recognized: Add the Scripts folder to PATH: C:Users<YourName>AppDataLocalProgramsPythonPython3xScripts

• Permission denied: Run Command Prompt as Administrator or use pip install –user qniverse

• Multiple Python installations causing confusion about which interpreter runs the code.

Installation on Linux

1. Update package lists and ensure Python 3 and pip are installed:

sudo apt update
sudo apt install python3 python3-pip python3-venv -y

2. Install the Qniverse SDK:

pip install qniverse

3. Install the Qniverse SDK:

qniverse --version

Linux Troubleshooting

• ModuleNotFoundError after install: Ensure you activated the virtual environment, if u have created, before running your script. Run ‘source ~/qniverse_env/bin/activate’ first.

• Permission denied during pip install: Do not use sudo pip. Instead use pip install –user qniverse or create a virtual environment.

• Missing build tools: Run: sudo apt install python3-dev build-essential libffi-dev

Installation on macOS

1. Install Homebrew if not present (recommended package manager):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Python via Homebrew:

brew install python

3. Install the Qniverse SDK:

pip install qniverse

4. Verify:

python3 -c "import qniverse; qniverse --version"

macOS Troubleshooting

• ‘command not found: python’: macOS defaults to python3. Use python3 explicitly, or alias it: echo ‘alias python=python3’ >> ~/.zshrc && source ~/.zshrc

• Apple Silicon (M1/M2): If a dependency fails with ‘architecture mismatch’, ensure you are using a native arm64 Python build from Homebrew, not the Rosetta-based Intel build.

• Homebrew PATH not found: Add to ~/.zshrc: export PATH=”/opt/homebrew/bin:$PATH”

If you encounter ModuleNotFoundError for any imported library like numpy , requests , svgwrite , cirq , or qsimcirq , ensure that:

• The package is installed inside that environment.

• You run the script with the same interpreter that owns the venv.

Software Dependencies and Prerequisites

These packages are automatically installed by pip when you install qniverse. They are listed here for reference and manual troubleshooting.

Package	Min Version	Purpose
numpy	1.21	Gate matrix operations and state-vector math
requests	2.25	HTTP communication with the Qniverse REST API
svgwrite	1.4	SVG circuit diagram generation
IPython	7.0	Inline SVG display in Jupyter Notebooks (optional)
tabulate	0.10.0	A Python library used to print data in formatted table structures

Supported Platforms

CPU

• qasm_Simulator

• aer_Simulator_density_matrix

• aer_Simulator_statevector

• Cirq_Simulator

• quest_simulator

• qsimcirq_simulator

• qulacs_multicpu_simulator

• cdac_photonics_simulator

Listed here are the CPU options available for the Param Utkarsh

• qasm_Simulator

• aer_Simulator_density_matrix

• aer_Simulator_statevector

• Cirq_Simulator

GPU

Aer_StateVector_simulator_GPU: Aer_StateVector_simulator_GPU is a feature within the Qiskit Aer framework that allows you to leverage the power of your GPU to perform state vector simulations of quantum circuits. State vector simulation involves calculating the complete quantum state of a system after a circuit is applied.

Qiskit Aer: Aer is a high-performance simulator for quantum circuits included in the Qiskit library. It provides various simulation methods, including state vector simulation.

State vector Simulation: This type of simulation calculates the entire state vector of a quantum circuit. The state vector holds the amplitudes (complex numbers representing probabilities) of finding the system in each possible basis state after applying the circuit.

GPU Acceleration: Aer_StateVector_simulator_GPU utilizes the NVIDIA cuStateVec library, which offers optimized kernels for state vector simulation on GPUs. This significantly speeds up simulations compared to CPU-based approaches, especially for larger circuits.

Faster Simulations: Running state vector simulations on GPUs can lead to significant speedups compared to CPU simulations, particularly for complex circuits with many qubits.

Improved Scalability: Leveraging GPUs allows you to handle larger quantum circuits that might be impractical to simulate on CPUs due to resource limitations.

Nvidia_cudaq_statevector_simulator:

The NVIDIA CUDA-Q Statevector Simulator is a high-performance tool that uses NVIDIA GPUs to accelerate simulations of quantum circuits. Its key features—such as GPU acceleration, scalability, precision, and seamless integration with the CUDA ecosystem—make it an invaluable resource for researchers and developers working on quantum computing applications.

Key Features:

GPU Acceleration: Leverages the parallel processing power of NVIDIA GPUs to significantly speed up quantum circuit simulations. This is crucial for handling larger circuits and more complex simulations that would be prohibitively slow on CPUs alone.

State vector Representation: Stores and manipulates the quantum state as a complex-valued vector. This allows for accurate simulation of quantum circuits and enables calculations of various properties of the quantum system.

Scalability: Supports scaling simulations across multiple GPUs and even multiple nodes in a cluster. This enables researchers to tackle larger and more complex problems that exceed the memory capacity of a single GPU.

Precision: Offers options for both single-precision (FP32) and double-precision (FP64) simulations. This allows users to choose the appropriate level of precision for their simulations, balancing accuracy with performance.

Integration with CUDA-Q: Seamlessly integrates within the NVIDIA CUDA-Q framework. This allows users to leverage other CUDA-Q features like custom kernel definitions and integration with other CUDA libraries.

Efficient Memory Management: Optimizes memory usage to minimize data transfer between CPU and GPU, further improving performance.

qsimcirq_simulator_cuquantum_gpu_simulator:

qsimcirq can integrate with NVIDIA’s cuQuantum SDK to provide a GPU-accelerated simulator for quantum circuits.

Here’s a breakdown of what that means:

qsimcirq: This is a Python interface for qsim, Google Quantum AI’s high-performance quantum circuit simulator. It qsim is written in C++ and is optimized for classical hardware, leveraging techniques like gate fusion, vectorized instructions (AVX/FMA), and multithreading (OpenMP). It’s designed to be faster than the default Cirq simulator and can simulate a larger number of qubits (up to around 40 on powerful workstations).

cuQuantum: This is NVIDIA’s software development kit (SDK) designed to accelerate quantum circuit simulations on NVIDIA GPUs. It provides highly optimized GPU-accelerated libraries for quantum computing, including:

cuStateVecFor state-vector simulations.

cuTensorNetFor tensor network-based simulations.

Integration: Google and NVIDIA have collaborated to integrate qsim with the cuQuantum SDK. This means that qsimcirq Users can leverage the power of NVIDIA GPUs to significantly speed up their quantum circuit simulations, especially for larger circuits.

Operating System

The SDK is compatible with:

• Windows (where Python and pip are available).

• Linux distributions (with Python and build tools).

• MacOS (with Python and compatible wheels).

---