FERROMOTION · RUST → WASM

The Reference That Shares Its Machinery

You want to split the contact-gradient error into its causes. Your reference solver shares the same integrator. What does the comparison measure?

Take a measurement you already trust and find out what it actually measures. You will split the contact-gradient error into the part the integrator causes and the part the contact model causes, discover they move in opposite directions, and learn the two ways a reference lies to you: by sharing machinery with the thing it scores, and by having a noise floor above the number you wanted to quote. Pass = you name the integrator share and the model share at 1e6, and say why an answer that moves when you change the probe is not an answer.

01Challenge

Last lesson you watched a gradient diverge and you were told, correctly, that the fixed-step integrator was to blame. How would you know that? Both candidate culprits - the contact model and the integrator - are inside the same number. Splitting them needs a reference, and the obvious reference is the one you get by running the same simulator more carefully, which is exactly the reference that cannot tell them apart. This lesson is about getting a reference from somewhere else entirely, and about the two failure modes that make a careful measurement worthless.

Predict firstYou want to split the contact-gradient error into its causes. Your reference solver shares the same integrator. What does the comparison measure?

02Model

Write the number you measured as a difference between two things: what the simulator's gradient is, and what the true gradient is. Now insert a third thing in the middle - the gradient of the contact model itself, integrated perfectly - and the single error becomes a sum of two. The first gap is the integrator's fault. The second is the contact model's fault. They are separately measurable, and once you measure them you find they move in opposite directions as you stiffen the contact: the integrator's share grows and the model's share shrinks. That is the whole answer, and it is invisible until you split the number. But the middle term needs a reference, and here is the trap. If you build it by running the same integrator with a tighter tolerance, then scoring the tolerance route against it proves nothing: they agree because they are the same machinery. So we score against something with no integrator in it at all - the saltation matrix, closed form, no timestep, no tolerance, no finite difference. When the tolerance route matches THAT, the agreement means something. Be precise about how much: three digits on the scaled statistic the test uses, and only about one and a half on the worst entry, which is what sets the test's pass margin. And be precise about which entry is genuinely independent - dv/dv0 is 1 by algebra whatever the restitution, while the others are calibrated by a restitution the same rollout measured. The second trap is quieter. Every finite-difference reference has a probe size, and a reference is only a measurement if the answer stops moving when the probe changes. Ours did not, at first. A uniform-step finite difference on this system reports the same derivative as 5.8, then minus 78, then 694, then minus 143 as the probe shrinks by decades. It is not measuring the derivative. It is measuring the probe. And a central difference carries a term that at high stiffness is bigger than the model error you were trying to read, so we extrapolate it away and then report what uncertainty is left - and refuse to quote any number that falls below it. Three of the seven stiffnesses in our own sweep are marked unquotable for exactly that reason.

03Guided practice

Step A (worked, fully shown): park the slider at 1e4 with the tolerance route on, and read the two shares off the readout: integrator about 2.0e1, contact model about 1.1e-1, a ratio near 190. Write both down. Step B (worked): move to 1e5. The integrator share rises to about 6.2e1; the model share falls to about 3.4e-2. Ratio about 1900. Note that neither number stayed put and they went opposite ways. Step C (you do it): move to 1e6 and predict both before you read them. If you predicted the integrator share up and the model share down, you have the mechanism. Step D (you do it): now the discipline question. The model share at 1e6 is about 9.4e-3. Our own sweep refuses to quote the model share at 1e7 and above. Given that the reference's uncertainty there is about 5e-3, say why - and say what you would have concluded if you had quoted it anyway.

04Feedback

PASS WHEN PASS when you can give the integrator share and the model share at 1e6 from the live readout, state which way each moves as the contact stiffens, and explain in one sentence why a finite-difference answer that changes with the probe size is not a measurement.

If your run fails, check:

You read the two shares at one stiffness and stopped. One point cannot show you a direction. Take at least three and watch the ratio: it goes roughly 190, then 1900, then 18000.
You noticed the model share is tiny and concluded the contact model is irrelevant. Careful - that is true at 1e6 and it is the opposite of true at 1e3, where the model share is the larger of the two. The claim has a range of validity and stating it is part of the result.
You are treating the tolerance route as ground truth. It is not: it is one route among three, and it earns its status only because it matches a closed-form answer that contains no integrator. If you scored it against a tighter run of itself you would learn nothing.
You quoted a model share below the reference floor. That number is the floor, not the physics. In our own sweep the model share reads 5.1e-3, 5.5e-3, 4.2e-3 at 1e7, 1e8, 1e9 - it looks like it has levelled off, and what it has actually done is hit the measurement's own noise.
You are asking why the probe size matters at all if the maths says the derivative is a limit. Because you are not taking a limit, you are subtracting two nearly-equal numbers and dividing by something small. On this system that amplifies the integrator's round-off enough to swing the answer from 5.8 to minus 143. The fix is not a smaller probe.

05Retrieve & space

The split (typed): the contact-gradient error at stiffness 1e6 divides into an integrator share of about ____ and a contact-model share of about ____ -> 1.6e2 and 9.4e-3, a ratio near 1.8e4.
Opposite directions (short answer): as contact stiffness rises, which share grows and which shrinks? -> The integrator's share grows; the contact model's share shrinks, as roughly 1/sqrt(k) over the well-resolved decades. A four-point fit reports -0.93, but that figure is set by one out-of-regime point at k = 1e3 whose model error is 280% of the Jacobian it is measured against. This is why blaming the model gets the direction of the fix exactly backwards.
The circular reference (multiple choice): why can a tighter run of the same adaptive integrator not serve as the reference for the adaptive route? -> Because agreement between two runs of the same machinery is not evidence about that machinery. The reference has to come from somewhere with no integrator in it - here, the closed-form saltation matrix.
The probe test (short answer): what single check tells you a finite-difference Jacobian is measuring the probe rather than the derivative? -> Change the probe size and see whether the answer moves. On this system a uniform-step difference reads 5.8, -78, 694, -143 across four decades of probe; the adaptive one does not move.
The floor rule (short answer): you measure a model error of 4.2e-3 against a reference whose own uncertainty is 4.1e-3. What do you report? -> That the measurement is at its floor and the value is not quotable. Reporting 4.2e-3 would be reporting your own noise as a physical result.

06Mastery & project

You can decompose an error into the shares contributed by each candidate cause, you ask how much machinery a reference shares with what it scores, and can name which of its entries are genuinely independent and which are only consistent, you test every finite-difference answer against a change of probe, and you report a noise floor alongside any small number - and refuse to quote below it. You also accept the uncomfortable corollary: a measurement can be completely correct while the explanation attached to it is completely wrong, and only a reference from outside can tell you which you have.

Not a capstone lesson. It is the method lesson for the whole course: every later claim you make about a simulator, a controller, or a policy will be a difference between two numbers, and this is how you find out which of them was responsible.

GO FURTHER · THE LIVE PLAYGROUND

The decomposition, with its own noise floor reported ↗ · Four routes on one system, three of which are integrated and one of which is not. Marks every row that falls below the reference floor and excludes it from the fit.
The tolerance-driven integrator and the two traps it avoids ↗ · Dormand-Prince 5(4) with a step controller, Richardson extrapolation to kill the probe term, and tests pinning both that the adaptive answer is probe-stable and that the uniform one is not.
The claim this method retracted ↗ · The original module comment, with the correction written directly beneath it rather than quietly edited out. The measurement stood; the explanation did not.

← The Gradient That Lies What a Certificate Cannot Claim →

FERROMOTION · RUST → WASM

The Reference That Shares Its Machinery

The same live lab as the previous lesson, used differently. Turn on the tolerance route and work with the bottom line of the readout: the error split into an integrator share and a contact-model share, both computed from ferromotion-core at the stiffness on the slider. The step counts are there too, because 'more accurate' means nothing without 'for what cost'.

You read

the readout: what the Rust crate computes, recomputed as you change things

You change

the bench controls, and with them the assumption the measurement rests on

Fixed

the ferromotion crate doing the computing, and the check that decides pass