Scaluq

For the Japanese version of this README, see README_ja.md.

Scaluq is a newly redeveloped Python/C++ library based on the quantum circuit simulator Qulacs.
It enables high-speed simulation of large-scale quantum circuits, noisy quantum circuits, and parametric quantum circuits.
This library is released under the MIT License.

Compared to Qulacs, the following improvements have been made:

• Implementation based on Kokkos allows seamless switching between execution environments (CPU/GPU) without requiring code changes.
• Provides execution speeds comparable to Qulacs on CPU, and achieves equivalent or faster speeds on GPU.
• Pointers are hidden from users, making the code simpler and safer to write.
• Integration of nanobind enables lightweight and low-overhead Python bindings.
• Provides batched execution for efficiently applying quantum circuits with the same structure but different parameters to multiple quantum states.

Documentation

See https://scaluq.readthedocs.io/en/latest/index.html

Performance

The execution times of our quantum circuit simulator and several existing quantum circuit simulators were compared.
In this benchmark, a circuit consisting of CX, RX, and RZ gates applied sequentially to different target qubits was executed, and the average execution time was measured.

See the benchmark repository.

CPU: Single State Vector Update (June 2026)

CPU single thread	CPU multi thread

GPU: Single State Vector Update (August 2026)

GPU

Batched State Vector Update (June 2026)

Varying batch size (#qubits=16)	Varying #qubits (batch size=100)

Build Requirements

• Ninja ≥ 1.10
• GCC ≥ 13 or LLVM Clang ≥ 18
  • if you enable CUDA, GCC ≥ 11 is OK, but you cannot use Clang.
• CMake ≥ 3.24
• CUDA ≥ 12.8 (only when using CUDA)
• Python ≥ 3.10 (only when using Python)

When using CUDA, use a host compiler version supported by your CUDA toolkit (see the CUDA Installation Guide Host Compiler Support Policy).

Note: It may work with lower versions, but this has not been verified.

Runtime Requirements

• CUDA ≥ 12.8 (only when using CUDA)

Note: It may work with lower versions, but this has not been verified.

Build Options

Build options can be specified using environment variables when running script/configure or pip install ..

Installing as a C++ Library

To install Scaluq as a static C++ library, run the following commands:

git clone https://github.com/qulacs/scaluq
cd scaluq
script/configure
sudo -E env "PATH=$PATH" ninja -C build install

• Required libraries such as Eigen and Kokkos will be installed together.
• You can install to a location other than /usr/local/ by setting CMAKE_INSTALL_PREFIX. For example, if you want to install locally or avoid conflicts with other Kokkos builds:
  CMAKE_INSTALL_PREFIX=~/.local script/configure; ninja -C build install
• sudo is used to install files to /usr/local/, but to preserve the user environment, we use -E and explicitly pass PATH.
• If you want to build the CUDA-enabled version (when NVIDIA GPU and CUDA are available), set SCALUQ_USE_CUDA=ON. Example:
  SCALUQ_USE_CUDA=ON script/configure; sudo env -E "PATH=$PATH" ninja -C build install

When changing options and rebuilding, make sure to clear the CMake cache by running:

rm build/CMakeCache.txt

An example CMake configuration for a project using the installed Scaluq library is provided in example_project/.

Installing as a Python Library

Scaluq can also be used as a Python library:

pip install scaluq

If you want to use GPU or precisions other than f32 and f64, clone the repository and install with options:

git clone https://github.com/qulacs/scaluq
cd ./scaluq
SCALUQ_USE_CUDA=ON pip install .

Python Documentation

A simple documentation page is available with function descriptions and type information for the Python library version:
https://scaluq.readthedocs.io/en/latest/index.html

Sample Code (C++)

#include <cstdint>
#include <iostream>
#include <scaluq/circuit/circuit.hpp>
#include <scaluq/gate/gate_factory.hpp>
#include <scaluq/operator/operator.hpp>
#include <scaluq/state/state_vector.hpp>

int main() {
    scaluq::initialize();  // must be called before using any scaluq methods
    {
        constexpr scaluq::Precision Prec = scaluq::Precision::F64;
        constexpr scaluq::ExecutionSpace Space = scaluq::ExecutionSpace::Default;
        const std::uint64_t n_qubits = 3;
        scaluq::StateVector<Prec, Space> state =
            scaluq::StateVector<Prec, Space>::Haar_random_state(n_qubits, 0);
        std::cout << state << std::endl;

        scaluq::Circuit<Prec> circuit;
        circuit.add_gate(scaluq::gate::X<Prec>(0));
        circuit.add_gate(scaluq::gate::CNot<Prec>(0, 1));
        circuit.add_gate(scaluq::gate::Y<Prec>(1));
        circuit.add_gate(scaluq::gate::RX<Prec>(1, std::numbers::pi / 2));
        circuit.update_quantum_state(state);

        std::vector<scaluq::PauliOperator<Prec>> terms;
        terms.emplace_back(1, 0);
        scaluq::Operator<Prec, Space> observable(terms);
        auto value = observable.get_expectation_value(state);
        std::cout << value << std::endl;
    }
    scaluq::finalize();  // must be called last
}

By including scaluq/all.hpp, you can omit template arguments using SCALUQ_OMIT_TEMPLATE.

#include <cstdint>
#include <iostream>
#include <scaluq/all.hpp>

namespace my_scaluq {
SCALUQ_OMIT_TEMPLATE(scaluq::Precision::F64, scaluq::ExecutionSpace::Default)
}

using namespace my_scaluq;

int main() {
    scaluq::initialize();  // must be called before using any scaluq methods
    {
        const std::uint64_t n_qubits = 3;
        StateVector state = StateVector::Haar_random_state(n_qubits, 0);
        std::cout << state << std::endl;

        Circuit circuit;
        circuit.add_gate(gate::X(0));
        circuit.add_gate(gate::CNot(0, 1));
        circuit.add_gate(gate::Y(1));
        circuit.add_gate(gate::RX(1, std::numbers::pi / 2));
        circuit.update_quantum_state(state);

        std::vector<PauliOperator> terms;
        terms.emplace_back(1, 0);
        Operator observable(terms);
        auto value = observable.get_expectation_value(state);
        std::cout << value << std::endl;
    }
    scaluq::finalize();  // must be called last
}

Sample Code (Python)

from scaluq import StateVector, Circuit, PauliOperator, Operator
from scaluq import gate
import math

n_qubits = 3
state = StateVector.Haar_random_state(n_qubits, 0)

circuit = Circuit()
circuit.add_gate(gate.X(0))
circuit.add_gate(gate.CNot(0, 1))
circuit.add_gate(gate.Y(1))
circuit.add_gate(gate.RX(1, math.pi / 2))
circuit.update_quantum_state(state)

terms = [PauliOperator("Z 0")]
observable = Operator(terms)
value = observable.get_expectation_value(state)
print(value)

Specifying Precision and Execution Space

Scaluq supports multiple floating-point precisions: f16, f32, f64, and bf16.
By default, only f32 and f64 are enabled.
While f64 is generally recommended, lower precisions like f32 can be up to 2–4x faster in applications such as quantum machine learning that do not require high precision.

Note: With f16 / bf16 precision, the calculation error may be very large (sometimes larger than $0.1$). We do not test the accuracy with these options.

Execution spaces determine whether computation is performed on CPU or GPU:

Note: You can only perform operations between objects with the same precision and execution space. For example, a gate created for 32-bit precision cannot be used with a 64-bit StateVector, even if both are CPU-based.

In C++, classes like StateVector, Circuit, Gate, and Operator accept Precision and ExecutionSpace as template arguments.

In Python, top-level classes such as StateVector and Circuit, as well as gate factories in scaluq.gate, accept precision and space keyword arguments, defaulting to 'f64' and 'default' respectively.

from scaluq import StateVector, Circuit
from scaluq import gate

prec = 'f64'
space = 'default'

state = StateVector(3, precision=prec, space=space)
x = gate.X(0, precision=prec)
x.update_quantum_state(state)
print(state)