pyrauli 0.3.1__tar.gz → 0.4.0__tar.gz

{pyrauli-0.3.1 → pyrauli-0.4.0}/CMakeLists.txt

@@ -15,7 +15,8 @@ FetchContent_Declare(
 FetchContent_Declare(
 		propauli
 		GIT_REPOSITORY https://github.com/zefresk/propauli.git
-		GIT_TAG v2.1.0
+		#GIT_TAG v2.1.0
+		GIT_TAG symbolic
 )
 
 FetchContent_MakeAvailable(pybind11 propauli)

{pyrauli-0.3.1 → pyrauli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pyrauli
-Version: 0.3.1
+Version: 0.4.0
 Summary: A very fast and easy to use Quantum circuit simulator relying on Pauli propagation. Compatible with qiskit.
 License:                     GNU GENERAL PUBLIC LICENSE
                                 Version 3, 29 June 2007
@@ -686,11 +686,15 @@ Project-URL: Homepage, https://github.com/zefresk/pyrauli
 Requires-Python: >=3.9
 Provides-Extra: qiskit
 Requires-Dist: qiskit>=2.0.0; extra == "qiskit"
+Requires-Dist: numpy; extra == "qiskit"
+Provides-Extra: symbolic
+Requires-Dist: sympy; extra == "symbolic"
 Provides-Extra: test
 Requires-Dist: pytest>=8.0.0; extra == "test"
 Requires-Dist: pytest-cov>=5.0.0; extra == "test"
 Requires-Dist: pytest-benchmark; extra == "test"
 Requires-Dist: numpy; extra == "test"
+Requires-Dist: sympy; extra == "test"
 Description-Content-Type: text/markdown
 
 # pyrauli: High-Performance Quantum Circuit Simulation
@@ -753,7 +757,7 @@ final_observable = circuit.run(observable)
 
 # 5. Retrieve the final expectation value
 # The expectation value is calculated with respect to the initial |00...0> state
-expectation_value = final_observable.get_expectation_value()
+expectation_value = final_observable.expectation_value()
 
 print(f"Final observable: {final_observable}")
 print(f"Expectation value: {expectation_value}")

{pyrauli-0.3.1 → pyrauli-0.4.0}/README.md

@@ -58,7 +58,7 @@ final_observable = circuit.run(observable)
 
 # 5. Retrieve the final expectation value
 # The expectation value is calculated with respect to the initial |00...0> state
-expectation_value = final_observable.get_expectation_value()
+expectation_value = final_observable.expectation_value()
 
 print(f"Final observable: {final_observable}")
 print(f"Expectation value: {expectation_value}")

pyrauli-0.4.0/benchmarks/test_benchmark_qaoa.py

@@ -0,0 +1,43 @@
+import pytest
+from pyrauli import SymbolicObservable, SymbolicCircuit
+
+def rzz(qc, q1, q2, v):
+    qc.add_operation("cx", q1, q2)
+    qc.add_operation("rz", q2, v)
+    qc.add_operation("cx", q1, q2)
+
+def rx(qc, q, v):
+    qc.add_operation("h", q)
+    qc.add_operation("rz", q, v)
+    qc.add_operation("h", q)
+    
+@pytest.fixture(scope="module")
+def maxcut_qaoa_N4P1():
+    """Fixture"""
+    obs = SymbolicObservable(["ZZII", "ZIZI", "IZZI", "ZIIZ", "IZIZ", "IIZZ"])
+    qc = SymbolicCircuit(4)
+
+    for i in range(4):
+        qc.add_operation("h", i)
+
+    rzz(qc, 0, 1, "tz")
+    rzz(qc, 0, 3, "tz")
+    rzz(qc, 0, 2, "tz")
+
+    rx(qc, 0, "tx")
+
+    rzz(qc, 1, 2, "tz")
+    rzz(qc, 1, 3, "tz")
+
+    rx(qc, 1, "tx")
+    rzz(qc, 2, 3, "tz")
+
+    rx(qc, 2, "tx")
+    rx(qc, 3, "tx")
+
+    return qc, obs
+
+def test_qaoa_N4P1_run(maxcut_qaoa_N4P1, benchmark):
+    qc, obs = maxcut_qaoa_N4P1
+
+    benchmark(qc.run, obs)

{pyrauli-0.3.1 → pyrauli-0.4.0}/docs/guides/how_to_qiskit.rst

@@ -60,6 +60,20 @@ the hood.
    :end-before: # [estimator_complex]
    :dedent: 4
 
+Full PUBs support
+-----------------
+
+``pyrauli`` intends to be fully compatible with Qiskit and the provided backends and estimators should be able to be swapped with any other qiskit backend. Therefore, :py:class:`~pyrauli.PyrauliEstimator` and :py:class:`~pyrauli.PBackend` `.run` methods allows for any PUB (see `Qiskit documentation on PUBs https://qiskit.qotlabs.org/docs/guides/primitive-input-output`).
+
+Below is an example of what is possible:
+
+.. literalinclude:: /../tests/test_backend.py
+   :language: python
+   :start-after: # [qiskit_multiparameters]
+   :end-before: # [qiskit_multiparameters]
+   :dedent: 4
+
+
 Qiskit and reverse qubit ordering
 ---------------------------------
 

pyrauli-0.4.0/docs/guides/how_to_symbolic.rst

@@ -0,0 +1,99 @@
+.. _how_to_symbolic:
+
+Symbolic Simulation
+===================
+
+`pyrauli` offers a powerful symbolic simulation mode that allows you to work with parameterized quantum circuits. Instead of providing fixed numerical values for parameters like gate angles or noise strengths, you can use symbolic variables. This is particularly useful for tasks like variational algorithms, gradient calculations, and sensitivity analysis, where you need to explore a function's behavior over a range of parameter values.
+
+The Symbolic Toolkit
+--------------------
+
+The symbolic mode is built on three core classes:
+
+* :py:class:`~pyrauli.SymbolicCoefficient`: Represents a mathematical expression that can include variables, constants, and standard mathematical operations.
+* :py:class:`~pyrauli.SymbolicObservable`: An observable whose terms have `SymbolicCoefficient` objects as coefficients.
+* :py:class:`~pyrauli.SymbolicCircuit`: A circuit that can accept `SymbolicCoefficient` objects as parameters for its operations.
+
+Working with `SymbolicCoefficient`
+------------------------------------
+
+The :py:class:`~pyrauli.SymbolicCoefficient` is the fundamental building block. You can create one from a number or a string (which becomes a variable name).
+
+.. literalinclude:: /../tests/snippets/test_symbolic_coefficient_guide.py
+   :language: python
+   :start-after: # [symbolic_init]
+   :end-before: # [symbolic_init]
+   :dedent: 4
+
+These objects support standard mathematical operations, allowing you to build complex expressions.
+
+.. literalinclude:: /../tests/snippets/test_symbolic_coefficient_guide.py
+   :language: python
+   :start-after: # [symbolic_ops]
+   :end-before: # [symbolic_ops]
+   :dedent: 4
+
+Evaluating Expressions
+~~~~~~~~~~~~~~~~~~~~~~
+
+A key feature is the ability to substitute variables with values. There are two ways to do this:
+
+1.  **.evaluate()**: This method substitutes all variables and computes a final floating-point number. It will raise an error if any variables are left unbound.
+2.  **.symbolic_evaluate()**: This method substitutes only the specified variables, returning a new, potentially simpler `SymbolicCoefficient`.
+
+.. literalinclude:: /../tests/snippets/test_symbolic_coefficient_guide.py
+   :language: python
+   :start-after: # [symbolic_evaluate]
+   :end-before: # [symbolic_evaluate]
+   :dedent: 4
+
+Simplifying Expressions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The :py:meth:`~pyrauli.SymbolicCoefficient.simplified` method applies arithmetic rules (like `x*1=x` or `x+0=x`) to reduce the complexity of an expression.
+
+.. literalinclude:: /../tests/snippets/test_symbolic_coefficient_guide.py
+   :language: python
+   :start-after: # [symbolic_simplify]
+   :end-before: # [symbolic_simplify]
+   :dedent: 4
+
+Constructing a `SymbolicObservable`
+-------------------------------------
+
+A :py:class:`~pyrauli.SymbolicObservable` works just like a regular :py:class:`~pyrauli.Observable`, but its coefficients are symbolic.
+
+.. literalinclude:: /../tests/snippets/test_symbolic_observable_guide.py
+   :language: python
+   :start-after: # [symbolic_obs_init]
+   :end-before: # [symbolic_obs_init]
+   :dedent: 4
+
+The :py:meth:`~pyrauli.SymbolicObservable.simplify` method on an observable will simplify the symbolic coefficients of all its terms. You can also pass a dictionary of variable substitutions to this method.
+
+.. literalinclude:: /../tests/snippets/test_symbolic_observable_guide.py
+   :language: python
+   :start-after: # [symbolic_obs_simplify]
+   :end-before: # [symbolic_obs_simplify]
+   :dedent: 4
+
+Building and Running a `SymbolicCircuit`
+------------------------------------------
+
+The end-to-end workflow is straightforward. You build a :py:class:`~pyrauli.SymbolicCircuit` using variable names for your parameters and then run it on a :py:class:`~pyrauli.SymbolicObservable`. The simulation propagates the symbolic expressions through the circuit according to the rules of quantum mechanics.
+
+.. literalinclude:: /../tests/snippets/test_symbolic_circuit_snippet.py
+   :language: python
+   :start-after: # [symbolic_circuit]
+   :end-before: # [symbolic_circuit]
+   :dedent: 4
+
+The final result is a new :py:class:`~pyrauli.SymbolicObservable`. To get the final expectation value, you call its :py:meth:`~pyrauli.SymbolicObservable.expectation_value` method, which returns a `SymbolicCoefficient`. You can then evaluate this coefficient for any set of concrete parameter values.
+
+.. literalinclude:: /../tests/snippets/test_symbolic_circuit_snippet.py
+   :language: python
+   :start-after: # [symbolic_evaluation]
+   :end-before: # [symbolic_evaluation]
+   :dedent: 4
+
+This workflow allows you to run the simulation once to get a general symbolic result and then analyze that result for many different parameter values without needing to re-run the simulation each time.

{pyrauli-0.3.1 → pyrauli-0.4.0}/docs/index.rst

@@ -31,6 +31,7 @@ the library for the first time or need a specific technical detail.
    guides/how_to_complexity
    guides/how_to_qiskit
    guides/how_to_noise
+   guides/how_to_symbolic
 
 .. toctree::
    :maxdepth: 2

{pyrauli-0.3.1 → pyrauli-0.4.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "pyrauli"
-version = "0.3.1"
+version = "0.4.0"
 description = "A very fast and easy to use Quantum circuit simulator relying on Pauli propagation. Compatible with qiskit."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -25,13 +25,18 @@ Homepage = "https://github.com/zefresk/pyrauli"
 
 [project.optional-dependencies]
 qiskit = [
-    "qiskit>=2.0.0"
+    "qiskit>=2.0.0",
+    "numpy"
+]
+symbolic = [
+	"sympy"
 ]
 test = [
     "pytest>=8.0.0",
     "pytest-cov>=5.0.0",
     "pytest-benchmark",
     "numpy",
+    "sympy"
 ]
 
 [tool.scikit-build.wheel]

{pyrauli-0.3.1 → pyrauli-0.4.0}/src/pyrauli/__init__.py

@@ -12,6 +12,7 @@ from ._core import (
     SchedulingPolicy, NeverPolicy, AlwaysBeforeSplittingPolicy,
     AlwaysAfterSplittingPolicy, Circuit, OperationType, Timing,
     SimulationState, CompressionResult, LambdaPolicy,
+    SymbolicCoefficient, SymbolicPauliTerm, SymbolicObservable, SymbolicNoise, SymbolicNoiseModel, SymbolicTruncator, SymbolicWeightTruncator, SymbolicNeverTruncator, SymbolicMultiTruncator, SymbolicCircuit
 )
 
 __all__ = [
@@ -22,8 +23,24 @@ __all__ = [
     "AlwaysBeforeSplittingPolicy", "AlwaysAfterSplittingPolicy", "Circuit",
     "OperationType", "Timing", "SimulationState", "CompressionResult",
     "LambdaPolicy",
+    "SymbolicCoefficient", "SymbolicObservable", "SymbolicPauliTerm", "SymbolicNoise", "SymbolicNoiseModel", "SymbolicTruncator", "SymbolicWeightTruncator", "SymbolicNeverTruncator", "SymbolicMultiTruncator", "SymbolicCircuit"
+
 ]
 
+try:
+    import sympy
+    def to_sympy(self):
+        """
+        Converts the SymbolicCoefficient to a SymPy expression.
+
+        Returns:
+            A SymPy expression equivalent to the SymbolicCoefficient.
+        """
+        return sympy.sympify(self.to_string())
+    SymbolicCoefficient.to_sympy = to_sympy
+except ImportError:
+    pass
+
 # Conditionally import Qiskit-related functionality
 try:
     from .backend import PBackend