org.soulspace.qclojure.domain.circuit-transformation — org.soulspace/qclojure 0.1.0

Circuit transformation utilities for quantum backends.

This namespace provides functionality for adapting quantum circuits to specific hardware backends by transforming operations not supported by the backend into equivalent sequences of supported operations.

analyze-qubit-usage clj

(analyze-qubit-usage circuit)

Analyze which qubits are actually used in a circuit.

Parameters:

• circuit: Quantum circuit to analyze

Returns: Map containing:

• :used-qubits - Set of qubit IDs that are actually used
• :total-qubits - Total number of qubits declared in circuit
• :unused-qubits - Set of qubit IDs that are declared but unused
• :max-qubit-id - Highest qubit ID used
• :qubit-usage-efficiency - Ratio of used qubits to total qubits

analyze-topology-connectivity clj

(analyze-topology-connectivity topology)

Analyze the connectivity properties of a hardware topology.

Parameters:

• topology: Hardware topology as vector of vectors

Returns: Map containing topology analysis:

• :num-qubits - Total number of qubits
• :total-edges - Total number of edges (connections)
• :avg-degree - Average degree (connections per qubit)
• :max-degree - Maximum degree
• :min-degree - Minimum degree
• :diameter - Maximum shortest path distance between any two qubits
• :is-connected - Whether the topology is fully connected

calculate-distance-matrix clj

(calculate-distance-matrix topology)

Calculate shortest path distances between all pairs of qubits in topology.

Parameters:

• topology: Vector of vectors representing qubit connectivity

Returns: 2D vector where element [i][j] is the shortest distance from qubit i to qubit j

calculate-mapping-cost clj

(calculate-mapping-cost two-qubit-ops mapping distance-matrix)

Calculate the cost of a logical-to-physical qubit mapping.

Parameters:

• two-qubit-ops: Vector of two-qubit operations with :control and :target
• mapping: Map from logical qubit to physical qubit
• distance-matrix: 2D vector of distances between physical qubits

Returns: Total cost (sum of distances for all two-qubit operations)

compare-topologies clj

(compare-topologies circuit topologies)

Compare multiple hardware topologies for a given circuit.

Parameters:

• circuit: Quantum circuit to optimize
• topologies: Map of topology-name to topology

Returns: Vector of maps sorted by total cost, each containing:

• :topology-name - Name of the topology
• :total-cost - Total routing cost
• :swap-count - Number of SWAP operations needed
• :logical-to-physical - Optimal qubit mapping

compose-circuits clj

(compose-circuits circuit1 circuit2 & [options])

Compose two quantum circuits sequentially.

Creates a new circuit that applies the first circuit followed by the second. If the circuits have different numbers of qubits, the one with fewer qubits will be automatically extended to match the larger one.

With optional parameters, you can control how the circuits are composed:

• qubit-mapping: Function to map circuit2's qubit indices to the combined circuit
• offset: Simple integer offset for circuit2's qubits (shorthand for adding offset)
• control-qubits-only: Boolean flag to indicate circuit2 should only operate on the first n qubits of circuit1 where n is the number of qubits in circuit2

Parameters:

• circuit1: First quantum circuit to execute
• circuit2: Second quantum circuit to execute after the first
• options: (Optional) Map with composition options:
  • :qubit-mapping - Function mapping circuit2's qubit indices
  • :offset - Integer to add to circuit2's qubit indices
  • :control-qubits-only - Boolean indicating circuit2 operates on control qubits only

Returns: New quantum circuit containing all operations from circuit1 followed by all operations from circuit2

Examples: (compose-circuits (h-gate (create-circuit 1) 0) (x-gate (create-circuit 1) 0)) ;=> Circuit that applies H then X on qubit 0

(compose-circuits (h-gate (create-circuit 1) 0) (cnot-gate (create-circuit 2) 0 1)) ;=> 2-qubit circuit that applies H on qubit 0, then CNOT from qubit 0 to 1

;; With offset, apply second circuit starting at qubit 3 (compose-circuits (create-circuit 5) (h-gate (create-circuit 2) 0) {:offset 3}) ;=> 5-qubit circuit with H gate on qubit 3

create-grid-topology clj

(create-grid-topology rows cols)

Create a grid hardware topology with qubits arranged in a rectangular grid.

Parameters:

• rows: Number of rows in the grid
• cols: Number of columns in the grid

Returns: Vector of vectors representing adjacency list for grid topology

create-linear-topology clj

(create-linear-topology num-qubits)

Create a linear hardware topology where qubits are connected in a line.

Parameters:

• num-qubits: Number of qubits in the topology

Returns: Vector of vectors representing adjacency list for linear topology

create-ring-topology clj

(create-ring-topology num-qubits)

Create a ring hardware topology where qubits are connected in a circle.

Parameters:

• num-qubits: Number of qubits in the topology

Returns: Vector of vectors representing adjacency list for ring topology

create-star-topology clj

(create-star-topology num-qubits)

Create a star hardware topology with one central qubit connected to all others.

Parameters:

• num-qubits: Number of qubits in the topology

Returns: Vector of vectors representing adjacency list for star topology

extend-circuit clj

(extend-circuit circuit
                new-num-qubits
                &
                {:keys [qubit-mapping] :or {qubit-mapping identity}})

Extend a quantum circuit to support a larger number of qubits.

This function creates a new circuit with the specified number of qubits while preserving all the operations of the original circuit. The original circuit operations will apply to the same qubits as before.

With the optional qubit-mapping parameter, you can specify a function to map original qubit indices to new indices in the extended circuit.

Parameters:

• circuit: Original quantum circuit to extend
• new-num-qubits: New total number of qubits (must be >= original)
• qubit-mapping: (Optional) Function that maps original qubit indices to new indices

Returns: A new circuit with increased qubit count and remapped qubit operations if specified

Examples: (extend-circuit (h-gate (create-circuit 1) 0) 3) ;=> 3-qubit circuit with Hadamard gate on qubit 0

;; Shift all qubits by 2 positions
(extend-circuit (h-gate (create-circuit 1) 0) 3 #(+ % 2)) ;=> 3-qubit circuit with Hadamard gate on qubit 2

extract-two-qubit-operations clj

(extract-two-qubit-operations circuit)

Extract all two-qubit operations from a circuit.

Parameters:

• circuit: Quantum circuit to analyze

Returns: Vector of maps containing :control and :target qubit pairs

find-optimal-mapping clj

(find-optimal-mapping arg1 arg2 arg3)

Find an optimal mapping from logical qubits to physical qubits using a greedy approach.

Parameters:

• When called with 3 args [circuit topology distance-matrix]:
  • circuit: Quantum circuit to optimize
  • topology: Hardware topology
  • distance-matrix: Precomputed distance matrix
• When called with 3 args [two-qubit-ops num-physical-qubits distance-matrix] (legacy):
  • two-qubit-ops: Vector of two-qubit operations
  • num-physical-qubits: Number of physical qubits available
  • distance-matrix: Precomputed distance matrix

Returns: Map from logical qubit to physical qubit

find-shortest-path clj

(find-shortest-path topology start end)

Find shortest path between two qubits in the topology.

Parameters:

• topology: Hardware topology
• start: Starting qubit
• end: Ending qubit

Returns: Vector of qubits representing the path from start to end

generate-swap-operations clj

(generate-swap-operations path target-qubit)

Generate SWAP operations to route a qubit from start to end position.

Parameters:

• path: Vector of qubits representing routing path
• target-qubit: The logical qubit that needs to be moved

Returns: Vector of SWAP operation maps

get-topology-info clj

(get-topology-info topology)

(get-topology-info topology name)

Get human-readable information about a topology.

Parameters:

• topology: Hardware topology
• name: Optional name for the topology

Returns: String with topology information

get-transformation-summary clj

(get-transformation-summary transformation-result)

Get a human-readable summary of a circuit transformation.

Parameters:

• transformation-result: Result from transform-circuit

Returns: String with transformation summary

optimize clj

(optimize circuit supported-operations)

(optimize circuit supported-operations options)

Comprehensive circuit optimization for specific supported operations.

This function combines multiple optimization strategies:

1. Transform operations to supported equivalents
2. Optimize qubit usage to minimize qubit count
3. Optimize for hardware topology with SWAP insertion

Parameters:

• circuit: Quantum circuit to optimize
• supported-operations: Set of supported operations for optimization
• options: Optional map with optimization options: :optimize-qubits? - Whether to optimize qubit usage (default: true) :transform-operations? - Whether to transform unsupported operations (default: true) :optimize-topology? - Whether to optimize for hardware topology (default: false) :topology - Hardware topology for topology optimization (required if :optimize-topology? is true) :max-iterations - Maximum decomposition iterations (default: 100)

Returns: Map containing:

• :quantum-circuit - The fully optimized circuit
• :transformation-result - Result from operation transformation
• :qubit-optimization-result - Result from qubit optimization (if enabled)
• :topology-optimization-result - Result from topology optimization (if enabled)
• :optimization-summary - Human-readable summary of all optimizations

Example: (optimize my-circuit #{:h :x :z :cnot} {:optimize-topology? true :topology linear-topology}) ;=> {:quantum-circuit <optimized-circuit>, ; :transformation-result {...}, ; :qubit-optimization-result {...}, ; :topology-optimization-result {...}, ; :optimization-summary "..."}

optimize-for-topology clj

(optimize-for-topology circuit topology)

(optimize-for-topology circuit topology options)

Optimize a quantum circuit for a specific hardware topology.

This function performs topology-aware optimization by:

1. Finding an optimal mapping from logical to physical qubits
2. Inserting SWAP operations when needed for routing
3. Minimizing the total cost of the circuit on the given topology

Parameters:

• circuit: Quantum circuit to optimize
• topology: Hardware topology as vector of vectors (adjacency list)
• options: Optional map with optimization options: :insert-swaps? - Whether to insert SWAP operations for routing (default: true) :optimize-mapping? - Whether to optimize qubit mapping (default: true)

Returns: Map containing:

• :quantum-circuit - The topology-optimized circuit
• :logical-to-physical - Map from logical qubit to physical qubit
• :physical-to-logical - Map from physical qubit to logical qubit
• :swap-count - Number of SWAP operations inserted
• :total-cost - Total routing cost of the optimized circuit
• :topology-summary - Human-readable summary of topology optimization

Example: ;; Linear topology for 5 qubits: 0-1-2-3-4 (def linear-topology [[1] [0 2] [1 3] [2 4] [3]]) (optimize-for-topology my-circuit linear-topology) ;=> {:quantum-circuit <optimized-circuit>, :logical-to-physical {0 1, 1 2, 2 3}, ...}

optimize-qubit-usage clj

(optimize-qubit-usage circuit)

Optimize a circuit to use the minimum number of qubits.

This function compacts qubit IDs to eliminate gaps and unused qubits, reducing the total number of qubits required for the circuit.

Parameters:

• circuit: Quantum circuit to optimize

Returns: Map containing:

• :quantum-circuit - Circuit with optimized qubit usage
• :qubit-mapping - Map from old qubit IDs to new qubit IDs
• :qubits-saved - Number of qubits saved by optimization
• :original-qubits - Original number of qubits
• :optimized-qubits - Final number of qubits after optimization

Example: ;; Circuit using qubits [0, 2, 5] out of 6 total qubits ;; After optimization: uses qubits [0, 1, 2] out of 3 total qubits (optimize-qubit-usage circuit) ;=> {:quantum-circuit <optimized-circuit>, :qubit-mapping {0 0, 2 1, 5 2}, ; :qubits-saved 3, :original-qubits 6, :optimized-qubits 3}

transform-circuit clj

(transform-circuit circuit supported-operations)

(transform-circuit circuit supported-operations options)

Transform a quantum circuit to use only operations supported by a given backend.

This function takes a quantum circuit and the supported operations, and returns a new circuit where all operations have been decomposed into the supported operations.

Parameters:

• circuit: Quantum circuit to transform
• supported-operations: Set of operation types supported
• options: Optional map with transformation options: :max-iterations - Maximum number of decomposition iterations (default: 100) :transform-unsupported? - Whether to transform unsupported operations (default: true)

Returns: A map containing:

• :quantum-circuit - The transformed circuit
• :transformed-operation-count - Count of operations that were transformed
• :unsupported-operations - List of operation types that couldn't be transformed

Example: (transform-circuit my-circuit #{:h :x :cnot} {:max-iterations 50}) ;=> {:quantum-circuit <transformed-circuit>, :transformed-operation-count 3, :unsupported-operations []}

update-operation-params clj

(update-operation-params operation mapping-fn)

Update operation parameters based on a qubit mapping function.

This function handles all types of quantum operations (gates and measurements) and updates any qubit indices in their parameters based on the provided mapping function.

Parameters:

• operation: The quantum operation to update
• mapping-fn: Function that takes a qubit index and returns a new index

Returns: Updated operation with remapped qubit indices

validate-topology clj

(validate-topology topology)

Validate that a hardware topology is well-formed.

Parameters:

• topology: Vector of vectors representing qubit connectivity

Returns: Boolean indicating if topology is valid