Deep dive number six. The Param Study manager. One run answers one question. A study answers a family of them. What happens as I scan this gradient, that voltage, the beam current, or a solver setting. This tab defines the family, runs it headless with resume and provenance built in, and analyses it live. Six real studies this episode. A line scan, a grid, a failure, a survey, seed repeats, and a hand written spec.
The left half defines the study in three groups. Parameters, strategy, and execution. The right half analyses it, four views named on their tabs. Runs, one D sweep, Map, and Overlay sigma of z. All four update live while a study runs, and sit empty until one loads. The machine is the D T L section, loaded from a file saved on disk. That matters in a moment.
Because a study never runs what is on the screen. It runs the saved file, headless, one subprocess per point. So the tab guards that seam. The lattice here carries an unsaved edit, and Start refuses with this dialog. The study executes the file on disk, and refusing beats silently studying different physics. No lattice at all, or an empty parameter table, are refused the same way. We undo the edit and carry on clean.
Parameters. Pick an element, pick a numeric attribute, press Add. The row pre fills around the live value. Gradient eight, so start six point four, stop nine point six. Twenty percent either side, five points, linear. Selector and label are fixed. Baseline, start, stop, n, and spacing edit in place, and we widen to four through twelve tesla per metre. Spacing accepts log, geometric steps, positive endpoints only. Back to linear. The picker also offers Beam, the input distribution, as a pseudo element. Beam current becomes a row the same way, pre filled minus one to plus one around zero. Remove selected takes it out again.
Everything the tab writes is a plain study dot json, and you can write one by hand. This one runs later in the episode. The selector grammar is one language everywhere. At six dot gradient is element six, one based, attribute gradient. The element name works too. A bare word like current is a beam field. And n x is a numerics knob, one of four structural selectors that live in the spec and the C L I. A parameter can carry an explicit values list instead of start, stop, n. The observables block we meet near the end.
Strategy decides how rows combine. The strategy list, seed repeats, base seed, forty two by default, and Samples, read only by random and latin hypercube. So the counter has something to count, a second quadrupole row is staged in the table above, minus twelve to minus four, five points.
Watch the total runs counter. Grid is the cross product, five times five, twenty five. Zip walks the rows in lockstep, five runs, and unequal lengths are rejected loudly. One at a time gives eleven. Five plus five, plus one all nominal reference run, which is why the baseline column exists. Random ignores n and takes the sample budget, thirty two, seeded so the same spec always draws the same points. Latin hypercube, same budget, spread evenly. And seed repeats multiply everything. Times three is ninety six, seeds forty two, forty three, forty four.
Execution. The name pre fills with a time stamp. We type our own. The folder is the study root, defaulting to runs slash studies under the working directory, browse button beside it. Mode, envelope or multi particle. Workers, one subprocess per run. One means serial, in process, and the range tops out one below your core count. Start, Stop, and Open study share the bottom row.
One row, grid, five gradients, envelope, serial. Start study creates the folder and begins. Start greys out while the worker lives, the bar counts five runs, and the status line reports done and failed. On longer studies it grows a live E T A, coming up soon. Envelope points cost milliseconds, so this is over immediately. Complete, with the summary path in the status line.
On disk, a study is a folder you can archive, share, or resume anywhere. Study dot json is the full specification, including a S H A two five six pin of the input deck. Lattice holds a provenance snapshot. Runs has one folder per run, its results file plus a status dot json recording ok or failed, parameters, and metrics. Results are written to a dot part file and renamed only when complete, so a crash never leaves a half written file looking valid. Summary holds two derived views. Summary dot C S V, and runs manifest dot json, the recorded plan.
Those files have teeth. The deck is pinned by S H A two five six at creation. We edited it afterwards and asked the command line to continue. It refuses with exactly this message, results would mix two different machines. Restore the bytes and the same study answers again. The manifest is the second guard. If the spec no longer expands to the recorded plan, the load refuses just as loudly.
The second quadrupole row goes back in, and the same Start button launches the twenty five run grid, two workers this time. The analysis views refresh after every finished run, and the grid completes in seconds. Every study in this episode goes through this identical path.
The Runs view is a live, sortable table. One row per run. Index, the tag encoding the parameter values, seed, status, the parameters as columns, then transmission, sizes, emittances, energy, elapsed, and an error column, empty on healthy rows. Transmission just reads none, envelope mode counts no particles. Click the sigma x header and the family sorts by final beam size, ascending, then descending. Failed rows go dark red, in a moment, for real.
Every run wrote a complete results file, so the table is a door. Double click a healthy row and the app opens that run in the Results tab, tiles and all. A study is a browsable library of full runs.
Failure handling, on purpose. We scanned beam energy from minus one to plus three M e V through the beam pseudo element. Two points are unphysical. The failed rows go dark red, the error column carries the exception, value error, energy must be greater than zero M e V, and the status still reads complete. The healthy three ran, the summary was written. Failed runs are rows, not crashes.
The one D sweep, on the grid. X is a parameter, Y is any of seventeen built in quantities plus your observables. Transmission is the default, and in envelope mode it is honestly empty. Sigma x shows the response, five gradients, each point the mean over the five second quad settings, bars showing that spread. Normalised emittance. Final energy, flat, these knobs never touch the R F. Elapsed, the cost per point. And log x, log y, one checkbox each.
Group by unfolds the mean. Grouped by the second quadrupole, twenty five runs become five coloured series, and the legend names each value. Strongest first gradient, weakest second, smallest final size, about ten point six millimetres. The opposite corner, thirteen point two. In log y, the error bars step aside where they would lie.
Two parameters against a quantity is the Map view. On a full grid it renders a true heatmap, one cell per run, colour bar labelled with the quantity. Final horizontal size, ten point six to thirteen point two millimetres, darkest where the gradients balance best. Repeats collapse by mean per cell. A missing cell, and it falls back to a scatter rather than interpolate a lie.
Overlay reads each selected run's results file and draws full curves along the machine. The list multi selects, three come pre selected, we take six, and Draw redraws. The legend is the run tag, and the curves run the full length of the machine. Fourteen quantities are offered, each run contributes what its file actually holds. Sigma x. Beta x, the Twiss function. Longitudinal emittance. This is how a family of machines differs along the line, not just at the exit.
The same two gradients, surveyed instead. A latin hypercube study, thirty two samples, run through the same Start button in seconds. No grid, so the Map view draws its honest fallback, colour mapped points, same axes, same scale. Sample broadly, find the interesting corner, then grid it finely.
Multi particle mode, where runs cost real time. Four gradient points, three seed repeats, twelve runs at a quarter million macro particles, two workers. Start. Once the first runs land, the status line grows a live E T A, and finished rows fill in above grey pending ones. Now the killer feature. Stop is graceful. In flight runs finish cleanly, then, stopped. Resume with Start. Completed runs are kept. Press Start again, and the bar comes back pre filled with the runs already done. The engine re expands the plan, skips the finished, and completes the rest. A crash or a power cycle behaves exactly the same. You only lose what was in flight.
Twelve runs, four gradient points. The one D view aggregates the three seeds at each point into mean, plus and minus one standard deviation. The bars are real seed scatter, about a hundredth of a millimetre here, on a beam of eight millimetres, far below the trend. When the bars rival your effect, the study is telling you to raise the particle count, or accept the uncertainty.
The exit is not the only place worth measuring. An observable extracts any envelope quantity at any s position or named element, per run, resolved to a position at creation, so evaluation never needs the lattice again. The command line twin runs our hand written spec. Same engine, same folders, live progress, and an observable called s x mid, sigma x at the fifth quadrupole.
Open the finished folder in the tab, the status line confirms it, and the observable is a first class column. There is s x mid in the Runs table, per run. And it joins the one D quantity menu, sigma x at the mid line against gradient, no results file ever reopened.
The tab also remembers. The study root and the last study are stored per user. This is a brand new copy of the tab, fresh from the constructor, and it has already reopened the study, loaded last study, on its own. Define here, run overnight elsewhere with the C L I, and tomorrow it is open before you ask.
The command line twin has four verbs. Plan, run, resume, summarize. Plan prints the expanded run table and executes nothing. Five runs, every selector, value, and seed. The sanity check before a thousand run commitment.
Run takes a spec or a folder, parallel sets the pool, resume is the same verb again. Retry failed re queues only failed rows. Here it re ran the two unphysical energy points, they failed again, honestly, and the closing line says so. Force wipes and starts over. Summarize rebuilds the C S V from the per run status files. The C S V is a view, the folders are the truth. And the assistant drives this same engine through its run study tool.
Everything here is written down. The G U I chapter covers the tab, defining a study, the study folder, analysing results, and the headless twins. The running chapter covers the C L I, the spec, and the folder layout with its resume semantics. Search reaches both pages from anywhere in the manual.
That is the Param Study manager. Six real studies in one sitting, every folder resumable, every claim inspectable on disk. Next, the Error Study tab, where the question changes from what if I turn this knob, to what happens when every magnet is slightly wrong at once. See you there.