Fix qpy serialization of substitution of type ParameterExpression (#13890)

* Fix qpy serialization of substitution of type ParameterExpression

When substitution history `ParameterExpression._qpy_replay` is serialized,
there was no branch for the case that the substituted value is of type
`ParameterExpression`.
This commit fixes this oversight.

* Fix deserializing qpy written by previous writing fix

* Added a branch for reading `ParameterExpression` in _qpy_replay

* Added a missing argument (version) in an existing call in code path that
  was previously untested

* Remove a bit of useless code introduced in last commit

* run black

* Add tests

* Revert renaming extra_symbols to extra_expressions

Reverting this to minimize changes in order to make the PR safer to
backport.

* Revert cleaning up logic in _encode_replay_subs

This was a good change. But not necessary for the bug fix, which is
the main point of this PR.

* Add qpy compat test

* Bind parameter when checking for equality

* Run black after merge in browser

---------

Co-authored-by: Luciano Bello <bel@zurich.ibm.com>

Author: jlapeyre

qiskit/qpy/binary_io/value.py

@@ -142,6 +142,8 @@ def _encode_replay_subs(subs, file_obj, version):
 
 
 def _write_parameter_expression_v13(file_obj, obj, version):
+    # A symbol is `Parameter` or `ParameterVectorElement`.
+    # `symbol_map` maps symbols to ParameterExpression (which may be a symbol).
     symbol_map = {}
     for inst in obj._qpy_replay:
         if isinstance(inst, _SUBS):
@@ -234,9 +236,17 @@ def _write_parameter_expression(file_obj, obj, use_symengine, *, version):
             # serialize key
             if symbol_key == type_keys.Value.PARAMETER_VECTOR:
                 symbol_data = common.data_to_binary(symbol, _write_parameter_vec)
+            elif symbol_key == type_keys.Value.PARAMETER_EXPRESSION:
+                symbol_data = common.data_to_binary(
+                    symbol,
+                    _write_parameter_expression,
+                    use_symengine=use_symengine,
+                    version=version,
+                )
             else:
                 symbol_data = common.data_to_binary(symbol, _write_parameter)
             # serialize value
+
             value_key, value_data = dumps_value(
                 symbol, version=version, use_symengine=use_symengine
             )
@@ -530,10 +540,13 @@ def _read_parameter_expression_v13(file_obj, vectors, version):
             symbol = _read_parameter(file_obj)
         elif symbol_key == type_keys.Value.PARAMETER_VECTOR:
             symbol = _read_parameter_vec(file_obj, vectors)
+        elif symbol_key == type_keys.Value.PARAMETER_EXPRESSION:
+            symbol = _read_parameter_expression_v13(file_obj, vectors, version)
         else:
             raise exceptions.QpyError(f"Invalid parameter expression map type: {symbol_key}")
 
         elem_key = type_keys.Value(elem_data.type)
+
         binary_data = file_obj.read(elem_data.size)
         if elem_key == type_keys.Value.INTEGER:
             value = struct.unpack("!q", binary_data)
@@ -548,6 +561,7 @@ def _read_parameter_expression_v13(file_obj, vectors, version):
                 binary_data,
                 _read_parameter_expression_v13,
                 vectors=vectors,
+                version=version,
             )
         else:
             raise exceptions.QpyError(f"Invalid parameter expression map type: {elem_key}")

test/python/qpy/test_serialize_value_objects.py

@@ -0,0 +1,43 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2025.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Test serializing ParameterExpressions from qpy."""
+
+import io
+from test import QiskitTestCase  # pylint: disable=wrong-import-order
+from qiskit.circuit import Parameter, QuantumCircuit
+from qiskit import qpy
+
+
+class TestQpySerializeParameterExpression(QiskitTestCase):
+    """QPY serializing ParameterExpression"""
+
+    def test_roundtrip_equal(self):
+        """Test serialize deserialize with ParameterExpression in _qpy_replay"""
+        a = Parameter("a")
+        b = Parameter("b")
+        a1 = a * 2
+        a2 = a1.subs({a: 3 * b})
+
+        qc = QuantumCircuit(1)
+        qc.rz(a2, 0)
+
+        use_symengine = True
+        version = 13
+        with io.BytesIO() as container:
+            qpy.dump(qc, container, version=version, use_symengine=use_symengine)
+            qc_qpy_str = container.getvalue()
+
+        with io.BytesIO(qc_qpy_str) as container:
+            qc_from_qpy = qpy.load(container)[0]
+
+        self.assertEqual(qc, qc_from_qpy)

test/qpy_compat/test_qpy.py

@@ -833,6 +833,18 @@ def generate_v12_expr():
     return [index, shift]
 
 
+def generate_replay_with_expression_substitutions():
+    """Circuits with parameters that have substituted expressions in the replay"""
+    a = Parameter("a")
+    b = Parameter("b")
+    a1 = a * 2
+    a2 = a1.subs({a: 3 * b})
+    qc = QuantumCircuit(1)
+    qc.rz(a2, 0)
+
+    return [qc]
+
+
 def generate_v14_expr():
     """Circuits that contain expressions and types new in QPY v14."""
     from qiskit.circuit.classical import expr, types
@@ -909,6 +921,11 @@ def generate_circuits(version_parts, current_version, load_context=False):
     if version_parts >= (1, 1, 0):
         output_circuits["standalone_vars.qpy"] = generate_standalone_var()
         output_circuits["v12_expr.qpy"] = generate_v12_expr()
+    if version_parts >= (1, 4, 1):
+        output_circuits["replay_with_expressions.qpy"] = (
+            generate_replay_with_expression_substitutions()
+        )
+
     if version_parts >= (2, 0, 0):
         output_circuits["v14_expr.qpy"] = generate_v14_expr()
     return output_circuits
@@ -1020,6 +1037,8 @@ def load_qpy(qpy_files, version_parts):
                 bind = np.linspace(1.0, 2.0, 22)
             elif path == "parameter_vector_expression.qpy":
                 bind = np.linspace(1.0, 2.0, 15)
+            elif path == "replay_with_expressions.qpy":
+                bind = [2.0]
 
             assert_equal(
                 circuit, qpy_circuits[i], i, version_parts, bind=bind, equivalent=equivalent