Axes and errors
Three position quantities, pitch error, repeatability, read noise — and why they must not be equal.
Three position quantities, all of them necessary
This is the single most important design decision in the virtual machine:
| Quantity | Equals | Who sees it |
|---|---|---|
Commanded CommandedMm |
where you told it to go; interpolated linearly in time while moving | engine internal |
Reported ReportedMm |
commanded + read noise | this is what the HMI and the calibration algorithms see |
True TrueMm |
commanded + pitch error + repeatability | engine only; the world geometry uses it |
If all three were equal, calibration would fit an identity transform and measure nothing. Home-made simulators usually die here: the axis responds "perfectly", so pixel size always comes out exactly nominal, the student learns nothing, and the regression tests are green forever.
ReportedMm = cmd + N(0, sigma_read) sigma_read from the machine file
TrueMm = cmd + A*sin(2*pi*cmd / P) + N(0, sigma_repeat) A, P: pitch error amplitude and period
Pitch error
A systematic error along the travel, modelled as a sine:
{ "name": "X", "pitchErrorAmpMm": 0.0008, "pitchErrorPeriodMm": 50 }X swings ±0.8 µm with a 50 mm period. On real hardware the curve is measured with a laser interferometer and is less regular, but the nature is the same: it is a function of position, not a random quantity — which is why a compensation table can remove it and cannot remove random error.
Worth verifying by hand once: return to the same position and the error repeats; move elsewhere and it changes.
Repeatability and read noise
Both are zero-mean random, but they are added in different places, with entirely different consequences:
- Repeatability is added to the true position — the stage really did not stop in the same place;
- Read noise is added to the reported position — the stage is where it should be, but the controller's number jitters.
On demo-xy-galvo: X/Y repeatability 0.2 µm, read noise 0.5 µm.
Read noise is larger than repeatability here, which is common on real machines and is exactly why averaging several samples during calibration helps.
The stage is not a plane
It has tilt and flatness ripple:
"stage": { "tiltA": 1.2e-5, "tiltB": -0.8e-5, "rippleAmpUm": 1.5, "ripplePeriodMm": 60 }Tilt is a small slope in each direction; ripple is a 60 mm period, 1.5 µm amplitude wave. Consequence: move to another corner and defocus changes even though Z did not — which is the physical origin of the question chain (7) exists to answer, "where should focus Z be measured?"
Limits, homing, e-stop
| Behaviour | Model |
|---|---|
| Soft limit | out of travel: the command is rejected with OutOfLimit, no motion |
| Not homed | absolute move before homing: rejected with NotHomed |
| Servo off | rejected with NotServo |
| Homing | runs a real homing sequence, taking real time |
| Timeout | waiting past the timeout raises Timeout (30 s per axis, 60 s for homing by default) |
| E-stop | stops immediately; requires a reset afterwards |
The position after homing defines the origin of the machine frame, exactly as on real hardware, so homing repeatability feeds into every calibration that follows.
What this model does not have
No acceleration profiles (trapezoid or S-curve), no backlash, no squareness error, no servo tuning or mechanical resonance.
Motion is point to point: given a velocity, the position is interpolated linearly in time. That is a deliberate trade-off — this product teaches calibration chains and coordinate conventions, not servo tuning. Adding those terms would make the model harder to explain and contribute nothing to "why did the calibration come out wrong".
If what you need is servo and trajectory simulation, this engine is the wrong tool. Don't force it.