Promote gradient_kwargs to a positional keyword argument in QNode (…

…#6828)

**Context:**
`gradient_kwargs` is now a positional keyword argument for the `QNode`.
This means you can not simply express,
```python
qml.QNode(func, dev, h=1)
```
instead, you must deliberately,
```python
qml.QNode(func, dev, gradient_kwargs={"h":1})
```
This allows easier and cleaner input validation. 

This PR could have wide-spread impact as it is very common to just
specify `gradient_kwargs` casually as additional kwargs.

### **Eco-System**
- [x] Catalyst: PennyLaneAI/catalyst#1480
- [x] Lightning:
PennyLaneAI/pennylane-lightning#1045
- [x] QML Demos: No instances of deprecated code found.

### **Plugins**
- [x] Pennylane-AQT: No instances of deprecated code found.
- [x] Pennylane-Qiskit: No instances of deprecated code found.
- [x] Pennylane-IonQ: No instances of deprecated code found.
- [x] Pennylane-Qrack: No instances of deprecated code found.
- [x] Pennylane-Cirq: No instances of deprecated code found.
- [x] Pennylane-Qulacs: No instances of deprecated code found.

**Description of the Change:**

Allow additional kwargs for now to ensure same functionality, but raise
a deprecation warning. Append those additional kwargs to the internal
gradient_kwargs dictionary.

**Benefits:** Improved input validation for users.

**Possible Drawbacks:** Might have missed some eco-system changes.
Especially with CI **sometimes** not raising
`PennyLaneDeprecationWarning`s as errors 😢 .

[sc-81531]

---------

Co-authored-by: Christina Lee <christina@xanadu.ai>

doc/development/deprecations.rst

@@ -9,6 +9,13 @@ deprecations are listed below.
 Pending deprecations
 --------------------
 
+* Specifying gradient keyword arguments as any additional keyword argument to the qnode is deprecated
+  and will be removed in v0.42.  The gradient keyword arguments should be passed to the new
+  keyword argument ``gradient_kwargs`` via an explicit dictionary, like ``gradient_kwargs={"h": 1e-4}``.
+
+  - Deprecated in v0.41
+  - Will be removed in v0.42
+
 * The `qml.gradients.hamiltonian_grad` function has been deprecated.
   This gradient recipe is not required with the new operator arithmetic system.
 

doc/releases/changelog-dev.md

@@ -84,6 +84,12 @@
 
 <h3>Deprecations 👋</h3>
 
+* Specifying gradient keyword arguments as any additional keyword argument to the qnode is deprecated
+  and will be removed in v0.42.  The gradient keyword arguments should be passed to the new
+  keyword argument `gradient_kwargs` via an explicit dictionary. This change will improve qnode argument
+  validation.
+  [(#6828)](https://github.com/PennyLaneAI/pennylane/pull/6828)
+
 * The `qml.gradients.hamiltonian_grad` function has been deprecated.
   This gradient recipe is not required with the new operator arithmetic system.
   [(#6849)](https://github.com/PennyLaneAI/pennylane/pull/6849)

pennylane/workflow/qnode.py

@@ -133,7 +133,8 @@ def _validate_gradient_kwargs(gradient_kwargs: dict) -> None:
         elif kwarg not in qml.gradients.SUPPORTED_GRADIENT_KWARGS:
             warnings.warn(
                 f"Received gradient_kwarg {kwarg}, which is not included in the list of "
-                "standard qnode gradient kwargs."
+                "standard qnode gradient kwargs. Please specify all gradient kwargs through "
+                "the gradient_kwargs argument as a dictionary."
             )
 
 
@@ -284,9 +285,7 @@ class QNode:
             as the name suggests. If not provided,
             the device will determine the best choice automatically. For usage details, please refer to the
             :doc:`dynamic quantum circuits page </introduction/dynamic_quantum_circuits>`.
-
-    Keyword Args:
-        **kwargs: Any additional keyword arguments provided are passed to the differentiation
+        gradient_kwargs (dict): A dictionary of keyword arguments that are passed to the differentiation
             method. Please refer to the :mod:`qml.gradients <.gradients>` module for details
             on supported options for your chosen gradient transform.
 
@@ -505,10 +504,12 @@ def __init__(
         device_vjp: Union[None, bool] = False,
         postselect_mode: Literal[None, "hw-like", "fill-shots"] = None,
         mcm_method: Literal[None, "deferred", "one-shot", "tree-traversal"] = None,
-        **gradient_kwargs,
+        gradient_kwargs: Optional[dict] = None,
+        **kwargs,
     ):
         self._init_args = locals()
         del self._init_args["self"]
+        del self._init_args["kwargs"]
 
         if logger.isEnabledFor(logging.DEBUG):
             logger.debug(
@@ -536,7 +537,16 @@ def __init__(
         if not isinstance(device, qml.devices.Device):
             device = qml.devices.LegacyDeviceFacade(device)
 
+        gradient_kwargs = gradient_kwargs or {}
+        if kwargs:
+            if any(k in qml.gradients.SUPPORTED_GRADIENT_KWARGS for k in list(kwargs.keys())):
+                warnings.warn(
+                    f"Specifying gradient keyword arguments {list(kwargs.keys())} is deprecated and will be removed in v0.42. Instead, please specify all arguments in the gradient_kwargs argument.",
+                    qml.PennyLaneDeprecationWarning,
+                )
+            gradient_kwargs |= kwargs
         _validate_gradient_kwargs(gradient_kwargs)
+
         if "shots" in inspect.signature(func).parameters:
             warnings.warn(
                 "Detected 'shots' as an argument to the given quantum function. "
@@ -676,16 +686,19 @@ def circuit(x):
         tensor(0.5403, dtype=torch.float64)
         """
         if not kwargs:
-            valid_params = (
-                set(self._init_args.copy().pop("gradient_kwargs"))
-                | qml.gradients.SUPPORTED_GRADIENT_KWARGS
-            )
+            valid_params = set(self._init_args.copy()) | qml.gradients.SUPPORTED_GRADIENT_KWARGS
             raise ValueError(
                 f"Must specify at least one configuration property to update. Valid properties are: {valid_params}."
             )
         original_init_args = self._init_args.copy()
-        gradient_kwargs = original_init_args.pop("gradient_kwargs")
-        original_init_args.update(gradient_kwargs)
+        # gradient_kwargs defaults to None
+        original_init_args["gradient_kwargs"] = original_init_args["gradient_kwargs"] or {}
+        # nested dictionary update
+        new_gradient_kwargs = kwargs.pop("gradient_kwargs", {})
+        old_gradient_kwargs = original_init_args.get("gradient_kwargs").copy()
+        old_gradient_kwargs.update(new_gradient_kwargs)
+        kwargs["gradient_kwargs"] = old_gradient_kwargs
+
         original_init_args.update(kwargs)
         updated_qn = QNode(**original_init_args)
         # pylint: disable=protected-access

tests/gradients/core/test_pulse_gradient.py

@@ -1385,7 +1385,10 @@ def test_simple_qnode_expval(self, num_split_times, shots, tol, seed):
         ham_single_q_const = qml.pulse.constant * qml.PauliY(0)
 
         @qml.qnode(
-            dev, interface="jax", diff_method=stoch_pulse_grad, num_split_times=num_split_times
+            dev,
+            interface="jax",
+            diff_method=stoch_pulse_grad,
+            gradient_kwargs={"num_split_times": num_split_times},
         )
         def circuit(params):
             qml.evolve(ham_single_q_const)(params, T)
@@ -1415,7 +1418,10 @@ def test_simple_qnode_expval_two_evolves(self, num_split_times, shots, tol, seed
         ham_y = qml.pulse.constant * qml.PauliX(0)
 
         @qml.qnode(
-            dev, interface="jax", diff_method=stoch_pulse_grad, num_split_times=num_split_times
+            dev,
+            interface="jax",
+            diff_method=stoch_pulse_grad,
+            gradient_kwargs={"num_split_times": num_split_times},
         )
         def circuit(params):
             qml.evolve(ham_x)(params[0], T_x)
@@ -1444,7 +1450,10 @@ def test_simple_qnode_probs(self, num_split_times, shots, tol, seed):
         ham_single_q_const = qml.pulse.constant * qml.PauliY(0)
 
         @qml.qnode(
-            dev, interface="jax", diff_method=stoch_pulse_grad, num_split_times=num_split_times
+            dev,
+            interface="jax",
+            diff_method=stoch_pulse_grad,
+            gradient_kwargs={"num_split_times": num_split_times},
         )
         def circuit(params):
             qml.evolve(ham_single_q_const)(params, T)
@@ -1471,7 +1480,10 @@ def test_simple_qnode_probs_expval(self, num_split_times, shots, tol, seed):
         ham_single_q_const = qml.pulse.constant * qml.PauliY(0)
 
         @qml.qnode(
-            dev, interface="jax", diff_method=stoch_pulse_grad, num_split_times=num_split_times
+            dev,
+            interface="jax",
+            diff_method=stoch_pulse_grad,
+            gradient_kwargs={"num_split_times": num_split_times},
         )
         def circuit(params):
             qml.evolve(ham_single_q_const)(params, T)
@@ -1504,7 +1516,10 @@ def test_simple_qnode_jit(self, num_split_times, time_interface):
         ham_single_q_const = qml.pulse.constant * qml.PauliY(0)
 
         @qml.qnode(
-            dev, interface="jax", diff_method=stoch_pulse_grad, num_split_times=num_split_times
+            dev,
+            interface="jax",
+            diff_method=stoch_pulse_grad,
+            gradient_kwargs={"num_split_times": num_split_times},
         )
         def circuit(params, T=None):
             qml.evolve(ham_single_q_const)(params, T)
@@ -1543,8 +1558,7 @@ def ansatz(params):
             dev,
             interface="jax",
             diff_method=stoch_pulse_grad,
-            num_split_times=num_split_times,
-            sampler_seed=seed,
+            gradient_kwargs={"num_split_times": num_split_times, "sampler_seed": seed},
         )
         qnode_backprop = qml.QNode(ansatz, dev, interface="jax")
 
@@ -1575,8 +1589,7 @@ def test_qnode_probs_expval_broadcasting(self, num_split_times, shots, tol, seed
             dev,
             interface="jax",
             diff_method=stoch_pulse_grad,
-            num_split_times=num_split_times,
-            use_broadcasting=True,
+            gradient_kwargs={"num_split_times": num_split_times, "use_broadcasting": True},
         )
         def circuit(params):
             qml.evolve(ham_single_q_const)(params, T)
@@ -1620,18 +1633,22 @@ def ansatz(params):
             dev,
             interface="jax",
             diff_method=stoch_pulse_grad,
-            num_split_times=num_split_times,
-            use_broadcasting=True,
-            sampler_seed=seed,
+            gradient_kwargs={
+                "num_split_times": num_split_times,
+                "use_broadcasting": True,
+                "sampler_seed": seed,
+            },
         )
         circuit_no_bc = qml.QNode(
             ansatz,
             dev,
             interface="jax",
             diff_method=stoch_pulse_grad,
-            num_split_times=num_split_times,
-            use_broadcasting=False,
-            sampler_seed=seed,
+            gradient_kwargs={
+                "num_split_times": num_split_times,
+                "use_broadcasting": False,
+                "sampler_seed": seed,
+            },
         )
         params = [jnp.array(0.4)]
         jac_bc = jax.jacobian(circuit_bc)(params)
@@ -1685,9 +1702,7 @@ def ansatz(params):
             dev,
             interface="jax",
             diff_method=qml.gradients.stoch_pulse_grad,
-            num_split_times=7,
-            use_broadcasting=True,
-            sampler_seed=seed,
+            gradient_kwargs={"num_split_times": 7, "sampler_seed": seed, "use_broadcasting": True},
         )
         cost_jax = qml.QNode(ansatz, dev, interface="jax")
         params = (0.42,)
@@ -1730,9 +1745,7 @@ def ansatz(params):
             dev,
             interface="jax",
             diff_method=qml.gradients.stoch_pulse_grad,
-            num_split_times=7,
-            use_broadcasting=True,
-            sampler_seed=seed,
+            gradient_kwargs={"num_split_times": 7, "sampler_seed": seed, "use_broadcasting": True},
         )
         cost_jax = qml.QNode(ansatz, dev, interface="jax")
 

tests/gradients/finite_diff/test_spsa_gradient.py

@@ -161,7 +161,7 @@ def test_invalid_sampler_rng(self):
         """Tests that if sampler_rng has an unexpected type, an error is raised."""
         dev = qml.device("default.qubit", wires=1)
 
-        @qml.qnode(dev, diff_method="spsa", sampler_rng="foo")
+        @qml.qnode(dev, diff_method="spsa", gradient_kwargs={"sampler_rng": "foo"})
         def circuit(param):
             qml.RX(param, wires=0)
             return qml.expval(qml.PauliZ(0))

tests/gradients/parameter_shift/test_cv_gradients.py

@@ -268,7 +268,11 @@ def qf(x, y):
 
         grad_F = jax.grad(qf)(*par)
 
-        @qml.qnode(device=gaussian_dev, diff_method="parameter-shift", force_order2=True)
+        @qml.qnode(
+            device=gaussian_dev,
+            diff_method="parameter-shift",
+            gradient_kwargs={"force_order2": True},
+        )
         def qf2(x, y):
             qml.Displacement(0.5, 0, wires=[0])
             qml.Squeezing(x, 0, wires=[0])

tests/gradients/parameter_shift/test_parameter_shift_shot_vec.py

@@ -1970,12 +1970,12 @@ def expval(self, observable, **kwargs):
 
         dev = DeviceSupporingSpecialObservable(wires=1, shots=None)
 
-        @qml.qnode(dev, diff_method="parameter-shift", broadcast=broadcast)
+        @qml.qnode(dev, diff_method="parameter-shift", gradient_kwargs={"broadcast": broadcast})
         def qnode(x):
             qml.RY(x, wires=0)
             return qml.expval(SpecialObservable(wires=0))
 
-        @qml.qnode(dev, diff_method="parameter-shift", broadcast=broadcast)
+        @qml.qnode(dev, diff_method="parameter-shift", gradient_kwargs={"broadcast": broadcast})
         def reference_qnode(x):
             qml.RY(x, wires=0)
             return qml.expval(qml.PauliZ(wires=0))

tests/resource/test_specs.py

@@ -33,10 +33,15 @@ class TestSpecsTransform:
     """Tests for the transform specs using the QNode"""
 
     def sample_circuit(self):
+
         @qml.transforms.merge_rotations
         @qml.transforms.undo_swaps
         @qml.transforms.cancel_inverses
-        @qml.qnode(qml.device("default.qubit"), diff_method="parameter-shift", shifts=pnp.pi / 4)
+        @qml.qnode(
+            qml.device("default.qubit"),
+            diff_method="parameter-shift",
+            gradient_kwargs={"shifts": pnp.pi / 4},
+        )
         def circuit(x):
             qml.RandomLayers(qml.numpy.array([[1.0, 2.0]]), wires=(0, 1))
             qml.RX(x, wires=0)
@@ -222,7 +227,11 @@ def test_splitting_transforms(self):
 
         @qml.transforms.split_non_commuting
         @qml.transforms.merge_rotations
-        @qml.qnode(qml.device("default.qubit"), diff_method="parameter-shift", shifts=pnp.pi / 4)
+        @qml.qnode(
+            qml.device("default.qubit"),
+            diff_method="parameter-shift",
+            gradient_kwargs={"shifts": pnp.pi / 4},
+        )
         def circuit(x):
             qml.RandomLayers(qml.numpy.array([[1.0, 2.0]]), wires=(0, 1))
             qml.RX(x, wires=0)

tests/templates/test_state_preparations/test_mottonen_state_prep.py

@@ -431,7 +431,7 @@ def circuit(coeffs):
         qml.MottonenStatePreparation(coeffs, wires=[0, 1])
         return qml.probs(wires=[0, 1])
 
-    circuit_fd = qml.QNode(circuit, dev, diff_method="finite-diff", h=0.05)
+    circuit_fd = qml.QNode(circuit, dev, diff_method="finite-diff", gradient_kwargs={"h": 0.05})
     circuit_ps = qml.QNode(circuit, dev, diff_method="parameter-shift")
     circuit_exact = qml.QNode(circuit, dev_no_shots)