Xpart API

The particle class

class xpart.Particles(**kwargs)

Particle objects have the following fields:

  • s [m]: Reference accumulated path length

  • x [m]: Horizontal position

  • px[1]: Px / (m/m0 * p0c) = beta_x gamma /(beta0 gamma0)

  • y [m]: Vertical position

  • py [1]: Py / (m/m0 * p0c)

  • delta[1]: (Pc m0/m - p0c) /p0c

  • ptau [1]: (Energy m0/m - Energy0) / p0c

  • pzeta [1]: ptau / beta0

  • rvv [1]: beta / beta0

  • rpp [1]: m/m0 P0c / Pc = 1/(1+delta)

  • zeta [m]: (s - beta0 c t )

  • tau [m]: (s / beta0 - ct)

  • mass0 [eV]: Reference rest mass

  • q0 [e]: Reference charge

  • p0c [eV]: Reference momentum

  • energy0 [eV]: Reference energy

  • gamma0 [1]: Reference relativistic gamma

  • beta0 [1]: Reference relativistic beta

  • mass_ratio [1]: mass/mass0 (this is used to track particles of

    different species. Note that mass is the rest mass of the considered particle species and not the relativistic mass)

  • chi [1]: q/ q0 * m0/m = qratio / mratio

  • charge_ratio [1]: q / q0

  • particle_id [int]: Identifier of the particle

  • at_turn [int]: Number of tracked turns

  • state [int]: It is <= 0 if the particle is lost, > 0 otherwise

    (different values are used to record information on how the particle is lost or generated).

  • weight [int]: Particle weight in number of particles

    (for collective sims.)

  • at_element [int]: Identifier of the last element through which

    the particle has been

  • parent_particle_id [int]: Identifier of the parent particle

    (secondary production processes)

start_tracking_at_element
init_pipeline(name)

Add attribute (for pipeline mode).

to_dict(copy_to_cpu=True, remove_underscored=None, remove_unused_space=None, remove_redundant_variables=None, keep_rng_state=None, compact=False)
to_pandas(remove_underscored=None, remove_unused_space=None, remove_redundant_variables=None, keep_rng_state=None, compact=False)
show()

Print particle properties.

get_classical_particle_radius0()

Get classical particle radius of the reference particle.

classmethod from_pandas(df, _context=None, _buffer=None, _offset=None)
classmethod merge(lst, _context=None, _buffer=None, _offset=None)

Merge a list of particles into a single particles object.

filter(mask)

Select a subset of particles satisfying a logical condition.

remove_unused_space()

Return a new particles object with removed no space in the particle arrays.

hide_lost_particles(_assume_reorganized=False)

Hide lost particles in the particles object.

unhide_lost_particles()

Unhide lost particles in the particles object.

property lost_particles_are_hidden
sort(by='particle_id', interleave_lost_particles=False)

Sort particles by particle ID or other veriabke.

reorganize()

Reorganize the particles object so that all active particles are at the beginning of the arrays.

add_particles(part, keep_lost=False)

Add particles to the Particles object.

get_active_particle_id_range()

Get the range of particle ids of active particles.

update_delta(new_delta_value)

Update the delta value of the particles object. ptau and rvv and rpp are updated accordingly.

property delta
update_ptau(new_ptau)

Update the ptau value of the particles object. delta and rvv and rpp are updated accordingly.

property ptau
property rvv
property rpp
property energy0
property energy
property pzeta
add_to_energy(delta_energy)

Add delta_energy to the energy of the particles object. delta, ‘ptau’, rvv and rpp are updated accordingly.

set_particle(index, set_scalar_vars=False, **kwargs)
at_element
at_turn
beta0
charge_ratio
chi
gamma0
mass0
p0c
parent_particle_id
particle_id
px
py
q0
s
state
weight
x
y
zeta

The build_particles function

xpart.build_particles(_context=None, _buffer=None, _offset=None, _capacity=None, mode=None, particle_ref=None, num_particles=None, x=None, px=None, y=None, py=None, zeta=None, delta=None, pzeta=None, x_norm=None, px_norm=None, y_norm=None, py_norm=None, zeta_norm=None, pzeta_norm=None, tracker=None, at_element=None, match_at_s=None, particle_on_co=None, R_matrix=None, W_matrix=None, method=None, nemitt_x=None, nemitt_y=None, scale_with_transverse_norm_emitt=None, weight=None, particles_class=None, **kwargs)

Function to create particle objects from arrays containing physical or normalized coordinates.

Parameters

  • mode (-) –

    choose between:

    • set: reference quantities including mass0, q0, p0c, gamma0, etc. are taken from the provided reference particle. Particles coordinates are set according to the provided input x, px, y, py, zeta, delta (zero is assumed as default for these variables).

    • shift: reference quantities including mass0, q0, p0c, gamma0, etc. are taken from the provided reference particle. Particles coordinates are set from the reference particles and shifted according to the provided input x, px, y, py, zeta, delta (zero is assumed as default for these variables).

    • normalized_transverse: reference quantities including mass0, q0, p0c, gamma0, etc. are taken from the provided reference particle. The longitudinal coordinates are set according to the provided input zeta, delta (zero is assumed as default value for these variable`. The transverse coordinates are computed from normalized values x_norm, px_norm, y_norm, py_norm using the closed-orbit information and the linear transfer map obtained from the tracker or provided by the user.

    The default mode is set. normalized_transverse is used if any of x_norm, px_norm, y_norm, pynorm is provided.

  • particle_ref (-) – particle object defining the reference quantities (mass0, 0, p0c, gamma0, etc.). Its coordinates (x, py, y, py, zeta, delta) are ignored unless `mode`=’shift’ is selected.

  • num_particles (-) – Number of particles to be generated (used if provided coordinates are all scalar)

  • x (-) – x coordinate of the particles (default is 0).

  • px (-) – px coordinate of the particles (default is 0).

  • y (-) – y coordinate of the particles (default is 0).

  • py (-) – py coordinate of the particles (default is 0).

  • zeta (-) – zeta coordinate of the particles (default is 0).

  • delta (-) – delta coordinate of the particles (default is 0).

  • x_norm (-) – transverse normalized coordinate x (in sigmas) used in combination with the one turn matrix R_matrix and with the transverse emittances provided in the argument scale_with_transverse_norm_emitt to generate x, px, y, py (x, px, y, py cannot be provided if x_norm, px_norm, y_norm, py_norm are provided).

  • x_norm – transverse normalized coordinate x (in sigmas).

  • px_norm (-) – transverse normalized coordinate px (in sigmas).

  • y_norm (-) – transverse normalized coordinate y (in sigmas).

  • py_norm (-) – transverse normalized coordinate py (in sigmas).

  • tracker (-) – tracker object used to find the closed orbit and the one-turn matrix.

  • particle_on_co (-) – Particle on closed orbit

  • R_matrix (-) – 6x6 matrix defining the linearized one-turn map to be used for the transformation of the normalized coordinates into physical space.

  • W_matrix (-) – 6x6 matrix with the eigenvalues of the one-turn map (R_matrix). If provided, the R_matrix can be omitted.

  • nemitt_x (-) – transverse normalized emittance in x.

  • nemitt_y (-) – transverse normalized emittance in y.

  • weight (-) – weights to be assigned to the particles.

  • at_element (-) – location within the line at which particles are generated. It can be an index or an element name. It can be given only if at_tracker is provided and transverse_mode is “normalized”.

  • match_at_s (-) – s coordinate of a location in the drifts downstream the specified at_element at which the particles are generated before being backdrifted to the location specified by at_element. No active element can be present in between.

  • _context (-) – xobjects context in which the particle object is allocated.

Longitudinal coordinates generation

xpart.generate_longitudinal_coordinates(tracker=None, particle_ref=None, mass0=None, q0=None, gamma0=None, num_particles=None, circumference=None, momentum_compaction_factor=None, rf_harmonic=None, rf_voltage=None, rf_phase=None, p_increment=0.0, distribution='gaussian', sigma_z=None, engine='pyheadtail', return_matcher=False, **kwargs)

Normalized transverse coordinates generation

Gaussian

xpart.generate_2D_gaussian(num_particles)

Polar grid

xpart.generate_2D_polar_grid(r_range=None, r_grid=None, dr=None, nr=None, theta_range=None, theta_grid=None, dtheta=None, ntheta=None)

Uniform circular sector

xpart.generate_2D_uniform_circular_sector(num_particles, r_range=(0, 1), theta_range=(0, 6.283185307179586))

Pencil

xpart.generate_2D_pencil(num_particles, pos_cut_sigmas, dr_sigmas, side='+')

Gaussian bunch generation (6D)

xpart.generate_matched_gaussian_bunch(num_particles, nemitt_x, nemitt_y, sigma_z, total_intensity_particles=None, particle_on_co=None, R_matrix=None, circumference=None, momentum_compaction_factor=None, rf_harmonic=None, rf_voltage=None, rf_phase=None, p_increment=0.0, tracker=None, particle_ref=None, particles_class=None, engine='pyheadtail', _context=None, _buffer=None, _offset=None, **kwargs)