Deep dive number four, the Matching tab. Matching means letting the computer turn the knobs, and three tools and a designer live here. The periodic matching dialog, a phase advance analyser, the auto adjust matcher with seven algorithms, and a Pareto designer.
The concept first. Knobs and targets live in the lattice file itself. An ADJUST card frees a parameter. Family QUAD, index two, the gradient, bounds minus thirty to plus thirty tesla per metre. Two cards, both link group one, so they move in lockstep, a ganged pair. The target, SET SIZE, weight one, sigma x four millimetres at the exit, y and longitudinal free.
The deck is the whole problem statement, and the manual documents every card. SET TWISS targets exit alpha and beta. Its six k flags are the only selection mechanism, all zeros means silently inert, and the z flags follow HELIX's alpha z sign and degrees per M e V beta z conventions. SET SIZE has a sign rule, positive fourth field, sigma phi in degrees, negative, sigma z in millimetres. MAX and MIN variants bound the worst sigma over a look back window. SET BEAM PHASE ADV is the one card whose file position matters, its span runs forward. The MIN family are one sided, growth costs, shrinkage is free. Nine SET cards are parsed but inert stubs. One generic ADJUST card with a parameter index covers eight element classes, unsupported pairs fail loudly, and the beam variants free input Twiss, centroid, emittance and current.
The tab's top row echoes the Beam tab's input Twiss as K P I cards, refreshed live on every edit. Every matching tool starts from here.
Open Matching Dialog is the classic periodic matcher. Four zones, mode, zero current Twiss, space charge matched Twiss, and a log. Whole lattice mode for genuinely periodic machines, FODO cell for transfer lines. And never whole lattice on an accelerating section, the eigenvalues leave the unit circle.
The four period FODO, three M e V, zero current. Compute Periodic Twiss. Alpha x minus one point four three, beta two point two nine metres, the y plane mirrored, forty point two degrees of phase advance, ten per period. Dispersion rows, exact zeros, nothing bends. Episode one's matched beam came from here. Apply to Beam Setup is armed.
Cell mode, the transfer line question. The cell selector wakes, filled by quad to quad detection, cell zero, elements three to seven. Compute, and the log records the matched input, ten point one degrees per cell. The rule, PIP two class lattices use cell mode, and dispersive arcs use the space charge path, which matches dispersion in an eight state formulation.
Fifteen milliamps now, iteration cap two hundred. Compute S C matched Twiss iterates the envelope solver from the zero current seed, damping as it goes, oscillation suspected, damping reduced. Converged in sixty three iterations. Beta grows from two point two nine to about two point five one metres, ten per cent, space charge defocuses. A verification pass re checks the fixed point.
Apply pushes it into the Beam tab, and the closing dialog makes the tab reconcile. Status, closed, beam config updated from dialog, project flagged dirty. The K P I cards read minus one point five three and two point five one. Unchanged gets reported honestly too.
The Auto Adjust panel drives those cards. Row one, solver setup. Space charge in the cost or not. Max iterations, evaluations for least squares, generations for populations. Cost solver, envelope, fast and linear, or M P, full particle in cell, fifty to one hundred times slower, M P particles greyed until chosen. Allow inert constraints, an escape hatch. Row two, the C M A E S and Bayesian knobs, then Match, Stop, Apply, Save. Algorithm and cap are session settings, not saved in the project.
The Phase Advance panel, the stability instrument. Period candidates are auto detected, here a type sequence repeat tagged auto. The L E D is green, half trace below one, stable. Sigma nought, ten point zero five degrees per plane. Sigma model, the depressed channel tune, identical at zero current, eta one point zero zero zero. Sigma beam, ten point zero six. The status line is strict to a fault, flagging a mismatch of nought point nought per cent.
Fifteen milliamps, space charge matched beam. Sigma model drops to nine point six two, eta nought point nine five seven, the tune depression. The beam row, nine point one five, ratio nought point nine one. And the status explains, mismatch nought point four per cent, eta spreading nought point seven to nought point nine eight across cells, trust the model number. Glance here before any match.
The Algorithm dropdown, seven entries in shipped order. Least squares, differential evolution, dual annealing, gradient, C M A E S, sequential scan, Bayesian optimisation. Sigma nought and popsize wake for C M A E S. No L S polish serves C M A E S and Bayesian optimisation, the prior is Bayesian only. Cost solver M P un greys M P particles.
Run one. Least squares, envelope cost, Match. The variables table fills with the linked pair's shared column, quad one's gradient, minus five to minus three point four three, written to both quadrupoles. The constraints table, SET SIZE, R M S residual zero. And the status, O K, eleven iterations, cost from eight point five times ten to the minus two to zero.
Two buttons arm after a match. Apply installs the matched values in the live lattice and beam. Save matched dot dat exports a TraceWin file. Until Apply, nothing is touched, experimenting is free.
Apply. Applied, lattice and beam updated, save to persist. Both flagged dirty, plain save reroutes to save as, the title bar keeps your file. Then Save matched dot dat, and the status names the written path.
The written deck. ADJUST and SET SIZE round trip untouched, and both quadrupoles carry the matched gradient, minus three point four three, where plus and minus five stood. Machine and problem, one portable file.
One honest rule. A match is valid only for the lattice it was computed on. Edit the lattice, the tables clear, Apply and Save grey out. Lattice changed since last match, click Match again.
Fresh deck, algorithm gradient, exact Jacobians from differentiable tracking. Same answer, minus three point four three, in six iterations against eleven. Its scope is narrow and fail loud, linear lattices only, no R F, field maps, centroid or longitudinal targets, it points you back to least squares. Both are local, they find the nearest valley.
Global now. Differential evolution breeds a population and mixes the best. The price, seven hundred and sixty eight evaluations against eleven, same answer. Global searches explore a box, so every ADJUST needs finite bounds.
Dual annealing, simulated annealing with restarts, sometimes accepts a worse point to escape a trap. Fifty two evaluations here. Use these two when the nearest valley may not be the best.
Enforced for real. This deck's ADJUST leaves min and max at zero, the unbounded convention. Differential evolution stops with a value error naming quad one's gradient, and the fix, add bounds or use least squares. The same check guards dual annealing, C M A E S, sequential scan and Bayesian optimisation.
C M A E S, the recommended pick for five to thirty coupled knobs, learns which directions improve the beam and walks diagonally. Sigma nought, step size as a fraction of the bound box, default nought point two. Popsize zero renders auto, four plus three log N. A least squares polish finishes it unless unticked, and Max iter counts generations.
A real six knob match on the shipped demo, five milliamps, space charge on. Every match opens this window. Cost per evaluation on a log axis, the noisy cloud is the population, the dashed line the best so far, the one you keep. The title counts generations and evaluations, ticking on through the least squares polish, the flat tail. Two hundred and twenty two evaluations, best just above two times ten to the minus three, an order of magnitude down. Below, the physics, emittances per plane, and the live row of the evaluation being scored. Closing this window does not stop the match.
The Stop button does. Same deck, M P cost, three hundred macroparticles, big budget. Stop, and the cancel lands at the next evaluation boundary. The status comes back, cancelled, best of run, with the iteration count and cost from baseline to best. Tables fill, Apply and Save arm. An interrupted match is never wasted, on any algorithm.
Sequential scan tunes like an operator, in beam order, bracketing each parameter, reversing on emittance growth. It asks questions first, Match opens a setup dialog.
The scan demo, six knobs. Every ADJUSTed element with category, attributes, bounds. Toolbar filters, all, none, solenoids only, cavities only, and solenoids only leaves the two focusing knobs. Passes, steps per parameter, step size as a bound fraction. Reversal, flip when both transverse and longitudinal emittance grew, or on any growth, measured against the input beam or the unmatched seed's exit. The hard loss rule, tick it, the threshold wakes, any step losing beam is rolled back, and it needs the M P solver, the envelope tracks no losses. The deck's active constraints are listed too.
Start, and the scan row names the element and attribute under the wrench, pass by pass, step by step, direction in brackets, emittances reacting per bracket. You learn which knob did what. Best settings kept.
Honest physics. Cost solver M P, three hundred macroparticles, least squares, the Numerics tab's settings, no hidden defaults. Feel the cadence, a few dozen evaluations in twenty seconds, where envelope just did seven hundred and sixty eight in two and a half. We stop at best of run. Envelope for the shape, M P for the final polish, particles against wall time.
This deck carries a transmission floor, but envelope tracks no particle loss, so the matcher refuses to pretend. Match would silently ignore active constraints, MIN TRANSMISSION, inert. Three ways out, fix the deck, switch cost solver, or allow inert constraints.
Allow inert constraints, ticked, the match proceeds. In the constraints table, real residuals on the emittance rows, the energy floor at zero, and the transmission row exactly zero, the tell, it contributed nothing by declaration. The better fix is still M P.
Bayesian optimisation builds a Gaussian process of the cost and spends each evaluation where expected improvement is highest, so it needs few, made for M P cost matches where evaluations cost minutes. No L S polish it shares with C M A E S. B O physics prior is its own, and only acts with cost solver M P, scouting on the cheap envelope first. For cheap matches, least squares wins on wall clock.
Proof, same six knobs, envelope cost. Sixty five evaluations against two hundred and twenty two for C M A E S, essentially the same cost. After the space filling samples every point is model chosen, and a least squares polish finishes unless unticked.
The multi objective button opens the Pareto designer, competing goals over the same knobs. Ten objectives, all minimised, emittance growths, beam loss, negative exit energy, exit and peak sizes. Tick two or more, here the default pair, longitudinal growth against exit energy. N S G A two, the genetic default, q N E H V I the Bayesian one. Population sixteen, eight generations, run. One hundred and twenty eight evaluations, ten Pareto designs. Grey dominated, orange front, the star is the knee. And honestly, the growth axis spans ten to the minus ten, energy comes nearly free here. Each row is a full design, objectives plus knobs. Take a row or the knee, Apply writes it to the lattice, project dirty.
Everything has a headless twin. The matcher module writes the matched deck next to the input, report prints the same tables. The mo subcommand lists the same ten objectives. And only the command line runs C M A E S in parallel, the G U I is sequential.
Any results popup gains a live match preview tick box. On, the curve becomes the matcher's current iterate, refreshed about once a second, throttled, read only. The fastest way to catch a cost win that is physically ugly along the line. At the end it snaps back to the committed results.
The rule of thumb. Close to the answer, least squares. Five to thirty coupled knobs, C M A E S. Treacherous landscape, differential evolution or dual annealing. Expensive M P cost, Bayesian optimisation. Operator style, sequential scan with the loss rule. Competing goals, the Pareto designer. And glance at the phase advance panel before you tune. Next, the Results tab, tile by tile.