atlas_q.quantum_hybrid_system#

QUANTUM-CLASSICAL HYBRID SYSTEM Complete implementation combining all breakthroughs

Features: - Compressed quantum state representations (O(1) to O(n) memory) - Tensor network support (MPS for moderate entanglement) - O(√r) period-finding algorithms - Hybrid quantum-classical approach - Handles small, medium, and large periods efficiently

Author: Your name Date: 2025 License: MIT

class atlas_q.quantum_hybrid_system.CompressedQuantumState(num_qubits)[source]#

Bases: ABC

Base class for memory-efficient quantum state representations

Methods

`get_amplitude`(basis_state)	Get amplitude for a specific basis state
`get_probability`(basis_state)	Get measurement probability for a basis state
`measure`([num_shots])	Simulate measurement of the quantum state

abstractmethod get_amplitude(basis_state)[source]#

Get amplitude for a specific basis state

get_probability(basis_state)[source]#

Get measurement probability for a basis state

measure(num_shots=1)[source]#

Simulate measurement of the quantum state

For large systems, automatically falls back to MPS sampling

class atlas_q.quantum_hybrid_system.PeriodicState(num_qubits, offset=0, period=1)[source]#

Bases: CompressedQuantumState

O(1) memory representation of periodic quantum states Perfect for Shor’s algorithm and period-finding

Represents: |ψ⟩ = 1/√k Σ |offset + j*period⟩

NEW: Analytic QFT sampling for exact/cheap QFT-step emulation

Methods

`get_amplitude`(basis_state)	Constant time amplitude lookup
`get_probability`(basis_state)	Get measurement probability for a basis state
`measure`([num_shots, use_qft])	Simulate measurement of the quantum state
`memory_usage`()	Memory usage in bytes (constant!)
`qft_amplitude`(fourier_state)	Analytic QFT amplitude computation
`sample_qft_measurement`([num_shots])	Sample from QFT of periodic state analytically

get_amplitude(basis_state)[source]#

Constant time amplitude lookup

qft_amplitude(fourier_state)[source]#

Analytic QFT amplitude computation

For a periodic state |ψ⟩ = 1/√k Σⱼ |offset + j*r⟩, QFT gives peaks at multiples of N/r where N = 2^n

This makes QFT-step emulation exact and O(1)!

sample_qft_measurement(num_shots=1)[source]#

Sample from QFT of periodic state analytically

This is EXACT and much faster than computing full QFT! Returns measurements that would result from measuring after QFT.

measure(num_shots=1, use_qft=False)[source]#

Simulate measurement of the quantum state

Args:: num_shots: Number of measurements use_qft: If True, sample from QFT of state (for Shor’s algorithm)

memory_usage()[source]#

Memory usage in bytes (constant!)

class atlas_q.quantum_hybrid_system.ProductState(num_qubits)[source]#

Bases: CompressedQuantumState

O(n) memory representation for separable (non-entangled) states

Represents: |ψ⟩ = |ψ₀⟩ ⊗ |ψ₁⟩ ⊗ … ⊗ |ψₙ₋₁⟩

Methods

`apply_hadamard`(qubit)	Apply Hadamard gate in O(1) time
`apply_x`(qubit)	Apply X (NOT) gate in O(1) time
`get_amplitude`(basis_state)	O(n) amplitude calculation
`get_probability`(basis_state)	Get measurement probability for a basis state
`measure`([num_shots])	Simulate measurement of the quantum state
`memory_usage`()	Memory usage in bytes

get_amplitude(basis_state)[source]#

O(n) amplitude calculation

apply_hadamard(qubit)[source]#

Apply Hadamard gate in O(1) time

apply_x(qubit)[source]#

Apply X (NOT) gate in O(1) time

memory_usage()[source]#

Memory usage in bytes

class atlas_q.quantum_hybrid_system.MatrixProductState(num_qubits, bond_dim=8)[source]#

Bases: CompressedQuantumState

Tensor network representation for moderate entanglement Memory: O(n × χ²) where χ is bond dimension

Can simulate 50-100 qubits with controlled entanglement!

NEW: MPS canonicalization and sweep sampling for accurate measurements

Methods

`canonicalize_left_to_right`()	Bring MPS into left-canonical form using QR decomposition
`canonicalize_right_to_left`()	Bring MPS into right-canonical form using QR decomposition
`get_amplitude`(basis_state)	Contract MPS to get amplitude - O(n × χ²)
`get_probability`(basis_state)	Get measurement probability for a basis state
`measure`([num_shots])	Simulate measurement with accurate MPS sampling
`memory_usage`()	Memory usage in bytes
`sweep_sample`([num_shots])	Accurate MPS sampling using conditional probabilities sweep

canonicalize_left_to_right()[source]#

Bring MPS into left-canonical form using QR decomposition

Each tensor satisfies: Σₛ Aˢ†Aˢ = I (left-orthogonal) This enables efficient sampling and norm computation!

canonicalize_right_to_left()[source]#

Bring MPS into right-canonical form using QR decomposition

Each tensor satisfies: Σₛ AˢAˢ† = I (right-orthogonal)

sweep_sample(num_shots=1)[source]#

Accurate MPS sampling using conditional probabilities sweep

This is the CORRECT way to sample from MPS! Complexity: O(num_shots × n × χ²)

measure(num_shots=1)[source]#

Simulate measurement with accurate MPS sampling

Uses sweep sampling for correct probability distribution

get_amplitude(basis_state)[source]#

Contract MPS to get amplitude - O(n × χ²)

memory_usage()[source]#

Memory usage in bytes

class atlas_q.quantum_hybrid_system.PeriodResult(period, method, time_seconds, attempts=1)[source]#

Bases: object

Result from period finding

period: int | None#

method: str#

time_seconds: float#

attempts: int = 1#

class atlas_q.quantum_hybrid_system.PeriodFinder[source]#

Bases: object

Collection of O(√r) period-finding algorithms

Methods

`baby_step_giant_step`(a, N[, m])	Baby-step giant-step algorithm Complexity: O(√r) time and space
`collision_detection`(a, N[, num_samples])	Birthday paradox collision detection Complexity: O(√r) expected
`parallel_candidate_search`(a, N[, max_candidates])	Generate smart candidates and check them In real implementation, this would be GPU-parallelized
`pollards_rho`(a, N[, max_iter])	Floyd's cycle detection algorithm Complexity: O(√r) average case
`smart_factorization`(a, N)	Check if period has small factors Complexity: O(k) where k is number of candidates

static smart_factorization(a, N)[source]#

Check if period has small factors Complexity: O(k) where k is number of candidates

static pollards_rho(a, N, max_iter=100000)[source]#

Floyd’s cycle detection algorithm Complexity: O(√r) average case

Uses tortoise and hare to detect cycles in sequence: 1, a mod N, a² mod N, a³ mod N, …

static collision_detection(a, N, num_samples=None)[source]#

Birthday paradox collision detection Complexity: O(√r) expected

Sample random points, find collision f(x₁) = f(x₂) Then period divides |x₁ - x₂|

static baby_step_giant_step(a, N, m=None)[source]#

Baby-step giant-step algorithm Complexity: O(√r) time and space

Finds period by solving a^x ≡ 1 (mod N)

static parallel_candidate_search(a, N, max_candidates=1000)[source]#

Generate smart candidates and check them In real implementation, this would be GPU-parallelized

class atlas_q.quantum_hybrid_system.QuantumClassicalHybrid(verbose=True, use_gpu=True)[source]#

Bases: object

Main system combining: - Compressed quantum state representations - Classical O(√r) period-finding algorithms - Hybrid approach for optimal performance - Quantum circuit emulation (tensor contractions) - GPU acceleration support (optional)

Methods

`create_circuit`(num_qubits)	Create a new quantum circuit
`create_mps_state`(num_qubits[, bond_dim])	Create a tensor network (MPS) quantum state
`create_periodic_state`(num_qubits, period)	Create a compressed periodic quantum state
`create_product_state`(num_qubits)	Create a compressed product (separable) quantum state
`execute_circuit`(circuit[, backend])	Execute a quantum circuit using tensor contractions
`factor_number`(N[, max_attempts])	Factor N using period-finding (Shor's algorithm approach)
`find_period`(a, N[, method])	Find period of a^x mod N
`find_period_gpu`(a, N)	GPU-accelerated period finding Falls back to CPU if GPU unavailable

find_period(a, N, method='auto')[source]#

Find period of a^x mod N

Args:: a: Base N: Modulus method: “auto” (tries all), or specific method name
Returns:: PeriodResult with period, method used, and timing

factor_number(N, max_attempts=20)[source]#

Factor N using period-finding (Shor’s algorithm approach)

Returns:: Tuple of (factor1, factor2) if successful, None otherwise

create_periodic_state(num_qubits, period)[source]#

Create a compressed periodic quantum state

create_product_state(num_qubits)[source]#

Create a compressed product (separable) quantum state

create_mps_state(num_qubits, bond_dim=8)[source]#

Create a tensor network (MPS) quantum state

create_circuit(num_qubits)[source]#

Create a new quantum circuit

execute_circuit(circuit, backend='auto')[source]#

Execute a quantum circuit using tensor contractions

Args:: circuit: The quantum circuit to execute backend: “product” (separable only), “mps” (tensor network),

or “auto” (choose automatically based on gates)
Returns:: The final quantum state

find_period_gpu(a, N)[source]#

GPU-accelerated period finding Falls back to CPU if GPU unavailable

class atlas_q.quantum_hybrid_system.QuantumCircuit(num_qubits)[source]#

Bases: object

Quantum circuit with tensor network contraction Supports limited depth circuits efficiently

Methods

`add_gate`(gate_name, qubit[, params])	Add a gate to the circuit
`cnot`(control, target)	Add CNOT gate
`cz`(control, target)	Add CZ gate
`depth`()	Calculate circuit depth
`execute_on_product_state`([initial_state])	Execute circuit on a product state Only works if circuit maintains separability
`gate_count`()	Count gates by type
`get_gate_matrix`(gate_name[, params])	Get the matrix representation of a gate
`h`(qubit)	Add Hadamard gate
`rx`(qubit, theta)	Add rotation around X axis
`ry`(qubit, theta)	Add rotation around Y axis
`rz`(qubit, theta)	Add rotation around Z axis
`x`(qubit)	Add X (NOT) gate
`y`(qubit)	Add Y gate
`z`(qubit)	Add Z gate

add_gate(gate_name, qubit, params=None)[source]#

Add a gate to the circuit

h(qubit)[source]#

Add Hadamard gate

x(qubit)[source]#

Add X (NOT) gate

y(qubit)[source]#

Add Y gate

z(qubit)[source]#

Add Z gate

rx(qubit, theta)[source]#

Add rotation around X axis

ry(qubit, theta)[source]#

Add rotation around Y axis

rz(qubit, theta)[source]#

Add rotation around Z axis

cnot(control, target)[source]#

Add CNOT gate

cz(control, target)[source]#

Add CZ gate

get_gate_matrix(gate_name, params=None)[source]#

Get the matrix representation of a gate

execute_on_product_state(initial_state=None)[source]#

Execute circuit on a product state Only works if circuit maintains separability

depth()[source]#

Calculate circuit depth

gate_count()[source]#

Count gates by type

__str__()[source]#

String representation of circuit

class atlas_q.quantum_hybrid_system.GPUAccelerator[source]#

Bases: object

GPU acceleration for period-finding and tensor operations

Note: Requires CuPy for actual GPU execution (pip install cupy-cuda12x) This provides the interface and CPU fallback

NEW: GPU modular exponentiation for massive O(√r) speedup

Methods

`accelerated_mps_contraction`(mps, basis_state)	GPU-accelerated MPS tensor contraction
`batched_period_check`(a, N, candidates)	GPU-accelerated batched period checking Uses custom CUDA kernel for maximum performance
`gpu_modular_exponentiation`(a, exponents, N)	GPU-accelerated batch modular exponentiation Computes a^r mod N for many r values in parallel
`parallel_period_check`(a, N, candidates)	Check multiple period candidates in parallel on GPU Falls back to CPU if GPU unavailable or problem is small
`to_cpu`(array)	Move array to CPU
`to_gpu`(array)	Move array to GPU

gpu_modular_exponentiation(a, exponents, N)[source]#

GPU-accelerated batch modular exponentiation Computes a^r mod N for many r values in parallel

This is MUCH faster than sequential pow() calls!

NEW: Uses Triton kernel (3-17× speedup!) if available, falls back to CuPy

batched_period_check(a, N, candidates)[source]#

GPU-accelerated batched period checking Uses custom CUDA kernel for maximum performance

to_gpu(array)[source]#

Move array to GPU

to_cpu(array)[source]#: Move array to CPU

parallel_period_check(a, N, candidates)[source]#

Check multiple period candidates in parallel on GPU Falls back to CPU if GPU unavailable or problem is small

NEW: Uses batched modular exponentiation kernel

accelerated_mps_contraction(mps, basis_state)[source]#

GPU-accelerated MPS tensor contraction

atlas_q.quantum_hybrid_system.demo_compressed_states()[source]#: Demonstrate compressed state representations

atlas_q.quantum_hybrid_system.demo_period_finding()[source]#: Demonstrate period-finding algorithms

atlas_q.quantum_hybrid_system.demo_factorization()[source]#: Demonstrate factorization using hybrid system

atlas_q.quantum_hybrid_system.demo_quantum_circuits()[source]#: Demonstrate quantum circuit emulation

atlas_q.quantum_hybrid_system.demo_gpu_acceleration()[source]#: Demonstrate GPU acceleration

atlas_q.quantum_hybrid_system.demo_advanced_features()[source]#: Demonstrate all advanced features

atlas_q.quantum_hybrid_system.run_comprehensive_demo()[source]#: Run complete demonstration of all features

Overview#

The quantum_hybrid_system module implements compressed quantum state representations and period-finding algorithms for Shor’s factorization algorithm. Key features include:

Memory-efficient quantum state representations (O(1) to O(n) memory)
Analytic QFT for periodic states
Hybrid classical-quantum period-finding
Fast modular exponentiation on GPU
Tensor network support for moderate entanglement

This module enables factorization of large numbers by leveraging the structure of periodic quantum states without requiring exponential memory.

Classes#

`CompressedQuantumState`	Base class for memory-efficient quantum state representations
`PeriodicState`	O(1) memory representation of periodic quantum states Perfect for Shor's algorithm and period-finding
`ProductState`	O(n) memory representation for separable (non-entangled) states
`MatrixProductState`	Tensor network representation for moderate entanglement Memory: O(n × χ²) where χ is bond dimension
`PeriodResult`	Result from period finding
`PeriodFinder`	Collection of O(√r) period-finding algorithms
`QuantumClassicalHybrid`	Main system combining: - Compressed quantum state representations - Classical O(√r) period-finding algorithms - Hybrid approach for optimal performance - Quantum circuit emulation (tensor contractions) - GPU acceleration support (optional)
`QuantumCircuit`	Quantum circuit with tensor network contraction Supports limited depth circuits efficiently
`GPUAccelerator`	GPU acceleration for period-finding and tensor operations

Quantum State Representations#

CompressedQuantumState#

class atlas_q.quantum_hybrid_system.CompressedQuantumState(num_qubits)[source]#

Bases: ABC

Base class for memory-efficient quantum state representations

Methods

`get_amplitude`(basis_state)	Get amplitude for a specific basis state
`get_probability`(basis_state)	Get measurement probability for a basis state
`measure`([num_shots])	Simulate measurement of the quantum state

Abstract base class for memory-efficient quantum state representations. Provides interface for:

Amplitude queries for specific basis states
Probability computations
Measurement sampling (with automatic MPS fallback for large systems)

abstractmethod get_amplitude(basis_state)[source]#

Get amplitude for a specific basis state

get_probability(basis_state)[source]#

Get measurement probability for a basis state

measure(num_shots=1)[source]#

Simulate measurement of the quantum state

For large systems, automatically falls back to MPS sampling

PeriodicState#

class atlas_q.quantum_hybrid_system.PeriodicState(num_qubits, offset=0, period=1)[source]#

Bases: CompressedQuantumState

O(1) memory representation of periodic quantum states Perfect for Shor’s algorithm and period-finding

Represents: |ψ⟩ = 1/√k Σ |offset + j*period⟩

NEW: Analytic QFT sampling for exact/cheap QFT-step emulation

Methods

`get_amplitude`(basis_state)	Constant time amplitude lookup
`get_probability`(basis_state)	Get measurement probability for a basis state
`measure`([num_shots, use_qft])	Simulate measurement of the quantum state
`memory_usage`()	Memory usage in bytes (constant!)
`qft_amplitude`(fourier_state)	Analytic QFT amplitude computation
`sample_qft_measurement`([num_shots])	Sample from QFT of periodic state analytically

O(1) memory representation of periodic quantum states. Perfect for Shor’s algorithm.

Represents states of the form:

\[|\psi\rangle = \frac{1}{\sqrt{k}} \sum_{j=0}^{k-1} |\text{offset} + j \cdot \text{period}\rangle\]

Features analytic QFT sampling for exact period extraction without explicit QFT computation.

get_amplitude(basis_state)[source]#

Constant time amplitude lookup

qft_amplitude(fourier_state)[source]#

Analytic QFT amplitude computation

For a periodic state |ψ⟩ = 1/√k Σⱼ |offset + j*r⟩, QFT gives peaks at multiples of N/r where N = 2^n

This makes QFT-step emulation exact and O(1)!

sample_qft_measurement(num_shots=1)[source]#

Sample from QFT of periodic state analytically

This is EXACT and much faster than computing full QFT! Returns measurements that would result from measuring after QFT.

measure(num_shots=1, use_qft=False)[source]#

Simulate measurement of the quantum state

Args:: num_shots: Number of measurements use_qft: If True, sample from QFT of state (for Shor’s algorithm)

memory_usage()[source]#

Memory usage in bytes (constant!)

ProductState#

class atlas_q.quantum_hybrid_system.ProductState(num_qubits)[source]#

Bases: CompressedQuantumState

O(n) memory representation for separable (non-entangled) states

Represents: |ψ⟩ = |ψ₀⟩ ⊗ |ψ₁⟩ ⊗ … ⊗ |ψₙ₋₁⟩

Methods

`apply_hadamard`(qubit)	Apply Hadamard gate in O(1) time
`apply_x`(qubit)	Apply X (NOT) gate in O(1) time
`get_amplitude`(basis_state)	O(n) amplitude calculation
`get_probability`(basis_state)	Get measurement probability for a basis state
`measure`([num_shots])	Simulate measurement of the quantum state
`memory_usage`()	Memory usage in bytes

O(n) memory representation for product (unentangled) states:

\[|\psi\rangle = |\psi_1\rangle \otimes |\psi_2\rangle \otimes \cdots \otimes |\psi_n\rangle\]

Efficient for states with no entanglement.

get_amplitude(basis_state)[source]#

O(n) amplitude calculation

apply_hadamard(qubit)[source]#

Apply Hadamard gate in O(1) time

apply_x(qubit)[source]#

Apply X (NOT) gate in O(1) time

memory_usage()[source]#

Memory usage in bytes

MatrixProductState#

class atlas_q.quantum_hybrid_system.MatrixProductState(num_qubits, bond_dim=8)[source]#

Bases: CompressedQuantumState

Tensor network representation for moderate entanglement Memory: O(n × χ²) where χ is bond dimension

Can simulate 50-100 qubits with controlled entanglement!

NEW: MPS canonicalization and sweep sampling for accurate measurements

Methods

`canonicalize_left_to_right`()	Bring MPS into left-canonical form using QR decomposition
`canonicalize_right_to_left`()	Bring MPS into right-canonical form using QR decomposition
`get_amplitude`(basis_state)	Contract MPS to get amplitude - O(n × χ²)
`get_probability`(basis_state)	Get measurement probability for a basis state
`measure`([num_shots])	Simulate measurement with accurate MPS sampling
`memory_usage`()	Memory usage in bytes
`sweep_sample`([num_shots])	Accurate MPS sampling using conditional probabilities sweep

O(n·χ²) memory representation for moderately entangled states using tensor networks. Provides:

Sweep-based sampling
Canonical form transformations
SVD-based compression

canonicalize_left_to_right()[source]#

Bring MPS into left-canonical form using QR decomposition

Each tensor satisfies: Σₛ Aˢ†Aˢ = I (left-orthogonal) This enables efficient sampling and norm computation!

canonicalize_right_to_left()[source]#

Bring MPS into right-canonical form using QR decomposition

Each tensor satisfies: Σₛ AˢAˢ† = I (right-orthogonal)

sweep_sample(num_shots=1)[source]#

Accurate MPS sampling using conditional probabilities sweep

This is the CORRECT way to sample from MPS! Complexity: O(num_shots × n × χ²)

measure(num_shots=1)[source]#

Simulate measurement with accurate MPS sampling

Uses sweep sampling for correct probability distribution

get_amplitude(basis_state)[source]#

Contract MPS to get amplitude - O(n × χ²)

memory_usage()[source]#

Memory usage in bytes

Period-Finding#

PeriodResult#

class atlas_q.quantum_hybrid_system.PeriodResult(period, method, time_seconds, attempts=1)[source]#

Bases: object

Result from period finding

Dataclass storing period-finding results:

Detected period (r)
Confidence score
Execution time
Success flag

period: int | None#

method: str#

time_seconds: float#

attempts: int = 1#

PeriodFinder#

class atlas_q.quantum_hybrid_system.PeriodFinder[source]#

Bases: object

Collection of O(√r) period-finding algorithms

Methods

`baby_step_giant_step`(a, N[, m])	Baby-step giant-step algorithm Complexity: O(√r) time and space
`collision_detection`(a, N[, num_samples])	Birthday paradox collision detection Complexity: O(√r) expected
`parallel_candidate_search`(a, N[, max_candidates])	Generate smart candidates and check them In real implementation, this would be GPU-parallelized
`pollards_rho`(a, N[, max_iter])	Floyd's cycle detection algorithm Complexity: O(√r) average case
`smart_factorization`(a, N)	Check if period has small factors Complexity: O(k) where k is number of candidates

Core period-finding algorithm using O(√r) complexity hybrid approach:

Classical preprocessing for small periods
Quantum period detection for medium periods
Continued fractions for period extraction

static smart_factorization(a, N)[source]#

Check if period has small factors Complexity: O(k) where k is number of candidates

static pollards_rho(a, N, max_iter=100000)[source]#

Floyd’s cycle detection algorithm Complexity: O(√r) average case

Uses tortoise and hare to detect cycles in sequence: 1, a mod N, a² mod N, a³ mod N, …

static collision_detection(a, N, num_samples=None)[source]#

Birthday paradox collision detection Complexity: O(√r) expected

Sample random points, find collision f(x₁) = f(x₂) Then period divides |x₁ - x₂|

static baby_step_giant_step(a, N, m=None)[source]#

Baby-step giant-step algorithm Complexity: O(√r) time and space

Finds period by solving a^x ≡ 1 (mod N)

static parallel_candidate_search(a, N, max_candidates=1000)[source]#

Generate smart candidates and check them In real implementation, this would be GPU-parallelized

QuantumClassicalHybrid#

class atlas_q.quantum_hybrid_system.QuantumClassicalHybrid(verbose=True, use_gpu=True)[source]#

Bases: object

Methods

`create_circuit`(num_qubits)	Create a new quantum circuit
`create_mps_state`(num_qubits[, bond_dim])	Create a tensor network (MPS) quantum state
`create_periodic_state`(num_qubits, period)	Create a compressed periodic quantum state
`create_product_state`(num_qubits)	Create a compressed product (separable) quantum state
`execute_circuit`(circuit[, backend])	Execute a quantum circuit using tensor contractions
`factor_number`(N[, max_attempts])	Factor N using period-finding (Shor's algorithm approach)
`find_period`(a, N[, method])	Find period of a^x mod N
`find_period_gpu`(a, N)	GPU-accelerated period finding Falls back to CPU if GPU unavailable

Complete factorization system combining:

Period-finding via quantum simulation
Classical GCD for factor extraction
Trial division for small factors
Automatic fallback strategies

Primary interface for factoring integers.

find_period(a, N, method='auto')[source]#

Find period of a^x mod N

Args:: a: Base N: Modulus method: “auto” (tries all), or specific method name
Returns:: PeriodResult with period, method used, and timing

factor_number(N, max_attempts=20)[source]#

Factor N using period-finding (Shor’s algorithm approach)

Returns:: Tuple of (factor1, factor2) if successful, None otherwise

create_periodic_state(num_qubits, period)[source]#

Create a compressed periodic quantum state

create_product_state(num_qubits)[source]#

Create a compressed product (separable) quantum state

create_mps_state(num_qubits, bond_dim=8)[source]#

Create a tensor network (MPS) quantum state

create_circuit(num_qubits)[source]#

Create a new quantum circuit

execute_circuit(circuit, backend='auto')[source]#

Execute a quantum circuit using tensor contractions

Args:: circuit: The quantum circuit to execute backend: “product” (separable only), “mps” (tensor network),

or “auto” (choose automatically based on gates)
Returns:: The final quantum state

find_period_gpu(a, N)[source]#

GPU-accelerated period finding Falls back to CPU if GPU unavailable

Supporting Classes#

QuantumCircuit#

class atlas_q.quantum_hybrid_system.QuantumCircuit(num_qubits)[source]#

Bases: object

Quantum circuit with tensor network contraction Supports limited depth circuits efficiently

Methods

`add_gate`(gate_name, qubit[, params])	Add a gate to the circuit
`cnot`(control, target)	Add CNOT gate
`cz`(control, target)	Add CZ gate
`depth`()	Calculate circuit depth
`execute_on_product_state`([initial_state])	Execute circuit on a product state Only works if circuit maintains separability
`gate_count`()	Count gates by type
`get_gate_matrix`(gate_name[, params])	Get the matrix representation of a gate
`h`(qubit)	Add Hadamard gate
`rx`(qubit, theta)	Add rotation around X axis
`ry`(qubit, theta)	Add rotation around Y axis
`rz`(qubit, theta)	Add rotation around Z axis
`x`(qubit)	Add X (NOT) gate
`y`(qubit)	Add Y gate
`z`(qubit)	Add Z gate

Quantum circuit builder for period-finding circuits. Supports:

Gate application (H, CNOT, phase gates)
Modular exponentiation circuits
QFT implementation

add_gate(gate_name, qubit, params=None)[source]#

Add a gate to the circuit

h(qubit)[source]#

Add Hadamard gate

x(qubit)[source]#

Add X (NOT) gate

y(qubit)[source]#

Add Y gate

z(qubit)[source]#

Add Z gate

rx(qubit, theta)[source]#

Add rotation around X axis

ry(qubit, theta)[source]#

Add rotation around Y axis

rz(qubit, theta)[source]#

Add rotation around Z axis

cnot(control, target)[source]#

Add CNOT gate

cz(control, target)[source]#

Add CZ gate

get_gate_matrix(gate_name, params=None)[source]#

Get the matrix representation of a gate

execute_on_product_state(initial_state=None)[source]#

Execute circuit on a product state Only works if circuit maintains separability

depth()[source]#

Calculate circuit depth

gate_count()[source]#

Count gates by type

__str__()[source]#

String representation of circuit

GPUAccelerator#

class atlas_q.quantum_hybrid_system.GPUAccelerator[source]#

Bases: object

GPU acceleration for period-finding and tensor operations

Note: Requires CuPy for actual GPU execution (pip install cupy-cuda12x) This provides the interface and CPU fallback

NEW: GPU modular exponentiation for massive O(√r) speedup

Methods

`accelerated_mps_contraction`(mps, basis_state)	GPU-accelerated MPS tensor contraction
`batched_period_check`(a, N, candidates)	GPU-accelerated batched period checking Uses custom CUDA kernel for maximum performance
`gpu_modular_exponentiation`(a, exponents, N)	GPU-accelerated batch modular exponentiation Computes a^r mod N for many r values in parallel
`parallel_period_check`(a, N, candidates)	Check multiple period candidates in parallel on GPU Falls back to CPU if GPU unavailable or problem is small
`to_cpu`(array)	Move array to CPU
`to_gpu`(array)	Move array to GPU

GPU-accelerated modular exponentiation and tensor operations. Provides 100-1000× speedup over CPU for period-finding.

gpu_modular_exponentiation(a, exponents, N)[source]#

GPU-accelerated batch modular exponentiation Computes a^r mod N for many r values in parallel

This is MUCH faster than sequential pow() calls!

NEW: Uses Triton kernel (3-17× speedup!) if available, falls back to CuPy

batched_period_check(a, N, candidates)[source]#

GPU-accelerated batched period checking Uses custom CUDA kernel for maximum performance

to_gpu(array)[source]#

Move array to GPU

to_cpu(array)[source]#: Move array to CPU

parallel_period_check(a, N, candidates)[source]#

Check multiple period candidates in parallel on GPU Falls back to CPU if GPU unavailable or problem is small

NEW: Uses batched modular exponentiation kernel

accelerated_mps_contraction(mps, basis_state)[source]#

GPU-accelerated MPS tensor contraction

Examples#

Basic factorization:

from atlas_q import get_quantum_sim

# Get factorization system
QCH, _, _, _ = get_quantum_sim()

# Factor a number
sim = QCH()
factors = sim.factor_number(221)

print(f"221 = {factors[0]} × {factors[1]}")  # Output: 221 = 13 × 17

Using PeriodicState:

from atlas_q.quantum_hybrid_system import PeriodicState

# Create periodic state with period=7, offset=3, in 20-qubit space
state = PeriodicState(
    num_qubits=20,
    period=7,
    offset=3
)

# Query amplitude (O(1) operation, no memory usage)
amp = state.get_amplitude(10)  # |10⟩
prob = state.get_probability(10)

print(f"Amplitude: {amp}")
print(f"Probability: {prob}")

# Sample measurements (uses analytic QFT)
samples = state.measure(num_shots=1000)
print(f"Sample: {samples[0]} (binary: {bin(samples[0])})")

Direct period-finding:

from atlas_q.quantum_hybrid_system import PeriodFinder

finder = PeriodFinder()

# Find period of a^x mod N
result = finder.find_period(a=7, N=15, num_qubits=8)

if result.success:
    print(f"Period: {result.period}")
    print(f"Confidence: {result.confidence:.2%}")
    print(f"Time: {result.time_sec:.3f}s")

Using MPS for entangled states:

from atlas_q.quantum_hybrid_system import MatrixProductState
import numpy as np

# Create MPS with bond dimension 16
mps = MatrixProductState(num_qubits=30, bond_dim=16)

# Apply gates to create entanglement
# (This is a simplified example; in practice use AdaptiveMPS)

# Sample from the state
samples = mps.measure(num_shots=100)
print(f"Sampled states: {samples[:10]}")

GPU-accelerated modular exponentiation:

from atlas_q.quantum_hybrid_system import GPUAccelerator

gpu = GPUAccelerator()

# Compute a^x mod N on GPU
a, N = 7, 221
x_values = list(range(100))

results = gpu.batch_modular_exp(a, x_values, N)
print(f"7^50 mod 221 = {results[50]}")

Advanced: Custom factorization with parameters:

from atlas_q import get_quantum_sim

QCH, _, _, _ = get_quantum_sim()

sim = QCH()

# Factor with custom parameters
N = 10403  # Product of two primes

# Attempt factorization
try:
    factors = sim.factor_number(N)
    if factors:
        p, q = factors
        print(f"{N} = {p} × {q}")
        assert p * q == N
except ValueError as e:
    print(f"Factorization failed: {e}")

Performance Characteristics#

Memory Usage#

PeriodicState: O(1) - constant memory regardless of qubit count
ProductState: O(n) - linear in qubit count
MatrixProductState: O(n·χ²) - depends on bond dimension χ

Computational Complexity#

Period-finding: O(√r) average case with quantum acceleration
Classical preprocessing: O(log N) for trial division
Modular exponentiation: O(log N) per operation
GPU acceleration: 100-1000× speedup over CPU

Applications#

Shor’s Algorithm#

The primary application is Shor’s factorization algorithm:

Choose random a < N
Find period r of f(x) = a^x mod N using QuantumClassicalHybrid
If r is even and a^(r/2) ≠ -1 mod N, factors are gcd(a^(r/2) ± 1, N)
Repeat if unsuccessful

Period-Finding in Cryptography#

Beyond factorization, period-finding has applications in:

Discrete logarithm problem
Order-finding in groups
Hidden subgroup problem

Best Practices#

Parameter Selection

register_size: Use 2n+1 bits for n-bit numbers (ensures sufficient precision)
chi_max: 32-64 sufficient for period-finding up to 10-12 qubits
samples: 1000-10000 for reliable period detection

Optimization

Use GPU for circuits with > 15 qubits
Enable statistics tracking to monitor entanglement
Batch multiple period-finding runs for different bases
Cache QFT circuit if running multiple times

Troubleshooting

Wrong period detected: Increase register_size or samples
Memory errors: Reduce chi_max or circuit size
Slow performance: Enable GPU, use Triton kernels

Use Cases#

Educational

Teaching Shor’s algorithm concepts
Demonstrating quantum speedup
Period-finding problem examples

Research

Benchmarking quantum simulators
Studying entanglement in hybrid algorithms
Developing improved factorization methods

Not Suitable For

Actual cryptographic attacks (classical algorithms faster for practical key sizes)
Production cryptography (use battle-tested libraries)

References#

[Shor94]

1. Shor, “Algorithms for quantum computation: Discrete logarithms and factoring,” FOCS 1994 (1994).

[Nielsen10]

1. Nielsen & I. L. Chuang, Quantum Computation and Quantum Information, Cambridge University Press (2010).

[Mosca01]

Mosca, “The quantum order finding algorithm,” arXiv:quant-ph/0110167 (2001).

atlas_q.quantum_hybrid_system#

Overview#

Classes#

Quantum State Representations#

CompressedQuantumState#

PeriodicState#

ProductState#

MatrixProductState#

Period-Finding#

PeriodResult#

PeriodFinder#

QuantumClassicalHybrid#

Supporting Classes#

QuantumCircuit#

GPUAccelerator#

Examples#

Performance Characteristics#

Memory Usage#

Computational Complexity#

Applications#

Shor’s Algorithm#

Period-Finding in Cryptography#

Best Practices#

Use Cases#

See Also#

References#