GUI tools
The Tools workspace provides independent calculations and data conversion. Inputs persist while switching pages in the same window; calculations do not modify the active simulation input or saved project. Use Detailed formulas for equations and data sources, and Copy formulas (LaTeX) for editable formulas.
Magnet ramping files
Open Tools → Data conversion → Magnet ramping
(工具 → 数据转换 → 磁铁 ramping…) to create the normalized-strength TFS tables
used by Quadrupole, Sextupole, Octupole and Multipole.
Import CSV / TXT / TFS: select the source file, delimiter, header and skipped rows; select the time column and its unit (s, ms, μs or ns); map each desired source strength column to its target, for example
K1LorK2SL. For TFS withTIME_UNITmetadata, the declared unit fixes the time-unit selector; column-unit metadata is checked before export.Generate from time breakpoints: add normal/skew K or KL columns and edit
TIME (s)and strength values in the table. Add or remove rows to describe the required piecewise-linear program. Paste a rectangular numeric range from Excel or another TSV source with Paste cells (Ctrl+V), beginning at the upper-left selected cell. Rows expand automatically; add and name any required strength columns first. Headers, nonfinite values and ranges wider than the existing table are rejected without changing the table.Rise–hold–fall template: select a strength column, enter the start time, rise/hold/fall durations and initial/plateau/final strengths, then apply the template. Rise and fall durations must be positive; a zero hold duration gives a triangular program. The selected component is replaced by the template, including its endpoint holds. Existing time knots remain; new knots are merged into the shared time grid and other components retain their piecewise-linear programs. Template strengths use the selected column’s units.
Use Read columns, then Preview and validate to inspect a component
before using Export ramping TFS. Times must increase
strictly, all values must be finite, and a component cannot have both K and KL
columns. Export converts time to seconds, preserves the selected strength units
and records normalized-strength metadata. The preview displays one selected
component at a time, so different strength units are not overlaid on one axis.
Opening this tool from Data conversion does not change the active element:
enable Is ramping and choose Ramping file in that element’s editor.
Alternatively, use Generate / import ramping file in the element editor’s
Ramping group. The generator starts from the current strength draft and
checks the element order and thin-magnet KL requirement before export.
Export and use for current element saves the TFS, fills Ramping file,
enables Is ramping and clears incompatible legacy component-file fields in
the property draft. Apply or insert the element to save these changes. Closing
without a successful export leaves the element draft unchanged.
K and KL values are absolute normalized strengths, not physical fields or ramp multipliers. Thin magnets require KL columns. Runtime interpolation, endpoint holding, current-bunch momentum normalization and the entrance-frozen approximation are described in Magnet ramping.
Kinematics, units and precision
Ions and atoms use AMeV, meaning kinetic energy per integer nucleon count:
Ek=K/A. Electrons, muons, tau leptons and mesons (A=0) use MeV per particle.
Neutrons and antinucleons have A=1, so the per-nucleon and per-particle values agree.
Write D=max(A,1) for the common divisor. C-12 6+ at Ek=100 AMeV has complete
kinetic energy K=1200 MeV. Its evaluated mass is still charge dependent;
this convention does not approximate the rest mass by A*u.
The read-only, dimensionless mass ratio mu follows Rest mass in the calculator results and the other tools’ reference-beam panels. It updates with particle/isotope/charge selection and is the numerical mass in u, not the integer nucleon number A; invalid mass data clear the field. For the same nuclide, changing charge leaves Z, N and A=Z+N unchanged, but changes the electron count and binding energy, hence the actual rest mass and mu:
For ions, the displayed total energy, momentum and rest mass are E/A (MeV), p/A (GeV/c) and m0/A (MeV/c²). For A=0, the corresponding fields show complete-particle E, p and m0. The mass ratio mu always refers to the complete particle, remains visible after rest mass, and is not an energy divisor. At fixed A and Ek, changing charge keeps complete kinetic energy K fixed, but the evaluated mass correction changes gamma, beta and momentum, as well as rigidity. Numeric results use 12 significant digits without asserting extra measurement accuracy. Units follow names in parentheses. The equations below use complete-particle K, E and p internally.
Known Ek, displayed total energy/momentum, rigidity, beta or gamma can be inverted.
The beam calculator displays the magnitude Bρ=p/(abs(q)*e). Neutral particles
show no finite rigidity; selecting rigidity as their known quantity is rejected.
Ek=0 gives beta=0, gamma=1 and momentum=0. Invalid inputs clear dependent results.
The definition applies throughout Tools, including reference transfers, power,
RF, emittance, magnets and Exciter. Copied reference data use Ek_AMeV for
A>0 or Ek_MeV for A=0, with an explicit energy_normalization field.
The numerical solve_kinematics API takes normalized kinetic energy in eV,
but complete-particle total energy (eV) and momentum (eV/c) for inverse inputs.
Tracking APIs and their existing mass approximations are unchanged; match their
documented units and mass convention when transferring values.
Current, power and stored energy
The former separate average/instantaneous forward/reverse entries are consolidated into three physically distinct modes:
Current ↔ power: choose known current (mA), kinetic-energy transport power (kW), or particle rate (1/s), and a common average/instantaneous time basis. The known input is not repeated in results.
I=Ndot*abs(q)*eandP=Ndot*K[J]; for charged particlesP[kW]=I[mA]*D*Ek/abs(q)with Ek in AMeV for A>0 or MeV for A=0 (D=max(A,1)). Circumference is unnecessary. Only particle-rate input works for neutral current/power conversion. A supplied peak is allowed; an average alone does not determine a peak. At zero Ek, power cannot uniquely determine current.Pulsed beam: real particles per pulse and actual extraction/repetition frequency give average current, average power and kinetic energy per pulse. Optional duration gives pulse-averaged current/power. These are peaks only for flat pulses; duration times repetition frequency must not exceed one.
Stored/circulating beam: total real particles and circumference give
f0=beta*c/C, period,I=N*abs(q)*e*f0and stored kinetic energyN*K[J]. Circulating current is not target power: the same particles circulate rather than being extracted every turn. Use pulsed delivery for actual extraction.
Zero current or count is valid. Power excludes rest energy and electrical wall-plug consumption. Instantaneous current, Ek and power must refer to the same cross section and instant; for a spread, use flux-weighted kinetic energy.
Reference inputs and exports
RF bucket, emittance, magnets and Exciter have independent reference particle and Ek inputs. Read beam calculator copies a valid particle/species and Ek as an explicit snapshot. Invalid source inputs do not replace the destination. RF needs mass, charge and energy for its slip factor, bucket height and frequencies. Emittance needs relativistic beta*gamma for normalization; magnets need rigidity and/or speed. Exciter uses speed for arrival times and tune conversion, and rigidity for its optional voltage/kick-angle converter. Formula references describe each approximation.
Plots export SVG/PNG/PDF and CSV with explicit column units. Emittance and Exciter place parameters and results together in the right vertical scrolling column. The plot remains visible on the left. Formula windows list the local catalog path, clickable official source URLs, and the shared per-nucleon/per-particle normalization equations.
Tune diagram
The condition is m*Qx+n*Qy=l with integer coefficients and order
abs(m)+abs(n); m and n cannot both be zero. Full tune ranges may cross
integers or include negative values. Enable orders 1–12 independently and
filter single-plane, sum or difference resonances. Difference lines are
dashed. Custom lines have separate visibility and removal controls.
Coincident lines are reduced using the full triple (m,n,l), assigned to their
lowest geometric order, and drawn once. 2*Qx=1 remains second order;
2*Qx=2 is assigned to first order. Turning off a low order also removes its
coincident higher-order representations. Excessive enumeration is rejected
with a request to narrow the ranges or selected orders.
The default ranges are 9–10 on both axes, with one unnamed point, (9.47, 9.43). The plot fills the left area. The right pane holds the ranges and Working points / Resonance lines tabs; drag the splitter to adjust their widths. Double-click table cells to edit names and coordinates; select a row to change its color and marker below the table. Toggle visibility or add/remove rows; new names are blank. Names are optional, and whitespace-only names are treated as blank. Visible points with nonempty names appear in a compact legend inside the upper-right corner of the plot, using their own colors and markers. Names are not written beside the points. Unnamed points remain visible and selectable; hidden and out-of-range points do not enter the legend. The resonance-order legend remains above the plot. Hover/select a point to see coordinates. Out-of-range points are counted in the status text. The Matplotlib toolbar provides zoom, pan and home. Export plot saves SVG, PNG or PDF with the current theme and view.
Paste accepts CSV or tab-separated rows; Import CSV appends UTF-8
CSV/TSV. Columns are Qx,Qy or name,Qx,Qy[,color,marker], with optional
headers. Two-column rows receive blank names; an empty name column is also valid.
Markers are o, s, ^, D or +. Invalid imports append
no rows. Export CSV includes all points, including hidden ones, with names,
coordinates, colors and markers, preserving blank names. Visibility is a local presentation choice.
The geometry does not calculate resonance strength or establish beam stability.
RF bucket
The navigation label is RF bucket 绘制. Enter V, harmonic h, circumference C, effective synchronous phase phi_s, and either gamma_t or eta. The reference particle is retained. In this section E_r=E/D=m0*c²/D+Ek is in eV and q_r=abs(q)/D, with D=max(A,1). Defaults: 100 kV, h=4, C=100 m, phi_s=0 and gamma_t=6.
These signs follow PASS’s small-deviation RF and longitudinal drift convention.
For a frozen single component, evaluate the physical waveform phase
theta(t_s)=2*pi*integral(f dt)+phase(t_s) at the selected synchronous event.
Use phi_s=theta(t_s) when signed q*V>0, or add pi when q*V<0;
the tool uses the positive voltage magnitude and absolute charge. Reduce modulo
2*pi. The reference event need not be the measured bunch centroid. Nominal
z_center is grouping metadata and adds no physical phase. RF h is independent
of the Injection grouping harmonic. Stability requires eta*cos(phi_s)<0; for positive
eta a stable phase is 180 degrees. Zero charge, V, Ek or eta is rejected.
The positive Hamiltonian is H=pi*h*abs(eta)*delta²+U(theta), theta=phi-phi_s,
with U=sign(eta)*q_r*V/(beta²*E_r)*(cos(phi_s+theta)-cos(phi_s)+theta*sin(phi_s)).
The lower adjacent saddle defines the separatrix. Inner contours and turning
points are solved numerically. Show phase or z_rel horizontally, delta or delta_E
vertically; delta_E≈beta²*E_r*delta. The result tab gives half-heights, full
widths, area, Qs, fs, revolution/RF frequencies and energy gain per turn.
For A>0, energy heights and plots show ΔE/A (MeV), gains are per nucleon,
and bucket area uses eV s per nucleon. For A=0 these are per-particle quantities
in MeV and eV s. CSV energy columns explicitly use eV_per_nucleon or
eV_per_particle. The numeric core retains complete-particle energies,
divided by D at the display/export boundary.
This is a frozen, single-harmonic, small-delta smooth model. It excludes collective
fields, radiation, multi-harmonic RF and capture ramps. Heights with |delta|>=1
are rejected. It does not replace tracking. Background:
CERN longitudinal beam dynamics.
Phase-space plotting and emittance calculation
The tool 相空间绘制及发射度计算 starts with one independent parameter page. Use ＋ to add a page or 复制当前页 to copy parameters, centroids, and visibility settings. A copy receives a new color; nonblank legend names gain a “副本” suffix, while blank names remain blank. Pages can be removed, but at least one remains. Page IDs remain stable after deletion. All pages share the reference particle and energy at the top. Switching tabs changes only the editor; enabled curves from all pages remain overlaid on one plot. No combined-beam emittance is calculated.
Each page enables 绘制相空间 (draw phase space) by default and disables 绘制投影椭圆（含色散） (draw projected ellipse with dispersion) by default. The latter also requires the page’s draw switch. Hidden pages still calculate results. Pages receive different editable colors; betatron curves are solid and projected curves dashed. The toolbar’s 显示图例 (show legend) switch defaults to enabled. Each curve has its own editable name. Empty or whitespace-only names omit that legend entry without hiding the curve; no legend box appears when no entries remain. Tab labels are independent of legend names. Centroids x₀ (mm), x′₀ (mrad) default to zero and translate both curves without changing centered RMS statistics, covariance, emittance, or Twiss parameters.
Each page keeps parameters and results in the same scrolling column. Invalid input clears only that
page’s results and curves, with an error marker on its tab; other valid pages continue to plot.
Image export preserves the displayed curves and legend. CSV exports both curves from every valid page,
including hidden curves, with page_id, page_name, legend names, and
draw_betatron / draw_projected visibility flags. Coordinates include centroid offsets and use m and rad.
Invalid pages have no exported curve rows. When at least one page is valid, copied results include
all page inputs, valid results, and error reasons for invalid pages.
The unit π·mm·mrad uses the agreed area convention: input 1 means a geometric
RMS emittance of 1e-6 m rad in the formulas, with ellipse area pi*1e-6 m rad for
n=1. Do not multiply the input by pi again. No four-RMS factor is implied.
Normalization is epsilon_n=beta_rel*gamma_rel*epsilon with the same convention.
Twiss labels are Twiss beta, Twiss alpha, Twiss gamma. Gamma is in the parameter block. In alpha/beta mode it updates automatically; beta/gamma mode solves alpha and requires a positive/negative branch choice:
Require beta>0 and beta*gamma>=1 for inversion. Gamma and beta cannot determine the sign of alpha. These Twiss quantities are distinct from relativistic factors.
The one-plane model assumes uncorrelated betatron coordinates and momentum spread:
The projected ellipse includes dispersive offsets of particles with different
momenta; its emittance is sqrt(det Sigma). At D=Dprime=0 it equals the betatron
ellipse. Cov is the average product of centered x and xprime, indicating their
joint tilt/correlation; r=Cov/(sigma_x*sigma_xprime) is dimensionless and lies
between -1 and 1 when defined. These do not represent another beam species.
Cov has units mm mrad, without an area-convention pi prefix.
Beam-size inversion subtracts the dispersion variance; an input below
abs(D)*sigma_delta is inconsistent. At Ek=0 normalized-to-geometric inversion
is underdetermined. An n-sigma covariance ellipse has area pi*n²*epsilon; for a
nondegenerate 2D Gaussian it contains 1-exp(-n²/2), about 39.35% at n=1.
The known-quantity selector retains geometric emittance, normalized emittance, and projected σx inputs, and adds 投影 RMS 与相关性 → ε、Twiss (projected RMS and correlation): enter σx, σxprime, and either r or Cov(x,xprime). These inputs are projected, centered statistics including dispersion. The calculation constructs the projected covariance and subtracts the dispersive contribution:
Both the projected matrix and B must be positive semidefinite; otherwise the inputs are inconsistent.
Correlation mode requires positive RMS values and |r|≤1. A zero RMS requires covariance mode with Cov=0,
and the resulting r is displayed as undefined. At epsilon=0 the emittance and available statistics remain
visible, inferred Twiss values are undefined, and the contour can degenerate to a line or point.
The original emittance/beam-size modes retain their supplied Twiss values.
Results distinguish betatron and projected RMS values and emittances; projected results remain available
even when their curve is hidden. The reported Twiss parameters describe the betatron covariance.
Magnet conversion
Choose particle-derived or directly entered signed B*rho=p/(q*e), positive length L, and one known magnet quantity. Direct mode ignores disabled reference inputs. Fields and strengths retain signs; beta/gamma normalization is not used for the magnet coefficients.
Dipole:
k0=B/(Bρ)=1/rho,theta=K0L=k0*L,integral B dl=(Bρ)*theta. L is effective arc length. Zero field has no finite radius.Quadrupole:
k1=G/(Bρ),K1L=k1*L,fx≈1/K1L,fy≈-1/K1L. G=dBy/dx. Focal lengths are thin-lens estimates.Sextupole and octupole: n=2 or 3,
G_n=d^n By/dx^n,k_n=G_n/(Bρ),K_nL=k_n*L. At (x=r,y=0),By=G_n*r^n/n!. Enter derivative, normalized strength, integrated strength/derivative, or field at a chosen reference radius. The 2! and 3! factors match PASS’s actual kicks.Solenoid:
Ks=Bz/(Bρ),kappa=Ks/2,theta=kappa*Landintegral Bz dl=(Bρ)*Ks*L. The reference paraxial Larmor parameter has the sign used by PASS’s rotation map. Focusing is kappa²;f≈1/(kappa²*L)is only a weak thin-lens estimate, not an exact finite-length focal distance.
Quadrupole, sextupole, octupole and solenoid default to normalized k1, k2, k3
and Ks respectively. For the three multipoles, enter the pole radius in mm:
Bp[Gauss]=10000*(Bρ)*k_n*r[m]^n/n! with n=1,2,3. The signed ideal pole field
and its inverse are supported; its magnitude is abs(Bp). The solenoid instead
shows axial Bz[Gauss]=10000*(Bρ)*Ks. Bore radius and Ks alone do not determine
an iron pole-face field; magnetic-circuit geometry and a field model are needed.
No fringe fields, saturation, hysteresis or coil-current calibration is included.
Exciter calculation and plotting
The page implements the four modes in PASS/commands/element/exciter.py:
single_fm, single_fm_am, dual_fm, dual_fm_am. Inputs include signed nominal kick
angle in rad, circumference, tune or frequency, full sweep width,
period, dual sweep offset (default 0.5 of a period) and AM parameters. Switching frequency input
mode preserves the physical center frequency and width. The default is tune mode.
Parameters use flat sections for reference beam, waveform, AM and sampling.
Angle inputs, numeric results, plot axes and summaries use radians in scientific
notation such as 1e-6.
No nominal bunch-slot offset is added and no z folding is performed.
The waveform uses \(u=t_{arrive}-t_{0,start}\); both DDS phases start at zero,
and arrivals before startup have zero signal. Only the sweep position is reduced
modulo its period; phase remains continuous. Reversing the input angle reverses
the kick, while envelopes and spectra remain magnitudes. Zero input angle gives
zero impulse. Single FM
uses phi=2*pi*fc*u+pi*df*tau*(tau-T)/T, with tau=u % T. Dual FM sums
two DDS signals with independently integrated phases. Each traverses the full
sweep width; DDS1 leads DDS2 by the selected sweep offset, rather than a fixed
sine phase difference. Non-half-period offsets display a warning. One kick-angle
setting supplies the common amplitude of both DDS signals; there are no separate
channel amplitudes or automatic division by two. Thus the dual signal has
a peak bound of \(2|\theta_0|\) before AM.
The formula window lists the frequency, phase integral and AM equations.
The selected z_rel shifts the arrival time used by both FM and AM. Preview
and tracking apply the configured angle directly as the normalized transverse
momentum amplitude; see Exciter. Angle units use the paraxial
reference-particle approximation \(\Delta u'\simeq\Delta p_u\). There is no
particle velocity correction or automatic amplitude rescaling with beam energy.
AM is evaluated continuously at \(u=t_{arrive}-t_{0,start}\) and normalized by the fixed revolution frequency at startup. It diverges at \(u=t_{ext}\), so all sampled particle times in an AM plot must be below that limit. The fixed-parameter preview plots the external signal, not beam response, losses or emittance growth. Optional turn markers evaluate arrival-phase sampling separately. Views include kick/envelope, DDS frequencies, AM factor and a one-sided Hann-window amplitude spectrum. The DDS1/DDS2 labels and CSV columns preserve channel identities when frequencies cross.
Numeric results include base kick, sampled peak/RMS, frequencies, sampling rate and frequency-bin spacing. At least 24 samples per bounded smooth frequency cycle are used, with a 200000-point cap; overly long high-frequency windows are rejected. Sweep frequency jumps preserve phase and can still broaden the spectrum. FFT bin spacing is 1/window duration; a sampled peak is not a global analytic bound. Waveform CSV columns use seconds, radians and Hz; spectrum CSV uses frequency_Hz and kick_amplitude_rad. Parameters/results share a vertical scrolling column and plots support the normal image/vector exports.
Voltage and kick-angle conversion
The Voltage conversion… (电压换算…) button opens a separate Voltage ↔ kick angle (电压 ↔ 踢角) window with both voltage and kick-angle inputs visible. Enter a voltage and press Enter to calculate the angle, or enter an angle and press Enter to calculate the voltage. Both directions use the main page’s selected reference particle and kinetic energy, gap d in mm, and effective plate length L in metres. Changing the gap, plate length or reference beam recalculates the angle from the current voltage. Only submitting the angle input calculates voltage from angle. Voltage V is the signed peak interplate voltage difference in volts; kick angle is signed and measured in radians. For a uniform transverse field, the reference-particle estimate is:
Use metres for d in these equations. \(B\rho\) is the positive rigidity magnitude, so charge sign is included explicitly. Positive V deflects positive charges in the selected positive transverse direction. Reversing charge or voltage reverses the result; zero V or L gives zero angle. The same expression applies to proton and ion reference particles because rigidity already contains the charge magnitude.
The inverse calculation is:
It requires \(L>0\): a zero-length plate gives zero angle in the forward
calculation, so voltage cannot be determined uniquely from that angle.
The window shows voltage, angle, electric field and transit time. Pressing Enter
only performs the conversion; it neither copies the angle to the main page nor
closes the window. Fill base kick angle (填入基准踢角) copies the current angle to the waveform’s angle input;
changing hardware or reference inputs later does not overwrite that input.
Copy the chosen result to the main Exciter configuration’s Kick angle (rad).
The element itself has no voltage, gap or length parameters.
This conversion assumes a paraxial reference particle and little waveform variation during passage through the electrodes (\(\omega L/v_s\ll1\) for a sinusoid). It is a nominal reference conversion, not a finite-length field tracking model. Migrating the old voltage-based input preserves its reference coefficient at the selected energy, not its former per-particle velocity factor or energy-dependent amplitude.
Data format conversion
Open or drop OMC3 SDDS, HDF5, CSV or TFS, select data, preview, then Save as.
Sources remain read-only. Supported directions are OMC3 SDDS ↔ CSV/TFS,
HDF5 ↔ CSV/TFS, and CSV ↔ TFS. Editing and direct SDDS ↔ HDF5 conversion are
outside the scope. Install the GUI extra or, for scripts only,
python -m pip install "pass-sim[conversion]" for PyLHC sdds and
turn-by-turn support. When installing from a GitHub clone or extracted source
archive, use python -m pip install --editable ".[conversion]" from the directory
containing pyproject.toml.
SDDS support is specifically the OMC3 LHC/TbT SDDS1 array layout, read through
PyLHC sdds. turn_by_turn is the Python reader used by OMC3, not another
file format. Other SDDS layouts, SPS-specific readers and legacy ASCII TbT files
are outside this converter’s scope. Each exported row contains BPM,
BUNCH, TURN and the selected X and/or Y values. Select BPMs on
the left, bunches and a turn interval on the right. Identifier columns are
always retained. Turn and row indices start at 0; stops are exclusive.
Row ranges and value filters apply after the BPM/bunch/turn selection.
The usual controls show bunches, turn range, X/Y and output format. Row filters, column types and parameter selection are under the initially collapsed Advanced options. Active advanced selections remain effective when collapsed and are marked. BPM search only changes visibility; Select visible and Deselect visible affect the current search results and retain hidden choices. The preview summary displays selected counts, declared units, acquisition-time retention and turn renumbering; absent units are explicitly shown as undeclared.
To convert CSV/TFS back, map its columns to BPM, BUNCH, TURN, X
and Y. Both planes and a complete BPM × bunch × consecutive-turn grid
are required. Duplicate samples, missing combinations and gaps in turns are
rejected. Output uses binary SDDS1, preserves float32/float64 position precision
and is checked with turn_by_turn.read_tbt(..., datatype="lhc").
Turns are renumbered from 0; a missing acquisition timestamp becomes
acqStamp=0 with a notice. BPM names and string parameters must be ASCII.
Extra SDDS arrays are listed as excluded; no unit or coordinate conversion is
performed and missing units are not inferred.
GUI preview checks the entire selection for return to OMC3 SDDS, including rows beyond the 500-row display. An incomplete table can still be saved as CSV/TFS; invalid CSV/TFS input disables SDDS saving and displays the reason. SDDS checking scans selected samples in bounded blocks; CSV/TFS checking uses the whole table in memory. These are format/structure checks, not an OMC3 physics analysis.
Preview displays at most 500 rows without limiting export. SDDS arrays and
CSV/TFS inputs are loaded into memory; SDDS table export uses bounded blocks.
HDF5 reads are bounded and require explicit dataset selection: equal-length
1-D columns, a 2-D matrix or plane, or a long table of grid points. For a PASS
(slice, y, x) field, choose Long table, slice 0,:,: and coordinate
paths /slice_id,/y,/x to export the first slice. Jobs can be cancelled.
CSV can include a content-checked .metadata.json sidecar for units, types
and parameters (including the exact acquisition timestamp). Keep it alongside
the CSV for a round trip. TFS stores compatible headers plus PASS metadata.
HDF5 output uses /table/<column>; arbitrary source hierarchy is not recreated.
Converted ParticleMonitor selections are ordinary tables marked Layout="table";
SourceLayout retains the original layout. These selected tables are read
as generic tables. For spectral analysis of a TFS long-table export, select trajectory
rows (record=1) and one particle ID before conversion.
Changing selections requires another preview. Source-change checks also include
the CSV metadata sidecar. Overwriting outputs needs
confirmation, and the source cannot be overwritten. Multi-file publication is
not atomic; cancellation can leave already completed output files.
Qt-independent functions live in PASS.tool.data_conversion:
inspect_file, preview_file, convert_sdds and convert_hdf5.
For example, convert_sdds("a.sdds", "a.csv", DataSelection(bpms=["BPM.1"], turns=(0, 100)))
exports the first 100 turns of BPM.1 for all bunches; convert_sdds("a.csv", "b.sdds")
reconstructs OMC3 SDDS from the five standard columns, and
convert_hdf5("a.csv", "a.h5") creates an HDF5 table.
Custom reverse mappings use DataSelection(tbt_columns={"BPM": "name", "BUNCH": "bunch", "TURN": "turn", "X": "x", "Y": "y"}).
Calls return output paths, row counts and notices; overwrite defaults to false.
Scripts can use preview_file(path, selection, check_sdds=True) to receive
the complete-selection result in sdds_check while limiting displayed rows.
Wake data import
Choose Import wake… in the conversion tool to prepare a canonical temporal wake TFS. Select the source file and component, map the numeric columns, and declare the source axis, units, signs, normalization and reference beta. For a file with an ordinary text header, set the number of rows to skip. Preview the normalized data and its validation messages, then save one component per TFS. WakeField tracking accepts these canonical TFS files only; external table interpretation stays in the importer. Changing the import settings or source requires a new preview.
For distance data, choose whether the source coordinate means
beta_c_tau (\(s=\beta_{\mathrm{ref}}c\tau\)) or c_tau
(\(s=c\tau\)). The default is beta_c_tau. Switching components with
the same spatial order preserves a custom unit. Changing the spatial order
or length normalization displays a reminder to check the unit instead of
silently replacing a user-specified scale.
Name reusable import settings with Import preset name, then choose Save preset… or Load preset…. A versioned JSON preset stores its name and complete import options, including column mapping and physical conventions. It does not store a source path or source hash. Loading a preset requires a new preview of the selected source before export. TFS review presets store only the format and reconstruction choice; their physical metadata is always read from the selected TFS file.
Select an existing canonical TFS to review its declared metadata and curve with its physical metadata read-only; this review does not export another file. Spectrum TFS review shows both real and imaginary impedance and lets you choose the tracking model’s reconstruction method. The preview of a large table retains endpoints and extrema instead of taking evenly spaced rows; the summary uses the complete table for the peak magnitude, tail-to-peak ratio and minimum/maximum spacing. Display reduction does not change exported samples.
After a successful export or TFS review, Copy component JSON copies the
fragment shown in the read-only Component configuration tab. It includes
the file model and explicit fixed velocity, plus spatial or reconstruction
settings where needed. Add it to a group’s Components list after checking
the file path and reference speed; copying does not modify the current simulation.
This dedicated import applies the wake conventions and preserves the original sample locations after unit/direction conversion. The ordinary Save as TFS route preserves general table data and does not infer wake physics. Delay is not converted to turns, and no resampling is performed. Supply the full zero-delay right limit, check a nonzero tail for truncation, and use the file at its declared reference speed. Finite-bunch wake potentials need separate deconvolution before point-charge wake import. See Canonical wake TFS and external conversion for the CSV example, command-line conversion, Python APIs and tracking configuration. External impedance-spectrum conversion is available through the command-line and Python APIs; the GUI imports time- or distance-domain point-charge wakes and reviews existing canonical wake or impedance TFS.