---
name: ferret-physics-electric
description: Use for circuits in Ferret: Circuit with sources, wires, resistors, lamps, heaters, motors, generators, inductors, capacitors, diodes, transformers, relays, fuses and breakers; mains and three-phase; faults and tying a motor to a shaft.
---

# Electric circuits

## When to use
Lamps that surge and burn, fuses and breakers that trip, motors and generators, wiring puzzles.

## The model
A `Circuit` solves its elements each step (nodes by name, `'0'` is ground). Parts: `VSource`, `ISource`, `Battery`, `Resistor`, `Lamp` (inrush, burnout, `T`), `Heater`, `Wire` (overheat), `Fuse` (`I²t`), `Breaker` (thermal + magnetic), `Rcd`, `Switch`, `Capacitor`, `Inductor`, `Diode`, `IdealTransformer`, `DCMachine`, `InductionMotor`, `Relay`. `circuit.phasor(ω)` solves in the frequency domain.

## Steps
1. `c.add(new VSource('V', 'a', '0', 230))` and the loads; every node needs a path to ground.
2. `c.step(dt)`; sub-step fast circuits with `maxStep`; call `circuit.restart()` after throwing a switch.
3. Events: `circuit:short`, `circuit:blown`, `lamp:burnt`, `trip`, `overheat`.
4. Motors: copy the shaft's `omega` to the machine, feed its `torque` to the shaft (`ferret-physics-mechanisms`).
5. Link faults to the world: `wireFire`, `arcFlash` (`ferret-physics-links`).
6. Commands: `circuit.add|connect|set|state|step`, `meter.read`.

## Check afterwards
A 2.3 kW kettle on 230 V draws 10 A; kettle plus dryer trips a 16 A breaker; rectifier ripple is about `I / (2 f C)`.

## What usually goes wrong
- NaN or huge voltages: a node with no path to ground, or a source across a short.
- A switch makes a spike: no `restart()`.
- A motor does not turn: `omega` not copied, or `k` sign reversed.
- Energy does not close on a resonating circuit: lower `maxStep`.

## Files

- `reference/electric.md` — Circuits with batteries, lamps, motors, generators and heaters; fuses, breakers and wires that fail; mains and three-phase.
- `reference/api-physics-electric.md` — every export of `@ferret/physics-electric` with signature and doc comment
- `reference/commands.md` — 7 commands of these packages with their arguments
- `recipes/machines-and-circuits.md` — Six recipes: a lamp that surges and burns, a rectifier that smooths, a transformer, a wind turbine lighting a lamp through a generator, a winch that cannot run back, a flywheel that evens out a pulsing drive.
- `recipes/flooded-cellar.md` — A burst main fills a cellar faster than the sump pump can empty it; the water reaches a socket, the circuit shorts, the breaker trips, the pump stops, and the flood wins.