simba.Modules.Beams package

Subpackages

simba.Modules.Beams.Particles package

Submodules

simba.Modules.Beams.astra module

cdist(a, b)[source]

convert_csrtrackfile_to_astrafile(self, csrtrackfile, astrafile)[source]

create_ref_particle(self, array, index=0, subtractmean=False)[source]

find_nearest_vector(self, nodes, node)[source]

interpret_astra_data(self, data, normaliseZ=False, keepLost=False)[source]

read_astra_beam_file(self, filename, normaliseZ=False, keepLost=False)[source]

read_csrtrack_beam_file(self, filename)[source]

read_csv_file(self, filename, delimiter=' ')[source]

read_pacey_beam_file(self, filename, charge=2.5e-10)[source]

rms(self, x, axis=None)[source]

write_astra_beam_file(self, filename=None, index=None, status=5, normaliseZ=False, zoffset=0.0)[source]

Parameters:

filename (Optional[str])
index (Optional[int])
status (int)
normaliseZ (bool)
zoffset (float)

write_csv_file(self, filename, data)[source]

simba.Modules.Beams.cheetah module

interpret_cheetah_ParticleBeam(self, parray, zstart=0, s=0, ref_index=None)[source]

read_cheetah_beam_file(self, filename, beam_energy, zstart=0, s=0, ref_index=None)[source]

write_cheetah_beam_file(self, filename=None, write=True)[source]: Save an openpmd file for cheetah.

simba.Modules.Beams.gdf module

read_gdf_beam_file(self, filename=None, position=None, time=None, charge=None, longitudinal_reference='t', gdfbeam=None)[source]

read_gdf_beam_file_info(self, file)[source]

read_gdf_beam_file_object(self, file)[source]

write_gdf_beam_file(self, filename=None, normaliseX=False, normaliseZ=False, cathode=False, charge=None, mass=None, zoffset=0.0)[source]

Parameters:

filename (Optional[str])
normaliseX (bool)
normaliseZ (bool)
cathode (bool)
charge (Optional[float])
mass (Optional[float])
zoffset (float)

simba.Modules.Beams.hdf5 module

read_HDF5_beam_file(self, filename, local=False)[source]

rotate_beamXZ(self, theta, preOffset=[0, 0, 0], postOffset=[0, 0, 0])[source]

unrotate_beamXZ(self)[source]

write_HDF5_beam_file(self, filename, centered=False, mass=9.1093837015e-31, sourcefilename=None, pos=None, rotation=None, longitudinal_reference='t', xoffset=0, yoffset=0, zoffset=0, toffset=0, cathode=False)[source]

write_HDF5_summary_file(filename, beams=[], clean=False)[source]

simba.Modules.Beams.mad8 module

read_tfs(tfs_file_path, index=None)[source]

Parses the TFS table present in tfs_file_path and returns a dictionary. :type tfs_file_path: str :param tfs_file_path: Path object to the output TFS file. :type tfs_file_path: str :type index: Optional[str] :param index: Name of the column to set as index. If not given, looks in tfs_file_path

for a column starting with INDEX&&&.

Returns:: Dictionary object.

read_tfs_beam_file(self, fileName, charge=None)[source]

set_beam_charge(self, charge)[source]

write_mad8_beam_file(self, filename)[source]: Save a mad8 beam file using multiple START commands.

simba.Modules.Beams.ocelot module

particle_array_to_beam(self, parray, zstart=0, s=0, ref_index=None)[source]

particle_group_to_parray(self, s_start=0)[source]

Construct an Ocelot ParticleArray from an openPMD-beamphysics ParticleGroup. The particle type is assumed to be electrons.

Parameters:: pgroup – ParticleGroup from which to construct the ParticleArray
Returns:: ParticleArray corresponding to the provided ParticleGroup
Return type:: ParticleArray

read_ocelot_beam_file(self, filename)[source]

write_ocelot_beam_file(self, filename, write=True)[source]: Save an npz file for ocelot.

simba.Modules.Beams.opal module

find_nearest(array, value)[source]

find_opal_s_positions(filename, spos, tolerance=0.1)[source]

read_opal_beam_file(self, filename, step=0)[source]

write_opal_beam_file(self, filename, subz=0, emitted=False)[source]: Save a text file for opal.

simba.Modules.Beams.openpmd module

read_openpmd_beam_file(self, filename)[source]

write_openpmd_beam_file(self, filename, pos=[0, 0, 0], toffset=0)[source]

write_openpmd_reference_particle(self, h5)[source]

Parameters:: h5 (File)

simba.Modules.Beams.plot module

density_plot(particle_group, key='x', bins=None, filename=None, **kwargs)[source]

1D density plot. Also see: marginal_plot

Example

density_plot(P, ‘x’, bins=100)

getScreenImage(beam, keys=['x', 'y'], scale=[1, 1], iscale=1, colormap=<matplotlib.colors.LinearSegmentedColormap object>, size=None, use_scipy=False, subtract_mean=[False, False], **kwargs)[source]

marginal_plot(particle_group, key1='t', key2='p', bins=None, units=['', ''], scale=[1, 1], subtract_mean=[False, False], cmap=None, limits=None, filename=None, **kwargs)[source]

Density plot and projections

Example

marginal_plot(P, ‘t’, ‘energy’, bins=200)

plot(self, keys=None, bins=None, type='density', **kwargs)[source]

plotScreenImage(beam, keys=['x', 'y'], scale=[1, 1], iscale=1, colormap=<matplotlib.colors.LinearSegmentedColormap object>, size=None, grid=False, marginals=False, limits=None, screen=False, use_scipy=False, subtract_mean=[False, False], title='', filename=None, fig=None, ax=None, labelsize=None, **kwargs)[source]

slice_plot(particle_group, xkey='t', ykey='slice_current', xlim=None, nice=True, include_legend=True, subtract_mean=True, bins=None, filename=None, **kwargs)[source]

slice plot. Also see: marginal_plot

Example

slice plot(P, ‘slice_current’, bins=100)

simba.Modules.Beams.sdds module

read_SDDS_beam_file(self, fileName, charge=None, ascii=False, page=-1, xyzoffset=[0, 0, 0], ref_index=None)[source]

set_beam_charge(self, charge)[source]

write_SDDS_file(self, filename=None, ascii=False, xyzoffset=[0, 0, 0])[source]

Save an SDDS file using the SDDS class.

Parameters:: filename (Optional[str])

simba.Modules.Beams.vsim module

read_vsim_h5_beam_file(self, filename, charge=7e-11, interval=1)[source]

write_vsim_beam_file(self, file, normaliseT=False)[source]

simba.Modules.Beams.wake_t module

beam_to_particle_bunch(self, zstart=0)[source]: Convert the internal beam representation to a Wake-T ParticleBunch.

particle_bunch_to_beam(self, bunch, zpos=0)[source]

read_wake_t_beam_file(self, filename, z_offset=0, charge=None)[source]

simba.Modules.Beams.xsuite module

read_xsuite_beam_file(self, filename, zstart=0, s=0, ref_index=None)[source]

write_xsuite_beam_file(self, filename=None, write=True, s_start=0)[source]

Save a json file for xsuite.

Parameters:

filename (Optional[str])
write (bool)
s_start (float)

Module contents

SIMBA Beams Module

This module defines the base class and utilities for representing particle beams and groups of beams.

Each beam consists of particles (see Particles), represented in 6-dimensional phase space (x, cpx, y, cpy, z, cpz).

Functions are provided to read/write the particle distribution from a range of simulation codes.

The beamGroup class is used for loading and analysing a group of beam distributions, for example from a directory.

Classes:

beam: Generic container for a particle beam.
beamGroup: Container for a group of particle beams.
particlesGroup: Container for a group of particle distributions.

class beam(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Class describing a particle distribution. The distribution is contained in the beam or Particles property of this class (see Particles).

Additional results from analysis of the beam are contained in the following properties:

sigmas – average beam properties,

see sigmas.

centroids – beam centroids,

see centroids.

centroids – various emittance calculations,

see emittance.

kde – kernel density estimator,

see kde.

mve – minimum volume ellipse,

see MVE.

slices – calculations of slice properties,

see slice.

twiss – Twiss parameters,

see twiss.

Functions are also provided for translating the particle distribution from and to HDF5 format (in-house developed or OpenPMD), ASTRA, GPT, OCELOT, or SDDS.

property E0_eV: float

Particle rest mass energy in eV

Returns:: Particle rest mass energy in eV; if already defined, just return the attribute; if not, calculate from the Particles object; if not possible, assume electrons and calculate its rest mass energy
Return type:: float

property Particles: Particles

Property defining the particle distribution

Returns:: The particle distribution
Return type:: Particles

property beam: Particles

Property defining the particle distribution

Returns:: The particle distribution
Return type:: Particles

beam_energy: float | None = None: Beam energy [required for Cheetah]

property centroids: centroids

Property defining the beam centroids

Returns:: Beam centroids
Return type:: centroids

code: str | None = None: Code from which the beam distribution was generated

property data: <property object at 0x77336bd4e340>

Property defining the particle distribution

Returns:: The particle distribution
Return type:: Particles

property emittance: emittance

Property defining the beam emittances

Returns:: Beam emittance
Return type:: emittance

filename: str | None = None: Name of beam distribution file; if provided on instantiation, load the file into this object

property fullbeam

property kde: kde

Property defining the beam kernel density estimator

Returns:: KDE
Return type:: kde

longitudinal_reference: ndarray | str | None = None: Longitudinal reference position for ASTRA-type distributions

property mve: Any

Property defining the beam minimum volume ellipse

Returns:: Beam sigmas
Return type:

normalise_to_ref_particle(array, index=0, subtractmean=False)[source]

Normalise a distribution to the first element in the array (i.e. the ASTRA reference particle)

Parameters:

array (np.ndarray) – The array to normalise
index (int) – Not in use
subtractmean (bool) – If true, subtract the reference particle from the array

Returns:

The normalised array

Return type:

np.ndarray

offset: list | ndarray = [0, 0, 0]: Beam offset from nominal axis [x,y,z]

particle_mass: ndarray | None = None: Particle mass in kg

plot(**kwargs)[source]

plotScreenImage(**kwargs)[source]

q_over_c: UnitValue = 5.344285992678308e-28 C/c: Elementary charge divided by speed of light

read_HDF5_beam_file(*args, **kwargs)[source]: Load in an HDF5-type beam distribution file and update the Particles object.

read_SDDS_beam_file(*args, **kwargs)[source]: Load in an SDDS-type beam distribution file and update the Particles object.

read_astra_beam_file(*args, **kwargs)[source]: Load in an ASTRA-type beam distribution file and update the Particles object.

read_beam_file(filename, run_extension='001', beam_energy=None, step=0)[source]

Load in a beam distribution file and update the Particles object.

Based on the extension in filename, the appropriate function will be called.

Parameters:

filename (str) – The name of the file to be loaded
run_extension (str) – Run extension for ASTRA-type beam distribution files.
beam_energy (float, optional) – Beam energy in eV (for Cheetah beam distributions)
step (int, optional) – Step number in output file (for OPAL beam distributions)

read_cheetah_beam_file(*args, **kwargs)[source]

read_gdf_beam_file(*args, **kwargs)[source]: Load in a GDF-type beam distribution file and update the Particles object.

read_ocelot_beam_file(*args, **kwargs)[source]: Load in an OCELOT-type beam distribution file and update the Particles object.

read_opal_beam_file(*args, **kwargs)[source]: Load in an OPAL-type beam distribution file and update the Particles object.

read_xsuite_beam_file(*args, **kwargs)[source]: Load in an Xsuite-type beam distribution file and update the Particles object.

reference_particle: ndarray | None = None: Reference particle for ASTRA-type distributions

reference_particle_coords: list = ['x', 'y', 'z', 'cpx', 'cpy', 'cpz', 't', 'charge', 'status']

reference_particle_index: int | None = None: Reference particle index for ASTRA-type distributions

resample(npart, **kwargs)[source]

Resample the beam using a kernel density estimator, updating the number of particles. See kde.

Parameters:: npart (int) – Number of particles for the new distribution
Returns:: The resampled beam.
Return type:: beam

reset_dicts()[source]

Clear out the Particles object, removing the distribution from this object.

Return type:: None

rms(x, axis=None)[source]

Calculate the RMS of a distribution

Parameters:

x (np.ndarray) – Array from which to calculate the RMS
axis (int, optional) – Axis along which to calculate the RMS

Returns:

RMS of the distribution

Return type:

float or np.ndarray

rotate_beamXZ(theta, preOffset=[0, 0, 0], postOffset=[0, 0, 0])[source]

sddsindex: int = 0: Index for SDDS files

set_particle_mass(mass=9.1093837015e-31)[source]

Set the mass of all particles in the distribution by updating particle_mass.

Parameters:: mass (float) – Particle mass in kg
Return type:: None

set_species(value)[source]

property sigmas: sigmas

Property defining the beam sigmas

Returns:: Beam sigmas
Return type:: sigmas

property slice: slice

Property defining the beam slice properties

Returns:: Beam slice properties
Return type:: slice

slice_plot(*args, **kwargs)[source]

species: str = 'electron'

speed_of_light: UnitValue = 299.792458 Mm/s: Speed of light

starting_position: list | ndarray = [0, 0, 0]: Beam starting position [x,y,z]

property status

theta: float = 0: Horizontal angle of beam distribution

property twiss: twiss

Property defining the beam twiss properties

Returns:: Beam Twiss parameters
Return type:: twiss

unrotate_beamXZ()[source]

write_HDF5_beam_file(*args, **kwargs)[source]: Write out an HDF5-type beam distribution file.

write_SDDS_beam_file(*args, **kwargs)[source]: Write out an SDDS-type beam distribution file.

write_astra_beam_file(*args, **kwargs)[source]: Write out an ASTRA-type beam distribution file.

write_cheetah_beam_file(*args, **kwargs)[source]

write_gdf_beam_file(*args, **kwargs)[source]: Write out a GDF-type beam distribution file.

write_mad8_beam_file(*args, **kwargs)[source]: Write out a MAD8-type beam distribution file.

write_ocelot_beam_file(*args, **kwargs)[source]: Write out an OCELOT-type beam distribution file.

write_opal_beam_file(*args, **kwargs)[source]: Write out an OPAL-type beam distribution file.

write_openpmd_beam_file(*args, **kwargs)[source]: Write out an openpmd-type beam distribution file.

write_xsuite_beam_file(*args, **kwargs)[source]: Write out an Xsuite-type beam distribution file.

class beamGroup(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Class for grouping together multiple particle distributions. These distributions can be loaded in from a directory, for example, using the function load_directory().

Properties such as the emittance objects for these distributions are stored as properties of the beamGroup.

(see particlesGroup).

add(filename)[source]

beams: Dict = {}: Dictionary containing the beam objects, keyed by (file)name

property centroids

property data

property emittance

getScreen(screen)[source]

getScreens()[source]

property kde

property mve

param(param)[source]

sddsindex: int = 0: Index for SDDS files

property sigmas

property slice

sort(key='z', function='mean', *args, **kwargs)[source]

property twiss

get_properties(obj)[source]

load_HDF5_summary_file(filename)[source]

load_directory(directory='.', types={'SIMBA': '.hdf5'}, verbose=False)[source]

Load in all beam distribution files from a directory and create a beamGroup object.

Parameters:

directory (str) – Directory from which to load the files
types (Dict) – Beam distribution file types to load
verbose (bool) – If true, print progress

Returns:

A new beamGroup.

Return type:

beamGroup

load_file(filename, *args, **kwargs)[source]

Load in a beam distribution files and create a beam object.

Parameters:: filename (str) – Name of file to load
Returns:: A new beam.
Return type:: beam

class particlesGroup(*args, **kwargs)[source]

Bases: BaseModel

Class for grouping together properties of multiple particle distributions, such as the emittance objects.

Parameters:

args (Any)
kwargs (Any)

particles: List = None: List of Particles or its sub-classes

save_HDF5_summary_file(directory='.', filename='./Beam_Summary.hdf5', screens=None, files=None)[source]

Parameters:

directory (str)
filename (str)
screens (Optional[list])
files (Optional[list])

Return type:

None

class stats(beam, function)[source]: Bases: object

class statsGroup(beam, function)[source]

Bases: object

Class for grouping together statistical properties of multiple particle distributions.