ObservablesArray docstring improvement

[gadial]

Summary

Expands the docstring of ObservablesArray.tolist to make it clear it might return a scalar in the case the observables array is of dimension 0.

Fixes #13402.

Details and comments

ObservablesArray.tolist is based on numpy's tolist method which returns a list with nesting level equal to the dimension of the numpy array being converted. When an observable array is initialized using a single observable (as opposed to a list containing a single observable) the internal representation of the array will be as a dimension 0 numpy array, resulting on a somewhat confusing return value:

>>> from qiskit.primitives.containers.observables_array import ObservablesArray
>>> oa = ObservablesArray.coerce(["Z"])
>>> print(type(oa.tolist()))
<class 'list'>
>>> oa = ObservablesArray.coerce("Z")
>>> print(type(oa.tolist()))
<class 'dict'>

This PR clarifies the issue in the method's docstring.

[qiskit-bot]

One or more of the following people are relevant to this code:

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

[coveralls]

Pull Request Test Coverage Report for Build 11794527861

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 6 unchanged lines in 2 files lost coverage.
• Overall coverage decreased (-0.002%) to 88.933%

---

Files with Coverage Reduction	New Missed Lines	%
crates/accelerate/src/unitary_synthesis.rs	1	92.2%
crates/qasm2/src/lex.rs	5	92.23%

Totals
Change from base Build 11784569909:	-0.002%
Covered Lines:	79063
Relevant Lines:	88902

---

💛 - Coveralls

[ElePT]

Naive question, why is the output type a dict? I would expect a string.

[gadial]

In general, an observable can be a weighted sum of Paulis, so it's represented by a dictionary mapping the Pauli (or Pauli string) to its weight. See here.

[ElePT]

Sphinx needs the double `` to mark code snippets:

Suggested change

	Similar to Numpy's `tolist` method, the level of nesting
	Similar to Numpy's ``tolist`` method, the level of nesting

[ElePT]

Thanks @gadial, in that case, would it incorrect to specify further something like this?

Suggested change

	case of dimension 0 the method returns a single observable
	instead of a list.
	case of dimension 0 the method returns a single observable
	(``dict`` in the case of a weighted sum of Paulis) instead of a list.