DOCUMENTATION.md

API Documentation

This document explains every public function in the quantum_core library and describes the variables they accept.

quantum_core/state.py

make_zero_state(number_of_qubits)

Create a state vector representing |0...0> for a multi-qubit system.

• number_of_qubits (int): number of qubits in the state. Must be a positive integer.
• Returns: NumPy array of length 2**number_of_qubits with the first element equal to 1 and all others 0.
• Raises:
  • TypeError if number_of_qubits is not an integer.
  • ValueError if number_of_qubits <= 0.

make_state_from_bit_string(bit_string)

Create a basis state from a classical bit string.

• bit_string (str): string of 0 and 1 characters, such as "00" or "101".
• Returns: NumPy array representing the basis state |bit_string>.
• Raises:
  • TypeError if bit_string is not a string.
  • ValueError if bit_string is empty.
  • ValueError if bit_string contains characters other than 0 or 1.

make_one_qubit_state(alpha, beta)

Create a normalized single-qubit state from amplitudes.

• alpha (complex or numeric): amplitude for |0>.
• beta (complex or numeric): amplitude for |1>.
• Returns: normalized NumPy array [alpha, beta].
• Uses normalize_state internally, so a zero or invalid state will raise an error.

count_qubits(state)

Return the number of qubits represented by a state vector.

• state (np.ndarray): one-dimensional NumPy array of length 2**n.
• Returns: integer n.
• Raises:
  • TypeError if state is not a NumPy array.
  • ValueError if state is not one-dimensional or empty.
  • ValueError if the array length is not a power of 2.

check_state_vector_basic_shape(state)

Validate the basic shape of a state vector.

• state (np.ndarray): state vector.
• Raises if the state is not a 1D NumPy array with nonzero length.

normalize_state(state)

Normalize a state vector so the total probability equals 1.

• state (np.ndarray): complex state vector.
• Returns: normalized state vector.
• Raises:
  • TypeError if state is not a NumPy array.
  • ValueError if the state is empty, not one-dimensional, not length power of 2, or all-zero.

check_state_is_valid(state)

Validate that a state vector is normalized and correctly shaped.

• state (np.ndarray): state vector.
• Returns: True if valid.
• Raises:
  • TypeError if state is not a NumPy array.
  • ValueError if the shape is invalid, the length is not a power of 2, or the total probability differs from 1 by more than 1e-8.

show_state(state)

Get a human-readable list of nonzero amplitudes.

• state (np.ndarray): valid, normalized state vector.
• Returns: list of strings like "(0.70710678+0j) |00>".
• Uses check_state_is_valid internally.

probability_dictionary(state)

Get probability values for each basis state.

• state (np.ndarray): valid state vector.
• Returns: dictionary mapping bit strings to probabilities.
• For example, {"00": 0.5, "11": 0.5}.

quantum_core/gates.py

Standard gate constants

• I: identity gate for one qubit.
• X: Pauli-X (bit flip).
• Y: Pauli-Y.
• Z: Pauli-Z (phase flip).
• H: Hadamard.
• S: phase gate with i on |1>.
• T: phase gate with e^{i\pi/4} on |1>.
• CNOT: controlled-NOT on two qubits.
• CZ: controlled-Z on two qubits.

check_gate_is_valid(gate)

Validate that a quantum gate is a square unitary matrix sized for qubits.

• gate (np.ndarray): 2D NumPy array.
• Returns: True if the gate is valid.
• Raises:
  • TypeError if gate is not a NumPy array.
  • ValueError if gate is not 2D, not square, empty, or has dimensions not a power of 2.
  • ValueError if the gate is not unitary.

phase_gate(theta)

Create a one-qubit phase gate.

• theta (float): phase angle in radians.
• Returns: [[1, 0], [0, exp(i * theta)]].

rotation_y_gate(theta)

Create a rotation around the Y axis.

• theta (float): rotation angle in radians.
• Returns: a one-qubit Ry unitary matrix.

quantum_core/circuit.py

check_target_qubits(number_of_qubits, target_qubits)

Validate target qubit indices for a gate application.

• number_of_qubits (int): total qubits in the current state.
• target_qubits (list[int]): qubit indices to apply the gate to.
• Returns: True if valid.
• Raises:
  • TypeError if inputs have invalid types.
  • ValueError if indices are empty, negative, out of range, or repeated.

apply_gate(state, gate, target_qubits)

Apply a quantum gate to selected qubits in a state vector.

• state (np.ndarray): normalized state vector.
• gate (np.ndarray): unitary gate matrix.
• target_qubits (list[int]): qubit indices where the gate acts.
• Returns: normalized new state after applying the gate.
• Raises:
  • ValueError if the gate size does not match the number of target qubits.

apply_gate_using_tensors(state, gate, target_qubits)

Internal helper that uses tensor contraction to apply the gate.

• state (np.ndarray): state vector.
• gate (np.ndarray): gate matrix.
• target_qubits (list[int]): qubit indices.
• Returns: new raw state vector before normalization.

quantum_core/measurement.py

get_probabilities(state)

Alias for probability_dictionary(state).

• state (np.ndarray): valid state vector.
• Returns: dictionary of outcome probabilities.

check_measurement_targets(state, target_qubits)

Validate qubit indices used in measurement.

• state (np.ndarray): valid state vector.
• target_qubits (list[int] or None): qubits to measure.
• Returns: validated list of qubit indices.
• If target_qubits is None, all qubits are measured.

measure(state, target_qubits=None, random_seed=None)

Measure one or more qubits and collapse the state.

• state (np.ndarray): valid state vector.
• target_qubits (list[int] or None): qubits to measure.
• random_seed (int or None): seed for reproducible randomness.
• Returns: tuple (chosen_result, collapsed_state).
  • chosen_result is a bit string like "0", "10", or "11".
  • collapsed_state is the new normalized state after collapse.

make_all_bit_results(number_of_bits)

Create all possible bit strings of a given length.

• number_of_bits (int): number of qubits.
• Returns: list of length 2**number_of_bits with strings from "00" to "11".

probability_for_partial_result(state, target_qubits, wanted_result)

Compute probability of a specific partial measurement outcome.

• state (np.ndarray): valid state vector.
• target_qubits (list[int]): qubits being measured.
• wanted_result (str): bit string describing the measurement result on target_qubits.
• Returns: float probability.

collapse_state(state, target_qubits, chosen_result)

Collapse the state to a measurement result.

• state (np.ndarray): valid state vector.
• target_qubits (list[int]): measured qubits.
• chosen_result (str): observed bit string.
• Returns: new normalized state after zeroing inconsistent amplitudes.

Example workflows

Create and inspect a Bell state

from quantum_core.state import make_zero_state
from quantum_core.circuit import apply_gate
from quantum_core.gates import H, CNOT
from quantum_core.measurement import get_probabilities, measure

state = make_zero_state(2)
state = apply_gate(state, H, [0])
state = apply_gate(state, CNOT, [0, 1])
print(get_probabilities(state))
measured_bits, collapsed_state = measure(state, [0])
print(measured_bits)
print(get_probabilities(collapsed_state))

Teleport a qubit

import numpy as np
from quantum_core.state import make_one_qubit_state, normalize_state
from quantum_core.circuit import apply_gate
from quantum_core.gates import H, CNOT, X, Z
from quantum_core.measurement import measure

unknown_state = make_one_qubit_state(np.sqrt(0.3), np.sqrt(0.7) * np.exp(0.37j))
state = np.kron(unknown_state, np.array([1, 0, 0, 0], dtype=complex))
state = normalize_state(state)
state = apply_gate(state, H, [1])
state = apply_gate(state, CNOT, [1, 2])
state = apply_gate(state, CNOT, [0, 1])
state = apply_gate(state, H, [0])
alice_bits, state = measure(state, [0, 1], random_seed=4)
if alice_bits[1] == "1":
    state = apply_gate(state, X, [2])
if alice_bits[0] == "1":
    state = apply_gate(state, Z, [2])

Notes

• All state vectors are represented as one-dimensional NumPy arrays of complex values.
• Gate matrices must be unitary and have dimensions 2**n x 2**n.
• Qubit indices start at 0.