Catalyst

Development

Examples

API

  1. Docs
  2. Program Listing for File QuantumDevice.hpp

Program Listing for File QuantumDevice.hpp

↰ Return to documentation for file (runtime/include/QuantumDevice.hpp)

// Copyright 2022-2025 Xanadu Quantum Technologies Inc.

// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at

//     http://www.apache.org/licenses/LICENSE-2.0

// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#pragma once

#include <complex>
#include <memory>
#include <optional>
#include <random>
#include <vector>

#include "DataView.hpp"
#include "Types.h"

// A helper template macro to generate the <IDENTIFIER>Factory function by
// calling <CONSTRUCTOR>(kwargs). Check the Custom Devices guideline for details:
// https://docs.pennylane.ai/projects/catalyst/en/stable/dev/custom_devices.html
#define GENERATE_DEVICE_FACTORY(IDENTIFIER, CONSTRUCTOR)                                           \
    extern "C" Catalyst::Runtime::QuantumDevice *IDENTIFIER##Factory(const char *kwargs)           \
    {                                                                                              \
        return new CONSTRUCTOR(std::string(kwargs));                                               \
    }

namespace Catalyst::Runtime {

struct QuantumDevice {
    QuantumDevice() = default;          // LCOV_EXCL_LINE
    virtual ~QuantumDevice() = default; // LCOV_EXCL_LINE

    QuantumDevice &operator=(const QuantumDevice &) = delete;
    QuantumDevice(const QuantumDevice &) = delete;
    QuantumDevice(QuantumDevice &&) = delete;
    QuantumDevice &operator=(QuantumDevice &&) = delete;

    // ----------------------------------------
    //  QUBIT MANAGEMENT
    // ----------------------------------------

    virtual auto AllocateQubits(size_t num_qubits) -> std::vector<QubitIdType> = 0;

    virtual void ReleaseAllQubits() = 0;

    virtual auto GetNumQubits() const -> size_t = 0;

    virtual auto AllocateQubit() -> QubitIdType
    {
        RT_FAIL("Dynamic qubit allocation is unsupported by device");
    }

    virtual void ReleaseQubit(QubitIdType qubit)
    {
        RT_FAIL("Dynamic qubit release is unsupported by device");
    }

    // ----------------------------------------
    //  EXECUTION MANAGEMENT
    // ----------------------------------------

    virtual void SetDeviceShots(size_t shots) = 0;

    virtual auto GetDeviceShots() const -> size_t = 0;

    virtual void SetDevicePRNG(std::mt19937 *gen) {};

    // ----------------------------------------
    //  QUANTUM OPERATIONS
    // ----------------------------------------

    virtual void NamedOperation(const std::string &name, const std::vector<double> &params,
                                const std::vector<QubitIdType> &wires, bool inverse = false,
                                const std::vector<QubitIdType> &controlled_wires = {},
                                const std::vector<bool> &controlled_values = {}) = 0;
    virtual auto Measure(QubitIdType wire, std::optional<int32_t> postselect) -> Result = 0;

    virtual void MatrixOperation(const std::vector<std::complex<double>> &matrix,
                                 const std::vector<QubitIdType> &wires, bool inverse = false,
                                 const std::vector<QubitIdType> &controlled_wires = {},
                                 const std::vector<bool> &controlled_values = {})
    {
        RT_FAIL("MatrixOperation is unsupported by device");
    }

    virtual void SetBasisState(DataView<int8_t, 1> &n, std::vector<QubitIdType> &wires)
    {
        RT_FAIL("SetBasisState is unsupported by device");
    }

    virtual void SetState(DataView<std::complex<double>, 1> &state, std::vector<QubitIdType> &wires)
    {
        RT_FAIL("SetState is unsupported by device");
    }

    // ----------------------------------------
    //  QUANTUM OBSERVABLES
    // ----------------------------------------

    virtual auto Observable(ObsId id, const std::vector<std::complex<double>> &matrix,
                            const std::vector<QubitIdType> &wires) -> ObsIdType
    {
        RT_FAIL("Observable is unsupported by device");
    }

    virtual auto TensorObservable(const std::vector<ObsIdType> &obs) -> ObsIdType
    {
        RT_FAIL("TensorObservable is unsupported by device");
    }

    virtual auto HamiltonianObservable(const std::vector<double> &coeffs,
                                       const std::vector<ObsIdType> &obs) -> ObsIdType
    {
        RT_FAIL("HamiltonianObservable is unsupported by device");
    }

    // ----------------------------------------
    //  MEASUREMENT PROCESSES
    // ----------------------------------------

    virtual void Sample(DataView<double, 2> &samples)
    {
        RT_FAIL("Sample is unsupported by device");
    }

    virtual void PartialSample(DataView<double, 2> &samples, const std::vector<QubitIdType> &wires)
    {
        RT_FAIL("PartialSample is unsupported by device");
    }

    virtual void Counts(DataView<double, 1> &eigvals, DataView<int64_t, 1> &counts)
    {
        RT_FAIL("Counts is unsupported by device");
    }

    virtual void PartialCounts(DataView<double, 1> &eigvals, DataView<int64_t, 1> &counts,
                               const std::vector<QubitIdType> &wires)
    {
        RT_FAIL("PartialCounts is unsupported by device");
    }

    virtual void Probs(DataView<double, 1> &probs) { RT_FAIL("Probs is unsupported by device"); }

    virtual void PartialProbs(DataView<double, 1> &probs, const std::vector<QubitIdType> &wires)
    {
        RT_FAIL("PartialProbs is unsupported by device");
    }
    virtual auto Expval(ObsIdType obsKey) -> double { RT_FAIL("Expval is unsupported by device"); }

    virtual auto Var(ObsIdType obsKey) -> double { RT_FAIL("Var is unsupported by device"); }

    virtual void State(DataView<std::complex<double>, 1> &state)
    {
        RT_FAIL("State is unsupported by device");
    }

    // ----------------------------------------
    //  QUANTUM DERIVATIVES
    // ----------------------------------------

    virtual void Gradient(std::vector<DataView<double, 1>> &gradients,
                          const std::vector<size_t> &trainParams)
    {
        RT_FAIL("Differentiation is unsupported by device");
    }

    virtual void StartTapeRecording() { RT_FAIL("Differentiation is unsupported by device"); }

    virtual void StopTapeRecording() { RT_FAIL("Differentiation is unsupported by device"); }
};

} // namespace Catalyst::Runtime