Deep dive number three. The Numerics tab. How finely to step the machine, how to compute space charge, what the run records, and a built in convergence scanner that measures whether your choices are good enough. Today we exercise all of it, for real.
Seven collapsible sections, only Step density open by default, and each remembers its state. Read the group's subtitle. Simulation settings, used by Run Multi particle and as the baseline for non scanned axes. That is a contract, the toolbar run and the error study campaigns build their space charge configuration from this one panel. Below sit the scan parameters, then the run row, Run All Scans, Run Single Axis, Stop, a progress bar, a status badge, and Apply converged value, and a tabbed output pane, Log, Plot, and Table.
Step density. Step one, integration steps per metre, how finely elements are sliced. Step two, space charge kicks per metre. Defaults, one hundred steps and fifty kicks, range five to five thousand. One caveat outranks everything. These two numbers govern drifts and field maps only. The preset combo swaps profiles in one click. Production, one hundred over fifty. Matching, thirty over fifteen, about three times faster, for optimiser loops.
Watch it work. Matching writes both spinboxes, thirty and fifteen. Production restores the one hundred and the fifty. Edit step one by hand and the preset flips itself to Custom, so the label never disagrees with the loaded values. And when a deck loads, its step config auto selects the preset. One click, and Production is back.
The manual is precise here. Step one drives integration substeps for drift and field map elements. Step two sets the space charge kick cadence inside them. Quads, bends, and solenoids always get exactly two substeps with one mid plane kick, whatever you type. Raising step one refines drifts and field maps. It does not re slice a quadrupole.
Space charge and P I C. Base grid, forty eight cells per axis of the cubic mesh. Grid extent, seven sigma. Both came from an M E B T convergence scan, finer grids are noise dominated, tighter extents clip halo and inflate losses. The P I C backend has five choices. Auto, C P U, G P U, cuda, M P S. Auto takes CUDA when available, else the C P U, and never auto selects M P S, which is single precision, about one part in ten million field error. Mps forces it with a warning, gpu and cuda force hardware or error.
The S C engine pairs production numpy with differentiable PyTorch. Pick torch and three controls grey out, grid mode, P I C backend, D C kernel, because torch ignores them. Grid mode snaps to adaptive, torch has no fixed grid path. It runs double precision on C P U, bunched beams only, D C beams fall back to numpy. Switch back, and your grid mode returns.
The physics choices. Green's function. I G F, the integrated Green function, is the accurate default, point is legacy. Particle to mesh. C I C is first order, fine where R F cavities reset grid noise. T S C, twenty seven cells at three times the work, for long no R F transport where C I C noise accumulates. Grid mode. Fixed builds the mesh once, adaptive rebuilds every kick, two to three times slower, for beams that outgrow the box. And for continuous beams the D C kernel, uniform, Gaussian, or pic two d per slice, all scaling the field with surviving current, so lossy beams are never overdriven.
The manual maps this section to four models. Bunched envelope beams, the uniform ellipsoid kick. Bunched multi particle, the three dimensional Hockney F F T P I C. Continuous envelope, the Sacherer O D E. Continuous multi particle, the two dimensional D C kick. The decision tree is the whole story in seven short lines, and mismatching physics and model is the manual's top source of disagreement with TraceWin.
Field maps. Integrator. K D, kick drift, or D K D, drift kick drift, symplectic, for long or periodic trajectories. Interpolation, linear or cubic. Cubic builds its table at load time, so a change applies on the next lattice load. Sampling is implementation, not physics. Kernel, the fused C plus plus sampler, measured one point eight times faster on multi particle with space charge, two point nine on envelope, bitwise identical to scipy, kept for cross checks.
The envelope solver. Matrix, the default, propagates the sigma matrix and tracks cavities and longitudinal dynamics. Sacherer integrates the K V envelope equations, D C, no acceleration, better under space charge strong enough that the split operator under resolves. And collective effects holds one checkbox, C S R in bends. Let us read what it buys.
The C S R model is a one dimensional steady state wake, the Saldin Schneidmiller Yurkov formulation. Tail radiation catches the head along the chord, and the bend's dispersion turns the energy kick into emittance growth, applied per substep inside every dipole. The caveats. Multi particle only, the envelope solver has no bunch profile. Steady state only, entrance and exit transients are not modelled. And beyond the checkbox, just two code knobs, bin count and model selector.
Diagnostics and recording. Record per sub step keeps the inside of every element, about fifty times more rows. Record particle density histograms the live beam along the machine, a megabyte per axis per thousand steps, feeding the Results heatmap. Snapshot every N dumps the full six dimensional cloud periodically, and zero means only flagged markers fire. Snapshot at names specific elements, or Add selected appends the current selection. Bins and extent size that grid. Now arm them.
Substeps on. Density on. And into Snapshot at, the name of a mid lattice quadrupole, exactly as the deck names it. Zoom out and run, twenty thousand macroparticles at five milliamps, Run Multi particle. The status bar confirms completion and the auto saved results file. Every switch was live for that run.
The phase space popup's location dropdown now offers the quadrupole we named, beside the default exit view, and redraws every panel from the six dimensional cloud captured there. Mid machine inspection, and free when unused.
The density recording feeds this heatmap, beam density along the whole line. Two hundred bins default, four hundred for sharp beams at four times the memory. Extent zero auto fits to one point one times the largest excursion. Set it explicitly when two runs must share one colour scale.
Scan controls. Scan N particles applies during scans only, the beam configuration keeps its own count, and five thousand matches the classic dialog. Parallel workers fans points across processes, half the cores capped at eight, seven here, with results identical to serial. The pool covers grid, extent, and particle count, the step axes stay serial, and G P U backends downgrade to C P U in pool workers. Our recordings run serial.
Five axes, and the values line follows. Thirty two to one twenty eight cells for grid. Three to six sigma extent. Fifty to five hundred step one, twenty five to two hundred step two. And ten thousand to three hundred thousand particles for the fifth, G U I only, noise floor axis. The field is free text, integers for count axes, floats otherwise.
The contract. Pick an axis, give a ladder, press a button. Run Single Axis scans one axis. Run All walks grid, extent, step one, step two with default ladders, and note, the baseline stays frozen, recommendations are committed together only at the end, so no winner contaminates later sweeps. Stop halts, Apply writes a winner back.
Scanning for real. Grid, sixteen to forty eight cells, five thousand scan particles, serial. The log is a lab notebook. Three header lines, space charge config, beam, with scan N beside the real twenty thousand, and step config. Then one row per point, sizes, emittances, wall seconds. The Plot draws epsilon x bold and sigma y dashed. Mind the auto zoomed axis, this curve spans under half a percent, a flat line magnified. The Table adds sigma phi in degrees and the wall time price sheet.
The verdict, and the rule. One percent tolerance on ending horizontal emittance. The finest row, forty eight, is the reference, and the smallest value within one percent wins. Here every row agrees, so the cheapest wins, sixteen, highlighted, and the badge reads converged at grid equals sixteen, finest drift zero point three three percent, the gap between the two finest rows, your live error bar. And read it correctly, at five thousand particles this deck simply cannot tell sixteen from forty eight. Statistics limited, the fifth axis's job.
Apply converged value writes the winner into the base settings. Watch the grid spinbox, forty eight becomes sixteen, and the badge appends, applied. Step axes also write into the lattice's step config, the particle axis updates the beam configuration. Receipt kept, and we put the grid straight back to forty eight.
A heavier ladder, to exercise Stop. Rows land, we press Stop, and the badge answers in two stages. Stopping, finishing the current step, the worker bails at the next element boundary, never killed mid integration. Then stopped, with the count completed. The in flight point is discarded, but finished rows survive, and the log records the stop. No recommendation and nothing to apply from a truncated scan. Half a scan is not evidence.
The full protocol, Run All Scans. The axis combo walks itself through the four axes while the log writes one header, config, beam, five thousand scan particles against twenty thousand real, steps, and the sweep plan. Rows stream with the wall seconds meter running. Note what it does not do. The baseline stays frozen through all four sweeps, each recommendation is stashed, not applied, so the extent sweep still runs on the original forty eight cell baseline. Everything commits at once, at the end.
Done, and the badge is the verdict. Grid one twenty eight, extent six, step one fifty, step two twenty five, applied. The log closes with the classic recommendation block, and the base settings hold the committed values. Now grade it. The step sweeps are flat to a tenth of a percent, solid winners. The grid sweep never flattened, emittance climbs steadily across the ladder, so the rule fell back to the finest row. That is grid heating on a five thousand particle scan, not convergence. The extent column collapses by a factor of fifteen, tight extents clip halo. Trust a recommendation exactly as far as it flattened.
Back on the forty eight cell, seven sigma baseline, the fifth axis, statistics. We type a ladder, five hundred to thirty thousand, and watch the plot. Five hundred particles reads two point four eight, nine percent below the thirty thousand reference, under sampled tails read low. Two thousand overshoots by three percent. Eight thousand lands within one percent, and the badge calls it, converged at n particles equals eight thousand, finest drift zero point seven five percent, the one over root N floor sinking below tolerance. The wall clock barely notices here, but on production lattices this is the accuracy versus cost axis.
One page to bookmark, the manual's Numerics tab chapter, with two behaviours no widget shows. Tooltips, every field carries the physics and the reference, the integrated Green function tooltip cites Qiang two thousand six. And dirty tracking, every fixed setting serialises into the project file and marks it dirty on change, while scan widgets stay session only and section states persist per user.
That is the Numerics tab at full depth. Scan, read the flattening and the drift, apply, re run at production statistics. When a result surprises you, double the steps, double the grid, and if nothing changes, believe the physics. Next, the Matching tab and its seven algorithms. See you there.