Merge branch 'main' into deprecation-cleanup

CONTRIBUTING.md

@@ -211,25 +211,14 @@ To execute all integration tests, run
 $ make integration-test
 ```
 
-##### 3. E2E tests
-
-Executed against an external system configured via a (token, instance, url) 
-tuple. Basic coverage of most important user-facing happy paths. Test suite runs
-faster than integration but slower than unit tests and is stable.
-
-To execute all e2e tests, run
-``` {.bash}
-$ make e2e-test
-```
-
 ###### Configuration
 
-Integration and E2E tests require an environment configuration and can be run agains both IBM Quantum APIs (`ibm_quantum`, and `ibm_cloud`).
+Integration tests require an environment configuration and can be run against both IBM Quantum APIs (`ibm_quantum`, and `ibm_cloud`).
 
 Sample configuration for IBM Quantum
 ```bash
 QISKIT_IBM_TOKEN=...                                            # IBM Quantum API token
-QISKIT_IBM_URL=https://auth.quantum.ibm.com/api       # IBM Quantum API URL
+QISKIT_IBM_URL=https://auth.quantum.ibm.com/api                 # IBM Quantum API URL
 QISKIT_IBM_INSTANCE=ibm-q/open/main                             # IBM Quantum provider to use (hub/group/project)
 QISKIT_IBM_QPU=...                                              # IBM Quantum Processing Unit to use
 ```

DEPRECATION.md

@@ -30,6 +30,22 @@ The guiding principles are:
 - all deprecations, changes and removals are considered API changes, and can
   only occur in minor releases not patch releases, per the [stable branch policy](https://github.com/Qiskit/qiskit/blob/main/MAINTAINING.md#stable-branch-policy).
 
+## What is the public interface?
+
+The public API comprises all *publicly documented* packages, modules, classes, functions, methods, and attributes.
+
+An object is *publicly documented* if and only if it appears in [the hosted API documentation](https://docs.quantum.ibm.com/api/qiskit-ibm-runtime) for `qiskit-ibm-runtime`.
+The presence of a docstring in the Python source (or a `__doc__` attribute) is not sufficient to make an object publicly documented; this documentation must also be rendered in the public API documentation.
+
+As well as the objects themselves needing to be publicly documented, the only public-API *import locations* for a given object is the location it is documented at in [the public API documentation](https://docs.quantum.ibm.com/api/qiskit-ibm-runtime), and parent modules or packages that re-export the object (if any).
+For example, while it is possible to import `RuntimeEncoder` from `qiskit_ibm_runtime.utils.json`, this is not a supported part of the public API because the[`RuntimeEncoder` object is documented as being in `qiskit_ibm_runtime`](https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/qiskit_ibm_runtime.RuntimeEncoder).
+
+As a rule of thumb, if you are using `qiskit-ibm-runtime`, you should import objects from the highest-level package that exports that object.
+
+Some components of the documented public interface may be marked as "experimental", and not subject to the stability guarantees of semantic versioning.
+These will be clearly denoted in the documentation.
+We will only use these "experimental" features sparingly, when we feel there is a real benefit to making the experimental version public in an unstable form, such as a backwards-incompatible new version of core functionality that shows significant improvements over the existing form for limited inputs, but is not yet fully feature complete.
+Typically, a feature will only become part of the public API when we are ready to commit to its stability properly.
 
 ## Removing a feature
 

Makefile

@@ -30,9 +30,6 @@ unit-test:
 integration-test:
 	python -m unittest discover --verbose --top-level-directory . --start-directory test/integration
 
-e2e-test:
-	python -m unittest discover --verbose --top-level-directory . --start-directory test/e2e
-
 docs-test:
 	./test/docs/vale.sh
 

docs/conf.py

@@ -27,7 +27,7 @@
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
-release = '0.34.0'
+release = '0.35.0'
 
 # -- General configuration ---------------------------------------------------
 

pyproject.toml

@@ -40,6 +40,7 @@ issue_format = "`{issue} <https://github.com/Qiskit/qiskit-ibm-runtime/pull/{iss
 
 [tool.setuptools.packages.find]
 exclude = ["test*"]
+namespaces = false
 
 [tool.setuptools]
 include-package-data = true
@@ -49,6 +50,7 @@ zip-safe = false
 root = "."
 write_to = "qiskit_ibm_runtime/VERSION.txt"
 version_scheme = "release-branch-semver"
+fallback_version = "0.35.0"
 
 [project]
 name = "qiskit-ibm-runtime"

qiskit_ibm_runtime/api/session.py

@@ -35,7 +35,6 @@
 STATUS_FORCELIST = (
     500,  # General server error
     502,  # Bad Gateway
-    503,  # Service Unavailable
     504,  # Gateway Timeout
     520,  # Cloudflare general error
     521,  # Cloudflare web server is down
@@ -348,6 +347,12 @@ def request(  # type: ignore[override]
                     message += f". {ex.response.text}"
             if status_code == 401:
                 raise IBMNotAuthorizedError(message) from ex
+            if status_code == 503:  # Planned maintenance outage
+                raise RequestsApiError(
+                    "Unexpected response received from server. Please check if the service "
+                    "is in maintenance mode "
+                    f"https://docs.quantum.ibm.com/announcements/service-alerts {message}"
+                )
             raise RequestsApiError(message, status_code) from ex
 
         return response

qiskit_ibm_runtime/base_primitive.py

@@ -31,7 +31,6 @@
     validate_isa_circuits,
     validate_no_dd_with_dynamic_circuits,
     validate_rzz_pubs,
-    validate_no_param_expressions_gen3_runtime,
 )
 from .utils.default_session import get_cm_session
 from .utils.deprecation import issue_deprecation_msg
@@ -153,7 +152,6 @@ def _run(self, pubs: Union[list[EstimatorPub], list[SamplerPub]]) -> RuntimeJobV
         runtime_options = self._options_class._get_runtime_options(options_dict)
 
         validate_no_dd_with_dynamic_circuits([pub.circuit for pub in pubs], self.options)
-        validate_no_param_expressions_gen3_runtime([pub.circuit for pub in pubs], self.options)
         if self._backend:
             if not is_simulator(self._backend):
                 validate_rzz_pubs(pubs)

qiskit_ibm_runtime/fake_provider/__init__.py

@@ -139,6 +139,7 @@
     FakeCasablancaV2
     FakeCusco
     FakeEssexV2
+    FakeFez
     FakeGeneva
     FakeGuadalupeV2
     FakeHanoiV2
@@ -154,6 +155,7 @@
     FakeLondonV2
     FakeManhattanV2
     FakeManilaV2
+    FakeMarrakesh
     FakeMelbourneV2
     FakeMontrealV2
     FakeMumbaiV2

qiskit_ibm_runtime/fake_provider/backends/__init__.py

@@ -32,6 +32,7 @@
 from .casablanca import FakeCasablancaV2
 from .cusco import FakeCusco
 from .essex import FakeEssexV2
+from .fez import FakeFez
 from .fractional import FakeFractionalBackend
 from .geneva import FakeGeneva
 from .guadalupe import FakeGuadalupeV2
@@ -47,6 +48,7 @@
 from .london import FakeLondonV2
 from .manhattan import FakeManhattanV2
 from .manila import FakeManilaV2
+from .marrakesh import FakeMarrakesh
 from .melbourne import FakeMelbourneV2
 from .montreal import FakeMontrealV2
 from .mumbai import FakeMumbaiV2

test/e2e/__init__.py → qiskit_ibm_runtime/fake_provider/backends/fez/__init__.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2022.
+# (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
@@ -10,4 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""E2E tests."""
+"""
+Fake Fez backend (156 qubit).
+"""
+
+from .fake_fez import FakeFez

qiskit_ibm_runtime/fake_provider/backends/fez/defs_fez.json

@@ -0,0 +1 @@
+{"qubit_freq_est": [4.95079277767259, 4.503346130911665, 4.952884329275643, 4.595887568323743, 4.98184748039319, 4.610594640509777, 4.983034456699497, 4.484647153756733, 4.945069073244737, 4.521229337942823, 4.8572200123612665, 4.500649489144136, 4.9640144012796, 4.522727219565492, 4.9571777916083635, 4.452114145850816, 4.940893692810253, 4.899159463654739, 4.8176643803509265, 4.835381386861501, 4.952108277816379, 4.5718867330462825, 4.907259595568143, 4.575659077949923, 4.970362778932589, 4.558094830554397, 4.958825939005655, 4.506204302730053, 4.907018481872754, 4.536686831481257, 4.920037823621657, 4.441639917018074, 4.991709296215476, 4.594712680717752, 4.942985266594169, 4.4709499335834515, 4.960844591393425, 4.934709786939442, 4.8644141903681435, 4.901906454996748, 4.975091504313234, 4.542638769067585, 4.974458459505283, 4.537737228870049, 4.9464041839912305, 4.5051678400608335, 4.891314095434463, 4.606613863963458, 4.915623624835605, 4.495006422150584, 4.931023629341118, 4.485320261015973, 4.848467543879026, 4.4309334659957145, 4.966495860510793, 4.532728535529459, 4.938161241428077, 4.901183156440622, 4.873875748174168, 4.89430084537525, 4.887839567629637, 4.579230822809624, 4.977247879238954, 4.470286158192751, 4.8747623415251855, 4.482410388157152, 4.811651608487689, 4.365766213220751, 4.734159737101941, 4.560791682262176, 4.887598731948059, 4.532251206302097, 4.9067638269113365, 4.526798556524261, 4.842542527079143, 4.527798178870366, 4.927660069828791, 4.919649204775521, 4.869412088951523, 4.885642199130317, 4.716199221552255, 4.603237433263415, 4.9919429649454985, 4.517669742667739, 4.920036560464483, 4.536200043800951, 4.93487704824665, 4.562807611975779, 4.943617667327317, 4.5325105817085785, 4.984064219819692, 4.525436696680738, 4.967497679351742, 4.500767042113552, 4.920844743741464, 4.542161232022286, 4.8661694136061655, 4.934644334230025, 4.869552507324293, 4.958407247045962, 4.857286378359333, 4.442210841329088, 4.960744638131382, 4.523674346840864, 4.872012984852126, 4.441479589609135, 4.713653754356548, 4.603520352477905, 4.895700804051116, 4.53971407587476, 4.953039906701974, 4.48634030337296, 4.84791941104327, 4.420349383467706, 4.899978662147701, 4.571489598155011, 4.842751906387526, 4.91009450908409, 4.90352447329264, 4.937435838720572, 4.877681672298434, 4.444304671134067, 4.984819633271854, 4.452762645631057, 4.95043788602721, 4.564303380108061, 4.96864364079267, 4.548529671109697, 4.977235522422675, 4.48518438132869, 4.94115564101883, 4.491132383766706, 4.864681570522855, 4.402323907168976, 4.898625869010777, 4.400698802842506, 4.970558246498248, 4.909999537721105, 4.961305324352133, 4.819908422069005, 4.949196273303993, 4.619444293656993, 4.941679430170647, 4.553703250032461, 4.913853075959568, 4.562833476543761, 4.921982438843083, 4.508232984521416, 4.892356163806747, 4.486061974670816, 4.859759146202145, 4.52800771128115, 4.885510748485252, 4.49062941083197, 4.834713543543853, 4.443193413224464], "meas_freq_est": [7.1177393900000006, 7.356718633000001, 6.663909214, 7.429737159, 7.122275722, 7.359569994, 6.666480355, 7.427730155000001, 7.1264337310000005, 7.361614212, 6.663004266000001, 7.429407222, 7.1220836300000006, 7.3581874030000005, 6.6644506670000005, 7.425995632, 6.735616876000001, 6.73223484, 6.73131881, 6.726271389000001, 6.9704234220000005, 7.273628876, 6.817273966, 7.201927107, 6.969616671000001, 7.277745745000001, 6.813527205000001, 7.198333438000001, 6.973430453000001, 7.276708775, 6.813669899000001, 7.202655645, 6.9661989570000005, 7.279676662000001, 6.817229513, 7.199935684000001, 6.887603684, 6.890598450000001, 6.889639955000001, 6.892373664000001, 7.115914676, 7.351485381000001, 6.661104771000001, 7.423138979722434, 7.114425458, 7.351499931, 6.660891304000001, 7.429951918, 7.111564675, 7.3517770790000005, 6.660717205, 7.428411406, 7.117590150000001, 7.3498941780000004, 6.66210165, 7.434276766000001, 6.726900174000001, 6.7280453080000004, 6.729464106, 6.730467161, 6.963420204, 7.266993395, 6.809741573, 7.193851242, 6.964777595, 7.274019594, 6.807316883, 7.190076203, 6.965802538, 7.268426418000001, 6.804493471000001, 7.195180743000001, 6.967497327, 7.275114291, 6.807593236000001, 7.195448766, 6.884959279, 6.886282266, 6.888280729000001, 6.888012783000001, 7.105308563, 7.344206885, 6.658284242000001, 7.417571068000001, 7.110777666000001, 7.34421076, 6.655930288, 7.4251786950000005, 7.113096711000001, 7.347179145, 6.656070279000001, 7.425530418, 7.110857813000001, 7.3458782220000005, 6.654641257000001, 7.421900518, 6.72495968, 6.727493506, 6.725660694, 6.7214238470000005, 6.958622207, 7.260410841000001, 6.804227283, 7.1890516600000005, 6.959827373, 7.270466331000001, 6.800735089000001, 7.191196141000001, 6.963580471, 7.267803025, 6.808508765, 7.191323046000001, 6.960224056, 7.265704824, 6.800980831, 7.18454498, 6.880886836, 6.879697053, 6.884487495, 6.887957657, 7.102284837, 7.335372380000001, 6.6572504320000006, 7.413766713, 7.0999968220000005, 7.330237379000001, 6.650621119, 7.408960858, 7.099957532, 7.334099475, 6.653071845, 7.409641601000001, 7.097663146, 7.3369714980000005, 6.654380818000001, 7.412891237, 6.718358800000001, 6.719498923000001, 6.718055551000001, 6.725150631, 6.952512487000001, 7.262912813000001, 6.7945761110000005, 7.179160744000001, 6.951041758000001, 7.260086461, 6.782920839, 7.1795064580000005, 6.960000492000001, 7.2566712650000005, 6.779550621, 7.182143336, 6.9593099370000004, 7.258523873000001, 6.775604343, 7.182864821000001], "buffer": 0, "pulse_library": [], "cmd_def": [], "meas_kernel": {"name": "hw_qmfk", "params": {}}, "discriminator": {"name": "hw_qmfk", "params": {}}, "_data": {}}

qiskit_ibm_runtime/fake_provider/backends/fez/fake_fez.py

@@ -0,0 +1,28 @@
+# 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.
+
+"""
+Fake Fez device (156 qubit).
+"""
+
+import os
+from qiskit_ibm_runtime.fake_provider import fake_backend
+
+
+class FakeFez(fake_backend.FakeBackendV2):
+    """A fake 156 qubit backend."""
+
+    dirname = os.path.dirname(__file__)  # type: ignore
+    conf_filename = "conf_fez.json"  # type: ignore
+    props_filename = "props_fez.json"  # type: ignore
+    defs_filename = "defs_fez.json"  # type: ignore
+    backend_name = "fake_fez"  # type: ignore

qiskit_ibm_runtime/fake_provider/backends/marrakesh/__init__.py

@@ -0,0 +1,17 @@
+# 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.
+
+"""
+Fake Marrakesh backend (156 qubit).
+"""
+
+from .fake_marrakesh import FakeMarrakesh