Added design doc for new rb algorithm

[merav-aharoni]

Summary

Created a design doc for the new algorithm for RB experiments under docs/api.

Details and comments

This is based on the implementation in PR #851. Since the implementation brought up many discussion items, I wrote this design docs. Please enter your feedback below. In particular, I raised several questions in bold in the document. @nkanazawa1989 , @yaelbh - you might want to copy your comments here.

[yaelbh]

As we've already discussed in various contexts, an experiment has several different functionalities: build (transpiled or non-transpiled) circuits, run them, analyze, save to the database. We've already noticed that the circuit building should become more independent (beyond override of the _transpiled_circuits method). By "more indpendent", I mean the ability of a user to specify the (usually transpiled) circuits as an input to the run. Then I'd imagine some procedure that looks roughly like this:

• Outside of the experiment flow, outside of BaseExperiment.run and everything - a user saves whatever is required for her to generate transpiled RB circuits (can be e.g. the circuits themselves, or Clifford decompostions). She does it in her file system, in the location that she chooses. She can write her own code for this, and also there can be code in qiskit-experiments to help her do it, but probably as some utility and not as part of BaseExperiment or even of StandardRB. The qiskit-experiments code can refrain from writing to files; instead it returns Python objects, which the user can dump by herself.
• The user generates the transpiled circuits. This again happens outside of the main flow, and can even be done by code that the user writes. The user can save them, if she wants (she's the one to invoke the commands that write to files).
• The user retrieves the transpiled circuits. Perhaps she has just generated them, or she reads them from a file where she stored them.
• The user runs the experiment, with the transpiled circuits specified in the input.

Other places where we've recently encountered the same topic:

1. The request for modularity came up, to my understanding, in conversations of @chriseclectic with users.
2. PR [WIP] Add caching of transpiled circuit generation to BaseExperiment #815 that @chriseclectic started and @ItamarGoldman is about to continue - about circuit caching. Note by the way that Haggai and I would like a follow-up PR to save the cache to a file, which can be loaded later. So we see that not only circuit caching - also file handling is a recurring issue.
3. @ItamarGoldman has suggested to pre-transpile say 1000 RB circuits, then in every execution sample one of them.
4. In the whole-backend PR [WIP] Functions to facilitate experiments on entire backends #859, I build something I've named BasicExperiment, which is an experiment whose only purpose is to store transpiled circuits.
5. @coruscating has asked, in the context of QV: "Would be nice to have standalone functions in experiments to help with playing around with the data (for example method to allow loading custom circuits while keeping analysis the same)".

[merav-aharoni]

My apologies. @eliarbel and @chriseclectic requested me to move this doc and discussion to the internal repo. So I will copy all this over there.