docs

Author: J-C-Q

docs/Project.toml

@@ -3,4 +3,3 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 MonitoredQuantumCircuits = "d8bf802c-9929-44b5-8e59-9c739daaeb6f"
-OhMyREPL = "5fb14364-9ced-5910-84b2-373655c76a03"

docs/make.jl

@@ -20,7 +20,7 @@ makedocs(;
         "Home" => "index.md",
         "Getting started" => "getting_started.md",
         "Library" => [
-            "Geometries" => "library/lattices.md",
+            "Geometries" => "library/geometries.md",
             "Operations" => "library/operations.md",
             "Circuits" => "library/circuits.md",
             "Backends" => [
@@ -30,9 +30,8 @@ makedocs(;
             ]
         ],
         "Interfaces" => [
-            "Geometry" => "interfaces/add_lattice.md",
+            "Geometry" => "interfaces/add_geometry.md",
             "Operation" => "interfaces/add_operation.md",
-            "Circuit" => "interfaces/add_circuit.md",
             "Backend" => "interfaces/add_backend.md"
         ],
         "Modules" => [

docs/src/getting_started.md

@@ -1,50 +1,69 @@
 # Getting Started
 
-The framework consists of three main parts. First is the qubit geometry, which represents the underlying qubits structure. Second is the circuit, which holds information about the operations applied to the qubits in a given geometry. The last part is the execution of the circuit, which can happen on various backends.
-As always, load MonitoredQuantumCircuits.jl (after [installing](/index.md) it) using the `using` keyword for the following code snippets to work
+MonitoredQuantumCircuits.jl is structured around three core components: **qubit geometry**, **circuit construction**, and **circuit execution**. This guide provides a concise overview to help you begin using the framework effectively.
+
+Before proceeding, ensure that MonitoredQuantumCircuits.jl is [installed](/index.md) and loaded:
+
 ```julia
 using MonitoredQuantumCircuits
 ```
 
-## Choose a Geometry
-A `Geometry` is a representation of qubits and connections between them (i.e., a graph). In general, it is only possible to apply operations to multiple qubits if they are connected in the geometry. For more information see [Geometries](/library/lattices.md).
-To construct a geometry object, call a constructor, e.g.,
+## 1. Select a Geometry
+
+A `Geometry` defines the arrangement and connectivity of qubits, typically represented as a graph. Operations can only be applied to qubits that are connected within the chosen geometry. For further details, refer to the [Geometries](/library/geometries.md) documentation.
+
+To construct a geometry object, use one of the provided constructors. For example:
+
 ```julia
 geometry = HoneycombGeometry(Periodic, 12, 12)
 ```
 
-## Compose a Circuit
-A circuit stores the [Operations](/library/operations.md) being applied to the qubits in a lattice. For more information see [Circuits](/library/circuits.md).
-To construct a circuit object, call a constructor, e.g.,
+## 2. Construct a Circuit
+
+A circuit encapsulates the [operations](/library/operations.md) applied to the qubits within a given geometry. For more information, see [Circuits](/library/circuits.md).
+
+To create a circuit, you may use a predefined constructor:
+
 ```julia
 circuit = MeasurementOnlyKitaev(geometry, px, py, pz; depth=100)
 ```
-Or start an iterative construction by initializing an empty circuit
+
+Alternatively, you can build a circuit iteratively by initializing an empty circuit:
+
 ```julia
 circuit = Circuit(geometry)
 ```
-Now you could continue with the CLI and call `apply!` for different operations, or launch a [GUI](/modules/gui.md) (WIP) using 
+
+You may then use the command-line interface to apply operations, or launch the [Graphical User Interface](/modules/gui.md) (GUI, work in progress):
+
 ```julia
 GUI.CircuitComposer!(circuit)
 ```
-Once you are done creating the circuit, compile it for faster iteration
+
+Once your circuit is complete, compile it for improved performance:
+
 ```julia
 compiled_circuit = compile(circuit)
 ```
 
-## Execute
-To execute a quantum circuit, you first have to think about which [Backend](/library/backends.md) to use.
-For example a Clifford simulation using QuantumClifford.jl
+## 3. Execute the Circuit
+
+To execute a quantum circuit, first select an appropriate [backend](/library/backends.md). For example, to use a Clifford simulator via QuantumClifford.jl:
+
 ```julia
 simulator = QuantumClifford.TableauSimulator(nQubits(geometry))
 ```
-or a state vector simulation using cuQuantum via Qiskit-Aer
+
+Or, for state vector simulation using cuQuantum through Qiskit-Aer:
+
 ```julia
 simulator = Qiskit.GPUStateVectorSimulator()
 ```
-Then, you can execute the circuit using
+
+Execute the compiled circuit on the chosen backend:
+
 ```julia
-execute!(circuit::CompiledCircuit, backend::Backend)
+execute!(compiled_circuit, simulator)
 ```
-For more information see [Backends](/library/backends.md).
 
+For additional details, consult the [Backends](/library/backends.md) documentation.

docs/src/interfaces/add_circuit.md

@@ -0,0 +1,75 @@
+# Geometry Interface
+
+A **qubit geometry** represents the physical connectivity of qubits. Geometries are primarily intended to simplify the construction of circuits on various lattice structures, making it easier for users to implement and reason about their circuits. While geometries do not play a major role in the execution of circuits, they provide a convenient abstraction for circuit design.
+
+Several [pre-implemented geometries](/library/geometries.md) are available. However, if you wish to define a custom geometry, this guide outlines the recommended approach.
+
+## Defining a Geometry Type
+
+To implement your own geometry, define a new `struct`:
+
+```julia
+struct MyGeometry <: Geometry
+    graph::Graph
+end
+```
+
+along with any necessary constructors.
+
+## Recommended Methods
+
+While not strictly required, the following methods are considered best practice and will help you construct and interact with circuits on your custom geometry.
+
+### Indexing
+
+It is often useful to support multiple indexing schemes, such as a one-dimensional linear index and a two-dimensional grid index. To facilitate conversions between these schemes, consider implementing:
+
+```julia
+function to_linear(geometry::MyGeometry, (i, j)::NTuple{2,Int64})
+    # Convert a grid index to a linear index (integer)
+end
+
+function to_grid(geometry::MyGeometry, i::Int64)
+    # Convert a linear index to a grid index (tuple)
+end
+```
+
+### Neighbor Access
+
+In many cases, it is important to identify the nearest neighbors of a qubit, for example, to apply two-qubit gates. Ideally, connections can be distinguished by their type, ensuring that each qubit has at most one neighbor of a given type. To support this, implement a neighbor-access method:
+
+```julia
+function neighbor(geometry::MyGeometry, i::Int64; direction::Symbol)
+    # Return the neighbor of qubit `i` in the specified `direction`
+    # Should return a linear index (integer)
+end
+```
+
+### Visualization (Optional)
+
+For improved usability in the REPL, you may wish to provide a visualization method:
+
+```julia
+function visualize(io::IO, geometry::MyGeometry)
+    # Print a basic visualization of the geometry
+end
+```
+
+## Example: All-to-All Connectivity
+
+Below is an example implementation of a geometry with all-to-all connectivity:
+
+```julia
+using Graphs
+
+struct CompleteGeometry <: Geometry
+    graph::Graph
+    size::Int64
+    function CompleteGeometry(nQubits::Integer)
+        graph = complete_graph(nQubits)
+        new(graph, nQubits)
+    end
+end
+```
+
+By following these guidelines, you can create custom geometries that integrate seamlessly with the MonitoredQuantumCircuits.jl framework.

docs/src/interfaces/add_geometry.md

@@ -1,41 +1,47 @@
 # Operation Interface
-Adding custom operation to the MonitoredQuantumCircuits.jl framework is also possible. I can however be a bit tricky since you have to be familiar with every backend that should support your new operation. 
 
-## The basics
-Independent of which backend you would like to support the operation, you need to implement a few functions. Firstly, you need to implement a type `MyOperation<:Operation` or `MyOperation<:MeasurementOperation` if your operation includes measurements. Next, there are some basic interfaces that the circuit construction logic relies on. Thus, please implement the following methods for your operation:
+It is possible to add custom operations to the MonitoredQuantumCircuits.jl framework. However, this process may require familiarity with each backend that should support your new operation.
 
-- `nQubits(::MyOperation)`
-- `isClifford(::MyOperation)`
-- `connectionGraph(::MyOperation)`
-- `plotPositions(::MyOperation)`
-- `color(::MyOperation)`
-- `isAncilla(::MyOperation, qubit::Integer)`
+## Basic Requirements
 
-## For each backend
-For each backend that should support this operation, implement the `apply!` method.
+Regardless of the backend, you must implement a few essential methods. Begin by defining a new type, either as a subtype of `Operation` or `MeasurementOperation` (if your operation involves measurements). The circuit construction logic relies on the following interface methods, which must be implemented for your operation:
+
+- `nQubits(::MyOperation)`  
+  Specifies the number of qubits the operation acts upon.
+- `isClifford(::MyOperation)`  
+  Indicates whether the operation is a Clifford operation.
+
+## Backend Integration
+
+For each backend that should support your operation, you must implement the corresponding `apply!` method.
 
 ## Example
-Here is an example how one could implement the `Id` (identity) gate:
+
+Below is an example implementation of the `Id` (identity) gate:
+
 ```julia
-import MonitoredQuantumCircuits: Operation, nQubits, isClifford, connectionGraph, plotPositions, color, isAncilla
-import MonitoredQuantumCircuits: Graphs
-import MonitoredQuantumCircuits: Qiskit
-import MonitoredQuantumCircuits: QuantumClifford
-import MonitoredQuantumCircuits: apply!
+import MonitoredQuantumCircuits: Operation, nQubits, isClifford
+import MonitoredQuantumCircuits: Qiskit, QuantumClifford, apply!
+
 struct Id <: Operation end
 
 nQubits(::Id) = 1
 isClifford(::Id) = true
-connectionGraph(::Id) = Graphs.path_graph(1)
-plotPositions(::Id) = [(0.0,0.0)]
-color(::Id) = "#FFFFFF"
-isAncilla(::Id, ::Integer) = false
 
-function apply!(qc::Qiskit.QuantumCircuit, ::Id, pos::Integer)
-    qc.id(pos - 1)
+# Qiskit backend implementation
+function apply!(qc::Qiskit.Circuit, ::Id, p, ::Integer)
+    qc.id(p[1] - 1)
 end
-function apply!(qc::QuantumClifford.QC.Register, ::Id, pos::Integer)
-    QuantumClifford.QC.apply!(qc, QuantumClifford.QC.sId1(p))
+
+# QuantumClifford backend implementation
+function apply!(
+    register::QuantumClifford.QC.Register,
+    ::QuantumClifford.TableauSimulator,
+    ::Id,
+    p
+)
+    QuantumClifford.QC.apply!(register, QuantumClifford.QC.sId1(p[1]))
 end
+```
 
-```
+By following this approach, you can ensure that your custom operation integrates seamlessly with the MonitoredQuantumCircuits.jl framework and is supported across the desired backends.

docs/src/interfaces/add_lattice.md

@@ -1,14 +1,35 @@
-Currently, there are the following backends:
-
-- Quantum computer
-    - `IBMBackend(name::String)`
-- Simulator
-    - Qiskit Aer
-        - `StateVectorSimulator()`
-        - `GPUStateVectorSimulator()`
-        - `CliffordSimulator()`
-        - `GPUTensorNetworkSimulator()`
-    - QuantumClifford
-        - `TableauSimulator()`
-        - `PauliFrameSimulator()`
-        - `GPUPauliFrameSimulator()`
+## Backends
+
+```@meta
+CurrentModule = MonitoredQuantumCircuits
+```
+
+A **backend** is a computational engine responsible for executing quantum circuits. Backends may represent either actual quantum hardware or classical simulators. The backend executes the compiled circuit and returns the results for further analysis.
+
+MonitoredQuantumCircuits.jl provides a range of built-in backends, encompassing both quantum computers and simulators. If you wish to integrate a custom backend, please refer to the [backend interface](/interfaces/add_backend.md) documentation.
+
+### Available Backends
+
+- **Quantum Computer**
+    - `IBMBackend`
+
+- **Simulators**
+    - **Qiskit Aer**
+        - `StateVectorSimulator`
+        - `GPUStateVectorSimulator`
+        - `CliffordSimulator`
+        - `GPUTensorNetworkSimulator`
+    - **QuantumClifford**
+        - `TableauSimulator`
+        - `PauliFrameSimulator`
+        - `GPUPauliFrameSimulator`
+
+### Selecting a Backend
+
+Backends are organized into modules according to their origin. For example, backends provided by [Qiskit](/library/qiskit.md) reside in the `Qiskit` module, while those from [QuantumClifford](/library/quantum_clifford.md) are found in the `QuantumClifford` module. To instantiate a backend, prefix the constructor with the appropriate module name. For example, to create a state vector simulator using Qiskit:
+
+```julia
+backend = Qiskit.StateVectorSimulator()
+```
+
+For further details on backend capabilities and usage, consult the respective module documentation.