Electricity

Package @ferret/physics-electric, capability electric.

What it is for#

Anything that runs on current: a torch with a battery that runs down, a kettle on a fuse, a garage-door motor that stalls, a generator turned by a windmill, a relay, a lamp that burns out when over-volted, a wire that overheats inside a wall.

Motors turn shafts of mechanisms and generators are turned by them. Heaters feed parts of heat. Every protection device reports what it did as an event.

How a circuit works#

A Circuit is a list of elements, each connecting two named nodes ('0' is ground). Every step the circuit solves for the voltage at every node, so Ohm's and Kirchhoff's laws hold exactly. Nothing is scripted: a lamp dims when the battery sags, because the battery's voltage falls with its charge and with the current it delivers.

Energy is accounted for. circuit.balance() returns what the sources delivered, what was dissipated, what is stored in capacitors and inductors, and the error, which stays tiny. That makes the electrical side trustworthy when you tie it to heat and motion.

If you throw a switch, call circuit.restart() so the next step does not ring.

The parts#

magnetForce is the pull of an electromagnet, railForce the push in a rail gun.

import { Circuit, VSource, Resistor, Capacitor } from '@ferret/physics-electric';

const c = new Circuit();
c.add(new VSource('V', 'a', '0', 5));
c.add(new Resistor('R', 'a', 'b', 1000));
c.add(new Capacitor('C', 'b', '0', 1e-6));
c.step(1e-5);
c.voltage('b');          // the capacitor charges along 1 − e^(−t/RC)

Half of what the source delivers ends up in the capacitor and half as heat in the resistor, as it should.

Gameplay ideas#

• A battery that runs down. A 1 Ah cell loaded by 0.5 A lasts two hours. Read soc for the state of charge and heat for what was lost inside.
• Sizing protection. A fuse blows when the current's square times time passes its rating. A kettle on a 10 A breaker, a wire thinner than its load, a residual-current device on a wet floor are all one circuit away.
• A motor. It runs at V/k − R·T/k²: the drive voltage over its constant, less a droop under load. Held still it draws V/R, which is how a jammed motor burns out.
• A generator. Drive the same machine from outside with a resistor across it and it produces k·ω volts, loading the shaft by k·I. A windmill that lights a lamp is two parts and a wire.

Heat a part#

el.bindHeater(circuit, heaterName, entity) sends the heater's power into the entity's part of heat every step. A 24 V supply across a 10 Ω heater warms a part by V²/R watts. The part's temperature, in turn, changes the heater's resistance (alpha).

Tying a motor to a shaft#

const el = electric();
host.register(el);
host.enable('electric');

const circuit = el.addCircuit('main');
circuit.add(new VSource('V', 'a', '0', 12));
const motor = circuit.add(new DCMachine('M', 'a', '0', 0.05, 0.5));

el.bindMachine('main', motor, drivetrain, shaft);    // speed and torque are exchanged every sub-step

The drivetrain is stepped by whoever owns it: the machine capability or your own loop. bindInduction does the same for an induction motor.

In a world#

The capability steps each circuit in sub-steps of at most maxStep (1 ms).

Events: circuit:blown, circuit:trip, circuit:short (a source carries more than shortCurrent), circuit:overheat, battery:empty, lamp:burnt, motor:stall, each with { circuit, element, time }.

Commands: circuit.info, circuit.state { circuit } (node voltages, element currents and powers, balance), circuit.add { circuit, kind, name, a, b, value? }, meter.read { circuit, node }.

Parameters#

Works with#

heat: heaters warm parts. mechanisms: motors and generators on shafts; a windmill drives a generator and a generator lights a lamp (links). liquids: a pump's pumpLoad is the mechanical side of an electric motor.

Cost#

A dense solve per circuit per sub-step, for a few dozen nodes; lamps and diodes add iterations. Raise maxStep for slow circuits, and keep it at or below a tenth of the fastest time constant (RC, L/R, 1/f).

When it does not behave#

Worked numbers (RC charging and energy balance, battery run time, fuse and breaker timing, motor speed, stall current) are in tests/unit/examples/physics-electric.test.ts.

Reference#

electric, ElectricCapability, Circuit, Battery, Fuse, Breaker, Wire, Lamp, Heater, DCMachine, InductionMotor, mains.