Mathematics Simulator

An open-source spin-off project aimed at exploring mathematics — ranging from trigonometric functions in two-dimensional spaces to topology, fractal geometry, and many more features to come. The project is under active development; if you'd like to help, contributions are very welcome.

It is a single, coherent mathematical exploration engine: every workspace below shares one math core (lexer → parser → AST → evaluator, complex numbers, symbolic calculus, and an AST→GLSL compiler). No two engines, no eval.

🔗 Live demo: mathematics-simulator.vercel.app — deployed on Vercel, continuously deployed from the main branch. No local backend; the whole app runs in the browser.

---

Workspaces

The top navigation switches between ten workspaces:

📈 Calculator — 2D & 3D graphing (Desmos-style)

• 2D: plot y = f(x), multiple expressions with color + visibility, pan/zoom, live trace of f(x) and f'(x).
• Sliders: any undefined variable becomes a slider; min/max/step accept expressions (so a slider can be limited to a set, e.g. {0, 2, …, n−1}); per-slider animation (loop / ping-pong).
• Analysis tools: draggable locator, tangent line with symbolic derivative, shaded definite integral (Simpson's rule).
• 3D: explicit surfaces z = f(x, y) and implicit surfaces F(x, y, z) = 0 (marching tetrahedra), multiple surfaces at once, bounding box + numbered axes, probe point showing f, ∂f/∂x, ∂f/∂y, ‖∇f‖, orbit camera + view presets.

🌀 Fractal Lab — GPU escape-time fractals

• Mandelbrot, Julia (pick-from-Mandelbrot), Burning Ship, Tricorn, Celtic, Buffalo, Newton.
• Generalised exponent z^p + c (incl. decimals), smooth coloring, 6 palettes.
• Deep zoom via emulated double precision (double-single, df64).
• Custom f(z,c) and Complex f(z) domain coloring — your typed expression is compiled through the shared parser into a GPU shader.
• Parameter animation, PNG + config JSON export.

🧭 Bloch Sphere — single-qubit simulator

• Gates X, Y, Z, H, S, S†, T, T† and Rx/Ry/Rz rotations.
• Drive pulses (Rabi Ω, detuning Δ, phase φ, duration t) with a live preview of the effective rotation axis + ghost arc before applying.
• State trajectory, arrow animation, |ψ⟩ / θ,φ readout, and measurement probability bars in the X/Y/Z bases.

🧊 4D — polytopes & parametric surfaces

• Tesseract, 5-cell, 16-cell, 24-cell, and parametric surfaces (u,v) → ℝ⁴ (Clifford torus, Hopf fibration, …) typed with the shared parser.
• Rotation in all six 4-space planes, perspective projection d/(d−w), and the 4th dimension mapped to color. Auto double-rotation.

🍩 Topology — homeomorphisms & deformation

• Everyday objects grouped by genus (ball, egg, plate, bowl, vase, cup…; donut, mug, teacup, ring, bagel, CD…).
• Continuous morph between same-genus shapes (mug ↔ donut, cup ↔ ball) — the panel verifies homeomorphism via genus / Euler characteristic χ = 2 − 2g.
• Grab & deform: pull the surface, inflate, twist, random deform — all topology-preserving. Spin in space, wireframe, color modes.

🌀 Dynamics — dynamical systems & phase portraits

• Type an autonomous system ẋ = f(x,y), ẏ = g(x,y) (or pick a preset: rotation, damped oscillator, saddle, Van der Pol, pendulum, spiral sink).
• Vector field, pan/zoom navigable plane, and equilibria colored by stability (stable/unstable node, spiral, saddle, center — from the Jacobian spectrum).
• Trajectory animation: click a start point and a particle flows along the field (RK4) to its end point — the equilibrium / singularity it converges to. Play/pause + speed.

🌌 Dynamics 3D — spatial dynamics & spacetime

One view, one Model toggle, three physical models sharing the same orbit camera and render loop (all physics runs outside React, in refs; the shared parser + ODE solver are reused — no second engine, no eval):

• Mathematical Field x′ = F(x) — type dx/dt, dy/dt, dz/dt over x, y, z, parsed through the same DynamicalSystem used by the 2D phase-plane view. Rendered as sampled vector arrows on a grid plus a handful of particle-probe streamlines, integrated via the shared ODE registry.
• Newtonian gravity — N-body with velocity-Verlet / RK4, collisions/merging, energy & momentum diagnostics. Exact (Φ = -GM/r, safely floored near r=0) and softened-Plummer models sit behind one shared force/potential seam and are switchable per-scenario; diagnostics are tagged exact/numerical/proxy (honest about what the nonphysical gravitationalStrength knob does to conservation). The space-time deformation surface is explicitly a potential proxy, not the Einstein metric.
• General Relativity — real geodesics of an analytic metric, d²xᵘ/dτ² + Γᵘ₍αβ₎ uᵃ uᵝ = 0, integrated by the shared ODE solver. Metrics: Minkowski (flat baseline), Schwarzschild and Kerr (rotating, spin a, non-diagonal Boyer-Lindquist metric) — one shared engine derives the inverse metric, Christoffel symbols and Riemann/Ricci/Einstein curvature from the metric alone, nothing model-specific hardcoded. Every metric shows its provenance; the 3D trace is captioned as a coordinate-position plot, not a literal spacetime embedding.

Click to spawn — every model shares the same body-preset picker (Particle, Planet, Star, Black Hole, Singularity, with procedural planet palettes): click the canvas to place a celestial marker. In Newtonian gravity it's a real N-body with mass; in Mathematical Field and General Relativity it's a visual marker only, advected by the field / integrated along a geodesic from the clicked point — the preset never leaks mass or softening into that physics.

🔬 Inspector — mathematical microscope

• Select an object (expression, matrix, vector, topological surface, dynamical system, ODE, probability distribution, dataset, time series) and get a typed report: structure/AST, classification, domain, calculus (f', f'', ∇, Hessian, ∇²), roots & critical points; matrix rank/det/eigenstructure/ decompositions/conditioning/subspaces + 2×2 geometric action.
• Every value is tagged exact / symbolic / numerical / estimated / inferred, with compare mode, capability chips, navigable related objects, and honest assumptions/limits. Registry-driven — new domains plug in without touching the engine.

📓 Notebook — reproducible experiments

• A document of cells (markdown / parameter / expression / analysis) whose outputs are derived deterministically from the source; parameters propagate through a dependency graph and downstream analyses recompute.
• Undo/redo, snapshots, localStorage autosave, import/export as .mathsim.json (declarative, schema-validated, no eval), and a bundled example gallery spanning calculus, linear algebra, optimization, dynamics, ODEs, PDEs, probability, number theory, complex analysis, and units.

📖 Docs — built-in manual

• Bilingual (English / Español) manual explaining every workspace and its underlying mathematics, with formulas typeset by KaTeX.

---

Advanced mathematics & scientific computing (Phase IV)

Beyond the visual workspaces, the math core (src/mathlab/) is a serious scientific-computing environment. Every domain shares the same object → analysis → Inspector → visualization → experiment architecture, so you move naturally between symbolic math, numerical math, and simulation.

Domain	Highlights
Linear algebra	LU / QR / Cholesky decompositions, SVD (UΣVᵀ), eigen (Jacobi + QR iteration), least squares, nullspace, condition number, 2D/3D geometric visualization
Dynamical systems	Continuous flows & discrete maps, equilibria (Newton), Jacobian stability (Hartman–Grobman), phase space, nullclines, bifurcation & chaos (Lyapunov, orbits)
ODEs	Euler, Heun, RK2, RK4, adaptive RKF45; systems & IVPs; error metadata, parameter sweeps, method comparison
PDEs	1D heat, 1D wave, 2D Laplace/Poisson via finite differences; CFL/stability-aware
Optimization	Golden-section, gradient descent, damped Newton; trajectories, Hessian classification, convergence analysis
Probability / Statistics	6 distributions (Bernoulli → Poisson), seeded sampling, Monte Carlo, descriptive stats, Dataset object, regression
Number theory	bigint-exact gcd/lcm/extended-Euclid, Miller–Rabin primality, Pollard ρ factorization, φ, μ, Collatz
Complex analysis	Domain coloring, grid mapping (z², eˣ, 1/z, log z), Cauchy–Riemann, special functions (Gamma, erf)
Scientific computing	Units & dimensional analysis, constants registry, uncertainty propagation, unified numerical-method registry

---

Shared math core (src/mathlab/)

The correctness-critical layer, unit-tested (1313 tests), all consuming one AST:

• core/ — lexer → parser → ast, real eval (whitelisted functions, never eval/Function), simplify, print, complexGlsl (AST → GLSL), structured errors, seeded rng, central tolerances, a unified numerical-method registry, and the shared TimeSeries object.
• calculus/ — symbolic differentiation, Taylor, gradient/Hessian/Jacobian/Laplacian.
• analysis/ + numeric/ — roots (bisection/Newton), integration (Simpson + adaptive), limits.
• linear/ — matrix ops, LU/QR/Cholesky/SVD, eigenvalues/eigenvectors (symmetric Jacobi + general QR), least squares, subspaces, conditioning.
• ode/ — Euler/Heun/RK2/RK4 + adaptive RKF45 with metadata.
• dynamics/ — systems, equilibria, Jacobian stability (continuous & discrete), trajectories. dynamics3d/ — N-body gravity and arbitrary 3D vector fields x′ = F(x) (streamlines via the shared solver).
• relativity/ — generic differential geometry from a metric alone (inverse metric, Christoffel, Riemann/Ricci/Einstein), geodesic integration via the shared ODE solver, and analytic Minkowski / Schwarzschild / Kerr models with provenance, including frame-dragging (zero-angular-momentum test particles).
• optimization/ — golden-section, gradient descent, Newton, critical-point classify.
• probability/ + statistics/ — distributions + seeded sampling + Monte Carlo; dataset, descriptives, regression.
• numberTheory/ — exact bigint arithmetic, primality, factorization, φ, μ, Collatz.
• units/ — dimensional quantities, conversion, constants, uncertainty.
• complex/ — first-class complex scalars, Node → Complex eval, Cauchy–Riemann.
• pde/ — 1D heat & wave, 2D Laplace/Poisson (finite differences).
• special/ — Gamma, log-Gamma, erf.

The inspector/ (registry-driven analysis engine), experiment/ (notebook document model + safe serialization), and a lightweight search/ index sit above the kernel. The same parsed AST feeds the calculator, the fractal shaders, and every analysis — that is the core design principle: one engine, no duplicates, no eval.

---

Tech stack

• React 19 + TypeScript (strict) + Vite 7
• TailwindCSS v4
• WebGL for fractals, 3D surfaces, the Bloch sphere, and 4D rendering
• zustand for state
• KaTeX for typeset math (lazy-loaded)
• Vitest for tests
• Deployed on Vercel

---

Project structure

src/
  mathlab/     shared math core: core, calculus, analysis, numeric, linear, ode,
               dynamics, dynamics3d, relativity, optimization, probability,
               statistics, numberTheory, units, complex, pde, special, symbolic
  inspector/   registry-driven inspection engine (types, capabilities, inspect/*)
  experiment/  notebook document model, execution engine, safe serialization
  search/      lightweight cross-workspace search index
  fractals/    fractal registry + types
  webgl/       WebGL renderer + AST→GLSL custom-shader builder
  graph/       graphing state + slider config
  bloch/       qubit math + state       fourd/  4D vectors, polytopes, surfaces
  topo/        topology surfaces + mesh + morph
  components/  React UI per workspace (graph, bloch, fourd, topo, dynamics,
               dynamics3d, inspector, notebook, docs, …)
  App.tsx      top-level workspace switcher

---

Getting started

git clone https://github.com/Max-arango/Mathematics-Simulator.git
cd Mathematics-Simulator
npm install
npm run dev        # http://localhost:5173

Other scripts:

npm run build      # type-check + production build (outputs to dist/)
npm run preview    # preview the production build
npm test           # run the test suite (Vitest)

Requires a modern browser with WebGL.

---

Deployment

The app is a fully static single-page application (no backend) and is deployed on Vercel with continuous deployment from main:

• Build command: npm run build
• Output directory: dist

Any push to main triggers a new deployment.

---

Contributing

The project is under development and help is welcome — new fractals, surfaces, calculator tools, or fixes. A good contribution:

1. Keeps the shared math core shared (no duplicate parsers/engines).
2. Adds a test for non-trivial math (npm test must stay green).
3. Uses no eval / new Function — everything goes through the parser/AST.

Fork, branch, and open a pull request.

License

Released under the MIT License.