Metadata-Version: 2.4
Name: lqft-python-engine
Version: 1.0.8
Summary: LQFT Engine: native C extension with bounded-depth lookups and structural sharing
Home-page: https://github.com/ParjadM/Log-Quantum-Fractal-Tree-LQFT-
Author: Parjad Minooei
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C
Classifier: Operating System :: OS Independent
Classifier: Topic :: Database :: Database Engines/Servers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: psutil
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Log-Quantum Fractal Tree (LQFT) 🚀

[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](#)
[![C-Engine](https://img.shields.io/badge/Native-C-red.svg)](#)
[![Concurrency](https://img.shields.io/badge/Concurrency-Benchmark_Dependent-yellow.svg)](#)
[![Architecture](https://img.shields.io/badge/Architecture-Merkle_HAMT-pink.svg)](#)
[![License](https://img.shields.io/badge/License-MIT-red.svg)](LICENSE.md)

## 📌 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 Snapshot (v1.0.8 Stable)

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

| Metric | Current Observation | Architectural Driver |
| :--- | :--- | :--- |
| **Insert Throughput (wrapper microbench)** | **~600k ops/sec class** | Buffered batch writes + native C bulk path |
| **Search Throughput (wrapper microbench)** | **~900k ops/sec class** | Fixed-depth traversal + native search path |
| **Memory Density** | **~104 Bytes / Node** | NUMA-Aware Slab Allocator (Background Daemon) |
| **Space Efficiency** | **1,500x Reduction** | Global Atomic Pool Stealing & Merkle-DAG Folding |

Benchmark note: Throughput is workload- and environment-dependent. Use the repo benchmark scripts to reproduce numbers for your hardware.

## 🧠 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.

```bash
# 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.

```python
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")

# Native Search (throughput depends on workload/profile)
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).
