Add examples for the NLocal class docstrings (#9080)

[ohadlev77]

Summary

This PR fixes issue #9080 by adding 2 examples for using the NLocal class.

Details and comments

I have added 2 examples for using the NLocal class that emphasize the necessary aspects.

Example 1 uses pre-defined QuantumCircuit objects for the rotation and entanglement layers.

Example 2 demonstrates the specific interface of the NLocal class compared to other parameterized circuit classes (e.g TwoLocal or EfficiensSU2) - one needs to provide the actual gate objects for the rotation_blocks / entanglement_blocks arguments (e.g RYGate(), RXGate(), etc). In the case of the other parameterized circuit classes, one can specify a specific string for a desired gate object (e.g 'ry' for an RY gate).

Following the convention in the docstrings of the other parameterized circuit classes, I didn't include any import statements within the examples. Of course, it can be done if we desire this, but I preferred to stick with the current convention that I've observed.

[qiskit-bot]

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

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

• @Cryoris
• @Qiskit/terra-core
• @ajavadia

[ohadlev77]

@Cryoris @ajavadia @1ucian0

There is a failure in the tests for python3.11 but I think it has nothing to do with my commit.
Can one of you confirm? Should I do something?

[HuangJunye]

@ohadlev77 I think you are right. The failing Python 3.11 is not due to your code. See #9296

[HuangJunye]

Can you please put the code inside jupyter-execute directives so that the code can be executed and tested during the building process?

[ohadlev77]

@HuangJunye
Done.

[ohadlev77]

@HuangJunye can you please check the PR?

[HuangJunye]

@ohadlev77 As discussed via Slack, we have removed the usage of jupyter-execute directive in the documentation, can you please update the code examples using testcode and testoutput directives instead? You can find the instructions here: https://qiskit.github.io/qiskit_sphinx_theme/sphinx_guide/how_to_add_code.html#sphinx-testcode-and-sphinx-testoutput. Please reach out to me if you are unsure about how to do that.

[Cryoris]

I think you could move this explanation outside of the code block, then it would be rendered as normal text and be easier to read 🙂

[ohadlev77]

Sure

[Cryoris]

If users are not familiar with specification per string, I think this is more confusing than clarifying. How about just removing that subsentence? 🙂

Suggested change

	# In the following `***_blocks` arguments is necessary to specify the actual gate objects,
	# rather than some abbreviations that are used in other classes,
	# e.g `CZGate()` = right, `cz` = wrong.
	# In the following `***_blocks` arguments is necessary to specify the Gate objects

[ohadlev77]

Sounds OK, Removing.

[1ucian0]

Hello @ohadlev77 ! are you still working on this PR?

[ohadlev77]

@1ucian0 - yes.
@Cryoris - fixed issues. I didn't change the jupyter-execute blocks because otherwise circuit-plots will not appear. Do we prefer to change it to a static circuit text-diagrams?