The bunch module contains the Bunch class and related classes.

Read back the files produced by Diagnositics_particles and obtain some variable of interest.

Currently implemented: just the Betatron Tune, based on the so-called “particle” files.

Public FunctionsAnalysis(std::string const & filename, size_t maxTurn = 0)~Analysis()doubleget_betatron_averaged_tune(bool isHorizontal)doubleget_betatron_tune_spread(bool isHorizontal)std::vector< double >get_betatron_tunes(bool isHorizontal)std::vector< double >get_XCoords_forTunes(size_t selectedParticle)std::vector< double >get_YCoords_forTunes(size_t selectedParticle)size_tget_num_betatron_tune_found(bool isHorizontal)voidset_minimum_required_turn_Num(size_t n)size_tget_minimum_required_turn_Num()intget_num_turns()intget_num_part_first_bunch()std::vector< double >get_transverse_action_for_particle(bool isH, size_t selectedParticle, double alpha, double beta)std::vector< double >get_transverse_action_for_bunch(bool isH, size_t turnNumber, double alpha, double beta)

Represents a macroparticle bunch distributed across the processors in a comm_sptrunicator.

Public Type

State enumThe state of the bunch is captured at a fixed s (or z, longitudinal coordinate) or at a fixed time. In the former case, particles are found within a range of different time coordinates while in the later case particles position along the beam axis do vary. A change of state is accomplish via the fixed_t_z_converter class.

Values:

fixed_z= = 1-fixed_t= = 2-fixed_z_lab= = 1-fixed_t_bunch= = 2-fixed_t_lab= = 3-fixed_z_bunch= = 4-Public FunctionsBunch(Reference_particleconst & reference_particle, int total_num, double real_num,Commxx_sptrcomm_sptr)Constructor: Allocates memory for the particles and assigns particle ID’s, but does not fill the phase space values in any way.

To fill the bunch with particles, use the populate methods.

Parameters

reference_particle-the reference particle for the bunch.

total_num-the total number of macroparticles in the bunch

real_num-the number of real particles represented by the bunch.

bucket_index-the bucket number the bunch occupies, used for multi-bunch simulations

comm_sptr-the comm_sptrunicator.

Bunch(Reference_particleconst & reference_particle, int total_num, double real_num,Commxx_sptrcomm_sptr, int particle_charge)Constructor with 5-parameter signature Same as above, but having the flexibility to redefine the charge of a particle.

Parameters

reference_particle-the reference particle for the bunch.

total_num-the total number of macroparticles in the bunch

real_num-the number of real particles represented by the bunch.

comm_sptr-the comm_sptrunicator.

particle_charge-in units of e.

Bunch(Reference_particleconst & reference_particle, int total_num, double real_num,Commxx_sptrcomm_sptr, double z_period_length, int bucket_index = 0)Bunch()Default constructor for serialization use only.

Bunch(Bunchconst & bunch)Copy constructor.

Assignment constructor.

voidset_particle_charge(int particle_charge)Set the particle charge.

Parameters

particle_charge-in units of e.

voidset_real_num(double real_num)Set the number of real particles represented by the bunch.

Parameters

real_num-the new real number of particles

voidset_local_num(int local_num)Reduce (set) the number of particles on this processor.

The number of particles can only be lowered by this member function. (In order to add new particles, create another

Bunchand use the inject member.) The total number and real number for the bunch will not be correct untilupdate_total_num()is called. The real number will scale to reflect the change in the total number. n.b.: The only way to change the total number after the bunch has been created is to change the local numbers on each processor.

Parameters

local_num-the new number of particles on this processor

voidupdate_total_num()Update the total number and real number of particles after the local number has been changed.

Requires comm_sptrunication.

voidset_sort_period(int period)Set the period for periodic_sort and reset the counter Periods less than zero will prohibit sorting.

Parameters

period-voidsort(int index)Sort the particles.

Parameters

index-the particle index on which to sort

voidperiodic_sort(int index)Sort the particles every sort period calls.

Parameters

index-the particle index on which to sort

voidset_converter(Fixed_t_z_converter& converter)Set the

Fixed_t_z_converterclass to be used when converting between fixed-t and fixed-z representations.

Parameters

converter-the converter class

voidconvert_to_state(Statestate)Convert to (fixed-t or fixed-z) state if necessary.

Does nothing if the bunch is already in the requested state.

Parameters

state-convert to this state.

Reference_particle&get_reference_particle()Return the reference particle.

Reference_particleconst &get_reference_particle()MArray2d_refget_local_particles()Get the array containing the macroparticles on this processor.

The array has length (length,7), where length of the array may be larger local_num. The macroparticle state vectors are stored in array[0:local_num,0:6] and the macroparticle IDs are stored in array[0:local_num,6]. Use

get_local_num()to obtain local_num.Const_MArray2d_refget_local_particles()intget_particle_charge()Get the particle charge in units of e.

doubleget_mass()Get the particle mass in units GeV/c^2.

doubleget_real_num()Get the real number of particles represented by the bunch.

doubleget_z_period_length()Get the period length of the bunch.

boolis_z_periodic()Is the bunch periodic?

intget_local_num()Get the number of macroparticles stored on this processor.

intget_total_num()Get the total number of macroparticles.

intget_sort_period()Get the period for periodic_sort.

voidset_bucket_index(int index)intget_bucket_index()Stateget_state()Get the (fixed-t or fixed-z) state.

Commxxconst &get_comm()Get the communicator.

Commxx_sptrget_comm_sptr()Get the communicator.

voidinject(Bunchconst & bunch)Add a copy of the particles in bunch to the current bunch.

The injected bunch must have the same macroparticle weight, i.e., real_num/total_num. If the state vectors of the reference particles of the two bunches differ, the particles will be shifted accordingly.

voidcheck_pz2_positive()template < class Archive >voidsave(Archive & ar, const unsigned int version)template < class Archive >voidload(Archive & ar, const unsigned int version)~Bunch()Public Static Attributesconst int

xconst int

xpconst int

yconst int

ypconst int

zconst int

zpconst int

cdtconst int

dpopconst int

id

Public FunctionsBunch_train(Bunches const & bunches, double spacing)Bunch_train(Bunches const & bunches, std::vector< double > const & spacings)Bunch_train()Commxx_sptrget_parent_comm_sptr()size_tget_size()Bunches &get_bunches()std::vector< double > &get_spacings()std::vector< int > &get_proc_counts_for_impedance()std::vector< int > &get_proc_offsets_for_impedance()template < class Archive >voidserialize(Archive & ar, const unsigned int version)~Bunch_train()

Diagnosticsis an abstract base class for bunch diagnostics classes.Public FunctionsDiagnostics(std::string const & name, std::string const & filename, std::string const & local_dir = “”)Diagnostics()std::string const &get_filename()std::string const &get_local_dir()voidset_bunch_sptr(Bunch_sptrbunch_sptr)boolhave_bunch()voiddelete_write_helper_ptr()Diagnostics_write_helper*new_write_helper_ptr()boolhave_write_helper()Diagnostics_write_helper&get_write_helper()Bunch&get_bunch()boolis_serial()Multiple serial diagnostics can be written to a single file.

voidupdate()Update the diagnostics.

voidwrite()Write the diagnostics to the file.

voidupdate_and_write()Update the diagnostics and write them to the file.

template < class Archive >voidserialize(Archive & ar, const unsigned int version)~Diagnostics()

Diagnostics_basicprovides the minimal set of statistical quantities to be calculated for aBunch.Public FunctionsDiagnostics_basic(std::string const & filename, std::string const & local_dir = “”)Create a

Diagnostics_basicobject.

Parameters

filename-filename for output

local_dir-local directory to use for temporary scratch

Diagnostics_basic()boolis_serial()Multiple serial diagnostics can be written to a single file.

The

Diagnostics_basicclass is serial.voidinit_writers(Hdf5_file_sptrfile_sptr)voidupdate()Update the diagnostics.

doubleget_s_n()Get the distance from the origin along the reference trajectory in meters.

intget_repetition()Get the number of complete repetitions.

doubleget_s()Get the total distance along the reference trajectory in meters.

intget_num_particles()Get the total number of macroparticles in the bunch.

doubleget_real_num_particles()Get the total number of real particles represented by the bunch.

Const_MArray1d_refget_mean()Get a six-dimensional vector of the means of each phase-space coordinate.

The units are in Synergia units.

Const_MArray1d_refget_std()Get a six-dimensional vector of the standard deviations of each phase-space coordinate.

The units are in Synergia units.

constMArray1dget_min()constMArray1dget_max()voidwrite()Write the diagnostics to the file.

template < class Archive >voidserialize(Archive & ar, const unsigned int version)~Diagnostics_basic()Public Static Attributesconst char

name[]

Diagnostics_bulk_trackrecords the phase space coordinates of a multiple particles.Particles will only be tracked if they stay on the same processor. Lost particles that are somehow restored or particles not available when the first update is called will also not be tracked.

Public FunctionsDiagnostics_bulk_track(std::string const & filename, int num_tracks, int offset = 0, std::string const & local_dir = “”)Create an empty

Diagnostics_bulk_trackobject.

Parameters

bunch_sptr-the

Bunchfilename-the base name for file to write to (base names will have a numerical index inserted

num_tracks-the number of local particles to track

offset-id offset for first particle to track

local_dir-local directory to use for temporary scratch

Diagnostics_bulk_track()boolis_serial()Multiple serial diagnostics can be written to a single file.

The

Diagnostics_bulk_trackclass is serial.voidupdate()Update the diagnostics.

voidwrite()Write the diagnostics to the file.

template < class Archive >voidserialize(Archive & ar, const unsigned int version)~Diagnostics_bulk_track()Public Static Attributesconst char

name[]

classTrack_statusPublic Functionstemplate < class Archive >voidserialize(Archive & ar, const unsigned int version)Public Membersbool

foundint

last_indexint

particle_id

Diagnostics_full2provides the full set of statistical quantities to be calculated for aBunchup to the second moments.Public FunctionsDiagnostics_full2(std::string const & filename, std::string const & local_dir = “”)Create a

Diagnostics_full2object.

Parameters

bunch-the

Bunchfilename-filename for output

local_dir-local directory to use for temporary scratch

Diagnostics_full2()voidinit_writers(Hdf5_file_sptrfile_sptr)boolis_serial()Multiple serial diagnostics can be written to a single file.

The

Diagnostics_full2class is serial.voidupdate()Update the diagnostics.

doubleget_s_n()Get the distance from the origin along the reference trajectory in meters.

intget_repetition()Get the number of complete repetitions.

doubleget_s()Get the total distance along the reference trajectory in meters.

intget_num_particles()Get the total number of macroparticles in the bunch.

doubleget_real_num_particles()Get the total number of real particles represented by the bunch.

Const_MArray1d_refget_mean()Get a six-dimensional vector of the means of each phase-space coordinate.

The units are in Synergia units.

Const_MArray1d_refget_std()Get a six-dimensional vector of the standard deviations of each phase-space coordinate.

The units are in Synergia units.

constMArray1dget_min()constMArray1dget_max()Const_MArray2d_refget_mom2()Get a 6x6 matrix of the second moments of the phase-space coordinates.

The units are Synergia units.

Const_MArray2d_refget_corr()Get a 6x6 matrix of the correlation coefficients of the phase-space coordinates.

doubleget_emitx()Get the horizontal emittance.

Currently reported in unnatural Synergia units.

doubleget_emity()Get the vertical emittance.

Currently reported in unnatural Synergia units.

doubleget_emitz()Get the longitudinal emittance.

Currently reported in unnatural Synergia units.

doubleget_emitxy()Get the (4D) transverse emittance.

Currently reported in unnatural Synergia units.

doubleget_emitxyz()Get the (6D) full emittance.

Currently reported in unnatural Synergia units.

voidwrite()Write the diagnostics to the file.

boolget_have_writers()template < class Archive >voidserialize(Archive & ar, const unsigned int version)~Diagnostics_full2()Public Static Attributesconst char

name[]

Diagnostics_particlesdumps the state of particles in a bunch.Public FunctionsDiagnostics_particles(std::string const & filename, int min_particle_id = 0, int max_particle_id = 0, std::string const & local_dir = “”)Create a

Diagnostics_particlesobject.

Parameters

bunch_sptr-the

Bunchfilename-the base name for file to write to (base names will have a numerical index inserted

min_particle_id-the lowest particle id to write (defaults to 0)

max_particle_id-the highest particle id to write (0 indicates no limit, hence min,max = 0,0 writes all particles)

local_dir-local directory to use for temporary scratch

Diagnostics_particles()boolis_serial()Multiple serial diagnostics can be written to a single file.

The

Diagnostics_particlesclass is not serial.voidupdate()Update the diagnostics.

voidwrite()Write the diagnostics to the file.

template < class Archive >voidserialize(Archive & ar, const unsigned int version)~Diagnostics_particles()Public Static Attributesconst char

name[]

Public FunctionsDiagnostics_reference_particle(std::string const & filename, std::string const & local_dir = “”)Create a

Diagnostics_reference_particleobject.

Parameters

bunch-the

Bunchfilename-filename for output

local_dir-local directory to use for temporary scratch

Diagnostics_reference_particle()boolis_serial()Multiple serial diagnostics can be written to a single file.

The

Diagnostics_reference_particleclass is serial.voidinit_writers(Hdf5_file_sptrfile_sptr)voidupdate()Update the diagnostics.

voidwrite()Write the diagnostics to the file.

template < class Archive >voidserialize(Archive & ar, const unsigned int version)~Diagnostics_reference_particle()Public Static Attributesconst char

name[]

Diagnostics_trackrecords the phase space coordinates of a single particle.Particles will only be tracked if they stay on the same processor. Lost particles that are somehow restored or particles not available when the first update is called will also not be tracked.

Public FunctionsDiagnostics_track(std::string const & filename, int particle_id, std::string const & local_dir = “”)Create an empty

Diagnostics_trackobject.

Parameters

bunch_sptr-the

Bunchfilename-the base name for file to write to (base names will have a numerical index inserted

particle_id-the particle ID to track

local_dir-local directory to use for temporary scratch

Diagnostics_track()Diagnostics_write_helper*new_write_helper_ptr()boolis_serial()Multiple serial diagnostics can be written to a single file.

The

Diagnostics_trackclass is serial.voidupdate()Update the diagnostics.

voidwrite()Write the diagnostics to the file.

template < class Archive >voidserialize(Archive & ar, const unsigned int version)~Diagnostics_track()Public Static Attributesconst char

name[]

Public Functionsvoidfrom_z_lab_to_t_lab(Bunch& bunch)Convert from the fixed-z state in the accelerator frame to the fixed-t state in the accelerator frame.

voidfrom_t_lab_to_z_lab(Bunch& bunch)Convert from the fixed-t state in the accelerator frame to the fixed-z state in the accelerator frame.

voidfrom_z_lab_to_t_bunch(Bunch& bunch)Convert from the fixed-z state in the accelerator frame to the fixed-t state in the beam frame.

voidfrom_t_bunch_to_z_lab(Bunch& bunch)Convert from the fixed-t state in the beam frame to the fixed-z state in the accelerator frame.

voidfrom_t_lab_to_t_bunch(Bunch& bunch)voidfrom_t_bunch_to_t_lab(Bunch& bunch)template < class Archive >voidserialize(Archive & ar, const unsigned int version)

Fixed_t_z_zerothimplements a fixed-t-fixed-z converter using the ballistic approximation: longitudinal coordinates are transformed, then transverse coordinates are transformed using the ballistic approximation, i.e., as though the particles were traveling independently in free space.UNIMPLEMENTED

Public Functionsvoidfrom_z_lab_to_t_lab(Bunch& bunch)Convert from the fixed-z state in the accelerator frame to the fixed-t state in the accelerator frame.

voidfrom_t_lab_to_z_lab(Bunch& bunch)Convert from the fixed-t state in the accelerator frame to the fixed-z state in the accelerator frame.

voidfrom_z_lab_to_t_bunch(Bunch& bunch)Convert from the fixed-z state in the accelerator frame to the fixed-t state in the beam frame.

voidfrom_t_bunch_to_z_lab(Bunch& bunch)Convert from the fixed-t state in the beam frame to the fixed-z state in the accelerator frame.

voidfrom_t_lab_to_t_bunch(Bunch& bunch)voidfrom_t_bunch_to_t_lab(Bunch& bunch)template < class Archive >voidserialize(Archive & ar, const unsigned int version)

Fixed_t_z_converteris a virtual base class for converters between the bunch fixed-z representation and the bunch fixed-t representation.There are three converters one can choose:

Public Functionsvoidfrom_z_lab_to_t_lab(Bunch& bunch)Convert from the fixed-z state in the accelerator frame to the fixed-t state in the accelerator frame.

voidfrom_t_lab_to_z_lab(Bunch& bunch)Convert from the fixed-t state in the accelerator frame to the fixed-z state in the accelerator frame.

voidfrom_z_lab_to_t_bunch(Bunch& bunch)Convert from the fixed-z state in the accelerator frame to the fixed-t state in the beam frame.

voidfrom_t_bunch_to_z_lab(Bunch& bunch)Convert from the fixed-t state in the beam frame to the fixed-z state in the accelerator frame.

voidfrom_t_lab_to_t_bunch(Bunch& bunch)voidfrom_t_bunch_to_t_lab(Bunch& bunch)template < class Archive >voidserialize(Archive & ar, const unsigned int version)Convert from the fixed-t state to the fixed-z state.

Convert from the fixed-z state to the fixed-t state.

~Fixed_t_z_converter()

transformation as in the old synergia....

Public Functionsvoidfrom_z_lab_to_t_lab(Bunch& bunch)voidfrom_t_lab_to_z_lab(Bunch& bunch)voidfrom_z_lab_to_t_bunch(Bunch& bunch)Convert from the fixed-z state in the accelerator frame to the fixed-t state in the beam frame.

voidfrom_t_bunch_to_z_lab(Bunch& bunch)Convert from the fixed-t state in the beam frame to the fixed-z state in the accelerator frame.

voidfrom_t_lab_to_t_bunch(Bunch& bunch)voidfrom_t_bunch_to_t_lab(Bunch& bunch)template < class Archive >voidserialize(Archive & ar, const unsigned int version)

Fixed_t_z_zerothimplements a fixed-t-fixed-z converter using the simplest approximation: longitudinal coordinates are transformed, but transverse coordinates are unaffected.Public Functionsvoidfrom_z_lab_to_t_lab(Bunch& bunch)voidfrom_t_lab_to_z_lab(Bunch& bunch)Convert from the fixed-t state in the accelerator frameto the fixed-z state in the accelerator frame.

voidfrom_z_lab_to_t_bunch(Bunch& bunch)Convert from the fixed-z state in the accelerator frame to the fixed-t state in the beam frame.

voidfrom_t_bunch_to_z_lab(Bunch& bunch)Convert from the fixed-t state in the beam frame to the fixed-z state in the accelerator frame.

voidfrom_t_lab_to_t_bunch(Bunch& bunch)voidfrom_t_bunch_to_t_lab(Bunch& bunch)template < class Archive >voidserialize(Archive & ar, const unsigned int version)

typedef boost::shared_ptr< *Bunch* > **Bunch_sptr**

typedef boost::shared_ptr< *Diagnostics_basic* > **Diagnostics_basic_sptr**

typedef boost::shared_ptr< *Diagnostics_bulk_track* > **Diagnostics_bulk_track_sptr**

typedef boost::shared_ptr< *Diagnostics_full2* > **Diagnostics_full2_sptr**

typedef boost::shared_ptr< *Diagnostics_particles* > **Diagnostics_particles_sptr**

typedef boost::shared_ptr< *Diagnostics_reference_particle* > **Diagnostics_reference_particle_sptr**

typedef boost::shared_ptr< *Diagnostics* > **Diagnostics_sptr**

typedef boost::shared_ptr< *Diagnostics_track* > **Diagnostics_track_sptr**