Constraint Docs

Overview

What Constraint Is

Constraint is a zero-backend simulation workbench for ordinary differential equations and physical systems. Users write model definitions in Fianko Script, verisolv integrates the ODE system in WebAssembly, and the browser renders the trajectory.

Language Fianko Script maps define state, parameters, ODEs, plot type, and runtime settings.

Solver verisolv WASM parses ODE expressions once and exposes derivatives plus RK4 steps.

Runtime Static HTML, CSS, JavaScript, and WASM. No server process after deployment.

Architecture

How the Pieces Fit

FS evaluates the source. The final FS expression must return a map. The WASM binding returns that map as structured valueJson.
The app validates the model map. It reads ordered state and parameter names, slider specs, ODE expressions, plot type, step size, warmup, and trail length.
verisolv compiles the ODE system. The browser creates an OdeSystem with comma-separated state names, parameter names, and one expression per state.
The renderer draws the current trajectory. Canvas handles every plot type. WebGL is available for the Lorenz attractor.
The URL stores the applied simulation. The compact sim= payload restores the model, changed parameters, solver mode, renderer mode, and time scale.

Fianko Script

Model Map Reference

FS maps are string-keyed. Use stateNames and paramNames to preserve order, then provide keyed values in states, params, and odes.

let a = 1

{
  "title": "Custom Oscillator",
  "description": "Two-state phase portrait.",
  "stateNames": "x,y",
  "states": {"x": 1, "y": 0},
  "paramNames": "a",
  "params": {"a": {"value": a, "min": 0, "max": 3, "step": 0.1}},
  "odes": {"x": "y", "y": "-a * x"},
  "plot": "phase",
  "dt": 0.006,
  "warmup": 100,
  "trail": 2200,
}

Field	Required	Purpose
`stateNames`	Yes	Comma ordered state variables.
`states`	Yes	Initial numeric value for each state.
`paramNames`	No	Comma ordered parameters used by sliders and ODE expressions.
`params`	No	Slider specs with `value`, `min`, `max`, and `step`.
`odes`	Yes	One expression string for every state.
`plot`	No	`phase`, `lorenz`, `pendulum`, `orbit`, or `sir`.

Numerics

Solver Modes

The browser-native verisolv package exposes derivative evaluation and RK4 stepping. Constraint uses those calls for three visible modes:

RK4: Fourth-order Runge-Kutta from verisolv WASM.
Midpoint: Second-order midpoint step using verisolv derivatives.
Euler: First-order explicit Euler step using verisolv derivatives.

The wider verisolv project also contains Python methods for Euler, RK4, RK45, Adams-Bashforth, BDF, heat, and wave equations, plus a Lean proof for the Euler recurrence.

Rendering

Canvas, WebGL, and Snapshots

Canvas renders every preset. WebGL renders the Lorenz attractor as a rotating phase trajectory. If WebGL is selected for another plot, the app keeps Canvas active and labels the limitation plainly.

Export PNG saves the currently visible frame. It works for Canvas and the WebGL Lorenz renderer.

URLs

Share Format

The app writes one compact sim= query parameter. It contains a version number plus the applied preset or custom source. Changed parameters, solver mode, renderer mode, and time scale are only included when they differ from defaults.

{
  "v": 1,
  "p": "sir",
  "r": {"beta": 3.1},
  "s": "midpoint",
  "g": "webgl",
  "k": 1.7
}

Presets

Included Systems

LorenzChaotic 3D convection model.

Double PendulumCoupled nonlinear angular system.

Lotka-VolterraPredator-prey phase cycles.

Orbital MechanicsPlanar two-body motion.

Van der PolNonlinear oscillator with a limit cycle.

SIRSusceptible, infected, recovered population curves.

Local Work

Run and Verify

python3 -m http.server 5173
node --check src/app.js
node --check scripts/smoke.mjs
node scripts/smoke.mjs

The smoke test starts a temporary static server, opens headless Chrome or Chromium, checks every preset, checks a shared preset URL, and checks a shared custom FS URL.