State

Table of Contents

• Overview
• State Structure
• Creating Quantum States
• State Operations
• Measurement
• Utility Methods
• Examples

Overview

The states module provides a quantum state vector representation using complex amplitudes. It supports operations such as:

• Creating various standard quantum states
• Normalizing state vectors
• Applying quantum gates
• Performing measurements
• Calculating probabilities
• Tensor products for multi-qubit systems

State Structure

pub struct State {
    // Fields are private - use getter methods to access
}

Access Methods:

• num_qubits(): Returns the number of qubits in the system
• vector(): Returns a reference to the state vector (read-only)
• vector_mut(): Returns a mutable reference to the state vector (for modifications)

Note: The internal fields are encapsulated for better API design and data integrity.

Creating Quantum States

Creating a Custom State

pub fn new(vector: Array1<Complex64>, num_qubits: Option<usize>) -> Result<Self, LogosQError>

Creates a new quantum state from a complex vector and automatically normalizes it.

Parameters:

• vector: The complex amplitudes
• num_qubits: Optional number of qubits. If not provided, calculated as log2 of the vector length

Returns:

• Result<State, LogosQError>: Returns an error if the vector dimension doesn't match the expected size

Example:

use logosq::prelude::*;

let vector = Array1::from_vec(vec![
    Complex64::new(1.0, 0.0),
    Complex64::new(1.0, 0.0),
]);
let state = State::new(vector, Some(1))?; // Handle Result appropriately
println!("Number of qubits: {}", state.num_qubits());

Standard Basis States

pub fn zero_state(num_qubits: usize) -> Self

Creates the |0...0⟩ state with the specified number of qubits.

pub fn one_state(num_qubits: usize) -> Self

Creates the |1...1⟩ state with the specified number of qubits.

Example:

let zero = State::zero_state(2); // |00⟩
let one = State::one_state(2);   // |11⟩

Superposition States

pub fn plus_state(num_qubits: usize) -> Self

Creates the |+⟩ state (equal superposition of all basis states).

pub fn bell_state() -> Self

Creates the Bell state (|00⟩ + |11⟩)/√2, a maximally entangled two-qubit state.

Example:

let plus = State::plus_state(1);  // (|0⟩ + |1⟩)/√2
let bell = State::bell_state();   // (|00⟩ + |11⟩)/√2

State Operations

Normalization

pub fn normalize(&mut self) -> Result<(), LogosQError>

Normalizes the state vector so that the sum of squared amplitudes equals 1.

Returns:

• Result<(), LogosQError>: Returns an error if normalization fails (e.g., zero norm)

Applying Gates

pub fn apply_gate<G: Gate>(&mut self, gate: &G) -> Result<(), LogosQError>

Applies a quantum gate to the state.

Parameters:

• gate: The quantum gate to apply

Returns:

• Result<(), LogosQError>: Returns an error if gate application fails

Example:

use logosq::prelude::*;

let mut state = State::zero_state(1);
let h_gate = h(0, 1);
h_gate.apply(&mut state)?; // Transforms |0⟩ to |+⟩

Tensor Product

pub fn tensor_product(&self, other: &State) -> Result<State, LogosQError>

Computes the tensor product of two quantum states.

Parameters:

• other: The state to compute the tensor product with

Returns:

• Result<State, LogosQError>: A new state representing the tensor product, or an error if computation fails

Example:

use logosq::prelude::*;

let state1 = State::zero_state(1); // |0⟩
let state2 = State::one_state(1);  // |1⟩
let combined = state1.tensor_product(&state2)?; // |01⟩

Measurement

Full State Measurement

pub fn measure(&self) -> usize

Measures the entire state, returning the observed basis state index according to the probability distribution.

Returns:

• The index of the measured basis state

Single Qubit Measurement

pub fn measure_qubit(&mut self, qubit_idx: usize) -> Result<usize, LogosQError>

Measures a specific qubit, collapsing the state according to the measurement outcome.

Parameters:

• qubit_idx: The index of the qubit to measure

Returns:

• Result<usize, LogosQError>: The measurement result (0 or 1), or an error if qubit index is invalid

Example:

use logosq::prelude::*;

let mut bell = State::bell_state(); // (|00⟩ + |11⟩)/√2
let result = bell.measure_qubit(0)?; // Measures first qubit, collapses state

Probability Calculation

pub fn probability(&self, basis_state: usize) -> f64

Calculates the probability of measuring a particular basis state.

Parameters:

• basis_state: The index of the basis state

Returns:

• The probability of measuring the specified basis state

Example:

let plus = State::plus_state(1);
let prob_zero = plus.probability(0); // 0.5

Utility Methods

Print Function

pub fn print(&self) -> String

Generates a human-readable representation of the quantum state.

Returns:

• A formatted string representation of the state

Example:

let bell = State::bell_state();
println!("{}", bell.print());
// Output:
// State: 2 qubits
// |00⟩ : 0.7071+0.0000i (p=0.5000)
// |11⟩ : 0.7071+0.0000i (p=0.5000)

Examples

Creating a Bell State and Measuring

// Create a Bell state
let mut bell = State::bell_state();
println!("Bell state:");
println!("{}", bell.print());

// Measure the first qubit
let result = bell.measure_qubit(0);
println!("Measured qubit 0: {}", result);
println!("State after measurement:");
println!("{}", bell.print());

Creating a Custom Superposition

use logosq::prelude::*;

// Create a custom state |ψ⟩ = (0.6|0⟩ + 0.8|1⟩)
let vector = Array1::from_vec(vec![
    Complex64::new(0.6, 0.0),
    Complex64::new(0.8, 0.0),
]);
let state = State::new(vector, Some(1))?;
println!("Custom state:");
println!("{}", state.print());
println!("Number of qubits: {}", state.num_qubits());

Working with Multi-Qubit Systems

use logosq::prelude::*;

// Create a 3-qubit GHZ state (|000⟩ + |111⟩)/√2
let mut vector = Array1::zeros(8);
vector[0] = Complex64::new(1.0/SQRT_2, 0.0);
vector[7] = Complex64::new(1.0/SQRT_2, 0.0);
let ghz = State::new(vector, Some(3))?;
println!("GHZ state:");
println!("{}", ghz.print());
println!("Number of qubits: {}", ghz.num_qubits());