Primitives (non runtime) changes for 1.0

[beckykd]

Closes #1072

Some helpful background: from Jessie: The goal of this document is for people to test their quantum program (that calls primitives) locally, before sending them to Qiskit Runtime to run on a real QPU.

Most of this page uses the statevector simulator, and there is an equivalent for V2, better named as StatevectorEstimator and StatevectorSampler.

[beckykd]

I made an attempt at updating it from the Features migration guide, but it definitely needs a review by someone who understands the base primitives. Maybe @ElePT , @ihincks , or @jyu00 , if anyone has time. Much appreciated!

[ElePT]

I started out trying to leave individual review comments but I think it's easier if I compile them into general feedback about the document. This doc is now a mix of a bunch of prior pages (I can recognize content from at least 3). There is the explanation of what primitives are (in general), particular implementation details of the reference primitives, how to define options, how to deal with parametrized circuits, how to translate everything to backend primitives, and on top of all, an introduction of the new V2 primitives and the need to show V1 and V2 paths for everything. I think that there is enough content that we can at least extract 2 decently sized independent pages, if not more. I suggest the following separation:

1. Keeping this page as a "reference primitives" how-to, i.e. "Running locally with statevector simulators/exact simulation". This is what the title suggests. The page should show how to run, retrieve results and set the only available option (shots/precision) for local execution. We can show paths for both V1 and V2 so this guide will also act a bit as a migration guide/introduction to StatevectorSampler and StatevectorSimulator but only for the most basic use case, no explanation of, for example, broadcasting rules.
2. A guide for the backend primitives, it might make sense to leave this one for when the V2 version is out, or try to document the alternatives that exist now, or keep it V1, but in a separate location.
3. A guide for the new V2 statevector primitives that shows detailed edge cases and how to deal with broadcasting. I think that this guide is crucial, I tried to cover some examples in the 1.0 feature migration guide but I think that it can be super valuable to have an inpendent, easily accessible page for this.
4. Probably better to leave for the future, but a clear guide on setting options in the primitives in general (and only talk about shots/precision in this one).

I have tried to single out the content I believe should be in this page and made a draft in a new branch (EPT/reference-primitives) https://github.com/Qiskit/documentation/blob/EPT/reference-primitives/docs/verify/simulate-with-qiskit-primitives.mdx. The code examples are not correct, a great deal of the document has been commented out and some content is missing, but the build hopefully shows better what I mean. Feel free to use that branch, I didn't want to push anything or overstep, but I wanted to do it to visualize what I wanted to express, and I thought it might be useful to share.

[ElePT]

Here are some screenshots of the content I propose in https://github.com/Qiskit/documentation/blob/EPT/reference-primitives/docs/verify/simulate-with-qiskit-primitives.mdx in case the comments make the raw text not very readable:

[beckykd]

@ElePT thanks so much for taking this on!

[beckykd]

My thoughts on the suggested breakup: (FYI @javabster )

1. Keeping this page as a "reference primitives" how-to, i.e. "Running locally with statevector simulators/exact simulation". This is what the title suggests. ... (BD: Makes sense to me)

2. A guide for the backend primitives, it might make sense to leave this one for when the V2 version is out, or try to document the alternatives that exist now, or keep it V1, but in a separate location. (BD: We've been putting V1 and V2 together, so I'd recommend doing that. Weren't the V2 backend primitives released already? I don't totally understand what would be in this, compared to topic 1.)

3. A guide for the new V2 statevector primitives that shows detailed edge cases and how to deal with broadcasting. I think that this guide is crucial, ... (BD: I'm fine with this)

4. Future: A clear guide on setting options in the primitives in general. (BD: would this be for the base primitives only? We have a section on this in the existing doc, although it's focused on Runtime)

I'm willing to start making issues for whatever new topics we decide on.

The only problem with doing the work on a separate fork is that we don't get the preview, but I don't mind working on your fork.

[ElePT]

We've been putting V1 and V2 together, so I'd recommend doing that. Weren't the V2 backend primitives released already? I don't totally understand what would be in this, compared to topic 1.

There are currently no V2 backend primitives, this is what Jessie's comment and that general thread refers to. For a bit of context, the backend primitives are different from the runtime or reference (statevector) primitives. Runtime primitives run on the runtime provider (IBM backends), reference primitives run on a local statevector simulator. This third type allows to "hook in" primitive implementations to any backend (IBM or non-IBM), and I think that we should document them separately because they do not fit into the "Exact simulation with Qiskit primitives" topic. Until now, the only references to the backend primitives on this page were the two notes about BackendSampler and BackendEstimator:

They were added when the page was a general introduction to the primitives. Now that the topic is under "Verify", they don't really make sense there. However, it is a bit hard to find a place for them in this start-build-transpile-verify-run paradigm. I would personally put them under "run", because they are an alternative to the runtime primtives., however, it's important to understand that they are not linked to any IBM provider/offering. The use-case for the backend primitives is a third-party provider that wants an out-of-the-box implementation of primitives to interface with their own backends that have a backend.run() method.

[ElePT]

4. Future: A clear guide on setting options in the primitives in general. (BD: would this be for the base primitives only? We have a section on this in the existing doc, although it's focused on Runtime)

As far as I understand, there is a plan to implement a new primitive options type that affects all primitives, as explained in this RFC. I have not followed the progress on this item but if it gets implemented, this is what I think should be documented clearly.

[ElePT]

The only problem with doing the work on a separate fork is that we don't get the preview, but I don't mind working on your fork.

@beckykd I can just push my proposal into your branch if that makes it easier for you. It's not in a separate fork, but we would have to open an independent PR to use it directly and we might lose track of the discussion in this PR, which I think is pretty valuable.

[beckykd]

Until now, the only references to the backend primitives on this page were the two notes about BackendSampler and BackendEstimator

@javabster suggested that I pull this information into Get started with primitives, since there's currently not enough to put in its own topic. I pulled it out in the latest commit.

[beckykd]

I suggest the following separation

I created new issues for 2. and 3., because I think they are reasonably separate topics. I'm not sure about 4 (a guide to setting options). That might be better handled within the individual topics.

[kevinsung]

@beckykd What's the status of this PR? In order to work on #1072 I'd like to convert docs/verify/simulate-with-qiskit-primitives.mdx to a Jupyter notebook, but this PR blocks that because it changes this file.

[abbycross]

Had to update this code because of an error found here:

[abbycross]

@ElePT @beckykd is this one ready to merge?