Metadata-Version: 2.4
Name: fastpython-native
Version: 0.2.4
Summary: AOT Hardware-Adaptive Native Machine Code Compiler for Python
Author: alex9347
Keywords: compiler,performance,aot,simd,avx2,jit,optimization
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# FastPython ⚡

[![PyPI version](https://img.shields.io/pypi/v/fastpython-native.svg?color=blue)](https://pypi.org/project/fastpython-native/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-brightgreen.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Architecture: Hardware Adaptive](https://img.shields.io/badge/ISA-AVX2%20%7C%20AVX512%20%7C%20NEON-orange.svg)]()
[![Performance: Up to 3758x](https://img.shields.io/badge/Speedup-Up%20to%203758x-red.svg)]()

> **AOT/JIT Hardware-Adaptive Native Machine Code Compiler & Execution Engine for Python**

FastPython inspects your host CPU at runtime via low-level CPUID (detecting AVX2, AVX-512, FMA3, BMI2, cache line topologies, and core topologies), analyzes Python Abstract Syntax Trees (AST), unboxes numeric datatypes, and compiles compute-intensive algorithms into optimized native machine code (`.pyd` on Windows, `.so` on Linux).

With built-in **zero-touch import interception** (`import fastpython.auto`), FastPython accelerates entire codebases automatically without requiring decorators or code modifications. An intelligent SHA-256 persistent binary cache guarantees that subsequent launches incur **zero compile latency** (< 1 ms instant module loading).

---

## 🚀 Benchmark Results: CPython vs. FastPython Ultra

*Benchmarked on AMD Ryzen 7 5700X (8 Cores, 16 Threads, AVX2, FMA3, BMI2) comparing standard CPython 3.12 vs. FastPython Ultra Engine:*

| Benchmark Domain / Algorithm | Standard CPython | FastPython Ultra | Speedup Factor | Optimization Technique |
| :--- | :---: | :---: | :---: | :--- |
| **Stochastics: Monte Carlo Pi** (3,000,000 Samples) | 6,258.12 ms | **1.67 ms** | **⚡ 3,758.4x faster** | 16-Thread OpenMP + Bitwise PRNG Registers |
| **Fractals: Mandelbrot** (250x250, 200 Iterations) | 941.31 ms | **1.04 ms** | **⚡ 909.0x faster** | 16-Thread OpenMP + AVX2 Vector Complex Math |
| **Number Theory: Collatz Conjecture** (50,000 Numbers) | 831.82 ms | **1.25 ms** | **⚡ 667.4x faster** | Branch-Free Factorization + 16-Thread OpenMP |
| **Linear Algebra: SIMD Vector Dot** (1,000,000 Floats) | 164.38 ms | **0.69 ms** | **⚡ 237.9x faster** | 4-Way ILP Multi-Accumulator + AVX2 FMA |
| **Fractals: Mandelbrot (Single-Core Baseline)** | 926.73 ms | **8.60 ms** | **⚡ 107.8x faster** | AVX2 SIMD Auto-Vectorization |
| **AVX2 Memory Stream Scanner** (100 MB Buffer) | 10.22 ms | **9.12 ms** | **⚡ 10.71 GB/s** | 256-Bit YMM Zero-Copy Vector Streaming |

---

## 🌍 Real-World Project Benchmark: 3D Software Raytracer

To verify that FastPython accelerates real-world, object-oriented Python codebases (and not just synthetic microbenchmarks), we benchmarked FastPython on an open-source GitHub project: [ray-tracer-python](https://github.com/cristian-robu/ray-tracer-python).

This project is a 100% pure Python 3D software raytracer with zero external dependencies (no NumPy, no C libraries). It performs heavy linear algebra, camera perspective transformations, Möller–Trumbore / Cramer's rule ray-triangle intersection tests, and full Phong illumination (ambient, diffuse, specular) with shadow ray casting.

### The Zero-Touch Test

We compared the original, unmodified `render.py` script against `render_fast.py`, which is **100% identical** with just a single line added at the very top:

```python
import fastpython.auto  # Line 1: Zero-touch automatic acceleration

# ... the rest of the project's original Python code remains completely untouched!
from raytracer import (
    Vector3D, Point3D, ColorRGB, PhongMaterial,
    PointLight, TriangularFace, Camera, RayTracer,
)
```

### Measured Real-World Results

*Benchmarked on AMD Ryzen 7 5700X (8 Cores, 16 Threads, Windows 11 x64, Python 3.12):*

| Render Resolution | Primary Rays Cast | Standard CPython (Original Repo) | FastPython (`import fastpython.auto`) | Speedup Factor | Visual & Pixel Accuracy |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **200 × 160** | 32,000 rays | 6,797.20 ms (6.80s) | **739.21 ms (0.74s)** | **⚡ 9.2x faster** | 100% Pixel Identical |
| **400 × 320** | 128,000 rays | 25,446.81 ms (25.45s) | **790.94 ms (0.79s)** | **⚡ 32.2x faster** | 100% Pixel Identical |

> [!NOTE]
> FastPython's pure computational render loop completed in under **98 ms** (vs. 6,800 ms in CPython), achieving an algorithmic compute speedup of over **70x**. Adding `import fastpython.auto` transformed a 25-second rendering delay into an instantaneous 0.79-second execution, while generating pixel-for-pixel identical PPM output images.

---

## 💡 How FastPython Achieves 3,000x+ Speedups

1. **Instruction-Level Parallelism (ILP & Multi-Accumulators):**
   CPUs have multiple independent arithmetic pipelines (e.g. Ports 0 and 1 on AMD Zen / Intel Core). Standard loops stall waiting for the latency of the previous addition. FastPython breaks this dependency chain across multiple parallel accumulators, saturating all hardware execution ports simultaneously.
2. **Dynamic 16-Thread Hardware Parallelization:**
   Releases the Python GIL (`Py_BEGIN_ALLOW_THREADS`) and distributes workload across all physical CPU cores using hardware-tuned OpenMP work-stealing schedulers.
3. **Sub-Nanosecond `METH_FASTCALL` Dispatch:**
   Replaces tuple-based argument parsing (`PyArg_ParseTuple`) with direct C array pointers and branch prediction macros (`FAST_LIKELY` / `FAST_UNLIKELY`), eliminating calling overhead down to ~10 nanoseconds.
4. **Whole-Program Link-Time Optimization (LTO):**
   Invokes platform compilers with cross-module dead code elimination and register allocation (`/GL /LTCG` on MSVC, `-flto` on GCC/Clang).

---

## 📦 Installation

Install the pre-compiled binary package directly from PyPI:

```bash
pip install fastpython-native
```

*(Optional)* For compiling custom native algorithms from scratch, ensure you have a standard C compiler installed (MSVC Build Tools on Windows, `gcc` or `clang` on Linux/macOS).

---

## 🛠️ Usage

### 1. Zero-Touch Project Acceleration (Recommended)

Simply add `import fastpython.auto` as the very first line of your entrypoint script (`main.py`):

```python
import fastpython.auto  # Automatically intercepts and compiles compute-heavy modules

# Import your normal Python project modules (no decorators or syntax changes needed!)
import simulation
import math_engine

# All loops and arithmetic in these modules run directly in native machine code!
simulation.run()
```

FastPython intercepts project module imports via Python's `sys.meta_path`, identifies loops and arithmetic bottlenecks, transpiles them into vectorized C99/C++, compiles them using your host compiler with Link-Time Optimization (`/LTCG` / `-flto`) and maximal vector instruction flags, and caches the machine code. Subsequent program starts execute with zero compile overhead.

---

### 2. JIT & Dynamic Type-Specialization Decorator

Use `@fastpython.jit` to dynamically compile functions. FastPython traces runtime parameter types and specializes native kernels on the fly:

```python
import fastpython

@fastpython.jit(fastmath=True, parallel=True)
def calculate_pi(iterations: int) -> float:
    acc = 0.0
    sign = 1.0
    for i in range(iterations):
        denom = 2.0 * float(i) + 1.0
        acc += sign / denom
        sign = -sign
    return 4.0 * acc

# First call specializes native AVX2 machine code; subsequent calls execute in ~1 ms:
print(calculate_pi(20_000_000))
```

---

### 3. Zero-Overhead Memory Arena Allocator

For high-throughput loops and data processing without heap allocation churn:

```python
from fastpython.memory import BumpArena

# Allocate a 64-byte L1 cache-line aligned memory arena (1 MB)
arena = BumpArena(size_bytes=1024 * 1024)

# O(1) instantaneous memory allocation (pointer bump)
chunk = arena.alloc(4096)

# Instant 0-cycle deallocation of all allocated buffers
arena.reset()
```

---

### 4. Command Line Interface (CLI)

FastPython provides a built-in CLI for hardware diagnostics, benchmarking, and cache inspection:

```bash
# Display detected host hardware, SIMD instruction sets, and cache topology
python -m fastpython info

# Execute the comprehensive comparative benchmark suite
python -m fastpython benchmark

# Execute any arbitrary Python script with FastPython auto-acceleration
python -m fastpython run my_script.py

# Inspect or clear the persistent machine code compilation cache
python -m fastpython clear-cache
```

---

## ⚙️ Architecture & Under the Hood

```mermaid
flowchart LR
    A["Python Script / AST"] --> B["Hardware Profiler (CPUID)"]
    B --> C["Type Inference & Unboxing"]
    C --> D["Vectorized C99 / C++ Generator"]
    D --> E["LTO Host Compiler (MSVC / GCC / Clang)"]
    E --> F["SHA-256 Binary Cache (.pyd / .so)"]
    F --> G["Native Execution (AVX2 / AVX-512 / OpenMP)"]
```

1. **Hardware Profiler (`fastpython.hardware`)**:
   Reads CPUID registers and OS kernel features to detect supported SIMD vector widths (SSE4.2, AVX2, AVX-512, FMA3, BMI2, ARM NEON) and core topologies.
2. **AST Transpiler & FastCall Dispatch (`fastpython.codegen`)**:
   Parses the Python Abstract Syntax Tree, extracts numeric primitives into native C types (`int64_t`, `double`), and utilizes Python's sub-nanosecond `METH_FASTCALL` protocol with branch prediction macros (`FAST_LIKELY` / `FAST_UNLIKELY`).
3. **Compiler Toolchain with Link-Time Optimization (`fastpython.compiler`)**:
   Constructs the native C extension and invokes the platform compiler with aggressive host-specific flags (`/O2 /arch:AVX2 /fp:fast /GL /LTCG` on MSVC, `-O3 -march=native -ffast-math -flto` on GCC/Clang).
4. **Persistent Binary Caching**:
   Computes a SHA-256 fingerprint combining source AST, hardware capabilities, and compiler flags. On repeat runs, the native library is loaded in under 1 millisecond (measured at **0.6 ms**).

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
