{"id":27624417,"url":"https://github.com/jjteoh-thewebdev/pi-quests","last_synced_at":"2026-04-29T00:32:29.681Z","repository":{"id":288947003,"uuid":"969166726","full_name":"jjteoh-thewebdev/pi-quests","owner":"jjteoh-thewebdev","description":"A fun project related to calculation of Pi(π)","archived":false,"fork":false,"pushed_at":"2025-04-23T02:51:07.000Z","size":1540,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T11:46:22.925Z","etag":null,"topics":["binary-splitting","chudnovsky-algorithm","pi-calculation","python3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jjteoh-thewebdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-19T14:40:11.000Z","updated_at":"2025-04-23T02:51:11.000Z","dependencies_parsed_at":"2025-04-20T16:46:23.151Z","dependency_job_id":null,"html_url":"https://github.com/jjteoh-thewebdev/pi-quests","commit_stats":null,"previous_names":["jjteoh-thewebdev/pi-quests"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jjteoh-thewebdev/pi-quests","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjteoh-thewebdev%2Fpi-quests","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjteoh-thewebdev%2Fpi-quests/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjteoh-thewebdev%2Fpi-quests/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjteoh-thewebdev%2Fpi-quests/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jjteoh-thewebdev","download_url":"https://codeload.github.com/jjteoh-thewebdev/pi-quests/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjteoh-thewebdev%2Fpi-quests/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32405901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"ssl_error","status_checked_at":"2026-04-28T19:37:55.688Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-splitting","chudnovsky-algorithm","pi-calculation","python3"],"created_at":"2025-04-23T11:42:08.480Z","updated_at":"2026-04-29T00:32:29.676Z","avatar_url":"https://github.com/jjteoh-thewebdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pi Quests\nA collection of apps that related to calculation of Pi precesion.\n\nBackend - A Python HTTP server that calculate Pi in increasing precision fashion.\n\n\nFrontend - A Next.js web app that showcase the Sun in 3D model and some other info. Retrieve the Pi value from Backend.\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"media/app_preview.png\" /\u003e\n\u003c/div\u003e\n\n\n## 📖 Overview\n\nThe main objective of this project is to compute Pi to arbitrary precision in increasing decimal places(e.g. 3, 3.1, 3.14, 3.141, 3.1415...). The frontend app serves as a client application that consumes the computed Pi.\n\n## 🏗️ Architecture\n\nThe application consists of three main components:\n\n1. **FastAPI Backend(Python)**\n   - Implements the Chudnovsky algorithm for calculating Pi with binary splitting and CPU Parallelism\n   - Uses `mpmath` (backended with `gmpy2`) for arbitrary precision arithmetic\n   - Caches calculated values in Redis\n   - Provides a RESTful API for Pi retrieval\n   - Simple route guard with API Key and rate limit.\n   - Containerized with Docker\n\n2. **Next.js Frontend**\n   - Simple prototyping with Next.js, R3F, TailwindCSS and shadcn-ui\n   - 3D sun model - basic interaction, camera view control\n   - Unit switching between kilometers and miles\n   - Modal dialog for viewing Pi(fetch from backend) with high precision\n\n3. **Redis Cache**\n   - Stores calculated Pi values\n   - Enable resume calculation from previous calculated precision.\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- [Docker](https://www.docker.com/get-started) \n- [Python 3.9+](https://www.python.org/downloads/) (for local backend development)\n- [nodejs 18+](https://nodejs.org) (for local frontend development)\n- [pnpm](https://pnpm.io/installation) (recommended for frontend development)\n\n### Using Docker (Recommended)\n\nThe easiest way to run the entire application stack:\n\n```bash\n# Clone the repository\ngit https://github.com/jjteoh-thewebdev/pi-quests.git\ncd pi-quests\n\n# (Optional) Update frontend/.env.docker and backend/.env.docker accordingly\n\n# Start the application stack\ndocker-compose up -d\n```\n\nThe application will be available at:\n- Frontend: http://localhost:3000\n- Backend API: http://localhost:8000\n\n### Local Development\n\n- create .env file\n\n    ```bash\n    cp backend/.env.sample backend/.env\n    cp frontend/env.sample frontend/.env.local\n    ```\n\n#### Backend\n\n```bash\ncd backend\n\n# Create a virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n# or (using Makefile)\nmake install\n\n# Install system dependencies for gmpy2\n# Ubuntu/Debian:\nsudo apt apt-get update\nsudo apt install libgmp-dev libmpfr-dev libmpc-dev\n\n# Set up environment variables\ncp .env.sample .env\n# Edit .env with your settings\n\n# (Optional) Start Redis with Docker, or you can install natively to you machine\ndocker run -d -p 6379:6379 redis:alpine\n\n# Run the backend\nuvicorn app.main:app --reload\n# or (using Makefile)\nmake dev\n```\n\n#### Frontend\n\n```bash\ncd frontend\n\n# Install dependencies\npnpm install\n\n# Set up environment variables\ncp env.sample .env.local\n# Edit .env.local with your settings\n\n# Start the development server\npnpm dev\n```\n\n## 📋 API Documentation\n\nOnce the backend is running, Swagger documentation is available at:\n- http://localhost:8000/docs\n\n## 💡 Key Features\n\n- **High-Precision Calculation**: Uses the Chudnovsky algorithm for rapid Pi calculation\n- **Parallelized Processing**: Multi-core support for faster calculations\n- **Progressive Enhancement**: Incrementally calculates Pi to higher precision in the background\n- **Caching Layer**: Redis caching prevents recalculating already-known digits\n\nCompute 100M decimal places on my machine took 113.52 seconds:\n\n![100M](media/100M.JPG)\n\nPC spec and CPU utilization\n\u003cdiv align=\"center\"\u003e\n    \u003cimg alt=\"pc info\" src=\"media/cpu-utilization.jpg\" /\u003e\n\u003c/div\u003e\n\n*I only have 16G RAM, 100M is the max I can push.\n\n\n## ⚙️ Configuration\n\n### Backend Environment Variables\n\n- `API_KEY`: API key for authentication\n- `MAX_DECIMAL_POINTS`: Maximum decimal places to calculate (default: 10000)\n- `START_DECIMAL_POINTS`: Start from decimal points (default from 0)\n- `REDIS_URL`: Redis connection string\n\n### Frontend Environment Variables\n\n- `API_BASE_URL`: Backend API URL\n- `API_KEY`: API key for authentication\n\n## 🤔 Limitations \u0026 Future Work\n\n### Current Limitations\n\n- High precision calculations are memory-intensive(my 16GB can only push up to 100M decimal points)\n- Low level languages like C or RUST has better performance than Python.\n\n### Future Enhancements\n\n- Use disk storage for caching, current implementation restricted to RAM size.\n- Use `gmpy2`(C libraries) directly. Current implementation using a pure Python wrapper(`mpmath`) to handle arbitary precision calculation.\n\n## 🔒 Security Notes\n\n- The default setup is for development; additional security measures should be implemented for production. \n- More robust API Key management should be implemented. \n\n## 📄 License\n\n[MIT License](LICENSE)\n\n## 🙏 Resources\n\nPi\n- https://en.wikipedia.org/wiki/Pi\n- https://youtu.be/1-JAx3nUwms?si=zMcB9i9RS3JKkYFK\n- https://youtu.be/gMlf1ELvRzc?si=HawpOIXHPg1dNUAe\n\nChudnovsky algorithm \u0026 binary splitting\n- https://www.craig-wood.com/nick/articles/pi-chudnovsky/\n- https://en.wikipedia.org/wiki/Chudnovsky_algorithm \n- https://youtu.be/LhlqCJjbEa0?si=xFLwPrZLaok_KyC2\n\nmpmath - for arbitrary precision arithmetic\n- https://mpmath.org/ ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjjteoh-thewebdev%2Fpi-quests","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjjteoh-thewebdev%2Fpi-quests","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjjteoh-thewebdev%2Fpi-quests/lists"}