lqft-python-engine 0.7.0

LQFT Engine: Strict Native C-Core & Hardware Concurrency (v0.7.0 Stable)

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. It synthesizes Hash Array Mapped Trie (HAMT) routing with Merkle-DAG structural folding to provide deterministic $O(1)$ search latency and sub-linear $O(\Sigma)$ space complexity.

By offloading core associative logic to a native C-Extension, the LQFT completely bypasses the Python Global Interpreter Lock (GIL), providing true hardware concurrency and significant memory reduction for versioned, redundant, or patterned datasets.

---

🧠 Core Architecture (v0.7.0 Strict Native Release)

1. Strict C-Core Enforcement (New in v0.7.0)

The legacy pure-Python fallback heuristics have been entirely stripped out. The LQFT now operates strictly as a zero-overhead FFI wrapper directly communicating with the underlying unmanaged C memory heap.

2. True Hardware Concurrency & GIL Bypass

The engine utilizes native OS-level read-write locks (SRWLOCK on Windows, pthread_rwlock_t on POSIX) combined with Py_BEGIN_ALLOW_THREADS.

• Multi-Core Scaling: Multiple Python threads can read and write to the Merkle-DAG simultaneously across all physical CPU cores without Segmentation Faults.
• Zero GIL Contention: The C-Engine entirely decouples from the Python interpreter during execution.

3. Scale-Invariant Time Complexity: $O(1)$

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

• Deterministic Latency: Every search or insertion requires exactly 13 pointer hops.
• Scale-Invariance: Performance remains constant whether the dataset contains 10^3 or 10^9 items.

4. Entropy-Based Space Complexity: $O(\Sigma)$

Nodes are identified by the cryptographic hash of their contents and child pointers (Merkle-DAG).

• Structural Folding: Identical sub-trees are shared physically in memory across different branches or versions.

---

🚀 Performance Benchmarks

Environment: Python 3.12 | GCC -O3 | MSYS2/MinGW64

Metric	Result
Search Latency (p50)	~500 ns
Concurrent Throughput	~1.8 Million ops/sec (Across 10 OS Threads)
Space Efficiency	Up to 1,500x reduction in versioned graph simulations
Stability	100% Memory Safe under massive multi-threaded turnover

---

🛠️ 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
python setup.py build_ext --inplace

Basic Usage

The LQFT provides a Pythonic interface to its high-performance C-backend.

from lqft_engine import LQFT
import threading

# Initialize the Strict Native Engine
db = LQFT()

# The C-Engine releases the GIL, allowing true multi-threading
def worker(thread_id):
    for i in range(10000):
        db.insert(f"thread_{thread_id}_key_{i}", "enterprise_payload")

threads = [threading.Thread(target=worker, args=(t,)) for t in range(4)]
for t in threads: t.start()
for t in threads: t.join()

# --- Native Disk Persistence ---
db.save_to_disk("production_state.bin")
db.clear()
db.load_from_disk("production_state.bin")

---

⚖️ License

This project is licensed under the MIT License - see the LICENSE.md file for details.