Table Of Contents

Previous topic

foundation module

Next topic

lattice module

This Page

bunch module

The bunch module contains the Bunch class and related classes.

Classes

class Analysis

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 Functions

Analysis(std::string const & filename, size_t maxTurn = 0)

~Analysis()

double get_betatron_averaged_tune(bool isHorizontal)

double get_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_t get_num_betatron_tune_found(bool isHorizontal)

void set_minimum_required_turn_Num(size_t n)

size_t get_minimum_required_turn_Num()

int get_num_turns()

int get_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)

class Bunch

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

Public Type

State enum

The 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 Functions

Bunch(Reference_particle const & reference_particle, int total_num, double real_num, Commxx_sptr comm_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_particle const & reference_particle, int total_num, double real_num, Commxx_sptr comm_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_particle const & reference_particle, int total_num, double real_num, Commxx_sptr comm_sptr, double z_period_length, int bucket_index = 0)

Bunch()

Default constructor for serialization use only.

Bunch(Bunch const & bunch)

Copy constructor.

Bunch & operator=(Bunch const & bunch)

Assignment constructor.

void set_particle_charge(int particle_charge)

Set the particle charge.

Parameters
  • particle_charge -

    in units of e.

void set_real_num(double real_num)

Set the number of real particles represented by the bunch.

Parameters
  • real_num -

    the new real number of particles

void set_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 Bunch and use the inject member.) The total number and real number for the bunch will not be correct until update_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

void update_total_num()

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

Requires comm_sptrunication.

void set_sort_period(int period)

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

Parameters
  • period -

void sort(int index)

Sort the particles.

Parameters
  • index -

    the particle index on which to sort

void periodic_sort(int index)

Sort the particles every sort period calls.

Parameters
  • index -

    the particle index on which to sort

void set_converter(Fixed_t_z_converter & converter)

Set the Fixed_t_z_converter class to be used when converting between fixed-t and fixed-z representations.

Parameters
  • converter -

    the converter class

void convert_to_state(State state)

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_particle const & get_reference_particle()

MArray2d_ref get_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_ref get_local_particles()

int get_particle_charge()

Get the particle charge in units of e.

double get_mass()

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

double get_real_num()

Get the real number of particles represented by the bunch.

double get_z_period_length()

Get the period length of the bunch.

bool is_z_periodic()

Is the bunch periodic?

int get_local_num()

Get the number of macroparticles stored on this processor.

int get_total_num()

Get the total number of macroparticles.

int get_sort_period()

Get the period for periodic_sort.

void set_bucket_index(int index)

int get_bucket_index()

State get_state()

Get the (fixed-t or fixed-z) state.

Commxx const & get_comm()

Get the communicator.

Commxx_sptr get_comm_sptr()

Get the communicator.

void inject(Bunch const & 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.

void check_pz2_positive()

template < class Archive >
void save(Archive & ar, const unsigned int version)

template < class Archive >
void load(Archive & ar, const unsigned int version)

~Bunch()

Public Static Attributes

const int x

const int xp

const int y

const int yp

const int z

const int zp

const int cdt

const int dpop

const int id

class Bunch_train

Public Functions

Bunch_train(Bunches const & bunches, double spacing)

Bunch_train(Bunches const & bunches, std::vector< double > const & spacings)

Bunch_train()

Commxx_sptr get_parent_comm_sptr()

size_t get_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 >
void serialize(Archive & ar, const unsigned int version)

~Bunch_train()

class Diagnostics

Diagnostics is an abstract base class for bunch diagnostics classes.

Public Functions

Diagnostics(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()

void set_bunch_sptr(Bunch_sptr bunch_sptr)

bool have_bunch()

void delete_write_helper_ptr()

Diagnostics_write_helper * new_write_helper_ptr()

bool have_write_helper()

Diagnostics_write_helper & get_write_helper()

Bunch & get_bunch()

bool is_serial()

Multiple serial diagnostics can be written to a single file.

void update()

Update the diagnostics.

void write()

Write the diagnostics to the file.

void update_and_write()

Update the diagnostics and write them to the file.

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

~Diagnostics()

class Diagnostics_basic

Diagnostics_basic provides the minimal set of statistical quantities to be calculated for a Bunch.

Public Functions

Diagnostics_basic(std::string const & filename, std::string const & local_dir = “”)

Create a Diagnostics_basic object.

Parameters
  • filename -

    filename for output

  • local_dir -

    local directory to use for temporary scratch

Diagnostics_basic()

bool is_serial()

Multiple serial diagnostics can be written to a single file.

The Diagnostics_basic class is serial.

void init_writers(Hdf5_file_sptr file_sptr)

void update()

Update the diagnostics.

double get_s_n()

Get the distance from the origin along the reference trajectory in meters.

int get_repetition()

Get the number of complete repetitions.

double get_s()

Get the total distance along the reference trajectory in meters.

int get_num_particles()

Get the total number of macroparticles in the bunch.

double get_real_num_particles()

Get the total number of real particles represented by the bunch.

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

The units are in Synergia units.

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

The units are in Synergia units.

const MArray1d get_min()

const MArray1d get_max()

void write()

Write the diagnostics to the file.

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

~Diagnostics_basic()

Public Static Attributes

const char name[]

class Diagnostics_bulk_track

Diagnostics_bulk_track records 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 Functions

Diagnostics_bulk_track(std::string const & filename, int num_tracks, int offset = 0, std::string const & local_dir = “”)

Create an empty Diagnostics_bulk_track object.

Parameters
  • bunch_sptr -

    the Bunch

  • filename -

    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()

bool is_serial()

Multiple serial diagnostics can be written to a single file.

The Diagnostics_bulk_track class is serial.

void update()

Update the diagnostics.

void write()

Write the diagnostics to the file.

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

~Diagnostics_bulk_track()

Public Static Attributes

const char name[]

class Track_status

Public Functions

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

Public Members

bool found

int last_index

int particle_id

class Diagnostics_full2

Diagnostics_full2 provides the full set of statistical quantities to be calculated for a Bunch up to the second moments.

Public Functions

Diagnostics_full2(std::string const & filename, std::string const & local_dir = “”)

Create a Diagnostics_full2 object.

Parameters
  • bunch -

    the Bunch

  • filename -

    filename for output

  • local_dir -

    local directory to use for temporary scratch

Diagnostics_full2()

void init_writers(Hdf5_file_sptr file_sptr)

bool is_serial()

Multiple serial diagnostics can be written to a single file.

The Diagnostics_full2 class is serial.

void update()

Update the diagnostics.

double get_s_n()

Get the distance from the origin along the reference trajectory in meters.

int get_repetition()

Get the number of complete repetitions.

double get_s()

Get the total distance along the reference trajectory in meters.

int get_num_particles()

Get the total number of macroparticles in the bunch.

double get_real_num_particles()

Get the total number of real particles represented by the bunch.

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

The units are in Synergia units.

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

The units are in Synergia units.

const MArray1d get_min()

const MArray1d get_max()

Get a 6x6 matrix of the second moments of the phase-space coordinates.

The units are Synergia units.

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

double get_emitx()

Get the horizontal emittance.

Currently reported in unnatural Synergia units.

double get_emity()

Get the vertical emittance.

Currently reported in unnatural Synergia units.

double get_emitz()

Get the longitudinal emittance.

Currently reported in unnatural Synergia units.

double get_emitxy()

Get the (4D) transverse emittance.

Currently reported in unnatural Synergia units.

double get_emitxyz()

Get the (6D) full emittance.

Currently reported in unnatural Synergia units.

void write()

Write the diagnostics to the file.

bool get_have_writers()

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

~Diagnostics_full2()

Public Static Attributes

const char name[]

class Diagnostics_particles

Diagnostics_particles dumps the state of particles in a bunch.

Public Functions

Diagnostics_particles(std::string const & filename, int min_particle_id = 0, int max_particle_id = 0, std::string const & local_dir = “”)

Create a Diagnostics_particles object.

Parameters
  • bunch_sptr -

    the Bunch

  • filename -

    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()

bool is_serial()

Multiple serial diagnostics can be written to a single file.

The Diagnostics_particles class is not serial.

void update()

Update the diagnostics.

void write()

Write the diagnostics to the file.

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

~Diagnostics_particles()

Public Static Attributes

const char name[]

class Diagnostics_reference_particle

Public Functions

Diagnostics_reference_particle(std::string const & filename, std::string const & local_dir = “”)

Create a Diagnostics_reference_particle object.

Parameters
  • bunch -

    the Bunch

  • filename -

    filename for output

  • local_dir -

    local directory to use for temporary scratch

Diagnostics_reference_particle()

bool is_serial()

Multiple serial diagnostics can be written to a single file.

The Diagnostics_reference_particle class is serial.

void init_writers(Hdf5_file_sptr file_sptr)

void update()

Update the diagnostics.

void write()

Write the diagnostics to the file.

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

~Diagnostics_reference_particle()

Public Static Attributes

const char name[]

class Diagnostics_track

Diagnostics_track records 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 Functions

Diagnostics_track(std::string const & filename, int particle_id, std::string const & local_dir = “”)

Create an empty Diagnostics_track object.

Parameters
  • bunch_sptr -

    the Bunch

  • filename -

    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()

bool is_serial()

Multiple serial diagnostics can be written to a single file.

The Diagnostics_track class is serial.

void update()

Update the diagnostics.

void write()

Write the diagnostics to the file.

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

~Diagnostics_track()

Public Static Attributes

const char name[]

class Fixed_t_z_alex

Public Functions

void from_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.

void from_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.

void from_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.

void from_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.

void from_t_lab_to_t_bunch(Bunch & bunch)

void from_t_bunch_to_t_lab(Bunch & bunch)

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

class Fixed_t_z_ballistic

Fixed_t_z_zeroth implements 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 Functions

void from_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.

void from_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.

void from_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.

void from_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.

void from_t_lab_to_t_bunch(Bunch & bunch)

void from_t_bunch_to_t_lab(Bunch & bunch)

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

class Fixed_t_z_converter

Fixed_t_z_converter is 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 Functions

void from_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.

void from_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.

void from_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.

void from_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.

void from_t_lab_to_t_bunch(Bunch & bunch)

void from_t_bunch_to_t_lab(Bunch & bunch)

template < class Archive >
void serialize(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()

class Fixed_t_z_synergia20

transformation as in the old synergia....

Public Functions

void from_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.

void from_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.

void from_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.

void from_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.

void from_t_lab_to_t_bunch(Bunch & bunch)

void from_t_bunch_to_t_lab(Bunch & bunch)

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

class Fixed_t_z_zeroth

Fixed_t_z_zeroth implements a fixed-t-fixed-z converter using the simplest approximation: longitudinal coordinates are transformed, but transverse coordinates are unaffected.

Public Functions

void from_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.

void from_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.

void from_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.

void from_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.

void from_t_lab_to_t_bunch(Bunch & bunch)

void from_t_bunch_to_t_lab(Bunch & bunch)

template < class Archive >
void serialize(Archive & ar, const unsigned int version)

Typedefs

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