diff --git a/qiskit/qpy/__init__.py b/qiskit/qpy/__init__.py index ad49b5147c0d..4dabba7a89a2 100644 --- a/qiskit/qpy/__init__.py +++ b/qiskit/qpy/__init__.py @@ -97,6 +97,8 @@ will be able to load all released format versions of QPY (up until ``QPY_VERSION``). +.. _qpy_compatibility: + QPY Compatibility ================= diff --git a/qiskit/qpy/interface.py b/qiskit/qpy/interface.py index 2410e4b0a79d..ef637b6bced5 100644 --- a/qiskit/qpy/interface.py +++ b/qiskit/qpy/interface.py @@ -126,9 +126,9 @@ def dump( used as the ``cls`` kwarg on the `json.dump()`` call to JSON serialize that dictionary. use_symengine: If True, all objects containing symbolic expressions will be serialized using symengine's native mechanism. This is a faster serialization alternative, - but not supported in all platforms. Please check that your target platform is supported - by the symengine library before setting this option, as it will be required by qpy to - deserialize the payload. For this reason, the option defaults to False. + but not supported in all platforms. This flag only has an effect if the emitted QPY format + version is 10, 11, or 12. For QPY format version >= 13 (which is the default starting in + Qiskit 1.3.0) this flag is no longer used. version: The QPY format version to emit. By default this defaults to the latest supported format of :attr:`~.qpy.QPY_VERSION`, however for compatibility reasons if you need to load the generated QPY payload with an older diff --git a/releasenotes/notes/add-qpy-v13-3b22ae33045af6c1.yaml b/releasenotes/notes/add-qpy-v13-3b22ae33045af6c1.yaml new file mode 100644 index 000000000000..3cc80adc0b5c --- /dev/null +++ b/releasenotes/notes/add-qpy-v13-3b22ae33045af6c1.yaml @@ -0,0 +1,33 @@ +--- +features_qpy: + - | + Added a new QPY format version 13 that adds a Qiskit native representation + of :class:`.ParameterExpression` objects. +issues: + - | + When using QPY formats 10, 11, or 12 there is a dependency on the version + of ``symengine`` installed in the payload for serialized + :class:`.ParamerExpression` if there is mismatched version of the installed + ``symengine`` package between the environment that generated the payload with + :func:`.qpy.dump` and the installed version that is trying to load the payload + with :func:`.qpy.load`. If this is encountered you will need to install the + symengine version from the error message emitted to load the payload. QPY + format version >= 13 (or < 10) will not have this issue and it is recommended + if you're serializing :class:`.ParameterExpression` objects as part of your + circuit or any :class:`.ScheduleBlock` objects you use version 13 to avoid + this issue in the future. +upgrade_qpy: + - | + The :func:`.qpy.dump` function will now emit format version 13 by default. + This means payloads generated with this function by default will only + be compatible with Qiskit >= 1.3.0. If you need for the payload to be + loaded by a older version of Qiskit you can use the ``version`` flag on + :func:`.qpy.dump` to emit a version compatible with earlier releases of + Qiskit. You can refer to :ref:`qpy_compatibility` for more details on this. +# security: +# - | +# Add security notes here, or remove this section. All of the list items in +# this section are combined when the release notes are rendered, so the text +# needs to be worded so that it does not depend on any information only +# available in another section, such as the prelude. This may mean repeating +# some details.