xboa
Public Member Functions | Static Public Attributes | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
Bunch Class Reference

Represents a bunch of particles. More...

Public Member Functions

def __init__
 Initialise to an empty bunch. More...
 
def __str__
 Return an abbreviated string like <Bunch of="" n="" hits>=""> More...
 
def __repr__
 Return a long string that contains data in every hit. More...
 
def __copy__
 Make a copy but use references to self's data. More...
 
def copy
 
def __deepcopy__
 Make a copy and copy self's data. More...
 
def deepcopy
 Make a copy and copy self's data. More...
 
def __len__
 Number of hits. More...
 
def __getitem__
 Called by subscript operator, returns the key^th hit in the bunch. More...
 
def __setitem__
 Called by subscript operator, sets the key^th hit in the bunch. More...
 
def __delitem__
 Called by remove method, deletes the key^th hit in the bunch. More...
 
def __del__
 Called by del. More...
 
def __eq__
 Return true if all hits in self are the same as all hits in target, and set_covariance_matrix data are the same. More...
 
def __ne__
 Return true if any hits in self are not the same as the corresponding hit in target. More...
 
def append
 Append a hit to Bunch self. More...
 
def new_from_hits
 Initialise from a list of hits, making a deepcopy of the hits (so allocating new memory for each hit) More...
 
def new_dict_from_read_builtin
 Create a dict of all bunches in a file using a built-in format. More...
 
def new_list_from_read_builtin
 Create a sorted list of all bunches in a file using a built-in format. More...
 
def new_from_read_builtin
 Initialise a bunch from a file using a built in format. More...
 
def new_from_read_user
 Initialise a bunch from a file using a user defined format. More...
 
def new_hit_shell
 Create a set of particles that sit on the shell of an ellipse in some arbitrary dimensional space. More...
 
def get_list_of_maus_dicts
 Get a list of maus_dicts from a maus_spill for a particular maus_type. More...
 
def read_maus_root_file
 Read hits from a maus ROOT file. More...
 
def read_maus_file
 Initialise a bunch from a MAUS file. More...
 
def read_g4mice_file
 Initialise a bunch from a g4mice file. More...
 
def setup_file
 Returns a file handle with special phrases and characters stripped. More...
 
def translate
 Translate all events in the bunch by dict_variables_values. More...
 
def abelian_transformation
 
def transform_to
 Perform a linear transformation on all particles in the bunch to get a bunch with covariance matrix similar to target_covariances. More...
 
def period_transformation
 Transform all hit's variable from a linear space to a periodic space with some frequency and offset. More...
 
def hits
 Returns the list of all hits in the bunch. More...
 
def get_hits
 Returns a list of all hits in the bunch with comparator(variable, value) == True By default comparator is equality operator, so returns a list of all hits in the bunch with variable == value. More...
 
def hit_equality
 Return True if all hits in self are the same as all hits in target. More...
 
def conditional_remove
 For when a cut is not good enough, remove hits from the bunch altogether if comparator(value, get([variable])) is False. More...
 
def standard_deviation
 Return a standard deviation, given by sum( (u-u_mean)**2 )**0.5 where u is the variable specified. More...
 
def moment
 Return a moment, sum( (u1 - u1_mean)*(u2-u2_mean)*(etc)) where u is a set of Hit get_variables indexed by variable_list. More...
 
def mean
 Return dict of variables to means. More...
 
def covariance_matrix
 Return covariance matrix of variables. More...
 
def set_covariance_matrix
 Choose whether to use an internal covariance matrix for calculations. More...
 
def covariances_set
 If internal covariances are set by set_covariance_matrix, return True; else return False. More...
 
def means_set
 If means are set by set_covariance_matrix, return True; else return False. More...
 
def bunch_weight
 Return statistical weight of all hits in the bunch. More...
 
def clear_local_weights
 Set local_weight of all hits in the bunch to 1. More...
 
def clear_global_weights
 Set global_weight of all hits in the bunch to 1. More...
 
def clear_weights
 Set global_weight and local_weight of all hits in the bunch to 1. More...
 
def cut
 Set weight of hits in the bunch to 0 if comparator(value, get([variable])) is False. More...
 
def transmission_cut
 Set weight of hits in the bunch to 0 if no events can be found in test_bunch with the same test_variable. More...
 
def get_beta
 Return the bunch beta function, defined by. More...
 
def get_gamma
 Return the bunch beta function, defined by. More...
 
def get_alpha
 Return the bunch alpha function, defined by. More...
 
def get_dispersion
 Return the bunch dispersion D in axis q, defined by. More...
 
def get_dispersion_rsquared
 Return a special bunch dispersion defined by. More...
 
def get_dispersion_prime
 Return the bunch dispersion prime D in axis q, defined by. More...
 
def get_decoupled_emittance
 Reserved for future development. More...
 
def get_emittance
 Return the n dimensional normalised emittance of the bunch. More...
 
def get_kinetic_angular_momentum
 Return the bunch kinetic angular momentum about some arbitrary axis, defined by. More...
 
def get_canonical_angular_momentum
 Return the bunch canonical angular momentum about some arbitrary axis, defined by. More...
 
def momentum_variable
 Return the momentum conjugate for axis_variable. More...
 
def get_amplitude
 Return the particle amplitude for a hit relative to a bunch, defined by. More...
 
def axis_list_to_covariance_list
 Convert from a list of position variables to a list of position and conjugate momentum variables. More...
 
def convert_string_to_axis_list
 Return a list of axes from a string. More...
 
def set_geometric_momentum
 Set the default for conjugate momenta; either geometric (x', y', etc) or kinetic (px, py, etc) More...
 
def get_geometric_momentum
 Set the default for conjugate momenta; either geometric (x', y', etc) or kinetic (px, py, etc) More...
 
def get_axes
 Return list of axis variables (position-type variables) More...
 
def get_hit_variable
 Return axis variable for hit. More...
 
def list_get_hit_variable
 Return a list of get_hit_variable results, one element for each hit in the bunch. More...
 
def get
 Return a bunch variable taken from the list Bunch.get_variables() More...
 
def list_get
 Get a list of lists of variables from each bunch in the dict_of_bunches. More...
 
def get_variables
 Return a list of variables suitable for calls to Bunch.get. More...
 
def hit_get_variables
 Return a list of variables suitable for calls to Bunch.get. More...
 
def hit_write_builtin
 Write the hits in the bunch using some built-in format to the file file_name. More...
 
def hit_write_builtin_from_dict
 Write the hits in the dict of bunches using some built-in format to the file file_name. More...
 
def hit_write_user
 Write the hits in the bunch in some user defined format to file_handle, in an order defined by comparator. More...
 
def build_ellipse_2d
 Build a 2x2 ellipse matrix, given by For geometric = true. More...
 
def build_MR_ellipse
 Not implemented. More...
 
def build_ET_ellipse
 Not implemented. More...
 
def build_ellipse_from_transfer_matrix
 Not implemented. More...
 
def build_penn_ellipse
 Build an ellipse using Penn formalism for solenoids. More...
 
def histogram
 Returns a binned 1D or 2D histogram of hits in the bunch (but doesnt draw anything or call any plotting package). More...
 
def histogram_var_bins
 Returns a binned histogram of hits in the bunch. More...
 
def root_histogram
 Prints a 1D or 2D histogram of hits in the bunch. More...
 
def root_scatter_graph
 Prints a 2d scatter plot of Hit.get(...) data over a dict of bunches. More...
 
def root_graph
 Prints a graph of Bunch.get(...) data over a set of bunches and returns the root canvas. More...
 
def matplot_histogram
 Prints a 1D or 2D histogram of hits in the bunch. More...
 
def matplot_scatter_graph
 Prints a 2d scatter plot of Hit.get(...) data over a dict of bunches. More...
 
def matplot_graph
 Prints a graph of Bunch.get(...) data over a dict of bunches. More...
 
def bunch_overview_doc
 Creates some summary documentation for the Bunch class. More...
 

Static Public Attributes

tuple new_from_hits = staticmethod(new_from_hits)
 
tuple new_dict_from_read_builtin = staticmethod(new_dict_from_read_builtin)
 
tuple new_list_from_read_builtin = staticmethod(new_list_from_read_builtin)
 
tuple new_from_read_builtin = staticmethod(new_from_read_builtin)
 
tuple new_from_read_user = staticmethod(new_from_read_user)
 
tuple new_hit_shell = staticmethod(new_hit_shell)
 
tuple get_list_of_maus_dicts = staticmethod(get_list_of_maus_dicts)
 
tuple read_maus_root_file = staticmethod(read_maus_root_file)
 
tuple read_maus_file = staticmethod(read_maus_file)
 
tuple read_g4mice_file = staticmethod(read_g4mice_file)
 
tuple setup_file = staticmethod(setup_file)
 
tuple clear_global_weights = staticmethod(clear_global_weights)
 
tuple momentum_variable = staticmethod(momentum_variable)
 
tuple get_amplitude = staticmethod(get_amplitude)
 
tuple axis_list_to_covariance_list = staticmethod(axis_list_to_covariance_list)
 
tuple convert_string_to_axis_list = staticmethod(convert_string_to_axis_list)
 
tuple set_geometric_momentum = staticmethod(set_geometric_momentum)
 
tuple get_geometric_momentum = staticmethod(get_geometric_momentum)
 
tuple get_axes = staticmethod(get_axes)
 
tuple list_get = staticmethod(list_get)
 
tuple get_variables = staticmethod(get_variables)
 
tuple hit_get_variables = staticmethod(hit_get_variables)
 
tuple hit_write_builtin_from_dict = staticmethod(hit_write_builtin_from_dict)
 
tuple build_ellipse_2d = staticmethod(build_ellipse_2d)
 
tuple build_MR_ellipse = staticmethod(build_MR_ellipse)
 
tuple build_ET_ellipse = staticmethod(build_ET_ellipse)
 
tuple build_ellipse_from_transfer_matrix = staticmethod(build_ellipse_from_transfer_matrix)
 
tuple build_penn_ellipse = staticmethod(build_penn_ellipse)
 
tuple root_graph = staticmethod(root_graph)
 
tuple matplot_graph = staticmethod(matplot_graph)
 
tuple bunch_overview_doc = staticmethod(bunch_overview_doc)
 

Private Member Functions

def _cut
 
def __mean_for_get
 
def __weight_for_get
 
def __ang_mom_for_get
 
def __dispersion_for_get
 
def __dispersion_prime_for_get
 
def __cov_mat_picker
 
def __mean_picker
 

Private Attributes

 __hits
 
 __bunchcore
 
 __covs
 
 __means
 

Static Private Attributes

dictionary __g4mice_types = {'g4mice_special_hit':'SpecialHits', 'g4mice_virtual_hit':'VirtualHits'}
 
dictionary __number_of_header_lines = {'icool_for009':3, 'icool_for003':2, 'g4beamline_bl_track_file':0,'g4mice_special_hit':0,'g4mice_virtual_hit':0,'zgoubi':0, 'turtle':0, 'madx':0,'mars_1':0, 'maus_virtual_hit':0, 'maus_primary':0, 'opal_loss':1, 'muon1_csv':0}
 
list __axis_list = ['x','y','z','t', 'ct']
 
dictionary __get_dict
 
 __geometric_momentum = False
 
list __get_list = []
 

Detailed Description

Represents a bunch of particles.

Methods to:

Definition at line 62 of file Bunch.py.

Constructor & Destructor Documentation

def __init__ (   self)

Initialise to an empty bunch.

Alternatively use static initialisers defined below - I prefer static initialisers

Definition at line 66 of file Bunch.py.

References Bunch.__bunchcore.

def __del__ (   self)

Called by del.

Definition at line 135 of file Bunch.py.

References Bunch.__covs.

Referenced by Bunch.__getitem__().

Member Function Documentation

def __str__ (   self)

Return an abbreviated string like <Bunch of="" n="" hits>="">

Definition at line 74 of file Bunch.py.

References Bunch.__covs, and Bunch.__repr__().

def __repr__ (   self)

Return a long string that contains data in every hit.

Definition at line 79 of file Bunch.py.

References Bunch.__copy__(), Bunch.__hits, Bunch.__means, and Bunch.copy().

Referenced by Bunch.__str__(), and Bunch.copy().

def __copy__ (   self)

Make a copy but use references to self's data.

Definition at line 91 of file Bunch.py.

References Bunch.__copy__(), and Bunch.__deepcopy__().

Referenced by Bunch.__copy__(), Bunch.__repr__(), and Hit.new_from_maus_object().

def copy (   self)

Definition at line 95 of file Bunch.py.

References Bunch.__repr__().

Referenced by Bunch.__repr__().

def __deepcopy__ (   self,
  target 
)

Make a copy and copy self's data.

Definition at line 100 of file Bunch.py.

References Bunch.__deepcopy__(), Bunch.__hits, Bunch.__len__(), and Bunch.deepcopy().

Referenced by Bunch.__copy__(), and Bunch.__deepcopy__().

def deepcopy (   self)

Make a copy and copy self's data.

Definition at line 108 of file Bunch.py.

References Bunch.__getitem__(), Bunch.__hits, and Bunch.__setitem__().

Referenced by Bunch.__deepcopy__().

def __len__ (   self)

Number of hits.

Definition at line 114 of file Bunch.py.

References Bunch.__delitem__(), and Bunch.__hits.

Referenced by Bunch.__deepcopy__().

def __getitem__ (   self,
  key 
)

Called by subscript operator, returns the key^th hit in the bunch.

Definition at line 119 of file Bunch.py.

References Bunch.__del__().

Referenced by Bunch.deepcopy().

def __setitem__ (   self,
  key,
  value 
)

Called by subscript operator, sets the key^th hit in the bunch.

Definition at line 124 of file Bunch.py.

References Bunch.__eq__(), and Bunch.__hits.

Referenced by Bunch.deepcopy().

def __delitem__ (   self,
  key 
)

Called by remove method, deletes the key^th hit in the bunch.

Definition at line 130 of file Bunch.py.

References Bunch.__hits, and Bunch.__means.

Referenced by Bunch.__len__().

def __eq__ (   self,
  target,
  float_tolerance = Common.float_tolerance 
)

Return true if all hits in self are the same as all hits in target, and set_covariance_matrix data are the same.

Definition at line 141 of file Bunch.py.

References Bunch.__eq__(), Bunch.__hits, Bunch.__ne__(), Bunch.append(), and Bunch.new_from_hits.

Referenced by Hit.__eq__(), Bunch.__eq__(), and Bunch.__setitem__().

def __ne__ (   self,
  target,
  float_tolerance = Common.float_tolerance 
)

Return true if any hits in self are not the same as the corresponding hit in target.

Definition at line 160 of file Bunch.py.

Referenced by Bunch.__eq__().

def append (   self,
  hit 
)

Append a hit to Bunch self.

Definition at line 165 of file Bunch.py.

References Bunch.new_dict_from_read_builtin.

Referenced by Bunch.__eq__(), Bunch.clear_weights(), and Bunch.get_hit_variable().

def new_from_hits (   hits_list,
  covs = None,
  means = {},
  weights = [] 
)

Initialise from a list of hits, making a deepcopy of the hits (so allocating new memory for each hit)

  • hits_list = list of Hit objects

e.g. myBunch = new_from_hits([hit1, hit2, hit3]) will return a new bunch containing hit1, hit2, hit3

Definition at line 177 of file Bunch.py.

def new_dict_from_read_builtin (   file_type_string,
  file_name,
  indexing_variable = 'station' 
)

Create a dict of all bunches in a file using a built-in format.

  • file_type_string = string from Hit.file_types() that defines the formatting of the file
  • file_name = name of the file that contains hit data
  • indexing_variable = variable that will be used to define a bunch

e.g. bunch_dict = new_dict_from_read_builtin('icool_for003', 'for003.dat', 'pid') will return a new dict of bunches loaded from for003.dat in icool_for003 format, where each entry in the dict will be a reference from a pid value to a bunch

e.g. bunch_dict = new_dict_from_read_builtin('icool_for009', 'for009.dat', 'station') will return a new dict of bunches loaded from for009.dat in icool_for009 format, where each entry in the dict will be a reference from a station value to a bunch

Definition at line 201 of file Bunch.py.

References Bunch.new_list_from_read_builtin.

def new_list_from_read_builtin (   file_type_string,
  file_name,
  sort_variable = 'station' 
)

Create a sorted list of all bunches in a file using a built-in format.

  • file_type_string = string from Hit.file_types() that defines the formatting of the file
  • file_name = name of the file that contains hit data
  • sort_variable = variable that will be used to define a bunch and used for sort order

e.g. bunch_list = new_list_from_read_builtin('icool_for003', 'for003.dat', 'pid') will return a new list of bunches loaded from for003.dat in icool_for003 format, where each entry in the list will contain only one pid value with first entry having lowest pid

e.g. bunch_list = new_list_from_read_builtin('icool_for009', 'for009.dat', 'station') will return a new list of bunches loaded from for009.dat in icool_for009 format, where each entry in the list will contain only one station value with first entry having lowest station

Definition at line 237 of file Bunch.py.

def new_from_read_builtin (   file_type_string,
  file_name,
  test_function = None,
  number_of_hits = -1 
)

Initialise a bunch from a file using a built in format.

  • file_type_string = string from Hit.file_types() that defines the file format
  • file_name = string that defines the file_name to be used
  • test_function = Hits with test_function(hit) == False will be ignored, unless test_function==None
  • number_of_hits = only loads the first number_of_hits Hits

e.g. myBunch = Bunch.new_from_read_builtin('icool_for009', for009.dat, lambda hit: hit['station'] == 1, 1000) will return a bunch containing first 1000 hits from for009.dat with stationNumber=1

Definition at line 261 of file Bunch.py.

References Bunch.new_from_read_user.

def new_from_read_user (   format_list,
  format_units_dict,
  filehandle,
  number_of_skip_lines,
  test_function = None,
  number_of_hits = -1 
)

Initialise a bunch from a file using a user defined format.

  • format_list = ordered list of variables from get_variables() that contains the particle variables on each line of your input file
  • format_units_dict = dict of variables:units that are used to transform to internal system of units
  • filehandle = file handle, created using e.g. filehandle = open('for009.dat')
  • number_of_skip_lines = integer; skip this many lines at the start of the file
  • test_function = Hits with test_function(hit) == False will be ignored, unless test_function==None
  • number_of_hits = only loads the first number_of_hits Hits. Will read to end of file if this is negative

e.g. myBunch = Bunch.new_from_read_user(['x','y','z','px','py','pz'], {'x':'mm', 'y':'mm', 'z':'mm', 'px':'MeV/c', 'py':'MeV/c', 'pz':'MeV/c'}, my_input_file, 3) will skip the first 3 lines of the file and then read in all events from my_input_file, assuming the formatting listed

Definition at line 296 of file Bunch.py.

def new_hit_shell (   n_per_dimension,
  ellipse,
  set_variable_list,
  mass_shell_variable,
  defaults = {} 
)

Create a set of particles that sit on the shell of an ellipse in some arbitrary dimensional space.

  • n_per_dimension = number of particles in each dimension. Total number of particles is n_per_dimension^dimension
  • ellipse = numpy.matrix that defines the ellipse of particles
  • set_variable_list = list of set variables that defines what each dimension in the ellipse corresponds to
  • mass_shell_variable = variable that will be used to set the mass shell condition for each hit
  • defaults = dict of default set variables that each hit will get.

e.g. new_bunch_as_hit_shell(2, numpy.matrix([[1,0],[0,1]]),['x','y'],'energy',{'pid':-13,'mass':Common.pdg_pid_to_mass[13],'pz':200.}) will make a set of muons on a circle in x-y space with 200. MeV/c momentum. Event number is automatically allocated incrementing from 0.

Definition at line 323 of file Bunch.py.

def get_list_of_maus_dicts (   maus_type,
  spill 
)

Get a list of maus_dicts from a maus_spill for a particular maus_type.

  • maus_type = type to extract from the spill
  • spill = dict containing a single maus spill

Returns dict formatted according to maus but for one hit

Definition at line 344 of file Bunch.py.

def read_maus_root_file (   file_name,
  number_of_hits = -1,
  list_of_maus_types = ['maus_root_virtual_hit',
  maus_root_primary 
)

Read hits from a maus ROOT file.

  • file_name = name of the file to read
  • number_of_hits = Not used
  • list_of_maus_types = only make hits from these types

Returns a list of hits

Definition at line 371 of file Bunch.py.

def read_maus_file (   file_name,
  number_of_hits = -1,
  list_of_maus_types = ['maus_virtual_hit',
  maus_primary 
)

Initialise a bunch from a MAUS file.

  • file_name = string that defines the file_name to be used
  • number_of_hits = only loads the first number_of_hits Hits
  • list_of_converters = list of converter functions that will be executed on the maus file (one for each hit type)

Definition at line 400 of file Bunch.py.

References Bunch.read_g4mice_file.

def read_g4mice_file (   file_name,
  number_of_hits = -1,
  list_of_classes = ['SpecialHits',
  VirtualHits 
)

Initialise a bunch from a g4mice file.

  • file_name = string that defines the file_name to be used
  • number_of_hits = only loads the first number_of_hits Hits
  • list_of_classes = ignores g4mice classes that are not in list_of_classes

Definition at line 436 of file Bunch.py.

def setup_file (   file_format_type_string,
  file_name 
)

Returns a file handle with special phrases and characters stripped.

Returned file_handle contains only hit data

Definition at line 461 of file Bunch.py.

References Bunch.__hits, and Bunch.abelian_transformation().

def translate (   self,
  dict_variables_values,
  mass_shell_variable = '' 
)

Translate all events in the bunch by dict_variables_values.

  • dict_variables_values = dict of variable names from Hit.set_variables() to variable values
  • mass_shell_variable = set mass shell variable so that E^2=p^2+m^2 after translation. Does nothing if equal to ''

e.g. bunch.translate({'pz':-10,'z':100}, 'energy') reduces particle pz by 10 MeV/c and increases E by 100 mm then sets E so that mass shell condition is still obeyed

Perform an Abelian Transformation on all variables in the bunch so that V_{out} - O = R*(V_{in}-O)+T

  • rotation_list = list of Hit.set_variables() strings that defines the vector V
  • rotation_matrix = matrix R
  • translation_dict = dict of Hit.set_variables() strings to values that defines the vector T
  • mass_shell_variable = set mass shell variable so that E^2=p^2+m^2 after transformation. Does nothing if equal to ''
  • origin_dict = dict of Hit.set_variables() strings to values that defines the vector O. Defaults to bunch mean.

e.g. bunch.abelian_transformation(['x','px','z'], [[1,0.1,0],[0,1,0],[0,0,1]], {'z':1000}, 'pz') has V_{in} = ('x','px','z') R = 1 0.1 0 0 1 0 0 0 1 T = (0,0,1000) O = bunch mean (This is like a drift). Note that 'z' has to be explicitly included in the rotation to be present in T

Definition at line 495 of file Bunch.py.

References Bunch.covariance_matrix(), and Bunch.transform_to().

def abelian_transformation (   self,
  rotation_list,
  rotation_matrix,
  translation_dict = {},
  origin_dict = {},
  mass_shell_variable = '' 
)
def transform_to (   self,
  transform_list,
  target_covariances,
  translation_dict = {},
  origin_dict = {},
  mass_shell_variable = '' 
)

Perform a linear transformation on all particles in the bunch to get a bunch with covariance matrix similar to target_covariances.

The transformation always has determinant 1, and so is emittance conserving. Then performs a translation using translation_dict

  • transform_list = list of Hit.set_variables() strings that defines the vector V
  • target_covariances = target covariance matrix. Must be n*n dimensions where n is the length of transform_list
  • translation_dict = dict of Hit.set_variables() strings to values that defines a translation
  • origin_dict = dict of Hit.set_variables() strings to values that defines the vector O. Defaults to bunch mean.
  • mass_shell_variable = set mass shell variable so that E^2=p^2+m^2 after transformation. Does nothing if equal to \'\'

e.g. bunch.transform_to(['x','px'], [[1,0],[0,1]], {'pz':10}, 'energy') will apply a transformation to all hits in the bunch that diagonalises the bunch and makes Var(x,x) equal to Var(px,px), but conserving emittance; then will add 10 to pz for all tracks; then adjust energy to keep mass shell condition.

Definition at line 542 of file Bunch.py.

References Bunch.__hits, Bunch.get_hit_variable(), Bunch.get_hits(), Bunch.hit_equality(), and Bunch.hits().

Referenced by Bunch.translate().

def period_transformation (   self,
  offset,
  frequency,
  variable = 't' 
)

Transform all hit's variable from a linear space to a periodic space with some frequency and offset.

  • offset = float that defines the offset
  • frequency = float that defines the frequency of the periodic space
  • variable = string from hit_set_variables. variable for which the periodicity is applied

e.g. bunch.period_transformation( dt, rf_freq) would transform all times into a range between (-0.5/rf_freq, 0.5/rf_freq). Hits with 't' = n*dt would transform to t=0 (n arbitrary integer) Used to transform a set of many rf buckets into one rf bucket, for calculating longitudinal emittance etc

Definition at line 572 of file Bunch.py.

Referenced by Bunch.abelian_transformation().

def hits (   self)

Returns the list of all hits in the bunch.

Definition at line 581 of file Bunch.py.

References Bunch.conditional_remove().

Referenced by Bunch.get_beta(), Bunch.transform_to(), and Bunch.transmission_cut().

def get_hits (   self,
  variable,
  value,
  comparator = operator.eq 
)

Returns a list of all hits in the bunch with comparator(variable, value) == True By default comparator is equality operator, so returns a list of all hits in the bunch with variable == value.

  • variable = string from Hit.get_variables()
  • value = value for comparison
  • comparator = function that operates on a hit and returns a boolean

e.g. get_hits('eventNumber', 50) returns a list of all hits in the bunch with hitNumber 50 e.g. get_hits('eventNumber', 50, operator.lt) returns a list of all hits in the bunch with hitNumber less than 50

Definition at line 596 of file Bunch.py.

References Bunch.__hits, Bunch.list_get_hit_variable(), Bunch.mean(), and Bunch.standard_deviation().

Referenced by Bunch.transform_to().

def hit_equality (   self,
  target,
  float_tolerance = Common.float_tolerance 
)

Return True if all hits in self are the same as all hits in target.

  • target = bunch to test against

Definition at line 609 of file Bunch.py.

References Bunch.standard_deviation().

Referenced by Bunch.transform_to().

def conditional_remove (   self,
  variable_value_dict,
  comparator,
  value_is_nsigma_bool = False 
)

For when a cut is not good enough, remove hits from the bunch altogether if comparator(value, get([variable])) is False.

  • variable_value_dict = dict of Bunch.get_variables() to the cut value; cut if the hit variable has value > value
  • value_is_nsigma_bool = boolean; if True, value is the number of standard deviations
  • global_cut = boolean; if True, apply cut to global weights; else apply to local weights

e.g. bunch.cut({'energy':300,}, operator.ge) removes particles if they have ge(hit.get('energy'),300) here operator.ge is a functional representation of the >= operator ge(hit.get('energy'),300) is the same as (hit.get('energy') >= 300)

A whole load of useful comparators can be found in the operator module. e.g. ge is >=; le is <=; etc See also python built-in function "filter".

Definition at line 630 of file Bunch.py.

References Bunch.__covs, Bunch.bunch_weight(), Bunch.mean(), and Bunch.moment().

Referenced by Bunch.hits().

def standard_deviation (   self,
  variable,
  variable_mean = {} 
)

Return a standard deviation, given by sum( (u-u_mean)**2 )**0.5 where u is the variable specified.

  • variable = a variable from Hit.get_variables(). Can be a list, in which case only the first hit is taken
  • variable_mean = use this as u_mean rather than calculating a priori. Can be a dict, in which case if variable is in the keys will use that value.

e.g. bunch.standard_deviation('x') returns the standard deviation of x

e.g. bunch.standard_deviation('x', 1.) returns the standard deviation of x about a mean of 1.

e.g. bunch.standard_deviation(['x'], {'x':1.}) returns the standard deviation of x about a mean of 1.

Definition at line 661 of file Bunch.py.

References Bunch.__hits, Bunch.bunch_weight(), Bunch.get_hit_variable(), and Bunch.mean().

Referenced by Bunch.get_hits(), and Bunch.hit_equality().

def moment (   self,
  variable_list,
  variable_mean_dict = {} 
)

Return a moment, sum( (u1 - u1_mean)*(u2-u2_mean)*(etc)) where u is a set of Hit get_variables indexed by variable_list.

  • variable_list = list of strings that index the moment
  • variable_mean_dict = dict of variable to means for moment calculation. Assume bunch mean if no value is specified

e.g. bunch.moment(['x','x'], {'x':0.1}) returns the variance of x about a mean of 0.1

e.g. bunch.moment(['x','px']) returns the covariance of x,px about the bunch mean

Definition at line 682 of file Bunch.py.

References Bunch.__means, Bunch.covariance_matrix(), Bunch.mean(), and Bunch.moment().

Referenced by Bunch._cut(), Bunch.conditional_remove(), Bunch.get_alpha(), Bunch.get_beta(), Bunch.get_decoupled_emittance(), Bunch.get_gamma(), Bunch.mean(), Bunch.means_set(), Bunch.moment(), and Bunch.transmission_cut().

def mean (   self,
  variable_list 
)

Return dict of variables to means.

  • variable_list = list of strings to calculate means

e.g. bunch.mean(['x','px']) returns a dict like {'x':x_mean, 'px':px_mean}

Definition at line 717 of file Bunch.py.

References Bunch.moment(), and Bunch.set_covariance_matrix().

Referenced by Bunch._cut(), Bunch.conditional_remove(), Bunch.convert_string_to_axis_list(), Bunch.covariance_matrix(), Bunch.get_alpha(), Bunch.get_beta(), Bunch.get_decoupled_emittance(), Bunch.get_gamma(), Bunch.get_hits(), Bunch.matplot_histogram(), Bunch.means_set(), Bunch.moment(), Bunch.standard_deviation(), and Bunch.transmission_cut().

def covariance_matrix (   self,
  get_variable_list,
  origin_dict = {} 
)

Return covariance matrix of variables.

  • variable_list = list of strings to calculate covariance
  • origin_dict = dict of strings to values for origin about which covariances are calculated. Defaults to mean

e.g. bunch.covariance_matrix(['x','px'], {'x':0, 'px':0}) returns a matrix like [[Var(x,x), Var(x,px)], [Var(x,px), Var(px,px)]

Definition at line 735 of file Bunch.py.

References Bunch.__covs, Bunch.__hits, Bunch.__means, Bunch.bunch_weight(), Bunch.clear_global_weights(), Bunch.clear_local_weights(), Bunch.clear_weights(), Bunch.covariance_matrix(), Bunch.covariances_set(), Bunch.mean(), and Bunch.means_set().

Referenced by Bunch.convert_string_to_axis_list(), Bunch.covariance_matrix(), Bunch.get_alpha(), Bunch.get_decoupled_emittance(), Bunch.moment(), and Bunch.translate().

def set_covariance_matrix (   self,
  use_internal_covariance_matrix = True,
  covariance_matrix = None,
  mean_dict = {} 
)

Choose whether to use an internal covariance matrix for calculations.

  • use_internal_covariance_matrix = boolean. If set to True, x-boa will recalculate its internal covariance matrix and use this for some calculations. If set to False, x-boa will calculate the covariance matrix each time.
  • covariance_matrix = NumPy matrix. x-boa will use this matrix as the internal covariance matrix; should be a 10x10 matrix ordered like (x, px, y, py, z, pz, t, enegry, ct, energy). Ignored if equal to None
  • mean_dict = dict of variables to means. x-boa will use this dict to index means; should contain means of (x, px, y, py, z, pz, t, enegry, ct, energy). Ignored if equal to None

As a speed optimisation, x-boa can calculate a covariance matrix and use this for all calculations involving covariances, i.e. Twiss parameters, emittances, amplitudes etc. Otherwise x-boa will re-calculate this each time, which can be slow. Be careful though - x-boa does not automatically detect for hits being added or removed from the bunch, etc. The user must call this function each time the bunch changes (events added, weightings changed, etc) to update the internal covariance matrix

Definition at line 773 of file Bunch.py.

References Bunch.clear_global_weights, Bunch.clear_local_weights(), and Bunch.cut().

Referenced by Bunch.mean().

def covariances_set (   self)

If internal covariances are set by set_covariance_matrix, return True; else return False.

Definition at line 787 of file Bunch.py.

Referenced by Bunch.covariance_matrix().

def means_set (   self)

If means are set by set_covariance_matrix, return True; else return False.

Definition at line 793 of file Bunch.py.

References Bunch.mean(), and Bunch.moment().

Referenced by Bunch.covariance_matrix().

def bunch_weight (   self)

Return statistical weight of all hits in the bunch.

Definition at line 798 of file Bunch.py.

References Bunch._cut(), and Bunch.list_get_hit_variable().

Referenced by Bunch.conditional_remove(), Bunch.covariance_matrix(), Bunch.matplot_histogram(), and Bunch.standard_deviation().

def clear_local_weights (   self)

Set local_weight of all hits in the bunch to 1.

Definition at line 806 of file Bunch.py.

References Bunch.__hits, and Bunch.transmission_cut().

Referenced by Bunch.covariance_matrix(), and Bunch.set_covariance_matrix().

def clear_global_weights ( )

Set global_weight of all hits in the bunch to 1.

Definition at line 812 of file Bunch.py.

Referenced by Bunch.covariance_matrix().

def clear_weights (   self)

Set global_weight and local_weight of all hits in the bunch to 1.

Definition at line 818 of file Bunch.py.

References Bunch.append().

Referenced by Bunch.covariance_matrix().

def cut (   self,
  variable_value_dict,
  comparator,
  value_is_nsigma_bool = False,
  global_cut = False 
)

Set weight of hits in the bunch to 0 if comparator(value, get([variable])) is False.

  • variable_value_dict = dict of Bunch.get_variables() to the cut value; cut if the hit variable has value > value
  • value_is_nsigma_bool = boolean; if True, value is the number of standard deviations
  • global_cut = boolean; if True, apply cut to global weights; else apply to local weights

e.g. bunch.cut({'energy':300,}, operator.ge) sets weight of particles to zero if they have ge(hit.get('energy'),300) here operator.ge is a functional representation of the >= operator ge(hit.get('energy'),300) is the same as (hit.get('energy') >= 300)

A whole load of useful comparators can be found in the operator module. e.g. ge is >=; le is <=; etc

Definition at line 836 of file Bunch.py.

References Bunch.get_beta().

Referenced by Bunch.set_covariance_matrix().

def _cut (   self,
  variable,
  comparator,
  cut_value,
  set_var 
)
private

Definition at line 848 of file Bunch.py.

References Bunch.get_emittance(), Bunch.mean(), and Bunch.moment().

Referenced by Bunch.bunch_weight().

def transmission_cut (   self,
  test_bunch,
  global_cut = False,
  test_variable = ['spill',
  event_number,
  particle_number,
  float_tolerance = Common.float_tolerance 
)

Set weight of hits in the bunch to 0 if no events can be found in test_bunch with the same test_variable.

  • test_bunch = bunch to test against
  • global_cut = if True, apply cut to global weights
  • test_variable = cut a hit in self if no hits are found in test_bunch with the same test_variable. If test_variable is a list, then cut from self if no hits are found in test_bunch with all test_variables the same.

E.g. bunch.transmission_cut( some_other_bunch, True ) will apply a global cut if a hit with the same [spill, event_number, particle_number] is not in some_other_bunch (for all hits)

Definition at line 870 of file Bunch.py.

References Bunch.get(), Bunch.get_alpha(), Bunch.get_emittance(), Bunch.get_gamma(), Bunch.hits(), Bunch.mean(), Bunch.moment(), and Bunch.momentum_variable.

Referenced by Bunch.clear_local_weights().

def get_beta (   self,
  axis_list,
  geometric = None 
)

Return the bunch beta function, defined by.

  • For normalised beta = Sum_{i} Var(x_i)*p/(emittance*mass*n)
  • For geometric beta = Sum_{i} Var(x_i)/(emittance*n)

where x_i is a position variable from axis_list.

  • axis_list = list of axes strings

and n is the length of axis_list. E.g.

1 get_beta(['x','y'])

will return ( Var(x,x)+Var(y,y) )/(2*pz*emittance(['x','y')*mass)

Definition at line 911 of file Bunch.py.

References Bunch.get(), Bunch.get_dispersion(), Bunch.get_emittance(), Bunch.hits(), Bunch.mean(), Bunch.moment(), and Bunch.momentum_variable.

Referenced by Bunch.cut().

def get_gamma (   self,
  axis_list,
  geometric = None 
)

Return the bunch beta function, defined by.

  • For normalised gamma = Sum_{i} Var(p_i)/(pz*emittance*mass*n)
  • For geometric gamma = Sum_{i} Var(p_i)/(emittance*n)

where p_i is a momentum variable from axis_list.

  • axis_list = list of axes strings

and n is the length of axis_list. E.g.

1 get_gamma(['x','y'])

will return ( Var(p_x)+Var(p_y) )/(2*pz*emittance(['x','y')*mass)

Definition at line 940 of file Bunch.py.

References Bunch.get_dispersion_prime(), Bunch.get_dispersion_rsquared(), Bunch.mean(), and Bunch.moment().

Referenced by Bunch.transmission_cut().

def get_alpha (   self,
  axis_list,
  geometric = None 
)

Return the bunch alpha function, defined by.

  • For normalised alpha = Sum_{i} Cov(x_i, p_i)/(emittance*mass*n)
  • For geometric alpha = Sum_{i} Cov(x_i, p_i)/(emittance*n)

where p_i is a momentum variable from axis_list.

  • axis_list = list of axes strings

and n is the length of axis_list. E.g.

1 get_alpha(['x','y'])

will return ( Var(p_x)+Var(p_y) )/(2*emittance(['x','y')*mass)

Definition at line 969 of file Bunch.py.

References Bunch.__cov_mat_picker(), Bunch.covariance_matrix(), Bunch.get_decoupled_emittance(), Bunch.mean(), and Bunch.moment().

Referenced by Bunch.transmission_cut().

def get_dispersion (   self,
  axis 
)

Return the bunch dispersion D in axis q, defined by.

  • D = cov(q,E)*mean(E)/var(E)
  • axis = string from axis_list that defines the axis q

E.g.

1 my_bunch.get_dispersion('y')

would return the dispersion in the y-direction

Definition at line 995 of file Bunch.py.

Referenced by Bunch.get_beta(), and Bunch.matplot_histogram().

def get_dispersion_rsquared (   self)

Return a special bunch dispersion defined by.

  • D = (<r2,E>-<r2>*<E>)*mean(E)/var(E)

where <> are raw moments (not central moments)

Definition at line 1006 of file Bunch.py.

References Bunch.get_emittance().

Referenced by Bunch.get_gamma().

def get_dispersion_prime (   self,
  axis,
  geometric = None 
)

Return the bunch dispersion prime D in axis q, defined by.

  • D' = cov(p_q,E)*mean(E)/var(E)
  • axis = string from axis_list that defines the axis q

E.g.

1 my_bunch.get_dispersion('y')

would return the dispersion in the y-direction

Definition at line 1025 of file Bunch.py.

Referenced by Bunch.get_gamma(), and Bunch.matplot_histogram().

def get_decoupled_emittance (   self,
  coupled_axis_list,
  emittance_axis_list,
  covariance_matrix = None,
  geometric = None 
)
def get_emittance (   self,
  axis_list,
  covariance_matrix = None,
  geometric = None 
)

Return the n dimensional normalised emittance of the bunch.

  • emittance = (|V|**(1/2n))/mass

where n is the number of elements in axis list and V is a covariance matrix with elements V_{ij} = cov(u_i, u_j) where u is a vector of elements in the axis_list and their momentum conjugates, u = (q_i, p_i)

  • axis_list = list of axes from Bunch.get_axes().
  • covariance_matrix = if specified, use this covariance matrix rather than calculating a new one each time.
  • geometric = if specified, use geometric variables (dx/dz, dy/dz, etc) rather than normalised variables (px, py, pz).

E.g.

1 get_emittance(['x'])

will return |V|**(1/2) where V is the matrix with elements V = Var(x,x) Cov(x,px) Cov(x,px) Var(px,px) and |V| is the determinant.

Definition at line 1122 of file Bunch.py.

References Bunch.get_amplitude.

Referenced by Bunch._cut(), Bunch.get_beta(), Bunch.get_decoupled_emittance(), Bunch.get_dispersion_rsquared(), and Bunch.transmission_cut().

def get_kinetic_angular_momentum (   self,
  rotation_axis_dict = {'x':0,
  y 
)

Return the bunch kinetic angular momentum about some arbitrary axis, defined by.

  • L = <x py>=""> - <y px>=""> (momentum variables)
  • L =

*(<x y'> - <y x'>) (geometric variables)

  • rotation_axis_dict = dict that defines the axis of rotation

Definition at line 1144 of file Bunch.py.

Referenced by Bunch.get_decoupled_emittance(), and Bunch.matplot_histogram().

def get_canonical_angular_momentum (   self,
  bz = None,
  field_axis_dict = {'x':0,
  y 
)

Return the bunch canonical angular momentum about some arbitrary axis, defined by.

  • L = <x py>=""> - <y px>=""> + e Bz (<x^2>+y^2) (momentum variables)
  • L =

*(<x y'> - <y x'>) + e Bz (<x^2>+y^2) (geometric variables)

  • bz = nominal on-axis magnetic field - where axis is as; defaults to the field of the 1st particle in the bunch
  • field_axis_dict = dict that defines the nominal solenoid axis
  • rotation_axis_dict = dict that defines the axis of rotation

Definition at line 1161 of file Bunch.py.

References Bunch.axis_list_to_covariance_list.

Referenced by Bunch.get_decoupled_emittance().

def momentum_variable (   axis_variable,
  geometric_momentum 
)

Return the momentum conjugate for axis_variable.

Definition at line 1171 of file Bunch.py.

References Bunch.convert_string_to_axis_list.

def get_amplitude (   bunch,
  hit,
  axis_list,
  covariance_matrix = None,
  mean_dict = {},
  geometric = None 
)

Return the particle amplitude for a hit relative to a bunch, defined by.

  • amplitude = emittance*x^T.V^-1.x

where x is a vector of particle coordinates and V is a covariance matrix

  • bunch = bunch from which the covariance matrix is calculated
  • hit = hit from which the particle vector is taken
  • axis_list = list of axes that defines the covariance matrix and particle vector
  • covariance_matrix = if this is not set to None, will use this covariance_matrix for the calculation rather than taking one from bunch. Should be a numpy matrix like "x","px","y","py" E.g.
    1 Bunch.get_amplitude(my_bunch, my_hit, ['x','y'])
    will return emittance*(x,px,y,py)^T*V^{-1}(x,px,y,py)*(x,px,y,py)

Definition at line 1208 of file Bunch.py.

References Bunch.get_axes(), and Bunch.get_geometric_momentum().

def axis_list_to_covariance_list (   axis_list,
  geometric = None 
)

Convert from a list of position variables to a list of position and conjugate momentum variables.

Definition at line 1232 of file Bunch.py.

References Bunch.list_get_hit_variable().

def convert_string_to_axis_list (   axis_string)

Return a list of axes from a string.

  • axis_string = string that contains a list of axis. Either format as axis_strings separated by white space or as a python list of axis_strings

Definition at line 1249 of file Bunch.py.

References Bunch.covariance_matrix(), and Bunch.mean().

def set_geometric_momentum (   new_value_bool)

Set the default for conjugate momenta; either geometric (x', y', etc) or kinetic (px, py, etc)

  • new_value_bool = if True, use geometric momenta. If False, use kinetic momenta (default)

Definition at line 1267 of file Bunch.py.

def get_geometric_momentum ( )

Set the default for conjugate momenta; either geometric (x', y', etc) or kinetic (px, py, etc)

  • new_value_bool = if True, use geometric momenta. If False, use kinetic momenta (default)

Definition at line 1277 of file Bunch.py.

Referenced by Bunch.get_amplitude().

def get_axes ( )

Return list of axis variables (position-type variables)

Definition at line 1283 of file Bunch.py.

Referenced by Bunch.get_amplitude().

def get_hit_variable (   self,
  hit,
  variable_name,
  covariance_matrix = None,
  mean_dict = {} 
)

Return axis variable for hit.

Special power is that it can calculate amplitude, unlike hit.get(blah)

- hit = a Hit object
- variable_name = either a variable from Hit.get_variables() or an amplitude variable.
    amplitude variables should be formatted like 'amplitude x y' or 'amplitude x y t'
- covariance_matrix = use a pre-calculated covariance matrix, or calculate if set to None

Definition at line 1296 of file Bunch.py.

References Bunch.append().

Referenced by Bunch.histogram_var_bins(), Bunch.root_graph(), Bunch.standard_deviation(), and Bunch.transform_to().

def list_get_hit_variable (   self,
  list_of_variables,
  list_of_units = [],
  covariance_matrix = None,
  mean_dict = {} 
)

Return a list of get_hit_variable results, one element for each hit in the bunch.

  • variable_name = either a variable from Hit.get_variables() or an amplitude variable. amplitude variables should be formatted like 'amplitude x y' or 'amplitude x y t' i.e. amplitude followed by a list of axes separated by white space
  • covariance_matrix = use a pre-calculated covariance matrix, or calculate if set to None

Definition at line 1312 of file Bunch.py.

References Bunch.__hits, Bunch.get_variables(), Bunch.hit_get_variables(), Bunch.hit_write_builtin(), and Bunch.hit_write_builtin_from_dict.

Referenced by Bunch.axis_list_to_covariance_list(), Bunch.build_ET_ellipse(), Bunch.build_MR_ellipse(), Bunch.build_penn_ellipse(), Bunch.bunch_weight(), Bunch.get_hits(), and Bunch.root_scatter_graph().

def get (   self,
  variable_string,
  variable_list 
)

Return a bunch variable taken from the list Bunch.get_variables()

  • variable_string = string variable from Bunch.get_variables()
  • variable_list = list of variables (see below, a bit complicated)

For 'bunch_weight', axis_list is ignored

For 'dispersion', 'dispersion_prime' the first value of variable_list is used. It should be taken from the list Bunch.get_axes()

For 'mean', the first value in variable_list is used. It should be taken from the list Bunch.hit_get_variables()

For others, variable_list should be a list taken from Bunch.get_axes()

E.g. bunch.get('emittance', ['x','y']) would get emittance x y

E.g. bunch.get('mean', ['x','px','z']) would return mean of x; px and z are ignored

Definition at line 1350 of file Bunch.py.

References Bunch.hit_write_user().

Referenced by Hit.__eq__(), Hit.__read_formatted(), Hit.abelian_transformation(), Hit.check(), Hit.deepcopy(), Hit.dict_from_hit(), Hit.file_header(), Hit.get(), Bunch.get_beta(), Bunch.get_decoupled_emittance(), Hit.get_ek(), Hit.get_p(), Hit.get_r(), Hit.get_rP(), Hit.get_tP(), Hit.read_builtin_formatted(), Hit.set_ek(), and Bunch.transmission_cut().

def list_get (   dict_of_bunches,
  list_of_variables,
  list_of_axis_lists 
)

Get a list of lists of variables from each bunch in the dict_of_bunches.

  • dict_of_bunches = dict of bunches from which the lists will be taken
  • list_of_variables = list of variables that will be used in the calculation
  • list_of_axis_lists = axis_list that will be used in the calculation of the corresponding variable

E.g. list_get(my_dict_of_bunches, ['mean', 'emittance'], [['z'],['x','y']]) would calculate a list of two arrays: (i) mean z; (ii) emittance x y

Output is sorted by the first variable in the list. This might be useful to interface with E.g. a plotting package

Definition at line 1371 of file Bunch.py.

References Bunch.__hits, and Bunch.build_ellipse_2d.

def get_variables ( )

Return a list of variables suitable for calls to Bunch.get.

Definition at line 1384 of file Bunch.py.

Referenced by Bunch.list_get_hit_variable().

def hit_get_variables ( )

Return a list of variables suitable for calls to Bunch.get.

Definition at line 1390 of file Bunch.py.

Referenced by Bunch.list_get_hit_variable().

def hit_write_builtin (   self,
  file_type_string,
  file_name,
  user_comment = None 
)

Write the hits in the bunch using some built-in format to the file file_name.

  • file_type_string = string that controls which predefined file type will be used
  • file_name = string that defines the file name
  • user_comment = comment to be included in file header (e.g. problem title)

e.g. my_bunches.hit_write_builtin('g4mice_special_hit', 'Sim.out.gz') would write all hits from my_bunches formatted in the old G4MICE Special Virtual style in file Sim.out.gz

Definition at line 1405 of file Bunch.py.

References Bunch.build_ET_ellipse(), and Bunch.build_MR_ellipse().

Referenced by Bunch.list_get_hit_variable().

def hit_write_builtin_from_dict (   dict_of_bunches,
  file_type_string,
  file_name,
  user_comment = None 
)

Write the hits in the dict of bunches using some built-in format to the file file_name.

  • dict_of_bunches = list of hits
  • file_type_string = string that controls which predefined file type will be used
  • file_name = string that defines the file name
  • user_comment = comment to be included in file header (e.g. problem title)

e.g. Bunch.hit_write_builtin_from_dict(my_bunches, 'g4mice_special_hit', 'Sim.out.gz') would write all hits from my_bunches formatted in the G4MICE Special Virtual style in file Sim.out.gz

Definition at line 1422 of file Bunch.py.

def hit_write_user (   self,
  format_list,
  format_units_dict,
  file_handle,
  separator = ' ',
  comparator = None 
)

Write the hits in the bunch in some user defined format to file_handle, in an order defined by comparator.

  • format_list = ordered list of strings from get_variables()
  • format_units_dict = dict of formats from format_list to units
  • file_handle = file handle made using e.g. open() command to which hits are written
  • separator = separator that is used to separate hits
  • comparator = comparator that is used for sorting prior to writing the file; if left as None, no sorting is performed

e.g. aBunch.hit_write_user(['x','px','y','py'], ['x':'m','y':'m','px':'MeV/c','py':'MeV/c'], some_file, '@') would make output like 0.001.nosp@m.@0.0.nosp@m.02@0.001.nosp@m.@0.0.nosp@m.02 0.003.nosp@m.@0.0.nosp@m.04@0.003.nosp@m.@0.0.nosp@m.04 in some_file

Definition at line 1445 of file Bunch.py.

Referenced by Bunch.get().

def build_ellipse_2d (   beta,
  alpha,
  emittance,
  p,
  mass,
  geometric 
)

Build a 2x2 ellipse matrix, given by For geometric = true.

  • var(x, x) = beta*emittance
  • var(x, x') = alpha*emittance
  • var(x',x') = gamma*emittance

For geometric = false

  • var(x, x ) = beta*emittance*mass/p
  • var(x, px) = alpha*emittance*mass
  • var(px,px) = gamma*emittance*mass*p

Definition at line 1466 of file Bunch.py.

References Bunch.histogram().

def build_MR_ellipse ( )

Not implemented.

Definition at line 1491 of file Bunch.py.

References Bunch.list_get_hit_variable().

Referenced by Bunch.hit_write_builtin().

def build_ET_ellipse ( )

Not implemented.

Definition at line 1500 of file Bunch.py.

References Bunch.list_get_hit_variable().

Referenced by Bunch.hit_write_builtin().

def build_ellipse_from_transfer_matrix (   M)

Not implemented.

Definition at line 1509 of file Bunch.py.

def build_penn_ellipse (   emittance_t,
  mass,
  beta_t,
  alpha_t,
  p,
  Ltwiddle_t,
  bz,
  q 
)

Build an ellipse using Penn formalism for solenoids.

  • emittance_t = nominal beam emittance
  • mass = particle mass
  • beta_t = transverse beta function
  • alpha_t = transverse alpha function
  • p = reference momentum
  • Ltwiddle_t = normalised canonical angular momentum
  • bz = magnetic field strength
  • q = particle charge

Output ellipse is a 4*4 matrix with elements v_ij where i,j indexes the vector (x,px,y,py)

Definition at line 1529 of file Bunch.py.

References Bunch.list_get_hit_variable(), and Bunch.root_histogram().

def histogram (   self,
  x_axis_string,
  x_axis_units = '',
  y_axis_string = '',
  y_axis_units = '',
  nx_bins = None,
  ny_bins = None,
  xmin = None,
  xmax = None,
  ymin = None,
  ymax = None 
)

Returns a binned 1D or 2D histogram of hits in the bunch (but doesnt draw anything or call any plotting package).

  • x_axis_string = string for call to get_hit_variables()
  • x_axis_units = units for x axis
  • y_axis_string = string for call to get_hit_variables(). If string is empty, makes a 1D histogram
  • y_axis_units = units for y axis
  • nx_bins = force histogram to use this number of bins for the x-axis rather than choosing number of bins itself
  • ny_bins = force histogram to use this number of bins for the y-axis rather than choosing number of bins itself
  • xmin = float that overrides auto-detection of minimum x-axis value
  • xmax = float that overrides auto-detection of maximum x-axis value
  • ymin = float that overrides auto-detection of minimum y-axis value
  • ymax = float that overrides auto-detection of maximum y-axis value

Return value is a list of bin weights for a 1D histogram or a list of lists of bin weights for a 2D histogram

Definition at line 1569 of file Bunch.py.

References Bunch.__hits, and Bunch.root_scatter_graph().

Referenced by Bunch.build_ellipse_2d().

def histogram_var_bins (   self,
  x_axis_string,
  x_bins,
  x_axis_units = '',
  y_axis_string = '',
  y_bins = None,
  y_axis_units = '' 
)

Returns a binned histogram of hits in the bunch.

Requires numpy

  • x_axis_string = string for call to get_hit_variables()
  • x_bins = list of bin edges used to generate the histogram
  • x_axis_units = units for x axis
  • y_axis_string = string for call to get_hit_variables()
  • y_bins = list of bin edges used to generate the histogram
  • y_axis_units = units for y axis

Return value is a tuple containing ((bin weights array),x_bins,y_bins). The bin weights array is always nx*ny, with ny defaulting to 1 in the case of a 1d histogram.

Definition at line 1602 of file Bunch.py.

References Bunch.get_hit_variable(), and Bunch.root_graph.

def root_histogram (   self,
  x_axis_string,
  x_axis_units = '',
  y_axis_string = '',
  y_axis_units = '',
  nx_bins = None,
  ny_bins = None,
  canvas = None,
  xmin = None,
  xmax = None,
  ymin = None,
  ymax = None,
  line_color = rg.line_color,
  line_style = rg.line_style,
  line_width = rg.line_width,
  fill_color = rg.fill_color,
  stats = rg.stats,
  hist_title_string = '',
  draw_option = '' 
)

Prints a 1D or 2D histogram of hits in the bunch.

Axes are automatically detected to encapsulate all data.

Needs correct root installation.

  • x_axis_string = string for call to get_hit_variables()
  • x_axis_units = units for x axis
  • y_axis_string = string for call to get_hit_variables(). If string is empty, makes a 1D histogram
  • y_axis_units = units for y axis
  • nx_bins = force root_histogram to use this number of bins for the x-axis rather than choosing number of bins itself
  • ny_bins = force root_histogram to use this number of bins for the y-axis rather than choosing number of bins itself
  • canvas = if canvas=None, root_histogram will create a new tcanvas and plot histograms on that else will plot on the existing canvas, attempting to plot on existing axes
  • xmin = float that overrides auto-detection of minimum x-axis value
  • xmax = float that overrides auto-detection of maximum x-axis value
  • ymin = float that overrides auto-detection of minimum y-axis value
  • ymax = float that overrides auto-detection of maximum y-axis value
  • line_color = int that sets the line colour of the histogram
  • line_style = int that sets the line style of the histogram
  • line_width = int that sets the line width of the histogram
  • fill_color = int that sets the fill color of the histogram
  • stats = set to True to plot a stats box on the histogram
  • hist_title_string = specify the string that will appear as a title on the canvas

e.g. bunch.root_histogram('x', 'cm', 'py', 'GeV/c') will histogram x vs py. Returns a tuple of the (canvas, histogram)

Definition at line 1642 of file Bunch.py.

Referenced by Bunch.build_penn_ellipse().

def root_scatter_graph (   self,
  x_axis_string,
  y_axis_string,
  x_axis_units = '',
  y_axis_units = '',
  include_weightless = True,
  canvas = None,
  xmin = None,
  xmax = None,
  ymin = None,
  ymax = None,
  line_color = rg.line_color,
  line_style = rg.line_style,
  line_width = rg.line_width,
  fill_color = rg.graph_fill_color,
  hist_title_string = '' 
)

Prints a 2d scatter plot of Hit.get(...) data over a dict of bunches.

Needs correct root installation.

  • x_axis_string = string for call to Bunch.get_hit_variable() used to calculate x-values
  • x_axis_units = units for x axis
  • y_axis_string = string for call to Bunch.get_hit_variable() used to calculate y-values
  • y_axis_units = units for y axis
  • include_weightless = set to True to plot hits with <= 0. weight
  • canvas = if canvas=None, root_graph will create a new tcanvas and plot graphs on that else will plot on the existing canvas, attempting to plot on existing axes
  • xmin = float that overrides auto-detection of minimum x-axis value
  • xmax = float that overrides auto-detection of maximum x-axis value
  • ymin = float that overrides auto-detection of minimum y-axis value
  • ymax = float that overrides auto-detection of maximum y-axis value
  • line_color = int that sets the line colour of the histogram
  • line_style = int that sets the line style of the histogram
  • line_width = int that sets the line width of the histogram
  • fill_color = int that sets the fill color of the histogram
  • hist_title_string = specify the string that will appear as a title on the canvas

e.g. bunch.root_scatter_graph('x', 'p', 'cm', 'MeV/c') will graph x vs p. Returns a tuple of (canvas, histogram, graph) where the histogram contains the axes

Definition at line 1702 of file Bunch.py.

References Bunch.__hits, Bunch.list_get_hit_variable(), Bunch.matplot_histogram(), and Bunch.matplot_scatter_graph().

Referenced by Bunch.histogram().

def root_graph (   bunches,
  x_axis_string,
  x_axis_list,
  y_axis_string,
  y_axis_list,
  x_axis_units = '',
  y_axis_units = '',
  canvas = '',
  comparator = None,
  xmin = None,
  xmax = None,
  ymin = None,
  ymax = None,
  line_color = rg.line_color,
  line_style = rg.line_style,
  line_width = rg.line_width,
  fill_color = rg.graph_fill_color,
  hist_title_string = '' 
)

Prints a graph of Bunch.get(...) data over a set of bunches and returns the root canvas.

Needs correct root installation.

  • bunches = either a dict or a list of bunches
  • x_axis_string = string for call to Bunch.get() used to calculate x axis variables
  • x_axis_list = list of variables for call to Bunch.get() used to calculate x axis variables
  • x_axis_units = units for x axis
  • y_axis_string = string for call to Bunch.get() used to calculate y axis variables
  • y_axis_list = list of variables for call to Bunch.get() used to calculate y axis variables
  • y_axis_units = units for y axis
  • canvas = if canvas=None, root_graph will create a new tcanvas and plot graphs on that else will plot on the existing canvas, attempting to plot on existing axes
  • comparator = comparator of bunch1, bunch2 - if none given, will sort by x-axis value
  • xmin = float that overrides auto-detection of minimum x-axis value
  • xmax = float that overrides auto-detection of maximum x-axis value
  • ymin = float that overrides auto-detection of minimum y-axis value
  • ymax = float that overrides auto-detection of maximum y-axis value
  • line_color = int that sets the line colour of the histogram
  • line_style = int that sets the line style of the histogram
  • line_width = int that sets the line width of the histogram
  • fill_color = int that sets the fill color of the histogram
  • hist_title_string = specify the string that will appear as a title on the canvas

e.g. root_graph(bunch_dict, 'mean', ['x'], 'emittance', ['x','y'], 'cm', 'mm') will graph mean x vs emittance x y. Returns a tuple of (canvas, histogram, graph) where the histogram contains the axes

Definition at line 1753 of file Bunch.py.

References Bunch.get_hit_variable(), and Bunch.matplot_graph.

def matplot_histogram (   self,
  x_axis_string,
  x_axis_units = '',
  y_axis_string = '',
  y_axis_units = '',
  canvas = None,
  comparator = None 
)

Prints a 1D or 2D histogram of hits in the bunch.

Axes are automatically detected to encapsulate all data. Use Bunch.cut(...) to shrink the axes.

Needs correct matplot installation.

  • x_axis_string = string for call to get_hit_variables()
  • x_axis_units = units for x axis
  • y_axis_string = string for call to get_hit_variables(). If string is empty, makes a 1D histogram
  • y_axis_units = units for y axis
  • comparator = comparator of bunch1, bunch2 - if none given, will sort by x-axis value

e.g. bunch.matplot_histogram('x', 'cm', 'py', 'GeV/c') will histogram x vs py.

To display plots, call Common.wait_for_matplot() - script waits until all matplot windows are closed

Definition at line 1802 of file Bunch.py.

References Bunch.__ang_mom_for_get(), Bunch.__cov_mat_picker(), Bunch.__covs, Bunch.__dispersion_for_get(), Bunch.__dispersion_prime_for_get(), Bunch.__mean_for_get(), Bunch.__mean_picker(), Bunch.__means, Bunch.__weight_for_get(), Bunch.bunch_weight(), Bunch.get_dispersion(), Bunch.get_dispersion_prime(), Bunch.get_kinetic_angular_momentum(), and Bunch.mean().

Referenced by Bunch.root_scatter_graph().

def matplot_scatter_graph (   self,
  x_axis_string,
  y_axis_string,
  x_axis_units = '',
  y_axis_units = '',
  include_weightless = True 
)

Prints a 2d scatter plot of Hit.get(...) data over a dict of bunches.

Needs correct matplot installation.

  • x_axis_string = string for call to Bunch.get_hit_variable() used to calculate x-values
  • x_axis_units = units for x axis
  • y_axis_string = string for call to Bunch.get_hit_variable() used to calculate y-values
  • y_axis_units = units for y axis
  • include_weightless = set to True to plot hits with <= 0. weight

e.g. bunch.matplot_scatter_graph('x', 'cm', 'p', 'MeV/c') will graph x vs p.

To display plots, call Common.wait_for_matplot() - script waits until all matplot windows are closed

Definition at line 1842 of file Bunch.py.

References Bunch.__means, and Bunch.bunch_overview_doc.

Referenced by Bunch.root_scatter_graph().

def matplot_graph (   bunches,
  x_axis_string,
  x_axis_list,
  y_axis_string,
  y_axis_list,
  x_axis_units = '',
  y_axis_units = '',
  comparator = None 
)

Prints a graph of Bunch.get(...) data over a dict of bunches.

Needs correct matplot installation.

  • x_axis_string = string for call to Bunch.get() used to calculate x axis variables
  • x_axis_list = list of variables for call to Bunch.get() used to calculate x axis variables
  • y_axis_string = string for call to Bunch.get() used to calculate y axis variables
  • y_axis_list = list of variables for call to Bunch.get() used to calculate y axis variables
  • x_axis_units = units for x axis
  • y_axis_units = units for y axis
  • comparator = comparator of bunch1, bunch2 - if none given, will sort by x-axis value

e.g. bunch.matplot_graph('mean', ['x'], 'cm', 'emittance', ['x','y'], 'mm') will graph mean x vs emittance x y.

To display plots, call Common.wait_for_matplot() - script waits until all matplot windows are closed

Definition at line 1871 of file Bunch.py.

def __mean_for_get (   self,
  variable_list 
)
private

Definition at line 1894 of file Bunch.py.

Referenced by Bunch.matplot_histogram().

def __weight_for_get (   self,
  variable_list 
)
private

Definition at line 1897 of file Bunch.py.

Referenced by Bunch.matplot_histogram().

def __ang_mom_for_get (   self,
  variable_list 
)
private

Definition at line 1900 of file Bunch.py.

Referenced by Bunch.matplot_histogram().

def __dispersion_for_get (   self,
  variable_list 
)
private

Definition at line 1903 of file Bunch.py.

Referenced by Bunch.matplot_histogram().

def __dispersion_prime_for_get (   self,
  variable_list 
)
private

Definition at line 1906 of file Bunch.py.

Referenced by Bunch.matplot_histogram().

def __cov_mat_picker (   self,
  axis_list 
)
private
def __mean_picker (   self,
  var_list 
)
private

Definition at line 1924 of file Bunch.py.

Referenced by Bunch.matplot_histogram().

def bunch_overview_doc (   verbose = False)

Creates some summary documentation for the Bunch class.

If verbose is True then will also print any functions or data not included in summary

Definition at line 1948 of file Bunch.py.

Member Data Documentation

tuple new_from_hits = staticmethod(new_from_hits)
static

Definition at line 185 of file Bunch.py.

Referenced by Bunch.__eq__().

tuple new_dict_from_read_builtin = staticmethod(new_dict_from_read_builtin)
static

Definition at line 219 of file Bunch.py.

Referenced by Bunch.append().

tuple new_list_from_read_builtin = staticmethod(new_list_from_read_builtin)
static

Definition at line 247 of file Bunch.py.

Referenced by Bunch.new_dict_from_read_builtin().

tuple new_from_read_builtin = staticmethod(new_from_read_builtin)
static

Definition at line 280 of file Bunch.py.

tuple new_from_read_user = staticmethod(new_from_read_user)
static

Definition at line 307 of file Bunch.py.

Referenced by Bunch.new_from_read_builtin().

tuple new_hit_shell = staticmethod(new_hit_shell)
static

Definition at line 333 of file Bunch.py.

tuple get_list_of_maus_dicts = staticmethod(get_list_of_maus_dicts)
static

Definition at line 358 of file Bunch.py.

tuple read_maus_root_file = staticmethod(read_maus_root_file)
static

Definition at line 389 of file Bunch.py.

tuple read_maus_file = staticmethod(read_maus_file)
static

Definition at line 425 of file Bunch.py.

tuple read_g4mice_file = staticmethod(read_g4mice_file)
static

Definition at line 457 of file Bunch.py.

Referenced by Bunch.read_maus_file().

tuple setup_file = staticmethod(setup_file)
static

Definition at line 482 of file Bunch.py.

tuple clear_global_weights = staticmethod(clear_global_weights)
static

Definition at line 814 of file Bunch.py.

Referenced by Bunch.set_covariance_matrix().

tuple momentum_variable = staticmethod(momentum_variable)
static
tuple get_amplitude = staticmethod(get_amplitude)
static

Definition at line 1223 of file Bunch.py.

Referenced by Bunch.get_emittance().

tuple axis_list_to_covariance_list = staticmethod(axis_list_to_covariance_list)
static

Definition at line 1239 of file Bunch.py.

Referenced by Bunch.get_canonical_angular_momentum().

tuple convert_string_to_axis_list = staticmethod(convert_string_to_axis_list)
static

Definition at line 1259 of file Bunch.py.

Referenced by Bunch.momentum_variable().

tuple set_geometric_momentum = staticmethod(set_geometric_momentum)
static

Definition at line 1269 of file Bunch.py.

tuple get_geometric_momentum = staticmethod(get_geometric_momentum)
static

Definition at line 1279 of file Bunch.py.

tuple get_axes = staticmethod(get_axes)
static

Definition at line 1285 of file Bunch.py.

tuple list_get = staticmethod(list_get)
static

Definition at line 1380 of file Bunch.py.

tuple get_variables = staticmethod(get_variables)
static

Definition at line 1386 of file Bunch.py.

tuple hit_get_variables = staticmethod(hit_get_variables)
static

Definition at line 1392 of file Bunch.py.

tuple hit_write_builtin_from_dict = staticmethod(hit_write_builtin_from_dict)
static

Definition at line 1428 of file Bunch.py.

Referenced by Bunch.list_get_hit_variable().

tuple build_ellipse_2d = staticmethod(build_ellipse_2d)
static

Definition at line 1485 of file Bunch.py.

Referenced by Bunch.list_get().

tuple build_MR_ellipse = staticmethod(build_MR_ellipse)
static

Definition at line 1494 of file Bunch.py.

tuple build_ET_ellipse = staticmethod(build_ET_ellipse)
static

Definition at line 1503 of file Bunch.py.

tuple build_ellipse_from_transfer_matrix = staticmethod(build_ellipse_from_transfer_matrix)
static

Definition at line 1512 of file Bunch.py.

tuple build_penn_ellipse = staticmethod(build_penn_ellipse)
static

Definition at line 1550 of file Bunch.py.

tuple root_graph = staticmethod(root_graph)
static

Definition at line 1783 of file Bunch.py.

Referenced by Bunch.histogram_var_bins().

tuple matplot_graph = staticmethod(matplot_graph)
static

Definition at line 1890 of file Bunch.py.

Referenced by Bunch.root_graph().

dictionary __g4mice_types = {'g4mice_special_hit':'SpecialHits', 'g4mice_virtual_hit':'VirtualHits'}
staticprivate

Definition at line 1934 of file Bunch.py.

dictionary __number_of_header_lines = {'icool_for009':3, 'icool_for003':2, 'g4beamline_bl_track_file':0,'g4mice_special_hit':0,'g4mice_virtual_hit':0,'zgoubi':0, 'turtle':0, 'madx':0,'mars_1':0, 'maus_virtual_hit':0, 'maus_primary':0, 'opal_loss':1, 'muon1_csv':0}
staticprivate

Definition at line 1935 of file Bunch.py.

list __axis_list = ['x','y','z','t', 'ct']
staticprivate

Definition at line 1936 of file Bunch.py.

dictionary __get_dict
staticprivate
Initial value:
1 = {'angular_momentum':__ang_mom_for_get, 'emittance':get_emittance, 'dispersion':__dispersion_for_get,
2  'dispersion_prime':__dispersion_prime_for_get, 'beta':get_beta, 'alpha':get_alpha, 'gamma':get_gamma,
3  'moment':moment, 'mean':__mean_for_get, 'bunch_weight':__weight_for_get, 'standard_deviation':standard_deviation}

Definition at line 1937 of file Bunch.py.

__geometric_momentum = False
staticprivate

Definition at line 1940 of file Bunch.py.

list __get_list = []
staticprivate

Definition at line 1942 of file Bunch.py.

tuple bunch_overview_doc = staticmethod(bunch_overview_doc)
static

Definition at line 2005 of file Bunch.py.

Referenced by Bunch.matplot_scatter_graph().

__hits
private
__bunchcore
private

Definition at line 68 of file Bunch.py.

Referenced by Bunch.__init__().

__covs
private
__means
private

The documentation for this class was generated from the following file: