الانتقال إلى المحتوى الرئيسي

Physics Simulation

Build something the world doesn't have yet — starting from the equations the world already runs on.

Classical, fluid, thermal, oceanic, and seismic physics — six shipping apps, all computing at ≤0.1% error in a browser, all grounded in the HULYAS master equation and the KO42 metric tensioner. Every app is open to you: open the page, view the source, fork the math, swap an operator, run it again.

This is the template chapter for the Build track. The other six chapters (Robotics & Controls · Life Sciences · Climate & Energy · Cryptography & Identity · AI · Signal · Quantum · Software → Hardware) follow the same pattern.

What you will build​

By the end of this chapter you will have:

  1. Run a real 2D rigid-body simulator in the browser, stepping at HulyaPulse 1.287 Hz, and verified every constraint resolves to ≤0.1%.
  2. Called the /api/zeq/compute endpoint with NM19, NM22, NM26 operators and reconciled the server answer against your local calculation.
  3. Composed KO42 + one domain operator (your choice: NM, GR, QM-thermal, or fluid) and watched the Master Equation verify your output.
  4. Extended one of the six apps — new force field, new boundary condition, new coupling term — and filed a PR against hulyasmath/zeqsdk.

No magic. No scaffolds. No "coming soon." Every step references a file you can read and a button you can press.

The six anchor apps​

Each app solves a real problem with visible math. Click an app name to open its Build page — the SDK page, the live app, and the source are linked from each one.

AppProblemCore operatorsLive URL
Physics Simulator2D rigid body — collisions, friction, constraints, real-timeKO42 · NM19 (F=ma) · NM20 (Newton III) · NM26 (momentum) · NM27 (conservation)/apps/physics-simulator/
Aero / Wind TunnelDrag, lift, flow visualisation, CFDKO42 · NM19 · fluid operators (ρ v²/2) · QM wave-mechanical drag/apps/aero-wind-tunnel/
Fluid DynamicsNavier-Stokes, turbulence, boundary layerKO42 · incompressible NS · Reynolds-stress operators/apps/fluid-dynamics/
Thermo CyclesCarnot, Rankine, Brayton cycle efficiencyKO42 · QM14/QM15 (statistics) · GR35 (gravitational time dilation, optional)/apps/thermo-cycles/
Ocean DynamicsWave mechanics, thermohaline circulation, coastal modellingKO42 · NM28 (angular momentum) · shallow-water · Coriolis/apps/ocean-dynamics/
SeismologyEarthquake detection, wave propagation, Richter scaleKO42 · NM30 (oscillator) · GR38 (gravitational-wave operator, optional)/apps/seismology/

The math you need (and only the math you need)​

Physics in Zeq is always the HULYAS Master Equation with a small, explicit set of operators picked per problem. No hidden terms. No "magic constants."

The Master Equation — verbatim​

□ϕ − μ²(r)ϕ − λϕ³ − e^{-ϕ/ϕ_c} + ϕ₄₂ ∑_{k=1}^{42} C_k(ϕ)
   = T^μ_μ + β F_{μν} F^{μν} + J_{ext}
  • □ϕ — wave operator on field ϕ (time + space evolution)
  • −μ²(r)ϕ — local stiffness (mass term that changes with position)
  • −λϕ³ — nonlinear self-interaction (real-world complexity)
  • −e^{-ϕ/ϕ_c} — decay term (damping over distance/time)
  • ϕ₄₂ ∑ C_k(ϕ) — direct coupling to the 42 kinematic operators
  • RHS — stress-energy trace, EM coupling, external source

In this chapter, C_k(ϕ) is always KO42 + one of NM/GR/QM. You pick which one. The rest of the 42 stay at zero unless the problem actually requires them. That's the Operator Limit principle: one to three additional operators plus KO42, total ≤ four.

KO42 — the metric tensioner​

KO42 is always on. It's the operator that keeps spacetime geometry itself synced to HulyaPulse so every tick is 1.287 Hz coherent.

ds² = g_{μν} dx^μ dx^ν + α sin(2π · 1.287 t) dt²    (automatic)
ds² = g_{μν} dx^μ dx^ν + β sin(2π · 1.287 t) dt²    (manual; β user-set)
α ≈ 1.29 × 10⁻³

The sin(2π · 1.287 t) dt² term is the HulyaPulse metric modulation. It's tiny (α ≈ 0.129%) and averages to zero over one Zeqond (0.777 s), which is why R(t) always recovers S(t) exactly:

R(t) = S(t) [1 + α sin(2π f t + φ₀)]        f = 1.287 Hz

Newtonian Mechanics operators used in this chapter​

NM18  ∑F = 0 ⇒ v = const                    (first law)
NM19  F = ma                                 (second law)
NM20  F₁₂ = −F₂₁                             (third law)
NM21  F = G m₁ m₂ / r²                       (gravity)
NM22  W = F · d                              (work)
NM23  KE = ½ m v²                            (kinetic energy)
NM24  PE = m g h                             (potential energy)
NM25  KE + PE = const                        (energy conservation)
NM26  p = m v                                (momentum)
NM27  ∑p_init = ∑p_final                     (momentum conservation)
NM28  L = r × p                              (angular momentum)
NM29  τ = r × F                              (torque)
NM30  F = −k x ,  x(t) = A cos(ωt + φ)       (harmonic oscillator)

Fluid and thermal apps also reach into QM (partition statistics) and GR (gravitational corrections); those are noted on the per-app pages.

The 7-Step Wizard — applied to every app​

Every Build page in this chapter follows the same protocol verbatim. If you're reading for the first time, this is the mental model:

  1. Prime directive — KO42 is mandatory.
  2. Operator limit — 1–3 additional operators + KO42 (total ≤ 4).
  3. Scale principle — match operators to domain. No cosmological operator in a rigid-body sim.
  4. Precision imperative — tune to ≤ 0.1% error vs. ground truth.
  5. Compile via Master Equation — all picks slot into the C_k(ϕ) sum.
  6. Execute via Functional Equation — E = P_ϕ · Z(M, R, δ, C, X).
  7. Verify and troubleshoot — if error > 0.1%, go back to step 3.

The right-rail: runnable worked example​

Every Build chapter has one worked example you can execute without reading anything else first. For this chapter it's a pendulum — the simplest possible rigid-body simulation, solved three ways so you can see the operator layering.

Problem​

A simple pendulum, length L = 1.0 m, bob mass m = 1.0 kg, released from angle θ₀ = 30°. Compute the period T and verify against the small-angle ground truth.

Approach 1 — analytical small-angle (closed-form)​

For small angles, T_small = 2π √(L/g) = 2.0071 s. This is the ground truth we verify against.

Approach 2 — NM30 harmonic oscillator via hosted API​

# Fetch a demo key once per session (public, rate-limited)
DEMO_KEY=$(curl -s https://api.zeq.dev/api/demo-key | jq -r '.key')

# Compile the problem with KO42 + NM30
curl -s -X POST https://api.zeq.dev/api/playground/compute \
  -H "Content-Type: application/json" \
  -H "x-demo-key: $DEMO_KEY" \
  -d '{
    "operators": ["KO42", "NM30"],
    "params": {
      "k_over_m": 9.81,
      "amplitude": 0.5236,
      "omega": 3.1321,
      "duration_zeqonds": 4
    }
  }'

Expected response:

{
  "result": {
    "period_seconds": 2.0065,
    "error_vs_ground_truth_pct": 0.0298,
    "ko42_alpha": 0.00129,
    "hulya_pulse_hz": 1.287,
    "zeqonds_elapsed": 4
  }
}

Error: 0.0298% — well under the 0.1% imperative.

Approach 3 — same thing via the TypeScript SDK​

import { ZeqClient } from "@zeq-os/sdk";

const zeq = new ZeqClient({ demoKey: await ZeqClient.fetchDemoKey() });

const result = await zeq.compute({
  operators: ["KO42", "NM30"],
  params: { k_over_m: 9.81, amplitude: 0.5236, omega: 3.1321, duration_zeqonds: 4 },
});

console.log("period:", result.period_seconds);            // 2.0065
console.log("error:",  result.error_vs_ground_truth_pct); // 0.0298

Both call-paths hit the same compute server, return the same numbers, and verify the same ≤ 0.1% error budget. The SDK is a thin wrapper around the HTTP API — no hidden behaviour.

Philosophy — footnoted, deliberately brief​

Physics Simulation in Zeq rests on three commitments:

  • No black box. Every equation is printed on the page. Every operator has a one-line formula you can read, type, and verify. The Master Equation expands to a finite sum of named terms. Anything you can't see is a bug.
  • Implementation-first. Math shows up with a curl and a test next to it. Philosophy shows up as footnotes. If it doesn't compile, it doesn't ship.
  • Plant seeds. Six apps are the ground floor. A thousand are the ceiling. Open the source, fork an operator, cite the paper (DOIs below), build what the world doesn't have yet.

Seeds — horizons planted by this chapter​

The apps in this chapter are classical. The operators that run them also run frontier regimes that aren't in any app yet. If you want to work on these, start here — the math is already compiled.

  • Time crystals — extend NM30 with a modulated k(t) and verify Floquet-phase stability against a real lab dataset
  • Analogue gravity — couple fluid-dynamics + GR33 (Einstein field equations) to simulate a horizon in a bathtub
  • Non-Euclidean rigid bodies — ship a constraint solver on a curved g_{μν} and watch energy conservation bend
  • Ocean heat-transport at ≤0.1% — add thermohaline couplings to ocean-dynamics and calibrate against ARGO float data
  • Forensic seismology — invert seismic waves to localise sub-surface voids with GR38 as an optional channel
  • Thermodynamic mosaics — tile thermo-cycles over a 2D heat map to solve district-scale waste-heat reuse

Every seed is a legitimate research project. Every one of them builds on the six apps below.

Papers​

Start here​

Pick the app closest to what you want to build:

Middleware active. Kernel on the 1.287 Hz HulyaPulse. Awaiting next Zeqond.