Realism

What Realism Is

Realism is the physical-law layer of Eustress. Each law is a plain function over SI quantities, such as the Nernst potential or the Euler buckling load, kept in one library that Studio, eustress-headless and scripts share. A few laws are also wired into systems that update parts while a run plays, which is how a battery drains, a concrete slab cracks and a hot block warms its neighbor.

The plugin that registers those systems is part of the core simulation tier, so it is always on, in Studio and in eustress-headless. Rigid-body motion belongs to Avian and is covered in Physics; Realism adds the quantities rigid bodies do not carry, and Simulation covers the clock and the recordings that capture them.

Systems and Libraries

A law reaches a Space in one of three ways, and the way decides what a file can do with it:

Not in this build

The realism library also holds GPU compute for fluid particles, a symbolic solver and quantum statistics. They sit behind build features that Eustress Engine does not enable, so they are not part of the app.

Sections in a Part File

A part joins a realism system through a section in its file. The loader reads five sections on any class:

Destructible parts need no section at all. Set destructible in [properties] and the part takes its mechanical constants from its material name:

[properties]
material = "Concrete"
destructible = true    # dents and cracks during Play

[metadata]
class_name = "Part"

A [material] block replaces the preset

The loader reads a [material] block as written: a key it leaves out is 0, not the preset's value. The dent model then falls back to generic plastic constants for each missing mechanical value, and heat conduction ignores a part with no conductivity, density or specific heat. Name the material in [properties] instead, and write a [material] block only for a material the presets do not cover, with every constant filled in.

In Properties

Select a part and Properties shows Destructible under Physics, and the realism sections its file declares under Material, Thermodynamic and Electrochemical. For a destructible part with no [material] block, the Material category lists the constants its material name implies, without writing them to the file.

Those rows show the file's values. The live state of a running model, such as a cell's charge or temperature, is published as sim values: read it with the simulation tools or in the run's recording.

Units and Constants

Every law works in SI units, and so do the file keys, with a few named exceptions:

Physical constants come from one module: R = 8.314462618 J/(mol·K), F = 96,485.33212 C/mol, k_B = 1.380649e-23 J/K, N_A = 6.02214076e23 /mol, G = 6.67430e-11 N·m²/kg² and the Stefan-Boltzmann constant 5.670374419e-8 W/(m²·K⁴).

Material Presets

A material's constants are 14 numbers: Young's modulus, Poisson's ratio, yield and ultimate strength, fracture toughness K_IC, hardness, thermal conductivity, specific heat, thermal expansion, melting point, density, static and kinetic friction, and restitution, plus any custom numeric keys. Eight presets supply them by name, and a part's appearance material maps onto one:

Names match without regard to case, spaces, underscores or hyphens. A name with no preset, such as Gold, gives a destructible part generic plastic-like constants. The library derives the rest from these: shear modulus G = E / (2(1 + ν)), bulk modulus, the Lamé constants, thermal diffusivity k / (ρ c_p) and the speed of sound √(E / ρ). It calls a material brittle when K_IC is below 8 MPa·√m or its yield strength is at least 90 % of its ultimate strength.

Dents

During Play, a destructible part that is struck takes a dent computed from contact mechanics. The impact energy comes from the closing speed, treating the collision as fully inelastic. A static part counts as immovable, and the striking body is treated as a sphere whose radius is half its smallest dimension.

Below Johnson's yield-onset energy the dent is elastic and springs back; above it the dent is plastic, using Tabor hardness H = 3σ_y, and stays:

The dent spreads over a patch of radius √(2 R δ), and its depth is physical, in meters, with no visual exaggeration.

Pausing undoes dents

Dents exist only while a run is playing. Pause or Stop restores every dented mesh, and resuming does not bring the dents back. Fracture fragments stay until Stop.

Cracks and Fragments

When the impact energy exceeds the part's Griffith threshold, the part cracks instead of denting. The threshold is the material's critical energy release rate times the part's smallest cross-section, the cheapest path for a crack:

So a 10 kg block that hits an anchored slab at 2 m/s brings 20 J: enough to crack glass or concrete, and only a dent in plastic or steel.

A crack splits the part into two dynamic bodies along a plane that contains the impact direction, so a part struck from above splits down through itself. The original part is hidden rather than deleted, and Stop brings it back and removes the fragments. Four guards stop a chain reaction: a fragment can be fractured again at most twice, a cut that would leave a piece under 0.05 m long is refused, a new fragment cannot crack for 0.3 s, and at most 4 fractures happen per frame.

The Stress Library

The library's stress and strain tensors are 3 by 3 and symmetric. A stress tensor caches its von Mises stress, principal stresses, hydrostatic stress and maximum shear. Functions convert between the two with generalized Hooke's law, including plane stress and plane strain, and test yield:

A material yields when σ_vm ≥ σ_y (von Mises) or τ_max ≥ σ_y / 2 (Tresca), and its safety factor is σ_y / σ_vm. These are Rust functions today: a per-frame system updates stress from strain on entities that carry both tensors, and no file section attaches them yet.

Conduction Between Parts

Parts that carry both [material] and [thermodynamic] exchange heat by conduction. Every 0.5 s the engine pairs any two such parts whose centers are within 0.5 m, and every frame it moves heat across each pair by Fourier's law, using the harmonic mean of the two conductivities:

The contact area A is the smaller X extent of the pair times the smaller Z extent, L is the distance between the centers (at least 1 mm), and V is each part's volume from its size. Each contact changes a part's temperature by at most 50 K per frame, and pairs less than 0.01 K apart are skipped. A contact, once made, is kept even if the parts move apart.

[material]
name = "Aluminum"
density = 2700.0              # kg/m3
specific_heat = 900.0         # J/(kg K)
thermal_conductivity = 237.0  # W/(m K)

[thermodynamic]
temperature = 350.0           # K

Conduction runs while you edit

Conduction steps on real frame time whenever the Space is open, in Edit as well as Play, and does not follow the time scale. Temperatures therefore drift while you edit, a run starts from wherever they are when you press Play, and Stop returns them to that point.

Heat Laws and Cycles

The thermodynamics library covers the rest of heat as functions: ideal and van der Waals gases, work in isobaric, isothermal and adiabatic processes, heat capacities, entropy changes, Carnot efficiency and heat-pump COP, conduction, convection and radiation rates, phase change, enthalpy, and the Gibbs and Helmholtz free energies. The thermocycles library adds steady-state Rankine, Brayton, Otto and Diesel, refrigeration and heat-exchanger analysis (LMTD and effectiveness-NTU).

One Step

The cell model turns a part's [electrochemical] section into a live battery. Every Play frame it steps each such part whose capacity is above zero, cutting the frame's simulated time into clock timesteps (1/60 s by default; see limits of compression). The cell with the largest capacity is the one driven by sim values and published. With a [thermodynamic] section the cell's temperature evolves; without one it stays at 298.15 K.

Open-circuit voltage follows the Nernst equation, with the reaction quotient taken from the state of charge and n = 2 electrons. The standard potential is the cell's own standard_potential_v, or the sodium-sulfur 2.23 V when unset:

Three losses come off it. Resistance rises in the cold by an Arrhenius law (0.35 eV unless set). Activation loss is the exact inverse of symmetric Butler-Volmer, with an exchange current density of 50 A/m². Transport loss rises steeply as the current density j approaches the limiting current σ(RT/F) / (1.5 t), set by the separator's ionic conductivity σ and thickness t, and is zero when no separator is set.

Charge counting, heat and temperature close the step:

Dendrite risk compares the plating current density on charge with a critical current density: the cell's j_crit_a_per_m2, or a Monroe-Newman estimate from sodium constants (G = 30 GPa, δ = 5 nm, V_m = 23.7 cm³/mol, about 131 A/m²) when unset. Discharge scores zero, and the risk is capped at 1.

Life and Fade

Capacity retention is the product of five independent channels, so whichever bites first sets the life:

• Lithium inventory: each unit of charge loses a little metal to interphase, more for deeper cycles (depth to the power 0.8) and at higher temperature. A reservoir (li_reservoir_frac) buffers this channel only.
• Cathode cracking: fatigue damage per unit charge of crack_k times depth to the power 1.5, optionally scaled by stack pressure.
• Calendar ageing: grows with the square root of equivalent hours, which accrue on every step, faster at high charge and temperature; the default coefficient is 2.14e-4.
• Creep: above creep_threshold_mpa (1 MPa by default) the plated metal creeps at a rate with exponent 6.6 in the overpressure, and only strain beyond the accommodation void (creep_accommodation_frac) counts.
• Bridged layers: creep that crosses the separator shorts whole layers of a layer_count stack, counted as layers lost rather than fade.

With sei_thickness_nm set, the coulombic loss behind the lithium channel is derived from deposit roughness, areal capacity q and stack pressure P instead of a fitted efficiency (0.995 by default):

battery.cycle_count counts equivalent full cycles: the charge moved divided by twice the effective capacity.

Keys and Readouts

The main [electrochemical] keys, and what the model does when a key is absent:

[electrochemical]
capacity_ah = 40.0
soc = 1.0
internal_resistance = 0.002      # ohm at 25 C
electrode_area_m2 = 0.74         # all layers
thermal_mass_j_per_k = 3000.0
thermal_resistance_k_per_w = 0.6
stack_pressure_mpa = 2.0
cell_mass_kg = 3.5

[thermodynamic]
temperature = 298.15             # K

[metadata]
class_name = "Part"

Every Play frame the model publishes 24 readouts as sim values:

Because they are sim values, every run records all 24, and nine of them carry watchpoints; see sim values for the keys the model reads back, battery.mode and battery.target_current.

Rune Law Modules

Rune scripts reach the law library through 13 modules under eustress::realism. They take and return f64 values and wrap the same Rust functions the engine uses:

use eustress::log_info;
use eustress::realism::structures;

pub fn on_init() {
    // A 2 m steel column, 50 mm square, pinned at both ends (K = 1).
    let i = structures::moment_of_area_rectangle(0.05, 0.05);         // m^4
    let p_cr = structures::euler_critical_load(200.0e9, i, 2.0, 1.0); // about 257 kN
    log_info(`Euler buckling load: ${p_cr} N`);

    // A 1 mm edge crack (Y = 1.12) in glass under 20 MPa of tension.
    let k = structures::stress_intensity_factor(20.0e6, 0.001, 1.12);
    if structures::fracture_occurs(k, 0.7e6) {
        log_info("K exceeds glass's K_IC of 0.7 MPa m^0.5: the crack runs.");
    }
}

Euler buckling is P_cr = π² E I / (K L)², and the stress intensity is K = Y σ √(π a). See Scripting for how scripts are attached and run.

Agent Tools

Two tools of the MCP server expose the library to agents:

• calculate_physics evaluates one of nine formulas by name: ideal_gas_pressure, kinetic_energy, gravitational_force, heat_transfer_conduction, nernst_potential, escape_velocity, spring_force, drag_force and buoyancy_force.
• query_material returns a part material's appearance values and the mechanical constants of the preset it maps to, or says that no preset matches.

{ "tool": "calculate_physics", "arguments": {
    "equation": "nernst_potential",
    "params": {
        "standard_potential": 2.23,
        "temperature_k": 298.15,
        "electron_count": 2,
        "reaction_quotient": 1.0
    }
} }

Running, stepping and comparing models uses the simulation tools listed in Simulation.

The Walkthrough

The V-Cell is Voltec's battery cell, and its case study is the end-to-end test of the cell model and the tools around it. The walkthrough, docs/architecture/VCELL_CASE_STUDY.md in the repository, sets out to show that Eustress can detect a simulation anomaly, diagnose it with the Workshop agent, correct it through MCP tools and verify the fix, with no manual step after the run starts. The cell is the subject because it produces continuous telemetry with well-defined safety thresholds: voltage, temperature and dendrite risk.

Its prerequisites:

• A Universe with a Space containing a V-Cell prototype entity.
• The cell model producing battery.* sim values.
• A Rune SoulScript attached to the V-Cell entity.
• The Workshop panel open with a valid BYOK API key.
• The Watchman enabled, which it is by default.

Detect, Repair, Verify

The limiter the walkthrough adds halves the current whenever the cell passes 55 °C. As a complete script:

use eustress::{get_sim_value, set_sim_value};

pub fn on_update(dt) {
    let temp = get_sim_value("battery.temperature_c");
    if temp > 55.0 {
        let reduced = get_sim_value("battery.current") * 0.5;
        set_sim_value("battery.current", reduced);
    }
}

A complete cycle is judged against the walkthrough's checklist:

What Models It

Everything the walkthrough exercises is the machinery on this page and on Simulation: the V-Cell's [electrochemical] section drives the cell model, its readouts are the battery.* sim values, telemetry is written once a second, the runtime snapshot four times a second, and Stop exports the recording. The Watchman runs in Studio during Play and ships with these thresholds:

It polls every 5 seconds, waits 30 seconds before repeating an alert for the same value, and stops after 10 alerts in a run. In the Workshop, a set_sim_value call runs without an approval prompt.

Lower the charge rate with the target current

Phase 3 of the walkthrough writes battery.current = -1.5 with set_sim_value. A current written by a tool is replaced before the cell model reads it, so from a tool set battery.mode to 1 and battery.target_current to 1.5, which charges at 1.5 A. Inside a script, as in the limiter above, battery.current takes effect directly.

Laws Without a File Section

Several laws already run as systems but have no way in from a Space file: continuous and batch chemical reactors, circuit elements with motors and power converters, particle fluids with buoyancy and aerodynamic drag, and stress tensors on parts. They will gain file sections or classes, so a part can carry a circuit or a reactor the way it carries a cell today.

The ARC-1 reactor model already exists as systems: one-group point kinetics, thermal-hydraulics, power conversion, a battery buffer, a three-loop PID controller and a scram monitor, publishing arc1.* watchpoints. A [nuclear] section already records an ArcReactorCore's starting state. The plugin that attaches the reactor's components to such instances is not yet added to the app; once it is, the reactor will run in any Space.

Simulated Time for Every Law

Only the cell model integrates against the simulation clock today. Heat conduction, the reactor and the reaction and circuit systems step on frame time, several of them limited to 0.05 s per frame, so a time scale does not speed them up. Moving them onto the clock will make one time scale apply to every model in a run. The GPU fluid path and the symbolic solver will follow.