Deep dive number seven. The Error Study tab. Until now every machine we tracked was perfect. Real magnets are misaligned by fractions of a millimetre, real fields are off by fractions of a percent, and the real question is not what does my design do, but what does the ensemble of imperfect machines that will actually get built do. That is a tolerance study, and this tab runs them.
The idea in one breath. You describe errors as statistical distributions. Quadrupole offsets, gaussian, zero point two millimetres R M S. The tab builds many copies of your machine, each with its own random draw of every error, tracks the same beam through all of them, and aggregates the results into bands. The copies are called seeds, and the four zones on this screen take you from declaration to results.
The tab is a map of the workflow. On top, two form sub tabs that describe errors, element side and beam side. Below them, the registered errors list, the reviewable budget. Then the orbit correction group, which decides how each seed is operated. At the bottom, the run group. Declare, review, correct, run. No keyboard shortcuts here, everything is form driven.
Registering an element error takes one form. Target type. A name pattern, an fnmatch wildcard against element names, auto filled to the whole family. The parameter, whose menu follows the type. The distribution. And the six decimal size box, sigma for a gaussian, half width for a uniform, in the parameter's own units. Cutoff truncates gaussian draws at three sigma by default. We register zero point two millimetre offsets in d x, add, then d y, add.
Switch the target type and two things rewrite at once, the parameter menu and the pattern hint, which follows the family, QUAD, GAP, BEND, or SOL, each with a wildcard. Quadrupoles offer offsets, tilt, a fractional gradient error, and g three and g four higher pole content. Cavities offer relative voltage, phase offset in degrees, and frequency offset. Bends and solenoids share a single fractional field error, and offsets and tilt are common to every type.
Patterns narrow as far as you like. Type one exact name, QUAD zero zero three, pick the fractional gradient error, switch to uniform, and the size box now reads as a half width, zero point zero five. Add, and a third row lands, targeting one element. Uniform draws ignore the cutoff. Gaussian truncation is by redrawing until the value falls inside it, the TraceWin convention, so no probability piles up at the limits.
The second sub tab holds beam errors, the machine's input side. Thirteen parameters in four groups. Six centroid channels, three fractional emittance growths, three mismatch channels, and shot to shot current variation. Units follow the channel, millimetres, milliradians, degrees, M e V, or fractions.
Two get registered for real. Centroid x, gaussian, zero point one millimetres, add. Then mismatch x, uniform, zero point zero five, add again. Each lands as a BEAM row. Per seed, the study perturbs a copy of the beam configuration before the beam is generated.
Every registered error is one row. A source tag, element or beam, then pattern, parameter, distribution, and size. Element rows list first, beam rows after. This list, plus any directives the deck itself carries, is the tolerance budget under test.
List hygiene is one button. Select the uniform gradient row, delete selected, and exactly that row disappears. The beam rows go the same way. We prune back to the two quadrupole offsets, one clean question for the headline ensemble.
Empty the list entirely and Run protects you. The warning fires only when there is truly nothing to randomise, and it looks in three places. The element list, the beam list, and ERROR directives carried by the parsed lattice itself. So an empty list does not mean an empty study, the deck can bring its own budget. Run also refuses without a lattice or a beam.
Now the subtle part. A real machine with misaligned quadrupoles is never operated raw, operators correct the orbit first. Tick apply orbit correction and the greyed controls wake, and every seed gets its own correction pass before tracking. Method auto picks one to one steering when steerer and monitor counts match, S V D otherwise, or you can force either. n iter caps the passes. Tolerance is the target R M S orbit. B P M noise adds measurement error to the readings. The targets box steers onto recorded set points instead of zero, and readings can come from envelope centroids instead of tracked particles. Without this box, a tolerance study of a correctable machine is unfairly pessimistic.
The same corrector exists outside studies. On the lattice tab, correct orbit runs a one shot pass driven by the deck's adjust steerer cards, and applies the fitted kicks through the undo bus as a single step. A fitted lattice reroutes plain save to save as, so the source deck is never silently overwritten. Next to it, B P M targets loads runtime set points, and a project setting can fire correction automatically when a project with steerer cards loads.
Run study. n seeds accepts two to ten thousand and defaults to fifty. Twenty here, for speed. The status line opens with an important statement, whether space charge is on or off, taken from the numerics tab exactly as a toolbar run would take it. Zero current, so off. Then the progress counts seeds, one full multi particle tracking pass each. An error study has no envelope mode. Every seed is the real thing.
When the last seed lands, the app wide status bar, magnified here, answers the obvious question. Error study finished, twenty seeds, open the results tab. Off we go.
The ensemble view. Sigma x and sigma y along the machine, a solid mean over all twenty seeds with dashed plus and minus one sigma bands. Narrow bands mean a robust machine, wide bands mean sensitivity. Below, the histogram of final transmission, and the summary line condenses it, twenty seeds, mean one hundred percent, minimum one hundred, sigma zero. Every imperfect machine transmits everything. With this budget, this matched line loses nothing.
The same view earning its keep. A six cell F O D O line at five M e V with twenty millimetre apertures, and the same study twice, twelve seeds each. Left, a zero point two millimetre alignment budget, every seed at one hundred percent. Right, the budget relaxed to one point five millimetres. The mean drops to about fifty eight percent, seven seeds transmit everything, five lose essentially the whole beam. Two lumps and nothing between is a brittle machine, and the mean alone would never tell you.
When a histogram looks like that, interrogate the results object. transmission stats condenses the ensemble. mean, standard deviation, and percentile return any recorded quantity across seeds, and percentile one hundred is the worst case at every location. The per seed finals name the guilty seed, index four, zero percent. Draws are deterministic per seed, so that machine can be regenerated and diffed against the nominal one. And with correction enabled, corrected kicks and correction history expose each seed's steerer solution.
Two spinboxes govern the statistics. n seeds, fifty by default, one hundred to two hundred for production. And the base seed, which offsets every per seed random draw. Finished a study and want more statistics? Set the base seed to one thousand and run again. The new batch is statistically independent, and the two ensembles pool cleanly.
Stop deserves a live demonstration. Two hundred seeds requested, on a fifty thousand particle beam so there is time to think. Run, the counter climbs, and mid flight we press stop. The status flashes stopping, finishing the current seed, because the stop is cooperative. Then the verdict, stopped, with exactly how many of the two hundred were kept. Only whole seeds enter the ensemble, a truncated recording would corrupt every mean and band.
And the partial ensemble is a first class citizen. The view plots the kept seeds like any finished study, and the statistics are valid because every seed in there is complete. Partial statistics are still honest statistics.
One more source of errors exists, the lattice file itself. ERROR directives in a TraceWin deck declare the same errors inline, and HELIX reads them on import. This is the shipped combined realistic budget, verbatim. The cutoff card sets three sigma truncation for the whole file, applied at end of parse, last card wins. Each card covers the next N elements of its family, six quads here, two cavities, one bend. The r slot picks the distribution, two is gaussian, one is uniform. Alignments read in millimetres, rotations in degrees, field errors in percent, and the beam card's final slot is percent current jitter, not milliamps. The comment in this deck says one milliamp, but the manual and the parser both read that slot as percent.
Deck directives run with an empty list. This is the quad alignment example project, ten M e V protons at ten milliamps, nothing registered in the form. Run proceeds anyway, because the directives live on the parsed lattice and merge in at run time. And read the status line, space charge ON, with exactly the P I C configuration the numerics tab holds. Ten seeds, each a full multi particle pass with space charge. Five such ready made projects ship in the examples folder.
Every directive is documented on one manual page. The quick map names the families, then the distribution codes, with honest rows. TraceWin's constant mode maps to a gaussian with a parse warning. ERROR SET RATIO is parsed but never consumed, so sweep amplitudes by scaling sigmas. And the variant table is equally plain. Dynamic and coupled cards are absorbed as static uncoupled errors, and the stat file and per cell R F Q cards are deferred no op markers.
The manual is just as direct about what is not modelled. In the alignment table, d z draws are stored on the element but no longitudinal shift is performed, and pitch and yaw are reserved slots, not yet honoured. The tracker honours d x, d y, and tilt.
Every draw is static per seed, held constant through the simulation, so time varying jitter is not modelled. Seeds run serially, the n workers argument is accepted and ignored, parallelise across studies with different base seeds instead. And since the draw convention change of twenty twenty six, results are deliberately not bit identical to older runs. The new statistics are the correct ones.
Planning wall time is a table lookup. A small lattice without space charge costs seconds for fifty seeds. A full machine ensemble with the P I C solver on belongs overnight. The working rule sits underneath. Iterate the budget without space charge, verify the final budget once with the solver on.
That is the Error Study tab in full. Declare imperfections through the form or ship them in the deck, correct like an operator, run with real space charge, stop honestly, read bands and histograms, and interrogate the results object when a second lump appears. Next, the Failure Study tab, where instead of many small errors we ask about single large ones. What happens when a cavity or a magnet simply dies. See you there.