quantune 0.0.4

This package is deprecated. Please use 'qumega'.

_Quantune - A Python Quantum Computing Framework_z

Quantune is an open-source Python library for simulating and visualizing quantum circuits. Designed for both educational and practical purposes, this library allows users to construct, execute, and analyze quantum circuits while providing intuitive visualizations and robust tools for quantum computation.

Features

• Flexible Simulation: Design and execute complex quantum circuits.
• Visualization Tools: Visualize quantum states using Q-Spheres, Bloch Spheres, state vector plots, and more.
• Educational Support: Comprehensive documentation and examples for learning quantum computing.

Installation You can install Quantune using pip:

pip install quantune

---

gates.py

Quantum Gates: The library provides a range of quantum gates for single and multi-qubit operations.

1. identity()
   • Description: Represents the identity gate (I), which leaves the quantum state unchanged.
   • Matrix:

$$ I = \begin{bmatrix} 1 & 0 \ 0 & 1 \end{bmatrix} $$

2. paulix()
   • Description: Pauli-X gate, equivalent to a NOT operation on the quantum state.
   • Matrix:

$$ X = \begin{bmatrix} 0 & 1 \ 1 & 0 \end{bmatrix} $$

3. pauliy()
   • Description: Pauli-Y gate rotates the qubit around the Y-axis on the Bloch sphere.
   • Matrix:

$$ Y = \begin{bmatrix} 0 & -i \ i & 0 \end{bmatrix} $$

4. pauliz()
   • Description: Pauli-Z gate flips the phase of the quantum state.
   • Matrix:

$$ Z = \begin{bmatrix} 1 & 0 \ 0 & -1 \end{bmatrix} $$

5. hadamard()
   • Description: Creates superposition by applying an equal-weighted transformation.
   • Matrix:

$$ H = \frac{1}{\sqrt{2}}\begin{bmatrix} 1 & 1 \ 1 & -1 \end{bmatrix} $$

6. phase(theta)
   • Description: Phase gate applies a phase shift of θ to the quantum state.
   • Matrix:

$$ P(\theta) = \begin{bmatrix} 1 & 0 \ 0 & e^{i\theta} \end{bmatrix} $$

7. s()
   • Description: S gate applies a π/2 phase shift.
   • Matrix:

$$ S = \begin{bmatrix} 1 & 0 \ 0 & i \end{bmatrix} $$

8. sdg()
   • Description: SDG gate applies a −π/2 phase shift (inverse of S gate).
   • Matrix:

$$ S^\dagger = \begin{bmatrix} 1 & 0 \ 0 & -i \end{bmatrix} $$

9. t()
   • Description: T gate applies a π/4 phase shift.
   • Matrix:

$$ T = \begin{bmatrix} 1 & 0 \ 0 & e^{i\pi/4} \end{bmatrix} $$

10. tdg()
    • Description: TDG gate applies a −π/4 phase shift (inverse of T gate).
    • Matrix:

$$ T^\dagger = \begin{bmatrix} 1 & 0 \ 0 & e^{-i\pi/4} \end{bmatrix} $$

11. rz(theta)
    • Description: Rotates the qubit around the Z-axis by an angle θ.
    • Matrix:

$$ RZ(\theta) = \begin{bmatrix} e^{-i\theta/2} & 0 \ 0 & e^{i\theta/2} \end{bmatrix} $$

12. rx(theta)
    • Description: Rotates the qubit around the X-axis by an angle θ.
    • Matrix:

$$ RX(\theta) = \begin{bmatrix} \cos(\theta/2) & -i\sin(\theta/2) \ -i\sin(\theta/2) & \cos(\theta/2) \end{bmatrix} $$

13. ry(theta)
    • Description: Rotates the qubit around the Y-axis by an angle θ.
    • Matrix:

$$ RY(\theta) = \begin{bmatrix} \cos(\theta/2) & -\sin(\theta/2) \ \sin(\theta/2) & \cos(\theta/2) \end{bmatrix} $$

14. sx()
    • Description: Square-root of the Pauli-X gate.
    • Matrix:

$$ SX = \frac{1}{2}\begin{bmatrix} 1+i & 1-i \ 1-i & 1+i \end{bmatrix} $$

15. sxdg()
    • Description: Conjugate transpose of the SX gate.
    • Matrix:

$$ SX^\dagger = \frac{1}{2}\begin{bmatrix} 1-i & 1+i \ 1+i & 1-i \end{bmatrix} $$

16. cnot()
    • Description: Controlled-NOT gate flips the second qubit if the first is ∣1⟩.
    • Matrix:

$$ CNOT = \begin{bmatrix} 1 & 0 & 0 & 0 \ 0 & 1 & 0 & 0 \ 0 & 0 & 0 & 1 \ 0 & 0 & 1 & 0 \end{bmatrix} $$

17. cz()
    • Description: Controlled-Z gate applies a phase flip to the second qubit if the first is ∣1⟩.
    • Matrix:

$$ CZ = \begin{bmatrix} 1 & 0 & 0 & 0 \ 0 & 1 & 0 & 0 \ 0 & 0 & 1 & 0 \ 0 & 0 & 0 & -1 \end{bmatrix} $$

18. toffoli()
    • Description: Toffoli gate flips the target qubit if both control qubits are ∣1⟩.
    • Matrix:

$$ Toffoli = \begin{bmatrix} 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \ 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \ 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \ 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \ 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \ 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \ 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \end{bmatrix} $$

19. swap()
    • Description: SWAP gate exchanges the states of two qubits.
    • Matrix:

$$ SWAP = \begin{bmatrix} 1 & 0 & 0 & 0 \ 0 & 0 & 1 & 0 \ 0 & 1 & 0 & 0 \ 0 & 0 & 0 & 1 \end{bmatrix} $$

20. U()
    • Description: The u gate is a general single-qubit gate with three parameters (θ, ϕ, λ).
    • Matrix:

$$ U(\theta,\phi,\lambda) = \begin{bmatrix} \cos(\theta/2) & -e^{i\lambda}\sin(\theta/2) \ e^{i\phi}\sin(\theta/2) & e^{i(\phi+\lambda)}\cos(\theta/2) \end{bmatrix} $$

21. r1()
    • Description: The r1 gate applies a phase rotation (θ) to a single qubit.
    • Matrix:

$$ R_1(\theta) = \begin{bmatrix} 1 & 0 \ 0 & e^{i\theta} \end{bmatrix} $$

22. rxx()
    • Description: The rxx gate is a two-qubit rotation gate around the X axis.
    • Matrix:

$$ RXX(\theta) = \begin{bmatrix} \cos(\theta/2) & 0 & 0 & -i\sin(\theta/2) \ 0 & \cos(\theta/2) & -i\sin(\theta/2) & 0 \ 0 & -i\sin(\theta/2) & \cos(\theta/2) & 0 \ -i\sin(\theta/2) & 0 & 0 & \cos(\theta/2) \end{bmatrix} $$

23. rzz()
    • Description: The rzz gate applies a two-qubit rotation around the Z axis.
    • Matrix:

$$ RZZ(\theta) = \begin{bmatrix} e^{-i\theta/2} & 0 & 0 & 0 \ 0 & e^{i\theta/2} & 0 & 0 \ 0 & 0 & e^{i\theta/2} & 0 \ 0 & 0 & 0 & e^{-i\theta/2} \end{bmatrix} $$

24. cr()
    • Description: The cr gate is a controlled rotation gate.
    • Matrix:

$$ CR(\theta) = \begin{bmatrix} 1 & 0 & 0 & 0 \ 0 & 1 & 0 & 0 \ 0 & 0 & 1 & 0 \ 0 & 0 & 0 & e^{i\theta} \end{bmatrix} $$

---

visual.py

The circuit_Visualizer class is designed to provide both text-based and graphical representations of a quantum circuit. It supports single-qubit and multi-qubit gates, with intuitive visualizations and detailed output.

Class: Circuit_Visualizer

Attributes

1. num_qubits (int):
   • Number of qubits in the quantum circuit.
2. operations (list of tuples):
   • List of quantum operations to be visualized.
   • Each operation is represented as a tuple:
     • gate (function): The gate function.
     • qubits (list of int): Qubits on which the gate operates.
     • name (str): Name of the gate (used for visualization).

Method: draw_text()

Description

Generates a text-based representation of the quantum circuit with connecting lines between qubits. It supports both single-qubit and multi-qubit gates.

Functionality

1. Creates a grid of text-based elements for the circuit.
2. Represents:
   • Single-qubit gates with the gate name.
   • Multi-qubit gates with:
     • ‘●’ for the control qubit.
     • ‘X’ for the target qubit.
     • ‘│’ for vertical connections between control and target.
   • Horizontal connections (─) between gates.
3. Returns a formatted string showing the circuit for all qubits.

Method: draw_matplotlib()

Description

Generates a Matplotlib-based graphical visualization of the quantum circuit.

Functionality

1. Creates a plot with:
   • Horizontal lines representing qubit wires.
   • Shapes for gates:
     • Rectangle for single-qubit gates.
     • Circle for control points.
     • Smaller Circle for target points in multi-qubit gates.
   • Vertical lines connecting control and target qubits for multi-qubit gates.
2. Uses text annotations for gate names and markers.
3. Configures axis labels:
   • q0, q1, ... for qubit identifiers.
   • Hides the x-axis labels for cleaner visualization.

Graphical Elements

• Single-qubit gates: Represented as rectangles with the gate name inside.
• Multi-qubit gates:
  • Control qubit: Red circle (+ in the center).
  • Target qubit: Blue dot.
  • Connection: Vertical black line between control and target.

---

gpu_calculator.py

Overview
The GpuCalculator class implements a GPU-accelerated quantum state vector simulator using CuPy. This implementation provides the same quantum computation capabilities as BaseCalculator but leverages GPU acceleration for improved performance on large quantum systems.

Class Structure
Constructor
Initializes a new GPU-accelerated quantum calculator instance.

Parameters:

• qubits (int): Number of qubits in the quantum system
• prep (str, optional): State preparation method. Defaults to "z"

Attributes

• qubits: Number of qubits in the system
• prep: State preparation method
• state: Current state vector of the quantum system (stored on GPU memory)

Methods

initialize_state()
Initializes the quantum state vector to |0...0⟩ state on the GPU.

• Returns:
  • cupy.ndarray: Initial state vector with dimensions $$2^{\text{n}}$$ where n is the number of qubits

gate_apply(gate, target)
Applies a quantum gate to specified target qubits using GPU acceleration.

• Parameters:
  • gate (cupy.ndarray): Gate matrix to apply
  • target (list[int]): List of target qubit indices

_create_full_gate(gate, target)
Creates an expanded gate matrix on the GPU that acts on the entire quantum system.

• Parameters:
  • gate (cupy.ndarray): Original gate matrix
  • target (list[int]): Target qubit indices
• Returns:
  • cupy.ndarray: Expanded gate matrix

measure_state()
Calculates measurement probabilities and transfers results back to CPU memory.

• Returns:
  • numpy.ndarray: Array of measurement probabilities for each basis state

---

base_calculator.py

Overview
The BaseCalculator class implements a quantum state vector simulator for quantum computations. It provides fundamental operations for initializing quantum states, applying quantum gates, and measuring quantum states. This class serves as a base implementation of the CalculatorInterface.

Class Structure
Constructor
Initializes a new quantum calculator instance.

Parameters:

• num_qubits (int): Number of qubits in the quantum system
• prep (str, optional): State preparation method. Defaults to "z"

Attributes

• num_qubits: Number of qubits in the system
• register: QuantumRegister instance managing the qubits
• prep: State preparation method
• state: Current state vector of the quantum system

Methods

initialize_state()
Initializes the quantum state vector to |0...0⟩ state.

• Returns:
  • numpy.ndarray: Initial state vector with dimensions $$2^{\text{n}}$$ where n is the number of qubits

gate_apply(gate, target)
Applies a quantum gate to specified target qubits.

• Parameters:
  • gate (numpy.ndarray): Gate matrix to apply
  • target (list[int]): List of target qubit indices
• Raises:
  • ValueError: If target qubits are out of range or dimensions mismatch

_create_full_gate(gate, target)
Creates an expanded gate matrix that acts on the entire quantum system.

• Parameters:
  • gate (numpy.ndarray): Original gate matrix
  • target (list[int]): Target qubit indices
• Returns:
  • numpy.ndarray: Expanded gate matrix

measure_state()
Calculates measurement probabilities for the current quantum state.

• Returns:
  • numpy.ndarray: Array of measurement probabilities for each basis state

Usage Example

# Create a 2-qubit calculator
calc = BaseCalculator(num_qubits=2)

# Define a single-qubit gate (e.g., Hadamard gate)
H = np.array([[1, 1], [1, -1]]) / np.sqrt(2)

# Apply gate to first qubit
calc.gate_apply(H, [0])

# Get measurement probabilities
probabilities = calc.measure_state()

---

calculator_interface.py

Overview
The CalculatorInterface defines the contract for quantum calculator implementations, supporting both CPU and GPU-based quantum state calculations. This interface ensures consistent behavior across different implementations while allowing flexibility in the underlying computation method.

Interface Definition
Constructor
Creates a new quantum calculator instance.

Parameters:

• qubits (int): Number of qubits in the quantum system
• prep (str, optional): State preparation method. Defaults to "z"
• use_gpu (bool, optional): Flag to enable GPU computation. Defaults to False

Methods

initialize_state()
Initializes the quantum state vector in the computational basis.

• Returns:
  • numpy.ndarray: The initialized quantum state vector
• Contract Requirements:
  • Must return a normalized state vector
  • Vector dimension must be $$2^{\text{n}}$$ where n is the number of qubits
  • Must use complex128 data type for numerical precision
  • For prep="z", must initialize to |0...0⟩ state

gate_apply(gate, target)
Applies a quantum gate to specified target qubits.

• Parameters:
  • gate (numpy.ndarray): Gate matrix to apply
  • target (List[int]): List of target qubit indices
• Contract Requirements:
  • Must preserve state vector normalization
  • Must handle multi-qubit gates correctly
  • Must validate target qubit indices
  • Must maintain quantum state coherence

Implementation Guidelines

State Vector Requirements

1. Dimensionality

   • State vector must have $$2^{\text{n}}$$ elements for n qubits
   • Must be represented as complex numbers

2. Normalization

   • State vector must remain normalized after all operations
   • Implementations should enforce ||ψ|| = 1

3. Numerical Precision

   • Must use complex128 (or equivalent) data type
   • Should maintain numerical stability in operations

Gate Operation Requirements

1. Matrix Properties

   • Gates must be unitary matrices
   • Dimensions must match number of target qubits
   • Multi-qubit gates must be handled correctly

2. Target Validation

   • Must verify target qubit indices are valid
   • Must handle multiple target qubits correctly

GPU Support Requirements

1. Memory Management

   • Must handle GPU memory allocation when use_gpu=True
   • Must manage CPU-GPU memory transfers efficiently

2. Computation Location

   • Must respect use_gpu flag for computation location
   • Must ensure consistent results between CPU and GPU

---

Calculator.py

Overview
The Quantum Calculator CLI is an interactive command-line tool for performing quantum operations on a quantum register. It supports various quantum gates, including single-qubit gates, two-qubit gates, and controlled operations.

Getting Started
When you run the calculator, it will first prompt you for the number of qubits in your quantum register. The register is initialized in the |0...0⟩ state.

Available Operations

Single-Qubit Gates
For these operations, you'll be prompted for a qubit index.

Operation	Description	Parameters
identity	Identity gate (I)	qubit index
h	Hadamard gate	qubit index
paulix	Pauli-X gate (NOT)	qubit index
pauliy	Pauli-Y gate	qubit index
pauliz	Pauli-Z gate	qubit index
s	S gate (√Z)	qubit index
sdg	S-dagger gate	qubit index
t	T gate (√S)	qubit index
tdg	T-dagger gate	qubit index
sx	√X gate	qubit index
sxdg	√X-dagger gate	qubit index

Rotation Gates
These gates require both a qubit index and an angle parameter.

Operation	Description	Parameters
rx	X-axis rotation	qubit index, angle
ry	Y-axis rotation	qubit index, angle
rz	Z-axis rotation	qubit index, angle
r1	Phase rotation	qubit index, angle
phase	Phase gate	qubit index, angle

Two-Qubit Gates
These operations require control and target qubit indices.

Operation	Description	Parameters
cnot	Controlled-NOT	control qubit, target qubit
cz	Controlled-Z	control qubit, target qubit
cr	Controlled-R	control qubit, target qubit, angle
rxx	XX-rotation	qubit1, qubit2, angle
rzz	ZZ-rotation	qubit1, qubit2, angle

Other Operations

Operation	Description	Parameters
swap	SWAP gate	qubit1 index, qubit2 index
toffoli	Toffoli gate	control1, control2, target
print	Print state vector	none

Angle Expressions
Angles can be specified using:

• Decimal numbers (e.g., 1.5707)
• Pi expressions (e.g., pi/2, pi/4, -pi)
• Basic arithmetic (e.g., pi/2 + 0.5)

State Vector
The quantum state is stored as a multi-dimensional numpy array with shape (2,)*n for n qubits. The print operation will flatten and display the state vector.

State Representation

• Uses NumPy arrays with shape (2,)*n for n qubits
• Complex amplitudes stored as complex128 type
• State vector normalized after operations

Example Usage
Creating a Bell State:

Enter the number of qubits: 2
Enter the operation name: h
Enter the qubit index: 0
Enter the operation name: cnot
Enter the control qubit index: 0
Enter the target qubit index: 1
Enter the operation name: print
Final State Vector:
[0.70710678+0.j 0.00000000+0.j 0.00000000+0.j 0.70710678+0.j]

---

quantum_circuit.py

Overview
QuantumCircuit is a high-level class for building and executing quantum circuits. It provides an interface for adding quantum gates, executing circuits, measuring results, and visualizing quantum circuits using both text and graphical representations.

Class Initialization
Parameters:

• num_qubits (int): Number of qubits in the circuit
• prep (str, optional): State preparation basis ('x', 'y', or 'z'). Defaults to 'z'
• gpu (bool, optional): Enable GPU acceleration. Defaults to False

Initialization Process:

1. Validates qubit preparation basis
2. Checks GPU availability if requested
3. Creates appropriate calculator (GPU or CPU-based)
4. Initializes circuit visualizer
5. Sets up circuit information tracking

Methods

add_gate(gate, qubits, name)
Adds a quantum gate to the circuit.

• Parameters:
  • gate (np.ndarray): Matrix representation of the quantum gate
  • qubits (list[int]): Target qubit indices
  • name (str): Gate name for visualization

execute()
Executes the quantum circuit by:

1. Applying gates sequentially
2. Synchronizing with quantum register
3. Providing debug output

measure()
Performs measurement on the final state.

• Returns:
  • Probability distribution of possible outcomes

draw_circuit(method)
Visualizes the quantum circuit.

• Parameters:
  • method (str): Visualization type
    • "text": ASCII art representation
    • "matplotlib": Graphical visualization

Circuit Management Methods

clear()
Removes all operations from the circuit.

dump_circuit()

• Returns:
  • List of circuit operations: [(gate, qubits, name), ...]

get_info()

• Returns:
  • Dictionary containing:
    • Number of qubits
    • Operation list
    • State preparation basis
    • GPU usage status

Usage Examples

Basic Circuit Creation

# Create a 2-qubit circuit
circuit = QuantumCircuit(num_qubits=2)

# Add Hadamard gate to first qubit
circuit.add_gate(hadamard(), [0], "H")

# Add CNOT gate
circuit.add_gate(cnot(), [0, 1], "CNOT")

# Execute circuit
circuit.execute()

# Measure results
probabilities = circuit.measure()

Circuit Visualization

# Text visualization
circuit.draw_circuit(method="text")

# Graphical visualization
circuit.draw_circuit(method="matplotlib")

GPU Acceleration

# Create GPU-accelerated circuit
circuit = QuantumCircuit(num_qubits=3, gpu=True)

Implementation Details GPU Support

• Automatically checks for NVIDIA CUDA toolkit
• Falls back to CPU if GPU is unavailable
• Uses CuPy for GPU-accelerated calculations

State Management

• Maintains synchronization between:
  • Circuit operations
  • Quantum register state
  • Calculator state

Visualization

• Text mode: ASCII representation
• Matplotlib mode: Professional circuit diagrams
• Shows gate sequence and qubit connections

---

quantum_register.py

The QuantumRegister class provides a framework for managing and simulating a quantum register, which is a collection of qubits. It allows for the initialization, manipulation, and retrieval of the quantum state.

Class: QuantumRegister

Attributes

1. num_qubits (int):
   • The number of qubits in the quantum register.
2. state (numpy array):
   • A complex-valued NumPy array representing the quantum state of the register.
   • Initialized to the $$\vert 0 \rangle ^{\otimes n}$$ state, where n is the number of qubits.
3. qubits (list of Qubits):
   • A list of Qubits objects, each representing an individual qubit in the register.

Methods

__init__(self, num_qubits: int)

• Description: Initializes the quantum register with the specified number of qubits.
• Parameters:
  • num_qubits (int): The number of qubits in the quantum register.
• Behavior:
  • Creates a quantum state vector of size $$2^{\text{numqubits}}$$ initialized to [1, 0, 0, …,0], representing the $$\vert 0 \rangle ^{\otimes n}$$ state.
  • Initializes a list of Qubits objects for individual qubit representation.

get_state(self) -> numpy array

• Description: Retrieves the current quantum state of the register.
• Returns:
  • (numpy array): The quantum state vector.

reset(self)

• Description: Resets the quantum register to the initial $$\vert 0 \rangle ^{\otimes n}$$ state.
• Behavior:
  • Sets the quantum state vector to [1, 0, 0, …,0] representing the $$\vert 0 \rangle ^{\otimes n}$$ state.

---

qubit.py

The Qubits class represents the fundamental unit of quantum information, analogous to a classical bit. It provides methods for initializing, representing, and retrieving the quantum state of a qubit.

Class: Qubits

Attributes

1. index (int):
   • The index of the qubit in a quantum register or system.
2. state (numpy array):
   • The state vector of the qubit initialized based on the specified orientation.

Methods

__init__(self, index: int, state: str = "z")

• Description: Initializes a qubit with the specified index and orientation (state).
• Parameters:
  • index (int): The index of the qubit in the system.
  • state (str): The initial orientation of the qubit. Must be one of:
    • "z": Initializes to the ∣0⟩ state.
    • "x": Initializes to the $$|+\rangle = \frac{1}{\sqrt{2}} (|0\rangle + |1\rangle)$$ state.
    • "y": Initializes to the $$|i\rangle = \frac{1}{\sqrt{2}} (|0\rangle + i|1\rangle)$$ state.
    • Default: "z".

initial_state(self, state: str = "z") -> NDArray

• Description: Creates and returns the state vector for the specified initial orientation of the qubit.
• Parameters:
  • state (str): The initial orientation of the qubit. Must be one of "z", "x", or "y".
• Returns:
  • NDArray: A 2×1 NumPy array representing the qubit's state vector.
• Raises:
  • ValueError: If the provided state is not one of "z", "x", or "y".

get_state(self) -> NDArray

• Description: Retrieves the current state vector of the qubit.
• Returns:
  • NDArray: The 2×1 NumPy array representing the qubit's state vector.

---

quantum_state.py

The QuantumState class provides a representation of a quantum system's state vector. It includes methods for initializing, manipulating, and measuring the quantum state, making it a fundamental component for simulating quantum computations.

Class: QuantumState

Attributes

1. num_qubits (int):
   • The number of qubits in the quantum system.
   • Determines the dimension of the quantum state vector ($$2^{\text{numqubits}}$$).
2. state (numpy array):
   • A complex-valued NumPy array representing the quantum state vector.
   • Initialized to the $$\vert 0 \rangle ^{\otimes n}$$ state, where n is the number of qubits.

Methods

__init__(self, num_qubits: int)

• Description: Initializes the quantum state with the specified number of qubits.
• Parameters:
  • num_qubits (int): The number of qubits in the quantum system.
• Behavior:
  • Creates a quantum state vector of size $$2^{\text{numqubits}}$$.
  • Initializes the state to $$\vert 0 \rangle ^{\otimes n}$$.

apply_unitary(self, unitary: np.ndarray)

• Description: Applies a unitary transformation (quantum gate) to the quantum state.
• Parameters:
  • unitary (numpy array): A $$2^n * 2^n$$ matrix representing the unitary operation.
• Behavior:
  • Validates that the unitary matrix dimensions match the quantum state vector ($$2^n * 2^n$$).
  • Updates the state vector by performing the matrix-vector multiplication: state = U⋅ state, where U is the unitary matrix.
• Raises:
  • ValueError: If the dimensions of the unitary matrix do not match $$2^n * 2^n$$.

get_state(self) -> np.ndarray

• Description: Retrieves the current quantum state vector.
• Returns:
  • np.ndarray: The quantum state vector.

measure(self) -> str

• Description: Simulates a measurement of the quantum state, collapsing it to one basis state.
• Returns:
  • str: The measured basis state as a binary string.
• Behavior:
  • Uses the measure function from the tools module to determine the measurement outcome based on the probability distribution of the state vector.

---

measure.py

The measure function simulates a quantum measurement on a quantum state or circuit.

Purpose:
This function performs a quantum measurement that collapses a quantum state according to quantum mechanics' measurement postulates.

Parameters:

• quantumstate: Either a numpy array representing a quantum state vector, or a QuantumCircuit object
  • If numpy array: Direct state vector
  • If QuantumCircuit: The current state of the circuit will be measured

Returns:

• A string representing the measured basis state in binary notation
  • Example: "00" for |00⟩, "01" for |01⟩, etc.
  • The string length matches the number of qubits

Process:

1. Converts input to state vector if needed using convert_state
2. Calculates number of qubits using log base 2 of state vector size
3. Computes measurement probabilities from state amplitudes
4. Randomly selects an outcome based on these probabilities
5. Converts the outcome to binary representation

---

probability.py

Overview
The probability function calculates measurement probabilities from a quantum state vector or quantum circuit. It supports various output formats and can focus on specific quantum states.

Parameters

quantumstate

• Type: Union[ndarray, QuantumCircuit]
• Description: The quantum state to analyze
• Accepted Formats:
  • NumPy array containing state vector
  • QuantumCircuit object
• Requirements:
  • Must be normalized (sum of probability amplitudes squared ≈ 1)
  • Size must be power of 2 ($$2^{\text{n}}$$ for n qubits)

round

• Type: int or None
• Default: None
• Description: Number of decimal places to round probabilities to
• Special Cases:
  • None: No rounding applied
  • Negative values: Returns None

show_percent

• Type: bool
• Default: False
• Description: Controls probability format
• Values:
  • False: Probabilities as decimals [0,1]
  • True: Probabilities as percentages [0,100]

show_bit

• Type: int
• Default: -1
• Description: Selects specific quantum state to analyze
• Values:
  • -1: Show all probabilities
  • ≥ 0: Show probability for specific basis state
  • ≥ $$2^{\text{n}}$$: Returns None (n = number of qubits)

Return Value
Type

• NDArray: NumPy array of probabilities
• None: If validation fails

Format

• Array of probabilities for each basis state
• Single probability value if show_bit ≥ 0
• Values rounded if round parameter specified

Validation Checks
The function performs several validations:

1. Normalization

   • Verifies sum of probabilities ≈ 1.0
   • Tolerance: 1e-6
   • Returns None if check fails

2. State Index

   • Verifies show_bit < $$2^{\text{n}}$$
   • Returns None if invalid

3. Rounding Parameter

   • Verifies round ≥ 0
   • Returns None if negative

Mathematical Details

1. Probability Calculation

   • Takes absolute value of squared amplitudes
   • Converts complex amplitudes to real probabilities

2. Percentage Conversion

   • Scales values to [0,100] range when show_percent=True

---

Simulator.py

The Simulator class is a foundational structure for simulating quantum computations. It provides a framework to manage and manipulate the state vector of a quantum system, representing the evolution of quantum states during computation.

Class: Simulator

Attributes

1. state_vector (None or numpy array):
   • Represents the quantum state vector of the system.
   • Initially set to None and is updated as the simulator is used to initialize and manipulate quantum states.

Methods

__init__(self)

• Description: Initializes the simulator instance with an uninitialized state vector.
• Behavior:
  • Sets the state_vector attribute to None.
  • Acts as a placeholder for later initialization and manipulation of the quantum state.

---