Qumat

QuMat

class QuMat()

Unified interface for quantum circuit operations across multiple backends.

Provides a consistent API for creating and manipulating quantum circuits using different quantum computing backends (Qiskit, Cirq, Amazon Braket). Abstracts backend-specific details for gate operations, circuit execution, and state measurement.

Arguments:

• backend_config (dict): Configuration dictionary for the quantum backend. Must contain backend_name (str) and backend_options (dict). The backend_options should include simulator_type and shots.

__init__

def __init__(backend_config: Mapping[str, Any] | None) -> None

Create a QuMat instance with the specified backend configuration.

Arguments:

• backend_config (dict): Configuration dictionary containing backend name and options. Required keys:
• backend_name: Name of the backend (e.g., "qiskit", "cirq", "amazon_braket")
• backend_options: Dictionary with backend-specific options

Raises:

• ImportError: If the specified backend module cannot be imported.
• ValueError: If backend_config is not a dictionary.
• KeyError: If required configuration keys are missing.

create_empty_circuit

def create_empty_circuit(num_qubits: int | None = None) -> None

Create an empty quantum circuit with the specified number of qubits.

Must be called before applying any gates or executing operations.

Arguments:

• num_qubits (int | None, optional): Number of qubits in the circuit. If None, creates a circuit without pre-allocated qubits.

apply_not_gate

def apply_not_gate(qubit_index: int) -> None

Apply a NOT gate (Pauli-X gate) to the specified qubit.

Flips the qubit state from |0⟩ to |1⟩ or |1⟩ to |0⟩. Equivalent to the Pauli-X gate.

Arguments:

• qubit_index (int): Index of the qubit.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_hadamard_gate

def apply_hadamard_gate(qubit_index: int) -> None

Apply a Hadamard gate to the specified qubit.

Creates a superposition state, transforming |0⟩ to (|0⟩ + |1⟩)/√2 and |1⟩ to (|0⟩ - |1⟩)/√2.

Arguments:

• qubit_index (int): Index of the qubit.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_cnot_gate

def apply_cnot_gate(control_qubit_index: int, target_qubit_index: int) -> None

Apply a Controlled-NOT (CNOT) gate between two qubits.

Fundamental for entangling qubits. Flips the target qubit if and only if the control qubit is in the |1⟩ state.

Arguments:

• control_qubit_index (int): Index of the control qubit.
• target_qubit_index (int): Index of the target qubit.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_toffoli_gate

def apply_toffoli_gate(control_qubit_index1: int, control_qubit_index2: int,
                       target_qubit_index: int) -> None

Apply a Toffoli gate (CCX gate) to three qubits.

Acts as a quantum AND gate. Flips the target qubit if and only if both control qubits are in the |1⟩ state.

Arguments:

• control_qubit_index1 (int): Index of the first control qubit.
• control_qubit_index2 (int): Index of the second control qubit.
• target_qubit_index (int): Index of the target qubit.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_swap_gate

def apply_swap_gate(qubit_index1: int, qubit_index2: int) -> None

Swap the states of two qubits.

Arguments:

• qubit_index1 (int): Index of the first qubit.
• qubit_index2 (int): Index of the second qubit.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_cswap_gate

def apply_cswap_gate(control_qubit_index: int, target_qubit_index1: int,
                     target_qubit_index2: int) -> None

Apply a controlled-SWAP (Fredkin) gate.

Swaps the states of two target qubits if and only if the control qubit is in the |1⟩ state.

Arguments:

• control_qubit_index (int): Index of the control qubit.
• target_qubit_index1 (int): Index of the first target qubit.
• target_qubit_index2 (int): Index of the second target qubit.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_pauli_x_gate

def apply_pauli_x_gate(qubit_index: int) -> None

Apply a Pauli-X gate to the specified qubit.

Equivalent to the NOT gate. Flips the qubit state from |0⟩ to |1⟩ or |1⟩ to |0⟩.

Arguments:

• qubit_index (int): Index of the qubit.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_pauli_y_gate

def apply_pauli_y_gate(qubit_index: int) -> None

Apply a Pauli-Y gate to the specified qubit.

Rotates the qubit around the Y-axis of the Bloch sphere, affecting both phase and amplitude.

Arguments:

• qubit_index (int): Index of the qubit.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_pauli_z_gate

def apply_pauli_z_gate(qubit_index: int) -> None

Apply a Pauli-Z gate to the specified qubit.

Rotates the qubit around the Z-axis of the Bloch sphere, altering the phase without changing the amplitude.

Arguments:

• qubit_index (int): Index of the qubit.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_t_gate

def apply_t_gate(qubit_index: int) -> None

Apply a T-gate (π/8 gate) to the specified qubit.

Applies a relative pi/4 phase (multiplies the |1> state by e^{i*pi/4}). Essential for universal quantum computation when combined with Hadamard and CNOT gates.

Arguments:

• qubit_index (int): Index of the qubit.

Raises:

• RuntimeError: If the circuit has not been initialized.

execute_circuit

def execute_circuit(
        parameter_values: Mapping[str, float] | None = None) -> Any

Execute the quantum circuit and return the measurement results.

Runs the circuit on the configured backend. For parameterized circuits, provide parameter values to bind before execution.

Arguments:

• parameter_values (dict, optional): Dictionary mapping parameter names to numerical values. Binds these values to circuit parameters before execution.

Raises:

• RuntimeError: If the circuit has not been initialized.

Returns:

dict | list[dict]: Measurement results. Format depends on the backend:

• Qiskit/Braket: Dictionary with state strings as keys and counts as values
• Cirq: List of dictionaries with integer states as keys

bind_parameters

def bind_parameters(parameter_values: Mapping[str, float]) -> None

Bind numerical values to circuit parameters.

Assigns numerical values to symbolic parameters defined in parameterized gates.

Arguments:

• parameter_values (dict): Dictionary mapping parameter names to numerical values.

Raises:

• ValueError: If a parameter name is not found in the circuit's parameter list.

get_final_state_vector

def get_final_state_vector() -> Any

Return the final state vector of the quantum circuit.

The complete quantum state vector after circuit execution, representing the full quantum state of all qubits. For parameterized circuits, call bind_parameters() first to set parameter values.

Raises:

• RuntimeError: If the circuit has not been initialized.
• ValueError: If parameterized circuit has unbound parameters.

Returns:

numpy.ndarray: The final state vector as a numpy array.

draw_circuit

def draw_circuit() -> Any

Visualize the quantum circuit.

Generates a visual representation of the circuit. The output format depends on the backend implementation.

Raises:

• RuntimeError: If the circuit has not been initialized.

Returns:

str | object: Circuit visualization. The exact type depends on the backend.

draw

def draw() -> Any

Alias for draw_circuit() for convenience.

Provides a shorter method name that matches common quantum computing library conventions and documentation examples.

Raises:

• RuntimeError: If the circuit has not been initialized.

Returns:

str | object: Circuit visualization. The exact type depends on the backend.

apply_rx_gate

def apply_rx_gate(qubit_index: int, angle: float | str) -> None

Apply a rotation around the X-axis to the specified qubit.

Rotates the qubit by the given angle around the X-axis of the Bloch sphere. The angle can be a static value or a parameter name for parameterized circuits.

Arguments:

• qubit_index (int): Index of the qubit.
• angle (float | str): Rotation angle in radians. Can be a float or a string parameter name.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_ry_gate

def apply_ry_gate(qubit_index: int, angle: float | str) -> None

Apply a rotation around the Y-axis to the specified qubit.

Rotates the qubit by the given angle around the Y-axis of the Bloch sphere. The angle can be a static value or a parameter name for parameterized circuits.

Arguments:

• qubit_index (int): Index of the qubit.
• angle (float | str): Rotation angle in radians. Can be a float or a string parameter name.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_rz_gate

def apply_rz_gate(qubit_index: int, angle: float | str) -> None

Apply a rotation around the Z-axis to the specified qubit.

Rotates the qubit by the given angle around the Z-axis of the Bloch sphere. The angle can be a static value or a parameter name for parameterized circuits.

Arguments:

• qubit_index (int): Index of the qubit.
• angle (float | str): Rotation angle in radians. Can be a float or a string parameter name.

Raises:

• RuntimeError: If the circuit has not been initialized.

apply_u_gate

def apply_u_gate(qubit_index: int, theta: float, phi: float,
                 lambd: float) -> None

Apply a U gate (universal single-qubit gate) to the specified qubit.

A universal single-qubit gate parameterized by three angles (theta, phi, lambd) that can represent any single-qubit unitary operation.

Arguments:

• qubit_index (int): Index of the qubit.
• theta (float): First rotation angle in radians.
• phi (float): Second rotation angle in radians.
• lambd (float): Third rotation angle in radians.

Raises:

• RuntimeError: If the circuit has not been initialized.

swap_test

def swap_test(ancilla_qubit: int, qubit1: int, qubit2: int) -> None

Implement the swap test circuit for measuring overlap between two quantum states.

Measures the inner product between the states on qubit1 and qubit2. The probability of measuring the ancilla qubit in state |0⟩ is related to the overlap as: P(0) = (1 + |⟨ψ|φ⟩|²) / 2

Arguments:

• ancilla_qubit (int): Index of the ancilla qubit (should be initialized to |0⟩).
• qubit1 (int): Index of the first qubit containing state |ψ⟩.
• qubit2 (int): Index of the second qubit containing state |φ⟩.

Raises:

• RuntimeError: If the circuit has not been initialized.

measure_overlap

def measure_overlap(qubit1: int, qubit2: int, ancilla_qubit: int = 0) -> float

Measure the overlap (fidelity) between two quantum states using the swap test.

Creates a swap test circuit to calculate the similarity between the quantum states on qubit1 and qubit2. Returns the squared overlap |⟨ψ|φ⟩|², which represents the fidelity between the two states.

The swap test measures P(ancilla=0), related to overlap as: P(0) = (1 + |⟨ψ|φ⟩|²) / 2

For certain states (especially identical excited states), global phase effects may cause the ancilla to measure predominantly |1⟩ instead of |0⟩. This method handles both cases by taking the measurement probability closer to 1.

Arguments:

• qubit1 (int): Index of the first qubit containing state |ψ⟩.
• qubit2 (int): Index of the second qubit containing state |φ⟩.
• ancilla_qubit (int, optional): Index of the ancilla qubit. Default is 0. Should be initialized to |0⟩.

Raises:

• RuntimeError: If the circuit has not been initialized.

Returns:

float: The squared overlap |⟨ψ|φ⟩|² between the two states (fidelity), clamped to the range [0.0, 1.0].

calculate_prob_zero

def calculate_prob_zero(results: Any, ancilla_qubit: int) -> float

Calculate the probability of measuring the ancilla qubit in |0⟩ state.

Delegates to the backend-specific implementation. Different backends may use different qubit ordering conventions (little-endian vs big-endian).

Arguments:

• results (dict | list[dict]): Measurement results from execute_circuit(). Format depends on the backend.
• ancilla_qubit (int): Index of the ancilla qubit.

Returns:

float: Probability of measuring the ancilla qubit in |0⟩ state.