Graphical interface

Install the interface from PyPI with python -m pip install pass-sim. The default installation and pass-sim[cpu] both include CPU computation and the GUI. Use pass-sim[gpu] or the equivalent pass-sim[cpu,gpu] to add NVIDIA GPU dependencies. Select the simulation backend separately in the input configuration; installing GPU dependencies does not enable GPU execution automatically. To install from a GitHub clone or extracted source archive, run python -m pip install --editable . from the directory containing pyproject.toml. Launch it with python -m PASS.gui or pass-gui.

Startup prepares the input schemas first, so the configuration page can become editable without loading the tracking commands. Calculation, plotting and file conversion dependencies continue loading in the background; their preparation status does not prevent editing the configuration.

Open a PASS input JSON, a .passproj project, or a project folder, or configure a new input. Folder selection prefers project.passproj, otherwise it requires exactly one .passproj file directly in that folder.
Edit the global parameters, injection, and execution sequence. Select Apply to commit each property form; unapplied forms and JSON text are drafts.
Select Validate in the sequence toolbar and resolve errors. See JSON input validation for validation scope and reports.
Save the input or project, select inputs on Run, and start the simulation.
Open the result directory or load outputs on Plot.

On Run, Output root directory selects the parent path and the optional Task name selects a folder such as output/capture_sc/. The latter initially contains the actual value default, rather than placeholder text; saved custom names remain visible. Leave it blank or enter default to use a single timestamp folder at minute precision, such as output/2026_10_30_18_39/ (output/YYYY_MM_DD_HH_MM/). The comparison ignores case and surrounding whitespace, so " DEFAULT " has the same effect. Existing subdirectories and result filename rules remain unchanged. Repeated automatic or custom names create siblings with unpadded suffixes _1, _2, and so on. The corresponding input parameter is Task name; project runs save the run-page choice as run.task_name. See Editable projects for setting precedence and rerunning.

The configuration page edits the same input used by the tracking engine. For editable project files, old-project conversion, run snapshots, stopping, and rerunning, see Editable projects. Standalone calculations are available under Tools; see GUI tools. The Analysis workspace uses the same icon-and-text sidebar as Tools, with four entries: Statistical data spectrum, PM particle spectrum, Frequency map analysis and Dynamic aperture. Statistical spectra use StatMonitor turn-by-turn quantities such as centroids and beam widths; PM spectra use individual ParticleMonitor trajectories. Each entry retains its own file, settings and analysis result. FFT spectra and frequency maps accept result files or external arrays; see Spectral analysis and frequency maps for the shared Python functions, supported files and numerical conventions. Analysis → Dynamic aperture analyses the observed survival regions of scans configured in Injection.

Dynamic-aperture workflow

In the selected Injection bunch’s Insert particles section, enable Generate x–y scan grid and configure its x/y ranges in mm, their point counts and initial dp list. Every dp value receives the complete x/y grid; fixed px, py and z default to zero. The form displays the total scan particle count and loads the saved grid when an existing bunch is selected. The summary displays Nx × Ny × Ndp = N particles. Editing the grid does not change the configured macro-particle count or injection schedule. Apply the bunch edit through the normal Injection editor. See Injection / Particle Generation for coordinate and reference-transform conventions.

Configure ParticleMonitor through its normal sequence editor: choose its position and same-position Order, particle tag range, recorded turns, output format and write interval. It records selected particles in one file per beam and monitor. The write interval controls buffering; every recorded turn is saved. Scan generation belongs exclusively to Injection.

On Analysis → Dynamic aperture, select one current PM HDF5 or finalized TFS file through PM file. Its injection records provide the initial coordinates. Read and classify the result in a cancellable background operation. Select initial dp, survival status or loss-turn colours. Show aperture boundary is enabled by default and can be switched off to display only the sampled points. Plot axes use actual initial x/y in mm. The target turn names a sample at the chosen monitor; it does not by itself certify a completed revolution. Missing initial coordinates or missing final samples are not classified as survival. Export all numeric points as CSV/NPZ and figures as PNG/PDF/SVG. Cancelling an export can leave a file that had already finished writing; successful completed exports are reported as such.

Plot mode → Multiple dp: boundary overlay displays selected initial-dp boundaries together with distinct colours and line styles. All groups start checked; use the dp list or Select all/Clear to choose a subset. Internal loss holes and disconnected stable regions remain visible. Groups without a drawable boundary are reported explicitly. Return to the single-dp mode to inspect points and loss-turn colours. Image export saves the currently displayed view.

Startup and file drops

Open-file dialogs start in the folder containing the current .passproj file, or the current standalone input JSON. Before a document is opened, source-checkout launches default to the PASS repository folder; installed copies use the working directory. A project’s temporary extraction directory is not used for browsing external files. This does not change how relative paths inside inputs are resolved.

The main window opens before schemas, scientific libraries and tool modules load in a background thread. Navigation, themes, Help and the Plot page are available immediately. Configuration and Run show loading messages until schemas are ready; their controls, the File menu and document drops are then enabled automatically, without waiting for the remaining tool resources. An unfinished tool shows a loading message. Each tool’s controls and initial plot are created on its first visit, after the modules finish loading. Unvisited tools are not constructed in the background. Tool values persist when switching pages in the same window.

The status bar reports when resources are ready. Before then, waveform/electrode previews, MAD-X previews/imports and Bump CSV conversion display a brief status message instead of waiting for imports on the interface thread; retry these actions after loading completes. File reading and actual calculations still take time, and creating a tool on its first visit can cause a short pause.

Drop one local .passproj, a project folder, or PASS input JSON onto the window, including child editors. File contents are checked before replacing the current document. A replacement requires confirmation; unsaved changes offer Save/Discard/Cancel. Invalid files or cancellation keep the current document. With a project open, an input JSON can replace the active input, be added as another configuration, or open as a standalone document. The configuration selector displays the input count, and 导入配置… (Import configuration) adds inputs to the same project. These configurations are independent alternatives; Beam 1 on the run page specifically means the optional second beam in a two-beam simulation.

Outside Plot and Analysis, a single OMC3 SDDS/HDF5 drop opens the conversion tool (see Data format conversion) without replacing beam parameters. CSV/TFS drops offer conversion, plotting, statistical spectra or PM particle spectra; dropping them directly into the converter selects conversion. NPY/NPZ/TSV/TXT/DAT drops open Analysis. Dropping CSV/TFS/HDF5 onto Analysis, or onto window margins or the tab bar while Analysis is active, uses the selected analysis tool. Plot also accepts drops onto its page, tab bar and active window margins. Spectrum and FMA automatically scan the available columns and arrays; select the signal and settings, then run the calculation. Dynamic aperture automatically reads and analyzes a current ParticleMonitor HDF5 or finalized TFS file with the selected end turn. It remains on the aperture page. Plot and Analysis accept multiple data files per drop and through the top Open files… dialog. Each file opens in an independent tab with its own data selection, settings, figure, zoom state and exports. New analysis tabs inherit the current analysis type and can then be configured independently. Dropping the same file again creates another tab for a different view. Tabs show filenames, with full paths in tooltips, and support reordering and individual closing. Closing a busy tab cancels and waits for its work before releasing it; other tabs remain usable. New tabs and file opening remain available after all tabs are closed. An individual plot tab can still add comparison files for overlays and differences; batch drops create independent figures. Projects, input JSON and the conversion tool retain single-file entry points; projects or JSON cannot be mixed with data files in a batch. For another project window, launch another pass-gui process.

Plot and analysis views offer thin horizontal and vertical crosshairs spanning the active plot area and always following the pointer. Curves separately mark the actual sample nearest the vertical line; scatter plots highlight nearby actual data points. A label near the crosshair intersection reports the marked point’s values, or pointer coordinates when no data point is selected. Marking data never moves the crosshair and does not create interpolated samples. Point lookup uses the underlying data even when the drawing reduces the displayed points. Spectrum hints include frequency, amplitude and phase; FMA hints include object identity and frequency drift; aperture hints include initial coordinates, dp, identity and survival/loss information. Crosshairs can be switched off, are hidden outside the axes and while dragging to pan or zoom, and resume on release without leaving the toolbar mode. Image exports omit the overlay.

Property ordering and sections

Property forms and the JSON source have separate drafts. Use Apply source or Discard source changes for JSON edits. If both contain pending changes, discard one draft before applying the other. Saving requires resolving drafts. Injection, Space charge, WakeField, and ElectronCloud forms apply their changes together as one undo step. Cancel restores applied parameters. Drafts are not automatically backed up; see Editable projects for manual saving and recovery.

The read-only Command type appears beside the property heading. Editable parameters start with name, position s, and length, followed by the element’s field strengths and geometry, then Model, Integrator, and slice count. Presentation order is independent of schema inheritance and JSON key order.

Sequence commands, including Injection and SortBunch, expose Order. Leave it blank or enter null to use the default command priority. If any command at the same s has an explicit order, all commands at that position must have distinct integer orders.

Inserting or duplicating a command, inserting generated optics, or importing MAD-X items also sorts the JSON Sequence in execution order: position using the engine’s tolerance bins, then Order or the default command priority. Commands with equal sorting keys keep their relative order. After successful sorting, each position group with explicit Order values is renumbered 10, 20, 30, ... in its existing execution order; numbering restarts in every position tolerance bin. Groups with all orders omitted or null retain their default-priority behavior and are not assigned explicit orders. If sorting fields are invalid or incomplete, such as missing or duplicate orders at one position, the JSON order and values are retained while validation reports the issue. Loading a file or applying raw JSON does not trigger this automatic sorting or renumbering. Undo restores both the previous sequence order and its Order values.

For example, SBend displays name, S (m), Length (m), K0L, E1 (rad), E2 (rad), Hgap (m), Fint, Fintx, Model, Integrator, and Num slices, followed by Field errors, Alignment errors, Aperture, Ramping, and Internal space charge sections. Each section keeps its switch and related parameters together inside a subtle border. All sections remain expanded, with no collapse controls. Disabled internal space-charge parameters stay visible.

Alignment groups its switch with DX, DY and DPSI. MAD-X element import also offers an alignment checkbox using the same error TFS as field errors. It moves only the magnetic field; apertures and SC boundaries remain fixed. Twiss transfer import does not offer alignment. See Element errors.

Other magnets use the same ordering for their supported parameters. RF data, Exciter frequency and amplitude modulation, Slicer ranges, and monitor reference optics and analysis ranges are grouped by purpose. Field, potential, density, and turn-selection outputs share a Diagnostic output section. Twiss retains its start/end optics and transfer settings sections.

Injection’s bunch editor groups its fields into Bunch and injection, Transverse distribution, Longitudinal distribution, Distribution file, Injection offsets, Insert particles, and Distribution output. All sections remain expanded and use the same subtle borders as other forms. The injection summary sits beside the particle counts and schedule. Manual coordinates, the particle file and the scan grid share Insert particles; they remain alternative ways of specifying the inserted particles. Distribution output places the save switch and format together. Turning saving off disables the format control while retaining its selected value.

Under Injection offsets, Momentum Offset dp (dimensionless dp/p) and Kinetic Energy Offset (eV) display the same offset in two forms. Editing either field updates the other using the current particle species and bunch reference kinetic energy, with the relativistic energy–momentum relation. Changing the reference energy keeps the last edited offset fixed and refreshes its converted value. Loading an existing input also fills the converted display. Applying the form saves the last edited offset and sets the other JSON field to zero, so the offset is specified only once.

Structured array parameters

Array and nested parameters have dedicated controls in the property pane. Use these controls to edit rows and dimensions directly. The JSON source tab remains available for complete input editing.

Save turns uses rows with start, inclusive end, and positive integer step. Add single turn creates a row whose start and end match; Add interval creates a range. All turns fills the current simulation range, while an empty table disables saving. Turn numbering starts at zero. Single rows are written as [turn] and intervals as [start, end, step].
Turn ranges for PhaseAdvanceMonitor uses start and exclusive end. A range must contain at least two turns; an empty table disables analysis.
Insert Particle Coordinate uses six numeric columns: x, px, y, py, bunch-relative z, and dp/p. Each row is one manually specified particle. The row count is displayed, and cannot exceed the first injection’s macro particle count. These coordinates replace particles inside that block; they do not add particles beyond the configured total.
Aperture value changes with the selected shape. Circle, rectangle, ellipse, rectangle-circle, rectangle-ellipse, racetrack, and octagon have labeled dimensions in meters. Polygon uses an ordered x/y vertex table. Radius and half-width/half-axis meanings are explicit. Shape switching keeps each shape’s current dimensions while the form remains open. Invalid sizes, degenerate polygons, and invalid octagon corner cuts are rejected on apply.
Dp aperture has a custom-range switch and lower/upper dp/p controls. With customization disabled, the engine uses its default -1 to 1 range.
KiL, KiSL, Field error KNL, and Field error KSL use explicit multipole-order/value rows. Order zero is dipole, one quadrupole, and two sextupole. Missing orders become zero; deleting a row does not shift higher orders. Duplicate orders are rejected. Integrated order-n strengths have units of inverse meters to power n.
Device Id uses integer GPU-ID rows with duplicate checking. The GPU device count is derived from this table, which is disabled for CPU inputs.
Slicer’s Explicit range has z-min/z-max controls, enabled by explicit range mode. auto writes no explicit range. Element Space charge has a switch, named-configuration selector, kick count, aperture controls, output switches, and its own saving schedule.

Tables support numeric cell editors, adding/removing rows, and a larger Table window. Right-click offers spreadsheet-row paste, copy, row movement, and clearing. Ctrl+V also pastes rows when the table itself has focus. Tab-separated or comma-separated numeric rows can be pasted without converting them to JSON; a malformed paste leaves existing rows unchanged. The larger window adds multiple rows at once and keeps edits private until Apply table. Apply the property form afterwards to update the input. Numeric table editors accept scientific notation and preserve small floating-point values. Saving also commits the numeric cell currently being edited. Optional bunch fields are shown with defaults even when omitted from the opened JSON.

Space charge

Use SC slicing to create a z_periodic Slicer. General-purpose slicing defaults to z_rel; WakeField slicing accepts z_rel or arrival_phase. Periodic is derived from Coordinate; legacy Periodic=true without a coordinate retains its arrival-phase meaning. Selecting arrival_phase sets equal-length bins and the explicit interval [-C, 0]. Changing circumference later requires checking that interval again. Slicing never rewrites particle z. RF does not re-bin saved intervals; regrouping requires another explicit Slicer.

Under Physics effects, click the Space charge heading to expand or collapse its submenu, just like the outer module section. Collapsing it does not change the project or discard the active form; there is no back-menu item.

Global configuration (全局配置) manages the module switch, named configurations, slice-set references, PIC grids, and solvers.
Insert calculation point (插入计算点) manually inserts a SpaceCharge command at a specified position, referencing a named calculation configuration. Point parameters, including the interaction length and output options, retain their existing meanings. See Space-Charge Effect (SpaceCharge).

Calculation options depend on Method and Solver:

pic lists only fft_free_space, fd_dirichlet, and dst_dirichlet. Deposition defaults to CIC, with TSC also available.
frozen and quasi-frozen list only the four free-space analytic solvers: round Gaussian, elliptic Gaussian, uniform disk, and uniform ellipse. Deposition remains visible but disabled.
frozen enables the fixed source centroid Center X/Y and only the selected formula’s sizes: Sigma for round Gaussian, Sigma X/Y for elliptic Gaussian, Radius for a uniform disk, or Semi-axis A/B for a uniform ellipse. Only elliptic formulas enable Angle.
quasi-frozen derives the centroid, sizes, and orientation from each slice’s current particle moments, so fixed profile inputs are disabled. Grid settings in analytic modes define diagnostic sampling and the default aperture.

Center X/Y describes the source centroid; Angle is the counterclockwise rotation of its local x axis in radians. Sigma is a Gaussian single-axis RMS size, Radius the uniform disk’s outer radius, and Semi-axis A/B the uniform ellipse’s semi-axes. Centroids and sizes are in meters. These describe the charge distribution, not the wall or particle loss aperture. Inapplicable fields remain visible, are disabled, and are written as null on saving, avoiding parameters from a different formula in the saved configuration.

Grid extent input (网格范围输入) selects full widths (全宽) or half widths (半宽); enter both axes in meters. The inactive pair is saved as null. Node spacings are calculated from extent and node counts.

Each SC point sets Aperture type and Aperture value; default resolves to the grid rectangle. The aperture handles losses and also defines the FD/DST conductor. Different FD walls use separate cached solvers with one shared grid; FFT shares kernels and uses apertures for losses only. Initialization checks finite PIC apertures fit in the grid and requires DST to use the complete grid rectangle. Wall and outside particles are lost before field calculation.

Analytic solvers cannot save potential. The GUI prevents enabling this option; an imported enabled option can be cleared. Internal SC inherits its parent element’s aperture; conflicting legacy child apertures are overridden by the engine. Num kicks sets the internal SC nodes, independently of the parent’s transport Num slices.

Injection, clocks, RF and pulsed elements

Injection preserves valid harmonic-ID permutations when applying a form. Harmonic Number is editable: enter the desired group count and select Update harmonic slots (更新谐波槽数), or apply the form directly. Increasing the count fills new slots with zero real and macro particles, retaining the current bunch’s reference parameters and assigning each new slot its own harmonic ID and default reference arrival time. For one populated bunch in four groups, fill only bunch0 with harmonic ID 0 and set the count to 4; the other three slots are created empty. GUI JSON drafts and imported inputs with fewer bunch entries are also completed when applying the source or saving/running. Saved inputs retain the full slot structure. Empty slots require no separate particle configuration and produce no monitor files. The bunch selector’s tooltips and summary identify empty slots. This group count remains independent of the RF cavity harmonics.

Empty current slot (当前槽置空) and Empty other slots (其余槽置空) zero the selected particle counts and clear particle sources without changing the group count. Reference parameters and harmonic IDs are retained. Reducing the group count removes only empty slots whose harmonic IDs are outside the new range; occupied slots must first be emptied. These operations remain form drafts until applied. Adding/copying a populated bunch fills an existing empty slot first; the group count increases only when every slot is occupied. Copying an empty slot does not create another slot. Deleting a bunch leaves its slot empty and preserves the group count and every other harmonic ID. To remove slots, reduce Harmonic Number explicitly. The batch summary shows the planned total, first/subsequent batch sizes, last injection turn and macro-particle weight. New bunches retain the existing weight. Distribution input offers sequential or repeat. Random seeds and reference arrival times can be cleared to null. Integer text inputs accept exact scientific notation, such as 1e5 or 2.5e3, and save ordinary JSON integers. Fractional results, NaN and infinity are rejected. Particle-count fields retain support for values above the signed-32-bit limit; bounded controls retain their existing ranges.

The shared design clock is calculated from the initial beam, circumference and enabled RF waveforms; global configuration has no clock-table input. It is independent of collective changes to the tracked particles. To preserve an external RF frequency program, use the component’s direct-frequency mode. See Automatic design clock and initialization for the design calculation and migration limits.

RFCavity components support inline/file and harmonic/direct-frequency modes. Voltage, phase and direct frequency can be scalars or tables sharing Time (s). File input requires TIME/VOLTAGE/PHASE, plus FREQUENCY for direct-frequency mode; a harmonic file must omit FREQUENCY. Inactive alternatives are cleared on apply. The physical-voltage preview evaluates the tracking waveform’s exact frequency integral, shows each component and their sum, and allows an explicit time window. It is not a multi-harmonic bucket calculation. Legacy cavity-level parameters and turn-indexed RF files need a physical-time migration, not a renamed key.

The library includes Bump and the current voltage/geometry ElSeparator interface. Required quantities remain blank until supplied; incomplete drafts cannot be applied. Bump previews TIME/HKICK/VKICK and can convert two CISP CSV files into one TFS using the union of their time nodes with each plane’s endpoint values held outside its range. Kicks are integrated delta-P/P0; the preview includes time offset and endpoint holds outside each plane’s supplied range. The CSV time grids and ranges may differ; conversion retains their union. Preview ES (预览ES) previews the tilted electrodes, circulating-beam field-free region and field region, with the independent vacuum aperture drawn as a dashed outline in beam coordinates. For rectcircle/rectellipse, the outline is clipped to the actual intersection rather than showing both complete component boundaries. Electrodes cover all local v; the drawing is cropped for display. S is its exit and S-Length its entrance. Zero strength retains material losses; zero length supports one VL kick. V is the interplate voltage difference in V, and VL its longitudinal integral in V m; applying/running requires exactly one. Gap and septum position must be filled before previewing; missing or invalid values identify the offending field. Leaving both V and VL empty permits a geometry-only preview without computing the field. Distribution File Mode and its popup fit both sequential/repeat options without truncating their labels. The ES Hardware parameters (硬件参数) group labels V, VL, gap width, septum position/thickness and tilt in Chinese, retaining their units and JSON keys. Bump preview validation and file errors are explained in Chinese, including path, TFS format, numeric data and unit errors.

Exciter uses a signed Kick angle (rad) amplitude, displayed in scientific notation such as 1e-6, and exposes tune/frequency selection and FM/AM-dependent fields. Voltage, gap and length are not element inputs; the Exciter tool converts between voltage and kick angle at a chosen reference particle and energy. New drafts default to tune mode, with Excite tune = 0.47 and Sweep tune = 0.02; existing frequency-mode inputs retain their Hz values. Quadrupole, Sextupole, Octupole and Multipole expose Is ramping and Ramping file for normalized strengths from a physical-time TFS table. The Ramping group includes Generate / import ramping file. Successful export fills the file path and enables ramping in the property draft, clearing legacy component-file fields; apply or insert the element to save the change. The generator supports rise–hold–fall templates and numeric table pasting; see GUI tools for the workflow. See Magnet ramping; other magnetic elements keep ramping disabled.

Exciter previews evaluate particle time as t = T_start + elapsed - z/(beta*c) using continuous bunch-relative z and the local reference arrival time. The DDS phases integrate frequency from the common startup at T_start and stay continuous at sweep resets. Dual mode defaults to a half-period sweep offset; a different offset produces a warning. Nominal bunch slots do not shift the preview. Both DDS signals use one shared kick-angle setting. AM uses the same continuous particle elapsed time as FM and the reference-clock frequency at startup for its normalization. The angle is applied as a normalized transverse momentum increment and is not rescaled with tracked beam energy.

Transverse feedback

The Transverse feedback component section provides TransversePickup and TransverseFeedback. Add the pickup first, then select its sequence name in the feedback’s Pickup field. Each pickup requires exactly one feedback. The feedback draft starts with zero coefficients and gain; enter the FIR coefficients, turn delay, gains and optional kick limits before tracking. Both nodes must be placed at actual transport boundaries. See Bunch-by-bunch transverse feedback for phase conventions, filter design and diagnostics.

In the feedback parameter form, Generate FIR coefficients… (生成 FIR 系数…) opens a coefficient generator. The referenced pickup’s Plane determines whether it designs x, y or both planes. Enter each plane’s tune and pickup-to-feedback phase independently; these inputs start blank and are not inferred from the machine configuration. Phase is in radians and is the signed phase difference within the same sequence turn numbering. It can be negative for an upstream feedback node; positions S (m) do not determine it, and the turn delay must not be counted a second time in this phase.

The planes share a design method, tap count and delay. Choose minimum_norm (default) or flat; the GUI accepts 3–256 taps, with at least five for flat, and an integer delay of at least one turn. The 256-tap maximum is a GUI limit, not a limit imposed by design_feedback_fir. Click Calculate and preview (计算并预览), inspect the result, then Fill draft (填入草稿). Invalid designs leave the parameter draft unchanged. A flat response is local to the chosen tune and does not establish closed-loop stability or select a gain.

Filling the draft replaces the coefficient lists for all measured planes, clears coefficients for unmeasured planes and synchronizes Delay turns. Gains remain unchanged, including a zero initial gain. The generated arrays remain manually editable; click Apply or Insert to save the draft. The design inputs are temporary GUI controls: only the existing coefficient and delay fields are saved, with no new JSON fields or electronics model.

WakeField

Wakefields → Global configuration manages the global enable switch and named model/solver configurations. Opening it collects existing inline point definitions into separate named configurations, without merging them. Applying a configuration rename updates its point references; configurations still in use cannot be deleted. Wake point selects a configuration, position, slice set and local enable switch. The global and local switches must both be on. Each point owns independent history even when it uses the same configuration. Inline Groups remain supported. See WakeField for the JSON/API representation.

Groups and components can be added, copied and removed. Solver selection covers direct, fft, recursive, modal, partitioned_fft and time_fft; history, grids, memory and periodic-boundary controls follow the selected mode. The editor exposes all nine model families, spatial powers for custom components, and fixed/factorized/ideal velocity laws. The shared schema validates combinations. File models require explicit units, axes, sign conventions, integration convention and reference beta; unknown external-file conventions are not guessed.

Electron clouds

Physics effects → Electron cloud provides Global configuration, Insert electron-cloud slicing, and Electron-cloud interaction point. Start with a named configuration, select its mode and solver, then insert points that reference it. The global Enabled and point Is enabled switches must both be on. Points sharing one configuration own independent cloud states. The interface writes the ordinary input schema described in Electron Cloud (ElectronCloud).

Mode and solver selection
Mode	Solver	Behavior and slicing
`frozen`	`uniform_round_free_space`, `fft_free_space`, `fd_dirichlet`, or `dst_dirichlet`	Fixed cloud with a transverse beam kick; no Slicer dependency.
`build_up`	`round_gaussian_beam`	Prescribed round-Gaussian beam drive, electron motion and wall emission; no cloud self-field or beam feedback. Requires a Slicer.
`coupled`	`fd_dirichlet`	Saved beam-slice particles drive the electrons; includes cloud PIC self-fields and a transverse beam kick. Requires a Slicer.

The editor groups the source, grid/boundary, and electron-motion/wall-emission parameters, and shows controls relevant to the selected mode and solver. Electron density is the physical number density in m⁻³; in dynamic modes it is only the initial density. The cloud disk radius, circular chamber radius, and beam RMS sigma are separate parameters. Supply the required density and disk radius; dynamic modes also require a chamber radius, positive maximum time step and positive beam sigma. Beam sigma controls only build_up; coupled retains the required schema field but uses the actual saved beam particles. The complete initial disk must lie strictly inside the chamber.

For frozen fields, free-space solvers accept default/off boundaries; FD supports the available conducting aperture shapes; DST requires the full grid-aligned rectangle. Dynamic modes use the circular Build up chamber. Coupled grids require odd Nx/Ny of at least 5, widths covering the chamber diameter, and spacing no greater than half its radius. These bounds check that the geometry is resolved at all; users still choose and check numerical resolution. The dynamic form also exposes the uniform magnetic field, magnetic gradient, initial energy, primary and secondary emission, macro-electron limits, integration step limit and wall-hit limit. An unspecified random seed is saved as JSON null; an explicit integer makes sampling reproducible for equal inputs.

For each dynamic point, explicitly insert or select a Slicer with Purpose=general and Coordinate=z_rel at the same S (m), before the point in execution order. It must cover all live particles. Periodic or beam-beam slices are incompatible. Re-run Slicer after structural regrouping; the cloud point does not generate or refresh slices. Validate reports missing configuration/slice references and incompatible execution order or coordinates.

An interaction point exposes position, order, configuration, slice set, interaction length, local enable switch, Save fields, and Save turns. Interaction length scales frozen/coupled kicks; it does not transport the beam. It remains required in build_up but does not change that mode’s electron dynamics. Add transport separately. Output turns are zero-based, with inclusive [start, end, step] ranges; saving requires both Save fields and selected turns. Empty Save turns disables output.

Add, duplicate, rename, or remove named configurations in the global editor. Applying a rename updates point references; referenced configurations cannot be removed. Mode, solver and aperture switches retain editing drafts so that returning to a previous selection restores its entries. Apply commits the complete edit as one undo step; Cancel restores the applied input. Disabling the global block preserves saved configuration definitions. Saving/reopening JSON or a project retains the three modes and their parameters, including null seeds.

Copying a point between project inputs also copies its named configuration and, for a dynamic point, the referenced Slicer definitions. Name collisions receive suffixes and copied references are updated. The target’s existing enable switch is preserved. Dynamic copies compare the prescribed physical clocks and offer an explicit choice when they differ; copying a frozen point needs no clock choice. Copying input definitions does not transfer a running point’s electron state.

Result files

The plot page loads CSV, TFS, and one-dimensional DistMonitor HDF5 columns. Load multiple files to select beam/bunch/turn snapshots, filter live/lost particles and injection batches, and inspect reference metadata. arrival_time_s is computed only for live particles with matching row or snapshot reference time and beta. Lost coordinates cannot use a later live reference. Missing values preserve row alignment. Multidimensional SC files use a separate field view.

Choose automatic, line, or scatter display. Automatic mode uses scatter for particle tables with tag or particle_id, and lines for other tables. Missing samples interrupt lines. Large previews reduce displayed points without changing the data. Each loaded file retains its axes and filter settings. The summary reports total, selected, and finite rows. Close current data unloads the current file; file loading can be cancelled. HDF5 table loading checks cancellation between data blocks. Loaded arrays remain an independent snapshot: later changes to the source file do not silently change the displayed or exported data. Reload the file to use a newer snapshot.

Phase-space presets select x–px, y–py, z–dp, x–y, or arrival-time–dp when their columns are present. Axes use supplied units and reference metadata; units are not inferred for plain CSV. Density and projections bins all finite X/Y pairs into 8–256 bins and displays counts and marginal projections. Counts represent macro-particle rows, without charge weighting. Large density calculations run in the background. Changing the selection again discards an older calculation; the preview and image export become available for the latest selection when its calculation finishes. Every finite pair still contributes to the histogram, including saved electron-number weights in the electron-cloud source view.

Select a baseline to overlay data or compute A−B or (A−B)/B. X values and row order must be identical and finite, with compatible units, coordinates, and reference conventions; particle IDs must also match when provided. There is no implicit sorting, interpolation, or unit conversion. Relative differences are NaN where the baseline is zero or nonfinite. Switch density plots to line or scatter mode before comparing data.

Export data writes all selected rows and numeric columns, preserving NaN and numeric types, with a hash-checked .csv.metadata.json sidecar in the pass-table-metadata-v1 format. Keep both files together; stale or unsupported metadata is rejected when reloaded. Export image generates PNG/SVG/PDF from the complete selected data and range. Advanced plots have a Matplotlib toolbar. Exports fix the current selection and report progress; cancellation may leave already completed files. CSV and metadata must be retained as a pair.

SC field arrays use (slice, y, x) with matching x/y coordinates, slice_id, and delta_z. Select a field and slice, and optionally overlay the saved aperture. Raw density, potential, and integrated Ex/Ey have units C/m², V·m, and V. Divide by Δz: slice averages gives C/m³, V, and V/m, requiring known units and positive finite widths. The view displays saved solver, potential-reference, and boundary metadata. Field export flattens the selected slice in y/x order, retains raw fields, and adds averages when selected; it does not recompute fields.

Electron-cloud HDF5 outputs open a dedicated Electron-cloud view selector. Available views follow the saved data: Instantaneous fields, Weighted electron distribution, and Time history. Frozen analytic output has fields; frozen PIC can also contain sampled electrons. build_up provides source and history data, and coupled additionally provides fields at the final saved physical time. Metadata identifies the mode, solver, source length and field time.

The source view selects saved x, y, ux, uy, uz or weight columns as available. Its two-dimensional histogram and projections sum saved electron-number weights per bin. They represent the physical electron number for the saved source length, not the number of macro-electron rows or a volume density. The history view plots a selected diagnostic against physical interval-end time time_end in seconds, initially using n_electrons_after. Other saved diagnostics include emission, wall hits and evolution steps.

Electron-cloud fields use volume charge density (C/m³), number density (m⁻³), potential (V), and electric field (V/m). They are already physical instantaneous fields and have no SC slice-width division control. Export the selected view as CSV with its metadata sidecar, or as PNG/SVG/PDF. Source exports retain saved particle weights; history exports retain all diagnostic columns and phase IDs; field exports use the saved grid. Exports use the complete selected data.

Twiss and optics

The library entries appear in this order:

Import Twiss points from MAD-X (从 MAD-X 文件导入 Twiss 点).
Insert one-turn transfer matrix (插入单圈传输矩阵).
Generate a smooth-approximation Twiss sequence (生成平滑近似 Twiss 序列).
Insert a Twiss transport point (插入 Twiss 传输点).

The MAD-X entry supports the sampling modes described below. The two generators use Preview generation, followed by Insert into Sequence. Previewing does not change the project. The preview shows the number of commands, position range, derived beta functions, step length, total phase advances, and the first 100 points. All generated points are inserted, including those beyond the table preview. Names that already exist receive a numeric suffix, and the preview displays the resolved names. Existing optical transport in the same ring range is flagged because adding another map can duplicate transport.

Changing generator inputs invalidates the preview and disables insertion until another preview is generated. Changes to the sequence, global circumference, or unconfirmed JSON also prevent insertion of an outdated preview. Circumference defaults to the global value; insertion synchronizes the global circumference to the displayed generator value. Existing commands are preserved. Leaving an edited generator asks whether to discard its uninserted draft.

MAD-X source and reference beam

Both element import and Twiss-point import offer Data source (数据来源): Existing Twiss/TFS (已有 Twiss/TFS) keeps the TFS workflow, while MAD-X sequence loads a .seq or .madx source using cpymad, which is installed automatically as a required PASS dependency.

For sequence input, select Sequence file (Sequence 文件) and enter the Lattice name (格架名称), initially ring. MAD-X LINE and SEQUENCE definitions are supported. Beam source (束流来源) selects either BEAM in file (文件中的 BEAM) or PASS beam configuration (PASS 束流配置). The file option requires an explicit beam declaration. With PASS configuration, choose PASS reference bunch (PASS 参考束团), displayed as an Injection name and bunchN. No first-bunch default is inferred. This selection supplies one reference beam for MAD-X; it does not overwrite the PASS beam configuration.

Optics calculation (光学计算) offers MAD-X TWISS or PTC TWISS when importing Twiss points or inserting a PhaseAdvanceMonitor. Ordinary physical element import does not require an optics calculation. PTC is needed for models using its quadrupole fringe optics. PTC output is converted to the supported uncoupled Twiss-map conventions; unsupported closed orbit, vertical dispersion or coupling stops the import. Physical-element conversion retains quadrupole F1/F2 and supported straight-magnet fringe controls from the sequence; see Physical entrance and exit fringe maps. Other unsupported fringe parameters still stop the import instead of being dropped.

Use Preview import before Import into Sequence. The preview includes the lattice name, MAD-X version, reference-beam choice and any source warnings. Preview and import reuse the same loaded result. Changes to the source, lattice name, beam selection or requested optics invalidate the relevant cache. After editing a file referenced by the source script, use Reload sequence (重新加载 sequence) to force a fresh load and preview. The existing sampling, BPM and geometry options still apply. The Python workflow and PTC derivative conversion are documented in Method 4: Load a MAD-X sequence or LINE.

Batch properties during element import

For physical-element import, enable Set properties by element type (按元件类型批量设置属性), select a command type and a property, then choose Add property setting (添加属性设置). Enter its value and add further settings for the same or other types. For example, set every imported SBend’s Model to rot-kick-rot and every Quadrupole’s Num slices to 20. Only selected properties of matching newly imported elements are replaced; unselected properties and existing sequence entries retain their values. Command, position and length come from the source.

Preview validates the resulting elements and lists the batch settings before import. Invalid settings prevent insertion. Explicit Order settings must still be complete and distinct at each shared position. Settings are retained in drafts and saved import recipes. Add Aperture type before Aperture value when changing aperture shape, so the value editor uses the selected geometry.

The ordinary SBend property editor also offers rot-kick-rot alongside adaptive and drift-kick-drift-exact. Quadrupole instead offers mat-kick-mat for its matrix-based map.

MAD-X sampling

Sampling mode defaults to Keep original positions. Selecting Uniform interpolation enables Segments per turn N, a positive integer. The base grid has N+1 points from 0 to C, with spacing C/N. Merge consecutive Drift is disabled and ignored in this mode. There is no advanced interpolation menu.

Click Preview import to see the actual spacing, base point count, additional split locations, Twiss command count, and full horizontal/vertical phase spans. Then use Import into Sequence. Only resampled points and necessary split points are imported; the source Twiss rows are not also imported. Import still appends to the current Sequence, so remove any earlier transport that this import is intended to replace. Changes to sampling inputs or the source file invalidate the cached import result.

The interpolation uses source phase, beta and alpha together: a quintic Hermite polynomial represents cumulative phase on each source interval. Its first and second derivatives match those implied by beta and alpha at both endpoints. Beta and alpha are then derived from that same polynomial. Dispersion uses cubic Hermite interpolation of DX with DPX as its slope in the supported uncoupled, on-reference paraxial convention. See Input File Generation (Command-Line Mode) for the equations and Python API.

The source must cover 0 through LENGTH, have positive beta functions and unwrapped increasing phases consistent with Q1/Q2. Missing endpoints are not extrapolated. The entire phase polynomial is checked for positive slope; if this fails, export denser source data from MAD-X. Merely increasing N cannot recover information absent from the source. Source values and total phase span are preserved to floating-point precision, with a tolerance when checking rounded TFS header tunes.

Thin elements and field errors retain their original positions, splitting the Twiss transport there. Zero-length BPM markers and selected monitors also retain their exact positions; finite BPM monitors are placed at the center. Distinct optical states at repeated S are preserved as incoming/outgoing states with a zero-length Twiss map for the optical jump. Consequently the final positions need not all be equally spaced. At a common position, Twiss maps execute before additional kicks/errors. The source optics already include its design linear focusing: explicitly inserted kicks are additional effects, not a subtraction or replacement of that focusing. Added linear errors can therefore change the tracked tune even though the resampled base optics preserve the source tune.

MAD-X BPM import

MAD-X MONITOR, HMONITOR and VMONITOR use the same BPM import options. The BPM handling (BPM 处理) checkbox Insert PASS monitor at BPM positions (在 BPM 位置插入 PASS monitor) is initially off. Enable it, select Monitor type (Monitor 类型), and fill in Monitor parameters (Monitor 参数) to add a StatMonitor, ParticleMonitor, DistMonitor or PhaseAdvanceMonitor at selected BPMs. The parameter controls follow the ordinary monitor editor. In element import:

BPM length and recording
Length	Recording off or BPM unselected	Recording on and BPM selected
`L = 0`	`Marker`	Selected monitor at `S`
`L > 0`	One `Drift` of length `L`	Half drift → monitor at `S-L/2` → half drift

TFS S denotes the BPM exit, so S-L/2 is its center. Recording does not add an extra marker. With recording off, finite BPM drifts may merge with adjacent drifts; with recording on, merging preserves the center monitor.

By default, recording covers all BPMs. Enable Select matching BPMs only (只选择匹配的 BPM) to limit it. BPM names (BPM 名称) accepts exact original MAD-X names separated by commas or newlines. BPM regex (BPM 正则) accepts one regular expression per line, preserving commas inside expressions. Matching is case-insensitive and uses the union of both fields; regular expressions use search matching. With the filter enabled and both fields empty, no BPM is selected. Unmatched BPMs retain the default conversion. Invalid regular expressions stop the preview with an error.

Strict geometry checks (严格检查几何一致性) is initially off. Enable it to reject inconsistent local positions, transport intervals or circumference. For element tracking, accumulated lengths must agree with each element’s exit. Twiss mode checks transport intervals without requiring sampled-row lengths to sum to the circumference. Drift merging always requires contiguous physical intervals, even with strict checks off.

When the source contains BPMs, the preview also opens a scrollable BPM conversion table. It shows the original name and occurrence number, MAD-X type, length, original exit S, whether a monitor was inserted, measurement position, conversion result, and final items after merging. Each final item includes its name, command, S, length and merge status. This keeps repeated names distinct and makes BPMs absorbed into longer drifts visible.

ParticleMonitor requires Max tag. Set Save turns for DistMonitor and Turn ranges for PhaseAdvanceMonitor using the range table; empty ranges produce no distribution output or phase-advance analysis, respectively. Phase-advance optics are taken from each source BPM row and, for finite BPMs, propagated backward through a half drift to the monitor center, with dispersion converted to PASS units. Closed-orbit offsets default to zero; configure any needed offsets explicitly for the generated tracking model.

The two Twiss import modes retain their Twiss transport and add or split transport points at these monitor positions, including exact center points in uniform interpolation. Changing the BPM settings invalidates the import preview. Selection and strict-check settings are preserved in the import draft/recipe. See MAD-X BPM markers and monitors for the Python API and monitor options.

One-turn transfer

Enter a name, circumference \(C>0\), tunes \(Q_x,Q_y\), and one set of periodic optical parameters in the order \(\alpha_x,\alpha_y,\beta_x,\beta_y\). Beta functions must be positive and are independently specified; they are not derived from the smooth-approximation formula. The horizontal dispersion \(D_x\), its derivative \(D'_x\), and full-turn chromaticities DQx and DQy appear directly in the same form, without an advanced collapsible section. All numeric inputs must be finite.

The generator copies alpha, beta, and dispersion to both endpoints. It sets S previous (m) = 0, S (m) = C, the previous horizontal and vertical Mu values to zero, and their endpoint values to \(Q_x,Q_y\). Thus the map has length \(C\) and phase advance \(2\pi Q\) even though the periodic optical functions agree at both endpoints.

Longitudinal transfer supports off, drift, and matrix. Only matrix enables the longitudinal tune \(Q_s\); its endpoint Mu z is \(Q_s\) and its previous value is zero. Other modes generate zero longitudinal phase advance. The engine’s matrix mode also uses the bunch’s longitudinal size and momentum spread; drift uses the slip factor and path length. See Twiss Transport (Twiss) for the tracking equations.

Smooth approximation

Enter \(C>0\), positive full tunes \(Q_x,Q_y\), and a positive integer number of segments per turn, \(N\). Do not supply only the fractional tunes when deriving the smooth beta functions (enter 9.47, for example, rather than 0.47). The form labels identify these as full tunes:

\[\beta_x = \frac{C}{2\pi Q_x},\qquad \beta_y = \frac{C}{2\pi Q_y},\qquad \Delta s = \frac{C}{N}.\]

The generator calls generate_smooth_twiss with num_points=N+1. The result contains an initial identity point at \(s=0\) and \(N\) transport segments ending at \(C\). The positions are \(s_i=iC/N\); phase advances are distributed linearly, and each segment receives DQx/N and DQy/N. The initial point has zero chromaticity. Names use the chosen prefix and point index, so short steps cannot produce duplicate names through position rounding.

Alpha defaults to zero. Constant alpha, dispersion, dispersion derivative, and full-turn chromaticity appear directly in the form, without an advanced section. These retain the existing generator’s behavior. Standard smooth optics uses zero alpha; nonzero constants define a custom sequence of transfer maps. Longitudinal modes follow the one-turn form. The workflow generates only Twiss commands, not SpaceCharge points.

Manual transport points and subsequent editing

Select Insert a Twiss transport point to add a manual map. A command describes transfer between two endpoints, so the form groups fields into Start optics, End optics, and Transport settings. Mu values are cumulative phases in cycles (\(2\pi\)), not radians.

Both generators write ordinary Twiss commands. Projects additionally preserve their generation settings and MAD-X import sources. After insertion or loading a JSON, select a generated command to edit its two endpoints individually. Use Save JSON for an independent input or Save project for the complete project. Generation settings can be restored from Project contents for another preview and insertion; this does not automatically replace manually edited commands.

Tools

The Tools workspace provides a beam calculator, tune diagram, RF bucket, phase-space plotting and emittance calculation, magnet conversion, exciter preview, and data format conversion. Calculations are independent of the active simulation input. Ions and atoms use kinetic energy per nucleon (AMeV); species with A=0 use MeV per particle. Particle masses come from the bundled evaluated mass catalog. See GUI tools for units, formulas, data sources, and workflows.

Appearance and controls

Select a dark, light, or system theme in the top bar. Window and pane sizes, theme, and sequence-column preferences are remembered locally. Drag column boundaries to resize them; right-click the header to show additional columns. Name, Command, and position remain visible. The sequence follows the engine’s position bins and command priorities; hover over a position to inspect its full value.

The left library starts with Input configuration (required) expanded. Under Physics effects, Space charge, Wakefields, Beam-beam effects and Electron cloud have independent submenus.

Property fields for the selected mode remain expanded. Long forms scroll, and Expand gives the editor the full workspace; Restore returns to the previous layout while retaining drafts. Dropdowns change selection by clicking an item; scrolling an open list only browses its options.

Help and local documentation

The Help menu next to the theme selector provides Online documentation (Chinese / English), Source code, Read local documentation (Chinese / English), Rebuild local documentation, and About PASS. Web links and local HTML pages open in the system’s default browser.

To enable local builds, install the documentation dependencies in the same Python environment used to launch the GUI, from a complete PASS source checkout:

python -m pip install --editable ".[docs]"

Every click on Rebuild local documentation starts a full Sphinx HTML build of both languages, using the GUI’s Python interpreter. The build runs in a separate process; the interface remains usable. The progress window shows live logs and a stop button. Closing that window leaves the build running; View build log in the Help menu reopens it. Repeated builds are disabled while one is running. Closing PASS during a build asks whether to stop it before exiting.

Each build writes to a new docs/build/gui/<timestamp-id>/ directory. Only a successful build with no Sphinx warnings and all language home pages present updates docs/build/gui/latest.json, which identifies the result used for reading. Failed or stopped builds leave the previous successful result available. Build directories are retained; rebuilding does not delete older results. Read local documentation opens the saved result without rebuilding and falls back to the conventional docs/build/html/ output if no saved GUI result is available. If no local page exists, it offers to compile or open online documentation. Missing sources or dependencies and filesystem errors are reported with guidance; the GUI does not install dependencies automatically. A regular package installation without the source checkout can use online documentation but cannot build locally.

About PASS displays the installed version, project description, authors, institution, copyright and Apache License 2.0. Documentation, repository and issue tracker links are clickable. The license opens in a read-only window when available locally, with an online fallback. Copy version and environment information copies the PASS, Python and PySide6 versions, operating system and architecture.