11.13 sddsanalyzebeam

• description: sddsanalyzebeam analyzes a beam of macro-particles and produces an SDDS file containing beam moments, emittances, equivalent beta functions, etc. The beam file is of the type written by elegant using the output field of the run_setup command, or the WATCH element.
• examples:

  sddsanalyzebeam run.out run.analysis

• synopsis:

  sddsanalyzebeam [-pipe=[input][,output]] [inputfile] [outputfile] [-nowarnings] [-correctedOnly] [-canonical] [-coupled]

• files:
  • inputfile — An SDDS file containing the columns x, xp, y, yp, t, and p, giving the six phase-space coordinates for a set of macroparticles. This file can be produced from elegant, for example, using the output field of the run_setup command, the bunch field of the bunched_beam command, or the WATCH element in coordinate mode.
  • outputfile — An SDDS file containing columns giving moments, emittances, equivalent Twiss parameters, and so on, for the macro-particles. Each row of this file corresponds to a page of the input file. The names and meanings of the columns are identical to what is used for elegant’s final output file from the run_setup command. The file from elegant, however, stores the results as parameters instead of columns; to convert outputfile to that convention, use the SDDS toolkit program sddsexpand.
• switches:
  • pipe — The standard SDDS Toolkit pipe option.
  • nowarnings — Suppressses warning messages.
  • correctedOnly — If given, only the “corrected” twiss parameters and emittances are computed and output. The corrected twiss parameters have the dispersive component subtracted. Normally, these are computed but given names like betacx, ecx, etc. whereas the uncorrected values are betax, ex, etc. The corrected parameters are the correct ones to match a beamline to, since they have the dispersive and mono-energetic terms properly separated. The uncorrected values are more relevant if the dispersion is spurious (i.e., uncorrected or due to something like CSR that doesn’t admit of correction).
  • -canonical — If given, all computations are performed using canonical momenta q_x = p_x∕p₀ = x^′(1 + δ)∕ etc.
  • -coupled — If given, a fully coupled analysis of the beam is performed and additional columns giving the coupled (eigen-)emittances and coupled lattice functions are written to the output file. The analysis is a 6×6 eigen-analysis of the beam (sigma) matrix itself: the eigenvalues of ΣJ (with J the block-diagonal symplectic form on the (x,x^′), (y,y^′), and (s,δ) pairs) are ±iϵ_k, where the three invariant eigen-emittances ϵ₁,ϵ₂,ϵ₃ reduce to the ordinary x, y, and longitudinal emittances when the planes are uncoupled [1]. The longitudinal coordinate is taken as s = βct (m), and the per-mode lattice functions (β_x,k, α_x,k, γ_x,k, the vertical and longitudinal analogs, and the x–y cross terms) follow the same conventions as elegant’s coupled_twiss_output command (Section 7.24), so the results are directly comparable to the eigen-emittances ϵ₁,ϵ₂,ϵ₃ reported by moments_output (Section 7.49).
• author: M. Borland, ANL/APS.