Extending CUDA-Q with a new Simulator¶

Backend circuit simulation in CUDA-Q is enabled via the NVQIR library (libnvqir). CUDA-Q code is ultimately lowered to the LLVM IR in a manner that is adherent to the QIR specification. NVQIR provides function implementations for the various declared functions in the specification, which in turn delegate to an extensible simulation architecture.

The primary extension point for NVQIR is the CircuitSimulator class. This class exposes an API that enables qubit allocation and deallocation, quantum operation invocation, and measurement and sampling. Subtypes of this class are free to override these methods to affect simulation of the quantum code in any simulation-strategy-specific manner (e.g., state vector, tensor network, etc.). Moreover, subtypes are free to implement simulators that leverage classical accelerated computing.

In this document, we’ll detail this simulator interface and walk through how to extend it for new types of simulation.

`CircuitSimulator`¶

The CircuitSimulator type is defined in runtime/nvqir/CircuitSimulator.h. It exposes a public API to libnvqir that is immediately subclassed in the CircuitSimulatorBase type. This type is templated on the floating point type used in the simulator’s computations (e.g. double,float). This templated type handles a lot of the base functionality required for allocating and deallocated qubits, as well as measurement, sampling, and observation under a number of execution contexts. This is the type that downstream simulation developers should extend.

The actual definition of the quantum state data structure, and its overall evolution are left as tasks for CircuitSimulatorBase subclasses. Examples of simulation subtypes can be found in runtime/nvqir/qpp/QppCircuitSimulator.cpp or runtime/nvqir/custatevec/CuStateVecCircuitSimulator.cpp. The QppCircuitSimulator models the state vector using the Q++ library, which leverages the Eigen::Matrix type and OpenMP threading for matrix-vector operations. The CuStateVecCircuitSimulator type models the state vector on an NVIDIA GPU device by leveraging the cuQuantum library.

The key methods that need to be overridden by subtypes of CircuitSimulatorBase are as follows:

Required Circuit Simulator Subtype Method Overrides¶
Method Name	Method Arguments	Method Description
`addQubitToState`	`void`	Add a qubit to the underlying state representation.
`addQubitsToState`	`nQubits : std::size_t`	Add the specified number of qubits to the underlying state representation.
`resetQubit`	`qubitIdx : std::size_t`	Reset the state of the qubit at the given index to `\|0>`
`resetQubitStateImpl`	`void`	Clear the entire state representation (reset to 0 qubits).
`applyGate`	`task : GateApplicationTask`	Apply the specified gate described by the `GateApplicationTask`. This type encodes the control and target qubit indices, optional rotational parameters, and the gate matrix data.
`measureQubit`	`qubitIdx : std::size_t -> bool` (returns bit result as bool)	Measure the qubit, produce a bit result, collapse the state.
`sample`	:code`qubitIdxs : std::vector<std::size_t>, shots : int`	Sample the current multi-qubit state on the provided qubit indices over a certain number of shots
`name`	`void`	Return the name of this CircuitSimulator, must be the same as the name used in `nvq++ -qpu NAME ...`

To extend a subtype class, you will need to create a new cpp implementation file with the same name as your subtype class name. In this file, you will subclass the CircuitSimulatorBase<FloatType> and implement the methods in the above table. Finally, the subclass must be registered with the NVQIR library so that it can be picked up and used when a user specifies nvq++ --target mySimulator ... from the command line (or cudaq.set_target('mySimulator') in Python.) Type registration can be performed with a provided NVQIR macro,

NVQIR_REGISTER_SIMULATOR(MySimulatorClassName, mySimulator)

where MySimulatorClassName is the name of your subtype, and mySimulator is the same name as what MySimulatorClassName::name() returns, and what you desire the -qpu NAME name to be.

A further requirement is that the code be compiled into its own standalone shared library with name libnvqir-NAME.{so,dylib}, where NAME is the same name as what MySimulatorClassName::name() returns, and what you desire the -qpu NAME name to be. You will also need to create a NAME.config file that contains the following contents

NVQIR_SIMULATION_BACKEND="NAME"

The library must be installed in $CUDA_QUANTUM_PATH/lib and the configuration file must be installed to $CUDA_QUANTUM_PATH/platforms.

Let’s see this in action¶

CUDA-Q provides some CMake utilities to make the creation of your new simulation library easier. Specifically, by using find_package(NVQIR), you’ll get access to a nvqir_add_backend function that will automate much of the boilerplate for creating your library and configuration file.

Let’s assume you want a simulation subtype named MySimulator. You can create a folder or repository for this code called my-simulator and add MySimulator.cpp and CMakeLists.txt files. Fill the CMake file with the following:

cmake_minimum_required(VERSION 3.24 FATAL_ERROR)
project(DemoCreateNVQIRBackend VERSION 1.0.0 LANGUAGES CXX)
find_package(NVQIR REQUIRED)
nvqir_add_backend(MySimulator MySimulator.cpp "")

and then fill out your MySimulator.cpp file with your subtype implementation. For example,

#include "CircuitSimulator.h"

namespace {

  class MySimulator : public nvqir::CircuitSimulatorBase<double> {

  protected:
    /// @brief Grow the state vector by one qubit.
    void addQubitToState() override { ... }

    /// @brief Grow the state vector by `count` qubit.
    void addQubitsToState(std::size_t count) override { ... }

    /// @brief Reset the qubit state.
    void resetQubitStateImpl() override { ... }

    /// @brief Apply the given gate
    void applyGate(const GateApplicationTask &task) override { ... }

  public:
    MySimulator() = default;
    virtual ~MySimulator() = default;

    bool measureQubit(std::size_t qubitIdx) override { ... }

    void resetQubit(std::size_t &qubitIdx) override { ... }

    cudaq::SampleResult sample(std::vector<std::size_t> &measuredBits,
                          int shots) override { ... }

    const std::string_view name() const override { return "MySimulator"; }

  };

} // namespace

/// Register this Simulator with NVQIR.
NVQIR_REGISTER_SIMULATOR(MySimulator)

To build, install, and use this simulation backend, run the following from the top-level of my-simulator:

export CUDA_QUANTUM_PATH=/path/to/cuda_quantum/install
mkdir build && cd build
cmake .. -G Ninja -DNVQIR_DIR="$CUDA_QUANTUM_PATH/lib/cmake/nvqir"
ninja install

Then given any CUDA-Q source file, you can compile and target your backend simulator with the following:

nvq++ file.cpp --target MySimulator
./a.out

Extending CUDA-Q with a new Simulator¶

CircuitSimulator¶

Let’s see this in action¶

`CircuitSimulator`¶