lqft-python-engine 1.0.3

LQFT Engine: 14.3M Ops/sec O(1) Time | O(Σ) Space Data Structure

Log-Quantum Fractal Tree (LQFT) 🚀

📌 Project Overview

The Log-Quantum Fractal Tree (LQFT) is a high-performance, scale-invariant data structure engine designed for massive data deduplication and persistent state management. Synthesizing Hash Array Mapped Trie (HAMT) routing with Merkle-DAG structural folding, the LQFT provides deterministic $O(1)$ search latency and sub-linear $O(\Sigma)$ space complexity.

Status: Code Frozen (March 2026) for the BFS/DFS Visual Mastery Sprint.

---

🏆 Performance Certification (v1.0.3 Stable)

Verified Environment: Python 3.12 | MSYS2/MinGW64 GCC -O3 | 16-Core Physical Affinity

Metric	Certified Result	Architectural Driver
Peak Throughput	14,395,262 ops/sec	Native OS Thread Affinity & Zero-Copy FFI
Search Latency	< 100 ns (L1 Cache)	Grandchild Look-Ahead Software Prefetching
Memory Density	~104 Bytes / Node	NUMA-Aware Slab Allocator (Background Daemon)
Space Efficiency	1,500x Reduction	Global Atomic Pool Stealing & Merkle-DAG Folding

🧠 Core Architecture

1. Hardware Synchronization (Thread Affinity & NUMA)

The LQFT explicitly pins OS threads to physical CPU cores to prevent scheduler migrations, guaranteeing that hot memory paths remain in the L1/L2 cache. Memory is mapped using MAP_POPULATE and VirtualAlloc to guarantee NUMA-local hardware proximity.

2. Lock-Free Search & Optimistic Concurrency

Read operations are 100% lock-free (RCU-inspired). Threads traverse the trie without acquiring mutexes or triggering atomic cache-line invalidations. Deallocations are deferred to Thread-Local Retirement Chains, eliminating global contention.

3. Scale-Invariant Big-O Complexity

The LQFT utilizes a fixed 64-bit hash space partitioned into 13 segments.

• Time Complexity: $O(1)$ — Every traversal requires exactly 13 hardware instructions.
• Space Complexity: $O(\Sigma)$ — Identical branches are folded into single pointers, mapping physical space to data entropy rather than data volume.

---

🛠️ Getting Started

Installation

The engine requires a C compiler (GCC/MinGW or MSVC) to build the native extension.

# Clone the repository
git clone [https://github.com/ParjadM/Log-Quantum-Fractal-Tree-LQFT-.git](https://github.com/ParjadM/Log-Quantum-Fractal-Tree-LQFT-.git)
cd Log-Quantum-Fractal-Tree-LQFT-

# Build the native C-extension with highest hardware optimizations
python setup.py build_ext --inplace

The FFI Bridge (Python)

The core engine handles massive state spaces seamlessly behind a high-level wrapper.

import lqft_c_engine

# High-Speed Zero-Copy Batching
# Send raw C-arrays directly to the engine to bypass the GIL entirely
lqft_c_engine.insert_batch_raw(bytes(raw_buffer_array), "enterprise_payload")

# 14.3M Ops/sec Native Search
result = lqft_c_engine.search(0x123456789ABCDEF)

# Fetch internal hardware metrics
metrics = lqft_c_engine.get_metrics()
print(metrics['physical_nodes']) 

⚖️ License

MIT License - Parjad Minooei (2026).