Numerics tab¶

Configure tracking-step density and space-charge solver settings. Wraps SpaceChargeConfig and tracker-level integrator parameters in a single panel.

Numerics tab

Numerics tab — collapsible numerics sections plus the built-in convergence-scan controls.

Sections¶

The settings panel is grouped into seven collapsible sections; only "Step density" opens by default, and each section's open/closed state is persisted per user across sessions:

Step density — an Integration profile preset combo (Production (100/50) / Matching (30/15) / Custom — editing either spinbox by hand switches to Custom), plus base step1 (integration steps per metre) and step2 (SC kicks per metre). Map to TraceWin's PARTRAN_STEP step1 step2. Below them, Single-push field-free drifts (on by default): a drift is pushed once when nothing sits between its sub-steps, and a loss inside it is located exactly on the particle's straight line; untick it to keep the sub-stepped walk of HELIX ≤ 1.9.1. With it on, a step1 scan at zero current only probes field maps. RFQ solver: Auto (time domain when possible) (default) tracks the RFQ in time whenever the time-domain solver can run the lattice and beam, and otherwise cell by cell, with a log notice that says why; Per cell (two-term model) tracks an RFQ one RFQ_CELL at a time along z; Time domain (3-D vane field) always tracks the whole RFQ in time through the field of its vanes and stops a run it cannot do. RFQ time steps per RF period (default 48) apply whenever the time-domain solver runs — see Time-domain RFQ solver. RFQ statistics: accelerated particles only (on by default) leaves the particles that leave the RFQ unaccelerated out of the plotted sizes, emittances and energy spread, from where they fall behind the bunch. They still count in the transmission. Only the RFQ cells change solver; the rest of the lattice is tracked as before. The choice applies to multiparticle runs from every tab (toolbar run, scans, matching, error, failure and parameter studies); envelope runs and backtracking keep the per-cell model. It is a run setting, not part of the lattice: loading or re-applying a lattice keeps it, and a project sets it (per cell when the project does not say).
Space charge & PIC — Space-charge method: a named method with its label and a one-line summary. Choosing one sets the settings that define it (engine, kernel, grid mode, how often the field is solved) and its default grid; those controls are then locked, the grid controls stay free, and Custom unlocks everything. A project saves the method and every setting. Below it: Green's-function build (exact / symmetric), HELIX_SC_GRID cards (apply / ignore / auto) and Field solved every N kicks (adaptive numpy grid only). Base PIC grid (nx=ny=nz): a single cubic spinbox (one value sets all three axes); grid extent (σ multiplier); PIC backend (auto / cpu / gpu / cuda / mps); CPU threads — All (N) (default) or 1 … N, the threads for the FFT field solve, the field maps and the charge deposition, for every backend; results are identical for any number. Saved for this computer, not in the project, and applied at once (CPU threads); SC engine — numpy (production PIC, default) or torch (the differentiable PyTorch PIC). Pick torch for the autograd-differentiable space-charge kick; it runs FP64 on the CPU, or on an NVIDIA GPU when the PIC backend is cuda or gpu (not yet tested on an NVIDIA GPU — see Installation), and handles bunched beams only. Selecting it greys out Grid mode and DC kernel (torch ignores them — it always uses an adaptive grid); a continuous beam falls back to numpy automatically. Also: Green's function (IGF / point), particle-mesh kernel (CIC / TSC), grid mode (fixed / adaptive), and the DC SC kernel (uniform / gaussian / pic2d) for continuous beams.
Field maps (FieldMap3D) — integrator (KD / DKD) and interpolation order (linear / cubic).
Envelope solver — solver choice: matrix (element-by-element transfer-matrix Σ propagation, default) or sacherer (coupled KV envelope ODE integrated with RK45; better under strong SC where the matrix split-operator under-resolves).
Collective effects — "CSR in bends" checkbox: apply a 1-D steady-state Coherent Synchrotron Radiation energy kick inside dipoles (multi-particle runs only — see Space-charge models → CSR).
Diagnostics & recording — record_substeps checkbox; Record particle density (histogram all alive particles into a 2-D density grid along s); Record halo action scan (count, at every record point of a multi-particle run, the particles outside the ellipses of the beam's own rms shape and emittance n·ε_rms in x–x′, y–y′ and φ–W — the Results tab's Halo action scan window; on by default; ≈ 20–30 ms and ≈ 12 kB per record at 10⁵ particles); Snapshot every N (full 6-D particle dump every N elements; 0 = only Marker(snapshot=True) fires); density bins and density extent (±mm) for the density recording. All of these are saved in the project file (record_action_scan for the action scan).
Scan controls — Scan N particles (macroparticle count the convergence scans use) and Parallel workers (0 = serial; N > 1 fans scan points across processes).

Convergence scans¶

Convergence scans are built into this tab — no separate dialog. The Scan parameters group has:

Scan axis combo — grid (nx=ny=nz), grid_extent (σ), step1 (integration/m), step2 (SC kicks/m), or n_particles.
Values (comma-sep) field — the scan points; defaults to 32, 48, 64, 96, 128.

The run row below offers:

Run All Scans (grid · extent · step1 · step2) — scans all four PIC/step parameters in sequence and auto-applies the converged value for each axis as it finishes.
Run Single Axis — scan just the selected axis with the Values list.
Stop — halt at the next element boundary, keeping the rows already completed.
Apply converged value — write the converged row's scan value back into the base settings used by Run Multi-particle.

Results stream into a tabbed output pane: Log (per-axis convergence log), Plot (ε_x end + σ_y vs scan value), and Table (per-point σ_x / σ_y / σ_φ / ε_x / ε_y / wall time).

Tooltips with formula references¶

Each field has a tooltip explaining its meaning + the relevant physics paper. E.g. the IGF tooltip cites Qiang et al. 2006.

Project dirty tracking¶

Every "fixed" setting in this tab (PIC grid, SC engine, Green's function, particle-mesh kernel, integrator, interp, step1 / step2, single-push drifts, RFQ solver, CSR flag) is serialised into the .lgproj JSON. Changing any of them marks the project as dirty so closing without Save Project triggers a warning. Section-collapse toggles and scan-axis widgets don't flag the project — collapse states persist per user via QSettings instead, and the scan-axis widgets are session-only. See Lattice tab → Unsaved-changes prompts.

Cross-references¶

← Beam tab · Continue to Matching tab →