Add documentation sections about Qiskit transpile service and AI Transpile passes (#459)

This PR adds two new sections under the `/transpile` page:
- A description of the new Qiskit transpile service and how to use it
- A description of the new AI transpiler passes and how to use them


This is a preliminary description of these services and features that
will be launched in the next IBM Quantum Summit. In the next weeks we
will improve the documentation with more contents and examples.

PR and contents co-authored by @d-kremer and @victor-villar.

---------

Co-authored-by: David Kremer <david.kremer@ibm.com>
Co-authored-by: ABBY CROSS <across@us.ibm.com>
Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com>
Co-authored-by: Abby Mitchell <23662430+javabster@users.noreply.github.com>

cSpell.json

@@ -129,6 +129,7 @@
     "resynthesized",
     "Roetteler",
     "Rueschlikon",
+    "satisfiability",
     "schedulable",
     "Shaohan",
     "Shaydulin",

docs/start/index.mdx

@@ -22,7 +22,7 @@ Already know what you’re looking for?
 
 - [Build](../build): Design and develop quantum circuits with primitives and advanced methods like dynamic circuits and mid-circuit measurements. You can also find our circuit library here.
 
-- [Transpile](../transpile): Compile locally to optimize your circuits to run efficiently on hardware, with varying degrees of error awareness.
+- [Transpile](../transpile): Compile to optimize your circuits to run efficiently on hardware, with varying degrees of error awareness.
 
 - [Verify](../verify): Validate and evaluate your quantum circuits.
 

docs/transpile/_toc.json

@@ -42,6 +42,19 @@
           "url": "/transpile/common-parameters"
         }
       ]
+    },
+    {
+      "title": "Qiskit transpiler service",
+      "children":[
+        {
+          "title": "Transpile circuits remotely with the Qiskit transpiler service",
+          "url": "/transpile/qiskit-transpiler-service"
+        },
+        {
+          "title": "AI transpiler passes",
+          "url": "/transpile/ai-transpiler-passes"
+        }
+      ]
     }
   ]
 }

docs/transpile/ai-transpiler-passes.mdx

@@ -0,0 +1,52 @@
+---
+title: AI transpiler passes
+description: What are the AI transpiler passes and how to use them
+---
+
+# AI transpiler passes
+​
+The AI-powered transpiler passes are experimental passes that work as a drop-in replacement of "traditional" qiskit passes for some transpiling tasks. They often produce better results than existing heuristic algorithms (such as lower depth and CNOT count), but are also much faster than optimization algorithms such as Boolean satisfiability solvers. The AI transpiler passes run on the cloud and are available to IBM Quantum Premium Plan users.
+
+
+<Admonition type="note">
+    This is an experimental feature available only to the IBM Quantum Premium Plan.
+    The AI-powered transpiler passes are in alpha release status, subject to change.
+</Admonition>
+
+The following passes are currently available:
+
+**Routing passes**
+ - `AIRouting`: Layout selection and circuit routing
+
+The following passes will be available in Q1 2024.
+
+**Circuit synthesis passes**
+ - `AICliffordSynthesis`: Clifford circuit synthesis
+ - `AILinearFunctionSynthesis`: Linear function circuit synthesis
+ - `AIPermutationSynthesis`: Permutation circuit synthesis
+
+To use the AI transpiler passes through our cloud services, install the `qiskit-transpiler-service` package (see instructions [here](qiskit-transpiler-service#install-transpiler-service)).
+
+## AI routing pass
+
+The `AIRouting` pass acts both as a layout stage and a routing stage. It can be used within a `PassManager` as follows:
+
+```python
+from qiskit.transpiler import PassManager
+from qiskit_transpiler_service.ai.routing import AIRouting
+from qiskit.circuit.library import EfficientSU2
+
+ai_passmanager = PassManager([
+  AIRouting(target="ibm_sherbrooke", optimization_level=2, layout_mode="optimize")
+])
+
+circuit = EfficientSU2(120, entanglement="circular", reps=1).decompose()
+
+transpiled_circuit = ai_passmanager.run(circuit)
+```
+
+Here, the `target` determines which backend to route for, the `optimization_level` (1, 2, or 3) determines the computational effort to spend in the process (higher usually gives better results but takes longer), and the `layout_mode` specifies how to handle the layout selection.
+The `layout_mode` includes the following options:
+- `keep`: This respects the layout set by the previous transpiler passes (or uses the trivial layout if not set). It is typically only used when the circuit must be run on specific qubits of the device. It often produces worse results because it has less room for optimization.
+- `improve`: This uses the layout set by the previous transpiler passes as a starting point. It is useful when you have a good initial guess for the layout; for example, for circuits that are built in a way that approximately follows the device's coupling map. It is also useful if you want to try other specific layout passes combined with the `AIRouting` pass.
+- `optimize`: This is the default mode. It works best for general circuits where you might not have good layout guesses. This mode ignores previous layout selections.

docs/transpile/index.mdx

@@ -7,7 +7,7 @@ description: Introduction to the transpiler
 
 # Introduction
 
-Transpilation is the process of rewriting a given input circuit to match the topology of a specific quantum device and optimize the circuit instructions for execution on present-day noisy quantum systems.  This documentation covers the tooling and workflows for local transpilation available to Qiskit users.  If you're using primitives and are only interested in the default transpilation options provided by the Qiskit Runtime service, read the [Configure runtime compilation for Qiskit Runtime](../run/configure-runtime-compilation) topic.
+Transpilation is the process of rewriting a given input circuit to match the topology of a specific quantum device, and optimize the circuit instructions for execution on noisy quantum systems.  This documentation covers the tooling and workflows for local transpilation available to all Qiskit users, as well as for the cloud-based [Qiskit transpiler service](qiskit-transpiler-service) available to Premium Plan users.  If you're using primitives and are only interested in the default transpilation options provided by the Qiskit Runtime service, read the [Configure runtime compilation for Qiskit Runtime](../run/configure-runtime-compilation) topic.
 
 A central component of Qiskit, the transpiler is designed for modularity and extensibility. Its central goal is to write new circuit transformations (known as transpiler **passes**), and combine them with other existing passes, greatly reducing the depth and complexity of quantum circuits.  Which passes are chained together and in which order has a major effect on the final outcome. This pipeline is determined by the [`PassManager`](/api/qiskit/qiskit.transpiler.PassManager) and [`StagedPassManager`](/api/qiskit/qiskit.transpiler.StagedPassManager) objects.  The `StagedPassManager` orchestrates the execution of one or more `PassManagers` and determines the order in which they are executed, while the `PassManager` object is merely a collection of one or more passes.  Think of the `StagedPassManager` as the conductor in an orchestra, the `PassManagers` as the different instrument sections, and the `Pass`es as the individual musicians.  In this way, you can compose hardware-efficient quantum circuits that let you execute utility-scale work while keeping noise manageable.
 

docs/transpile/qiskit-transpiler-service.mdx

@@ -0,0 +1,72 @@
+---
+title: Transpile circuits remotely with the Qiskit transpiler service
+description: What is the Qiskit transpiler service and how to use it
+
+---
+# Transpile circuits remotely with the Qiskit transpiler service
+
+The Qiskit transpiler service provides transpilation capabilities on the cloud. In addition to the local Qiskit transpiler capabilities, your transpilation tasks can benefit from both IBM Quantum Cloud resources and AI-powered transpiler passes.
+
+The Qiskit transpiler service offers a Python library to seamlessly integrate this service and its capabilities into your current Qiskit patterns and workflows.
+
+<Admonition type="note">
+    This experimental service is only available for IBM Quantum Premium Plan users.
+    The service is an alpha release, subject to change.
+</Admonition>
+
+<span id="install-transpiler-service"></span>
+## Install the qiskit-transpiler-service package
+
+To use the Qiskit transpiler service, install the `qiskit-transpiler-service` package:
+
+```sh
+pip install qiskit-transpiler-service
+```
+
+By default, the package tries to authenticate to IBM Quantum services with the defined Qiskit API token, and uses your token from the `QISKIT_IBM_TOKEN` environment variable or from the file `~/.qiskit/qiskit-ibm.json` (under the section `default-ibm-quantum`).
+
+## qiskit-transpiler-service transpile options
+
+- `target` (optional, str) - A backend name as it would be expected by QiskitRuntimeService (for example, `ibm_sherbrooke`). If this is set, the transpile method uses the layout from the specified backend for the transpilation operation. If any other option is set that impacts these settings, such as `coupling_map`, the `target` settings are overridden.
+- `coupling_map` (optional, List[List[int]]) - A valid coupling map list (for example, [[0,1],[1,2]]). If this is set, the transpile method uses this coupling map for the transpilation operation. If defined, it overrides any value specified for `target`.
+- `optimization_level` (int) - The potential optimization level to apply during the transpilation process. Valid values are [1,2,3], where 1 is the least optimization (and fastest), and 3 the most optimization (and most time-intensive).
+- `ai` (bool) - Whether to use AI capabilities during transpilation. The AI capabilities available can be for `AIRouting` transpiling passes or other AI synthesis methods. If this value is `True`, the service applies different AI-powered transpiling passes depending on the `optimization_level` requested.
+- `qiskit_transpile_options` (dict) - A Python dictionary object that can include any other option that is valid in the [Qiskit `transpile()` method](defaults-and-configuration-options). If the `qiskit_transpile_options` input includes `optimization_level`, it is discarded in favor of the `optimization_level` specified as parameter input. If the `qiskit_transpile_options` includes any option not recognized by the Qiskit `transpile()` method, the library raises an error.
+
+
+## Examples
+
+The following examples demonstrate how to transpile circuits using the Qiskit transpiler service with different parameters.
+
+1. Create a random circuit and call the Qiskit transpiler service to transpile the circuit with `ibm_cairo` as the `target`, 1 as the `optimization_level`, and not using AI during the transpilation.
+
+    ```python
+    from qiskit.circuit.random import random_circuit
+    from qiskit_transpiler_service.transpiler_service import TranspilerService
+
+    random_circ = random_circuit(5, depth=3, seed=42).decompose(reps=3)
+
+    cloud_transpiler_service = TranspilerService(
+        target="ibm_cairo",
+        ai=False,
+        optimization_level=1,
+    )
+    transpiled_circuit = cloud_transpiler_service.run(random_circ)
+    ```
+
+1. Produce a similar random circuit and transpile it, requesting AI transpiling capabilities by setting the flag `ai` to `True`:
+
+    ```python
+    from qiskit.circuit.random import random_circuit
+    from qiskit_transpiler_service.transpiler_service import TranspilerService
+
+    random_circ = random_circuit(5, depth=3, seed=42).decompose(reps=3)
+
+    cloud_transpiler_service = TranspilerService(
+        target="ibm_cairo",
+        ai=True,
+        optimization_level=1,
+    )
+    transpiled_circuit = cloud_transpiler_service.run(random_circ)
+    ```
+​