Fermion Labs Documentation

Welcome to the Fermion Labs engineering and architectural documentation. This guide details the internal mechanisms of our web-based physics engine, including rendering pipelines, state management, our dynamic multi-theme injection system, and guidelines for writing high-performance React code.

Introduction & Platform

Welcome to Fermion Labs, an advanced physics simulation engine designed specifically for the modern web. Our goal is to make high-fidelity physical phenomena accessible directly in the browser, without requiring users to download heavy desktop applications or specialized software.

Whether you are a student visualizing wave functions, an educator demonstrating orbital mechanics, or a researcher exploring density functional theory, Fermion Labs provides a mathematically rigorous, beautifully rendered, and highly performant sandbox to explore the universe.

Technology Stack

To achieve native-like performance and stunning visuals on the web, Fermion Labs is built upon a bleeding-edge modern technology stack:

Next.js 15 (React 19)

Provides the core application routing, server-side rendering, and API routes. The App Router architecture ensures fast page loads and seamless navigation.

React Three Fiber & Three.js

Powers the high-performance WebGL rendering engine, allowing us to display thousands of particles, complex 3D meshes, and custom shaders at 60 FPS.

Zustand

Handles global application state efficiently. It avoids the cascading re-render issues common with standard React Context when dealing with high-frequency updates.

Tailwind CSS v4

Provides the dynamic styling engine. Paired with custom CSS properties, it allows for our fluid, multi-theme aesthetics.

How to Use the Site

Fermion Labs is structured around a centralized Simulation Catalog. From the main navigation, you can access the catalog to browse through various physics domains, including Classical Mechanics, Electromagnetism, Quantum Mechanics, Relativity, and more.

  • Browsing Domains: Use the filtering options to narrow down simulations by their physics domain or specific topics.
  • Interactive Equations: Many simulations provide mathematical context via beautifully rendered KaTeX equations.
  • User Accounts: By creating an account (powered by Supabase), you can save simulation states, track your usage time, and access premium modules.

Running Simulations

Once you select a simulation, you will be taken to a dedicated sandbox environment.

  1. Initialization: The canvas will initialize and render the initial state of the physical system. The engine automatically adapts to your device's DPI for maximum clarity.
  2. Controls: Use the "Run Simulation" button (or the play icon) to start the mathematical integration. You can pause, step forward, or reset the system at any time.
  3. Parameter Adjustment: Most simulations include real-time sliders and inputs. Adjusting masses, charges, lengths, or constants will instantly update the simulation logic without requiring a page reload.
  4. Data Export: While the simulation runs, physics data (like velocity, position, or energy) is recorded into a ring buffer. You can export this data to a CSV file for external analysis.

How Simulations Render

Fermion Labs enforces a strictly decoupled Logic-Render loop. To maintain 60 frames per second, we never perform heavy mathematical integrations or DOM updates on the main thread.

1. Web Worker Physics

Complex $O(N^2)$ calculations, such as N-body gravitational interactions or quantum wave function evolution, are offloaded to dedicated Web Workers. These workers compute the next state of the universe and pass the resulting typed arrays back to the main thread via zero-copy transfer.

2. The WebGL Canvas

We use React Three Fiber to manage the Three.js scene graph declaratively. Instead of relying on React state (`useState`), which triggers slow cascading re-renders, we use React Refs to mutate the 3D objects directly.

import { useFrame } from '@react-three/fiber';
import { useRef } from 'react';

export function QuantumWellSimulation() {
  const meshRef = useRef();

  useFrame((state, delta) => {
    // 1. Fetch computed wave-function array from Worker
    const waveData = PhysicsWorker.getWaveState();
    
    // 2. Mutate Three.js InstancedMesh directly (Zero React Overhead)
    meshRef.current.geometry.attributes.position.needsUpdate = true;
  });

  return (
    <instancedMesh ref={meshRef} args={[geometry, material, count]} />
  );
}

3. Post-Processing & Shaders

To give our simulations their signature cinematic, glowing appearance, we utilize custom GLSL shaders and post-processing pipelines. We apply bloom filters, noise overlays, and adaptive pixel ratio scaling to ensure the physics look as beautiful as they are accurate.