From e40660e31019ac0e487429d61105eddb0352b072 Mon Sep 17 00:00:00 2001 From: alexanderlerner Date: Mon, 7 Oct 2024 17:38:56 -0400 Subject: [PATCH 1/9] flesh out getting started guide --- docs/getting_started.rst | 83 +++++++++++++++++++++++++++++++--------- 1 file changed, 65 insertions(+), 18 deletions(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index fa9a7b0..6c0c83b 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -4,16 +4,34 @@ Getting Started ===================== Welcome to Fast-Pauli from `Qognitive `_, an open-source Python / C++ library for optimized operations on Pauli matrices and Pauli strings -based on `PauliComposer `_. In this guide, -we'll introduce some of the important operations to help users get started. For more details, -see the API documentation. +based on `PauliComposer `_. +In this guide, we'll introduce some of the important operations to help users get started as well as some conceptual background on Pauli matrices and Pauli strings. + +For more details, see the :doc:`python_api` or :doc:`cpp_api` documentation. For tips on installing the library, check out the guide: :doc:`index`. Pauli Matrices ------------------------ -For a conceptual overview of Pauli matrices, see `here `_. +For a more in-depth overview of Pauli matrices, see `here `_. + +In math and physics, a `Pauli matrix `_, named after the physicist Wolfgang Pauli, is any one of the special 2 x 2 complex matrices in the set (often denoted by the greek letter :math:`\sigma`) : + +.. math:: + + \sigma_0 = \begin{bmatrix} 1 & 0 \\ 0 & 1 \end{bmatrix} + \sigma_x = \begin{bmatrix} 0 & 1 \\ 1 & 0 \end{bmatrix} + \sigma_y = \begin{bmatrix} 0 & -i \\ i & 0 \end{bmatrix} + \sigma_z = \begin{bmatrix} 1 & 0 \\ 0 & -1 \end{bmatrix} + +All the pauli matrices share the properties that they are: + +1. Hermitian (equal to their own conjugate transpose) :math:`\sigma_i = \sigma_i^\dagger` for all :math:`i \in \{x, y, z\}` +2. Involutory (they are their own inverse) :math:`\sigma_i^2 = \sigma_0` for all :math:`i \in \{x, y, z\}` +3. Unitary (their inverse is equal to their conjugate transpose) :math:`\sigma_i^{-1} = \sigma_i^\dagger` for all :math:`i \in \{x, y, z\}` + +with the identity matrix :math:`\sigma_0` or the :math:`2 \times 2` Identity matrix :math:`I` being the trivial case. In ``fast_pauli``, we represent pauli matrices using the ``Pauli`` class. For example, to represent the Pauli matrices, we can do: @@ -26,13 +44,23 @@ In ``fast_pauli``, we represent pauli matrices using the ``Pauli`` class. For ex pauli_y = fp.Pauli('Y') pauli_z = fp.Pauli('Z') + str(pauli_0) # returns "I" + We can also multiply two ``Pauli`` objects together to get a ``Pauli`` object representing the tensor product of the two pauli matrices. +The result includes a phase factor because Pauli matrices do not necessarily commute. They exhibit the following `commutation relations `_: + +.. math:: + + \sigma_x \sigma_y = i \sigma_z \\ + \sigma_y \sigma_z = i \sigma_x \\ + \sigma_z \sigma_x = i \sigma_y + +For example, we can compute the resulting ``Pauli`` object from multiplying :math:`\sigma_x` and :math:`\sigma_y` as follows: .. code-block:: python + # phase = i, new_pauli = fp.Pauli('Z') phase, new_pauli = pauli_x @ pauli_y - # returns "I" - str(pauli_0) From here, we can also convert our ``Pauli`` object back to a dense numpy array if we'd like: @@ -43,6 +71,21 @@ From here, we can also convert our ``Pauli`` object back to a dense numpy array Pauli Strings ------------------------ +Pauli strings, also known as Pauli words, are tensor-product combinations of Pauli matrices. For example, the following is a valid Pauli string: + +.. math:: + + \mathcal{\hat{P}} = \sigma_x \otimes \sigma_y \otimes \sigma_z + +where :math:`\otimes` denotes the tensor product, and we can more simply denote by + +.. math:: + + \mathcal{\hat{P}} = XYZ + +Other valid Pauli strings include ``III``, ``IXYZ``, ``IZYX``, etc. In general, a Pauli string of length ``N`` is a tensor product of ``N`` +Pauli matrices. A ``N``-length Pauli String in dense form is a :math:`2^N \times 2^N` matrix, so ``XYZ`` is a :math:`8 \times 8` matrix. + In ``fast_pauli``, we represent Pauli strings using the ``PauliString`` class. For example, to construct the Pauli string ``X, Y, Z``, we can do: .. code-block:: python @@ -61,16 +104,12 @@ Pauli Strings also support operations like addition, multiplication, and more. F P1.dim P1.n_qubits - # Add two Pauli strings. Return type is a PauliOp because - # the product is not a Pauli string - P3 = P1 + P2 - # Multiply two Pauli strings. phase, new_string = P1 @ P2 -We can also do more complicated things, like compute the action of a Pauli string :math:`\mathcal{\hat{P}}` on a quantum state :math:`| \psi \rangle`, :math:`\mathcal{\hat{P}}| \psi \rangle`, or -compute the expectation value of a Pauli string with a state :math:`\langle \psi | \mathcal{\hat{P}} | \psi \rangle`: +We can also do more complicated things, like compute the action of a Pauli string :math:`\mathcal{\hat{P}}` on a vector :math:`| \psi \rangle`, :math:`\mathcal{\hat{P}}| \psi \rangle`, or +compute the expectation value of a Pauli string with a state :math:`\langle \psi | \mathcal{\hat{P}} | \psi \rangle`. As a side note, in this guide we will use state and vector interchangeably: .. code-block:: python @@ -94,13 +133,14 @@ We can also convert ``PauliString`` objects back to dense numpy arrays if we'd l # Returns "XYZ" P_str = str(P) -For more details on the ``PauliString`` class, see the Python or C++ API documentation. +For more details on the ``PauliString`` class, see the :doc:`python_api` or :doc:`cpp_api` documentation. Pauli Operators ------------------------ -The ``PauliOp`` class lets us represent operators that are linear combinations of Pauli strings with complex coefficients. More specifically, -we can represent an arbitrary operator :math:`A` as a sum of Pauli strings :math:`P_i` with complex coefficients :math:`c_i`: +The ``PauliOp`` class lets us represent operators that are linear combinations of Pauli strings with complex coefficients. +In physics, an operator is represented by a matrix in a given basis. +For example, in the Pauli basis, we can represent an arbitrary operator :math:`A` as a sum of Pauli strings :math:`P_i` with complex coefficients :math:`c_i`: .. math:: @@ -122,7 +162,7 @@ that represents the operator :math:`A = 0.5 * XYZ + 0.5 * YYZ`, we can do: A.dim A.n_pauli_strings -Just like with ``PauliString`` objects, we can apply ``PauliOp`` objects to a set of quantum states or compute expectation values, as well as arithmetic +Just like with ``PauliString`` objects, we can apply ``PauliOp`` objects to a set of vectors, or compute expectation values, as well as arithmetic operations and dense matrix conversions. Just like with ``PauliString`` objects, we can also convert ``PauliOp`` objects back to dense numpy arrays if we'd like or get their string representation, in this case a list of strings: @@ -132,6 +172,13 @@ or get their string representation, in this case a list of strings: pauli_strings = ['XYZ', 'YYZ'] A = fp.PauliOp(coeffs, pauli_strings) + # Adding two Pauli strings returns a PauliOp. + # The returned object is a PauliOp because + # the sum is a linear combination of Pauli strings + P1 = fp.PauliString('XYZ') + P2 = fp.PauliString('YZX') + O = P1 + P2 + # PauliOp supports addition, subtraction, multiplication, # scaling, as well as have PauliString objects # as the second operand. All valid operations: @@ -141,7 +188,7 @@ or get their string representation, in this case a list of strings: s = fp.PauliString('XYZ') A4 = A1 + s - # Apply A to a state or set of states + # Apply A to a state / vector or set of states states = np.random.rand(10, 8) + 1j * np.random.rand(10, 8) new_states = A.apply(states) @@ -170,5 +217,5 @@ between ``PauliOp`` objects and ``SparsePauliOp`` objects from Qiskit: P = fp.PauliString('XYZ') qiskit_pauli = fp.to_qiskit(P) -For more details on Qiskit conversions, see the Python or C++ API documentation. +For more details on Qiskit conversions, see the :doc:`python_api` or :doc:`cpp_api` documentation. From 0c7deee582cd8dfddecf7bec7b6850fe782311c9 Mon Sep 17 00:00:00 2001 From: alexanderlerner Date: Mon, 7 Oct 2024 19:08:14 -0400 Subject: [PATCH 2/9] updated from comments --- docs/getting_started.rst | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 6c0c83b..cdabc62 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -20,7 +20,6 @@ In math and physics, a `Pauli matrix `_: - -.. math:: - - \sigma_x \sigma_y = i \sigma_z \\ - \sigma_y \sigma_z = i \sigma_x \\ - \sigma_z \sigma_x = i \sigma_y +The result includes a phase factor because the product of two Pauli matrices is not another Pauli matrix. For example, we can compute the resulting ``Pauli`` object from multiplying :math:`\sigma_x` and :math:`\sigma_y` as follows: @@ -71,20 +64,20 @@ From here, we can also convert our ``Pauli`` object back to a dense numpy array Pauli Strings ------------------------ -Pauli strings, also known as Pauli words, are tensor-product combinations of Pauli matrices. For example, the following is a valid Pauli string: +Pauli strings are tensor-product combinations of Pauli matrices. For example, the following is a valid Pauli string: .. math:: \mathcal{\hat{P}} = \sigma_x \otimes \sigma_y \otimes \sigma_z -where :math:`\otimes` denotes the tensor product, and we can more simply denote by +where :math:`\otimes` denotes the tensor or `Kronecker `_ product, and we can more simply denote by .. math:: \mathcal{\hat{P}} = XYZ -Other valid Pauli strings include ``III``, ``IXYZ``, ``IZYX``, etc. In general, a Pauli string of length ``N`` is a tensor product of ``N`` -Pauli matrices. A ``N``-length Pauli String in dense form is a :math:`2^N \times 2^N` matrix, so ``XYZ`` is a :math:`8 \times 8` matrix. +A Pauli string of length ``N`` is a tensor product of ``N`` +Pauli matrices. A ``N``-length Pauli String is a :math:`2^N \times 2^N` matrix, so ``XYZ`` is a :math:`8 \times 8` matrix. In ``fast_pauli``, we represent Pauli strings using the ``PauliString`` class. For example, to construct the Pauli string ``X, Y, Z``, we can do: @@ -140,7 +133,7 @@ Pauli Operators The ``PauliOp`` class lets us represent operators that are linear combinations of Pauli strings with complex coefficients. In physics, an operator is represented by a matrix in a given basis. -For example, in the Pauli basis, we can represent an arbitrary operator :math:`A` as a sum of Pauli strings :math:`P_i` with complex coefficients :math:`c_i`: +For example we can represent any arbitrary operator :math:`A` as a sum of Pauli strings :math:`P_i` with complex coefficients :math:`c_i`: .. math:: @@ -151,8 +144,8 @@ that represents the operator :math:`A = 0.5 * XYZ + 0.5 * YYZ`, we can do: .. code-block:: python - coeffs = np.array([0.5, 0.5], dtype=complex) - pauli_strings = ['XYZ', 'YYZ'] + coeffs = np.array([0.5, 0.5], dtype=complex) # represent c_i in the sum above + pauli_strings = ['XYZ', 'YYZ'] # represent P_i in the sum above A = fp.PauliOp(coeffs, pauli_strings) # Get the number of qubits the operator acts on, From 10ba4165e8ea6481722e55c6d555318007a14b7b Mon Sep 17 00:00:00 2001 From: alexanderlerner Date: Mon, 7 Oct 2024 19:11:55 -0400 Subject: [PATCH 3/9] tiny typo --- docs/getting_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index cdabc62..213e8a2 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -133,7 +133,7 @@ Pauli Operators The ``PauliOp`` class lets us represent operators that are linear combinations of Pauli strings with complex coefficients. In physics, an operator is represented by a matrix in a given basis. -For example we can represent any arbitrary operator :math:`A` as a sum of Pauli strings :math:`P_i` with complex coefficients :math:`c_i`: +For example, we can represent any arbitrary operator :math:`A` as a sum of Pauli strings :math:`P_i` with complex coefficients :math:`c_i`: .. math:: From 1d58f6e801aba036af357d9565b85fc57a899a87 Mon Sep 17 00:00:00 2001 From: alexanderlerner Date: Mon, 7 Oct 2024 19:46:09 -0400 Subject: [PATCH 4/9] address comments --- docs/getting_started.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 213e8a2..08ee157 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -45,7 +45,7 @@ In ``fast_pauli``, we represent pauli matrices using the ``Pauli`` class. For ex str(pauli_0) # returns "I" -We can also multiply two ``Pauli`` objects together to get a ``Pauli`` object representing the tensor product of the two pauli matrices. +We can also multiply two ``Pauli`` objects together to get a ``Pauli`` object representing the matrix product of the two pauli matrices. The result includes a phase factor because the product of two Pauli matrices is not another Pauli matrix. For example, we can compute the resulting ``Pauli`` object from multiplying :math:`\sigma_x` and :math:`\sigma_y` as follows: @@ -123,8 +123,8 @@ We can also convert ``PauliString`` objects back to dense numpy arrays if we'd l P = fp.PauliString('XYZ') P_np = P.to_tensor() - # Returns "XYZ" - P_str = str(P) + + P_str = str(P) # Returns "XYZ" For more details on the ``PauliString`` class, see the :doc:`python_api` or :doc:`cpp_api` documentation. @@ -156,7 +156,7 @@ that represents the operator :math:`A = 0.5 * XYZ + 0.5 * YYZ`, we can do: A.n_pauli_strings Just like with ``PauliString`` objects, we can apply ``PauliOp`` objects to a set of vectors, or compute expectation values, as well as arithmetic -operations and dense matrix conversions. Just like with ``PauliString`` objects, we can also convert ``PauliOp`` objects back to dense numpy arrays if we'd like +operations. Just like with ``PauliString`` objects, we can also convert ``PauliOp`` objects back to dense numpy arrays if we'd like or get their string representation, in this case a list of strings: .. code-block:: python From ce7c24bd87c8a08c3521567907feda38f4600741 Mon Sep 17 00:00:00 2001 From: Alex Lerner <99294195+alexanderlerner@users.noreply.github.com> Date: Mon, 7 Oct 2024 19:50:02 -0400 Subject: [PATCH 5/9] Update docs/getting_started.rst Co-authored-by: James E T Smith --- docs/getting_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 08ee157..2e1fb92 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -3,7 +3,7 @@ Getting Started ===================== -Welcome to Fast-Pauli from `Qognitive `_, an open-source Python / C++ library for optimized operations on Pauli matrices and Pauli strings +Welcome to :code:`fast-pauli` from `Qognitive `_, an open-source Python / C++ library for optimized operations on Pauli matrices and Pauli strings based on `PauliComposer `_. In this guide, we'll introduce some of the important operations to help users get started as well as some conceptual background on Pauli matrices and Pauli strings. From 662242d1600da9a5aa8a58db7e2185bca7f2a6a2 Mon Sep 17 00:00:00 2001 From: Alex Lerner <99294195+alexanderlerner@users.noreply.github.com> Date: Mon, 7 Oct 2024 19:50:11 -0400 Subject: [PATCH 6/9] Update docs/getting_started.rst Co-authored-by: James E T Smith --- docs/getting_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 2e1fb92..140b90d 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -7,7 +7,7 @@ Welcome to :code:`fast-pauli` from `Qognitive `_, an based on `PauliComposer `_. In this guide, we'll introduce some of the important operations to help users get started as well as some conceptual background on Pauli matrices and Pauli strings. -For more details, see the :doc:`python_api` or :doc:`cpp_api` documentation. +For more details on our programmatic interface, see the :doc:`python_api` or :doc:`cpp_api` documentation. For tips on installing the library, check out the guide: :doc:`index`. From ec0ed0bfe8db869778b875d71c8d360b02f2fa55 Mon Sep 17 00:00:00 2001 From: Alex Lerner <99294195+alexanderlerner@users.noreply.github.com> Date: Tue, 8 Oct 2024 09:45:22 -0400 Subject: [PATCH 7/9] Apply suggestions from code review Co-authored-by: James E T Smith --- docs/getting_started.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 140b90d..6aded88 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -7,10 +7,9 @@ Welcome to :code:`fast-pauli` from `Qognitive `_, an based on `PauliComposer `_. In this guide, we'll introduce some of the important operations to help users get started as well as some conceptual background on Pauli matrices and Pauli strings. +If you want to follow along with this guide, please follow the installation instructions in :doc:`index`. For more details on our programmatic interface, see the :doc:`python_api` or :doc:`cpp_api` documentation. -For tips on installing the library, check out the guide: :doc:`index`. - Pauli Matrices ------------------------ @@ -24,7 +23,7 @@ In math and physics, a `Pauli matrix Date: Tue, 8 Oct 2024 09:46:37 -0400 Subject: [PATCH 8/9] address comments --- docs/getting_started.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 140b90d..cdf48a5 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -77,9 +77,10 @@ where :math:`\otimes` denotes the tensor or `Kronecker `_, allowing for easy interfacing with certain Qiskit objects. For example, we can convert +``fast_pauli`` also has integration with `IBM's Qiskit SDK `_, allowing for easy interfacing with certain Qiskit objects. For example, we can convert between ``PauliOp`` objects and ``SparsePauliOp`` objects from Qiskit: .. code-block:: python - # Convert a Fast-Pauli PauliOp to a Qiskit SparsePauliOp object and back + # Convert a fast_pauli PauliOp to a Qiskit SparsePauliOp object and back O = fp.PauliOp([1], ['XYZ']) qiskit_op = fp.to_qiskit(O) fast_pauli_op = fp.from_qiskit(qiskit_op) - # Convert a Fast-Pauli PauliString to a Qiskit Pauli object + # Convert a fast_pauli PauliString to a Qiskit Pauli object P = fp.PauliString('XYZ') qiskit_pauli = fp.to_qiskit(P) -For more details on Qiskit conversions, see the :doc:`python_api` or :doc:`cpp_api` documentation. +For more details on Qiskit conversions, see the :doc:`python_api` documentation. From e0745f5dd060b0c840b5831279d7307e4f110e84 Mon Sep 17 00:00:00 2001 From: alexanderlerner Date: Tue, 8 Oct 2024 10:21:19 -0400 Subject: [PATCH 9/9] wording --- docs/getting_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 9ccf35f..886d6df 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -45,7 +45,7 @@ In ``fast_pauli``, we represent pauli matrices using the ``Pauli`` class. For ex str(pauli_0) # returns "I" We can also multiply two ``Pauli`` objects together to get a ``Pauli`` object representing the matrix product of the two pauli matrices. -The result includes a phase factor because the product of two Pauli matrices is not another Pauli matrix. +The result includes a phase factor because the product of two Pauli matrices is not another Pauli matrix, but rather a Pauli matrix multiplied by either ``i`` or ``-i`` which we call a phase factor. For example, we can compute the resulting ``Pauli`` object from multiplying :math:`\sigma_x` and :math:`\sigma_y` as follows: