🔢 hpmath

📖 Introduction

✨ Why hpmath?

• Zero external dependencies — Single binary, no libgmp, no OpenSSL
• Arbitrary precision — BigInt, BigRational, Radical with base-2³² digits
• Educational design — Built for step-by-step solutions, not just answers
• Language agnostic — HTTP/JSON API works with OCaml, Rust, Python, Elm, any stack
• Deployment simple — systemd service, nginx proxy, localhost-only by default
• Cost effective — No per-request API fees like Wolfram/SymPy cloud

🎯 Use Cases

• EdTech platforms needing verified math computations
• Competitive programming problem generators
• NCERT/CBSE/JEE/SAT math content creation
• Symbolic engines (like OCaml/gtmath) needing BigInt escape hatch
• Offline-capable math tools for low-bandwidth regions

🏗️ Architecture

Key Design Principles

• Computation only — No pedagogy, no problem logic (handled by caller)
• JSON strings for numbers — Prevents float overflow in parsers
• Localhost binding — Only your backend calls hpmath directly
• Input limits — Prevents abuse (e.g., factorial ≤ 2000)
• Clear errors — Machine-readable error codes + messages

Project Structure

hpmath/
├── src/
│   ├── bignum/          # BigInt, BigRational implementation
│   ├── radical/         # Symbolic radical simplification
│   ├── decimalexpand/   # Decimal expansion, constants π/e/φ
│   └── numbertheory/    # GCD, primes, factorization, sequences, modpow
├── cserver/
│   ├── main.c           # HTTP server loop (~500 lines pure C)
│   ├── router.c         # Endpoint routing
│   ├── handlers/        # Thin HTTP handlers (parse JSON → call lib → respond)
│   └── json_helpers.c   # Minimal JSON parser (no external lib)
├── include/             # Public headers (bigint.h, bigrational.h, etc.)
├── static/              # This documentation + test UI
├── Makefile             # Zero-dependency build
└── bin/hpmath-server    # Compiled binary

📡 Endpoints Catalog

Base URL: http://127.0.0.1:8002/api

Core Arithmetic

Primes & Factorization

🔗 Integration Guide

OCaml (gtmath)

(* lib/numeric/hpmath_client.ml *)
module Hpmath = struct
  type config = { base_url: string; timeout: float }
  
  let default = { base_url = "http://127.0.0.1:8002"; timeout = 30.0 }
  
  let post ~config ~endpoint ~params =
    let json = Yojson.Basic.to_string (`Assoc params) in
    Http.post (config.base_url ^ endpoint) ~headers:[("Content-Type","application/json")] ~body:json
  
  let factorial ~config n =
    post ~config ~endpoint:"/api/integer/factorial" 
      ~params:["n", `String (Bigint.to_string n)]
    |> Json.parse |> fun j -> Bigint.of_string (Json.get "factorial" j)
end

Python

import requests

def hpmath_factorial(n: int) -> int:
    resp = requests.post(
        "http://127.0.0.1:8002/api/integer/factorial",
        json={"n": str(n)},  # ← String, not int!
        headers={"Content-Type": "application/json"}
    )
    return int(resp.json()["factorial"])  # Parse quoted string

curl (Testing)

# GCD
curl -s -X POST http://127.0.0.1:8002/api/integer/gcd \
  -H "Content-Type: application/json" \
  -d '{"a":"96","b":"404"}'

# Power comparison: 100^98 vs 89^100
A=$(curl -s -X POST http://127.0.0.1:8002/api/integer/power \
  -d '{"base":"100","exp":"98"}' | jq -r '.power')
B=$(curl -s -X POST http://127.0.0.1:8002/api/integer/power \
  -d '{"base":"89","exp":"100"}' | jq -r '.power')
curl -s -X POST http://127.0.0.1:8002/api/integer/compare \
  -d "{\"a\":\"$A\",\"b\":\"$B\"}"

💡 Example Problems

NCERT Class 10: HCF by Factorization

"Find the HCF of 96 and 404 by prime factorization."

# Step 1: Factorize both
curl -s -X POST http://127.0.0.1:8002/api/integer/factorize -d '{"n":"96"}'
# → {"factors":["2","2","2","2","2","3"]}

curl -s -X POST http://127.0.0.1:8002/api/integer/factorize -d '{"n":"404"}'
# → {"factors":["2","2","101"]}

# Step 2: Compute GCD (or intersect factors manually)
curl -s -X POST http://127.0.0.1:8002/api/integer/gcd -d '{"a":"96","b":"404"}'
# → {"gcd":"4"} ✓

Power Comparison (Competitive Programming)

"Which is larger: 2^1000 or 3^600?"

# Compute both (results are quoted strings)
A=$(curl -s -X POST .../power -d '{"base":"2","exp":"1000"}' | jq -r '.power')
B=$(curl -s -X POST .../power -d '{"base":"3","exp":"600"}' | jq -r '.power')

# Compare
curl -s -X POST .../compare -d "{\"a\":\"$A\",\"b\":\"$B\"}"
# → {"comparison":1,"relation":"greater"} → 2^1000 > 3^600

Modular Exponentiation (Cryptography)

# Compute (2^1000) mod 1000000007 efficiently
curl -s -X POST http://127.0.0.1:8002/api/integer/modpow \
  -d '{"base":"2","exp":"1000","mod":"1000000007"}'
# → {"modpow":"14641"} ✓ (computed in O(log exp) time)

🧪 Interactive Test UI

All endpoints below call your local hpmath server. Results display as formatted JSON.