Add better error messages for typical SamplerV2 and EstimatorV2 error cases

[t-imamichi]

Summary

If users want to run a circuit with SamplerV2, they need to call SamplerV2.run([circuit]) according to the spec.

qiskit/qiskit/primitives/base/base_sampler.py

Lines 166 to 167 in 00b0952

	def run(
	self, pubs: Iterable[SamplerPubLike], *, shots: int | None = None

But, they may miss [] but the corresponding error message was not comprehensive as follows. This PR detects such a case and shows more comprehensive message.

from qiskit import QuantumCircuit
from qiskit.circuit.library import RealAmplitudes
from qiskit.primitives import StatevectorSampler

qc = QuantumCircuit(1, 1)
qc.h(0)
qc.measure(0, 0)

sampler = StatevectorSampler()
result = sampler.run([qc]).result()
# OK

result = sampler.run(qc).result()
# NG

output
main branch:

AttributeError: '_SingletonHGate' object has no attribute 'parameters'

this PR:

ValueError: An invalid Sampler pub-like was given (<class 'qiskit._accelerate.quantum_circuit.CircuitInstruction'>). If you want to run a single circuit, you need to wrap it with [] like sampler.run([circuit]) instead of sampler.run(circuit).

---

I also added a similar error message for Estimator V2 as suggested by @ElePT.

from qiskit import QuantumCircuit
from qiskit.circuit.library import RealAmplitudes
from qiskit.primitives import StatevectorEstimator

qc = QuantumCircuit(1, 1)
qc.h(0)
qc.h(0)
qc.h(0)

estimator = StatevectorEstimator()
result = estimator.run([(qc, "Z")]).result()
# OK

result = estimator.run((qc, "Z")).result()
# NG

output

main branch

TypeError: Invalid observable type: <class 'qiskit._accelerate.quantum_circuit.CircuitInstruction'>

this PR

ValueError: An invalid Estimator pub-like was given (<class 'qiskit.circuit.quantumcircuit.QuantumCircuit'>). If you want to run a single pub-like, you need to wrap it with [] like estimator.run([(circuit, observables, param_values)]) instead of estimator.run((circuit, observables, param_values)).

Details and comments

In addition to the error messages, I fixed random seed for primitives tests (replaced np.random.rand with np.random.default_rng).

[qiskit-bot]

One or more of the the following people are requested to review this:

• @Qiskit/terra-core
• @ajavadia
• @ikkoham
• @levbishop
• @t-imamichi

[coveralls]

Pull Request Test Coverage Report for Build 8344800410

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 10 of 10 (100.0%) changed or added relevant lines in 2 files are covered.
• 5 unchanged lines in 1 file lost coverage.
• Overall coverage decreased (-0.3%) to 89.319%

---

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/lex.rs	5	91.94%

Totals
Change from base Build 8320404144:	-0.3%
Covered Lines:	59811
Relevant Lines:	66963

---

💛 - Coveralls

[ElePT]

Thanks a lot for this PR, I think it makes a lot of sense. I added a suggestion to make the message even more clear (specifying single circuit). Would it make sense to extend this to the Estimator too? I am not sure if there is also a case with a single circuit and observable where this type of issue would happen.

[t-imamichi]

I made the following changes since the last review comment.

• Added an error message for EstimtorV2
• Changed to display the object type instead of the object itself because the message can be very long
• Fixed random seed related np.random.rand. I noticed a error occurred due to the randomness. https://github.com/Qiskit/qiskit/pull/12031/checks?check_run_id=22772610685

[ElePT]

Thanks a lot! I agree that exposing the pub could make the message too long, so using the type is a good call. It might still be a bit unexpected for users to see a report of <class 'qiskit._accelerate.quantum_circuit.CircuitInstruction'> (for example) as their input, but I think that overall the message is much much clearer and hopefully the suggestion about adding [ ] covers a lot of these initial user errors. Mostly LGTM (I left a tiny tiny comment). The changes to the test seeds/rng also look good.

[ElePT]

Sorry, one more question, would a single sampler pub input like sampler.run((circuit,parameters)) run successfully? or would it also have to be wrapped in [] like the estimator one (sampler.run([(circuit,parameters)]))? Asking in case this also needs to be covered by the error messages.

[t-imamichi]

sampler.run((circuit,parameters)) isn't correct. It raises an error ValueError: The number of values (0) does not match the number of parameters (X) for the circuit. (X is the actual number of parameters). In this case, the first item is a valid pub-like ((circuit,parameters) is an iterable and the first object is QuantumCircuit, which is a pub-like), but it is missing parameter values. So, the error message covers the case.
This error message is also raised in the case of sampler.run((circuit1, circuit2)) where circuit1 has some parameters.

[ElePT]

sampler.run((circuit,parameters)) isn't correct. It raises an error ValueError: The number of values (0) does not match the number of parameters (X) for the circuit. (X is the actual number of parameters). In this case, the first item is a valid pub-like ((circuit,parameters) is an iterable and the first object is QuantumCircuit, which is a pub-like), but it is missing parameter values. So, the error message covers the case.
This error message is also raised in the case of sampler.run((circuit1, circuit2)) where circuit1 has some parameters.

I see... it's difficult to tell apart both cases to have a specific message for each case. What do you think if we also add a second part to the error message in SamplerPub.validate so that it says the following??:

  raise ValueError(
      f"The number of values ({num_parameters}) does not match "
      f"the number of parameters ({self.circuit.num_parameters}) for the circuit. "
      f"Note that if you want to run a single pub, you need to wrap it with `[]` like "
      f"`sampler.run([(circuit, param_values)])` instead of `sampler.run((circuit, param_values))`."
  )

[t-imamichi]

Thank you for your suggestion. I added your additional message if the number of parameters do not match and num_parameters == 0.

[ElePT]

Thanks a lot for your changes, I think this looks very good now. Approving!