diff --git a/docs/guides/algorithmiq-tem.ipynb b/docs/guides/algorithmiq-tem.ipynb index 24edd1f9b6d..5e45454d601 100644 --- a/docs/guides/algorithmiq-tem.ipynb +++ b/docs/guides/algorithmiq-tem.ipynb @@ -282,11 +282,26 @@ "\n", "**Parameters**\n", "\n", - "Name | Type | Description | Required | Default | Example\n", - "-- | -- | -- | -- | -- | --\n", - "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/primitive-input-output#overview-of-pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n", - "`backend_name` | str | Name of the backend to make the query.| No | If not provided, the least-busy backend will be used. | \"ibm_fez\"\n", - "`options` | dict | Input options. See `Options` section for more details. | No | See `Options` section for more details.| \\{\"max_bond_dimension\": 100\\}\n", + "### `pubs`\n", + "\n", + "An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/primitive-input-output#overview-of-pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU.\n", + "- Required: Yes\n", + "- Example: `(circuit, observables)`\n", + "\n", + "\n", + "### `backend_name`\n", + "\n", + "Name of the backend to make the query\n", + "- Required: No\n", + "- Example: `\"ibm_fez\"`\n", + "\n", + "\n", + "### `options`\n", + "\n", + "Input options. See the [Options](#options) section for more details.\n", + "- Required: No\n", + "- Example: `{\"max_bond_dimension\": 100}`\n", + "\n", "\n", "\n", " TEM currently has the following limitations:\n", @@ -306,19 +321,60 @@ "\n", "A dictionary containing the advanced options for the TEM. The dictionary may contain the keys in the following table. If any of the options are not provided, the default value listed in the table will be used. The default values are good for typical use of TEM.\n", "\n", - "Name | Choices | Description | Default\n", - "-- | -- | -- | --\n", - "`tem_max_bond_dimension` | int | The maximum bond dimension to be used for the tensor networks. | 500 |\n", - "`tem_compression_cutoff` | float | The cutoff value to be used for the tensor networks. | 1e-16\n", - "`compute_shadows_bias_from_observable` | bool | A boolean flag indicating whether the bias for the classical shadows measurement protocol should be tailored to the PUB observable or not. If False, the classical shadows protocol (equal probability of measuring Z, X, Y) will be used.| False\n", - "`shadows_bias` | np.ndarray | The bias to be used for the randomized classical shadows measurement protocol, a 1d or 2d array of size 3 or shape (num_qubits, 3) respectively. order is ZXY | np.array([1 / 3, 1 / 3, 1 / 3])\n", - "`max_execution_time` | int or `None` | The maximum execution time on the QPU in seconds. If the runtime exceeds this value, the job will be canceled. If `None`, a default limit set by Qiskit Runtime will apply. | `None`\n", - "`num_randomizations` | int | The number of randomizations to be used for noise learning and gate twirling. | 32\n", - "`max_layers_to_learn` | int | The maximum number of unique layers to learn. | 4\n", - "`mitigate_readout_error` | bool | A Boolean flag indicating whether to perform readout error mitigation or not. | True\n", - "`num_readout_calibration_shots` | int | The number of shots to be used for readout error mitigation. | 10000\n", - "`default_precision` | float | The default precision to be used for the PUBs for which the precision is not specified. |0.02\n", - "`seed` | int or `None` | Set the seed of the random number generator for reproducibility. If `None`, don't set the seed. | None" + "#### `tem_max_bond_dimension` \n", + "\n", + "The maximum bond dimension to be used for the tensor networks.\n", + "\n", + "\n", + "#### `tem_compression_cutoff`\n", + "\n", + "The cutoff value to be used for the tensor networks.\n", + "\n", + "\n", + "#### `compute_shadows_bias_from_observable`\n", + "\n", + "A boolean flag indicating whether the bias for the classical shadows measurement protocol should be tailored to the PUB observable or not. If False, the classical shadows protocol (equal probability of measuring Z, X, Y) will be used.\n", + "\n", + "\n", + "#### `shadows_bias`\n", + "\n", + "The bias to be used for the randomized classical shadows measurement protocol, a 1d or 2d array of size 3 or shape (`num_qubits`, 3) respectively. Order is ZXY.\n", + "\n", + "\n", + "#### `max_execution_time`\n", + "\n", + "The maximum execution time on the QPU in seconds. If the runtime exceeds this value, the job will be canceled. If `None`, a default limit set by Qiskit Runtime will apply.\n", + "\n", + "\n", + "#### `num_randomizations`\n", + "\n", + "The number of randomizations to be used for noise learning and gate twirling.\n", + "\n", + "\n", + "#### `max_layers_to_learn`\n", + "\n", + "The maximum number of unique layers to learn.\n", + "\n", + "\n", + "#### `mitigate_readout_error`\n", + "\n", + "A boolean flag indicating whether to perform readout error mitigation or not.\n", + "\n", + "\n", + "#### `num_readout_calibration_shots`\n", + "\n", + " The number of shots to be used for readout error mitigation.\n", + " \n", + "\n", + "#### `default_precision`\n", + "\n", + "The default precision to be used for the PUBs for which the precision is not specified.\n", + "\n", + "\n", + "#### `seed`\n", + "\n", + "Set the seed of the random number generator for reproducibility. If `None`, don't set the seed.\n", + "" ] }, { @@ -331,10 +387,23 @@ "A Qiskit [PrimitiveResults](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) containing the TEM-mitigated result. The result for each PUB is returned as a [PubResult](/docs/api/qiskit/qiskit.primitives.PubResult) containing the following fields:\n", "\n", "\n", - "Name |Type | Description\n", - "-- | -- | --\n", - "data | DataBin | A Qiskit [DataBin](/docs/api/qiskit/qiskit.primitives.DataBin) containing the TEM mitigated observable and its standard error. The DataBin has the following fields: \n", - "metadata | dict | A dictionary containing additional results. The dictionary contains the following keys: " + "### `data`\n", + "\n", + "A Qiskit [DataBin](/docs/api/qiskit/qiskit.primitives.DataBin) containing the TEM mitigated observable and its standard error. The DataBin has the following fields:\n", + "- `evs`: The TEM-mitigated observable value.\n", + "- `stds`: The standard error of the TEM-mitigated observable.\n", + "\n", + "\n", + "### `metadata`\n", + "\n", + "A dictionary containing additional results. The dictionary contains the following keys:\n", + "- `\"evs_non_mitigated\"`: The observable value without error mitigation.\n", + "- `\"stds_non_mitigated\"`: The standard error of the result without error mitigation.\n", + "- `\"evs_mitigated_no_readout_mitigation\"`: The observable value with error mitigation but without readout error mitigation.\n", + "- `\"stds_mitigated_no_readout_mitigation\"`: The standard error of the result with error mitigation but without readout error mitigation.\n", + "- `\"evs_non_mitigated_with_readout_mitigation\"`: The observable value without error mitigation but with readout error mitigation.\n", + "- `\"stds_non_mitigated_with_readout_mitigation\"`: The standard error of the result without error mitigation but with readout error mitigation.\n", + "" ] }, { @@ -342,9 +411,9 @@ "id": "fd045ee6", "metadata": {}, "source": [ - "## Fetching error messages\n", + "## Fetch error messages\n", "\n", - "If your workload status is ERROR, use job.result() to fetch the error message as follows:" + "If your workload status is ERROR, use `job.result()` to fetch the error message as follows:" ] }, { @@ -390,10 +459,11 @@ "\n", "\n", "\n", - "- [Request access to Algorithmiq Tensor-network error mitigation](https://quantum.cloud.ibm.com/functions?id=algorithmiq-tem)\n", - "- Review [Filippov, S., et al. (2023). Scalable tensor-network error mitigation for near-term quantum computing. arXiv preprint arXiv:2307.11740.](https://arxiv.org/abs/2307.11740)\n", - "- Review [Filippov, S., et al. (2024). Scalability of quantum error mitigation techniques: from utility to advantage. arXiv preprint arXiv:2403.13542.](https://arxiv.org/abs/2403.13542)\n", - "- Review [Fischer, E. F., et al. (2024). Dynamical simulations of many-body quantum chaos on a quantum computer. arXiv preprint arXiv:2411.00765.](https://arxiv.org/abs/2411.00765)\n", + "- [Request access to Algorithmiq Tensor-network error mitigation.](https://quantum.cloud.ibm.com/functions?id=algorithmiq-tem)\n", + "- Review the following papers:\n", + " - [Filippov, S., et al. (2023). Scalable tensor-network error mitigation for near-term quantum computing. arXiv preprint arXiv:2307.11740.](https://arxiv.org/abs/2307.11740)\n", + " - [Filippov, S., et al. (2024). Scalability of quantum error mitigation techniques: from utility to advantage. arXiv preprint arXiv:2403.13542.](https://arxiv.org/abs/2403.13542)\n", + " - [Fischer, E. F., et al. (2024). Dynamical simulations of many-body quantum chaos on a quantum computer. arXiv preprint arXiv:2411.00765.](https://arxiv.org/abs/2411.00765)\n", "\n", "" ] diff --git a/docs/guides/ibm-circuit-function.ipynb b/docs/guides/ibm-circuit-function.ipynb index f92930fcb33..2495630121a 100644 --- a/docs/guides/ibm-circuit-function.ipynb +++ b/docs/guides/ibm-circuit-function.ipynb @@ -203,12 +203,33 @@ "id": "19eafc4c", "metadata": {}, "source": [ - "| Name | Type | Description | Required | Default | Example |\n", - "|-----------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------------------------------------------------------|------------------------------------------|\n", - "| backend_name | str | Name of the backend to make the query. | Yes | N/A | `ibm_fez` |\n", - "| pubs | Iterable[EstimatorPubLike] | An iterable of abstract PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/docs/guides/primitive-input-output#overview-of-pubs) for more information. The circuits can be abstract (non-ISA). | Yes | N/A | (circuit, observables, parameter_values) |\n", - "| options | dict | Input options. See the **Options** section for more details. | No | See the **Options** section for details. | `{\"optimization_level\": 3}` |\n", - "| instance | str | The cloud resource name of the instance to use in that format. | No | One is randomly picked if your account has access to multiple instances. | `CRN` |" + "### `backend_name`\n", + "\n", + "Name of the backend to make the query.\n", + "- Required: Yes\n", + "- Example: `ibm_fez`\n", + "\n", + "\n", + "### `pubs`\n", + "\n", + "An iterable of abstract PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/docs/guides/primitive-input-output#overview-of-pubs) for more information. The circuits can be abstract (non-ISA).\n", + "- Required: Yes\n", + "- Example: `(circuit, observables, parameter_values)`\n", + "\n", + "\n", + "### `options`\n", + "\n", + "Input options. See the [Options](#options) section for more details.\n", + "- Required:No\n", + "- Example: `{\"optimization_level\": 3}`\n", + "\n", + "\n", + "### `instance`\n", + "\n", + "The cloud resource name of the instance to use in that format.\n", + "- Required: No\n", + "- Example: `CRN`\n", + "" ] }, { @@ -231,13 +252,13 @@ "IBM Circuit function also supports `mitigation_level`. The mitigation level specifies how much error suppression and mitigation to apply to the job. Higher levels generate more accurate results, at the expense of longer processing times. The degree of error reduction depends on the method applied. The mitigation level abstracts the detailed choice of error mitigation and suppression methods to allow users to reason about the cost/accuracy trade-off appropriate to their application. The following table shows the corresponding methods for each level.\n", "\n", "\n", - "While the names are similar, `mitigation_level` applies different techniques than the ones used by Estimator’s `resilience_level`.\n", + "While the names are similar, `mitigation_level` applies different techniques than the ones used by Estimator's `resilience_level`.\n", "\n", "\n", "Similar to ``resilience_level`` in Qiskit Runtime Estimator, ``mitigation_level`` specifies a base set of curated options. Any options you manually specify in addition to the mitigation level are applied on top of the base set of options defined by the mitigation level. Therefore, in principle, you could set the mitigation level to 1, but then turn off measurement mitigation, although this is not advised.\n", "\n", "| **Mitigation Level** | **Technique** |\n", - "|:-:|:-:|\n", + "|---|---|\n", "| 1 [Default] | Dynamical decoupling + measurement twirling + TREX |\n", "| 2 | Level 1 + gate twirling + ZNE via gate folding |\n", "| 3 | Level 1 + gate twirling + ZNE via PEA |\n", @@ -264,25 +285,106 @@ "source": [ "#### All available options\n", "\n", - "In addition to `mitigation_level`, the IBM Circuit function also provides a select number of advanced options that allow you to fine-tune the cost/accuracy trade-off. The following table shows all the available options:\n", - "\n", - "| Option | Sub-option | Sub-sub-option | Description | Choices | Default |\n", - "|-|-|-|-|-|-|\n", - "| default_precision | | | The default precision to use for any PUB or `run()`
call that does not specify one.
Each input PUB can specify its own precision. If the `run()` method is given a precision, then that value is used for all PUBs in the `run()` call that do not specify their own. | float > 0 | 0.015625 |\n", - "| max_execution_time | | | Maximum execution time in seconds, which is based
on QPU usage (not wall clock time). QPU usage is the
amount of time that the QPU is dedicated to processing your job. If a job exceeds this time limit, it is forcibly canceled. | Integer number of seconds in the range [1, 10800] | |\n", - "| mitigation_level | | | How much error suppression and mitigation to apply. Refer to the [Mitigation level](#mitigation-level) section for more information about the methods used at each level. | 1 / 2 / 3 | 1 |\n", - "| optimization_level | | | How much optimization to perform on the circuits. [Higher levels](/docs/guides/set-optimization) generate more optimized circuits, at the expense of longer transpilation time. | 1 / 2 / 3 | 2 |\n", - "| dynamical_decoupling | enable | | Whether to enable dynamical decoupling. Refer to [Error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques#dynamical-decoupling) for the explanation of the method. | True/False | True |\n", - "| | sequence_type | | Which dynamical decoupling sequence to use.
* `XX`: use the sequence `tau/2 - (+X) - tau - (+X) - tau/2`
* `XpXm`: use the sequence `tau/2 - (+X) - tau - (-X) - tau/2`
* `XY4`: use the sequence
`tau/2 - (+X) - tau - (+Y) - tau (-X) - tau - (-Y) - tau/2` | 'XX'/'XpXm'/'XY4' | 'XX' |\n", - "| twirling | enable_gates | | Whether to apply 2-qubit Clifford gate twirling. | True/False | False |\n", - "| | enable_measure | | Whether to enable twirling of measurements. | True/False | True |\n", - "| resilience | measure_mitigation | | Whether to enable TREX measurement error mitigation method. Refer to [Error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques#twirled-readout-error-extinction-trex) for the explanation of the method. | True/False | True |\n", - "| | zne_mitigation | | Whether to turn on Zero Noise Extrapolation error mitigation method. Refer to [Error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) for the explanation of the method. | True/False | False |\n", - "| | zne | amplifier | Which technique to use for amplifying noise. One of:
- `gate_folding` (default) uses 2-qubit gate folding to amplify noise. If the noise factor requires amplifying only a subset of the gates, then these gates are chosen randomly.

- `gate_folding_front` uses 2-qubit gate folding to amplify noise. If the noise factor requires amplifying only a subset of the gates, then these gates are selected from the front of the topologically ordered DAG circuit.

- `gate_folding_back` uses 2-qubit gate folding to amplify noise. If the noise factor requires amplifying only a subset of the gates, then these gates are selected from the back of the topologically ordered DAG circuit.

- `pea` uses a technique called Probabilistic error amplification (PEA) to amplify noise. Refer to [Error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques#probabilistic-error-amplification-pea) for the explanation of the method. | gate_folding / gate_folding_front / gate_folding_back / pea | gate_folding |\n", - "| | | noise_factors | Noise factors to use for noise amplification. | list of floats; each float >= 1 | (1, 1.5, 2) for PEA, and (1, 3, 5) otherwise. |\n", - "| | | extrapolator | Noise factors to evaluate the fit extrapolation models at. This option does not affect execution or model fitting in any way; it only determines the points at which the `extrapolator` objects are evaluated to be returned in the data fields called `evs_extrapolated` and `stds_extrapolated`. | one or more of `exponential`,`linear`, `double_exponential`,`polynomial_degree_(1 <= k <= 7)` | (`exponential`, `linear`) |\n", - "| | pec_mitigation | | Whether to turn on Probabilistic Error Cancellation error mitigation method. Refer to [Error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec) for the explanation of the method. | True/False | False |\n", - "| | pec | max_overhead | The maximum circuit sampling overhead allowed, or `None` for no maximum. | None/ integer >1 | 100 |\n", + "In addition to `mitigation_level`, the IBM Circuit function also provides a select number of advanced options that allow you to fine-tune the cost/accuracy trade-off.\n", + "\n", + "##### `default_precision`\n", + "\n", + "The default precision to use for any PUB or `run()` call that does not specify one. Each input PUB can specify its own precision. If the `run()` method is given a precision, then that value is used for all PUBs in the `run()` call that do not specify their own.\n", + "- Choices: `float > 0`\n", + "\n", + "\n", + "##### `max_execution_time`\n", + "\n", + "Maximum execution time in seconds, which is based on QPU usage (not wall clock time). QPU usage is the amount of time that the QPU is dedicated to processing your job. If a job exceeds this time limit, it is forcibly canceled.\n", + "- Choices: Integer number of seconds in the range `[1, 10800]`\n", + "\n", + "\n", + "##### `mitigation_level`\n", + "\n", + "How much error suppression and mitigation to apply. Refer to the [Mitigation level](#mitigation-level) section for more information about the methods used at each level.\n", + "- Choices: 1 / 2 / 3\n", + "\n", + "\n", + "##### `optimization_level`\n", + "\n", + "How much optimization to perform on the circuits. [Higher levels](/docs/guides/set-optimization) generate more optimized circuits, at the expense of longer transpilation time.\n", + "- Choices: 1 / 2 / 3\n", + "\n", + "\n", + " ##### `dynamical_decoupling` sub-option - `enable`\n", + "\n", + "Whether to enable dynamical decoupling. Refer to [Error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques#dynamical-decoupling) for the explanation of the method.\n", + "- Choices: True/False\n", + "\n", + "\n", + " ##### `dynamical_decoupling` sub-option - `sequence_type` \n", + "\n", + "Which dynamical decoupling sequence to use.\n", + " - `XX`: use the sequence `tau/2 - (+X) - tau - (+X) - tau/2`\n", + " - `XpXm`: use the sequence `tau/2 - (+X) - tau - (-X) - tau/2`\n", + " - `XY4`: use the sequence `tau/2 - (+X) - tau - (+Y) - tau (-X) - tau - (-Y) - tau/2`\n", + "- Choices: 'XX'/'XpXm'/'XY4'\n", + "\n", + "\n", + "##### `twirling` sub-option - `enable_gates`\n", + "\n", + "Whether to apply two-qubit Clifford gate twirling.\n", + "- Choices: True/False\n", + "\n", + "\n", + "##### `twirling` sub-option - `enable_measure`\n", + "\n", + "Whether to enable twirling of measurements.\n", + "- Choices: True/False\n", + "\n", + "\n", + "##### `resilience` sub-option - `measure_mitigation`\n", + "\n", + "Whether to enable TREX measurement error mitigation method. Refer to [Error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques#twirled-readout-error-extinction-trex) for the explanation of the method.\n", + "- Choices: True/False\n", + "\n", + "\n", + "##### `resilience` sub-option - `zne_mitigation`\n", + "\n", + "Whether to turn on Zero Noise Extrapolation error mitigation method. Refer to [Error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) for the explanation of the method.\n", + "- Choices: True/False\n", + "\n", + "\n", + "##### `resilience` sub-option - `zne` - sub-sub-option - `amplifier`\n", + "\n", + "Which technique to use for amplifying noise. One of:\n", + " - `gate_folding` (default) uses two-qubit gate folding to amplify noise. If the noise factor requires amplifying only a subset of the gates, then these gates are chosen randomly.\n", + " - `gate_folding_front` uses two-qubit gate folding to amplify noise. If the noise factor requires amplifying only a subset of the gates, then these gates are selected from the front of the topologically ordered DAG circuit.\n", + " - `gate_folding_back` uses two-qubit gate folding to amplify noise. If the noise factor requires amplifying only a subset of the gates, then these gates are selected from the back of the topologically ordered DAG circuit. \n", + " - `pea` uses a technique called Probabilistic error amplification (PEA) to amplify noise. Refer to [Error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques#probabilistic-error-amplification-pea) for the explanation of the method.\n", + "- Choices: `gate_folding` / `gate_folding_front` / `gate_folding_back` / `pea`\n", + "\n", + "\n", + "##### `resilience` sub-option - `zne` - sub-sub-option - `noise_factors`\n", + "\n", + "Noise factors to use for noise amplification.\n", + "- Choices: list of floats; each float >= 1\n", + "\n", + "\n", + "##### `resilience` sub-option - `zne` - sub-sub-option - `extrapolator`\n", + "\n", + "Noise factors at which to evaluate the fit extrapolation models. This option does not affect execution or model fitting in any way; it only determines the points at which the `extrapolator` objects are evaluated to be returned in the data fields called `evs_extrapolated` and `stds_extrapolated`.\n", + "- Choices: One or more of `exponential`,`linear`, `double_exponential`,`polynomial_degree_(1 <= k <= 7)`\n", + "\n", + "\n", + "##### `resilience` sub-option - `pec_mitigation`\n", + "\n", + "Whether to turn on Probabilistic Error Cancellation error mitigation method. Refer to [Error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec) for the explanation of the method.\n", + "- Choices: True/False\n", + "\n", + "\n", + "\n", + "##### `resilience` sub-option - `pec` - sub-sub-option -`max_overhead`\n", + "\n", + "The maximum circuit sampling overhead allowed, or `None` for no maximum.\n", + "- Choices: `None`/ integer > 1\n", + "\n", + "\n", "\n", "In the following example, setting the mitigation level to 1 initially turns off ZNE mitigation, but setting `zne_mitigation` to `True` overrides the relevant setup from `mitigation_level`." ] diff --git a/docs/guides/q-ctrl-optimization-solver.ipynb b/docs/guides/q-ctrl-optimization-solver.ipynb index a779a0934dc..cbc81e408b6 100644 --- a/docs/guides/q-ctrl-optimization-solver.ipynb +++ b/docs/guides/q-ctrl-optimization-solver.ipynb @@ -74,14 +74,43 @@ "metadata": {}, "source": [ "## Inputs and outputs\n", + "\n", "### Inputs\n", "\n", - "| Name | Type | Description | Required | Default | Example |\n", - "| --------- |-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | ---------- | ---------- |\n", - "| problem | `str` or `SparsePauliOp` | 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 and spin chain problem definitions, which are limited to \"maxcut\" or \"spin_chain\"; 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 | `\"ibm_fez\"` |\n", - "| options | `dict` | Input options, including the following: (Optional) `session_id`: `str`; default behavior creates a new Session | No | `None` | `{\"session_id\": \"cw2q70c79ws0008z6g4g\"}` |\n", + "#### `problem`\n", + "\n", + "\n", + "\n", + "One of the representations listed under \"Accepted problem formats\".\n", + "- Required: Yes\n", + "- Example: `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", + "\n", + "\n", + "#### `problem_type`\n", + "\n", + "\n", + " Name of the problem class; only used for graph and spin chain problem definitions, which are limited to `\"maxcut\"` or `\"spin_chain\"`; not required for arbitrary objective function problem definitions.\n", + " - Required: No\n", + " - Example: `\"maxcut\"`\n", + "\n", + "\n", + "#### `backend_name`\n", + "\n", + "\n", + " Name of the backend to use.\n", + " - Required: No\n", + " - Example: `\"ibm_fez\"`\n", + "\n", + "\n", + "\n", + "#### `options`\n", + "\n", + "\n", + " Input options, including the following: (Optional) `session_id`: `str`; default behavior creates a new Session.\n", + " - Required: No\n", + " - Example: `{\"session_id\": \"cw2q70c79ws0008z6g4g\"}`\n", + "\n", + "\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", @@ -127,28 +156,73 @@ "id": "22e843bf", "metadata": {}, "source": [ - "**Options:**\n", - "| Name | Type | Description | Default |\n", - "|--------|----------|-----------------------|---------------------|\n", - "| session_id | `str` | An existing Qiskit Runtime session ID | `\"cw4r3je6f0t010870y3g\"` |\n", - "| job_tags | `list[str]` | A list of job tags | `[]`|\n", + "#### Options\n", + "\n", + "##### `session_id`\n", + "\n", + "\n", + "An existing Qiskit Runtime session ID.\n", + "- Default: `None`\n", + "- Example: `\"cw4r3je6f0t010870y3g\"`\n", + "\n", + "\n", + "##### `job_tags`\n", + "\n", + "A list of job tags.\n", + "- Default: `None`\n", + "- Example: `[\"job_tag1\", \"job_tag2\"]`\n", + "\n", + "\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", - "\n", - "\n", - "**Result dictionary contents:**\n", - "| Name | Type | Description |\n", - "| --------- | ---------------- | -------------------------- |\n", - "| solution_bitstring_cost | `float` | The best minimum cost across all iterations |\n", - "| final_bitstring_distribution | `CountsDict` | The bitstring counts dictionary associated with the minimum cost |\n", - "| solution_bitstring | `str` | Bitstring with the best cost in the final distribution |\n", - "| iteration_count | `int` | The total number of QAOA iterations performed by the Solver |\n", - "| variables_to_bitstring_index_map | `float` | The mapping from the variables to the equivalent bit in the bitstring |\n", - "| best_parameters | `list[float]` | The optimized beta and gamma parameters across all iterations |\n", - "| warnings |`list[str]` | The warnings produced while compiling or running QAOA (defaults to None) |" + "\n", + "#### `result`\n", + "\n", + "\n", + "Solution and metadata listed under \"Result dictionary contents\".\n", + "\n", + "Example: `{'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", + "\n", + "##### `solution_bitstring_cost`\n", + "\n", + "\n", + "The best minimum cost across all iterations.\n", + "\n", + "\n", + "\n", + "##### `final_bitstring_distribution`\n", + "\n", + "\n", + "The bitstring counts dictionary associated with the minimum cost.\n", + "\n", + "\n", + "##### `solution_bitstring`\n", + "\n", + "Bitstring with the best cost in the final distribution.\n", + "\n", + "\n", + "##### `iteration_count`\n", + "\n", + "The total number of QAOA iterations performed by the Solver.\n", + "\n", + "\n", + "##### `variables_to_bitstring_index_map`\n", + "\n", + "The mapping from the variables to the equivalent bit in the bitstring.\n", + "\n", + "\n", + "##### `best_parameters`\n", + "\n", + "The optimized beta and gamma parameters across all iterations.\n", + "\n", + "\n", + "##### `warnings`\n", + "\n", + "The warnings produced while compiling or running QAOA.\n", + "" ] }, {