Skip to content
PreciSim
physics

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.

Last updated: Sep 22, 2026
Was this page helpful?