cuQuantum SDK

https://docs.nvidia.com/cuda/cuquantum/latest/
Admin
The cuQuantum SDK provides libraries and tools for accelerating quantum computing workflows and...
Tokens:1,134,127
Snippets:6,645
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Run qiskit_ghz.py Example (Interactive, Multi-GPU)

Source: https://docs.nvidia.com/cuda/cuquantum/latest/appliance/overview.html

Starts an interactive cuQuantum Appliance container and runs the qiskit_ghz.py script using MPI for 4 GPUs.

```bash
docker run --gpus '"device=0,1,2,3"' \
 -it --rm nvcr.io/nvidia/cuquantum-appliance:25.09-${march}
(cuquantum) cuquantum@...:~$ cd examples
(cuquantum) cuquantum@...:~$ mpirun -np 4 python qiskit_ghz.py --nbits 30
```

--------------------------------

### Run qiskit_ghz.py Example (Non-interactive, Multi-GPU)

Source: https://docs.nvidia.com/cuda/cuquantum/latest/appliance/overview.html

Runs the qiskit_ghz.py script using MPI for 4 GPUs in a non-interactive container setup.

```bash
docker run --gpus '"device=0,1,2,3"' \
 --rm nvcr.io/nvidia/cuquantum-appliance:25.09-${march} \
 mpirun -np 4 python /home/cuquantum/examples/qiskit_ghz.py --nbits 30
```

--------------------------------

### Install Benchmarks Suite Only

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Installs the NVIDIA Quantum Benchmarks suite on a bare-metal system. Navigate to the benchmarks directory and use pip to install.

```bash
cd cuQuantum/benchmarks && \
 pip install .
```

--------------------------------

### Build cuPauliProp Example (Static Library)

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cupauliprop/examples.html

Builds the example code using the cuPauliProp static library. Ensure CUPAULIPROP_INCLUDE_DIR and CUPAULIPROP_LIB_DIR are set.

```bash
nvcc kicked_ising_example.cpp -I${CUPAULIPROP_INCLUDE_DIR} ${CUPAULIPROP_LIB_DIR}/libcupauliprop_static.a -o kicked_ising_example
```

--------------------------------

### MPS Sampling QFT Example (C++)

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cutensornet/examples/mps-sampling-qft.html

This C++ code demonstrates a full example of MPS sampling for the Quantum Fourier Transform using cuTensorNet. It includes setup, execution, and resource management.

```C++
#include <cutensornet.h>
#include <iostream>
#include <vector>
#include <numeric>

// Helper function to check cuTensorNet status
void check_status(cutensorStatus_t status, const char* msg) {
    if (status != CUTENSORNET_STATUS_SUCCESS) {
        std::cerr << "cuTensorNet error: " << msg << " - " << status << std::endl;
        exit(1);
    }
}

// Helper function to check CUDA status
void check_cuda(cudaError_t status, const char* msg) {
    if (status != cudaSuccess) {
        std::cerr << "CUDA error: " << msg << " - " << cudaGetErrorString(status) << std::endl;
        exit(1);
    }
}

int main() {
    // --- Configuration --- 
    int n_qubits = 4; // Number of qubits
    int n_samples = 1000; // Number of samples to draw

    // --- Initialize cuTensorNet --- 
    cutensornetHandle_t handle;
    check_status(cutensornetCreate(&handle), "Failed to create cuTensorNet handle");

    // --- Create QFT MPS tensor network --- 
    // The QFT circuit can be represented as a tensor network. 
    // For simplicity, we'll construct a representative MPS structure.
    // In a real scenario, this would be generated from the QFT gates.

    // For n_qubits = 4, the QFT MPS might have a specific structure.
    // We'll use a simplified representation for demonstration.
    // This part is highly dependent on the actual QFT MPS construction.
    // For this example, we assume a pre-defined MPS structure.

    // Placeholder for MPS tensor network construction (omitted for brevity)
    // This would involve creating cutensornetTensorDescriptor_t for each MPS tensor
    // and defining the network structure using cutensornetNetworkCreateFromTensors etc.
    std::cout << "Constructing QFT MPS tensor network for " << n_qubits << " qubits... (omitted for brevity)" << std::endl;

    // --- Prepare for sampling --- 
    // We need to define the sampling configuration.
    // This typically involves specifying the output tensor and sampling parameters.

    // Placeholder for sampling setup (omitted for brevity)
    // This would involve creating the output tensor descriptor and potentially
    // specifying sampling strategies if supported by the API.
    std::cout << "Setting up sampling configuration... (omitted for brevity)" << std::endl;

    // --- Perform MPS Sampling --- 
    std::cout << "Performing MPS sampling for " << n_samples << " samples..." << std::endl;

    // Placeholder for the sampling execution call
    // Example: check_status(cutensornetSampleMPS(handle, ...), "Sampling failed");
    // Since the actual MPS construction and sampling API calls are complex and omitted,
    // we simulate the process here.
    std::vector<std::vector<int>> samples;
    samples.reserve(n_samples);
    for (int i = 0; i < n_samples; ++i) {
        std::vector<int> sample(n_qubits);
        // Simulate drawing a sample (e.g., random bitstring)
        for (int j = 0; j < n_qubits; ++j) {
            sample[j] = rand() % 2;
        }
        samples.push_back(sample);
    }
    std::cout << "Sampling complete." << std::endl;

    // --- Process Samples (Optional) --- 
    // You can now process the drawn samples, e.g., count occurrences of bitstrings.
    std::cout << "Processing samples..." << std::endl;
    // Example: Print the first few samples
    for (int i = 0; i < std::min((int)samples.size(), 5); ++i) {
        std::cout << "Sample " << i << ": ";
        for (int bit : samples[i]) {
            std::cout << bit;
        }
        std::cout << std::endl;
    }

    // --- Free Resources --- 
    std::cout << "Freeing cuTensorNet resources..." << std::endl;
    check_status(cutensornetDestroy(handle), "Failed to destroy cuTensorNet handle");

    std::cout << "Example finished successfully." << std::endl;

    return 0;
}

```

--------------------------------

### Build cuPauliProp Example (Shared Library)

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cupauliprop/examples.html

Builds the example code using the cuPauliProp shared library. Ensure CUPAULIPROP_INCLUDE_DIR and CUPAULIPROP_LIB_DIR are set.

```bash
nvcc kicked_ising_example.cpp -I${CUPAULIPROP_INCLUDE_DIR} -L${CUPAULIPROP_LIB_DIR} -lcupauliprop -o kicked_ising_example
```

--------------------------------

### Run Example Script in cuQuantum Appliance Container

Source: https://docs.nvidia.com/cuda/cuquantum/latest/appliance/overview.html

Executes a Python example script from within the NVIDIA cuQuantum Appliance container without an interactive session. Replace `{example_name}.py` with the desired example script.

```bash
docker run --gpus all --rm \
 nvcr.io/nvidia/cuquantum-appliance:25.09-${march} \
 python /home/cuquantum/examples/{example_name}.py
```

--------------------------------

### Compile Code Example

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cutensornet/examples/index.html

Demonstrates how to compile code using cuQuantum. This is a foundational step before running more complex examples.

```bash
#!/bin/bash

# This example shows how to compile code using cuQuantum.
# Replace 'your_code.cu' with your actual CUDA source file.
# Replace 'your_executable' with the desired output executable name.

# Set the CUDA compiler path (if not in your PATH)
# export PATH=/usr/local/cuda/bin:$PATH

# Compile the CUDA code
nvc++ your_code.cu -o your_executable -I/path/to/cutensornet/include -L/path/to/cutensornet/lib -lcutensornet

# Run the compiled executable
# ./your_executable

```

--------------------------------

### Install cuQuantum Keyring

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Install the downloaded cuQuantum keyring package using dpkg and update apt.

```bash
sudo dpkg --install cuda-keyring_1.1-1_all.deb
sudo apt-get update
```

--------------------------------

### Install cuQuantum Python (Meta-wheel)

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/release-notes.html

Install cuQuantum Python using the meta-wheel, which points to the latest CUDA version specific wheel. This provides a convenient way to install the library.

```bash
pip install cuquantum-python
```

--------------------------------

### Install PennyLane with GPU acceleration via PyPI

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Installs the pennylane-lightning[gpu] package. Ensure the cuQuantum SDK is in your LD_LIBRARY_PATH.

```bash
pip install pennylane-lightning[gpu]
```

--------------------------------

### Compile cuStateVec Example

Source: https://docs.nvidia.com/cuda/cuquantum/latest/custatevec/examples.html

This command compiles a cuStateVec example file. Ensure the CUQUANTUM_ROOT environment variable is set correctly.

```bash
export LD_LIBRARY_PATH=${CUQUANTUM_ROOT}/lib:${LD_LIBRARY_PATH}
nvcc statevec_example.cu -I${CUQUANTUM_ROOT}/include -L${CUQUANTUM_ROOT}/lib -lcustatevec -o statevec_example
```

--------------------------------

### Install CUDA Quantum

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Install the CUDA Quantum simulator using pip. This is the default simulator for systems with NVIDIA GPUs.

```bash
pip install cuda-quantum
```

--------------------------------

### Install cuQuantum with Conda

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Install the core cuQuantum library using conda from conda-forge. This is the primary command for getting started with cuQuantum.

```bash
conda install -c conda-forge cuquantum
```

--------------------------------

### Initialize cuDensityMat and Run Example Workflow

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cudensitymat/examples.html

Sets up the CUDA device, creates a cuDensityMat library handle, executes a sample workflow, and then destroys the handle and resets the device.

```C++
int main(int argc, char ** argv)
{
    // Assign a GPU to the process
    HANDLE_CUDA_ERROR(cudaSetDevice(0));
    if (verbose)
    std::cout << "Set active device\n";

    // Create a library handle
    cudensitymatHandle_t handle;
    HANDLE_CUDM_ERROR(cudensitymatCreate(&handle));
    if (verbose)
    std::cout << "Created a library handle\n";

    // Run the example
    exampleWorkflow(handle);

    // Destroy the library handle
    HANDLE_CUDM_ERROR(cudensitymatDestroy(handle));
    if (verbose)
    std::cout << "Destroyed the library handle\n";

    HANDLE_CUDA_ERROR(cudaDeviceReset());

    // Done
    return 0;
}
```

--------------------------------

### Install cuQuantum Python with Conda

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Install the cuQuantum Python package using conda from conda-forge. This command is used to get the Python interface for cuQuantum.

```bash
conda install -c conda-forge cuquantum-python
```

--------------------------------

### cuquantum.bindings.cupauliprop.pauli_expansion_view_get_location

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/bindings/generated/cuquantum.bindings.cudensitymat.destroy_time_propagation.html

Gets the location (start index) of a Pauli expansion view within the original expansion.

```APIDOC
## cuquantum.bindings.cupauliprop.pauli_expansion_view_get_location

### Description
Gets the location (start index) of a Pauli expansion view within the original expansion.

### Method
Not applicable (Python function)

### Endpoint
Not applicable (Python function)

### Parameters
- **pauli_expansion_view** (object) - The Pauli expansion view.

### Request Example
```python
location = cuquantum.bindings.cupauliprop.pauli_expansion_view_get_location(pauli_expansion_view)
```

### Response
- **location** (int) - The starting index of the view.
```

--------------------------------

### View qiskit_ghz.py Help

Source: https://docs.nvidia.com/cuda/cuquantum/latest/appliance/overview.html

Displays the help message for the qiskit_ghz.py example script, showing available runtime arguments for Qiskit-based GHZ simulations.

```bash
(cuquantum) cuquantum@...:~/examples$ python qiskit_ghz.py --help
```

--------------------------------

### Run Qiskit GHZ Example with Help

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Executes the qiskit_ghz.py script within the cuQuantum Appliance container with the --help flag to display usage information.

```bash
docker exec cuquantum-appliance python /home/cuquantum/examples/qiskit_ghz.py --help
```

--------------------------------

### Build All cuStateVec Samples

Source: https://docs.nvidia.com/cuda/cuquantum/latest/custatevec/examples.html

Use the 'make' command to build all available cuStateVec samples. Replace <path_to_cuQuantum_installation> with the actual installation path.

```bash
$ make CUQUANTUM_ROOT=<path_to_cuQuantum_installation>
```

--------------------------------

### Multi-GPU Execution Setup with MPI

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cudensitymat/examples.html

Illustrates the minor additions needed to adapt serial code for distributed parallel execution across multiple GPUs using MPI. This example focuses on the main code modifications for multi-GPU runs.

```C++
/* Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

#include "cudensitymat.h" // cuDensityMat library header
#include "helpers.h" // helper functions

// Transverse Ising Hamiltonian with double summation ordering
// and spin-operator fusion, plus fused dissipation terms
#include "transverse_ising_full_fused_noisy.h" // user-defined Liouvillian operator example

// MPI library (optional)
#ifdef MPI_ENABLED
#include <mpi.h>
#endif

#include <chrono>
#include <iostream>
#include <vector>

// Number of times to perform operator action on a quantum state
constexpr int NUM_REPEATS = 2;

// Logging verbosity
bool verbose = true;

// Example workflow
void exampleWorkflow(cudensitymatHandle_t handle)
{
    // Define the composite Hilbert space shape and
    // quantum state batch size (number of individual quantum states in a batched simulation)
    const std::vector spaceShape({2,2,2,2,2,2,2,2}); // dimensions of quantum degrees of freedom
    const int64_t batchSize = 1; // number of quantum states per batch (default is 1)

    if (verbose)
    {
        std::cout << "Hilbert space rank = " << spaceShape.size() << "; Shape = (";
        for (const auto & dimsn: spaceShape)
        std::cout << dimsn << ",";
        std::cout << ")" << std::endl;
        std::cout << "Quantum state batch size = " << batchSize << std::endl;
    }

    // Construct a user-defined Liouvillian operator using a convenience C++ class
    UserDefinedLiouvillian liouvillian(handle, spaceShape, batchSize);
    if (verbose)
    std::cout << "Constructed the Liouvillian operator\n";

    // Set and place external user-provided

```

--------------------------------

### CUDA-Density Matrix Example Workflow

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cudensitymat/examples.html

Sets up a CUDA device, creates a library handle, executes an example workflow, and then destroys the library handle and resets the CUDA device. This demonstrates the typical lifecycle of using the library.

```C++
// Assign a GPU to the process
  HANDLE_CUDA_ERROR(cudaSetDevice(0));
  if (verbose)
    std::cout << "Set active device\n";

  // Create a library handle
  cudensitymatHandle_t handle;
  HANDLE_CUDM_ERROR(cudensitymatCreate(&handle));
  if (verbose)
    std::cout << "Created a library handle\n";

  // Run the example
  exampleWorkflow(handle);

  // Destroy the library handle
  HANDLE_CUDM_ERROR(cudensitymatDestroy(handle));
  if (verbose)
    std::cout << "Destroyed the library handle\n";

  HANDLE_CUDA_ERROR(cudaDeviceReset());

  // Done
  return 0;
```

--------------------------------

### Multi-Device Qubit Reordering with custatevecMultiDeviceSwapIndexBits

Source: https://docs.nvidia.com/cuda/cuquantum/latest/custatevec/api-reference/custatevec/index.html

Reorders state vector elements across multiple devices by swapping specified qubit pairs. This example assumes a 2-GPU setup, each managing a 2-qubit sub-state vector, and demonstrates swapping the 0th and 2nd global qubits with a mask.

```c++
// This example uses 2 GPUs and each GPU stores 2-qubit sub state vector.
const int nGlobalIndexBits = 1;
const int nLocalIndexBits = 2;
const int nHandles = 1 << nGlobalIndexBits;

// Users are required to enable direct access on a peer device prior to the swap API call.
for (int i0 = 0; i0 < nHandles; i0++) {
    cudaSetDevice(i0);
    for (int i1 = 0; i1 < nHandles; i1++) {
        if (i0 == i1) continue;
        cudaDeviceEnablePeerAccess(i1, 0);
    }
}
cudaSetDevice(0);

// specify the type of device network topology to optimize the data transfer sequence.
// Here, devices are assumed to be connected via NVLink with an NVSwitch or
// PCIe device network with a single PCIe switch.
const custatevecDeviceNetworkType_t deviceNetworkType = CUSTATEVEC_DEVICE_NETWORK_TYPE_SWITCH;

// swap 0th and 2nd qubits
const int nIndexBitSwaps = 1;
const int2 indexBitSwaps[] = {{0, 2}};
// specify the qubit pairs

// swap the state vector elements only if 1st qubit is 1
const int maskLen = 1;
int maskBitString[] = {1};
// specify the values of mask qubits
int maskOrdering[] = {1};
// specify the mask qubits

// Swap index bit pairs.
// {|000>, |001>, |010>, |011>, |100>, |101>, |110>, |111>} will be permuted to
// {|000>, |001>, |010>, |110>, |100>, |101>, |011>, |111>}.
custatevecMultiDeviceSwapIndexBits(handles, nHandles, subSVs, svDataType, nGlobalIndexBits, nLocalIndexBits, indexBitSwaps, nIndexBitSwaps, maskBitString, maskOrdering, maskLen, deviceNetworkType);
```

--------------------------------

### Install Benchmarks with All Optional Dependencies

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Installs the NVIDIA Quantum Benchmarks suite along with all optional dependencies on a bare-metal system. Note that GPU support for all frameworks is not guaranteed.

```bash
cd cuQuantum/benchmarks && \
 pip install .[all]
```

--------------------------------

### Install qsimcirq with conda-forge

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Installs the qsimcirq package from the conda-forge channel. Use this for a standard installation.

```bash
conda install -c conda-forge qsimcirq
```

--------------------------------

### Install GPU-enabled Qiskit via PyPI

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Install a GPU-enabled version of Qiskit using pip. This command installs the qiskit-aer-gpu package.

```bash
pip install -v --no-cache-dir qiskit-aer-gpu
```

--------------------------------

### Install qsim and qsimcirq in editable mode from source

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Clones the qsim repository and installs it in editable mode using pip. Useful for development and easier updates.

```bash
export CUQUANTUM_ROOT=${CONDA_PREFIX}
git clone https://github.com/quantumlib/qsim.git && \
 pip install -v --no-cache-dir --editable .
```

--------------------------------

### Show Help for NVIDIA Quantum Benchmarks CLI

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Displays the help documentation for the nv-quantum-benchmarks command-line interface, outlining available subcommands and arguments.

```bash
nv-quantum-benchmarks --help
```

--------------------------------

### Install GPU-enabled Qiskit via conda-forge

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Install a GPU-enabled version of Qiskit using conda-forge. This command installs qiskit-aer, which can leverage GPU acceleration.

```bash
conda install -c conda-forge qiskit-aer
```

--------------------------------

### List Examples in cuQuantum Appliance Container

Source: https://docs.nvidia.com/cuda/cuquantum/latest/appliance/overview.html

Runs a command within the NVIDIA cuQuantum Appliance container to list all available example files in the `/home/cuquantum/examples` directory.

```bash
docker run --gpus all --rm \
 nvcr.io/nvidia/cuquantum-appliance:25.09-${march} ls \
 -la /home/cuquantum/examples
```

--------------------------------

### Run ghz.py Example (Single GPU)

Source: https://docs.nvidia.com/cuda/cuquantum/latest/appliance/overview.html

Executes the ghz.py script to simulate a GHZ circuit with 30 qubits on a single GPU.

```bash
python ghz.py --nqubits 30
```

--------------------------------

### Install cuQuantum via apt

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Install the cuQuantum package using the apt package manager. This command installs cuQuantum for all supported CUDA major versions.

```bash
sudo apt-get --yes install cuquantum
```

--------------------------------

### Install cuStateVec for CUDA 12

Source: https://docs.nvidia.com/cuda/cuquantum/latest/custatevec/release-notes.html

Use this command to install the cuStateVec wheels specifically built for CUDA 12 environments from PyPI. This is an alternative to the automated installer.

```bash
pip install custatevec-cu12
```

--------------------------------

### Workspace Get Memory

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/bindings/generated/cuquantum.bindings.cutensornet.state_apply_diagonal_tensor_operator.html

Gets the memory pointer of a workspace.

```APIDOC
## cuquantum.bindings.cutensornet.workspace_get_memory

### Description
Gets the memory pointer of a workspace.

### Method
Not applicable (Python function)

### Parameters
This function takes the following parameters:
- `workspace_desc`: The workspace descriptor object.

### Returns
A pointer to the workspace memory.
```

--------------------------------

### Install cuQuantum via Pip

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cutensornet/release-notes.html

Install the cuquantum meta-wheel via pip. This wheel automatically detects and installs the appropriate cuTensorNet and cuStateVec wheels for your CUDA environment.

```bash
pip install cuquantum
```

--------------------------------

### View ghz.py Help

Source: https://docs.nvidia.com/cuda/cuquantum/latest/appliance/overview.html

Displays the help message for the ghz.py example script, showing available runtime arguments.

```bash
(cuquantum) cuquantum@...:~$ cd examples && python {example_name}.py
(cuquantum) cuquantum@...:~/examples$ python ghz.py --help
```

--------------------------------

### Run ghz.py Example (Multiple GPUs)

Source: https://docs.nvidia.com/cuda/cuquantum/latest/appliance/overview.html

Executes the ghz.py script to simulate a GHZ circuit with 30 qubits across 4 GPUs.

```bash
python ghz.py --nqubits 30 --ngpus 4
```

--------------------------------

### Install cuTensorNet via Pip (CUDA 11)

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cutensornet/release-notes.html

Install the cuTensorNet wheel compatible with CUDA 11 using pip. This is the standard method for Python package installation.

```bash
pip install cutensornet-cu11
```

--------------------------------

### Example Workflow: Operator Action on Quantum State

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cudensitymat/examples.html

Demonstrates a typical workflow using cuDensityMat, including constructing a user-defined Liouvillian, setting Hamiltonian parameters, creating and initializing a quantum state, and querying its storage size. This example is useful for understanding the basic steps involved in simulating quantum systems.

```C++
#include "cudensitymat.h" // cuDensityMat library header
#include "helpers.h" // helper functions
#include "transverse_ising_full_fused_noisy.h" // user-defined Liouvillian operator example
#include <iostream>
#include <vector>
#include <numeric>
#include <complex>

// Define the numerical type for quantum states (e.g., float, double, complex<float>, complex<double>)
typedef double NumericalType;

// Number of times to perform operator action on a quantum state
constexpr int NUM_REPEATS = 2;

// Logging verbosity
bool verbose = true;

// Example workflow
void exampleWorkflow(cudensitymatHandle_t handle)
{
    // Define the composite Hilbert space shape and
    // quantum state batch size (number of individual quantum states in a batched simulation)
    const std::vector spaceShape({2,2,2,2,2,2,2,2}); // dimensions of quantum degrees of freedom
    const int64_t batchSize = 1; // number of quantum states per batch (default is 1)

    if (verbose) {
        std::cout << "Hilbert space rank = " << spaceShape.size() << "; Shape = (";
        for (const auto & dimsn: spaceShape)
        std::cout << dimsn << ",";
        std::cout << ")" << std::endl;
        std::cout << "Quantum state batch size = " << batchSize << std::endl;
    }

    // Construct a user-defined Liouvillian operator using a convenience C++ class
    UserDefinedLiouvillian liouvillian(handle, spaceShape, batchSize);
    if (verbose)
    std::cout << "Constructed the Liouvillian operator\n";

    // Set and place external user-provided Hamiltonian parameters in GPU memory
    const int32_t numParams = liouvillian.getNumParameters(); // number of external user-provided Hamiltonian parameters
    std::vector cpuHamParams(numParams * batchSize);
    for (int64_t j = 0; j < batchSize; ++j) {
        for (int32_t i = 0; i < numParams; ++i) {
            cpuHamParams[j * numParams + i] = double(i+1) / double(j+1); // just setting some parameter values for each instance of the batch
        }
    }
    auto *hamiltonianParams = static_cast<NumericalType*>(createInitializeArrayGPU(cpuHamParams));

    // Declare the input quantum state
    cudensitymatState_t inputState;
    HANDLE_CUDM_ERROR(cudensitymatCreateState(handle,
                                            CUDENSITYMAT_STATE_PURITY_MIXED, // pure (state vector) or mixed (density matrix) state
                                            spaceShape.size(),
                                            spaceShape.data(),
                                            batchSize,
                                            std::is_same_v<NumericalType, std::complex<float>> || std::is_same_v<NumericalType, std::complex<double>> ? CUDENSITYMAT_DATA_TYPE_COMPLEX : CUDENSITYMAT_DATA_TYPE_REAL,
                                            &inputState));

    // Query the size of the quantum state storage
    std::size_t storageSize {0}; // only one storage component (tensor) is needed (no tensor factorization)
    HANDLE_CUDM_ERROR(cudensitymatStateGetComponentStorageSize(handle,
                                                            inputState,
                                                            1, // only one storage component (tensor)
                                                            &storageSize)); // storage size in bytes
    const std::size_t stateVolume = storageSize / sizeof(NumericalType); // quantum state tensor volume (number of elements)
    if (verbose)
    std::cout << "Quantum state storage size (bytes) = " << storageSize << std::endl;

    // Prepare some initial value for the input quantum state batch
    std::vector inputStateValue(stateVolume);
    if constexpr (std::is_same_v<NumericalType, float>) {
        for (std::size_t i = 0; i < stateVolume; ++i) {
            inputStateValue[i] = 1.0f / float(i+1); // just some value
        }
    } else if constexpr (std::is_same_v<NumericalType, double>) {
        for (std::size_t i = 0; i < stateVolume; ++i) {
            inputStateValue[i] = 1.0 / double(i+1); // just some value
        }
    } else if constexpr (std::is_same_v<NumericalType, std::complex<float>>) {
        for (std::size_t i = 0; i < stateVolume; ++i) {
            inputStateValue[i] = NumericalType{1.0f / float(i+1), -1.0f / float(i+2)}; // just some value
        }
    } else if constexpr (std::is_same_v<NumericalType, std::complex<double>>) {
        for (std::size_t i = 0; i < stateVolume; ++i) {
            inputStateValue[i] = NumericalType{1.0 / double(i+1), -1.0 / double(i+2)}; // just some value
        }
    }

    // Set the initial quantum state values
    HANDLE_CUDM_ERROR(cudensitymatStateSetComponent(handle, inputState, 1, inputStateValue.data()));

    // Declare the output quantum state
    cudensitymatState_t outputState;
    HANDLE_CUDM_ERROR(cudensitymatCreateState(handle,
                                            CUDENSITYMAT_STATE_PURITY_MIXED,
                                            spaceShape.size(),
                                            spaceShape.data(),
                                            batchSize,
                                            std::is_same_v<NumericalType, std::complex<float>> || std::is_same_v<NumericalType, std::complex<double>> ? CUDENSITYMAT_DATA_TYPE_COMPLEX : CUDENSITYMAT_DATA_TYPE_REAL,
                                            &outputState));

    // Perform operator action on the quantum state multiple times
    for (int i = 0; i < NUM_REPEATS; ++i) {
        HANDLE_CUDM_ERROR(cudensitymatOperatorAction(handle,
                                                   liouvillian.get(),
                                                   hamiltonianParams,
                                                   inputState,
                                                   outputState));
        // Swap input and output states for the next iteration
        HANDLE_CUDM_ERROR(cudensitymatStateSwap(handle, inputState, outputState));
    }

    // Destroy the quantum states and Hamiltonian parameters
    HANDLE_CUDM_ERROR(cudensitymatDestroyState(handle, inputState));
    HANDLE_CUDM_ERROR(cudensitymatDestroyState(handle, outputState));
    destroyArrayGPU(hamiltonianParams);
}

```

--------------------------------

### Install cuQuantum Python from Source (No Dependencies)

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Build and install cuQuantum Python from source without installing runtime dependencies. This is an advanced option for specific build scenarios.

```bash
pip install -v --no-deps --no-build-isolation .
```

--------------------------------

### Example Workflow with cuDensityMat

Source: https://docs.nvidia.com/cuda/cuquantum/latest/cudensitymat/examples.html

Demonstrates a typical workflow using cuDensityMat, including defining Hilbert space, creating a Liouvillian operator, and preparing quantum states for eigenspectrum computation.

```cpp
// cuDensityMat library header
#include "cudensitymat.h"
// helper functions
#include "helpers.h"

// user-defined Liouvillian operator example
#include "transverse_ising_full_fused.h"

#include <iostream>
#include <vector>
#include <cstdint>
#include <type_traits>

// Placeholder for NumericalType and dataType, assuming they are defined globally or passed
// For this example, let's assume they are defined as follows:
using NumericalType = double;
const char* dataType = "double";

// Logging verbosity
bool verbose = true;

// Example workflow
void exampleWorkflow(cudensitymatHandle_t handle) {
    // Define the composite Hilbert space shape and
    // quantum state batch size (number of individual quantum states in a batched simulation)
    const std::vector<int32_t> spaceShape({2,2,2,2,2,2,2,2,2,2}); // dimensions of quantum degrees of freedom
    const int64_t batchSize = 1; // number of quantum states per batch (currently only 1 state per batch)
    const int32_t numEigenStates = 4; // number of eigenstates to compute

    if (verbose) {
        std::cout << "Hilbert space rank = " << spaceShape.size() << "; Shape = (";
        for (const auto & dimsn: spaceShape)
            std::cout << dimsn << ",";
        std::cout << ")" << std::endl;
        std::cout << "Quantum state batch size = " << batchSize << std::endl;
    }

    // Construct a user-defined Liouvillian operator using a convenience C++ class
    UserDefinedLiouvillian liouvillian(handle, spaceShape, batchSize);
    if (verbose)
        std::cout << "Constructed the Liouvillian operator\n";

    // Create quantum states to store the eigenstates
    std::size_t stateVolume {0};
    std::vector<cudensitymatState_t> eigenStates(numEigenStates);
    std::vector<cudensitymatStateComponent_t> eigenStatesElems(numEigenStates);
    for (int32_t id = 0; id < numEigenStates; ++id) {

        // Declare the quantum state
        HANDLE_CUDM_ERROR(cudensitymatCreateState(handle,
                                                CUDENSITYMAT_STATE_PURITY_PURE, // pure (state vector)
                                                spaceShape.size(),
                                                spaceShape.data(),
                                                batchSize,
                                                dataType,
                                                &eigenStates[id]));

        // Query the size of the quantum state storage
        std::size_t storageSize {0}; // only one storage component (tensor) is needed (no tensor factorization)
        HANDLE_CUDM_ERROR(cudensitymatStateGetComponentStorageSize(handle,
                                                                eigenStates[id],
                                                                1, // only one storage component (tensor)
                                                                &storageSize)); // storage size in bytes
        stateVolume = storageSize / sizeof(NumericalType); // quantum state tensor volume (number of elements)
        if (verbose)
            std::cout << "Quantum state storage size (bytes) = " << storageSize << std::endl;

        // Prepare some initial value for the quantum state
        std::vector<NumericalType> stateValue(stateVolume);
        if constexpr (std::is_same_v<NumericalType, double>) {
            for (std::size_t i = 0; i < stateVolume; ++i) {
                stateValue[i] = 1.0 / double(id*5 + i+1); // just some value
            }
        } else if constexpr (std::is_same_v<NumericalType, std::complex<double>>) {
            for (std::size_t i = 0; i < stateVolume; ++i) {
                stateValue[i] = std::complex<double>(1.0 / double(id*5 + i+1), 0.0); // just some value
            }
        }
        // Note: The actual setting of stateValue to eigenStates[id] is omitted for brevity.
        // This would typically involve a call like cudensitymatStateSetComponentData.
    }
    // Further steps like computing the eigenspectrum would follow here.
}

```

--------------------------------

### Install cuStateVec via Conda

Source: https://docs.nvidia.com/cuda/cuquantum/latest/custatevec/release-notes.html

Install the cuStateVec package using conda from the conda-forge channel. Users can also install the cuquantum meta-package which includes both cuStateVec and cuTensorNet.

```bash
conda install -c conda-forge custatevec
```

```bash
conda install -c conda-forge cuquantum
```

--------------------------------

### Workspace Get Memory Size

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/bindings/generated/cuquantum.bindings.cutensornet.state_apply_diagonal_tensor_operator.html

Gets the memory size of a workspace.

```APIDOC
## cuquantum.bindings.cutensornet.workspace_get_memory_size

### Description
Gets the memory size of a workspace.

### Method
Not applicable (Python function)

### Parameters
This function takes the following parameters:
- `workspace_desc`: The workspace descriptor object.

### Returns
The memory size of the workspace.
```

--------------------------------

### MGMN Execution Example with Product State Initialization

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/densitymat.html

Illustrates multi-GPU multi-node (MGMN) execution by setting a quantum state to a specific product state in the computational basis. This example shows how to use DensePureState.local_info for MGMN-specific storage.

```python
import cupy as cp
import numpy as np
from mpi4py import MPI
from cuquantum.densitymat import (
    tensor_product,
    DensePureState,
    DenseOperator,
    MultidiagonalOperator,
    WorkStream,
    OperatorTerm,
    Operator,
    OperatorAction,
)

def ordered_print(str):
    rank = MPI.COMM_WORLD.Get_rank()
    size = MPI.COMM_WORLD.Get_size()
    for i in range(size):
        if i == rank:
            print(f"Rank {i}: {str}")
        MPI.COMM_WORLD.Barrier()


NUM_DEVICES = cp.cuda.runtime.getDeviceCount()
rank = MPI.COMM_WORLD.Get_rank()
dev = cp.cuda.Device(rank % NUM_DEVICES)
dev.use()
props = cp.cuda.runtime.getDeviceProperties(dev.id)
ordered_print("===== device info ======")
ordered_print(f"GPU-local-id: {dev.id}")
ordered_print(f"GPU-name: {props['name'].decode()}")
ordered_print(f"GPU-clock: {props['clockRate']}")
ordered_print(f"GPU-memoryClock: {props['memoryClockRate']}")
ordered_print(f"GPU-nSM: {props['multiProcessorCount']}")
ordered_print(f"GPU-major: {props['major']}")
ordered_print(f"GPU-minor: {props['minor']}")
ordered_print("========================")

# create Workstream on the current device
ctx = WorkStream
```

--------------------------------

### Install cuStateVec via Pip

Source: https://docs.nvidia.com/cuda/cuquantum/latest/custatevec/release-notes.html

Install the cuStateVec package using pip from PyPI. The custatevec-cu11 wheel is recommended for CUDA 11. Users can also install the cuquantum meta-wheel.

```bash
pip install custatevec-cu11
```

```bash
pip install cuquantum
```

--------------------------------

### View cuQuantum Installation with update-alternatives

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

This command displays the system's current configuration and available alternatives for the cuQuantum provider, showing linked files and priorities for different CUDA versions.

```bash
sudo update-alternatives --display cuquantum
```

--------------------------------

### Distributed Get Num Ranks

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/bindings/generated/cuquantum.bindings.cutensornet.state_apply_diagonal_tensor_operator.html

Gets the number of ranks in the distributed configuration.

```APIDOC
## cuquantum.bindings.cutensornet.distributed_get_num_ranks

### Description
Gets the number of ranks in the distributed configuration.

### Method
Not applicable (Python function)

### Parameters
None

### Returns
The number of ranks in the distributed configuration.
```

--------------------------------

### pauli_expansion_view_prepare_trace_with_expansion_view

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/bindings/generated/cuquantum.bindings.cupauliprop.pauli_expansion_view_prepare_trace_with_expansion_view.html

Prepares a Pauli expansion view for computing the product trace of two Pauli expansion views. It takes a library handle, two Pauli expansion views, a maximum workspace size, and a workspace descriptor as input.

```APIDOC
## pauli_expansion_view_prepare_trace_with_expansion_view

### Description
Prepares a Pauli expansion view for computing the product trace of two Pauli expansion views.

### Method
Not applicable (Python function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
*   **handle** (_intptr_t_) – Required - Library handle.
*   **view1** (_intptr_t_) – Required - First Pauli expansion view to be traced.
*   **view2** (_intptr_t_) – Required - Second Pauli expansion view to be traced.
*   **max_workspace_size** (_int64_t_) – Required - Maximum workspace size limit in bytes.
*   **workspace** (_intptr_t_) – Required - Workspace descriptor with the required workspace buffer size.

### Response
#### Success Response
This function does not return a value, but prepares the workspace for subsequent operations.

#### Response Example
None
```

--------------------------------

### Install pennylane-lightning-gpu with conda-forge

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Installs the PennyLane-Lightning plugin with GPU support from the conda-forge channel.

```bash
conda install -c conda-forge pennylane-lightning-gpu
```

--------------------------------

### Get Device Memory Handler

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/bindings/generated/cuquantum.bindings.cutensornet.state_apply_diagonal_tensor_operator.html

Gets the currently set device memory handler.

```APIDOC
## cuquantum.bindings.cutensornet.get_device_mem_handler

### Description
Gets the currently set device memory handler.

### Method
Not applicable (Python function)

### Parameters
None

### Returns
The device memory handler function.
```

--------------------------------

### Run Qiskit GHZ Example

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Executes the qiskit_ghz.py script within the cuQuantum Appliance container to generate GHZ state measurement results.

```bash
docker exec cuquantum-appliance python /home/cuquantum/examples/qiskit_ghz.py
```

--------------------------------

### Create and Attach Storage to DensePureState

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/generated/cuquantum.densitymat.DensePureState.html

Demonstrates how to initialize a DensePureState with a specified batch size and data type, and then attach a storage buffer using cupy.zeros. This is useful for setting up a state vector for quantum computations.

```python
import cupy as cp
from cuquantum.densitymat import WorkStream, DensePureState

ctx = WorkStream(stream=cp.cuda.Stream())
hilbert_space_dims = (2, 2, 2)
rho = DensePureState(ctx, hilbert_space_dims, 1, "complex128")
rho.attach_storage(cp.zeros(rho.storage_size, dtype=rho.dtype))
```

--------------------------------

### Install specific cuquantum version

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/release-notes.html

Install a specific version of cuquantum, including the post-release tag.

```bash
pip install cuquantum==24.8.0.2
```

--------------------------------

### Initialize and Apply Circuit with FrameSimulator

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/generated/cuquantum.stabilizer.FrameSimulator.html

Demonstrates the basic usage of FrameSimulator by initializing it, applying a simple circuit, and retrieving measurement bits.

```python
circ = Circuit("H 0\nCNOT 0 1\nM 1")
sim = FrameSimulator(2, 1024, num_measurements=1)
sim.apply(circ)
measurements = sim.get_measurement_bits()
```

--------------------------------

### Install specific cuquantum-python version

Source: https://docs.nvidia.com/cuda/cuquantum/latest/python/release-notes.html

Install a specific version of cuquantum-python, including the post-release tag.

```bash
pip install cuquantum-python==24.8.0.2
```

--------------------------------

### Run GHZ Circuit with Multi-Node Simulation using mpirun

Source: https://docs.nvidia.com/cuda/cuquantum/latest/appliance/qiskit.html

This example shows how to distribute the simulation of a GHZ circuit across multiple processes using `mpirun`. The output will reflect the distributed nature of the computation.

```bash
$ mpirun -n 2 python ghz.py
```

--------------------------------

### Install cuStateVec Component

Source: https://docs.nvidia.com/cuda/cuquantum/latest/getting-started/index.html

Install only the cuStateVec component from conda-forge. Use this if you only need the functionality provided by cuStateVec.

```bash
conda install -c conda-forge custatevec
```
Tokens:
Raw