Xfields API¶
Table of Contents
Beam elements¶
Space Charge 3D¶
- class xfields.SpaceCharge3D(_context=None, _buffer=None, _offset=None, update_on_track=True, length=None, apply_z_kick=True, fieldmap=None, x_range=None, y_range=None, z_range=None, nx=None, ny=None, nz=None, dx=None, dy=None, dz=None, x_grid=None, y_grid=None, z_grid=None, rho=None, phi=None, solver=None, gamma0=None, fftplan=None)¶
Simulates the effect of space charge on a bunch.
- Parameters
context (XfContext) – identifies the context on which the computation is executed.
update_on_track (bool) – If
True
the beam field map is update at each interaction. IfFalse
the initial field map is used at each interaction (frozen model). The default isTrue
.length (float) – the length of the space-charge interaction in meters.
apply_z_kick (bool) – If
True
, the longitudinal kick on the particles is applied.x_range (tuple) – Horizontal extent (in meters) of the computing grid.
y_range (tuple) – Vertical extent (in meters) of the computing grid.
z_range (tuple) – Longitudina extent (in meters) of the computing grid.
nx (int) – Number of cells in the horizontal direction.
ny (int) – Number of cells in the vertical direction.
nz (int) – Number of cells in the vertical direction.
dx (float) – Horizontal cell size in meters. It can be provided alternatively to
nx
.dy (float) – Vertical cell size in meters. It can be provided alternatively to
ny
.dz (float) – Longitudinal cell size in meters.It can be provided alternatively to
nz
.x_grid (np.ndarray) – Equispaced array with the horizontal grid points (cell centers). It can be provided alternatively to
x_range
,dx
/nx
.y_grid (np.ndarray) – Equispaced array with the horizontal grid points (cell centers). It can be provided alternatively to
y_range
,dy
/ny
.z_grid (np.ndarray) – Equispaced array with the horizontal grid points (cell centers). It can be provided alternatively to
z_range
,dz
/nz
.rho (np.ndarray) – initial charge density at the grid points in Coulomb/m^3.
phi (np.ndarray) – initial electric potential at the grid points in Volts. If not provided the
phi
is calculated fromrho
using the Poisson solver (if available).solver (str or solver object) – Defines the Poisson solver to be used to compute phi from rho. Accepted values are
FFTSolver3D
andFFTSolver2p5D
. A Xfields solver object can also be provided. In caseupdate_on_track``is ``False
andphi
is provided by the user, this argument can be omitted.gamma0 (float) – Relativistic gamma factor of the beam. This is required only if the solver is
FFTSolver3D
.
- Returns
A space-charge 3D beam element.
- Return type
- copy(_context=None, _buffer=None, _offset=None)¶
- property iscollective¶
bool(x) -> bool
Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
- track(particles)¶
Computes and applies the space-charge forces for the provided set of particles.
- Parameters
particles (Particles Object) – Particles to be tracked.
Space Charge Bi-Gaussian¶
- class xfields.SpaceChargeBiGaussian(_context=None, _buffer=None, _offset=None, update_on_track=False, length=None, apply_z_kick=False, longitudinal_profile=None, mean_x=0.0, mean_y=0.0, sigma_x=None, sigma_y=None, fieldmap=None, min_sigma_diff=1e-10, **kwargs)¶
- to_dict()¶
- track(particles)¶
- property iscollective¶
bool(x) -> bool
Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
- property mean_x¶
- property mean_y¶
- property sigma_x¶
- property sigma_y¶
Beam-beam Bi-Gaussian 2D¶
- class xfields.BeamBeamBiGaussian2D(_context=None, _buffer=None, _offset=None, _xobject=None, n_particles=None, q0=None, beta0=None, mean_x=0.0, mean_y=0.0, sigma_x=None, sigma_y=None, d_px=0.0, d_py=0.0, min_sigma_diff=1e-28, fieldmap=None, **kwargs)¶
Simulates the effect of beam-beam on a bunch.
- Parameters
context (xobjects context) – identifies the context on which the computation is executed.
n_particles (float64) – Number of particles in the colliding bunch.
q0 (float64) – Number of particles in the colliding bunch.
beta0 (float64) – Relativistic beta of the colliding bunch.
mean_x (float64) – Horizontal position (in meters) of the colliding bunch. It can be updated after the object creation. Default is
0.
.mean_y (float64) – Vertical position (in meters) of the Gaussian distribution. It can be updated after the object creation. Default is
0.
.sigma_x (float64) – Horizontal r.m.s. size (in meters) of the colliding bunch. It can be updated after the object creation. Default is
None
.sigma_y (float64) – Vertical r.m.s. size (in meters) of the colliding bunch. It can be updated after the object creation. Default is
None
.
- Returns
A beam-beam element.
- Return type
- to_dict()¶
- update(**kwargs)¶
- property mean_x¶
- property mean_y¶
- property sigma_x¶
- property sigma_y¶
Beam-beam Bi-Gaussian 3D¶
Field Maps¶
Beam-beam Tri-linear Iterpolated Field Map¶
- class xfields.fieldmaps.TriLinearInterpolatedFieldMap(_context=None, _buffer=None, _offset=None, x_range=None, y_range=None, z_range=None, nx=None, ny=None, nz=None, dx=None, dy=None, dz=None, x_grid=None, y_grid=None, z_grid=None, rho=None, phi=None, solver=None, scale_coordinates_in_solver=(1.0, 1.0, 1.0), updatable=True, fftplan=None)¶
Builds a linear interpolator for a 3D field map. The map can be updated using the Parcle In Cell method.
- Parameters
context (xobjects context) – identifies the context on which the computation is executed.
x_range (tuple) – Horizontal extent (in meters) of the computing grid.
y_range (tuple) – Vertical extent (in meters) of the computing grid.
z_range (tuple) – Longitudina extent (in meters) of the computing grid.
nx (int) – Number of cells in the horizontal direction.
ny (int) – Number of cells in the vertical direction.
nz (int) – Number of cells in the vertical direction.
dx (float) – Horizontal cell size in meters. It can be provided alternatively to
nx
.dy (float) – Vertical cell size in meters. It can be provided alternatively to
ny
.dz (float) – Longitudinal cell size in meters.It can be provided alternatively to
nz
.x_grid (np.ndarray) – Equispaced array with the horizontal grid points (cell centers). It can be provided alternatively to
x_range
,dx
/nx
.y_grid (np.ndarray) – Equispaced array with the horizontal grid points (cell centers). It can be provided alternatively to
y_range
,dy
/ny
.z_grid (np.ndarray) – Equispaced array with the horizontal grid points (cell centers). It can be provided alternatively to
z_range
,dz
/nz
.rho (np.ndarray) – initial charge density at the grid points in Coulomb/m^3.
phi (np.ndarray) – initial electric potential at the grid points in Volts. If not provided the
phi
is calculated fromrho
using the Poisson solver (if available).solver (str or solver object) – Defines the Poisson solver to be used to compute phi from rho. Accepted values are
FFTSolver3D
andFFTSolver2p5D
. A Xfields solver object can also be provided. In caseupdate_on_track``is ``False
andphi
is provided by the user, this argument can be omitted.scale_coordinates_in_solver (tuple) – Three coefficients used to rescale the grid coordinates in the definition of the solver. The default is (1.,1.,1.).
updatable (bool) – If
True
the field map can be updated after creation. Default isTrue
.
- Returns
Interpolator object.
- Return type
- get_values_at_points(x, y, z, return_rho=True, return_phi=True, return_dphi_dx=True, return_dphi_dy=True, return_dphi_dz=True)¶
Returns the charge density, the field potential and its derivatives at the points specified by x, y, z. The output can be customized (see below). Zeros are returned for points outside the grid.
- Parameters
x (float64 array) – Horizontal coordinates at which the field is evaluated.
y (float64 array) – Vertical coordinates at which the field is evaluated.
z (float64 array) – Longitudinal coordinates at which the field is evaluated.
return_rho (bool) – If
True
, the charge density at the given points is returned.return_phi (bool) – If
True
, the potential at the given points is returned.return_dphi_dx (bool) – If
True
, the horizontal derivative of the potential at the given points is returned.return_dphi_dy – If
True
, the vertical derivative of the potential at the given points is returned.return_dphi_dz – If
True
, the longitudinal derivative of the potential at the given points is returned.
- Returns
The required quantities at the provided points.
- Return type
(tuple of float64 array)
- update_from_particles(particles=None, x_p=None, y_p=None, z_p=None, ncharges_p=None, state_p=None, q0_coulomb=None, reset=True, update_phi=True, solver=None, force=False)¶
Updates the charge density at the grid using a given set of particles, which can be provided by a particles object or by individual arrays. The potential can be optionally updated accordingly.
- Parameters
particles (xtrack.Particles) – xtrack particle object.
x_p (float64 array) – Horizontal coordinates of the macroparticles.
y_p (float64 array) – Vertical coordinates of the macroparticles.
z_p (float64 array) – Longitudinal coordinates of the macroparticles.
ncharges_p (float64 array) – Number of reference charges in the macroparticles.
state_p (int64, array) – particle state (>0 active, lost otherwise)
q0_coulomb (float64) – Reference charge in Coulomb.
reset (bool) – If
True
the stored charge density is overwritten with the provided one. IfFalse
the provided charge density is added to the stored one. The default isTrue
.update_phi (bool) – If
True
the stored potential is recalculated from the stored charge density.solver (Solver object) – solver object to be used to solve Poisson’s equation (compute phi from rho). If
None
is provided the solver attached to the fieldmap is used (if any). The default isNone
.force (bool) – If
True
the potential is updated even if the map is declared as not updateable. The default isFalse
.
- update_rho(rho, reset=True, force=False)¶
Updates the charge density on the grid.
- Parameters
rho (float64 array) – Charge density at the grid points in C/m^3.
reset (bool) – If
True
the stored charge density is overwritten with the provided one. IfFalse
the provided charge density is added to the stored one. The default isTrue
.force (bool) – If
True
the charge density is updated even if the map is declared as not updateable. The default isFalse
.
- update_phi(phi, reset=True, force=False)¶
Updates the potential on the grid. The stored derivatives are also updated.
- Parameters
rho (float64 array) – Potential at the grid points.
reset (bool) – If
True
the stored potential is overwritten with the provided one. IfFalse
the provided potential is added to the stored one. The default isTrue
.force (bool) – If
True
the potential is updated even if the map is declared as not updateable. The default isFalse
.
- update_phi_from_rho(solver=None)¶
Updates the potential on the grid (phi) from the charge density on the grid (phi). It requires a Poisson solver object. If none is provided the one attached to the fieldmap is used (if any).
- Parameters
solver (Solver object) – solver object to be used to solve Poisson’s equation. If
None
is provided the solver attached to the fieldmap is used (if any). The default isNone
.
- generate_solver(solver, fftplan)¶
Generates a Poisson solver associated to the defined grid.
- Parameters
solver (str) – Defines the Poisson solver to be used
and (to compute phi from rho. Accepted values are FFTSolver3D) –
FFTSolver2p5D. –
- Returns
Solver object associated to the defined grid.
- Return type
(Solver)
- property x_grid¶
Array with the horizontal grid points (cell centers).
- property y_grid¶
Array with the vertical grid points (cell centers).
- property z_grid¶
Array with the longitudinal grid points (cell centers).
- property nx¶
Number of cells in the horizontal direction.
- property ny¶
Number of cells in the vertical direction.
- property nz¶
Number of cells in the longitudinal direction.
- property dx¶
Horizontal cell size in meters.
- property dy¶
Vertical cell size in meters.
- property dz¶
Longitudinal cell size in meters.
- property rho¶
- property phi¶
Electric potential at the grid points in Volts.
- property dphi_dx¶
- property dphi_dy¶
- property dphi_dz¶
Beam-beam Bi-Gaussian Field Map¶
- class xfields.fieldmaps.BiGaussianFieldMap(_context=None, _buffer=None, _offset=None, _xobject=None, mean_x=0.0, mean_y=0.0, sigma_x=None, sigma_y=None, min_sigma_diff=1e-10, updatable=True)¶
Builds a field-map object that provides the fields generated by a normalized 2D Gaussian distribution (Bassetti-Erskine formula).
- Parameters
context (xobjects context) – identifies the context on which the computation is executed.
mean_x (float64) – Horizontal position (in meters) of the Gaussian distribution. It can be updated after the object creation. Default is
0.
.mean_y (float64) – Vertical position (in meters) of the Gaussian distribution. It can be updated after the object creation. Default is
0.
.sigma_x (float64) – Horizontal r.m.s. size (in meters) of the Gaussian distribution. It can be updated after the object creation. Default is
None
.sigma_y (float64) – Vertical r.m.s. size (in meters) of tthe Gaussian distribution. It can be updated after the object creation. Default is
None
.min_sigma_diff (float64) – Difference between sigma_x and sigma_y (in meters) below which round distribution is assumed.
updatable (bool) – If
True
the field map can be updated after creation. Default isTrue
.
- Returns
Field map object.
- Return type
- property updatable¶
- update_from_particles(x_p, y_p, z_p, ncharges_p, q0_coulomb, reset=True, update_phi=True, solver=None, force=False)¶
- update_rho(rho, reset)¶
- update_phi(phi, reset=True, force=False)¶
- update_phi_from_rho(solver=None)¶
- generate_solver(solver)¶
Solvers¶
FFT Solver 3D¶
- class xfields.solvers.FFTSolver3D(dx, dy, dz, nx, ny, nz, context=None, fftplan=None)¶
Creates a Poisson solver object that solves the full 3D Poisson equation using the FFT method (free space).
- Parameters
nx (int) – Number of cells in the horizontal direction.
ny (int) – Number of cells in the vertical direction.
nz (int) – Number of cells in the vertical direction.
dx (float) – Horizontal cell size in meters.
dy (float) – Vertical cell size in meters.
dz (float) – Longitudinal cell size in meters.
context (XfContext) – identifies the context on which the computation is executed.
- Returns
Poisson solver object.
- Return type
- solve(rho)¶
Solves Poisson’s equation in free space for a given charge density.
- Parameters
rho (float64 array) – charge density at the grid points in Coulomb/m^3.
- Returns
electric potential at the grid points in Volts.
- Return type
phi (float64 array)
FFT Solver 2.5D¶
- class xfields.solvers.FFTSolver2p5D(dx, dy, dz, nx, ny, nz, context=None, fftplan=None)¶
Creates a Poisson solver object that solve’s Poisson equation in the 2.5D aaoroximation equation the FFT method (free space).
- Parameters
nx (int) – Number of cells in the horizontal direction.
ny (int) – Number of cells in the vertical direction.
nz (int) – Number of cells in the vertical direction.
dx (float) – Horizontal cell size in meters.
dy (float) – Vertical cell size in meters.
dz (float) – Longitudinal cell size in meters.
context (XfContext) – identifies the context on which the computation is executed.
- Returns
Poisson solver object.
- Return type
- solve(rho)¶
Solves Poisson’s equation in free space for a given charge density.
- Parameters
rho (float64 array) – charge density at the grid points in Coulomb/m^3.
- Returns
electric potential at the grid points in Volts.
- Return type
phi (float64 array)