Links between capabilities

Package @ferret/physics-links, capability name links, phase stretch (order 1000, last).

What it is for#

Each physics capability knows only itself. A link is where one capability's output becomes another's input, so a world closes its loops: a chemical vessel sits in a water bath, a hot wall warms the gas of a tank, a slipping brake heats its drum, steam from a boiler turns a shaft, a reactor's coolant drives a turbine, a screw on a shaft pushes a ship and loads the engine, an arc fault blasts, an overloaded wire lights a fire.

Links read and write the plain fields and methods of the objects they join (a heat part, a chemical vessel, a gas volume, a shaft, a reactor, a thruster, a kernel body), so the package imports none of their packages and you can write your own in a dozen lines.

The model#

A Link is { kind, moved, step(dt, host, contacts) }. step reads one side, writes the other, once per world step after the capabilities have stepped; moved counts the energy that crossed (J). The links capability holds a list of them and keeps the scene energy account: you register terms (stores such as kinetic, heat, chemical, electric; and sinks such as losses and the condenser), and energy() sums them. In a closed scene the total stays where it started.

First use: a brake heats its drum, and the energy adds up#

import { slipHeats, links } from '@ferret/physics-links';

const cap = links();
cap.add(slipHeats(brake, drum, net));                          // the brake's losses become heat in the drum
cap.account({ name: 'wheel', joules: () => train.kinetic() }); // the stores that make up the scene's energy
cap.account({ name: 'drum', joules: () => drum.H });
cap.energy().total;                                            // stays where it started, in a closed scene

When the brake slows the wheel, its rotation goes into the drum: the wheel's term falls, the drum's rises by the same amount, and the total stays put. If the sum of your terms drifts, a link or a capability is losing energy. That is the way to find a bug in a scene.

Recipes#

A hot wall and a tank#

cap.add(gasInPart(gas, wall, net, 2));       // 2 W/K between the wall and the gas

A hot wall warms the gas, and the pressure in a closed tank rises with it. The same pattern with a cooling wall and a vessel (vesselInPart) gives a reactor in a water bath; a vessel that raises chem:runaway in a bath that cannot carry the heat is a thermal-runaway scenario.

A turbine on a reactor#

import { turbineOnReactor } from '@ferret/physics-links';

cap.add(turbineOnReactor(reactor, shaft, { efficiency: 0.33, maxTorque: 1e5 }));

A third of the coolant's heat becomes torque on the shaft. Chain it on: a generator on that shaft (electric bindMachine) lights a lamp whose power comes from the reactor. The steam path in between has its own link, engineOnBoiler.

In a world#

const cap = links();
host.register(cap);
host.enable('links');
cap.add(slipHeats(brake, drum, heat.network));
cap.account({ name: 'wheel', joules: () => train.kinetic() });

The capability steps every link after the other capabilities, once per world step. links.energy (command) returns { total, terms }. Events from the capabilities (circuit:short, circuit:trip, circuit:overheat) are what arcFlash and wireFire listen to; each fires once per fault and has dispose().

Write your own link#

A link is any object with kind, moved and step. Read the source, write the target, add the energy that crossed to moved:

const solarHeatsRoof: Link = {
  kind: 'sun→roof', moved: 0,
  step(dt) { const q = irradiance() * area * dt; net.add(roofPart, q); this.moved += q; },
};
cap.add(solarHeatsRoof);

Budget#

A few reads and writes per link per step; hundreds of links are free.

Debugging#

Reference#

links, LinksCapability, Link, EnergyTerm, vesselInPart, gasInPart, slipHeats, turbineOnReactor, engineOnBoiler, screwOnShaft, arcFlash, wireFire, mudOver, boilerFed, @ferret/physics-links.