foxpi 0.1.0__py3-none-any.whl

cli.py

@@ -0,0 +1,115 @@
+# cli.py
+#!/usr/bin/env python3
+"""
+FoxPi — High-precision π & mathematical explorer
+"""
+
+import sys
+import time
+import argparse
+from pathlib import Path
+from typing import List
+
+from core.algorithms import (
+    get_ramanujan_pi_terms,
+    get_chudnovsky_pi_terms,
+    compute_chudnovsky_pi,
+    compute_machin_pi,
+    generate_bbp_spigot,
+    isqrt,
+)
+from core.visualize import render_convergence_table, render_comparison
+
+def main():
+    parser = argparse.ArgumentParser(prog="foxpi", description="High-precision π explorer 🦊")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    # digits command
+    d = sub.add_parser("digits", help="Compute N digits of π")
+    d.add_argument("count", type=int, help="Number of decimal digits")
+    d.add_argument("--method", choices=["ramanujan", "chudnovsky", "machin"], default="chudnovsky")
+
+    # explore command
+    e = sub.add_parser("explore", help="Live convergence visualisation")
+    e.add_argument("--method", choices=["ramanujan", "chudnovsky"], default="ramanujan")
+    e.add_argument("--terms", type=int, default=30)
+
+    # compare command
+    sub.add_parser("compare", help="Benchmark multiple algorithms")
+
+    # bbp spigot
+    b = sub.add_parser("bbp", help="Extract hexadecimal digits using BBP formula")
+    b.add_argument("position", type=int, default=1, help="Starting digit position (1 = first after decimal)")
+
+    args = parser.parse_args()
+
+    if args.cmd == "digits" and args.count < 0:
+        print(f"Error: digit count must be >= 0 (got {args.count}).", file=sys.stderr)
+        sys.exit(1)
+    if args.cmd == "bbp" and args.position < 1:
+        print(f"Error: position must be >= 1 (got {args.position}); 1 is the first hex digit after the point.", file=sys.stderr)
+        sys.exit(1)
+    if args.cmd == "explore" and args.terms < 1:
+        print(f"Error: --terms must be >= 1 (got {args.terms}).", file=sys.stderr)
+        sys.exit(1)
+
+    if args.cmd == "digits":
+        # Python 3.11+ caps int->str conversion at 4300 digits by default;
+        # raise it to fit the requested precision (plus a small margin).
+        sys.set_int_max_str_digits(max(4300, args.count + 20))
+
+        start = time.perf_counter()
+        if args.method == "chudnovsky":
+            pi_int = compute_chudnovsky_pi(args.count)
+        elif args.method == "ramanujan":
+            # Take last term
+            last = None
+            for term in get_ramanujan_pi_terms(args.count):
+                last = term
+            pi_int = last[1]
+        else:  # machin
+            pi_int = compute_machin_pi(args.count)
+
+        elapsed = time.perf_counter() - start
+        pi_str = str(pi_int)
+        print(f"\nπ ({args.count} digits) using {args.method.capitalize()}:")
+        print(f"{pi_str[0]}.{pi_str[1:]}")
+        print(f"Time: {elapsed:.4f}s")
+
+    elif args.cmd == "explore":
+        print(f"Exploring convergence with {args.method}...\n")
+        history = []
+        gen = get_ramanujan_pi_terms(100) if args.method == "ramanujan" else get_chudnovsky_pi_terms(100)
+
+        for i in range(args.terms):
+            try:
+                k, pi_est, delta = next(gen)
+                history.append({'step': k, 'pi': pi_est, 'delta': delta})
+                pi_s = str(pi_est)
+                print(f"Term {k:3d} → π ≈ {pi_s[0]}.{pi_s[1:15]}...", end="\r")
+            except StopIteration:
+                print(f"\n(series exhausted at {len(history)} term(s) for this precision — "
+                      f"further terms would add no more distinguishable digits)")
+                break
+        print("\n")
+        render_convergence_table(history)
+
+    elif args.cmd == "compare":
+        print("Benchmarking algorithms...\n")
+        results = []
+        for method, func in [("Chudnovsky", lambda: compute_chudnovsky_pi(1000)),
+                             ("Machin", lambda: compute_machin_pi(1000))]:
+            t0 = time.perf_counter()
+            func()
+            t1 = time.perf_counter()
+            results.append({'algo': method, 'precision': 1000, 'time': t1-t0})
+        render_comparison(results)
+
+    elif args.cmd == "bbp":
+        print(f"Extracting 16 hex digits of π starting at position {args.position}:")
+        digits = list(generate_bbp_spigot(args.position))
+        print("".join(digits))
+        print("(BBP Spigot — hexadecimal)")
+
+if __name__ == "__main__":
+    main()

core/algorithms.py

@@ -0,0 +1,235 @@
+"""
+FoxPi Core Algorithms — High-precision π computation.
+Implements exact integer-scaled implementations of historical and elite formulas.
+"""
+
+from typing import Generator, Tuple
+
+def get_ramanujan_pi_terms(precision: int) -> Generator[Tuple[int, int, int], None, None]:
+    """
+    Ramanujan's legendary 1914 hypergeometric series for 1/π.
+    Formula:
+      1/π = (2√2 / 9801) * Σ [ (4k)! * (1103 + 26390k) / ((k!)^4 * 396^(4k)) ]
+      
+    Yields:
+        Tuple[int, int, int]: (term_index, current_pi_estimate, current_term_value)
+    """
+    # Guard digits to mitigate rounding accumulation
+    guard = 20
+    scale = 10 ** (precision + guard)
+    
+    # Pre-calculate integer-scaled square root of 2: isqrt(2 * scale^2)
+    # 2√2 * scale = isqrt(8 * scale^2)
+    two_sqrt_two = isqrt(8 * (scale ** 2))
+    
+    total_sum = 0
+    
+    # Iterative hypergeometric factors
+    # Holds: (4k)! / ((k!)^4 * 396^(4k))
+    num_ratio = 1
+    den_ratio = 1
+    
+    k = 0
+    while True:
+        # Linear term: (1103 + 26390k)
+        linear = 1103 + 26390 * k
+        
+        # Current hypergeometric term
+        term = (scale * num_ratio * linear) // den_ratio
+        
+        if term == 0:
+            break
+            
+        total_sum += term
+        
+        # 1/pi = (2sqrt2/9801) * Sigma  =>  pi = 9801*scale^3 / (two_sqrt_two * total_sum)
+        # (two_sqrt_two and total_sum each already carry one factor of scale)
+        current_pi = (9801 * scale * scale * scale) // (two_sqrt_two * total_sum)
+        final_pi = current_pi // (10 ** guard)
+        
+        yield k, final_pi, term
+        
+        # Hypergeometric updates for k -> k + 1 step
+        # Multiplier derivation: (4k+1)(4k+2)(4k+3)(4k+4) / ((k+1)^4 * 396^4)
+        num_ratio *= (4 * k + 1) * (4 * k + 2) * (4 * k + 3) * (4 * k + 4)
+        den_ratio *= ((k + 1) ** 4) * 24591257856  # 396^4 = 24591257856
+        k += 1
+
+
+def get_chudnovsky_pi_terms(precision: int = 100) -> Generator[Tuple[int, int, int], None, None]:
+    """
+    Chudnovsky series computed one term at a time for convergence
+    visualization (the `explore` command). Recomputes binary splitting
+    from scratch each step — O(k^2) overall, which is fine for the
+    handful of terms `explore` requests. Use compute_chudnovsky_pi for
+    actual high-precision computation.
+
+    Yields:
+        Tuple[int, int, int]: (term_index, current_pi_estimate, term_magnitude)
+    """
+    guard = 20
+    scale = 10 ** (precision + guard)
+    C = 640320
+    C3_OVER_24 = (C ** 3) // 24
+
+    def bs(a: int, b: int) -> Tuple[int, int, int]:
+        if b - a == 1:
+            if a == 0:
+                P = 1
+                Q = 1
+            else:
+                P = (6 * a - 5) * (2 * a - 1) * (6 * a - 1)
+                Q = (a ** 3) * C3_OVER_24
+            T = P * (13591409 + 545140134 * a)
+            if a % 2 == 1:
+                T = -T
+            return P, Q, T
+        else:
+            m = (a + b) // 2
+            P1, Q1, T1 = bs(a, m)
+            P2, Q2, T2 = bs(m, b)
+            return P1 * P2, Q1 * Q2, Q2 * T1 + P1 * T2
+
+    sqrt_10005 = isqrt(10005 * (scale ** 2))
+    max_terms = (precision // 14) + 2  # Chudnovsky gives ~14 digits/term
+
+    k = 1
+    while k <= max_terms:
+        _, _, single_T = bs(k - 1, k)
+        term_magnitude = abs(single_T) if single_T != 0 else 1
+
+        _, Q, T = bs(0, k)
+        numerator = 426880 * sqrt_10005 * Q
+        pi_val = numerator // T
+        final_pi = pi_val // (10 ** guard)
+
+        yield k - 1, final_pi, term_magnitude
+        k += 1
+
+
+def compute_chudnovsky_pi(precision: int) -> int:
+    """
+    The Chudnovsky algorithm utilizing Binary Splitting execution logic.
+    Provides ~14 digits per iteration. Used by world-record engines.
+    """
+    guard = 20
+    scale = 10 ** (precision + guard)
+    
+    # Constants
+    C = 640320
+    C3_OVER_24 = (C ** 3) // 24
+    
+    # Binary splitting helper to divide-and-conquer huge integer expansions
+    def bs(a: int, b: int) -> Tuple[int, int, int]:
+        if b - a == 1:
+            if a == 0:
+                P = 1
+                Q = 1
+            else:
+                P = (6 * a - 5) * (2 * a - 1) * (6 * a - 1)
+                Q = (a ** 3) * C3_OVER_24
+            T = P * (13591409 + 545140134 * a)
+            if a % 2 == 1:
+                T = -T
+            return P, Q, T
+        else:
+            m = (a + b) // 2
+            P1, Q1, T1 = bs(a, m)
+            P2, Q2, T2 = bs(m, b)
+            P = P1 * P2
+            Q = Q1 * Q2
+            T = Q2 * T1 + P1 * T2
+            return P, Q, T
+
+    # Estimate required terms: ~14 digits per term
+    terms = (precision // 14) + 1
+    P, Q, T = bs(0, terms)
+    
+    # 426880 * √10005
+    sqrt_10005 = isqrt(10005 * (scale ** 2))
+    numerator = 426880 * sqrt_10005 * Q
+    
+    pi = numerator // T
+    return pi // (10 ** guard)
+
+
+def compute_machin_pi(precision: int) -> int:
+    """Classical Machin formula with scaled integer arithmetic."""
+    guard = 20
+    scale = 10 ** (precision + guard)
+    
+    def arccot(x: int, base_scale: int) -> int:
+        total = base_scale // x
+        term = total
+        n = 3
+        x2 = x * x
+        sign = -1
+        while True:
+            term = term // x2
+            if term == 0:
+                break
+            total += sign * (term // n)
+            sign = -sign
+            n += 2
+        return total
+        
+    pi_approx = 4 * (4 * arccot(5, scale) - arccot(239, scale))
+    return pi_approx // (10 ** guard)
+
+
+def generate_bbp_spigot(digit_position: int) -> Generator[str, None, None]:
+    """
+    Bailey-Borwein-Plouffe (BBP) Spigot implementation.
+    Extracts hexadecimal digits of π starting directly at 'digit_position'.
+    Does not require calculating any preceding digits.
+    """
+    from decimal import Decimal, getcontext
+
+    # Native float (53-bit mantissa) loses precision after ~13-14 hex digits
+    # of summation at deeper positions, corrupting trailing output digits.
+    # Use Decimal with enough guard digits to keep all 16 requested digits exact.
+    getcontext().prec = max(30, len(str(digit_position)) + 30)
+
+    def series_sum(n: int, j: int) -> Decimal:
+        s = Decimal(0)
+        for k in range(n + 1):
+            r = 8 * k + j
+            s = (s + Decimal(pow(16, n - k, r)) / r) % 1
+        k = n + 1
+        while True:
+            term = Decimal(16) ** (n - k) / (8 * k + j)
+            if term < Decimal("1e-30"):
+                break
+            s += term
+            k += 1
+        return s
+
+    n = digit_position - 1
+    s1 = series_sum(n, 1)
+    s2 = series_sum(n, 4)
+    s3 = series_sum(n, 5)
+    s4 = series_sum(n, 6)
+
+    pid = (4 * s1 - 2 * s2 - s3 - s4) % 1
+    if pid < 0:
+        pid += 1
+
+    for _ in range(16):
+        pid *= 16
+        digit = int(pid)
+        yield hex(digit)[2:].upper()
+        pid -= digit
+
+
+def isqrt(n: int) -> int:
+    """High-performance standard Newton-Raphson integer square root engine."""
+    if n < 0:
+        raise ValueError("Square root of a negative integer is undefined.")
+    if n == 0:
+        return 0
+    x = 2 ** ((n.bit_length() + 1) // 2)
+    while True:
+        y = (x + n // x) // 2
+        if y >= x:
+            return x
+        x = y

core/visualize.py

@@ -0,0 +1,25 @@
+"""
+FoxPi Visualization Module
+Handles high-fidelity CLI output formats.
+"""
+
+import time
+from typing import List, Dict, Any
+
+def render_convergence_table(history: List[Dict[str, Any]]) -> None:
+    """Prints a beautiful live convergence log to stdout."""
+    print(f"\n{'Iteration':<12} | {'Term Delta (Log10)':<20} | {'Pi Preview (First 15 Digits)':<20}")
+    print("-" * 60)
+    for entry in history:
+        idx = entry['step']
+        delta_len = len(str(entry['delta']))
+        pi_str = str(entry['pi'])
+        pi_preview = f"{pi_str[0]}.{pi_str[1:15]}..." if len(pi_str) > 15 else pi_str
+        print(f"{idx:<12} | -10^{delta_len:<16} | {pi_preview:<20}")
+
+def render_comparison(results: List[Dict[str, Any]]) -> None:
+    """Displays benchmark metrics comparing different numerical formulas."""
+    print(f"\n{'Algorithm':<15} | {'Precision (Digits)':<20} | {'Time Elapsed (s)':<18}")
+    print("-" * 60)
+    for res in results:
+        print(f"{res['algo']:<15} | {res['precision']:<20} | {res['time']:.6f}s")

foxpi-0.1.0.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.4
+Name: foxpi
+Version: 0.1.0
+Summary: High-precision terminal π explorer — Chudnovsky, Ramanujan, Machin, and BBP spigot algorithms.
+License-Expression: MIT
+Project-URL: Source, https://github.com/foxhackerzdevs/foxpi
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🦊 FoxPi
+
+**High-precision π explorer and mathematical visualization toolkit for the command line.**
+
+FoxPi is a Python-based CLI application for computing and exploring the digits of π using several famous algorithms. It provides fast high-precision computation, convergence visualization, benchmarking tools, and hexadecimal digit extraction via the Bailey–Borwein–Plouffe (BBP) formula.
+
+---
+
+# Table of Contents
+
+* [Features](#features)
+* [Project Structure](#project-structure)
+* [Installation](#installation)
+* [Usage](#usage)
+
+  * Compute Digits
+  * Explore Convergence
+  * Compare Algorithms
+  * BBP Hexadecimal Digits
+* [Algorithms Implemented](#algorithms-implemented)
+* [Examples](#examples)
+* [Dependencies](#dependencies)
+* [Configuration](#configuration)
+* [Troubleshooting](#troubleshooting)
+* [Contributing](#contributing)
+* [License](#license)
+
+---
+
+# Features
+
+* Compute π to an arbitrary number of decimal digits.
+* Multiple computation algorithms:
+
+  * Chudnovsky Algorithm
+  * Ramanujan Series
+  * Machin Formula
+* Interactive convergence exploration.
+* Benchmark algorithm performance.
+* Extract hexadecimal digits directly using the BBP formula.
+* Pure Python implementation using integer arithmetic for high precision.
+* No third-party dependencies.
+
+---
+
+# Project Structure
+
+```text
+foxpi/
+│
+├── cli.py                # Command-line interface
+└── core/
+    ├── algorithms.py     # Mathematical algorithms
+    └── visualize.py      # CLI visualization utilities
+```
+
+---
+
+# Installation
+
+Clone the repository:
+
+```bash
+git clone <repository-url>
+cd foxpi
+```
+
+Python 3.9+ is recommended.
+
+No external packages are required.
+
+Run with a subcommand:
+
+```bash
+python cli.py digits 100
+```
+
+`python cli.py` alone (with no subcommand) prints usage and exits with an error — a subcommand (`digits`, `explore`, `compare`, or `bbp`) is required.
+
+or
+
+```bash
+python -m cli
+```
+
+---
+
+# Usage
+
+## Compute Decimal Digits
+
+Compute π using one of the supported algorithms.
+
+```bash
+python cli.py digits 1000
+```
+
+Specify the algorithm:
+
+```bash
+python cli.py digits 5000 --method chudnovsky
+```
+
+```bash
+python cli.py digits 1000 --method ramanujan
+```
+
+```bash
+python cli.py digits 1000 --method machin
+```
+
+---
+
+## Explore Convergence
+
+Watch the approximation converge term by term.
+
+```bash
+python cli.py explore
+```
+
+Choose an algorithm:
+
+```bash
+python cli.py explore --method ramanujan
+```
+
+```bash
+python cli.py explore --method chudnovsky
+```
+
+Limit the number of displayed terms:
+
+```bash
+python cli.py explore --terms 20
+```
+
+---
+
+## Compare Algorithms
+
+Benchmark the available implementations.
+
+```bash
+python cli.py compare
+```
+
+Current benchmark compares:
+
+* Chudnovsky
+* Machin
+
+---
+
+## Extract Hexadecimal Digits (BBP)
+
+Retrieve hexadecimal digits beginning at a specified position without computing previous digits.
+
+```bash
+python cli.py bbp 1
+```
+
+Example:
+
+```bash
+python cli.py bbp 1000
+```
+
+Outputs the next 16 hexadecimal digits beginning at that position.
+
+---
+
+# Algorithms Implemented
+
+## Chudnovsky Algorithm
+
+* Modern state-of-the-art series for computing π.
+* Approximately **14 decimal digits per term**.
+* Uses **binary splitting** for efficient large integer arithmetic.
+* Suitable for very high precision.
+
+---
+
+## Ramanujan Series
+
+* Classic 1914 hypergeometric series.
+* Extremely rapid convergence.
+* Integer-scaled implementation for numerical stability.
+
+---
+
+## Machin Formula
+
+Uses
+
+```
+π = 4 × (4 arccot(5) − arccot(239))
+```
+
+Advantages:
+
+* Simple
+* Educational
+* Useful for comparison against faster modern methods
+
+---
+
+## Bailey–Borwein–Plouffe (BBP)
+
+Supports direct extraction of hexadecimal digits of π.
+
+Unlike traditional algorithms, BBP allows accessing hexadecimal digits beginning at an arbitrary position without computing all preceding digits.
+
+---
+
+# Examples
+
+Compute 100 digits:
+
+```bash
+python cli.py digits 100
+```
+
+Compute 5000 digits using Chudnovsky:
+
+```bash
+python cli.py digits 5000 --method chudnovsky
+```
+
+Visualize convergence:
+
+```bash
+python cli.py explore --method chudnovsky --terms 15
+```
+
+Benchmark:
+
+```bash
+python cli.py compare
+```
+
+Extract hexadecimal digits:
+
+```bash
+python cli.py bbp 250
+```
+
+---
+
+# Dependencies
+
+Only Python standard library modules are used:
+
+* argparse
+* decimal
+* pathlib
+* sys
+* time
+* typing
+
+No external dependencies are required.
+
+---
+
+# Configuration
+
+There are currently no configuration files.
+
+Precision and algorithm selection are controlled through command-line arguments.
+
+---
+
+# Troubleshooting
+
+### Import errors
+
+Ensure the project directory structure matches the expected layout:
+
+```text
+core/
+    algorithms.py
+    visualize.py
+```
+
+---
+
+### Slow execution
+
+Very large digit counts require significant CPU time.
+
+For best performance:
+
+* Prefer the Chudnovsky algorithm.
+* Use Ramanujan for convergence exploration.
+* Use Machin primarily for educational purposes and comparisons.
+
+---
+
+### Unexpected precision
+
+Higher requested precision naturally requires more computation time and memory due to large integer arithmetic.
+
+---
+
+# Contributing
+
+Contributions are welcome.
+
+Possible improvements include:
+
+* Additional π algorithms
+* Parallel binary splitting
+* Progress bars
+* Graphical convergence plots
+* Export benchmark results
+* Automated testing
+* Packaging for PyPI
+
+---
+
+# License
+
+No license information was provided in the source files.
+
+Consider adding a `LICENSE` file (for example MIT, Apache-2.0, or GPL-3.0) before publishing the project.

foxpi-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+cli.py,sha256=bC1_Dfc8M2yW3EHPsKVhp9V4ij0UST73-kzkAKjb1JM,4393
+core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+core/algorithms.py,sha256=bjZVvQhkk9s4lIdU-FTyzqdQfGBSWhNFsSgWIRPIFFI,7228
+core/visualize.py,sha256=bFV-BZyqMrQkzxf9fhtOQqjVfY_b7G24VQH0NZ7OJYA,1022
+foxpi-0.1.0.dist-info/licenses/LICENSE,sha256=p1OSXnJheNJK39gGLrV1Q4tD6bRP_UYYl_mQvp1_YNY,1068
+foxpi-0.1.0.dist-info/METADATA,sha256=8PVgVFyexMKw-Tfh3LEZFPO3JfCXB-rvNVk_MYARVDA,5887
+foxpi-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+foxpi-0.1.0.dist-info/entry_points.txt,sha256=DJ8tj_Bw-PI0HaaRWTFrmVWQ7ihel-G1fl-wBZmUZQs,35
+foxpi-0.1.0.dist-info/top_level.txt,sha256=3d1SrIv4s8kkUKftU2GUWApholP9j4ktB3LaSaSWSNM,9
+foxpi-0.1.0.dist-info/RECORD,,

foxpi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

foxpi-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+foxpi = cli:main

foxpi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fox Hackerz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

foxpi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+cli
+core