7.67 touschek_scatter

• type: setup/action command.
• function: Simulate Touschek scattering process at each TSCATTER element based on Monte Carlo method. The local scattering rate is calculated by using Piwinski’s formula and from the Monte Carlo simulation. Scattered particles can be tracked through the entire beamline for one or more passes, and beam loss information is recorded.
• sequence: must follow run_setup and twiss_output.
• can use parallel resources (Pelegant)
• Command syntax, including use of equations and subcommands, is discussed in 7.2.
• notes:
  • A momentum aperture file is required previous using this command. It should contain momentum aperture at least at each TSCATTER element and can be obtained by running momentum_aperture command.
  • The simulation can be done for a Gaussian distributed beam or an arbitrary particle distribution given by histogram file(s) (See MHISTOGRAM).
  • When using histogram file as input, it should contain data at least at each TSCATTER element. This can be done by inserting a MHISTOGRAM element following each TSCATTER element. With lumped=1 option, a multi page SDDS file will be output automatically or you can combine individual output file into a multi page SDDS file before using this command.
  • The input particle distribution can be given in 3 ways: 2D(x-x’)+2D(y-y’)+2D(dt-dp); or 4D(x-x’-y-y’)+2D(dt-dp); or 6D(x-x’-y-y’-dt-dp); base on user’s choice. We recommend to use lower “order” histogram table if the original particle number which used to generate these table is not large enough.
  • The emit_*, emit_dp and sigma_s is always required for running the simulation (Used for Piwinski’s rate). Use closed value when simulate a non-Gaussian distributed bunch.

• charge — Bunch charge in Coulombs. May not be zero.
• frequency — Bunch repetition frequency in Hz. The product of the charge and frequency gives the average current in Amps.
• emit_x, emit_y — RMS emittance for the x and y planes. Ignored if RMS normalized emittance is nonzero.
• emit_nx, emit_ny — RMS normalized emittance for the x and y planes.
• sigma_dp, sigma_s — Rms fractional momentum spread, σ_δ, and rms bunch length.
• distribution_cutoff — The number of sigmas to use in each plane for Gaussian beam.
• Momentum_Aperture — Input file containing the estimated momentum aperture at each TSCATTER element. This can be obtained from the momentum_aperture command in a separate run. (If using the parallel version to obtain the momentum aperture, it will be necessary to use output_mode=0 or else reorganize the data if output_mode\neq 0. Also, it will be necessary to use sddssort to sort the data by the s column.)
• Momentum_Aperture_scale — This value times the aperture value from Momentum_Aperture file sets up the limit on δ_m in the simulation. Only particles that have δ > δ_m will be kept for tracking. And the scattering rate is calculated at this value.
• XDist, YDist, ZDist — Input filename of 2D histogram table of X, Y, and Z plane. X and Y are ignored when TranDist or FullDist is present.
• TranDist — Input file name of the 4D histogram table of transverse plane. Has to be used together with ZDist.
• FullDist — Input file name of the 6D histogram table. If present, all other tables are ignored.
• bunch — The (incomplete) name of an SDDS file to which the phase-space coordinates of the simulated scattered particles are to be written. Recommended value: “%s-%03ld.bun”. If “%03ld” or the equivalent is not provided then only the last simulated bunch is kept (one bunch for one TSCATTER element).
• loss — The (incomplete) name of an SDDS file to which the original and final phase-space coordinates of the lost simulated scattered particles are to be written. Recommended value: “%s-%03ld.los”. Used together with do_track = 1.
• distribution — The (incomplete) name of an SDDS file to which the one-dimensional histogram of simulated scattered particles are to be written. Recommended value: “%s-%03ld.dis”
• initial — The (incomplete) name of an SDDS file to which the one dimension histogram of simulated particles before scattering are to be written. Recommended value: “%s-%03ld.ini”
• output — The (incomplete) name of an SDDS file. The average loss rate (particles per second) over a step size of sbin_step at location s is written to this file. Recommended value: “%s-%03ld.out”
• sbin_step — Bin size for loss rate summary output to the output file.
• nbins — Number of bins used for the distribution and initial table.
• n_simulated — The total number of simulated scattered particles with δ > δ_m. Choosing too small a value will cause unreliable results. Note: use an integer number here. A number such as 5E6 sometimes will cause you trouble.
• ignored_portion — Fraction of the total scattering rate ignored in tracking. Using this parameter will greatly increase the tracking speed. For example, if the total loss rate is 50% of the total scattering rate, then ignoring for tracking purposes 5% (0.05) of the scattered particles will cause a ~10% error, but the simulation is greatly sped up.
• i_start, i_end — The simulation will be done from the i_start^th to the i_end^th TSCATTER element along the beamline.
• do_track — If non-zero, scattered particles will be tracked from their generation location for n_passes (given by run_control). If non-zero, the run_control command must proceed the |touschek_scatter|command. The loss property can be analysed using output or loss.
• match_position_only — If non-zero, then matching of the momentum aperture data to the lattice is done using the position data only (s column), rather than the element names. Can be helpful if errors appear about files ending prematurely or data not matching.
• overwrite_files — If non-zero, then output files will be overwritten. If set to zero, then when output files are found, the corresponding computations are skipped. This can be used to restart a Touschek scattering run, provided the output filenames are index (e.g., of the form “%s-%03ld.los” rather than “%s.los”.)

Note: If using Pelegant to compute the momentum aperture with output_mode=1, it is necessary to first run the script reorganizeMmap to put the data into the form needed by touschekLifetime.