Add tutorial for the runtime VQE program

[Cryoris]

Summary

Add a tutorial for for using the runtime VQE program.

Details and comments

We need to exclude this tutorial from the CI, since the CI does not have runtime access (and it would take much too long to run)!

[woodsp-ibm]

Could/should we use algorithm_globals and set its seed? Also for better reproducibility the seed_simulator and seed_transpiler would be set. Maybe you really just want the same initial point for the start.

Did you consider showing a remote device usage the current way - instead of, or in addition to the simulator usage? Maybe running it might be too slow overall but you would see things like noise mitigation in there etc so as more easily able to compare todays execution on a remote backend to using the runtime instead.

[manoelmarques]

The CI builds the docs and by consequence runs the tutorials in order to build their html doc version, it is not merely to test them. If a tutorial is excluded because of access or because it is too slow, it means it won't be uploaded to the Qiskit docs. Instead why not do the same we have done in the past for other tutorials like the ones that used IBMQ and have instead some flag (env. variable) with an 'if statement' in the cells so that the user can run it locally and the tutorial would still show in the documentation ?

Also Terra has the concept of "fake" backends they use to test backends for which the CI wouldn't have access or be slow. Can we have something similar like a "fake" runtime that doesn't access the network and doesn't require credentials ?

[Cryoris]

Could/should we use algorithm_globals and set its seed? Also for better reproducibility the seed_simulator and seed_transpiler would be set. Maybe you really just want the same initial point for the start.

Initially I just wanted to set the initial point and let the local simulator be subject to randomness just like the runtime. Do you think it would be nicer to fix all settings for the local simulation?

Did you consider showing a remote device usage the current way - instead of, or in addition to the simulator usage? Maybe running it might be too slow overall but you would see things like noise mitigation in there etc so as more easily able to compare todays execution on a remote backend to using the runtime instead

Yeah, we considered that but ended up excluding it to keep the tutorial shorter and focus on how to use the VQE program for chemistry. We should definitely add another tutorial in future where we compare actual runtimes using Qiskit Runtime and "traditional" execution.

[Cryoris]

The CI builds the docs and by consequence runs the tutorials in order to build their html doc version, it is not merely to test them. If a tutorial is excluded because of access or because it is too slow, it means it won't be uploaded to the Qiskit docs. Instead why not do the same we have done in the past for other tutorials like the ones that used IBMQ and have instead some flag (env. variable) with an 'if statement' in the cells so that the user can run it locally and the tutorial would still show in the documentation ?

It would of course be nice if we could show the tutorials in the documentation.

How exactly does the if-statement exclusion work? Do we only exclude it for the user? Do all tutorials on the website get executed by some server or can we circumvent that with some if-statements? The issue here might be that we don't want a server/CI to execute these tutorials.

Also Terra has the concept of "fake" backends they use to test backends for which the CI wouldn't have access or be slow. Can we have something similar like a "fake" runtime that doesn't access the network and doesn't require credentials ?

That's a good question and I think there are some test environments (right @jyu00) but I didn't yet get the chance to test or include them.

[manoelmarques]

How exactly does the if-statement exclusion work? Do we only exclude it for the user? Do all tutorials on the website get executed by some server or can we circumvent that with some if-statements? The issue here might be that we don't want a server/CI to execute these tutorials.

The idea is to have some cells only running on the user's machine:

One example is where the user needs to supply a token. That cell only runs on the user's machine since it needs a token: https://qiskit.org/documentation/finance/tutorials/11_time_series.html

token = "REPLACE-ME"
if token != "REPLACE-ME":
    try:
        wiki = WikipediaDataProvider(
                         token = token,
                         tickers = stocks,
                         start = datetime.datetime(2016,1,1),
                         end = datetime.datetime(2016,1,30))
        wiki.run()
    except QiskitFinanceError as ex:
        print(ex)
        print("Error retrieving data.")

Another situation is if some cell may take a long time, to have an if statement similar to the one above only running if some env.variable is not set. This way the doc.build/CI could set the env.variable and the cell would not run during build time. Since the user would not set the env.variable, the cell would run locally only.

If however you don’t want the notebook to be run at all by sphinx (CI) but still show in docs, just add this to your notebook json metadata as explained at https://nbsphinx.readthedocs.io/en/0.2.15/never-execute.html :

“nbsphinx": {
  "execute": "never"
},

[woodsp-ibm]

Could/should we use algorithm_globals and set its seed? Also for better reproducibility the seed_simulator and seed_transpiler would be set. Maybe you really just want the same initial point for the start.

Initially I just wanted to set the initial point and let the local simulator be subject to randomness just like the runtime. Do you think it would be nicer to fix all settings for the local simulation?

My comment was part motivated by this talking about reproducibility

np.random.seed(5)  # fix seed for reproducibility

Now if it just starting from the same place then you could just set the point here. And in fact why not pick a point that is closer to the final solution - you could get such a point from a run.

Now what is the goal here in this tutorial. The main introduction text is around speed up yet the tutorial does not include execution times. I agree a key aspect too is how simple things are to change to using runtime, which is the later part of that text, and this tutorial shows. Can we pick a point closer to the solution, where the runtime of the current way would not be too bad, and contrast running with that to the new way? Maybe just even run a few iterations to show the difference, if such an initial point ends up with too many. Of course it would need to be stated that since devices are shared that any times that were shown can vary depending on usage etc.

In the graph at the end the line +200mH is just because this is where its converging? Its far from what is considered chemical accuracy, that you might see done as a higher line above the expected in plots.

[stefan-woerner]

lgtm