Python API¶
fast_pauli is a Python package with C++ backend, optimized for operations on Pauli Matrices and Pauli Strings.
Pauli¶
- class fast_pauli.Pauli(*args, **kwargs)¶
A class for efficient representation of a \(2 \times 2\) Pauli Matrix \(\sigma_i \in \{ I, X, Y, Z \}\)
- __init__¶
Overloaded function.
__init__(self) -> None
Default constructor to initialize with identity matrix.
__init__(self, code: int) -> None
Constructor given a numeric code.
- Parameters:
code (int) – Numerical label of type int for corresponding Pauli matrix \(0: I, 1: X, 2: Y, 3: Z\)
__init__(self, symbol: str) -> None
Constructor given Pauli matrix symbol.
- Parameters:
symbol (str) – Character label of type str corresponding to one of the Pauli Matrix symbols \(I, X, Y, Z\)
- __matmul__¶
Returns matrix product of two Paulis as a tuple of phase and new Pauli object.
- __new__(**kwargs)¶
- __str__¶
Returns a string representation of Pauli matrix.
- Returns:
One of \(I, X, Y, Z\), a single character string representing a Pauli Matrix
- Return type:
str
- to_tensor¶
Returns a dense representation of Pauli object as a \(2 \times 2\) matrix.
- Returns:
2D numpy array of complex numbers
- Return type:
np.ndarray
PauliString¶
- class fast_pauli.PauliString(*args, **kwargs)¶
A class representation of a Pauli String \(\mathcal{\hat{P}}\) (i.e. a tensor product of Pauli matrices)
\[ \begin{align}\begin{aligned}\mathcal{\hat{P}} = \bigotimes_i \sigma_i\\\sigma_i \in \{ I,X,Y,Z \}\end{aligned}\end{align} \]- __add__¶
Returns the sum of two Pauli strings in a form of PauliOp object.
- Parameters:
rhs (PauliString) – The other PauliString object to add
- Returns:
A linear combination of the PauliString objects as a PauliOp.
- Return type:
- __init__¶
Overloaded function.
__init__(self) -> None
Default constructor to initialize with empty string.
__init__(self, string: str) -> None
Constructs a PauliString from a string and calculates the weight. This is often the most compact way to initialize a PauliString.
- Parameters:
string (str) – Pauli String representation. Each character should be one of \(I, X, Y, Z\)
__init__(self, paulis: collections.abc.Sequence[fast_pauli._fast_pauli.Pauli]) -> None
Constructs a PauliString from a list of Pauli objects and calculates the weight.
- Parameters:
paulis (list[Pauli]) – List of ordered Pauli objects
- __matmul__¶
Returns matrix product of two pauli strings and their phase as a pair.
- Parameters:
rhs (PauliString) – Right hand side PauliString object
- Returns:
Phase and resulting PauliString object
- Return type:
tuple[complex, PauliString]
- __new__(**kwargs)¶
- __str__¶
Returns a string representation of PauliString object.
- Returns:
string representation of PauliString object
- Return type:
str
- __sub__¶
Returns the difference of two Pauli strings in a form of PauliOp object.
- Parameters:
rhs (PauliString) – The other PauliString object to subtract
- Returns:
A linear combination of the PauliString objects as a PauliOp.
- Return type:
- apply¶
Apply a Pauli string to a single dimensional state vector or a batch of states.
\[c \mathcal{\hat{P}} \ket{\psi_t}\]Note
For batch mode it applies the PauliString to each individual state separately. In this case, the input array is expected to have the shape of (n_dims, n_states) with states stored as columns.
- Parameters:
states (np.ndarray) – The original state(s) represented as 1D (n_dims,) or 2D numpy array (n_dims, n_states) for batched calculation. Outer dimension must match the dimensionality of Pauli string.
coeff (complex) – Scalar multiplication factor (\(c\)) to scale the PauliString before applying to states
- Returns:
New state(s) in a form of 1D (n_dims,) or 2D numpy array (n_dims, n_states) according to the shape of input states
- Return type:
np.ndarray
- property dim¶
The dimension of PauliString \(2^n, n\) - number of qubits
- Type:
int
- expectation_value¶
Calculate expectation value(s) for a given single dimensional state vector or a batch of states.
\[\bra{\psi_t} \mathcal{\hat{P}} \ket{\psi_t}\]Note
For batch mode it computes the expectation value for each individual state separately. In this case, the input array is expected to have the shape of (n_dims, n_states) with states stored as columns.
- Parameters:
states (np.ndarray) – The original state(s) represented as 1D (n_dims,) or 2D numpy array (n_dims, n_states) for batched calculation. Outer dimension must match the dimensionality of Pauli string.
coeff (complex) – Multiplication factor to scale the PauliString before calculating the expectation value
- Returns:
Expectation value(s) in the form of a 1D numpy array with a shape of (n_states,)
- Return type:
np.ndarray
- property n_qubits¶
The number of qubits in PauliString (i.e. number of Pauli Matrices in tensor product)
- Type:
int
- to_tensor¶
Returns a dense representation of PauliString.
- Returns:
2D numpy array of complex numbers
- Return type:
np.ndarray
- property weight¶
The weight of PauliString (i.e. number of non-identity Pauli matrices in it)
- Type:
int
PauliOp¶
- class fast_pauli.PauliOp(*args, **kwargs)¶
A class representation for a Pauli Operator \(A\) (i.e. a weighted sum of Pauli Strings)
\[ \begin{align}\begin{aligned}A = \sum_j h_j \mathcal{\hat{P}}_j\\\mathcal{\hat{P}} = \bigotimes_i \sigma_i \quad h_j \in \mathbb{C}\end{aligned}\end{align} \]- __add__¶
Overloaded function.
__add__(self, arg: fast_pauli._fast_pauli.PauliOp, /) -> fast_pauli._fast_pauli.PauliOp
Returns the sum of two Pauli Operators.
- Parameters:
rhs (PauliOp) – The other PauliOp object to add
- Returns:
New PauliOp instance holding the sum.
- Return type:
__add__(self, arg: fast_pauli._fast_pauli.PauliString, /) -> fast_pauli._fast_pauli.PauliOp
Returns the sum of Pauli Operator with Pauli String.
- Parameters:
rhs (PauliString) – Right hand side PauliString object to add
- Returns:
New PauliOp instance holding the sum.
- Return type:
- __iadd__¶
Overloaded function.
__iadd__(self, arg: fast_pauli._fast_pauli.PauliOp, /) -> fast_pauli._fast_pauli.PauliOp
Performs inplace addition with other Pauli Operator.
- Parameters:
other (PauliOp) – Pauli operator object to add
- Returns:
Current PauliOp instance after addition
- Return type:
__iadd__(self, arg: fast_pauli._fast_pauli.PauliString, /) -> fast_pauli._fast_pauli.PauliOp
Performs inplace addition with Pauli String.
- Parameters:
other (PauliString) – Pauli string object to add
- Returns:
Current PauliOp instance after addition
- Return type:
- __imul__¶
Scale Pauli Operator inplace by a scalar value.
- Parameters:
other (complex or float) – Scalar multiplier
- Returns:
Current PauliOp instance after scaling
- Return type:
- __init__¶
Overloaded function.
__init__(self) -> None
Default constructor to initialize strings and coefficients with empty arrays.
__init__(self, pauli_strings: collections.abc.Sequence[str]) -> None
Construct a PauliOp from a list of strings and default corresponding coefficients to ones.
- Parameters:
pauli_strings (List[str]) – List of Pauli Strings as simple str. Each string should be composed of characters \(I, X, Y, Z\) and should have the same size
__init__(self, arg: collections.abc.Sequence[fast_pauli._fast_pauli.PauliString], /) -> None
Construct a PauliOp from a list of PauliString objects and default corresponding coefficients to ones.
- Parameters:
pauli_strings (List[PauliString]) – List of PauliString objects.
__init__(self, coefficients: ndarray[dtype=complex128], pauli_strings: collections.abc.Sequence[fast_pauli._fast_pauli.PauliString]) -> None
Construct a PauliOp from a list of PauliString objects and corresponding coefficients.
- Parameters:
coefficients (np.ndarray) – Array of coefficients corresponding to Pauli strings.
pauli_strings (List[PauliString]) – List of PauliString objects.
__init__(self, coefficients: collections.abc.Sequence[complex], pauli_strings: collections.abc.Sequence[fast_pauli._fast_pauli.PauliString]) -> None
Construct a PauliOp from a list of PauliString objects and corresponding coefficients.
- Parameters:
coefficients (List[complex]) – List of coefficients corresponding to Pauli strings.
pauli_strings (List[PauliString]) – List of PauliString objects.
__init__(self, coefficients: collections.abc.Sequence[complex], pauli_strings: collections.abc.Sequence[str]) -> None
Construct a PauliOp from a list of strings and corresponding coefficients.
- Parameters:
coefficients (np.ndarray) – Array of coefficients corresponding to Pauli strings.
pauli_strings (List[str]) – List of Pauli Strings as simple str. Each string should be composed of characters \(I, X, Y, Z\) and should have the same size
- __isub__¶
Overloaded function.
__isub__(self, arg: fast_pauli._fast_pauli.PauliOp, /) -> fast_pauli._fast_pauli.PauliOp
Performs inplace subtraction with other Pauli Operator.
- Parameters:
other (PauliOp) – Pauli operator object to subtract
- Returns:
Current PauliOp instance after subtraction
- Return type:
__isub__(self, arg: fast_pauli._fast_pauli.PauliString, /) -> fast_pauli._fast_pauli.PauliOp
Performs inplace subtraction with Pauli String.
- Parameters:
other (PauliString) – Pauli string object to subtract
- Returns:
Current PauliOp instance after subtraction
- Return type:
- __matmul__¶
Overloaded function.
__matmul__(self, arg: fast_pauli._fast_pauli.PauliOp, /) -> fast_pauli._fast_pauli.PauliOp
Efficient matrix multiplication of two Pauli Operators, leveraging their sparse structure.
- Parameters:
rhs (PauliOp) – Right hand side PauliOp object
- Returns:
New PauliOp instance containing the product
- Return type:
__matmul__(self, arg: fast_pauli._fast_pauli.PauliString, /) -> fast_pauli._fast_pauli.PauliOp
Efficient matrix multiplication of PauliOp with a PauliString on the right, leveraging their sparse structure.
- Parameters:
rhs (PauliString) – Right hand side PauliString object
- Returns:
New PauliOp instance containing the product
- Return type:
- __mul__¶
Scale Pauli Operator by a scalar value.
- Parameters:
rhs (complex or float) – Right hand side scalar multiplier
- Returns:
New PauliOp instance containing the product
- Return type:
- __new__(**kwargs)¶
- __radd__¶
Returns the sum of Pauli Operators with Pauli String.
- Parameters:
lhs (PauliString) – Left hand side PauliString object to add
- Returns:
New PauliOp instance holding the sum.
- Return type:
- __rmatmul__¶
Efficient matrix multiplication of PauliOp with a PauliString on the left, leveraging their sparse structure.
- __rmul__¶
Scale Pauli Operator by a scalar value.
- Parameters:
lhs (complex or float) – Left hand side scalar multiplier
- Returns:
New PauliOp instance containing the product
- Return type:
- __rsub__¶
Returns the difference of Pauli Operators with Pauli String.
- Parameters:
lhs (PauliString) – Left hand side PauliString object to subtract
- Returns:
New PauliOp instance holding the difference.
- Return type:
- __sub__¶
Overloaded function.
__sub__(self, arg: fast_pauli._fast_pauli.PauliOp, /) -> fast_pauli._fast_pauli.PauliOp
Returns the difference of two Pauli Operators.
- Parameters:
rhs (PauliOp) – The other PauliOp object to subtract
- Returns:
New PauliOp instance holding the difference.
- Return type:
__sub__(self, arg: fast_pauli._fast_pauli.PauliString, /) -> fast_pauli._fast_pauli.PauliOp
Returns the difference of Pauli Operator with Pauli String.
- Parameters:
rhs (PauliString) – Right hand side PauliString object to subtract
- Returns:
New PauliOp instance holding the difference.
- Return type:
- apply¶
Apply a Pauli Operator to a single dimensional state vector or a batch of states.
\[\big( \sum_j h_j \mathcal{\hat{P}}_j \big) \ket{\psi_t}\]Note
For batch mode it applies the PauliOp to each individual state separately. In this case, the input array is expected to have the shape of (n_dims, n_states) with states stored as columns.
- Parameters:
states (np.ndarray) – The original state(s) represented as 1D (n_dims,) or 2D numpy array (n_dims, n_states) for batched calculation. Outer dimension must match the dimensionality of Pauli Operator.
- Returns:
New state(s) in a form of 1D (n_dims,) or 2D numpy array (n_dims, n_states) according to the shape of input states
- Return type:
np.ndarray
- property coeffs¶
Ordered list of coefficients corresponding to Pauli strings
- Type:
List[complex]
- property dim¶
The dimension of PauliStrings used to compose PauliOp \(2^n, n\) - number of qubits
- Type:
int
- expectation_value¶
Calculate expectation value(s) for a given single dimensional state vector or a batch of states.
\[\bra{\psi_t} \big( \sum_j h_j \mathcal{\hat{P}}_j \big) \ket{\psi_t}\]Note
For batch mode it computes the expectation value for each individual state separately. In this case, the input array is expected to have the shape of (n_dims, n_states) with states stored as columns.
- Parameters:
states (np.ndarray) – The original state(s) represented as 1D (n_dims,) or 2D numpy array (n_dims, n_states) for batched calculation. Outer dimension must match the dimensionality of Pauli Operator.
- Returns:
Expectation value(s) in the form of a 1D numpy array with a shape of (n_states,)
- Return type:
np.ndarray
- extend¶
Overloaded function.
extend(self, other: fast_pauli._fast_pauli.PauliOp) -> None
Add another PauliOp to the current one by extending the internal summation with new terms.
- Parameters:
other (PauliOp) – PauliOp object to extend the current one with
extend(self, other: fast_pauli._fast_pauli.PauliString, multiplier: complex, dedupe: bool = True) -> None
Add a Pauli String term with a corresponding coefficient to the summation inside PauliOp.
- Parameters:
other (PauliString) – PauliString object to add to the summation
multiplier (complex) – Coefficient to apply to the PauliString
dedupe (bool) – Whether to deduplicate the set of PauliStrings
- property n_pauli_strings¶
The number of PauliString terms in PauliOp
- Type:
int
- property n_qubits¶
The number of qubits in PauliOp
- Type:
int
- property pauli_strings¶
Ordered list of PauliString objects in PauliOp
- Type:
List[PauliString]
- property pauli_strings_as_str¶
Ordered list of Pauli Strings representations from PauliOp
- Type:
List[str]
- scale¶
Overloaded function.
scale(self, factor: complex) -> None
Scale each individual term of Pauli Operator by a scalar value.
- Parameters:
factor (complex or float) – Scalar multiplier
scale(self, factors: ndarray[dtype=complex128]) -> None
Scale each individual term of Pauli Operator by a scalar value.
- Parameters:
factors (np.ndarray) – Array of factors to scale each term with. The length of the array should match the number of Pauli strings in PauliOp
- to_tensor¶
Returns a dense representation of PauliOp.
- Returns:
2D numpy array of complex numbers with a shape of \(2^n \times 2^n, n\) - number of qubits
- Return type:
np.ndarray