improvement!: fix loop timing and own the control law as an Nx kernel

[jimsynz]

Requires bb ~> 0.26 for BB.Loop.

Addresses #43. Two commits, both breaking.

Warning

Existing loops must be retuned. Gain semantics, derivative behaviour and anti-windup behaviour all change. Details at the bottom.

1. Loop timing and a measured dt

The tick was re-armed with a fixed div(1000, rate) delay after the PID step and publish, so handler duration and scheduler latency both pushed the period out. Measured over 300 ticks at a nominal 10ms that is ~13% slow — a "100Hz" loop running at about 88Hz. div/2 truncation compounded it (rate: 60 gave 16ms, i.e. 62.5Hz), and rate above 1000 produced a delay of 0 and a scheduler-saturating tight loop.

PIDControl.step/3 was then called with the library default t: 1.0, so the integral and derivative terms were computed as though each step were one second apart. The two defects compounded: the loop didn't run at the configured rate, and the maths assumed a rate it wasn't achieving anyway.

Now a BB.Loop — absolute deadlines, missed periods dropped rather than fired as catch-up ticks, and per-tick interval and skip counts on [:bb, :loop, :tick].

2. pid_control dropped for BB.PID.Kernel

The control law is now an Nx.Defn kernel written elementwise over its tensors, so the same code advances one loop or a batch. Gains and state are tensors of matching shape — {} for one loop, {n} for n — with no reshaping or per-loop branching. BB.PID.Controller is the {} case.

Written scalar-shaped a defn would be dispatch cost with no payoff; batch-shaped, the vectorisation and composition bb#147 is after are available as soon as something wants them. A test asserts a 2-loop batch matches the same loops stepped individually to 1e-9.

Owning the algorithm fixes two defects pid_control had:

Derivative on measurement, not error. With e = sp - pv, differentiating the error puts a spike of kd · Δsp/dt through the output on any setpoint step — derivative kick — which pid_control could only blunt with zero_d_on_set_point_change. Differentiating pv and negating responds identically to disturbances while being wholly insensitive to setpoint changes.

Back-calculation anti-windup. The saturation error is folded back into the integrator, holding p + i + d == output exactly while clamped. pid_control clamped the integrator to the output range, which bounds the wrong quantity: with a large kp the proportional term alone fills the range, leaving the integrator free to wind to a limit it must then unwind before the output responds at all.

handle_options/2 now retunes via put_gains/2, replacing only the named gains. Rebuilding the struct previously discarded the integrator, stepping the output by whatever it had accumulated.

Precision

Everything the kernel builds is :f64, and numbers and lists passed to step/4 are converted to :f64 too. That has to happen at the boundary: defn converts a plain float argument at the Nx default of :f32 on entry, and casting inside the defn preserves the rounding rather than undoing it. Hence the deftransform, which also keeps step/4 callable from within another defn. A tensor the caller built at :f32 is upcast but keeps its rounding — documented and tested.

Breaking changes

	Before	After
ki / kd	per step, against a nominal 1s timestep	per second of real elapsed time
Derivative	on error — kicks on setpoint steps	on measurement — no kick
Anti-windup	integrator clamped to output range	back-calculation
Retune	integrator discarded	integrator preserved

At the default rate: 100 the integral term accumulates 100× more slowly and the derivative is 100× larger for the same gains. Option names and meanings are unchanged (kp, ki, kd, tau, output_min, output_max, rate).

Happy to add a CHANGELOG migration note before release if you'd like one.

Not in this PR

The measurement-staleness guard and the trigger: mode from #43 are still outstanding.

mix check --no-retry green; 52 tests (28 of them new, covering the control law directly).