pyqpanda3
Search K

English

简体中文

English

简体中文

Appearance

Simulator -- CPUQVM, GPUQVM, DensityMatrixSimulator, Stabilizer, PartialAmplitudeQVM ​

API reference for quantum circuit simulators in pyqpanda3.

Overview ​

pyqpanda3 provides five simulator backends for executing quantum programs:

SimulatorState RepresentationNoise SupportBest For
CPUQVMState vectorYesGeneral-purpose simulation
DensityMatrixSimulatorDensity matrixYesMixed states, partial trace, noise analysis
PartialAmplitudeQVMState vector (partial)NoLarge circuits where only select amplitudes are needed
StabilizerStabilizer (Clifford)YesLarge Clifford circuits, efficient sampling
GPUQVMState vector (GPU)YesHigh-performance simulation with CUDA

CPUQVM ​

State-vector-based quantum simulator running on the CPU. This is the primary simulator for general-purpose quantum circuit simulation. It stores the full state vector of the quantum system and supports noisy simulation via NoiseModel.

Signature ​

python
class CPUQVM:
    def __init__() -> None
    def run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None
    def result() -> QResult

CPUQVM.init ​

python
CPUQVM() -> None

Constructs a new CPUQVM instance with default parameters.

Parameters ​

None.

Returns ​

A new CPUQVM instance.

CPUQVM.run ​

python
CPUQVM.run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None

Executes a quantum program a specified number of times (shots) and stores the results internally. Each shot re-initializes the state and runs the full circuit. If measurement operations are present in the program, the results are aggregated across all shots.

Parameters ​

ParameterTypeDescription
progQProgThe quantum program to execute.
shotsintThe number of times to repeat the execution. Measurement outcomes are aggregated across all shots.
modelNoiseModelOptional noise model to apply during execution. Defaults to an ideal (noise-free) model.

Returns ​

None. Results are stored internally and retrieved via result().

CPUQVM.result ​

python
CPUQVM.result() -> QResult

Retrieves the result of the most recent run() call.

Parameters ​

None.

Returns ​

A QResult object containing measurement counts, state vector, and probability data.

Examples ​

Run a Bell state circuit and retrieve measurement counts:

python
from pyqpanda3.core import CPUQVM, QProg, H, CNOT, measure

# Build a Bell state program
prog = QProg()
prog << H(0) << CNOT(0, 1)
prog << measure(0, 0) << measure(1, 1)

# Run on the CPU simulator
qvm = CPUQVM()
qvm.run(prog, shots=1000)
res = qvm.result()

# Print measurement counts
counts = res.get_counts()
print(counts)
# Example output: {'00': 503, '11': 497}

Get the state vector after running a circuit:

python
from pyqpanda3.core import CPUQVM, QProg, H, CNOT

prog = QProg()
prog << H(0) << CNOT(0, 1)

qvm = CPUQVM()
qvm.run(prog, shots=1)
res = qvm.result()

state = res.get_state_vector()
print(state)
# [0.707+0j, 0+0j, 0+0j, 0.707+0j]

Run with a depolarizing noise model:

python
from pyqpanda3.core import (
    CPUQVM, QProg, H, CNOT, measure,
    NoiseModel, depolarizing_error, GateType
)

prog = QProg()
prog << H(0) << CNOT(0, 1)
prog << measure(0, 0) << measure(1, 1)

noise = NoiseModel()
noise.add_all_qubit_quantum_error(depolarizing_error(0.01), [GateType.CNOT])

qvm = CPUQVM()
qvm.run(prog, shots=1000, model=noise)
res = qvm.result()
print(res.get_counts())

expval_hamiltonian ​

Calculate the expectation value of a Hamiltonian.

Deprecated: Use the module-level expval_hamiltonian() function instead.

python
expval_hamiltonian(prog: QProg, hamiltonian: Hamiltonian, shots: int = 1000, noise_model: NoiseModel = NoiseModel()) -> float

expval_pauli_operator ​

Calculate the expectation value of a Pauli operator.

Deprecated: Use the module-level expval_pauli_operator() function instead.

python
expval_pauli_operator(prog: QProg, pauli_operator: PauliOperator, shots: int = 1000, noise_model: NoiseModel = NoiseModel()) -> float

See Also ​

  • QResult -- Result object with counts, state vector, and probabilities
  • NoiseModel -- Noise model configuration
  • QProg -- Quantum program construction
  • expval_hamiltonian -- Global function for Hamiltonian expectation values

DensityMatrixSimulator ​

Density-matrix-based quantum simulator. Unlike the state vector simulator, this backend represents the quantum state as a density matrix, enabling simulation of mixed states, noisy evolution, and computation of partial traces. It supports all noise model operations natively.

Signature ​

python
class DensityMatrixSimulator:
    def __init__() -> None
    def run(prog: QProg, model: NoiseModel = NoiseModel()) -> None
    def state_prob(index: int) -> float
    def state_prob(index: str) -> float
    def state_probs() -> list[float]
    def state_probs(qubits: list[int]) -> list[float]
    def state_probs(bin_indices: list[str]) -> list[float]
    def density_matrix() -> matrixXcd
    def reduced_density_matrix(qubits: list[int]) -> matrixXcd

DensityMatrixSimulator.init ​

python
DensityMatrixSimulator() -> None

Constructs a new DensityMatrixSimulator instance.

Parameters ​

None.

Returns ​

A new DensityMatrixSimulator instance.

DensityMatrixSimulator.run ​

python
DensityMatrixSimulator.run(prog: QProg, model: NoiseModel = NoiseModel()) -> None

Executes a quantum program with an optional noise model, evolving the density matrix accordingly.

Parameters ​

ParameterTypeDescription
progQProgThe quantum program to execute.
modelNoiseModelOptional noise model to apply during execution. Defaults to an ideal (noise-free) model.

Returns ​

None. The density matrix is updated internally.

DensityMatrixSimulator.state_prob (by index) ​

python
DensityMatrixSimulator.state_prob(index: int) -> float

Returns the probability of the computational basis state at the given integer index.

Parameters ​

ParameterTypeDescription
indexintThe integer index of the computational basis state.

Returns ​

The probability (float) of the specified state.

DensityMatrixSimulator.state_prob (by binary string) ​

python
DensityMatrixSimulator.state_prob(index: str) -> float

Returns the probability of the computational basis state identified by the given binary string.

Parameters ​

ParameterTypeDescription
indexstrThe binary string representation of the basis state (e.g., "01").

Returns ​

The probability (float) of the specified state.

DensityMatrixSimulator.state_probs (all states) ​

python
DensityMatrixSimulator.state_probs() -> list[float]

Returns the probabilities of all possible computational basis states.

Parameters ​

None.

Returns ​

A list of probabilities for every computational basis state.

DensityMatrixSimulator.state_probs (specific qubits) ​

python
DensityMatrixSimulator.state_probs(qubits: list[int]) -> list[float]

Returns the marginal probability distribution for the specified subset of qubits.

Parameters ​

ParameterTypeDescription
qubitslist[int]Indices of the qubits to compute probabilities for.

Returns ​

A list of probabilities for the specified qubits.

DensityMatrixSimulator.state_probs (by binary strings) ​

python
DensityMatrixSimulator.state_probs(bin_indices: list[str]) -> list[float]

Returns the probabilities for the states specified by a list of binary strings.

Parameters ​

ParameterTypeDescription
bin_indiceslist[str]A list of binary string representations of basis states.

Returns ​

A list of probabilities corresponding to the given states.

DensityMatrixSimulator.density_matrix ​

python
DensityMatrixSimulator.density_matrix() -> matrixXcd

Returns the full density matrix of the current quantum state.

Parameters ​

None.

Returns ​

A complex-valued matrix (matrixXcd) representing the density matrix.

DensityMatrixSimulator.reduced_density_matrix ​

python
DensityMatrixSimulator.reduced_density_matrix(qubits: list[int]) -> matrixXcd

Returns the reduced density matrix obtained by tracing out all qubits not in the specified list.

Parameters ​

ParameterTypeDescription
qubitslist[int]Indices of the qubits to keep. All other qubits are traced out.

Returns ​

A complex-valued matrix (matrixXcd) representing the reduced density matrix for the specified qubits.

Examples ​

Compute the density matrix of a Bell state and trace out one qubit:

python
from pyqpanda3.core import DensityMatrixSimulator, QProg, H, CNOT

prog = QProg()
prog << H(0) << CNOT(0, 1)

sim = DensityMatrixSimulator()
sim.run(prog)

# Full density matrix
rho = sim.density_matrix()
print(rho)

# Reduced density matrix for qubit 0 (trace out qubit 1)
rho_0 = sim.reduced_density_matrix([0])
print(rho_0)
# Expected: maximally mixed state [[0.5, 0], [0, 0.5]]

# Probability of state |00>
p_00 = sim.state_prob(0)
print(f"P(|00>) = {p_00}")

# Probability via binary string
p_11 = sim.state_prob("11")
print(f"P(|11>) = {p_11}")

# All state probabilities
probs = sim.state_probs()
print(probs)
# [0.5, 0.0, 0.0, 0.5]

Simulate with amplitude damping noise:

python
from pyqpanda3.core import (
    DensityMatrixSimulator, QProg, H, GateType,
    NoiseModel, amplitude_damping_error
)

prog = QProg()
prog << H(0)

noise = NoiseModel()
noise.add_all_qubit_quantum_error(amplitude_damping_error(0.1), GateType.H)

sim = DensityMatrixSimulator()
sim.run(prog, model=noise)

rho = sim.density_matrix()
print(rho)

See Also ​

  • CPUQVM -- State vector simulator
  • NoiseModel -- Noise model configuration
  • QProg -- Quantum program construction

PartialAmplitudeQVM ​

Partial amplitude simulator. This backend is designed for large quantum circuits where computing the full state vector is infeasible due to memory constraints. Instead of returning the complete state vector, it computes amplitudes for specific computational basis states specified by binary strings.

Signature ​

python
class PartialAmplitudeQVM:
    def __init__() -> None
    def run(prog: QProg) -> None
    def get_state_vector(amplitudes: list[str]) -> list[complex]

PartialAmplitudeQVM.init ​

python
PartialAmplitudeQVM() -> None

Constructs a new PartialAmplitudeQVM instance.

Parameters ​

None.

Returns ​

A new PartialAmplitudeQVM instance.

PartialAmplitudeQVM.run ​

python
PartialAmplitudeQVM.run(prog: QProg) -> None

Executes the quantum program and prepares the simulator for partial amplitude queries. Note: this simulator does not take a shots parameter -- it performs a single state-vector evolution.

Parameters ​

ParameterTypeDescription
progQProgThe quantum program to execute.

Returns ​

None.

PartialAmplitudeQVM.get_state_vector ​

python
PartialAmplitudeQVM.get_state_vector(amplitudes: list[str]) -> list[complex]

Retrieves the complex amplitudes for the specified computational basis states.

Parameters ​

ParameterTypeDescription
amplitudeslist[str]A list of binary strings, each specifying a computational basis state (e.g., ["00", "11"]).

Returns ​

A list of complex numbers, each being the amplitude of the corresponding basis state.

Examples ​

Get specific amplitudes from a Bell state:

python
from pyqpanda3.core import PartialAmplitudeQVM, QProg, H, CNOT

prog = QProg()
prog << H(0) << CNOT(0, 1)

qvm = PartialAmplitudeQVM()
qvm.run(prog)

# Get amplitudes for |00> and |11>
amps = qvm.get_state_vector(["00", "11"])
print(amps)
# [(0.707+0j), (0.707+0j)]

# Get amplitude for |01>
amp_01 = qvm.get_state_vector(["01"])
print(amp_01)
# [0j]

See Also ​

  • CPUQVM -- Full state vector simulator
  • QProg -- Quantum program construction

Stabilizer ​

Stabilizer simulator based on the Clifford group representation. This simulator efficiently simulates circuits composed solely of Clifford gates (H, S, CNOT, and measurements). Instead of storing the full state vector, it maintains a stabilizer tableau, allowing simulation of very large numbers of qubits with polynomial memory.

Signature ​

python
class Stabilizer:
    def __init__() -> None
    def run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None
    def result() -> StabilizerResult

Stabilizer.init ​

python
Stabilizer() -> None

Constructs a new Stabilizer simulator instance.

Parameters ​

None.

Returns ​

A new Stabilizer instance.

Stabilizer.run ​

python
Stabilizer.run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None

Executes the quantum program using the stabilizer formalism for a specified number of measurement shots. The circuit must be composed of Clifford gates (H, S, CNOT, X, Y, Z, SWAP, and measurements). Non-Clifford gates (such as T gates) are not supported.

Noise model support is limited to Clifford-compatible noise channels (bit-flip, phase-flip, bit-phase-flip, phase-damping, depolarizing).

Parameters ​

ParameterTypeDescription
progQProgThe quantum program to execute. Must contain only Clifford gates and measurements.
shotsintThe number of measurement repetitions.
modelNoiseModelOptional noise model (Clifford-compatible only). Defaults to an ideal model.

Returns ​

None. Results are stored internally and retrieved via result().

Stabilizer.result ​

python
Stabilizer.result() -> StabilizerResult

Retrieves the result of the most recent run() call. The StabilizerResult object provides access to measurement counts and state information.

Parameters ​

None.

Returns ​

A StabilizerResult object (subclass of QResult) containing measurement outcomes.

Examples ​

Run a Clifford circuit with the stabilizer simulator:

python
from pyqpanda3.core import Stabilizer, QProg, H, CNOT, measure

prog = QProg()
prog << H(0) << CNOT(0, 1)
prog << measure(0, 0) << measure(1, 1)

sim = Stabilizer()
sim.run(prog, shots=1000)
res = sim.result()

counts = res.get_counts()
print(counts)
# Example output: {'00': 501, '11': 499}

See Also ​

GPUQVM ​

GPU-accelerated state vector simulator. This backend uses CUDA to accelerate quantum circuit simulation on NVIDIA GPUs. It provides the same interface as CPUQVM but leverages GPU parallelism for significantly faster execution on circuits with many qubits.

Availability: This simulator requires pyqpanda3 to be compiled with CUDA support (USE_CUDA flag). It is not available in the standard CPU-only build.

Signature ​

python
class GPUQVM:
    def __init__() -> None
    def run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None
    def result() -> QResult

GPUQVM.init ​

python
GPUQVM() -> None

Constructs a new GPUQVM instance. Requires CUDA support at compile time.

Parameters ​

None.

Returns ​

A new GPUQVM instance.

GPUQVM.run ​

python
GPUQVM.run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None

Executes a quantum program on the GPU for a specified number of shots.

Parameters ​

ParameterTypeDescription
progQProgThe quantum program to execute.
shotsintThe number of times to repeat the execution.
modelNoiseModelOptional noise model to apply during execution. Defaults to an ideal model.

Returns ​

None. Results are stored internally and retrieved via result().

GPUQVM.result ​

python
GPUQVM.result() -> QResult

Retrieves the result of the most recent run() call.

Parameters ​

None.

Returns ​

A QResult object containing measurement counts, state vector, and probability data.

Examples ​

Run a circuit on the GPU simulator:

python
from pyqpanda3.core import GPUQVM, QProg, H, CNOT, measure

prog = QProg()
prog << H(0) << CNOT(0, 1)
prog << measure(0, 0) << measure(1, 1)

qvm = GPUQVM()
qvm.run(prog, shots=1000)
res = qvm.result()

counts = res.get_counts()
print(counts)

See Also ​

QResult ​

Result object returned by CPUQVM.result() and GPUQVM.result(). Contains measurement outcomes, state vector data, and probability distributions.

Signature ​

python
class QResult:
    def get_state_vector() -> list[complex]
    def get_counts() -> dict[str, int]
    def get_prob_list(qubits: list[int] = []) -> list[float]
    def get_prob_dict(qubits: list[int] = []) -> dict[str, float]
    def shots() -> int
    def print_results() -> None

QResult.get_state_vector ​

python
QResult.get_state_vector() -> list[complex]

Returns the state vector of the quantum system after the final shot of execution.

Returns ​

A list of complex numbers representing the quantum state vector.

QResult.get_counts ​

python
QResult.get_counts() -> dict[str, int]

Returns the aggregated measurement results as a dictionary mapping bitstring outcomes to their frequency counts.

Returns ​

A dictionary where keys are bitstrings (e.g., "00", "11") and values are the number of times that outcome was observed.

QResult.get_prob_list ​

python
QResult.get_prob_list(qubits: list[int] = []) -> list[float]

Returns the probability distribution for the specified qubits (or all qubits if none are specified) as a list.

Parameters ​

ParameterTypeDescription
qubitslist[int]Optional list of qubit indices. If empty, returns probabilities for all qubits.

Returns ​

A list of probabilities.

QResult.get_prob_dict ​

python
QResult.get_prob_dict(qubits: list[int] = []) -> dict[str, float]

Returns the probability distribution for the specified qubits as a dictionary mapping bitstrings to probabilities.

Parameters ​

ParameterTypeDescription
qubitslist[int]Optional list of qubit indices. If empty, returns probabilities for all qubits.

Returns ​

A dictionary mapping bitstrings to their probabilities.

QResult.shots ​

python
QResult.shots() -> int

Returns the total number of measurement shots performed.

Returns ​

The number of shots as an integer.

QResult.print_results ​

python
QResult.print_results() -> None

Prints the measurement results to standard output in the format bitstring: count, one per line.

See Also ​

StabilizerResult ​

Result object returned by Stabilizer.result(). Extends QResult with additional stabilizer-specific data.

Signature ​

python
class StabilizerResult(QResult):
    def get_state_vector() -> list[complex]
    def get_counts() -> dict[str, int]
    def get_prob_list(qubits: list[int] = []) -> list[float]
    def get_prob_dict(qubits: list[int] = []) -> dict[str, float]
    def shots() -> int
    def print_results() -> None

See QResult for full method documentation.

See Also ​

Released under the MIT License.

Copyright 2024-present Origin Quantum