Rename arguments in primitives (Qiskit#7818)

* Rename arguments in primitives

* Apply suggestions from code review

Co-authored-by: Takashi Imamichi <[email protected]>

Co-authored-by: Takashi Imamichi <[email protected]>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Author: 3 people

qiskit/primitives/base_estimator.py

@@ -198,36 +198,36 @@ def parameters(self) -> tuple[ParameterView, ...]:
     @abstractmethod
     def __call__(
         self,
-        circuits: Sequence[int],
-        observables: Sequence[int],
-        parameters: Sequence[Sequence[float]],
+        circuit_indices: Sequence[int],
+        observable_indices: Sequence[int],
+        parameter_values: Sequence[Sequence[float]],
         **run_options,
     ) -> EstimatorResult:
         """Run the estimation of expectation value(s).
 
-        ``circuits``, ``observables``, and ``parameters`` should have the same length.
-        The i-th element of the result is the expectation of observable
+        ``circuit_indices``, ``observable_indices``, and ``parameter_values`` should have the same
+        length. The i-th element of the result is the expectation of observable
 
         .. code-block:: python
 
-            obs = self.observables[observables[i]]
+            obs = self.observables[observable_indices[i]]
 
         for the state prepared by
 
         .. code-block:: python
 
-            circ = self.circuits[circuits[i]]
+            circ = self.circuits[circuit_indices[i]]
 
         with bound parameters
 
         .. code-block:: python
 
-            values = parameters[i].
+            values = parameter_values[i].
 
         Args:
-            circuits: the list of circuit indices.
-            observables: the list of observable indices.
-            parameters: concrete parameters to be bound.
+            circuit_indices: the list of circuit indices.
+            observable_indices: the list of observable indices.
+            parameter_values: concrete parameters to be bound.
             run_options: runtime options used for circuit execution.
 
         Returns:

qiskit/primitives/base_sampler.py

@@ -162,19 +162,20 @@ def parameters(self) -> tuple[ParameterView, ...]:
     @abstractmethod
     def __call__(
         self,
-        circuits: Sequence[int],
-        parameters: Sequence[Sequence[float]],
+        circuit_indices: Sequence[int],
+        parameter_values: Sequence[Sequence[float]],
         **run_options,
     ) -> SamplerResult:
         """Run the sampling of bitstrings.
 
         Args:
-            circuits: indexes of the circuits to evaluate.
-            parameters: parameters to be bound.
+            circuit_indices: indexes of the circuits to evaluate.
+            parameter_values: parameters to be bound.
             run_options: backend runtime options used for circuit execution.
 
         Returns:
             the result of Sampler. The i-th result corresponds to
-            ``self.circuits[circuits[i]]`` evaluated with parameters bound as ``parameters[i]``.
+            ``self.circuits[circuit_indices[i]]`` evaluated with parameters bound as
+            ``parameter_values[i]``.
         """
         ...

qiskit/primitives/estimator.py

@@ -59,40 +59,40 @@ def __init__(
 
     def __call__(
         self,
-        circuits: Sequence[int] | None = None,
-        observables: Sequence[int] | None = None,
-        parameters: Sequence[Sequence[float]] | Sequence[float] | None = None,
+        circuit_indices: Sequence[int] | None = None,
+        observable_indices: Sequence[int] | None = None,
+        parameter_values: Sequence[Sequence[float]] | Sequence[float] | None = None,
         **run_options,
     ) -> EstimatorResult:
         if self._is_closed:
             raise QiskitError("The primitive has been closed.")
 
-        if parameters and not isinstance(parameters[0], Sequence):
-            parameters = cast("Sequence[float]", parameters)
-            parameters = [parameters]
+        if parameter_values and not isinstance(parameter_values[0], Sequence):
+            parameter_values = cast("Sequence[float]", parameter_values)
+            parameter_values = [parameter_values]
         if (
-            circuits is None
+            circuit_indices is None
             and len(self._circuits) == 1
-            and observables is None
+            and observable_indices is None
             and len(self._observables) == 1
-            and parameters is not None
+            and parameter_values is not None
         ):
-            circuits = [0] * len(parameters)
-            observables = [0] * len(parameters)
-        if circuits is None:
-            circuits = list(range(len(self._circuits)))
-        if observables is None:
-            observables = list(range(len(self._observables)))
-        if parameters is None:
-            parameters = [[]] * len(circuits)
-        if len(circuits) != len(parameters):
+            circuit_indices = [0] * len(parameter_values)
+            observable_indices = [0] * len(parameter_values)
+        if circuit_indices is None:
+            circuit_indices = list(range(len(self._circuits)))
+        if observable_indices is None:
+            observable_indices = list(range(len(self._observables)))
+        if parameter_values is None:
+            parameter_values = [[]] * len(circuit_indices)
+        if len(circuit_indices) != len(parameter_values):
             raise QiskitError(
-                f"The number of circuits ({len(circuits)}) does not match "
-                f"the number of parameter sets ({len(parameters)})."
+                f"The number of circuit indices ({len(circuit_indices)}) does not match "
+                f"the number of parameter value sets ({len(parameter_values)})."
             )
 
         bound_circuits = []
-        for i, value in zip(circuits, parameters):
+        for i, value in zip(circuit_indices, parameter_values):
             if len(value) != len(self._parameters[i]):
                 raise QiskitError(
                     f"The number of values ({len(value)}) does not match "
@@ -101,7 +101,7 @@ def __call__(
             bound_circuits.append(
                 self._circuits[i].bind_parameters(dict(zip(self._parameters[i], value)))
             )
-        sorted_observables = [self._observables[i] for i in observables]
+        sorted_observables = [self._observables[i] for i in observable_indices]
         expectation_values = []
         for circ, obs in zip(bound_circuits, sorted_observables):
             if circ.num_qubits != obs.num_qubits:

qiskit/primitives/estimator_result.py

@@ -32,7 +32,7 @@ class EstimatorResult:
         result = estimator(circuits, observables, params)
 
     where the i-th elements of ``result`` correspond to the circuit and observable given by
-    `circuits[i]`, `observables[i]`, and the parameters bounds by `params[i]`.
+    ``circuit_indices[i]``, ``observable_indices[i]``, and the parameter_values bounds by ``params[i]``.
     For example, ``results.values[i]`` gives the expectation value, and ``result.metadata[i]``
     is a metadata dictionary for this circuit and parameters.
 

qiskit/primitives/sampler.py

@@ -64,27 +64,27 @@ def __init__(
 
     def __call__(
         self,
-        circuits: Sequence[int] | None = None,
-        parameters: Sequence[Sequence[float]] | None = None,
+        circuit_indices: Sequence[int] | None = None,
+        parameter_values: Sequence[Sequence[float]] | None = None,
         **run_options,
     ) -> SamplerResult:
         if self._is_closed:
             raise QiskitError("The primitive has been closed.")
 
-        if circuits is None and parameters is not None and len(self._circuits) == 1:
-            circuits = [0] * len(parameters)
-        if circuits is None:
-            circuits = list(range(len(self._circuits)))
-        if parameters is None:
-            parameters = [[]] * len(circuits)
-        if len(circuits) != len(parameters):
+        if circuit_indices is None and parameter_values is not None and len(self._circuits) == 1:
+            circuit_indices = [0] * len(parameter_values)
+        if circuit_indices is None:
+            circuit_indices = list(range(len(self._circuits)))
+        if parameter_values is None:
+            parameter_values = [[]] * len(circuit_indices)
+        if len(circuit_indices) != len(parameter_values):
             raise QiskitError(
-                f"The number of circuits ({len(circuits)}) does not match "
-                f"the number of parameter sets ({len(parameters)})."
+                f"The number of circuit indices ({len(circuit_indices)}) does not match "
+                f"the number of parameter value sets ({len(parameter_values)})."
             )
 
         bound_circuits_qargs = []
-        for i, value in zip(circuits, parameters):
+        for i, value in zip(circuit_indices, parameter_values):
             if len(value) != len(self._parameters[i]):
                 raise QiskitError(
                     f"The number of values ({len(value)}) does not match "
@@ -101,7 +101,7 @@ def __call__(
         ]
         quasis = [QuasiDistribution(dict(enumerate(p))) for p in probabilities]
 
-        return SamplerResult(quasis, [{}] * len(circuits))
+        return SamplerResult(quasis, [{}] * len(circuit_indices))
 
     def close(self):
         self._is_closed = True

qiskit/primitives/sampler_result.py

@@ -30,8 +30,8 @@ class SamplerResult:
 
         result = sampler(circuits, params)
 
-    where the i-th elements of ``result`` correspond to the circuit given by ``circuits[i]``,
-    and the parameters bounds by ``params[i]``.
+    where the i-th elements of ``result`` correspond to the circuit given by ``circuit_indices[i]``,
+    and the parameter_values bounds by ``params[i]``.
     For example, ``results.quasi_dists[i]`` gives the quasi-probabilities of bitstrings, and
     ``result.metadata[i]`` is a metadata dictionary for this circuit and parameters.
 

test/python/primitives/test_estimator.py

@@ -47,15 +47,15 @@ def test_estimator(self):
             observable = PauliSumOp.from_list(lst)
             ansatz = RealAmplitudes(num_qubits=2, reps=2)
             with Estimator([ansatz], [observable]) as est:
-                result = est(parameters=[0, 1, 1, 2, 3, 5])
+                result = est(parameter_values=[0, 1, 1, 2, 3, 5])
             self.assertIsInstance(result, EstimatorResult)
             np.testing.assert_allclose(result.values, [1.84209213])
 
         with self.subTest("SparsePauliOp"):
             observable = SparsePauliOp.from_list(lst)
             ansatz = RealAmplitudes(num_qubits=2, reps=2)
             with Estimator([ansatz], [observable]) as est:
-                result = est(parameters=[0, 1, 1, 2, 3, 5])
+                result = est(parameter_values=[0, 1, 1, 2, 3, 5])
             self.assertIsInstance(result, EstimatorResult)
             np.testing.assert_allclose(result.values, [1.84209213])
 
@@ -64,7 +64,7 @@ def test_estimator_param_reverse(self):
         observable = PauliSumOp.from_list([("XX", 1), ("YY", 2), ("ZZ", 3)])
         ansatz = RealAmplitudes(num_qubits=2, reps=2)
         with Estimator([ansatz], [observable], [ansatz.parameters[::-1]]) as est:
-            result = est(parameters=[0, 1, 1, 2, 3, 5][::-1])
+            result = est(parameter_values=[0, 1, 1, 2, 3, 5][::-1])
         self.assertIsInstance(result, EstimatorResult)
         np.testing.assert_allclose(result.values, [1.84209213])
 
@@ -98,14 +98,14 @@ def test_init_observable_from_operator(self):
     def test_evaluate(self):
         """test for evaluate"""
         with Estimator([self.ansatz], [self.observable]) as est:
-            result = est(parameters=[0, 1, 1, 2, 3, 5])
+            result = est(parameter_values=[0, 1, 1, 2, 3, 5])
         self.assertIsInstance(result, EstimatorResult)
         np.testing.assert_allclose(result.values, [-1.284366511861733])
 
     def test_evaluate_multi_params(self):
         """test for evaluate with multiple parameters"""
         with Estimator([self.ansatz], [self.observable]) as est:
-            result = est(parameters=[[0, 1, 1, 2, 3, 5], [1, 1, 2, 3, 5, 8]])
+            result = est(parameter_values=[[0, 1, 1, 2, 3, 5], [1, 1, 2, 3, 5, 8]])
         self.assertIsInstance(result, EstimatorResult)
         np.testing.assert_allclose(result.values, [-1.284366511861733, -1.3187526349078742])
 
@@ -124,7 +124,7 @@ def test_run_with_multiple_observables_and_none_parameters(self):
         circuit.cx(0, 1)
         circuit.cx(1, 2)
         with Estimator(circuit, ["ZZZ", "III"]) as est:
-            result = est(circuits=[0, 0], observables=[0, 1])
+            result = est(circuit_indices=[0, 0], observable_indices=[0, 1])
         self.assertIsInstance(result, EstimatorResult)
         np.testing.assert_allclose(result.values, [0.0, 1.0])
 

test/python/primitives/test_sampler.py

@@ -84,15 +84,15 @@ def test_sampler(self, indices):
         """test for sampler"""
         circuits, target = self._generate_circuits_target(indices)
         with Sampler(circuits=circuits) as sampler:
-            result = sampler(parameters=[[] for _ in indices])
+            result = sampler(parameter_values=[[] for _ in indices])
             self._compare_probs(result.quasi_dists, target)
 
     @combine(indices=[[0], [1], [0, 1]])
     def test_sampler_pqc(self, indices):
         """test for sampler with a parametrized circuit"""
         params, target = self._generate_params_target(indices)
         with Sampler(circuits=self._pqc) as sampler:
-            result = sampler(parameters=params)
+            result = sampler(parameter_values=params)
             self._compare_probs(result.quasi_dists, target)
 
     @combine(indices=[[0, 0], [0, 1], [1, 1]])
@@ -101,7 +101,7 @@ def test_evaluate_two_pqcs(self, indices):
         circs = [self._pqc, self._pqc]
         params, target = self._generate_params_target(indices)
         with Sampler(circuits=circs) as sampler:
-            result = sampler(parameters=params)
+            result = sampler(parameter_values=params)
             self._compare_probs(result.quasi_dists, target)
 
     def test_sampler_example(self):
@@ -114,7 +114,7 @@ def test_sampler_example(self):
 
         # executes a Bell circuit
         with Sampler(circuits=[bell], parameters=[[]]) as sampler:
-            result = sampler(parameters=[[]], circuits=[0])
+            result = sampler(parameter_values=[[]], circuits=[0])
             self.assertIsInstance(result, SamplerResult)
             self.assertEqual(len(result.quasi_dists), 1)
             keys, values = zip(*sorted(result.quasi_dists[0].items()))