Coupled Pendulums Sandbox

Interactive sandbox for serial coupled pendulums with two complementary views of the same system:

• Nonlinear Sandbox: integrates the full coupled equations for large angles, unequal lengths, and unequal masses.
• Linear Modes: solves the small-angle generalized eigenvalue problem to show normal modes, frequencies, and modal superposition.

The frontend is a React + Vite canvas app. A persistent C++ engine now owns both the nonlinear time integration and the linear modal solver, while Node acts as a small WebSocket bridge between the browser and the native process.

Demo Video

Download the higher-quality recording (demo.gif)

What Is Implemented

• Arbitrary number of pendulums from 1 to 10
• Equal/unequal toggles for:
  • lengths
  • masses
  • initial angles
• Nonlinear time evolution with RK4 integration
• Linear modal analysis with unequal lengths and unequal masses
• Fading trails for each bob so phase-space-like recurrence is easier to see on the canvas

Mathematical Scope

• The nonlinear mode is the physical sandbox. It supports large angles and can show strongly non-periodic motion, including chaotic-looking behavior in appropriate energy regimes.
• The linear mode is intentionally not chaotic. After small-angle linearization, the system becomes an integrable modal superposition problem.

The full derivation of the implemented model is in docs/mathematical_model.md.

Project Layout

• engine_cpp/
  • C++ simulation engine for nonlinear dynamics and linear normal modes
• backend_node/
  • Node bridge exposing the persistent C++ engine over WebSocket
• frontend_web/
  • React UI, canvas renderer, controls, and recording

Running Locally

1. Build the C++ engine

From the repository root:

cmake -S engine_cpp -B engine_cpp/build
cmake --build engine_cpp/build --config Release

2. Start the backend

cd backend_node
pnpm install
pnpm start

The backend expects the executable at engine_cpp/build/Release/pendulum_cli.exe.

3. Start the frontend

cd frontend_web
pnpm install
pnpm dev

Then open http://localhost:5173/.

The frontend reads the backend WebSocket URL from frontend_web/.env:

VITE_BACKEND_WS_URL=ws://localhost:3001

For deploys, copy frontend_web/.env.example and set it to your public backend WebSocket URL.

Notes

• In Nonlinear Sandbox, chaos is possible but not guaranteed for every release condition.
• In Linear Modes, large angles are clamped because the modal model is only valid in the small-angle regime.
• The current implementation assumes point masses connected by rigid, massless rods in a planar serial chain.

Core Equations

For the full nonlinear serial chain with unequal masses and unequal lengths, the implemented equations are

$$\sum_{j=1}^{n} \mu_{ij} l_j \cos(\theta_i-\theta_j)\,\ddot{\theta}_j = -\mu_i g \sin(\theta_i) - \sum_{j=1}^{n} \mu_{ij} l_j \sin(\theta_i-\theta_j)\,\dot{\theta}_j^2$$

with

$$\mu_i = \sum_{k=i}^{n} m_k \qquad \mu_{ij} = \sum_{k=\max(i,j)}^{n} m_k$$

That nonlinear system is what the native C++ engine integrates in Nonlinear Sandbox.

For the small-angle modal view, the same C++ engine solves the linearized generalized eigenvalue problem

$$K v = \lambda M v \qquad \lambda = \omega^2$$

with

$$M_{ij} = \mu_{ij} l_i l_j \qquad K_{ij} = \delta_{ij}\,\mu_i g l_i$$

Where To Look

• For the real mathematical model implemented in the app, read docs/mathematical_model.md.
• For the frontend transport and canvas renderer, look at frontend_web/src/App.tsx.
• For the native simulation loop, look at engine_cpp/src/simulation_engine.cpp.
• For the linear modal solver, look at engine_cpp/src/pendulum_system.cpp.

Project Docs

Documentation for the rest of the stack is now organized in docs/:

• docs/index.md
• docs/architecture.md
• docs/frontend.md
• docs/backend.md
• docs/engine_cpp.md
• docs/development.md
• docs/docs_site.md

If you want a browsable docs site, install the Python docs dependencies and run:

python -m pip install -r requirements-docs.txt
python -m mkdocs serve