Certain collective-effects elements in elegant can operate under the assumption that the beam is organized into bunches. This includes the FRFMODE, FTRFMODE, LRWAKE, RFMODE, WAKE, TRFMODE, TRWAKE, ZLONGIT, and ZTRANSVERSE elements. At present, this behavior is only available when loading a beam from an external file using the sdds_beam command. A typical sequence is to run elegant once to generate a beam file using bunched_beam, then load that beam into a subsequent run.
This beam file may either contain the entire beam (all the bunches) or it may contain a single bunch. In the latter case, the single bunch must be duplicated using the n_duplicates and duplicate_stagger parameters of sdds_beam. Otherwise, in the beam-generation run, the run_control command must be used to specify both the number of bunches (using n_steps) and the bunch frequency (using bunch_frequency). The beamline for this run would typically consist simply of a zero-length drift space, so that the output file from the run_setup command contains the coordinates for each bunch as generated, with no modifications. Once the beam is generated, it can be used as the input file for sdds_beam with track_pages_separately=0 and use_bunched_mode=1.
For those who prepare beams using other programs, it may be helpful to understand how the organization of the beam into bunches is specified. The relevant data from the beam file are the values in the IDSlotsPerBunch parameter and particleID column. The particleID is generally a unique positive integer for each particle. When S =IDSlotsPerBunch is non-zero, the bunch index is computed as ⌊(I - 1)∕S⌋, where I is the particle ID. For example, with IDSlotsPerBunch=1000, particle IDs from 1 to 1000 would be in bunch 0, from 2001-3000 would be bunch 1, and so on. This mechanism allows specifying the bunch structure without adding columns to the beam file, and also handles particle loss automatically.
Note that although in the case of beams generated with bunched_beam the individual bunches appear in separate pages of the beam file, this is not necessary.