Update Q-CTRL Qiskit Function guides (#2134)

- Update schemas for both functions - Split out Sampler/Estimator docs, rerun problems, update outputs - Update some text and typos --------- Co-authored-by: abbycross <[email protected]> Co-authored-by: Eric Arellano <[email protected]>
Qiskit · Oct 17, 2024 · 1c0954e · 1c0954e
1 parent 763ec2e
commit 1c0954e
Show file tree

Hide file tree

Showing 3 changed files with 392 additions and 234 deletions.
diff --git a/docs/guides/q-ctrl-optimization-solver.ipynb b/docs/guides/q-ctrl-optimization-solver.ipynb
@@ -45,21 +45,37 @@
    "source": [
     "## Inputs and outputs\n",
     "### Inputs\n",
-    "| Name    | Type | Description | Required | Example |\n",
-    "| ---------  | ---------------- | -------------------------- | -------- | ---------- |\n",
-    "| problem  | `str`              | One of the representations listed under \"Accepted problem formats\". | Yes   |`Poly(2.0*n[0]*n[1] + 2.0*n[0]*n[2] - 3.13520241298341*n[0] + 2.0*n[1]*n[2] - 3.14469748506794*n[1] - 3.18897660121566*n[2] + 6.0, n[0], n[1], n[2], domain='RR')` |\n",
-    "| problem_type  | `str`              | Name of the problem class. This is only used for graph problem definitions to determine the objective. Currently limited to “maxcut”.       | No      | `“maxcut”`      |\n",
-    "| instance  | `str`              | The hub/group/project to use in that format.                     | Yes      | `“hub1/group1/project1”`      |\n",
-    "| run_options  | `dict`              | Input options, including the following: (Optional) `backend_name`: str. Defaults to least busy backend. | No     | `{“backend_name”: “ibm_fez\"}`     |\n",
+    "| Name    | Type | Description | Required | Default | Example |\n",
+    "| ---------  | ---------------- | -------------------------- | -------- | ---------- | ---------- |\n",
+    "| problem  | `str`              | One of the representations listed under \"Accepted problem formats\" | Yes | N/A   |`Poly(2.0*n[0]*n[1] + 2.0*n[0]*n[2] - 3.13520241298341*n[0] + 2.0*n[1]*n[2] - 3.14469748506794*n[1] - 3.18897660121566*n[2] + 6.0, n[0], n[1], n[2], domain='RR')` |\n",
+    "| problem_type  | `str`              | Name of the problem class; only used for graph problem definitions, which are limited to \"maxcut\"; not required for arbitrary objective function problem definitions   | No      | `None`| `\"maxcut\"`      |\n",
+    "| backend_name  | `str`              | Name of the backend to use      | No  | Least busy backend that your instance has access to    | `\"hub1/group1/project1\"`      |\n",
+    "| instance  | `str`              | The hub/group/project to use    | No   | A Premium access instance is randomly chosen if your account has access to multiple instances   | `\"hub1/group1/project1\"`      |\n",
+    "| options  | `dict`              | Input options, including the following: (Optional) `session_id`: `str`; default behavior creates a new Session | No | `None`    | `{\"session_id\": \"cw2q70c79ws0008z6g4g\"}`     |\n",
     "\n",
     "**Accepted problem formats:**\n",
     "- Polynomial expression representation of an objective function. Ideally created in Python with an existing SymPy Poly object and formatted into a string using [sympy.srepr](https://docs.sympy.org/latest/tutorials/intro-tutorial/printing.html#srepr).\n",
     "- Graph representation of a specific problem type. The graph should be created using the networkx library in Python. It should then converted to a string by using the networkx function `[nx.readwrite.json_graph.adjacency_data](http://nx.readwrite.json_graph.adjacency_data.)`.\n",
     "\n",
+    "**Supported backends:**\n",
+    "The following list of backends are currently supported. If your device is not listed, [reach out to Q-CTRL](https://form.typeform.com/to/iuujEAEI?typeform-source=q-ctrl.com) to add support.\n",
+    "- ibm_brisbane\n",
+    "- ibm_brussels\n",
+    "- ibm_cleveland\n",
+    "- ibm_fez\n",
+    "- ibm_kawasaki\n",
+    "- ibm_kyiv\n",
+    "- ibm_nazca\n",
+    "- ibm_quebec\n",
+    "- ibm_rensselaer\n",
+    "- ibm_sherbrooke\n",
+    "- ibm_strasbourg\n",
+    "- ibm_torino\n",
+    "\n",
     "### Outputs\n",
     "| Name    | Type | Description | Example |\n",
     "| ---------  | ---------------- | -------------------------- | -------- |\n",
-    "| result  | `dict[str, Any]`              | Solution and metadata listed under \"Result dictionary contents\"         | `{‘solution_bitstring_cost’: 3.0, ‘final_bitstring_distribution’: {‘000001’: 100, ‘000011’: 2}, ‘iteration_count’: 3, ‘solution_bitstring’: ‘000001’,  'variables_to_bitstring_index_map': {n[1]': 5, 'n[2]': 4, 'n[3]': 3, 'n[4]': 2, 'n[5]': 1}, 'best_parameters': [0.19628831763697097, -1.047052334523102], 'warnings': []}`     |\n",
+    "| result  | `dict[str, Any]`              | Solution and metadata listed under \"Result dictionary contents\"         | `{'solution_bitstring_cost': 3.0, ‘final_bitstring_distribution’: {‘000001’: 100, ‘000011’: 2}, ‘iteration_count’: 3, 'solution_bitstring': ‘000001’,  'variables_to_bitstring_index_map': {n[1]': 5, 'n[2]': 4, 'n[3]': 3, 'n[4]': 2, 'n[5]': 1}, 'best_parameters': [0.19628831763697097, -1.047052334523102], 'warnings': []}`     |\n",
     "\n",
     "\n",
     "**Result dictionary contents:**\n",
@@ -124,24 +140,24 @@
     "catalog = QiskitFunctionsCatalog(token=token)\n",
     "\n",
     "# Access Function\n",
-    "solver = catalog.load('q-ctrl/optimization-solver')"
+    "solver = catalog.load(\"q-ctrl/optimization-solver\")"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "e8837f5f",
    "metadata": {},
    "source": [
-    "## Example: Unconstrained Optimization\n",
-    "Run the [maximum cut](https://en.wikipedia.org/wiki/Maximum_cut) (Max-Cut) problem. The following example demonstrates the Solver's capabilities on a 120-node, 3-regular unweighted graph Max-Cut problem, but you can also solve weighted graph problems."
+    "## Example: Unconstrained optimization\n",
+    "Run the [maximum cut](https://en.wikipedia.org/wiki/Maximum_cut) (Max-Cut) problem. The following example demonstrates the Solver's capabilities on a 156-node, 3-regular unweighted graph Max-Cut problem, but you can also solve weighted graph problems."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "a699235b",
    "metadata": {},
    "source": [
-    "In addition to the `qiskit-serverless` package, you will also use the following packages to run this example: `NetworkX`, `PuLP`, and `NumPy`. You can install these packages by uncommenting the following cell if you are running this example in a notebook using the IPython kernel."
+    "In addition to `qiskit-ibm-catalog`, you will also use the following packages to run this example: `networkx` and `numpy`. You can install these packages by uncommenting the following cell if you are running this example in a notebook using the IPython kernel."
    ]
   },
   {
@@ -171,10 +187,9 @@
    "outputs": [],
    "source": [
     "import networkx as nx\n",
-    "import pulp\n",
     "import numpy as np\n",
     "\n",
-    "# Generate a random graph with 120 nodes\n",
+    "# Generate a random graph with 156 nodes\n",
     "maxcut_graph = nx.random_regular_graph(d=3, n=156, seed=8)"
    ]
   },
@@ -237,18 +252,18 @@
    "source": [
     "# Solve the problem\n",
     "maxcut_job = solver.run(\n",
-    "    problem = problem_as_str,\n",
-    "    problem_type = \"maxcut\",\n",
-    "    instance = hub + \"/\" + group + \"/\" + project\n",
+    "    problem=problem_as_str,\n",
+    "    problem_type=\"maxcut\",\n",
+    "    instance=hub + \"/\" + group + \"/\" + project,\n",
     ")"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "03998691",
+   "id": "48069093",
    "metadata": {},
    "source": [
-    "You can use the familiar [Qiskit Serverless APIs](https://docs.quantum.ibm.com/guides/qiskit-serverless) to check your Qiskit Function workload's status:"
+    "Check your Qiskit Function workload's [status](/guides/functions#check-job-status) or return [results](/guides/functions#retrieve-results) as follows:"
    ]
   },
   {
@@ -267,7 +282,7 @@
    "id": "74f48eab",
    "metadata": {},
    "source": [
-    "### 3. Get the result\n",
+    "### 3. Retrieve the result\n",
     "Retrieve the optimal cut value from the results dictionary.\n",
     "\n",
     "<Admonition type=\"note\">The mapping of the variables to the bitstring may have changed. The output dictionary contains a `variables_to_bitstring_index_map` sub-dictionary, which helps to verify the ordering.</Admonition>"
@@ -322,7 +337,7 @@
    "id": "a9fbc0e9",
    "metadata": {},
    "source": [
-    "In addition to the `qiskit-ibm-catalog` and `qiskit` packages, you will also use the following packages to run this example: `NumPy`, `NetworkX`, `SymPy` and `PuLP`. You can install these packages by uncommenting the following cell if you are running this example in a notebook using the IPython kernel."
+    "In addition to the `qiskit-ibm-catalog` and `qiskit` packages, you will also use the following packages to run this example: `numpy`, `networkx`, and `sympy`. You can install these packages by uncommenting the following cell if you are running this example in a notebook using the IPython kernel."
    ]
   },
   {
@@ -365,7 +380,6 @@
     "import numpy as np\n",
     "import networkx as nx\n",
     "from sympy import symbols, Poly\n",
-    "import pulp\n",
     "\n",
     "# To change the weights, change the seed to any integer.\n",
     "rng_seed = 18\n",
@@ -381,11 +395,7 @@
     "    mvc_graph.add_node(i, weight=_rng.random())\n",
     "\n",
     "# Optionally, visualize the graph\n",
-    "nx.draw(\n",
-    "    mvc_graph,\n",
-    "    nx.kamada_kawai_layout(mvc_graph),\n",
-    "    node_size=200,\n",
-    ")"
+    "nx.draw(mvc_graph, nx.kamada_kawai_layout(mvc_graph), node_size=200)"
    ]
   },
   {
@@ -460,8 +470,7 @@
    "source": [
     "# Solve the problem\n",
     "mvc_job = solver.run(\n",
-    "    problem = sympy.srepr(cost_function),\n",
-    "    instance = hub + \"/\" + group + \"/\" + project\n",
+    "    problem=sympy.srepr(cost_function), instance=hub + \"/\" + group + \"/\" + project\n",
     ")"
    ]
   },
@@ -470,7 +479,7 @@
    "id": "d154c226",
    "metadata": {},
    "source": [
-    "You can check your Qiskit Function workload's status as follows:"
+    "Check your Qiskit Function workload's [status](/guides/functions#check-job-status) or return [results](/guides/functions#retrieve-results) as follows:"
    ]
   },
   {