1st public code

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @cbjuan @d-kremer @victor-villar @jesus-talavera-ibm @y4izus

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+<!--
+⚠️ If you do not respect this template, your pull request will be closed.
+⚠️ Your pull request title should be short detailed and understandable for all.
+⚠️ Also, please add a release note file using reno if the change needs to be
+  documented in the release notes.
+⚠️ If your pull request fixes an open issue, please link to the issue.
+
+- [ ] I have added the tests to cover my changes.
+- [ ] I have updated the documentation accordingly.
+- [ ] I have read the CONTRIBUTING document.
+-->
+
+### Summary
+
+
+
+### Details and comments

.gitignore

@@ -1,3 +1,8 @@
+# Sphinx
+
+docs/_build
+docs/stubs
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -20,6 +25,7 @@ parts/
 sdist/
 var/
 wheels/
+pip-wheel-metadata/
 share/python-wheels/
 *.egg-info/
 .installed.cfg
@@ -82,6 +88,18 @@ target/
 profile_default/
 ipython_config.py
 
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
 # pyenv
 #   For a library or package, you might want to ignore these files since the code is
 #   intended to run in multiple environments; otherwise, check them in:
@@ -121,7 +139,7 @@ celerybeat.pid
 
 # Environments
 .env
-.venv
+.venv*
 env/
 venv/
 ENV/
@@ -158,3 +176,4 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+plugin_src/service_credentials.json

CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+> **Types of changes**:
+>
+> - 🎉 **Added**: for new features.
+> - ✏️ **Changed**: for changes in existing functionality.
+> - 🐛 **Fixed**: for any bug fixes.
+> - ❌ **Removed**: for now removed features.
+> - 👾 **Security**: in case of vulnerabilities.
+> - ⚠️ **Deprecated**: for soon-to-be removed features.
+
+## [Unreleased]
+
+### 🎉 Added
+
+### ✏️ Changed
+
+### 🐛 Fixed
+
+### ❌ Removed
+
+### 👾 Security
+
+### ⚠️ Deprecated
+
+## [0.4.3] - 2024-06-07
+
+### ✏️ Changed
+
+- #85 Check existence of credentials and raise related exceptions instead of breaking
+
+## [0.4.2] - 2024-06-07
+
+### ✏️ Changed
+
+- #82 Relaxing pin of local dependencies
+
+### 🐛 Fixed
+
+- #83 Python 3.8 support. Back to specify types with typing
+- #81) Fixing some import errors for local modules
+
+## [0.4.1] - 2024-06-06
+
+### ✏️ Changed
+
+- #72 Refactoring the extension code
+- #69 Updating logs levels
+
+### 🐛 Fixed
+
+- #76 Rebuild layout in transpiled circuit
+- #71 Avoid barrier nodes in collection
+
+## [0.4.0] - 2024-05-28
+
+### 🎉 Added
+
+- #63 Request the synthesis of a list of circuits to the service.
+- #57 Adding docstrings for public documentation
+
+### ✏️ Changed
+
+- #67 Updating Clifford service URL.
+- #60 Replace use_ai by ai param in requests
+- #58 Move type hints in documentation.
+- #54 Set name to logger
+
+### 🐛 Fixed
+
+- #56 Adjust dependencies to be less strict and support minor version updates for qiskit & patch updates for qiskit-qasm3-import
+
+## [0.3.0] - 2024-02-29
+
+### ✏️ Changed
+
+- #36 Updating the plugin to use Qiskit 1.0 by default.
+
+### 🐛 Fixed
+
+- #38 Supporting measurements in circuits when transpiling using ai=true option.
+
+## [0.2.1] - 2024-02-22
+
+### 🎉 Added
+
+- #34 Add multithreading to synth requests. The requests  to the service for transpile and transpile now are done in parallel.
+
+### ✏️ Changed
+
+- #31 Updated collection passes. Now the passes could work up to N of qubits or with any block size of qubits
+
+## [0.2.0] - 2024-02-12
+
+### 🎉 Added
+
+- #28 Added support for synthesis and transpilation of Clifford, Permutation and Linear Function circuits. Using new URLs for the service.
+
+## [0.1.3] - 2023-12-11
+
+### 🐛 Fixed
+
+- #20 Fixing layout integration with Qiskit for the transpiler service
+- #18 Fixing hardcoded input to routing
+- #17 Fix bug in input and refactor
+
+## [0.1.2] - 2023-12-04
+
+- Publishing first version 0.1.2 for the IBM Quantum Summit.
+
+[Unreleased]: https://github.com/Qiskit/qiskit-transpiler-service/compare/0.4.3...main

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to qiskit_transpiler_service
+
+## Documentation
+
+**Write**
+
+We use Sphinx to compile docstrings into API documentation. The docstrings are written in reStructuredText. See our [Sphinx guide](https://qiskit.github.io/qiskit_sphinx_theme/sphinx_guide/index.html) for more information on writing Sphinx documentation.
+
+If you want an object to appear in the API documentation, you'll need to add it to the autosummary of the appropriate module-level docstring. For example, the [`qiskit_transpiler_service.ai`](./qiskit_transpiler_service/ai/__init__.py) module contains the following autosummary.
+
+```rst
+Classes
+=======
+.. autosummary::
+   :toctree: ../stubs/
+
+   AIRouting
+```
+
+Functions should be inlined in the module's file, e.g. `utils.py`:
+
+```rst
+.. currentmodule:: qiskit_transpiler_service.utils
+
+Functions
+=========
+
+.. autofunction:: create_random_linear_function
+.. autofunction:: get_metrics
+```
+
+When adding a new module, you'll also need to add a new file to `docs/apidocs`. The file name should match the module's name, e.g. `my_module.submodule.rst`. You'll probably find it easiest to copy one of the existing files. You also need to update `apidocs/index.rst` with the new file name.
+
+**Build**
+
+To build the documentation, install Sphinx and the `qiskit-sphinx-theme` (both included in `requirements-dev.txt`) then run the following command.
+
+```sh
+make docs
+```
+
+To view the documentation open `docs/_build/html/index.html`. Note that this is just a preview, the final documentation content is pulled into [Qiskit/documentation](https://github.com/qiskit/documentation) and re-rendered into <https://docs.quantum.ibm.com>.

Makefile

@@ -0,0 +1,6 @@
+# Minimal makefile for Sphinx documentation
+
+docs:
+	sphinx-build -j auto -b html docs docs/_build/html
+
+.PHONY: help Makefile docs

README.md

@@ -1 +1,146 @@
-# qiskit-transpiler-service
+# qiskit_transpiler_service
+
+A library to use [Qiskit Transpiler service](https://docs.quantum.ibm.com/transpile/qiskit-transpiler-service) and the [AI transpiler passes](https://docs.quantum.ibm.com/transpile/ai-transpiler-passes).
+
+**Note** The Qiskit transpiler service and the AI transpiler passes use different experimental services that are only available for IBM Quantum Premium Plan users. This library and the releated services are an alpha release, subject to change.
+
+## Installing the qiskit-transpiler-service
+
+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`).
+
+*Note*: This library requires Qiskit 1.0 by default.
+
+## How to use the library
+
+### Using the Qiskit Transpiler service
+
+The following examples demonstrate how to transpile circuits using the Qiskit transpiler service with different parameters.
+
+1. Create a circuit and call the Qiskit transpiler service to transpile the circuit with `ibm_sherbrooke` as the `backend_name`, 3 as the `optimization_level`, and not using AI during the transpilation.
+
+    ```python
+    from qiskit.circuit.library import EfficientSU2
+    from qiskit_transpiler_service.transpiler_service import TranspilerService
+
+    circuit = EfficientSU2(101, entanglement="circular", reps=1).decompose()
+
+    cloud_transpiler_service = TranspilerService(
+        backend_name="ibm_sherbrooke",
+        ai=False,
+        optimization_level=3,
+    )
+    transpiled_circuit = cloud_transpiler_service.run(circuit)
+    ```
+
+*Note:* you only can use `backend_name` devices you are allowed to with your IBM Quantum Account. Apart from the `backend_name`, the `TranspilerService` also allows `coupling_map` as parameter.
+
+2. Produce a similar circuit and transpile it, requesting AI transpiling capabilities by setting the flag `ai` to `True`:
+
+    ```python
+    from qiskit.circuit.library import EfficientSU2
+    from qiskit_transpiler_service.transpiler_service import TranspilerService
+
+    circuit = EfficientSU2(101, entanglement="circular", reps=1).decompose()
+
+    cloud_transpiler_service = TranspilerService(
+        backend_name="ibm_sherbrooke",
+        ai=True,
+        optimization_level=1,
+    )
+    transpiled_circuit = cloud_transpiler_service.run(circuit)
+    ```
+
+### Using the AIRouting pass manually
+
+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(backend_name="ibm_sherbrooke", optimization_level=2, layout_mode="optimize")
+])
+
+circuit = EfficientSU2(101, entanglement="circular", reps=1).decompose()
+
+transpiled_circuit = ai_passmanager.run(circuit)
+```
+
+Here, the `backend_name` 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.
+
+### Using the AI circuit synthesis passes
+
+The AI circuit synthesis passes allow you to optimize pieces of different circuit types ([Clifford](https://docs.quantum.ibm.com/api/qiskit/qiskit.quantum_info.Clifford), [Linear Function](https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.LinearFunction), [Permutation](https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.Permutation#permutation)) by re-synthesizing them. The typical way one would use the synthesis pass is the following:
+
+```python
+from qiskit.transpiler import PassManager
+
+from qiskit_transpiler_service.ai.routing import AIRouting
+from qiskit_transpiler_service.ai.synthesis import AILinearFunctionSynthesis
+from qiskit_transpiler_service.ai.collection import CollectLinearFunctions
+from qiskit.circuit.library import EfficientSU2
+
+ai_passmanager = PassManager([
+  AIRouting(backend_name="ibm_cairo", optimization_level=3, layout_mode="optimize"),  # Route circuit
+  CollectLinearFunctions(),  # Collect Linear Function blocks
+  AILinearFunctionSynthesis(backend_name="ibm_cairo")  # Re-synthesize Linear Function blocks
+])
+
+circuit = EfficientSU2(10, entanglement="full", reps=1).decompose()
+
+transpiled_circuit = ai_passmanager.run(circuit)
+```
+
+The synthesis respects the coupling map of the device: it can be run safely after other routing passes without "messing up" the circuit, so the overall circuit will still follow the device restrictions. By default, the synthesis will replace the original sub-circuit only if the synthesized sub-circuit improves the original (currently only checking `CNOT` count), but this can be forced to always replace the circuit by setting `replace_only_if_better=False`.
+
+The following synthesis passes are available from `qiskit_transpiler_service.ai.synthesis`:
+
+- *AICliffordSynthesis*: Synthesis for [Clifford](https://docs.quantum.ibm.com/api/qiskit/qiskit.quantum_info.Clifford) circuits (blocks of `H`, `S` and `CX` gates). Currently up to 9 qubit blocks.
+- *AILinearFunctionSynthesis*: Synthesis for [Linear Function](https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.LinearFunction) circuits (blocks of `CX` and `SWAP` gates). Currently up to 9 qubit blocks.
+- *AIPermutationSynthesis*: Synthesis for [Permutation](https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.Permutation#permutation) circuits (blocks of `SWAP` gates). Currently available for 65, 33, and 27 qubit blocks.
+
+We expect to gradually increase the size of the supported blocks.
+
+All passes use a thread pool to send several requests in parallel. By default it will use as max threads as number of cores plus four (default values for `ThreadPoolExecutor` python object). However, you can set your own value with the `max_threads` argument at pass instantation. For example, the following line will instantiate the `AILinearFunctionSynthesis` pass allowing it to use a maximum of 20 threads.
+
+```python
+AILinearFunctionSynthesis(backend_name="ibm_cairo", max_threads=20)  # Re-synthesize Linear Function blocks using 20 threads max
+```
+
+You can also set the environment variable `AI_TRANSPILER_MAX_THREADS` to the desired number of maximum threads, and all synthesis passes instantiated after that will use that value.
+
+For sub-circuit to be synthesized by the AI synthesis passes, it must lay on a connected subgraph of the coupling map (this can be ensured by just doing a routing pass previous to collecting the blocks, but this is not the only way to do it). The synthesis passes will automatically check if a the specific subgraph where the sub-circuit lays is supported, and if it is not supported it will raise a warning and just leave the original sub-circuit as it is.
+
+To complement the synthesis passes we also provide custom collection passes for Cliffords, Linear Functions and Permutations that can be imported from `qiskit_transpiler_service.ai.collection`:
+
+- *CollectCliffords*: Collects `Clifford` blocks as `Instruction` objects and stores the original sub-circuit to compare against it after synthesis.
+- *CollectLinearFunctions*: Collects blocks of `SWAP` and `CX` as `LinearFunction` objects and stores the original sub-circuit to compare against it after synthesis.
+- *CollectPermutations*: Collects blocks of `SWAP` circuits as `Permutations`.
+
+These custom collection passes limit the sizes of the collected sub-circuits so that they are supported by the AI synthesis passes, so it is recommended to use them after the routing passes and before the synthesis passes to get a better optimization overall.
+
+## Citation
+
+If you use any AI-powered feature from the Qiskit transpiler service in your research, use the following recommended citation:
+
+```
+@misc{2405.13196,
+Author = {David Kremer and Victor Villar and Hanhee Paik and Ivan Duran and Ismael Faro and Juan Cruz-Benito},
+Title = {Practical and efficient quantum circuit synthesis and transpiling with Reinforcement Learning},
+Year = {2024},
+Eprint = {arXiv:2405.13196},
+}
+```