propaq.datatypes

Operator representations: individual basis terms, the weighted sums that collect them, and the lazy streamers that read a saved sum back one term at a time.

See Core concepts for how these relate to the Pauli and Majorana bases, and Streaming and I/O for the file format and streamers.

datatypes

Datatypes for propaq.

Classes:

Name	Description
PauliString	An n-qubit Pauli operator encoded as two integer bitmasks.
PauliTermSum	Class representing a sum of Pauli terms:
MajoranaMonomial	A Majorana monomial, a product of Majorana operators encoded as a mode bitmask.
MajoranaTermSum	Class representing a sum of Majorana monomials:
PauliTermStreamer
MajoranaTermStreamer
AbstractTerm	Abstract monomial datatype. Concrete examples: PauliString, MajoranaMonomial.
AbstractTermSum	Abstract container for a linear combination of monomials with complex coefficients.
DictTermSum	A dict-backed sum of basis terms with complex coefficients.

PauliString

An n-qubit Pauli operator encoded as two integer bitmasks.

x and z together encode the single-qubit Pauli on each qubit:

00 -> I, 01 -> X, 10 -> Z, 11 -> Y

Parameters:

Name	Type	Description	Default
x		Integer bitmask where bit k is set if qubit k has an X or Y component.	required
z		Integer bitmask where bit k is set if qubit k has a Z or Y component.	required
n_qubits		Total number of qubits in the system.	required

Methods:

Name	Description
commutes_with	Return True if this Pauli string commutes with other.
to_bytes	Serialize the monomial as little-endian X bytes concatenated with Z bytes.
trace_with_diag_state	Compute \(\langle \psi | P | \psi \rangle\) for this Pauli string P.

Attributes:

Name	Type	Description
n_qubits	int
weight	int	Number of non-identity single-qubit Pauli operators (popcount of x | z).
x	Any	X-component bitmask as a Python int.
z	Any	Z-component bitmask as a Python int.

n_qubits property

n_qubits: int

weight property

weight: int

Number of non-identity single-qubit Pauli operators (popcount of x | z).

x property

x: Any

X-component bitmask as a Python int.

z property

z: Any

Z-component bitmask as a Python int.

commutes_with method descriptor

commutes_with(other: PauliString) -> bool

Return True if this Pauli string commutes with other.

Two Pauli strings commute iff the number of positions where they anticommute is even.

Parameters:

Name	Type	Description	Default
other	PauliString	Another PauliString to check commutation with.	required

Returns:

Type	Description
bool	True if self and other commute, False otherwise.

to_bytes method descriptor

to_bytes() -> bytes

Serialize the monomial as little-endian X bytes concatenated with Z bytes.

trace_with_diag_state method descriptor

trace_with_diag_state(diag_state: Any) -> float

Compute \(\langle \psi | P | \psi \rangle\) for this Pauli string P.

Returns 0.0 if P has any X or Y components (off-diagonal). For Z-only P, returns \((-1)^{\text{popcount}(z \text{ AND } \psi)}\).

Parameters:

Name	Type	Description	Default
diag_state	Any	Computational basis state as a bitstring integer.	required

Returns: Expectation value of the Pauli string in the given basis state.

PauliTermSum

Bases: PauliTermSum, Generic[T]

Class representing a sum of Pauli terms:

\[ \sum_i c_i P_i \]

Backend is implemented in Rust for performance, but this class provides a Python interface for constructing and manipulating sums of Pauli terms.

Methods:

Name	Description
add	Add coeff x term to the sum, accumulating if the monomial is already present.
apply_damping	Apply noise damping to every coefficient.
copy	Return a shallow copy of this term sum.
from_file	Load a PauliTermSum from a gzip-compressed binary file saved by propagate or
items	Return all (monomial, coefficient) pairs.
merge	Add all terms from other into this sum. Both sums must share the same dtype.
merge_from_file	Stream terms from a file and merge them into this sum one at a time,
norm_squared	Return the sum of |coefficient|^2 over all terms.
save	Save this term sum to a gzip-compressed binary file. Coefficients are
scale	Multiply every coefficient by factor in-place.
from_xx_plus_yy	Construct from an XX+YY gate between qubits q_indices[0] and q_indices[1].
from_phase	Construct from a phase gate on qubit q_indices[0].
from_rz_angle	Construct from a raw Rz rotation angle.
from_rz	Construct from an RZ gate.
from_cp	Construct from a controlled-phase gate between q_indices[0] and q_indices[1].
from_swap	Construct from a SWAP gate between q_indices[0] and q_indices[1].
from_x	Construct from an X gate on qubit q_indices[0].
from_sparse_pauli_op	Construct directly from a SparsePauliOp.
to_sparse_pauli_op	Convert this PauliTermSum back to a Qiskit SparsePauliOp.

Attributes:

Name	Type	Description
dtype	str	Coefficient precision: "float64" or "float32".
sparse_key_bytes	int	Bytes of resident sparse key storage held by this term sum.

dtype property

dtype: str

Coefficient precision: "float64" or "float32".

sparse_key_bytes property

sparse_key_bytes: int

Bytes of resident sparse key storage held by this term sum.

Keys only: coefficients and merge metadata are excluded.

add method descriptor

add(term: PauliString, coeff: float) -> None

Add coeff x term to the sum, accumulating if the monomial is already present.

apply_damping method descriptor

apply_damping(noise: Any, active_modes: int) -> None

Apply noise damping to every coefficient.

copy method descriptor

copy() -> PauliTermSum

Return a shallow copy of this term sum.

from_file staticmethod

from_file(path: str) -> PauliTermSum

Load a PauliTermSum from a gzip-compressed binary file saved by propagate or expectation_value. Always loads as float64 (the file format's precision).

Parameters:

Name	Type	Description	Default
path	str	Path to the file written by the filename parameter.	required

items method descriptor

items() -> list[tuple[PauliString, float]]

Return all (monomial, coefficient) pairs.

merge method descriptor

merge(other: PauliTermSum) -> None

Add all terms from other into this sum. Both sums must share the same dtype.

merge_from_file method descriptor

merge_from_file(streamer: PauliTermStreamer) -> None

Stream terms from a file and merge them into this sum one at a time, accumulating coefficients for strings already present. The file is always f64; values are cast down if this sum is float32.

Parameters:

Name	Type	Description	Default
streamer	PauliTermStreamer	A PauliTermStreamer opened with PauliTermStreamer.from_file().	required

norm_squared method descriptor

norm_squared() -> float

Return the sum of |coefficient|^2 over all terms.

save method descriptor

save(path: str) -> None

Save this term sum to a gzip-compressed binary file. Coefficients are always widened to f64 on disk regardless of in-memory precision.

Parameters:

Name	Type	Description	Default
path	str	Destination file path.	required

scale method descriptor

scale(factor: float) -> None

Multiply every coefficient by factor in-place.

from_xx_plus_yy classmethod

from_xx_plus_yy(instr: Instruction, q_indices: list[int], n_modes: int) -> PauliTermSum[PauliString]

Construct from an XX+YY gate between qubits q_indices[0] and q_indices[1].

Parameters:

Name	Type	Description	Default
instr	Instruction	The instruction representing the gate.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of qubits in the system.	required

Returns:

Type	Description
PauliTermSum[PauliString]	The corresponding PauliTermSum.

from_phase classmethod

from_phase(instr: Instruction, q_indices: list[int], n_modes: int) -> PauliTermSum[PauliString]

Construct from a phase gate on qubit q_indices[0].

Parameters:

Name	Type	Description	Default
instr	Instruction	The instruction representing the gate.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of qubits in the system.	required

Returns:

Type	Description
PauliTermSum[PauliString]	The corresponding PauliTermSum.

from_rz_angle classmethod

from_rz_angle(q: int, angle: float, n_modes: int) -> PauliTermSum[PauliString]

Construct from a raw Rz rotation angle.

Parameters:

Name	Type	Description	Default
q	int	The index of the qubit the gate acts on.	required
angle	float	The rotation angle in radians.	required
n_modes	int	The total number of qubits in the system.	required

Returns:

Type	Description
PauliTermSum[PauliString]	The corresponding PauliTermSum.

from_rz classmethod

from_rz(instr: Instruction, q_indices: list[int], n_modes: int) -> PauliTermSum[PauliString]

Construct from an RZ gate.

Parameters:

Name	Type	Description	Default
instr	Instruction	The instruction representing the gate.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of qubits in the system.	required

Returns:

Type	Description
PauliTermSum[PauliString]	The corresponding PauliTermSum.

from_cp classmethod

from_cp(instr: Instruction, q_indices: list[int], n_modes: int) -> PauliTermSum[PauliString]

Construct from a controlled-phase gate between q_indices[0] and q_indices[1].

Parameters:

Name	Type	Description	Default
instr	Instruction	The instruction representing the gate.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of qubits in the system.	required

Returns:

Type	Description
PauliTermSum[PauliString]	The corresponding PauliTermSum.

from_swap classmethod

from_swap(instr: Instruction | None, q_indices: list[int], n_modes: int) -> PauliTermSum[PauliString]

Construct from a SWAP gate between q_indices[0] and q_indices[1].

Parameters:

Name	Type	Description	Default
instr	Instruction | None	The instruction representing the gate, if any (unused; SWAP carries no gate parameters). None when called from a non-Qiskit frontend, e.g. propaq.circuits._cirq_gates.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of qubits in the system.	required

Returns:

Type	Description
PauliTermSum[PauliString]	The corresponding PauliTermSum.

from_x classmethod

from_x(instr: Instruction, q_indices: list[int], n_modes: int) -> PauliTermSum[PauliString]

Construct from an X gate on qubit q_indices[0].

Parameters:

Name	Type	Description	Default
instr	Instruction	The instruction representing the gate.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of qubits in the system.	required

Returns:

Type	Description
PauliTermSum[PauliString]	The corresponding PauliTermSum.

from_sparse_pauli_op classmethod

from_sparse_pauli_op(op: SparsePauliOp) -> PauliTermSum[PauliString]

Construct directly from a SparsePauliOp.

Parameters:

Name	Type	Description	Default
op	SparsePauliOp	The SparsePauliOp to convert.	required

Returns:

Type	Description
PauliTermSum[PauliString]	The corresponding PauliTermSum.

to_sparse_pauli_op

to_sparse_pauli_op() -> SparsePauliOp

Convert this PauliTermSum back to a Qiskit SparsePauliOp.

Raises:

Type	Description
ValueError	If the term sum is empty (n_qubits cannot be inferred).

Returns:

Type	Description
SparsePauliOp	The equivalent SparsePauliOp with simplified (deduplicated) terms.

MajoranaMonomial

A Majorana monomial, a product of Majorana operators encoded as a mode bitmask.

Bit 2k is set if \(\gamma_{2k}\) (even mode) is active on site k. Bit 2k+1 is set if \(\gamma_{2k+1}\) (odd mode) is active on site k.

Parameters:

Name	Type	Description	Default
modes		Integer bitmask encoding occupied Majorana modes.	required
n_modes		Total number of Majorana modes (must be even, equal to 2 * n_qubits).	required
is_number_preserving		Whether the monomial preserves particle number (default True).	required

Methods:

Name	Description
commutes_with	Return True if this monomial commutes with other.
overlap	Number of Majorana modes shared with other (popcount of modes & other.modes).
resulting_weight	Pauli weight of the product monomial self @ other, without computing the full product.
to_bytes	Serialize the mode bitmask as a little-endian byte string.
trace_with_diag_state	Compute \(\langle \psi |M| \psi \rangle\) for this Majorana monomial M.

Attributes:

Name	Type	Description
is_number_preserving	bool
length	int	Number of active Majorana modes in the monomial (popcount of the mode bitmask).
modes	Any	The active mode indices as a Python integer bitmask.
n_modes	int
weight	int	Pauli weight of this monomial under the Jordan-Wigner mapping.

is_number_preserving property

is_number_preserving: bool

length property

length: int

Number of active Majorana modes in the monomial (popcount of the mode bitmask).

modes property

modes: Any

The active mode indices as a Python integer bitmask.

n_modes property

n_modes: int

weight property

weight: int

Pauli weight of this monomial under the Jordan-Wigner mapping.

commutes_with method descriptor

commutes_with(other: MajoranaMonomial) -> bool

Return True if this monomial commutes with other. Arguments: other: Another MajoranaMonomial to check commutation with. Returns: True if self and other commute, False otherwise.

overlap method descriptor

overlap(other: MajoranaMonomial) -> int

Number of Majorana modes shared with other (popcount of modes & other.modes). Arguments: other: Another MajoranaMonomial to compare with. Returns: The number of Majorana modes that are active in both self and other.

resulting_weight method descriptor

resulting_weight(other: MajoranaMonomial) -> int

Pauli weight of the product monomial self @ other, without computing the full product. Arguments: other: Another MajoranaMonomial to multiply with. Returns: The Pauli weight of the resulting monomial from multiplying self and other.

to_bytes method descriptor

to_bytes() -> bytes

Serialize the mode bitmask as a little-endian byte string.

trace_with_diag_state method descriptor

trace_with_diag_state(diag_state: Any) -> float

Compute \(\langle \psi |M| \psi \rangle\) for this Majorana monomial M.

Returns 0.0 if M has any unpaired modes. For paired modes, returns the product of \((2n_k - 1)\) values for each occupied pair.

Parameters:

Name	Type	Description	Default
diag_state	Any	Computational basis state as a bitstring integer.	required

Returns: Expectation value of the Majorana monomial in the given basis state.

MajoranaTermSum

Bases: MajoranaTermSum, Generic[T]

Class representing a sum of Majorana monomials:

\[ \sum_i c_i M_i \]

Backend is implemented in Rust for performance, but this class provides a Python interface for constructing and manipulating sums of Majorana monomials.

Methods:

Name	Description
add	Add coeff * term to the sum, accumulating if the monomial is already present.
apply_damping	Apply noise damping to every coefficient.
copy	Return a shallow copy of this term sum.
from_file	Load a MajoranaTermSum from a gzip-compressed binary file saved by propagate or
items	Return all (monomial, coefficient) pairs.
merge	Add all terms from other into this sum. Both sums must share the same dtype.
merge_from_file	Stream terms from a file and merge them into this sum one at a time,
norm_squared	Return the sum of |coefficient|^2 over all terms.
save	Save this term sum to a gzip-compressed binary file. Coefficients are
scale	Multiply every coefficient by factor in-place.
truncate	Deduplicate and remove terms according to policy.
from_xx_plus_yy	Construct from an XX+YY gate between qubits q_indices[0] and q_indices[1].
from_phase	Construct from a phase gate on qubit q_indices[0].
from_rz_angle	Construct from a raw Rz rotation angle.
from_rz	Construct from an RZ gate.
from_cp	Construct from a controlled-phase gate between q_indices[0] and q_indices[1].
from_swap	Construct from a SWAP gate between q_indices[0] and q_indices[1].
from_x	Construct from an X gate on qubit q_indices[0].
from_sparse_pauli_op	Construct from a SparsePauliOp via the Jordan-Wigner inverse transform.
from_openfermion	Construct from an OpenFermion FermionOperator.
from_ffsim	Construct from an ffsim object supporting the SupportsFermionOperator protocol
to_sparse_pauli_op	Convert this MajoranaTermSum back to a Qiskit SparsePauliOp via the inverse

Attributes:

Name	Type	Description
dtype	str	Coefficient precision: "float64" or "float32".
sparse_key_bytes	int	Bytes of resident sparse key storage held by this term sum.

dtype property

dtype: str

Coefficient precision: "float64" or "float32".

sparse_key_bytes property

sparse_key_bytes: int

Bytes of resident sparse key storage held by this term sum.

Keys only: coefficients and merge metadata are excluded.

add method descriptor

add(term: MajoranaMonomial, coeff: float) -> None

Add coeff * term to the sum, accumulating if the monomial is already present.

apply_damping method descriptor

apply_damping(noise: Any, active_modes: int) -> None

Apply noise damping to every coefficient.

copy method descriptor

copy() -> MajoranaTermSum

Return a shallow copy of this term sum.

from_file staticmethod

from_file(path: str) -> MajoranaTermSum

Load a MajoranaTermSum from a gzip-compressed binary file saved by propagate or expectation_value. Always loads as float64 (the file format's precision).

Parameters:

Name	Type	Description	Default
path	str	Path to the file written by the filename parameter.	required

items method descriptor

items() -> list[tuple[MajoranaMonomial, float]]

Return all (monomial, coefficient) pairs.

merge method descriptor

merge(other: MajoranaTermSum) -> None

Add all terms from other into this sum. Both sums must share the same dtype.

merge_from_file method descriptor

merge_from_file(streamer: MajoranaTermStreamer) -> None

Stream terms from a file and merge them into this sum one at a time, accumulating coefficients for monomials already present. The file is always f64; values are cast down if this sum is float32.

Parameters:

Name	Type	Description	Default
streamer	MajoranaTermStreamer	A MajoranaTermStreamer opened with MajoranaTermStreamer.from_file().	required

norm_squared method descriptor

norm_squared() -> float

Return the sum of |coefficient|^2 over all terms.

save method descriptor

save(path: str) -> None

Save this term sum to a gzip-compressed binary file. Coefficients are always widened to f64 on disk regardless of in-memory precision.

Parameters:

Name	Type	Description	Default
path	str	Destination file path.	required

scale method descriptor

scale(factor: float) -> None

Multiply every coefficient by factor in-place.

truncate method descriptor

truncate(policy: Any) -> None

Deduplicate and remove terms according to policy.

from_xx_plus_yy classmethod

from_xx_plus_yy(instr: Instruction, q_indices: list[int], n_modes: int) -> MajoranaTermSum[MajoranaMonomial]

Construct from an XX+YY gate between qubits q_indices[0] and q_indices[1].

Parameters:

Name	Type	Description	Default
instr	Instruction	The instruction representing the gate.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of Majorana modes in the system.	required

Returns:

Type	Description
MajoranaTermSum[MajoranaMonomial]	The corresponding MajoranaTermSum.

from_phase classmethod

from_phase(instr: Instruction, q_indices: list[int], n_modes: int) -> MajoranaTermSum[MajoranaMonomial]

Construct from a phase gate on qubit q_indices[0].

Parameters:

Name	Type	Description	Default
instr	Instruction	The instruction representing the gate.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of Majorana modes in the system.	required

Returns:

Type	Description
MajoranaTermSum[MajoranaMonomial]	The corresponding MajoranaTermSum.

from_rz_angle classmethod

from_rz_angle(q: int, angle: float, n_modes: int) -> MajoranaTermSum[MajoranaMonomial]

Construct from a raw Rz rotation angle.

Parameters:

Name	Type	Description	Default
q	int	The index of the qubit the gate acts on.	required
angle	float	The rotation angle in radians.	required
n_modes	int	The total number of Majorana modes in the system.	required

Returns:

Type	Description
MajoranaTermSum[MajoranaMonomial]	The corresponding MajoranaTermSum.

from_rz classmethod

from_rz(instr: Instruction, q_indices: list[int], n_modes: int) -> MajoranaTermSum[MajoranaMonomial]

Construct from an RZ gate.

Parameters:

Name	Type	Description	Default
instr	Instruction	The instruction representing the gate.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of Majorana modes in the system.	required

Returns:

Type	Description
MajoranaTermSum[MajoranaMonomial]	The corresponding MajoranaTermSum.

from_cp classmethod

from_cp(instr: Instruction, q_indices: list[int], n_modes: int) -> MajoranaTermSum[MajoranaMonomial]

Construct from a controlled-phase gate between q_indices[0] and q_indices[1].

Parameters:

Name	Type	Description	Default
instr	Instruction	The instruction representing the gate.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of Majorana modes in the system.	required

Returns:

Type	Description
MajoranaTermSum[MajoranaMonomial]	The corresponding MajoranaTermSum.

from_swap classmethod

from_swap(instr: Instruction | None, q_indices: list[int], n_modes: int) -> MajoranaTermSum[MajoranaMonomial]

Construct from a SWAP gate between q_indices[0] and q_indices[1].

Parameters:

Name	Type	Description	Default
instr	Instruction | None	The instruction representing the gate, if any (unused; SWAP carries no gate parameters). None when called from a non-Qiskit frontend, e.g. propaq.circuits._cirq_gates.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of Majorana modes in the system.	required

Returns:

Type	Description
MajoranaTermSum[MajoranaMonomial]	The corresponding MajoranaTermSum.

from_x classmethod

from_x(instr: Instruction, q_indices: list[int], n_modes: int) -> MajoranaTermSum[MajoranaMonomial]

Construct from an X gate on qubit q_indices[0].

Parameters:

Name	Type	Description	Default
instr	Instruction	The instruction representing the gate.	required
q_indices	list[int]	The indices of the qubits the gate acts on.	required
n_modes	int	The total number of Majorana modes in the system.	required

Returns:

Type	Description
MajoranaTermSum[MajoranaMonomial]	The corresponding MajoranaTermSum.

from_sparse_pauli_op classmethod

from_sparse_pauli_op(op: SparsePauliOp) -> MajoranaTermSum[MajoranaMonomial]

Construct from a SparsePauliOp via the Jordan-Wigner inverse transform.

Parameters:

Name	Type	Description	Default
op	SparsePauliOp	The SparsePauliOp to convert.	required

Returns:

Type	Description
MajoranaTermSum[MajoranaMonomial]	The corresponding MajoranaTermSum.

from_openfermion classmethod

from_openfermion(op: Any, n_modes: int) -> MajoranaTermSum[MajoranaMonomial]

Construct from an OpenFermion FermionOperator.

Requires the optional openfermion extra: pip install propaq[openfermion].

Parameters:

Name	Type	Description	Default
op	Any	The OpenFermion FermionOperator to convert. Must be Hermitian.	required
n_modes	int	The total number of Majorana modes in the system.	required

Returns:

Type	Description
MajoranaTermSum[MajoranaMonomial]	The corresponding MajoranaTermSum.

from_ffsim classmethod

from_ffsim(obj: Any, n_modes: int | None = None) -> MajoranaTermSum[MajoranaMonomial]

Construct from an ffsim object supporting the SupportsFermionOperator protocol (e.g. MolecularHamiltonian, MolecularHamiltonianSpinless, DiagonalCoulombHamiltonian, DoubleFactorizedHamiltonian).

Requires the optional ffsim extra: pip install propaq[ffsim].

Parameters:

Name	Type	Description	Default
obj	Any	The ffsim object to convert. Must be Hermitian.	required
n_modes	int | None	The total number of Majorana modes in the system. Defaults to 4 * obj.norb if obj exposes a norb attribute (2 spin sectors times 2 Majorana modes per spin orbital).	None

Returns:

Type	Description
MajoranaTermSum[MajoranaMonomial]	The corresponding MajoranaTermSum.

to_sparse_pauli_op

to_sparse_pauli_op() -> SparsePauliOp

Convert this MajoranaTermSum back to a Qiskit SparsePauliOp via the inverse Jordan-Wigner transform.

Raises:

Type	Description
ValueError	If the term sum is empty (n_qubits cannot be inferred).

Returns:

Type	Description
SparsePauliOp	The equivalent SparsePauliOp with simplified (deduplicated) terms.

PauliTermStreamer

Methods:

Name	Description
from_file	Open a gzip-compressed binary file for lazy streaming.

from_file staticmethod

from_file(path: str) -> PauliTermStreamer

Open a gzip-compressed binary file for lazy streaming.

Parameters:

Name	Type	Description	Default
path	str	Path to a file written by PauliTermSum.save().	required

MajoranaTermStreamer

Methods:

Name	Description
from_file	Open a gzip-compressed binary file for lazy streaming.

from_file staticmethod

from_file(path: str) -> MajoranaTermStreamer

Open a gzip-compressed binary file for lazy streaming.

Parameters:

Name	Type	Description	Default
path	str	Path to a file written by MajoranaTermSum.save().	required

AbstractTerm dataclass

AbstractTerm()

Bases: ABC

Abstract monomial datatype. Concrete examples: PauliString, MajoranaMonomial.

Methods:

Name	Description
commutes_with	Returns True if the term commutes with other, False otherwise.
to_bytes	Serializes the term to bytes.
trace_with_diag_state	Diagonal expectation \(\langle f | T | f \rangle\) against a computational basis state.
dagger	The Hermitian conjugate, as a (phase, term) pair.
from_bytes	Rebuild a term from to_bytes output, the inverse of to_bytes.

Attributes:

Name	Type	Description
weight	int	Number of non-identity single-site operators in the term.
n_units	int	Number of qubits, modes, qudits, or other single-site units this term is defined on.
words	list[int]	This term's key as little-endian 64-bit words.

weight abstractmethod property

weight: int

Number of non-identity single-site operators in the term.

n_units abstractmethod property

n_units: int

Number of qubits, modes, qudits, or other single-site units this term is defined on.

words property

words: list[int]

This term's key as little-endian 64-bit words.

This is what a key-aware noise model (damping_factor_term) reads as words. The default packs to_bytes into 64-bit little-endian words, zero-padding the final word. Override it if your basis has a more natural word layout.

commutes_with abstractmethod

commutes_with(other: _T) -> bool

Returns True if the term commutes with other, False otherwise.

to_bytes abstractmethod

to_bytes() -> bytes

Serializes the term to bytes.

trace_with_diag_state abstractmethod

trace_with_diag_state(diag_state: DiagState) -> complex

Diagonal expectation \(\langle f | T | f \rangle\) against a computational basis state.

Parameters:

Name	Type	Description	Default
diag_state	DiagState	The reference state. Both PauliString and MajoranaMonomial accept an integer bitmask.	required

dagger

dagger() -> tuple[complex, _T]

The Hermitian conjugate, as a (phase, term) pair.

Defaults to Hermitian, i.e. (1, self). Override this for a basis whose elements are not self-adjoint (a qudit Weyl string, for example).

from_bytes classmethod

from_bytes(data: bytes, n_units: int) -> _T

Rebuild a term from to_bytes output, the inverse of to_bytes.

Only needed for AbstractPropagator's filename= term I/O.

Parameters:

Name	Type	Description	Default
data	bytes	The bytes produced by to_bytes.	required
n_units	int	The number of units (qubits, modes, qudits, ...) the term is defined on.	required

Raises:

Type	Description
NotImplementedError	Unless a subclass overrides it.

AbstractTermSum

Bases: ABC, Generic[TermT]

Abstract container for a linear combination of monomials with complex coefficients.

Concrete examples: MajoranaTermSum, PauliTermSum.

Methods:

Name	Description
add	Add coeff * term to the sum.
scale	Multiply every coefficient by factor in-place.
merge	Add all terms from other into this sum.
truncate	Remove terms according to policy.
items	Return a list of (monomial, coefficient) pairs.

add abstractmethod

add(term: TermT, coeff: complex) -> None

Add coeff * term to the sum.

scale abstractmethod

scale(factor: complex) -> None

Multiply every coefficient by factor in-place.

merge abstractmethod

merge(other: AbstractTermSum[TermT]) -> None

Add all terms from other into this sum.

truncate abstractmethod

truncate(policy: object | Sequence[object] | TruncationPolicy | None) -> None

Remove terms according to policy.

items abstractmethod

items() -> list[tuple[TermT, complex]]

Return a list of (monomial, coefficient) pairs.

DictTermSum

DictTermSum(terms: Mapping[TermT, complex] | None = None)

Bases: AbstractTermSum[TermT]

A dict-backed sum of basis terms with complex coefficients.

This satisfies the AbstractTermSum interface, so a new operator basis only needs to define its AbstractTerm subclass to get a working term sum. Subclassing and setting a term_type class attribute enables term loading from disk.

class WeylTermSum(DictTermSum[WeylString]):
    term_type = WeylString

Parameters:

Name	Type	Description	Default
terms	Mapping[TermT, complex] | None	Optional initial mapping of term to coefficient.	None

Construct a term sum from an optional initial mapping.

Methods:

Name	Description
add	Add coeff * term to the sum, accumulating if already present.
scale	Multiply every coefficient by factor in-place.
merge	Add all terms from other into this sum.
truncate	Remove terms according to policy, in-place.
items	Return all (term, coefficient) pairs.
copy	Return a shallow copy of this term sum.
norm_squared	Return the sum of |coefficient|^2 over all terms.
save	Save this term sum to a gzip-compressed binary file.
from_file	Load a term sum from a gzip-compressed binary file.
hermitian	The Hermitian observable \(\tfrac{1}{2}(c B + \bar{c} B^\dagger)\) built from one term.

Attributes:

Name	Type	Description
term_type	type[AbstractTerm] | None	The AbstractTerm subclass from_file rebuilds keys as, if set by a subclass.

term_type class-attribute

term_type: type[AbstractTerm] | None = None

The AbstractTerm subclass from_file rebuilds keys as, if set by a subclass.

add

add(term: TermT, coeff: complex) -> None

Add coeff * term to the sum, accumulating if already present.

scale

scale(factor: complex) -> None

Multiply every coefficient by factor in-place.

merge

merge(other: AbstractTermSum[TermT]) -> None

Add all terms from other into this sum.

truncate

truncate(policy: object | Sequence[object] | TruncationPolicy | None) -> None

Remove terms according to policy, in-place.

Parameters:

Name	Type	Description	Default
policy	object | Sequence[object] | TruncationPolicy | None	A truncator, a sequence of truncators, a TruncationPolicy, or None. See resolve_truncation for the accepted forms.	required

items

items() -> list[tuple[TermT, complex]]

Return all (term, coefficient) pairs.

copy

copy() -> DictTermSum[TermT]

Return a shallow copy of this term sum.

norm_squared

norm_squared() -> float

Return the sum of |coefficient|^2 over all terms.

save

save(path: str) -> None

Save this term sum to a gzip-compressed binary file.

Every coefficient has to be real. TODO: Generalize to complex coefficients.

Parameters:

Name	Type	Description	Default
path	str	Destination file path.	required

Raises:

Type	Description
ValueError	If a coefficient is complex, or terms serialize to differing byte lengths.

from_file classmethod

from_file(path: str, term_type: type[TermT] | None = None) -> DictTermSum[TermT]

Load a term sum from a gzip-compressed binary file.

Parameters:

Name	Type	Description	Default
path	str	Path to the file written by save, or by a propagator's filename parameter.	required
term_type	type[TermT] | None	The AbstractTerm subclass to rebuild keys as. Falls back to term_type if a subclass sets it.	None

Raises:

Type	Description
TypeError	If neither term_type nor the class attribute is set.

hermitian classmethod

hermitian(term: TermT, coeff: complex = 1.0) -> DictTermSum[TermT]

The Hermitian observable \(\tfrac{1}{2}(c B + \bar{c} B^\dagger)\) built from one term.

Parameters:

Name	Type	Description	Default
term	TermT	The basis term \(B\).	required
coeff	complex	The coefficient \(c\).	1.0