From spreadsheet to verified engine: what we learned porting a legacy design tool
Every legacy design tool contains undocumented judgement. Finding it means running the old tool and the new one side by side until the last discrepancy has a reason.
· 10 min read · Engineering
The corpus is the specification
When you replace a design tool that a works has trusted for twenty years, the tool's documentation is not the specification. The specification is the set of designs it produced and the units that were built from them. So the first thing we built was not a calculation, it was a corpus: every real design we could recover, with its inputs and its outputs, held as the reference the new engine has to reproduce.
Every module is checked against that corpus before it is allowed into the chain. A module that agrees on nine designs in ten and disagrees on the rest is not ninety per cent done. It has found something, and the discrepancy is the interesting part.
Most discrepancies are undocumented judgement
The differences almost never came from the physics. They came from decisions the original author made and never wrote down: a rounding applied to conductor dimensions before an area calculation rather than after, a correction factor that only applied above a certain diameter, a table interpolated linearly in one place and logarithmically in another.
Each of those is invisible in the formula and decisive in the result. The only way to find them is to compare outputs on real inputs and refuse to accept a difference as noise.
Bugs found by disagreement
Some discrepancies turned out to be errors in the original, preserved because nobody had reason to question them. A short-circuit thermal calculation that reported a temperature rise roughly ten times too high is the clearest example we hit: it had been flagging designs as needing adjustment for years, and designers had learned to ignore that particular warning.
Reproducing a legacy tool faithfully and correcting it are in tension. Our rule is that a difference is only accepted when it can be explained in physical terms and written down, and when the corrected result is the one that matches the built unit's test report.
Why traceability is the deliverable
The engine's real output is not a number, it is a number with its provenance: which table it was read from, which factor was applied, which standard's clause governs the limit it is checked against. That is what lets a senior engineer finalise a design they did not compute themselves.
It is also what makes the corpus maintainable. When a material table is updated or a method is corrected, the designs that move are identified immediately, and the ones that should not have moved are the regression.
What we would tell anyone doing the same
Collect the corpus before you write the first module. Automate the comparison from day one, because a manual comparison stops being run in week three. Treat every disagreement as a question rather than a tolerance. And keep the old tool running until the last one is answered.