<div align="center"> <br>

🔢 NumOS

Open-Source Scientific Graphing Calculator OS

ESP32-S3 N16R8 · ILI9341 IPS 320×240 · LVGL 9.x · Pro-CAS Engine · Natural Display V.P.A.M.

<br>

<br>

A real open-source alternative to commercial scientific calculators. Inspired by NumWorks · TI-84 Plus · HP Prime G2, built from scratch in C++17.

<br> </div>

---

Table of Contents

0. Webpage
1. What is NumOS?
2. Key Features
3. System Architecture
4. Pro-CAS Engine
5. Hardware
6. Quick Start
7. User Manual — EquationsApp
8. Project Structure
9. Build Stats
10. Critical Hardware Fixes
11. Project Status
12. Technology Stack
13. Comparison with Commercial Calculators
14. Documentation
15. Contributing

---

What is NumOS?

NumOS is an open-source scientific and graphing calculator operating system built on the ESP32-S3 N16R8 microcontroller (16 MB Flash QIO + 8 MB PSRAM OPI). The project aims to become the best open-source calculator in the world, rivalling the Casio fx-991EX ClassWiz, the NumWorks, the TI-84 Plus CE, and the HP Prime G2.

NumOS delivers:

• Full Pro-CAS Engine — Advanced symbolic algebra: immutable DAG with hash-consing (ConsTable), overflow-safe bignum arithmetic (CASInt/CASRational), multi-pass fixed-point simplifier, symbolic differentiation (17 rules), symbolic integration (Slagle heuristic), and non-linear equation/system solving via Sylvester resultant. All memory managed in PSRAM with an STL-compatible allocator.
• Natural Display V.P.A.M. — Formulae rendered as they appear on paper: real stacked fractions, radical symbols (√), genuine superscripts, 2D navigation with a structural smart cursor.
• Modern LVGL 9.x Interface — Smooth transitions, animated splash screen, NumWorks-style launcher. Recent launcher refactor: the launcher now uses LVGL Flex ROW_WRAP (dynamic rows) with fixed card sizing instead of a static grid descriptor. See docs/UI_CHANGES.md for developer migration notes and docs/fluid2d_plan.md for an example app (Fluid2D) integrated into the new APPS[] schema.
• Custom Math Engine — Complete pipeline: Tokenizer → Shunting-Yard Parser → RPN Evaluator + Visual AST, implemented from scratch in C++17.
• Modular App Architecture — Each application is a self-contained module with explicit lifecycle (begin/end/load/handleKey), orchestrated by SystemApp.

---

Key Features

| Feature | Description | |:--------|:------------| | CAS-S3-ULTRA Engine | Sylvester Resultant solver (3×3 NL systems), 16-seed Newton-Raphson, BigInt precision (CASInt + CASRational), hash-consed DAG, 8-pass fixed-point simplifier, PSRAM-backed step logger | | Unified Calculus App | Symbolic $d/dx$ differentiation (17 rules) and numerical/symbolic $\int dx$ integration (Slagle heuristic: table lookup, linearity, u-substitution, integration by parts/LIATE), tab-based mode switching, automatic simplification, and detailed step-by-step output | | EquationsApp | Solves linear, quadratic, and 2×2 systems (linear + non-linear via Sylvester resultant) with full step-by-step display | | Bridge Designer | Real-time structural bridge simulator with Verlet integration physics, stress analysis (green→red beam visualisation), snap-to-grid editor, wood/steel/cable materials, and truck/car load testing — PSRAM-backed, 60 Hz fixed timestep | | Particle Lab | Powder-Toy-class sandbox: 30+ materials (Sand, Water, Lava, LN2, Wire, Iron, Titan, C4, Clone), spark electronics with Joule heating, phase transitions, reaction matrix (Water+Lava=Stone+Steam), Bresenham line tool, material palette overlay, LittleFS save/load | | Settings App | System-wide toggles for complex number output (ON/OFF), decimal precision selector (6/8/10/12 digits), and angle-mode display | | Natural Display | Real fractions, radicals, exponents, 2D cursors — mathematical rendering as it appears on paper | | Graphing: y=f(x) | Real-time function plotter with zoom, pan, and value table | | 85+ CAS Unit Tests | Comprehensive test suite for the Pro-CAS, enable/disable via compile-time flag | | PSRAMAllocator | CAS uses PSRAMAllocator<T> to isolate memory usage in the 8 MB PSRAM OPI | | Variables A–Z + Ans | Persistent storage via LittleFS — 216 bytes in /vars.dat | | SerialBridge | Full calculator control from PC via Serial Monitor without physical hardware | | SerialBridge Debug | Immediate byte echo, 5-second heartbeat, 8-event circular buffer |

---

Photo gallery

Neural Network Simulator:

Fluid 2D Simulator:

Periodic Table (Chemistry App):

Grapher App:

Steps (Equations App) (WIP, still in development, Alpha):

Calculus App:

Probability (Gaussian Distribution):

Python App:

Bridge Designer:

Circuit Simulator (Circuit Core, Alpha):

Particle Lab (Powder Toy like):

Optics Lab:

---

System Architecture

flowchart TB
   subgraph esp[ESP32-S3 N16R8]
      main["main.cpp: setup() → PSRAM, TFT, LVGL, Splash, SystemApp; loop(): lv_timer_handler(), app.update(), serial.poll()"]
      system["SystemApp (Dispatcher)"]
      main --> system
   end

   subgraph apps[Applications]
      mm["MainMenu (LVGL)"]
      calc["CalculationApp (Natural VPAM, History)"]
      grapher["GrapherApp (y=f(x), Zoom & Pan)"]
      eq["EquationsApp (Pro-CAS)"]
      calculus["CalculusApp (d/dx, ∫dx)"]
      settings["SettingsApp"]
   end

   system --> mm
   system --> calc
   system --> grapher
   system --> eq
   system --> calculus
   system --> settings

   math["Math Engine: Tokenizer · Parser · Evaluator · ExprNode · VariableContext · EquationSolver"]
   procas["Pro-CAS Engine: CASInt · CASRational · SymExpr DAG · SymSimplify · SymDiff · SymIntegrate"]

   system --> math
   math --> procas

   display["Display Layer: DisplayDriver · LVGL flush DMA · ILI9341 @ 10 MHz"]
   input["Input Layer: KeyMatrix 5x10 · SerialBridge · LvglKeypad · LittleFS"]

   system --> display
   system --> input

   display -->|SPI @ 10 MHz| ili["ILI9341 IPS 3.2 in — 320x240 · 16 bpp"]
   ili -.-> esp

---

Pro-CAS Engine

The Pro-CAS (Computer Algebra System) is NumOS's complete symbolic-algebra engine. Evolved from the original CAS-Lite, it implements an immutable DAG with hash-consing, overflow-safe bignum arithmetic, multi-pass fixed-point simplification, symbolic differentiation, symbolic integration (Slagle), and non-linear system solving via Sylvester resultant. All CAS memory resides in PSRAM.

CAS Pipeline (Derivatives)

flowchart TB
   user["User input (CalculusApp): x^3 + sin(x)"]
   user --> me["Math Engine: Parser + Tokenizer"]
   me --> af["ASTFlattener: MathAST → SymExpr DAG"]
   af --> sd["SymDiff → d/dx: 3x^2 + cos(x)"]
   sd --> ss["SymSimplify (8-pass fixed-point)"]
   ss --> sea["