qumat

qumat.QuMat(backend_config)

class QuMat(backend_config):

Bases: object

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.

• Parameters: 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.

apply_cnot_gate

apply_cnot_gate(control_qubit_index, target_qubit_index)

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.

• Parameters:
  • 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_cswap_gate

apply_cswap_gate(control_qubit_index, target_qubit_index1, target_qubit_index2)

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.

• Parameters:
  • 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_hadamard_gate

apply_hadamard_gate(qubit_index)

Apply a Hadamard gate to the specified qubit.

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

• Parameters: qubit_index (int) – Index of the qubit.
• Raises: RuntimeError – If the circuit has not been initialized.

apply_not_gate

apply_not_gate(qubit_index)

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.

• Parameters: qubit_index (int) – Index of the qubit.
• Raises: RuntimeError – If the circuit has not been initialized.

apply_pauli_x_gate

apply_pauli_x_gate(qubit_index)

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⟩.

• Parameters: qubit_index (int) – Index of the qubit.
• Raises: RuntimeError – If the circuit has not been initialized.

apply_pauli_y_gate

apply_pauli_y_gate(qubit_index)

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.

• Parameters: qubit_index (int) – Index of the qubit.
• Raises: RuntimeError – If the circuit has not been initialized.

apply_pauli_z_gate

apply_pauli_z_gate(qubit_index)

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.

• Parameters: qubit_index (int) – Index of the qubit.
• Raises: RuntimeError – If the circuit has not been initialized.

apply_rx_gate

apply_rx_gate(qubit_index, angle)

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.

• Parameters:
  • 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

apply_ry_gate(qubit_index, angle)

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.

• Parameters:
  • 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

apply_rz_gate(qubit_index, angle)

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.

• Parameters:
  • 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_swap_gate

apply_swap_gate(qubit_index1, qubit_index2)

Swap the states of two qubits.

• Parameters:
  • 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_t_gate

apply_t_gate(qubit_index)

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.

• Parameters: qubit_index (int) – Index of the qubit.
• Raises: RuntimeError – If the circuit has not been initialized.

apply_toffoli_gate

apply_toffoli_gate(control_qubit_index1, control_qubit_index2, target_qubit_index)

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.

• Parameters:
  • 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_u_gate

apply_u_gate(qubit_index, theta, phi, lambd)

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.

• Parameters:
  • 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.

bind_parameters

bind_parameters(parameter_values)

Bind numerical values to circuit parameters.

Assigns numerical values to symbolic parameters defined in parameterized gates.

• Parameters: 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.

calculate_prob_zero

calculate_prob_zero(results, ancilla_qubit)

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).

• Parameters:
  • results (dict | list *[*dict ]) – Measurement results from execute_circuit(). Format depends on the backend.
  • ancilla_qubit (int) – Index of the ancilla qubit.
• Returns: Probability of measuring the ancilla qubit in |0⟩ state.
• Return type: float

create_empty_circuit

create_empty_circuit(num_qubits=None)

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

Must be called before applying any gates or executing operations.

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

draw

draw()

Alias for draw_circuit() for convenience.

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

• Returns: Circuit visualization. The exact type depends on the backend.
• Return type: str | object
• Raises: RuntimeError – If the circuit has not been initialized.

draw_circuit

draw_circuit()

Visualize the quantum circuit.

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

• Returns: Circuit visualization. The exact type depends on the backend.
• Return type: str | object
• Raises: RuntimeError – If the circuit has not been initialized.

execute_circuit

execute_circuit(parameter_values=None)

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.

• Parameters: parameter_values (dict , optional) – Dictionary mapping parameter names to numerical values. Binds these values to circuit parameters before execution.
• Returns: 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
• Return type: dict | list[dict]
• Raises: RuntimeError – If the circuit has not been initialized.

get_final_state_vector

get_final_state_vector()

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.

• Returns: The final state vector as a numpy array.
• Return type: numpy.ndarray
• Raises:
  • RuntimeError – If the circuit has not been initialized.
  • ValueError – If parameterized circuit has unbound parameters.

measure_overlap

measure_overlap(qubit1, qubit2, ancilla_qubit=0)

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.

• Parameters:
  • 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⟩.
• Returns: The squared overlap |⟨ψ|φ⟩|² between the two states (fidelity), clamped to the range [0.0, 1.0].
• Return type: float
• Raises: RuntimeError – If the circuit has not been initialized.

swap_test

swap_test(ancilla_qubit, qubit1, qubit2)

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

• Parameters:
  • 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.