IBMQExperiment and FreeformDesign/CombinedExperimentDesign quality-of-life updates

.gitignore

@@ -49,6 +49,7 @@ jupyter_notebooks/Tutorials/tutorial_files/exampleBriefReport
 jupyter_notebooks/Tutorials/tutorial_files/*.ipynb
 jupyter_notebooks/Tutorials/tutorial_files/tempTest
 jupyter_notebooks/Tutorials/tutorial_files/*checkpoints
+jupyter_notebooks/Tutorials/objects/advanced/test_ibmq*
 
 
 

jupyter_notebooks/Tutorials/objects/advanced/IBMQExperiment.ipynb

@@ -11,16 +11,18 @@
    ]
   },
   {
-   "cell_type": "raw",
+   "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
-    "qiskit.__qiskit_version__ = {'qiskit-terra': '0.25.3', 'qiskit': '0.44.3', 'qiskit-aer': None, 'qiskit-ignis': None, 'qiskit-ibmq-provider': '0.20.2', 'qiskit-nature': None, 'qiskit-finance': None, 'qiskit-optimization': None, 'qiskit-machine-learning': None}\n",
-    "qiskit_ibm_provider.__version__ = '0.7.2'"
+    "#qiskit.__qiskit_version__ = {'qiskit-terra': '0.25.3', 'qiskit': '0.44.3', 'qiskit-aer': None, 'qiskit-ignis': None, 'qiskit-ibmq-provider': '0.20.2', 'qiskit-nature': None, 'qiskit-finance': None, 'qiskit-optimization': None, 'qiskit-machine-learning': None}\n",
+    "#qiskit_ibm_provider.__version__ = '0.7.2'"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": null,
    "metadata": {
     "tags": []
    },
@@ -55,7 +57,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -65,7 +67,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "metadata": {
     "tags": [
      "nbval-skip"
@@ -82,16 +84,22 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "metadata": {
     "tags": [
      "nbval-skip"
     ]
    },
    "outputs": [],
    "source": [
-    "dev_name = 'ibm_lagos'\n",
-    "backend = provider.get_backend(dev_name)"
+    "# Use backends() to see what backends you have access to\n",
+    "#provider.backends()\n",
+    "\n",
+    "# Can use a physical device...\n",
+    "backend = provider.get_backend('ibm_hanoi')\n",
+    "\n",
+    "# ... or can use a simulator\n",
+    "sim_backend = provider.get_backend('ibmq_qasm_simulator')"
    ]
   },
   {
@@ -112,7 +120,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -122,7 +130,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "metadata": {
     "tags": [
      "nbval-skip"
@@ -131,7 +139,7 @@
    "outputs": [],
    "source": [
     "# Using the active backend to pull current device specification\n",
-    "device = ExperimentalDevice.from_qiskit_backend(backend)"
+    "device = ExperimentalDevice.from_qiskit_backend(sim_backend)"
    ]
   },
   {
@@ -226,9 +234,9 @@
    "metadata": {},
    "source": [
     "## Running on IBM Q\n",
-    "We're now ready to run on the IBM Q processor. We do this using an `IBMQExperiment` object, which \n",
+    "We're now ready to run on the IBM Q processor. We do this using an `IBMQExperiment` object.\n",
     "\n",
-    "First it converts pyGSTi circuits into jobs that can be submitted to IBM Q. **This step includes transpiling of the pyGSTi circuits into OpenQASM** (and then into QisKit objects)."
+    "We can enable checkpointing for `IBMQExperiment` objects by providing a path. This is the default and is recommended!"
    ]
   },
   {
@@ -239,54 +247,63 @@
    },
    "outputs": [],
    "source": [
-    "exp = ibmq.IBMQExperiment(combined_edesign, pspec, circuits_per_batch=75, num_shots=1024)"
+    "exp = ibmq.IBMQExperiment(combined_edesign, pspec, circuits_per_batch=75, num_shots=1024, seed=20231201, checkpoint_path='test_ibmq')"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We're now ready to submit this experiment to IBM Q."
+    "First we convert pyGSTi circuits into jobs that can be submitted to IBM Q. **This step includes transpiling of the pyGSTi circuits into OpenQASM** (and then into QisKit objects)."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "tags": [
-     "nbval-skip"
-    ]
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
-    "exp.submit(backend)"
+    "# Provide the directory name to enable transpilation checkpointing\n",
+    "exp.transpile()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# We can simulate having been interrupted by removing the last few transpiled batches\n",
+    "del exp.qasm_circuit_batches[4:]\n",
+    "del exp.qiskit_circuit_batches[4:]\n",
+    "\n",
+    "# And now transpilation should only redo the missing batches\n",
+    "exp.transpile()\n"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can then monitor the jobs. If get an error message, you can query the error using `exp['qjob'][i].error_message()` for batch `i`."
+    "If the `IBMQExperiment` object is lost and needs to be reloaded (i.e. notebook restarts), it can be loaded from file now.\n",
+    "\n",
+    "However, the Qiskit circuits are not automatically regenerated from the transpiled QASM during loading for speed. They can (and need to be regenerated if calling `submit()`) by passing in the `regen_qiskit_circs=True` flag to `from_dir()`."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "tags": [
-     "nbval-skip"
-    ]
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
-    "exp.monitor()"
+    "exp2 = ibmq.IBMQExperiment.from_dir('test_ibmq', regen_qiskit_circs=True)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can then grab the results, **Once you see that all the jobs are complete** (`.retrieve_results()` will just hang if the jobs have not yet completed)."
+    "We're now ready to submit this experiment to IBM Q.Note that we can submit using a different backend than what was used to generate the experiment design. In general, it is not a good idea to mix and match backends for physical devices unless they have the exact same connectivity and qubit labeling; however, it **is** often useful for debugging purposes to use the simulator backend rather than a physical device."
    ]
   },
   {
@@ -299,32 +316,35 @@
    },
    "outputs": [],
    "source": [
-    "exp.retrieve_results()"
+    "# Again, we can checkpoint by passing in dirname\n",
+    "exp2.submit(sim_backend)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This `IBMQExperiment` object now contains the results of your experiment. It contains much of the information about exactly what was submitted to IBM Q, and raw results objects that IBM Q returned."
+    "You can then monitor the jobs. If get an error message, you can query the error using `exp.qjobs[i].error_message()` for batch `i`."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "tags": []
+    "tags": [
+     "nbval-skip"
+    ]
    },
    "outputs": [],
    "source": [
-    "print(exp.keys())"
+    "exp2.monitor()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "But, most importantly, it contains the data formatted into a pyGSTi `ProtocolData` object, which is the packaged-up data that pyGSTi analysis proctols use."
+    "Again, the `IBMQExperiment` can be loaded from file if checkpointing is being used. The Qiskit RuntimeJobs are not serialized; however, they can be retrieved from the IBMQ service from their job ids. In order to do this, pass `regen_runtime_jobs=True` and a `provider` to the `from_dir()` call."
    ]
   },
   {
@@ -337,14 +357,27 @@
    },
    "outputs": [],
    "source": [
-    "data = exp['data']"
+    "exp3 = ibmq.IBMQExperiment.from_dir('test_ibmq', regen_runtime_jobs=True, provider=provider)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "nbval-skip"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "exp3.monitor()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We can write this data to disk, which saves the `ProtocolData` in the standard pyGSTi format. It also pickles (or JSONs) up all of the additional information contained then `IBMQExperiment` object, e.g., the job IDs, in a subfolder `ibmqexperiment`."
+    "You can then grab the results, **Once you see that all the jobs are complete** (`.retrieve_results()` will just hang if the jobs have not yet completed)."
    ]
   },
   {
@@ -357,16 +390,14 @@
    },
    "outputs": [],
    "source": [
-    "exp.write('test_ibmq_experiment')"
+    "exp3.retrieve_results()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you only want to load the `ProtocolData` you can do this using pyGSTi's standard `io` functions. We can also load the `IBMQExperiment` object, which will skip unpickling any objects when the unpickling fails (e.g., due to changes in `QisKit`).\n",
-    "\n",
-    "New in '0.9.12': IBM jobs are no longer pickle-able. Instead, they will be retrieved from the server. However, this requires the provider to be passed in at load time."
+    "This `IBMQExperiment` object now contains the results of your experiment. It contains much of the information about exactly what was submitted to IBM Q, and raw results objects that IBM Q returned."
    ]
   },
   {
@@ -379,7 +410,15 @@
    },
    "outputs": [],
    "source": [
-    "loaded_exp = ibmq.IBMQExperiment.from_dir('test_ibmq_experiment', provider)"
+    "display(exp3.qjobs)\n",
+    "display(exp3.batch_results)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "But, most importantly, it contains the data formatted into a pyGSTi `ProtocolData` object, which is the packaged-up data that pyGSTi analysis proctols use."
    ]
   },
   {
@@ -392,15 +431,14 @@
    },
    "outputs": [],
    "source": [
-    "# Now we can run as before\n",
-    "loaded_exp.monitor()"
+    "data = exp3.data"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Analzing the results\n",
+    "## Analyzing the results\n",
     "Because `retrieve_results()` has formatted the data into a `ProctocolData` object, we can just hand this to the analysis protocol(s) that are designed for analyzing this type of data. Here we'll analyze this data using a standard RB curve-fitting analysis."
    ]
   },