PauliOperator

PauliOperator represents a weighted sum of Pauli strings acting on qubits. It is the primary class for defining quantum observables and problem Hamiltonians in pyqpanda3. Each term in the operator is a tensor product of Pauli matrices ( $I$ , $X$ , $Y$ , $Z$ ) on specific qubits, multiplied by a complex coefficient:

O = \sum_{i} c_{i} ⨂_{j} σ_{i j}

where $σ_{i j} \in {I, X, Y, Z}$ and $c_{i} \in C$ .

The four Pauli matrices are:

I = (\begin{matrix} 1 & 0 \\ 0 & 1 \end{matrix}), X = (\begin{matrix} 0 & 1 \\ 1 & 0 \end{matrix}), Y = (\begin{matrix} 0 & - i \\ i & 0 \end{matrix}), Z = (\begin{matrix} 1 & 0 \\ 0 & - 1 \end{matrix})

Construction

Default constructor

python

PauliOperator() -> PauliOperator

Constructs an empty (null) PauliOperator with no terms.

Copy constructor

python

PauliOperator(pauli_operator: PauliOperator) -> PauliOperator

Parameter	Type	Description
`pauli_operator`	`PauliOperator`	An existing PauliOperator to deep-copy.

From string

python

PauliOperator(pauli: str) -> PauliOperator

Constructs a PauliOperator from a single Pauli character, creating a single-term operator on qubit 0.

Parameter	Type	Description
`pauli`	`str`	A single Pauli character (`"X"`, `"Y"`, `"Z"`, or `"I"`). Creates a single-term Pauli operator on qubit 0.

From dictionary

python

PauliOperator(pauli_with_coef_s: dict[str, complex]) -> PauliOperator

Constructs a PauliOperator from a dictionary mapping Pauli strings to complex coefficients.

Parameter	Type	Description
`pauli_with_coef_s`	`dict[str, complex]`	A dict such as `{"X0 Z1": 1.1, "Y2 I1": 2.1+0j}`.

From parallel lists (sparse notation)

python

PauliOperator(paulis: list[str], coefs: list[complex]) -> PauliOperator

Constructs from two parallel lists -- Pauli strings and their coefficients.

Parameter	Type	Description
`paulis`	`list[str]`	A list of Pauli strings such as `["X0 Z1", "Y2 I1"]`.
`coefs`	`list[complex]`	A list of coefficients such as `[1.1+0j, 2.1+0j]`. Must be the same length as `paulis`.

From parallel lists (compact notation)

python

PauliOperator(paulis: list[str], coefs: list[complex], AB_is_A1_B0: bool) -> PauliOperator

Constructs from parallel lists using compact Pauli notation, where each string character maps positionally to a qubit index.

Parameter	Type	Description
`paulis`	`list[str]`	A list of compact Pauli strings such as `["XZI", "IZX"]`. Character position maps to qubit index.
`coefs`	`list[complex]`	A list of coefficients such as `[1.1+0j, 2.1+0j]`. Must be the same length as `paulis`.
`AB_is_A1_B0`	`bool`	If `True`, uses big-endian ordering where character index 0 corresponds to the highest qubit index (a.k.a. A1 B0 convention). If `False`, character index 0 corresponds to qubit 0 (little-endian).

From list of tuples

python

PauliOperator(paulis_qbits_coef__s: list[tuple[str, list[int], complex]]) -> PauliOperator

Constructs from a list of tuples, each specifying a Pauli string, the qubit indices, and a coefficient.

Parameter	Type	Description
`paulis_qbits_coef__s`	`list[tuple[str, list[int], complex]]`	For example `[("XZ", [0, 4], 1.1+0j), ("YX", [1, 2], 2.1+0j)]`. Each tuple is `(pauli_string, qubit_indices, coefficient)`.

From matrix

python

PauliOperator(mat: numpy.ndarray) -> PauliOperator

Constructs a PauliOperator by decomposing a real-valued matrix into a sum of Pauli strings.

Parameter	Type	Description
`mat`	`numpy.ndarray`	A real-valued square matrix (2D, double-precision). The matrix dimension must be a power of 2.

Operators

Addition

python

PauliOperator.__add__(other: PauliOperator) -> PauliOperator
PauliOperator.__add__(num: complex) -> PauliOperator
PauliOperator.__radd__(num: complex) -> PauliOperator
PauliOperator.__iadd__(other: PauliOperator) -> PauliOperator
PauliOperator.__iadd__(num: complex) -> PauliOperator

Adds two PauliOperators or adds a scalar (treated as a coefficient on the identity). When two terms have identical Pauli strings, their coefficients are summed. Returns a new PauliOperator.

Subtraction

python

PauliOperator.__sub__(other: PauliOperator) -> PauliOperator
PauliOperator.__sub__(num: complex) -> PauliOperator
PauliOperator.__rsub__(num: complex) -> PauliOperator
PauliOperator.__isub__(other: PauliOperator) -> PauliOperator
PauliOperator.__isub__(num: complex) -> PauliOperator

Subtracts one PauliOperator from another, or subtracts a scalar. For num - self, the result is equivalent to PauliOperator("I") * num - self.

Unary negation

python

PauliOperator.__neg__() -> PauliOperator

Returns the negation of the operator, equivalent to self * (-1).

Multiplication

python

PauliOperator.__mul__(other: PauliOperator) -> PauliOperator
PauliOperator.__mul__(scalar: complex) -> PauliOperator
PauliOperator.__rmul__(scalar: complex) -> PauliOperator

Multiplies two PauliOperators (following Pauli algebra rules: $X^{2} = I$ , $X Y = i Z$ , etc.) or scales all coefficients by a scalar. Returns a new PauliOperator.

In-place multiplication

python

PauliOperator.__imul__(other: PauliOperator) -> PauliOperator

Multiplies the current PauliOperator by another PauliOperator in place, following Pauli algebra rules. The current object is updated to be the product.

Matrix multiplication (@)

python

PauliOperator.__matmul__(other: PauliOperator) -> PauliOperator

Equivalent to __mul__. Computes the product of two PauliOperators using Pauli algebra.

Tensor product

python

PauliOperator.tensor(other: PauliOperator) -> PauliOperator
PauliOperator.tensor(n: int) -> PauliOperator

Computes the tensor product (Kronecker product) of this operator with another, or with itself n-1 times. In the result, qubit indices of the left operand remain unchanged, while indices of the right operand are shifted by the number of qubits in the left operand.

Copy

python

PauliOperator.__copy__() -> PauliOperator

Returns a copy of this PauliOperator.

Equality

python

PauliOperator.__eq__(other: PauliOperator) -> bool

Two PauliOperators are equal if they have the same terms with the same coefficients.

Methods

str_with_I

python

PauliOperator.str_with_I(AB_is_A1_B0: bool = True) -> str

Returns a formatted string representation in compact Pauli notation, including identity (I) characters. If AB_is_A1_B0 is True, the first character in the string corresponds to the highest qubit index.

Parameter	Type	Description
`AB_is_A1_B0`	`bool`	Controls qubit-to-character index ordering. Default `True`.

Returns: A formatted string representation showing the Pauli operators in compact notation, such as { qbit_totql = 2, paulis = ['ZX'], coefs = [1 + 0j] }.

str_no_I / str_without_I

python

PauliOperator.str_no_I() -> str
PauliOperator.str_without_I() -> str

Returns a string representation excluding identity terms, in the same format as print().

Returns: A formatted string representation such as { qubit_total = 2, pauli_with_coef_s = { 'X0 Z1 ':1 + 0j, } }.

matrix

python

PauliOperator.matrix() -> numpy.ndarray

Converts the PauliOperator to its dense matrix representation.

Returns: A complex-valued NumPy array of shape (2^n, 2^n) where n is the number of qubits.

group_commuting

python

PauliOperator.group_commuting(qubit_wise: bool = False) -> list[PauliOperator]

Groups the terms into commuting subsets.

Parameter	Type	Description
`qubit_wise`	`bool`	If `True`, use qubit-wise commutation (Paulis on the same qubit must commute). If `False`, use full commutation (commutator equals zero). Default `False`.

Returns: A list of PauliOperator objects, each representing a group of mutually commuting terms.

terms

python

PauliOperator.terms() -> list[PauliTerm]

Returns the individual Pauli terms that make up this operator.

Returns: A list of PauliTerm objects.

to_qcircuits

python

PauliOperator.to_qcircuits() -> list[tuple[QCircuit, complex]]

Converts each term into a quantum circuit paired with its coefficient.

Returns: A list of (QCircuit, complex) tuples.

to_hamiltonian_pq2

python

PauliOperator.to_hamiltonian_pq2() -> list[tuple[dict[int, str], complex]]

Converts the PauliOperator to the legacy QPanda2 QHamiltonian term representation.

Returns: A list of (dict[int, str], complex) tuples compatible with legacy QPanda2 APIs.

qubits

python

PauliOperator.qubits() -> tuple[list[int], list[int]]

Returns the qubits involved in the operator, partitioned into those acted on only by identity and those acted on by non-identity Paulis.

Returns: A tuple (identity_only_qubits, non_identity_qubits).

max_qbit_idx

python

PauliOperator.max_qbit_idx() -> int

Returns the maximum qubit index referenced by any term in the operator.

Returns: An integer qubit index.

data_3tuple_list_complex_coeff

python

PauliOperator.data_3tuple_list_complex_coeff() -> list[tuple[str, list[int], complex]]

Returns the internal data as a list of (pauli_string, qubit_indices, complex_coefficient) tuples.

Returns: For example [("XXZ", [0, 1, 4], 1+2j), ("ZZ", [1, 2], -1+1j)].

data_3tuple_list_float_coeff

python

PauliOperator.data_3tuple_list_float_coeff() -> list[tuple[str, list[int], float]]

Returns the internal data as a list of (pauli_string, qubit_indices, float_coefficient) tuples. Raises an error if any coefficient has a non-zero imaginary part.

Returns: For example [("XXZ", [0, 1, 4], 1.0), ("ZZ", [1, 2], -1.0)].

data_dict_float_coeff

python

PauliOperator.data_dict_float_coeff() -> dict[str, float]

Returns the operator data as a dictionary mapping Pauli strings to float coefficients.

Returns: For example {"Z0": 0.395, "Z1": -0.395}.

data_dict_complex_coeff

python

PauliOperator.data_dict_complex_coeff() -> dict[str, complex]

Returns the operator data as a dictionary mapping Pauli strings to complex coefficients.

Returns: For example {"Z0": 0.395+0j, "Z1": -0.395+0j}.

data_dict_str

python

PauliOperator.data_dict_str(is_coeff_complex: bool = True, double_quote: bool = True) -> str

Serializes the operator to a string format suitable for later deserialization.

Parameter	Type	Description
`is_coeff_complex`	`bool`	Whether to serialize coefficients as complex numbers. Default `True`.
`double_quote`	`bool`	Whether to use double quotes for keys. Default `True`.

Returns: A serialized string like '"Z0": 0.395, "Z1": -0.395'.

from_dict_str (static)

python

PauliOperator.from_dict_str(dict_str: str) -> PauliOperator

Deserializes a string produced by data_dict_str() back into a PauliOperator.

Parameter	Type	Description
`dict_str`	`str`	A serialized string like `'"Z0": 0.395, "Z1": -0.395'`.

Returns: A new PauliOperator.

Examples

Construct from a dictionary

A common pattern for defining Hamiltonians is to pass a dictionary of Pauli strings and coefficients.

python

from pyqpanda3.hamiltonian import PauliOperator

# Define a 2-qubit Hamiltonian:
# H = 0.5 * Z0 Z1 + 0.3 * X0 + 0.1 * X1
h = PauliOperator({"Z0 Z1": 0.5, "X0": 0.3, "X1": 0.1})
print(h)

运行结果：

{ qubit_total = 2, pauli_with_coef_s = { 'Z0 Z1 ':0.5 + 0j, 'X0 ':0.3 + 0j, 'X1 ':0.1 + 0j, } }

Construct from compact notation with flag

python

from pyqpanda3.hamiltonian import PauliOperator

# Compact strings: character position maps to qubit index
# "XZ" with qubit indices [0, 1] means X on qubit 0, Z on qubit 1
h = PauliOperator(["XZ", "ZX"], [1.0+0j, -1.0+0j], True)
print(h)

运行结果：

{ qubit_total = 2, pauli_with_coef_s = { 'Z0 X1 ':1 + 0j, 'X0 Z1 ':-1 + 0j, } }

Arithmetic operations

python

from pyqpanda3.hamiltonian import PauliOperator

a = PauliOperator({"X0": 1.0})
b = PauliOperator({"Z0": 1.0})

# Addition
s = a + b
print("a + b =", s)

# Multiplication (Pauli algebra: X * Z = -iY)
p = a * b
print("a * b =", p)

# Scalar multiplication
scaled = 2.0 * a
print("2 * a =", scaled)

# Negation
neg = -a
print("-a =", neg)

运行结果：

a + b = { qubit_total = 1, pauli_with_coef_s = { 'X0 ':1 + 0j, 'Z0 ':1 + 0j, } }
a * b = { qubit_total = 1, pauli_with_coef_s = { 'Y0 ':0 -1j, } }
2 * a = { qubit_total = 1, pauli_with_coef_s = { 'X0 ':2 + 0j, } }
-a = { qubit_total = 1, pauli_with_coef_s = { 'X0 ':-1 + 0j, } }

Tensor product

python

from pyqpanda3.hamiltonian import PauliOperator

a = PauliOperator({"X0": 1.0})
b = PauliOperator({"Z0": 1.0})

# Tensor product: b's qubits are shifted
t = a.tensor(b)
print("a tensor b =", t)
# Result: X0 Z1 with coefficient 1.0

运行结果：

a tensor b = { qubit_total = 2, pauli_with_coef_s = { 'X0 Z1 ':1 + 0j, } }

Matrix representation

python

from pyqpanda3.hamiltonian import PauliOperator

h = PauliOperator({"Z0": 1.0, "X0": 0.5})
mat = h.matrix()
print(mat)

运行结果：

[[ 1. +0.j  0.5+0.j]
 [ 0.5+0.j -1. +0.j]]

Group commuting terms

python

from pyqpanda3.hamiltonian import PauliOperator

h = PauliOperator({"X0": 1.0, "Z0": 1.0, "X1": 0.5})
groups = h.group_commuting(qubit_wise=True)
for i, group in enumerate(groups):
    print(f"Group {i}: {group}")

运行结果：

Group 0: { qubit_total = 2, pauli_with_coef_s = { 'X0 ':1 + 0j, 'X1 ':0.5 + 0j, } }
Group 1: { qubit_total = 2, pauli_with_coef_s = { 'Z0 ':1 + 0j, } }

Serialize and deserialize

python

from pyqpanda3.hamiltonian import PauliOperator

h = PauliOperator({"Z0": 0.5, "X1": -0.3})
s = h.data_dict_str()
print("Serialized:", s)

h2 = PauliOperator.from_dict_str(s)
print("Deserialized:", h2)
print("Equal:", h == h2)

运行结果：

Serialized: "Z0":0.500000000000000000+0.000000000000000000j,"X1":-0.299999999999999989+0.000000000000000000j
Deserialized: { qubit_total = 2, pauli_with_coef_s = { 'Z0 ':0.5 + 0j, 'X1 ':-0.3 + 0j, } }
Equal: True

PauliOperator ​

Construction ​

Default constructor ​

Copy constructor ​

From string ​

From dictionary ​

From parallel lists (sparse notation) ​

From parallel lists (compact notation) ​

From list of tuples ​

From matrix ​

Operators ​

Addition ​

Subtraction ​

Unary negation ​

Multiplication ​

In-place multiplication ​

Matrix multiplication (@) ​

Tensor product ​

Copy ​

Equality ​

Methods ​

str_with_I ​

str_no_I / str_without_I ​

matrix ​

group_commuting ​

terms ​

to_qcircuits ​

to_hamiltonian_pq2 ​

qubits ​

max_qbit_idx ​

data_3tuple_list_complex_coeff ​

data_3tuple_list_float_coeff ​

data_dict_float_coeff ​

data_dict_complex_coeff ​

data_dict_str ​

from_dict_str (static) ​

Examples ​

Construct from a dictionary ​

Construct from compact notation with flag ​

Arithmetic operations ​

Tensor product ​

Matrix representation ​

Group commuting terms ​

Serialize and deserialize ​

See Also ​

PauliOperator

Construction

Default constructor

Copy constructor

From string

From dictionary

From parallel lists (sparse notation)

From parallel lists (compact notation)

From list of tuples

From matrix

Operators

Addition

Subtraction

Unary negation

Multiplication

In-place multiplication

Matrix multiplication (@)

Tensor product

Copy

Equality

Methods

str_with_I

str_no_I / str_without_I

matrix

group_commuting

terms

to_qcircuits

to_hamiltonian_pq2

qubits

max_qbit_idx

data_3tuple_list_complex_coeff

data_3tuple_list_float_coeff

data_dict_float_coeff

data_dict_complex_coeff

data_dict_str

from_dict_str (static)

Examples

Construct from a dictionary

Construct from compact notation with flag

Arithmetic operations

Tensor product

Matrix representation

Group commuting terms

Serialize and deserialize

See Also