Merge pull request #194 from BQSKit/pre-built-model-example

Pre built model example

bqskit/compiler/compile.py

@@ -322,6 +322,15 @@ def compile(
         >>> model = MachineModel(circuit.num_qudits, gate_set=target_gate_set)
         >>> compiled_circuit = compile(circuit, model, optimization_level=2)
 
+        You can also use pre-built models from the :obj:`~bqskit.ext` package
+        for common hardware. For example, to compile to the H1-1 machine
+        from Quantinuum:
+
+        >>> from bqskit import compile, Circuit
+        >>> from bqskit.ext import H1_1Model
+        >>> circuit = Circuit.from_file('input.qasm')
+        >>> compiled_circuit = compile(circuit, H1_1Model)
+
     Raises:
         ValueError: If the input is an empty iterable.
 

bqskit/compiler/machine.py

@@ -50,8 +50,8 @@ def __init__(
             ValueError: If `num_qudits` is nonpositive.
 
         Note:
-            Pre-built models for many active QPUs exist in the `bqskit.ext`
-            package.
+            Pre-built models for many active QPUs exist in the
+            :obj:`~bqskit.ext` package.
         """
 
         if not is_integer(num_qudits):

bqskit/ext/__init__.py

@@ -6,7 +6,50 @@
 .. currentmodule:: bqskit.ext
 
 This subpackage provides integrations with other popular frameworks
-and pre-built MachineModels for many QPUs.
+and pre-built MachineModels for many QPUs. For some, you will need to
+manually install the dependencies. For example, to use the Pytket translators
+you will need to install the `pytket` package.
+
+.. rubric:: Pre-Built Machine Models
+
+.. autosummary::
+    :toctree: autogen
+    :recursive:
+
+    Aspen11Model
+    AspenM2Model
+    H1_1Model
+    H1_2Model
+    Sycamore23Model
+    SycamoreModel
+    model_from_backend
+
+.. rubric:: Translators
+
+.. autosummary::
+    :toctree: autogen
+    :recursive:
+
+    bqskit_to_cirq
+    cirq_to_bqskit
+    bqskit_to_pytket
+    pytket_to_bqskit
+    bqskit_to_qiskit
+    qiskit_to_bqskit
+    bqskit_to_qutip
+    qutip_to_bqskit
+
+.. rubric:: SupermarQ Metrics
+
+.. autosummary::
+    :toctree: autogen
+    :recursive:
+
+    supermarq_program_communication
+    supermarq_critical_depth
+    supermarq_entanglement_ratio
+    supermarq_parallelism
+    supermarq_liveness
 """
 from __future__ import annotations
 

docs/index.rst

@@ -39,3 +39,4 @@ our `tutorial series. <https://github.com/BQSKit/bqskit-tutorial/>`_
    source/utils
    source/exec
    source/runtime
+   source/ext

docs/source/ext.rst

@@ -0,0 +1,4 @@
+.. automodule:: bqskit.ext
+   :no-members:
+   :no-inherited-members:
+   :no-special-members: