API Reference

This page contains the auto-generated API reference for the pyrauli package.

pyrauli: A Python Wrapper for ProPauli

This package provides a high-performance Python interface for quantum circuit simulation, powered by the C++ propauli library.

class pyrauli.AlwaysAfterSplittingPolicy

Bases: SchedulingPolicy

A policy that applies an optimization just after every splitting gate.

class pyrauli.AlwaysBeforeSplittingPolicy

Bases: SchedulingPolicy

A policy that applies an optimization just before every splitting gate.

class pyrauli.Circuit

Bases: pybind11_object

Represents a quantum circuit and provides a high-level simulation interface.

add_operation(*args, **kwargs)

Overloaded function.

add_operation(self: pyrauli._core.Circuit, op: str, qubit: int) -> None

Adds a single-qubit gate.

add_operation(self: pyrauli._core.Circuit, op: str, qubit: int, param: float) -> None

Adds a single-qubit gate with a parameter.

add_operation(self: pyrauli._core.Circuit, op: str, control: int, target: int) -> None

Adds a two-qubit gate.

nb_qubits(self: pyrauli._core.Circuit) → int: Gets the number of qubits in the circuit.

reset(self: pyrauli._core.Circuit) → None: Clears all operations from the circuit.

run(self: pyrauli._core.Circuit, arg0: pyrauli._core.Observable) → pyrauli._core.Observable: Runs the simulation on the circuit.

set_merge_policy(self: pyrauli._core.Circuit, arg0: pyrauli._core.SchedulingPolicy) → None: Sets a new policy for when to merge Pauli terms.

set_truncate_policy(self: pyrauli._core.Circuit, arg0: pyrauli._core.SchedulingPolicy) → None: Sets a new policy for when to truncate the observable.

set_truncator(self: pyrauli._core.Circuit, arg0: pyrauli._core.Truncator) → None: Sets a new truncator for the circuit.

class pyrauli.CliffordGate

Bases: pybind11_object

Enumeration for single-qubit Clifford gates.

Members:

H : Hadamard gate.

H = <CliffordGate.H: 0>

property name

property value

class pyrauli.CoefficientTruncator

Bases: Truncator

Truncator that removes Pauli terms with small coefficients.

class pyrauli.CompressionResult

Bases: pybind11_object

Stores the result of a compression (merge or truncate) operation.

nb_terms_after(self: pyrauli._core.CompressionResult) → int: Number of terms after compression.

property nb_terms_before: Number of terms before compression.

property nb_terms_merged: Number of terms removed/merged.

class pyrauli.KeepNTruncator

Bases: Truncator

A truncator that removes least significant Pauli Terms, when their numbers is above a threshold.

class pyrauli.LambdaPolicy

Bases: SchedulingPolicy

A policy that uses a Python function to determine when to apply optimizations.

class pyrauli.LambdaTruncator

Bases: Truncator

A truncator that uses a Python function as a predicate.

class pyrauli.MultiTruncator

Bases: Truncator

A truncator that combines multiple truncators at runtime.

class pyrauli.NeverPolicy

Bases: SchedulingPolicy

A policy that never applies an optimization.

class pyrauli.NeverTruncator

Bases: Truncator

A truncator that never removes any terms.

class pyrauli.Noise

Bases: pybind11_object

Defines the strengths of different noise channels.

property amplitude_damping_strength

property dephasing_strength

property depolarizing_strength

class pyrauli.NoiseModel

Bases: pybind11_object

A model for applying noise to quantum gates.

add_amplitude_damping_on_gate(self: pyrauli._core.NoiseModel, arg0: pyrauli._core.QGate, arg1: float) → None: Adds an amplitude damping channel to be applied after a specific gate type.

add_unital_noise_on_gate(self: pyrauli._core.NoiseModel, arg0: pyrauli._core.QGate, arg1: pyrauli._core.UnitalNoise, arg2: float) → None: Adds a unital noise channel to be applied after a specific gate type.

class pyrauli.Observable

Bases: pybind11_object

Represents a quantum observable as a linear combination of Pauli strings.

apply_amplitude_damping(self: pyrauli._core.Observable, arg0: int, arg1: float) → None: Applies an amplitude damping noise channel.

apply_clifford(self: pyrauli._core.Observable, arg0: pyrauli._core.CliffordGate, arg1: int) → None: Applies a single-qubit Clifford gate to the observable.

apply_cx(self: pyrauli._core.Observable, arg0: int, arg1: int) → None: Applies a CNOT (CX) gate to the observable.

apply_pauli(self: pyrauli._core.Observable, arg0: pyrauli._core.PauliGate, arg1: int) → None: Applies a single-qubit Pauli gate to the observable.

apply_rz(self: pyrauli._core.Observable, arg0: int, arg1: float) → None: Applies a single-qubit Rz rotation gate to the observable.

apply_unital_noise(self: pyrauli._core.Observable, arg0: pyrauli._core.UnitalNoise, arg1: int, arg2: float) → None: Applies a single-qubit unital noise channel.

expectation_value(self: pyrauli._core.Observable) → float: Calculates the expectation value of the observable.

merge(self: pyrauli._core.Observable) → int: Merges Pauli terms with identical Pauli strings.

size(self: pyrauli._core.Observable) → int: Gets the number of Pauli terms in the observable.

truncate(self: pyrauli._core.Observable, arg0: Truncator<float>) → int: Truncates the observable based on a given truncation strategy.

class pyrauli.OperationType

Bases: pybind11_object

Type of operation in the simulation.

Members:

BasicGate

SplittingGate

Merge

Truncate

BasicGate = <OperationType.BasicGate: 0>

Merge = <OperationType.Merge: 2>

SplittingGate = <OperationType.SplittingGate: 1>

Truncate = <OperationType.Truncate: 3>

property name

property value

class pyrauli.PBackend(num_qubits: int = 128, noise_model: ~pyrauli._core.NoiseModel = None, truncator: ~pyrauli._core.Truncator = <pyrauli._core.NeverTruncator object>, merge_policy: ~pyrauli._core.SchedulingPolicy = <pyrauli._core.AlwaysAfterSplittingPolicy object>, truncate_policy: ~pyrauli._core.SchedulingPolicy = <pyrauli._core.AlwaysAfterSplittingPolicy object>, **kwargs)

Bases: BackendV2

A Qiskit BackendV2 that uses the pyrauli simulator.

This backend integrates pyrauli’s Pauli back-propagation engine into the Qiskit ecosystem, allowing it to be used as a target for Qiskit’s transpiler and as a simulator for running quantum circuits.

from qiskit.circuit import QuantumCircuit
from qiskit.quantum_info import SparsePauliOp
from pyrauli import PBackend

# Create a Qiskit circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

# Define an observable and instantiate the backend
obs = SparsePauliOp("ZI")
backend = PBackend()

# Run using the PUB (Primitive Unified Bloc) format
job = backend.run([(qc, obs)])
result = job.result()
ev = result.results[0].data.evs[0]

print(f"Expectation value from Qiskit backend: {ev}")

property max_circuits: int: The maximum number of circuits that can be run in a single job.

run(run_input: QuantumCircuit | List[QuantumCircuit], **options) → JobV1

Run a circuit or a list of circuits on the backend.

This backend uses a PyrauliEstimator to execute the circuits.

Parameters:

run_input – A QuantumCircuit or a list of them to run.
**options – Runtime options for the execution. may include: “noise_model”, “truncator”, “merge_policy”, “truncate_policy”

Returns:

A JobV1 object that represents the execution.

property target: Target: The Qiskit Target object for this backend, detailing supported gates and connectivity.

class pyrauli.Pauli

Bases: pybind11_object

Represents a single Pauli operator (I, X, Y, or Z).

apply_clifford(self: pyrauli._core.Pauli, arg0: pyrauli._core.CliffordGate) → float: Applies a single-qubit Clifford gate to this operator, modifying it in place.

apply_cx(self: pyrauli._core.Pauli, arg0: pyrauli._core.Pauli) → float: Applies the control part of a CNOT gate to this operator, modifying it and the target in place.

apply_pauli(self: pyrauli._core.Pauli, arg0: pyrauli._core.PauliGate) → float: Applies a Pauli gate to this operator (in the Heisenberg picture).

apply_unital_noise(self: pyrauli._core.Pauli, arg0: pyrauli._core.UnitalNoise, arg1: float) → float: Applies a unital noise channel to this operator.

commutes_with(self: pyrauli._core.Pauli, arg0: pyrauli._core.Pauli) → bool: Checks if this Pauli operator commutes with another.

weight(self: pyrauli._core.Pauli) → int: Calculates the Pauli weight (1 if not Identity, 0 otherwise).

class pyrauli.PauliEnum

Bases: pybind11_object

Enumeration for single Pauli operators (I, X, Y, Z).

Members:

I

X

Y

Z

I = <PauliEnum.I: 0>

X = <PauliEnum.X: 1>

Y = <PauliEnum.Y: 2>

Z = <PauliEnum.Z: 3>

property name

property value

class pyrauli.PauliGate

Bases: pybind11_object

Enumeration for single-qubit Pauli gates (I, X, Y, Z).

Members:

I

X

Y

Z

I = <PauliGate.I: 0>

X = <PauliGate.X: 1>

Y = <PauliGate.Y: 2>

Z = <PauliGate.Z: 3>

property name

property value

class pyrauli.PauliTerm

Bases: pybind11_object

Represents a single term in an observable, consisting of a Pauli string and a coefficient.

apply_amplitude_damping_xy(self: pyrauli._core.PauliTerm, arg0: int, arg1: float) → None: Applies the X/Y part of the amplitude damping channel.

apply_amplitude_damping_z(self: pyrauli._core.PauliTerm, arg0: int, arg1: float) → pyrauli._core.PauliTerm: Applies the Z part of the amplitude damping channel, splitting the term.

apply_clifford(self: pyrauli._core.PauliTerm, arg0: pyrauli._core.CliffordGate, arg1: int) → None: Applies a Clifford gate to a specific qubit of the term.

apply_cx(self: pyrauli._core.PauliTerm, arg0: int, arg1: int) → None: Applies a CNOT gate to the term.

apply_pauli(self: pyrauli._core.PauliTerm, arg0: pyrauli._core.PauliGate, arg1: int) → None: Applies a Pauli gate to a specific qubit of the term.

apply_rz(self: pyrauli._core.PauliTerm, arg0: int, arg1: float) → pyrauli._core.PauliTerm: Applies an Rz gate, potentially splitting the term.

apply_unital_noise(self: pyrauli._core.PauliTerm, arg0: pyrauli._core.UnitalNoise, arg1: int, arg2: float) → None: Applies a unital noise channel to a specific qubit of the term.

property coefficient: The coefficient of the term.

expectation_value(self: pyrauli._core.PauliTerm) → float: Calculates the expectation value of this single term.

pauli_weight(self: pyrauli._core.PauliTerm) → int: Calculates the Pauli weight (number of non-identity operators).

class pyrauli.PyrauliEstimator(noise_model: ~pyrauli._core.NoiseModel = None, truncator: ~pyrauli._core.Truncator = <pyrauli._core.NeverTruncator object>, merge_policy: ~pyrauli._core.SchedulingPolicy = <pyrauli._core.AlwaysAfterSplittingPolicy object>, truncate_policy: ~pyrauli._core.SchedulingPolicy = <pyrauli._core.AlwaysAfterSplittingPolicy object>)

Bases: BaseEstimatorV2

A Qiskit Estimator primitive that uses the pyrauli C++ simulator.

This estimator calculates the expectation values of observables for given quantum circuits, leveraging the high-performance Pauli back-propagation engine of pyrauli.

from qiskit.circuit import QuantumCircuit
from qiskit.quantum_info import SparsePauliOp
from pyrauli import PyrauliEstimator

estimator = PyrauliEstimator()
qc = QuantumCircuit(1)
qc.h(0)
obs = SparsePauliOp("Z") # EV of Z on |+> state is 0

job = estimator.run([(qc, obs)])
result = job.result()
print(result[0].data.evs[0])

run(run_input: List[Tuple], **options) → PJob

Run a list of pubs (Primitive Unified Blocs) on the estimator.

Parameters:

run_input – A list of pubs, where each pub is a tuple of (circuit, observables, parameter_values).
**options – Additional circuit options: “noise_model”, “truncator”, “truncate_policy”, “merge_policy”.

Returns:

A PJob object that represents the asynchronous execution.

class pyrauli.QGate

Bases: pybind11_object

Enumeration for all supported quantum gates and noise channels.

Members:

I

X

Y

Z

H

Rz

Cx

AmplitudeDamping

Depolarizing

Dephasing

AmplitudeDamping = <QGate.AmplitudeDamping: 7>

Cx = <QGate.Cx: 6>

Dephasing = <QGate.Dephasing: 9>

Depolarizing = <QGate.Depolarizing: 8>

H = <QGate.H: 4>

I = <QGate.I: 0>

Rz = <QGate.Rz: 5>

X = <QGate.X: 1>

Y = <QGate.Y: 2>

Z = <QGate.Z: 3>

property name

property value

class pyrauli.SchedulingPolicy

Bases: pybind11_object

Abstract base class for defining scheduling policies.

class pyrauli.SimulationState

Bases: pybind11_object

Holds the state of the simulation at a given point in time.

property merge_history: History of merge operations.

property nb_gates_applied: Total number of gates applied so far.

property nb_splitting_gates_applied: Number of splitting gates applied so far.

property nb_splitting_gates_left: Number of splitting gates remaining in the circuit.

property terms_history: History of observable sizes after each operation.

property truncate_history: History of truncate operations.

class pyrauli.Timing

Bases: pybind11_object

Timing of a policy application relative to an operation.

Members:

Before

After

After = <Timing.After: 1>

Before = <Timing.Before: 0>

property name

property value

class pyrauli.Truncator

Bases: pybind11_object

Abstract base class for defining truncation strategies.

class pyrauli.UnitalNoise

Bases: pybind11_object

Enumeration for unital noise channels.

Members:

Depolarizing : Depolarizing noise channel.

Dephasing : Dephasing noise channel.

Dephasing = <UnitalNoise.Dephasing: 1>

Depolarizing = <UnitalNoise.Depolarizing: 0>

property name

property value

class pyrauli.WeightTruncator

Bases: Truncator

Truncator that removes Pauli terms with high Pauli weight.

pyrauli.from_qiskit(qiskit_obj, noise_model: NoiseModel = None, reverse=False)

Converts a Qiskit object to its pyrauli equivalent.

Parameters:

qiskit_obj – The Qiskit object to convert (QuantumCircuit or SparsePauliOp).
noise_model – A pyrauli NoiseModel to apply to the circuit.

Returns:

The equivalent pyrauli object.