35  Field Solver Physics

This chapter is the physics-level counterpart to the Field Solver user guide. The user guide documents input choices and current runtime behavior; this chapter will derive the model, state its approximations, and collect numerical validation.

NoteDocumentation skeleton

The headings below define the intended scope. The sections on FFT2D5 longitudinal fields, P3M, cathode image fields, and binned rest-frame space charge are written. The remaining headings contain only short writing prompts so that equations and claims can be added after they are checked against the implementation and benchmark cases.

35.1 Scope and notation

Define the charge, field, coordinate, unit, and sign conventions used throughout the chapter. State which parts apply to all solvers and which are specific to space charge.

35.2 Governing electrostatic model

State the quasi-static approximation and the physical problem solved in the selected bunch frame.

35.2.1 Poisson equation

Introduce the source term, potential, electric field, and boundary data.

35.2.2 Self-field force

Connect the solved fields to the force applied by the tracker, including any frame transformation required before the particle push.

35.3 Particle-mesh discretization

Describe the complete particle-in-cell cycle and identify the discrete quantities that live on particles and on the mesh.

35.3.1 Charge deposition

Specify the particle shape, weighting rule, normalization, and treatment of ghost cells.

35.3.2 Mesh solve

Define the discrete Poisson operator or convolution used by each solver family.

35.3.3 Field reconstruction and interpolation

Explain how the electric field is reconstructed and interpolated back to particle positions.

35.4 Frames and relativistic transformations

For binned space charge, OPALX first constructs a beam-aligned frame whose origin follows the bunch and whose longitudinal axis is parallel to the mean momentum. Let \(Q\) denote its orthogonal rotation. Particle coordinates entering the binned calculation are

\[ \mathbf r'_i=Q(\mathbf r_i-\mathbf r_0), \qquad \mathbf p'_i=Q\mathbf p_i. \]

Both transformations are required: using \(\mathbf r'_i\) with unrotated \(\mathbf p_i\) mixes coordinate systems in bin selection, mean-bin momentum, and the field transformation. Because \(Q\) is orthogonal, \(|\mathbf p'_i|=|\mathbf p_i|\) and \(\gamma_i=\sqrt{1+|\mathbf p_i|^2}\) is unchanged. After gathering, positions, momenta, and electromagnetic fields are rotated back to the tracking frame.

35.5 FFT2D5 longitudinal fields

FFT2D5 uses local transverse coordinates and arc length along a planar reference path. This geometric transformation is not a Lorentz boost: deposition uses laboratory line charge, so the transverse Poisson field is already the laboratory electric field. In the locally parallel common-velocity approximation, \(\mathbf B_\perp=(\beta/c)\hat{\mathbf t}\times\mathbf E_\perp\); for a straight beam, \(\mathbf F_\perp=q\mathbf E_\perp/\gamma^2\). The cell-averaged logarithmic Green function includes a finite self term, and centered boundary gradients use the exterior convolution potential. Curved-path projection does not add a nonlocal curvature correction.

The current ORIGINAL model solves independent open transverse Poisson slices with a cell-integrated logarithmic Green function and doubled-grid FFT convolution. It estimates the longitudinal field from laboratory line charge \(\lambda(s)\) along the reference path. Here \(\gamma\) is formed from the mean longitudinal normalized momentum of the active bunch:

\[ E_s=-\frac{g}{4\pi\varepsilon_0\gamma^2}\frac{d\lambda}{ds}. \]

Let \(a=\mathtt{BEAMR}\) and \(b=\min(\mathtt{PIPESIZEX},\mathtt{PIPESIZEY})\). The scalar factors are

\[ \begin{aligned} g_{\rm OPEN}&=6.36,\\ g_{\rm CIRCULAR}&=0.67+2\ln(b/a),\\ g_{\rm PLATES}&=0.67+2\ln(4b/(\pi a)). \end{aligned} \]

NONE sets the longitudinal field to zero. Here \(b\) follows the implementation’s use of the full numerical mesh widths; there is no independent PIPERADIUS attribute in this model. This is a local longitudinal closure, not a nonlocal finite-source three-dimensional Poisson solve.

MPI divides the reference-path mesh into longitudinal slabs. Every rank solves complete transverse planes with its FFT plans. Particle migration and density/ field halo exchange connect neighbouring slabs; the longitudinal line-density profile is reduced separately for the derivative. Transverse MPI decomposition is unsupported. Choose enough slices per rank for halo exchange and longitudinal resolution; one-plane local slabs are not supported by the current full exchange.

Optional batching groups independent transverse transforms into local workspaces on CPUs and CUDA GPUs. It changes execution and workspace use while retaining the same slice model; it adds no longitudinal FFT. See the distributed and batched input controls.

Development model notes — unavailable in the current version

The derivations below are retained development notes for a finite-source OPEN operator and a pointwise round-beam model. Those models and their additional attributes are unavailable in the current ORIGINAL implementation.

PIPEMODE="OPEN" uses a finite-source Coulomb potential on a straight or constant-curvature reference path. Let \(u\) point along the local radial basis, \(y\) be vertical, \(s\) be arc length, and \(\kappa=1/R\) be signed curvature, so \(\partial_s\mathbf t=-\kappa\mathbf b\) and the metric is \(J=1+\kappa u\). Particle deposition gives coordinate density \(\rho_c=dq/(du\,dy\,ds)\); it already includes the physical source Jacobian. No second factor \(J\) is applied to the charge.

For source coordinate \(u'\) and separation \(\tau=s-s'\), define

\[ \xi=\frac{2\sin(\kappa\tau/2)}{\kappa},\quad D=(u-u')^2+(y-y')^2+\xi^2,\quad G=D^{-1/2},\quad H=\xi^2D^{-3/2},\quad F=(u-u')H. \]

The straight limit is \(\xi=\tau\). Expanding the exact circular Coulomb kernel only in transverse \(\kappa u\) and \(\kappa u'\), while retaining the full angular separation, gives

\[ \Phi\simeq\frac{1}{4\pi\varepsilon_0} \left[G*\rho_c-\kappa u(H*\rho_c)+\frac{\kappa}{2}(F*\rho_c)\right]. \]

The omitted kernel terms are second order in transverse size/R. Here \(*\) denotes convolution over \((u,y,s)\). All three fields derive from this same potential:

\[ E_u=-\partial_u\Phi,\qquad E_y=-\partial_y\Phi,\qquad E_s=-\frac{1}{1+\kappa u}\partial_s\Phi. \]

The implementation integrates the singular source-cell kernels, uses padded three-dimensional FFTs on the thin reference-path mesh, and differentiates the potential with fourth-order centred differences in physical cells. It does not create a Cartesian field mesh covering the orbit. Unlike a local \(\lambda'\) closure, this operator includes fields from distant slices and finite ends, including where \(\lambda'=0\).

The fitted path must be straight or a horizontal circular arc shorter than one turn; arbitrary curvature and closed rings are rejected. The mesh and field halo must satisfy \(|\kappa u|\le0.01\). This is a thin-tube expansion, not an expansion in total bend angle. On a straight path, the source longitudinal coordinate is stretched by the common mean \(\gamma\), the transverse rest-frame field is multiplied by \(\gamma\), and the longitudinal field is retained when returning to the laboratory. Curved paths use instantaneous electrostatics, reject \(\beta>0.1\), and have no validated relativistic tracking interpretation. The local magnetic-field approximation is not a nonlocal Biot–Savart solve.

The remaining modes retain open transverse Poisson slices and a local longitudinal model. Let \(r\) be distance from a straight reference path and \(\lambda(s)\) be laboratory line charge; \(\gamma\) is the mean longitudinal Lorentz factor.

PIPEMODE="CIRCULAR_UNIFORM" assumes a uniform circular beam of constant radius \(a=\mathtt{BEAMR}\) centred in a coaxial grounded circular pipe of physical radius \(b=\mathtt{PIPERADIUS}\ge a\). Gauss’s law gives the local laboratory radial field

\[ E_r(r,s)=\frac{\lambda(s)}{2\pi\varepsilon_0} \begin{cases} r/a^2,&0\le r\le a,\\ 1/r,&a<r\le b. \end{cases} \]

Integrating from \(r\) to the grounded wall gives the transverse potential

\[ \Phi(r,s)=\int_r^b E_r(r',s)\,dr' =\frac{\lambda(s)}{4\pi\varepsilon_0}g(r),\qquad g(r)=\begin{cases} 1+2\ln(b/a)-r^2/a^2,&0\le r\le a,\\ 2\ln(b/r),&a<r\le b. \end{cases} \]

For a uniformly moving, quasi-static bunch, the longitudinal laboratory field in this long-beam approximation is

\[ E_s(r,s)=-\frac{1}{\gamma^2}\frac{\partial\Phi}{\partial s} =-\frac{\lambda'(s)}{4\pi\varepsilon_0\gamma^2}g(r). \]

The two expressions for \(g\) agree at \(r=a\), and \(E_s(b,s)=0\) at the grounded wall. The on-axis value is \(g(0)=1+2\ln(b/a)\); the uniform-disk average is \(\overline g=1/2+2\ln(b/a)\). The distinction between on-axis and averaged fields is discussed by Baartman. The implementation rejects particles with \(r>b\); this is a coverage check, not a transverse conducting-wall solve or a material-loss model.

The transverse mesh widths PIPESIZEX and PIPESIZEY do not enter \(g(r)\) in this mode. The physical radius must remain fixed during numerical-domain checks. The open transverse solve gives the same local radial field as the centred round-pipe model for an axisymmetric source, because the conductor changes its potential reference rather than its interior radial field. This equivalence does not extend to offset or arbitrary transverse profiles.

The model neglects the longitudinal second-derivative term in Poisson’s equation. Its longitudinal variation scale in the bunch frame must be large compared with the pipe radius. A triangular-bunch benchmark therefore compares the linear branches away from the cusp and ends. The formula does not supply the nonlocal fringe field at a sharp end. It is derived for a straight, coaxial beam; transforming particles to a curved reference path does not add a curvature correction. The input radius is fixed and is not inferred from the evolving transverse distribution.

The retained CIRCULAR mode instead uses the scalar coefficient

\[ g_{\mathrm{moment}}=0.67+2\ln(b/a) \]

for every particle at a given \(s\). The constant \(0.67\) comes from the equivalent parabolic/ellipsoidal moment model described by Oeftiger and Hegglin. It is neither the pointwise uniform-disk value nor its disk average. PIPERADIUS explicitly sets \(b\) for this mode. Without that attribute, CIRCULAR retains its historical use of the smaller full numerical width as the length in the logarithm. PLATES retains its scalar model. Neither OPEN nor PLATES accepts PIPERADIUS.

In PyORBIT’s slice-by-slice model, transverse and enabled longitudinal kicks come from the same sliced potential; a conducting boundary fixes the potential reference between slices. The current model disables that longitudinal kick without a boundary. OPALX’s round-beam formula is separate from its numerical transverse potential and assumes the prescribed circular profile. It is closer longitudinally to PyORBIT’s Baartman variant, which uses a line-density derivative with radial dependence, although that variant estimates its equivalent radius from transverse second moments and uses one projected transverse distribution. Neither reduced method is a full 3D Poisson solve. See the PyORBIT source and the OPALX input guide.

35.6 Boundary conditions and Green functions

Define each boundary-value problem independently of its input syntax.

35.6.1 Periodic boundaries

Describe the periodic domain, compatibility conditions, and zero-mode handling.

35.6.2 Open boundaries

Derive the free-space Green-function convolution and doubled-domain method.

35.6.3 Dirichlet and image-charge boundaries

OPALX models a cathode as an infinite, grounded, perfectly conducting plane \(z=z_p\) normal to the beam axis, placed at R0Z of the emission source. The bunch lies on one side, \(z>z_p\). The method of images [1] replaces the conductor by the mirrored charge

\[ \rho_I(x,y,z)=-\rho(x,y,2z_p-z), \qquad \phi_I(x,y,z)=-\phi(x,y,2z_p-z), \]

so that \(\phi+\phi_I=0\) on the plane. The bunch is pushed with \(\mathbf E+\mathbf E_I\) and \(\mathbf B+\mathbf B_I\).

Moving image

The image of a charge \(q\) at \((x,y,z)\) with velocity \(\mathbf v=v\hat{\mathbf z}\) is a charge \(-q\) at \((x,y,2z_p-z)\) with velocity \(-\mathbf v\). For uniform motion this pair satisfies the perfect-conductor conditions on the plane exactly: the tangential \(\mathbf E\) and the normal \(B_z\) cancel, while the normal \(E_z\) and the tangential \(\mathbf B\) double and correspond to the surface charge and surface current. The image is therefore treated like a bunch with the same rest-frame solve and the reversed velocity. For bin \(b\) (see binned rest-frame space charge), with rest-frame image field \(\mathbf E'_I\),

\[ \mathbf E_I=\gamma_b\mathbf E'_I -(\gamma_b-1)(\mathbf E'_I\cdot\hat{\mathbf w}_b)\hat{\mathbf w}_b, \qquad \mathbf B_I=-\frac{\gamma_b}{c^2}\,\mathbf v_b\times\mathbf E'_I . \]

Only the sign of \(\mathbf B_I\) differs from the real bunch, because \(\hat{\mathbf w}_b\) enters \(\mathbf E\) only quadratically. Without binning, \(\gamma_b=1\) and \(\mathbf B_I=0\).

Explicit image charges

With ZEROFACE_R0Z, OPALX deposits \(-q\) at \(2z_p-z\) for every particle and solves for \(\rho+\rho_I\) (unbinned) or for \(\rho_I\) in a separate pass per bin (binned). The mesh must span the bunch, its mirror, and the gap of twice the bunch-plane distance between them. OPALX uses \(2N_z\) longitudinal mesh points in this mode, so the resolution matches the solve without images only while the bunch touches the plane and decreases as the bunch moves away.

Shifted Green function

The shifted-Green method [2] evaluates the image field on the mesh of the real bunch. Let \(z_c\) be the centre of that mesh. The mirror point then satisfies \(2z_p-z=\tilde z-s\) with \(\tilde z=2z_c-z\) and \(s=2(z_c-z_p)\), so

\[ \phi_I(x,y,z)=-\phi_s(x,y,2z_c-z), \qquad \phi_s(\mathbf r)=\frac{1}{4\pi\varepsilon_0} \int\frac{\rho(\mathbf r')\,\mathrm d^3r'}{|\mathbf r-\mathbf s-\mathbf r'|}, \qquad \mathbf s=s\,\hat{\mathbf z}. \]

\(\phi_s\) is an ordinary Hockney convolution of the real charge with the translated kernel \(G(\mathbf r-\mathbf s)\); the image charges themselves never appear on the mesh. Reflecting the field about \(z_c\) and applying \(\mathbf E_I=-\nabla\phi_I\) gives the component rule, which holds in the same form for the rest-frame fields of a bin:

\[ \mathbf E'_I(x,y,z)=\bigl(-E'_{s,x},\,-E'_{s,y},\,+E'_{s,z}\bigr)(x,y,2z_c-z). \]

In the rest frame of bin \(b\), longitudinal separations grow by \(\gamma_b\), so the kernel shift is \(s=2\gamma_b(z_c-z_p)\), with \(z_c\) and \(z_p\) in laboratory coordinates. The result is converted with the image transformation above. With TYPE=OPEN, the shifted kernel follows GREENSF; with TYPE=P3M, it is the full Coulomb kernel, regularized as \(1/\sqrt{r^2+h_{\min}^2/4}\) for \(r<h_{\min}/2\).

The image and bunch meshes coincide, so the resolution does not degrade as the bunch moves away from the plane. Each bin still needs one additional Poisson solve.

Images with P3M

With TYPE=P3M, only the real bunch receives the short-range pair term of P3M. The image field is resolved on the mesh only:

\[ \mathbf E=\mathbf E_{\mathrm{mesh}}+\mathbf E_{\mathrm{pp}}+\mathbf E_{I,\mathrm{mesh}} . \]

A particle at distance \(d_i\) from the plane is separated from the image of a particle at \(d_j\) by at least \(d_i+d_j\). A short-range image term is therefore missing only for pairs with \(d_i+d_j<r_c\), which occur only within \(r_c\) of the plane. Neglecting boundary conditions in the short-range interaction introduces an error of the order of the mesh discretization error [3].

Validity

The model assumes a flat, infinite, perfectly conducting plane normal to the direction of motion. It is quasi-static: retardation is neglected, and the image responds instantaneously to the bunch. ZEROFACE_MAXSTEPS disables the correction when the configured step limit is reached; zero leaves it active indefinitely. The solver does not test whether the image field is negligible. Choose a finite limit by checking its effect on the observables.

35.6.4 Bunch trains

A bunch in a linac also feels the space charge of the bunches in the neighbouring RF buckets. If these bunches are identical copies of the tracked bunch, displaced by \(ka\,\hat{\mathbf z}\) for \(0<|k|\le K\), their potential adds to that of the tracked bunch:

\[ \phi(\mathbf r)=\sum_{|k|\le K}\int G(\mathbf r-ka\,\hat{\mathbf z}-\mathbf r') \,\rho(\mathbf r')\,\mathrm d^3r' =\int G_K(\mathbf r-\mathbf r')\,\rho(\mathbf r')\,\mathrm d^3r', \qquad G_K(\mathbf r)=\sum_{|k|\le K}G(\mathbf r-ka\,\hat{\mathbf z}), \]

with \(G(\mathbf r)=1/(4\pi\varepsilon_0|\mathbf r|)\). The copies therefore enter only the kernel. One Hockney convolution of the tracked charge with \(G_K\) gives the field of all \(2K+1\) bunches on the mesh of the tracked bunch, without extending the mesh to the copies. The copy kernels are summed when the Green function is built.

In the rest frame of bin \(b\), longitudinal distances grow by \(\gamma_b\), so the copies of that bin are spaced by \(\gamma_b a\), as for the shifted-Green image shift. The bin field, including its copies, is then transformed to the laboratory frame as in the binned mode.

With TYPE=OPEN, the copies use the kernel selected by GREENSF. With TYPE=P3M, the mesh kernel of the tracked bunch holds only the long-range part of the force split, and the pair sum runs only over tracked particles. The copies therefore use the full Coulomb kernel. Point-sampled copies, from GREENSF=STANDARD or P3M, are regularized as \(1/\sqrt{r^2+h_{\min}^2/4}\) for \(r<h_{\min}/2\). This affects the result only when the mesh is longer than \(a\) along \(z\), so that a copy’s singularity lies inside the mesh.

The model assumes that all bunches of the train have the same charge, distribution and velocity at every step. Differences between bunches and the motion of the neighbours are not modelled, and the train ends after \(K\) copies on each side. Like the other self-fields here, the field is quasi-static.

35.7 Solver formulations

Relate the mathematical problem to the available numerical backends.

35.7.1 Periodic FFT solver

Document the spectral formulation, differentiation, normalization, and parallel decomposition.

35.7.2 Hockney open-boundary solver

Document domain doubling, kernel sampling, padding, and extraction of the physical-domain result.

35.7.3 Particle-particle particle-mesh solver

A mesh solve resolves the field only on scales above the mesh spacing \(h\). The field on particle \(i\) separates into a smooth part and a part from discreteness and short-range correlations,

\[ \mathbf E_i=\langle\mathbf E\rangle(\mathbf r_i)+\delta\mathbf E_i , \]

and charge deposition followed by a mesh solve retains only the first term [4]. The second term causes intrabeam scattering, which in dense, cold beams raises the energy spread far above the prediction of mesh-only space-charge models [5]. P3M [6] recovers \(\delta\mathbf E_i\) by splitting the Coulomb kernel at the scale \(1/\alpha\):

\[ \frac{1}{r}= \underbrace{\frac{\operatorname{erf}(\alpha r)}{r}}_{\text{mesh}} +\underbrace{\frac{\operatorname{erfc}(\alpha r)}{r}}_{\text{particle-particle}}, \qquad \alpha=\frac{2}{r_c}. \]

Long-range mesh part

The smooth kernel replaces the Green function of the FFT solvers, and \(\mathbf E_{\mathrm{mesh}}=-\nabla(G_L*\rho)\). For open boundaries, the Hockney solver convolves with

\[ G_L(r)=\frac{1}{4\pi\varepsilon_0}\frac{\operatorname{erf}(\alpha r)}{r}, \qquad G_L(0)=\frac{1}{4\pi\varepsilon_0}\frac{2\alpha}{\sqrt\pi}, \]

which is finite at the origin and needs no regularization. For periodic boundaries, the periodic solver multiplies by the Ewald kernel

\[ \hat G_L(\mathbf k)=\frac{1}{\varepsilon_0}\frac{e^{-k^2/(4\alpha^2)}}{k^2}, \qquad \mathbf k\neq\mathbf 0, \]

and sets the \(\mathbf k=\mathbf 0\) mode to zero, which is equivalent to a uniform neutralizing background. Deposition and interpolation use the same CIC scheme as the other solvers.

Short-range particle part

The complement is summed directly over all neighbours within the cutoff radius:

\[ \mathbf E_{\mathrm{pp},i}=\frac{1}{4\pi\varepsilon_0} \sum_{\substack{j\neq i\\ r_{ij}<r_c}} q_j\,\frac{\mathbf r_{ij}}{r_{ij}^{3}}\,f(\alpha r_{ij}), \qquad f(x)=\operatorname{erfc}(x)+\frac{2x}{\sqrt\pi}e^{-x^{2}}, \]

with \(\mathbf r_{ij}=\mathbf r_i-\mathbf r_j\). The mesh carries the remaining fraction \(1-f(\alpha r)\) of each pair force, so \(\mathbf E=\mathbf E_{\mathrm{mesh}}+\mathbf E_{\mathrm{pp}}\) is the full Coulomb field up to the mesh error and the neglected tail \(f(\alpha r)\) for \(r\ge r_c\). Below \(r=10^{-9}\,\mathrm m\), the singular Coulomb term is replaced by a linear force that is continuous at that radius.

With binning, the mesh part is solved for each bin in the rest frame of that bin. The pair part instead splits the kernel in the rest frame of each source particle \(j\), which moves with its own normalized momentum \(\mathbf u_j=\gamma_j\boldsymbol\beta_j\). At equal laboratory time, the rest-frame distance of a pair is

\[ s_{ij}^2=r_{ij}^2+(\mathbf u_j\cdot\mathbf r_{ij})^2 , \]

and the short-range part of the field of a uniformly moving charge [1, Sec. 11.10], [7] is

\[ \mathbf E_{\mathrm{pp},i}=\frac{1}{4\pi\varepsilon_0} \sum_{\substack{j\neq i\\ s_{ij}<r_c}} q_j\gamma_j\,\frac{\mathbf r_{ij}}{s_{ij}^{3}}\,f(\alpha s_{ij}), \qquad \mathbf B_{\mathrm{pp},i}=\sum_{\substack{j\neq i\\ s_{ij}<r_c}} \frac{\mathbf u_j\times\mathbf E_{\mathrm{pp},ij}}{\gamma_j c}, \]

where \(\mathbf E_{\mathrm{pp},ij}\) is the term of source \(j\). For sources at rest, this is the sum above. For a common momentum along \(z\), it is the pair field on the separations \((\Delta x,\Delta y,\gamma\Delta z)\), converted to the laboratory like the mesh field. Since \(s_{ij}\ge r_{ij}\), every pair within the rest-frame cutoff is also a laboratory pair within \(r_c\), and the neighbour search is unchanged. The pair sum runs once for all bins.

Each source thus enters the short-range part with its own velocity and the long-range part with the velocity of its bin. The binning error is confined to the smooth long-range kernel: it is bounded as \(r\to0\), continuous at \(r_c\), and vanishes for narrow bins. The long-range kernel carries the fraction \(1-f(\alpha s)\) of a pair force, about \(0.08\) at \(s=r_c/4\), \(0.43\) at \(s=r_c/2\), and \(0.95\) at \(s=r_c\). The particle velocities therefore govern the sub-cell interactions, which the mesh cannot resolve, while separations near \(r_c\) already follow the bin velocity. Like the mesh part, the pair term neglects the acceleration of the source.

The mesh deposits each charge weighted by \(\Delta t_j/\Delta t\), while the pair sum uses the unweighted charge. The two differ only during emission, when particle time steps differ.

Accuracy and parameters

Two dimensionless numbers control the error [8]: \(\alpha r_c\) for the truncation of the pair sum and \(\alpha h\) for the mesh error of the long-range part. OPALX fixes \(\alpha r_c=2\), so that the neglected tail is at most \(f(2)\approx4.6\times10^{-2}\) of the Coulomb force at \(r=r_c\) and decays as \(e^{-\alpha^2r^2}\) beyond. The free parameter is the split distance in mesh cells,

\[ \kappa=\frac{r_c}{h_{\max}}, \qquad \alpha h_{\max}=\frac{2}{\kappa}, \]

set by RCUT_CELLS (default \(\kappa=2\), so \(\alpha h_{\max}=1\)) or by a fixed cutoff RCUT. At \(\kappa=2\) the mesh error dominates. A larger \(\kappa\) moves more of the interaction into the exact pair sum, at a pair cost that grows as \(\kappa^3\) for a fixed mesh. With RCUT_CELLS, \(r_c\) follows the moving mesh at every update.

In the rest frame of bin \(b\), the longitudinal spacing is \(\gamma_b h_z\) while \(r_c\) is unchanged. A mesh that resolves the split in the laboratory frame can therefore be too coarse in the rest frame. If \(\gamma_b h_z\) does not exceed the largest laboratory spacing for the most energetic bin, \(\alpha h\) keeps its laboratory value \(2/\kappa\).

The pair term models physical Coulomb collisions only when every macroparticle carries the charge of one physical particle. With heavier macroparticles, the pair term causes artificial collisional heating, which distorts second-order moments such as the emittance and the energy spread.

Neighbour search and load balance

Each MPI rank stores ghost copies of the particles within \(r_c\) of its region and sorts local and ghost particles into search cells at least \(r_c\) wide. A particle visits its own and the 26 adjacent cells. One thread per local particle sums its pair fields and stores them once, so the pair term needs no atomic updates, with and without binning. The ghosts and search cells require \(r_c\) to be at most half the rank extent in every direction. A mesh-tied cutoff is reduced to the largest value that fits, which raises \(\alpha h_{\max}\) above \(2/\kappa\); a fixed RCUT that does not fit is an error. For periodic boundaries, particles within \(r_c\) of the domain boundary are also copied as periodic image ghosts.

With number density \(n\), a particle has about \(\tfrac{4\pi}{3}r_c^3n\) neighbours, so the pair work of a rank grows as \(\sum n^2\) over its cells rather than with its particle count. The option LOADBALANCINGPAIRWEIGHT \(=\beta\) therefore weights the ORB partition per mesh vertex by

\[ w=(1-\beta)\frac{n}{\sum n}+\beta\frac{n^2}{\sum n^2}, \]

where \(n\) is the deposited particle count of the vertex and the sums run over all ranks.

35.7.4 Iterative solvers

Reserve this subsection for the operator, convergence criterion, preconditioning, and supported boundary conditions once an iterative backend is production-ready.

35.8 Binned rest-frame space charge

35.8.1 Quasi-static single-frame model

If all particles move with nearly the same velocity \(\mathbf v_f=\beta_f c\,\hat{\mathbf w}\), they are approximately at rest in the co-moving frame. There, \(\mathbf B'=\mathbf 0\) and the field follows from Poisson’s equation [2]:

\[ \nabla'^2\phi'=-\frac{\rho'}{\varepsilon_0}, \qquad \mathbf E'=-\nabla'\phi', \qquad \rho'=\frac{\rho}{\gamma_f}, \qquad x'_\parallel=\gamma_f\,x_\parallel, \quad \mathbf x'_\perp=\mathbf x_\perp , \]

with laboratory coordinates taken at one laboratory time. The inverse Lorentz transformation gives

\[ \mathbf E=\gamma_f\mathbf E'-(\gamma_f-1)(\mathbf E'\cdot\hat{\mathbf w})\hat{\mathbf w}, \qquad \mathbf B=\frac{\gamma_f}{c^2}\,\mathbf v_f\times\mathbf E' =\frac{1}{c^2}\,\mathbf v_f\times\mathbf E , \]

that is, \(E_\parallel=E'_\parallel\) and \(\mathbf E_\perp=\gamma_f\mathbf E'_\perp\). For a common, uniform velocity this is exact. The model neglects retardation and radiation from accelerated particles, and the velocity differences between particles. The latter requires the particles to be nonrelativistic in the common frame; for a paraxial beam with longitudinal momentum spread \(\Delta p_z\) (in units of \(mc\)) [9]

\[ \Delta p'_z\simeq\frac{\Delta p_z}{\gamma_f}\ll1 . \]

During photoemission this fails: the first electrons are already relativistic when the last ones leave the cathode, and \(\Delta p_z/\gamma_f\) is of order one.

For the three-dimensional Cartesian backends, the monolithic mode (BINS=NONE) solves Poisson’s equation in the laboratory frame, with \(\gamma_f=1\) and no magnetic self-field. For a relativistic bunch it overestimates the transverse self-force by up to \(\gamma^2\), because the magnetic force that nearly cancels the electric one is missing.

FFT2D5 instead uses the slice model described above, including its magnetic field.

35.8.2 Energy-binned decomposition

Binning restores the validity condition bin by bin [2], [9]. The particles are partitioned into \(N_b\) bins of a binning variable \(\zeta(p_z)\). Since \(\rho=\sum_b\rho_b\) and the field equations are linear, the field splits in the same way, and each contribution is approximated in the rest frame of its bin:

\[ \mathbf E\approx\sum_{b=1}^{N_b}\Bigl[\gamma_b\mathbf E'_b -(\gamma_b-1)(\mathbf E'_b\cdot\hat{\mathbf w}_b)\hat{\mathbf w}_b\Bigr], \qquad \mathbf B\approx\sum_{b=1}^{N_b}\frac{\gamma_b}{c^2}\,\mathbf v_b\times\mathbf E'_b, \]

where \(\mathbf E'_b\) solves the rest-frame problem for \(\rho_b\) with \(\gamma_f=\gamma_b\). The frame parameters are unweighted averages over the \(n_b\) particles of the bin:

\[ \gamma_b=\frac{1}{n_b}\sum_{i\in b}\gamma_i, \qquad \mathbf v_b=\frac{c\,\langle\mathbf p\rangle_b}{\gamma_b}, \qquad \hat{\mathbf w}_b=\frac{\langle\mathbf p\rangle_b}{|\langle\mathbf p\rangle_b|}. \]

On the mesh, the solve uses the beam-aligned frame. For each non-empty bin, OPALX deposits only the particles of that bin, divides the density by \(\gamma_b\), stretches the longitudinal spacing to \(\gamma_b h_z\), solves, and converts the mesh field to \(\mathbf E_b\) and \(\mathbf B_b\). The cell volume grows by the same factor \(\gamma_b\), so the stretched mesh still holds the full charge of the bin. The contributions are accumulated on the mesh and interpolated to the particles in one gather, and the pusher then applies these fields with each particle’s own velocity. With a cathode plane, each bin also has an image solve.

As the bin widths go to zero, the binned field converges to the quasi-static model for the full velocity distribution, not to a solution of Maxwell’s equations. Retardation, radiation, and the transverse velocity spread inside a bin remain unresolved. One explicit bin (MAXBINS=1) applies the single-frame model to the whole bunch. With TYPE=P3M, only the long-range mesh part is binned; the short-range pair part uses the velocity of each particle.

35.8.3 Frame of a warm bin

The bin parameters above form an exact Lorentz boost only if every particle in the bin has the same momentum. Otherwise, \(\mathbf v_b\) is still the velocity of the bin’s centre-of-momentum frame, but the Lorentz factor of that frame is not \(\gamma_b\). It is

\[ \Gamma_{\mathrm{CM}} =\frac{\gamma_b}{\sqrt{\gamma_b^2-|\langle\mathbf p\rangle_b|^2}} =\frac{\gamma_b}{\langle\gamma'\rangle_b}, \]

where \(\langle\gamma'\rangle_b\ge1\) is the mean Lorentz factor of the bin’s particles in that frame. OPALX applies no separate centre-of-momentum correction: it uses \(\gamma_b\) for the density, the mesh stretch, and the field transformation, and the gammaBin column of the bin table reports the same value.

For a small momentum spread, \(\gamma_b/\Gamma_{\mathrm{CM}}\approx1+\tfrac12\langle|\mathbf p'|^2\rangle_b\). The difference is second order in the spread, so it stays small under the condition the quasi-static model already needs. It becomes large for a hot bin with little net motion: at zero mean momentum, \(\Gamma_{\mathrm{CM}}=1\), while \(\gamma_b\) can be well above one.

The frame has two further limits. The mesh is stretched along the solve z axis only, while \(\mathbf v_b\) keeps its transverse components. The solve axes follow the mean momentum of the whole bunch, so a bin whose own mean momentum points elsewhere is not stretched along its direction of motion; that would take the directional stretch \(A=I+(\gamma_b-1)\hat{\mathbf w}_b\hat{\mathbf w}_b^T\). Particles sampled at one laboratory time are also treated as simultaneous in the bin frame, and OPALX does not correct for the resulting time offsets.

35.8.4 Binning variable

The bins are rebuilt from the current momenta at every field evaluation, using

\[ \zeta_i=\frac{|p_{z,i}|}{\sqrt{1+p_{z,i}^2}}\quad(\mathtt{VELOCITYZ}), \qquad \zeta_i=\sqrt{1+p_{z,i}^2}\quad(\mathtt{GAMMAZ}). \]

To first order, a bin of width \(\Delta\zeta\) has the rest-frame spread

\[ \Delta p'_z\simeq\gamma_b^2\,\Delta\beta_z\simeq\frac{\Delta\gamma_z}{\beta_b\gamma_b}. \]

A fixed width in \(\beta_z\) thus admits a spread growing as \(\gamma_b^2\), but the range of \(\beta_z\) shrinks as the bunch becomes relativistic, so the bins merge by themselves. A fixed width in \(\gamma_z\) admits a spread decreasing as \(1/(\beta_b\gamma_b)\).

35.8.5 Adaptive bin merging

With ADAPTIVEBINNING=FALSE, the range \(R=\zeta_{\max}-\zeta_{\min}\) is divided into \(N_{\max}=\) MAXBINS uniform bins. Otherwise, these fine bins are merged into \(N_b\le N_{\max}\) contiguous bins that minimize [10]

\[ C=\sum_{b=1}^{N_b}\Bigl[ w_b\,p_b\ln p_b +\alpha_{\mathrm{bin}}\,w_b^2 +\beta_{\mathrm{bin}}\,(w_b-w_d)^2 +\frac{w_d}{p_b}\,\Theta(w_d-p_b)\Bigr], \]

where \(p_b\) is the fraction of particles in bin \(b\), \(w_b\) its width in units of \(\zeta\), and \(\Theta(x)=1\) for \(x>0\), otherwise \(0\). The input parameters are \(\alpha_{\mathrm{bin}}=\) BINNINGALPHA, \(\beta_{\mathrm{bin}}=\) BINNINGBETA, and \(w_d=\) DESIREDWIDTH. The cost is a heuristic for the trade-off between the modeling error of wide bins, the shot noise of sparse bins, and one Poisson solve per bin:

  • The entropy term favors bins of equal population.
  • The width terms set the resolution: \(\alpha_{\mathrm{bin}}>0\) favors narrow bins, and the deviation term pulls the widths toward \(w_d\). For equal widths, they balance at \(N_b\approx (R/w_d)\sqrt{1+\alpha_{\mathrm{bin}}/\beta_{\mathrm{bin}}}\).
  • The sparse term acts almost as a lower bound \(p_b\gtrsim w_d\), which merges sparse tails and bounds \(N_b\lesssim1/w_d\).

Because \(C\) is a sum over bins, the exact minimum follows from the dynamic program

\[ D(k)=\min_{0\le i<k}\Bigl[D(i)+c\bigl(p_{ik},(k-i)\,\delta\bigr)\Bigr], \qquad D(0)=0, \]

over the first \(k\) fine bins of width \(\delta=R/N_{\max}\), where \(c(p,w)\) is the summand of \(C\) and \(p_{ik}\) the particle fraction in fine bins \(i+1\) to \(k\). Empty merged bins are excluded. The merge costs \(\mathcal O(N_{\max}^2)\) and does not depend on the particle number.

A binned step costs approximately

\[ T_{\mathrm{sc}}\approx N_b(1+s)\,T_{\mathrm{solve}}+(1+s)\,T_{\mathrm{dep}}+T_{\mathrm{gather}}, \]

with \(s=1\) while a cathode plane is active and \(s=0\) otherwise. Each particle is deposited once per pass, so only the solves grow with \(N_b\).

35.9 Emission and conducting boundaries

Near the cathode, the conducting plane and binning act together. Emitted particles start almost at rest at \(z_p\) and are accelerated, so the bunch spans a wide range of \(p_z\). Every bin \(b\) has an image bin that moves with \(-\mathbf v_b\) and is solved in the same rest frame, so each bin costs two Poisson solves while the plane is active. The image field decays with the distance to the plane, and ZEROFACE_MAXSTEPS ends the correction. Like other numerical parameters, this cutoff requires a convergence check.

The treatment of emission time and of space-charge activation during emission remains to be documented.

35.10 Numerical accuracy and convergence

Collect the error sources that should be varied in convergence studies.

35.10.1 Mesh resolution

Define spatial refinement studies and expected convergence observables.

35.10.2 Particle noise and deposition order

Separate sampling noise from mesh and solver error.

35.10.3 Time-step coupling

The particle step is a drift–kick–drift composition. OPALX provides two self-field sampling conventions while retaining the same Boris kick and external-field evaluation at the midpoint.

For the default midpoint convention,

\[ \mathbf r_{n+1/2}=D_{\Delta t/2}(\mathbf r_n,\mathbf p_n),\qquad (\mathbf E_{\mathrm{sc}},\mathbf B_{\mathrm{sc}})_{n+1/2} =\mathcal S(\mathbf r_{n+1/2},\mathbf p_n), \]

followed by the full Boris momentum kick and the second half drift. The historical pre-step convention instead evaluates

\[ (\mathbf E_{\mathrm{sc}},\mathbf B_{\mathrm{sc}})_n =\mathcal S(\mathbf r_n,\mathbf p_n) \]

before the first half drift. Those gathered fields remain attached to their particles through that drift and are combined with midpoint external fields. The input choices are SCFIELDUPDATE="MIDPOINT" and "PRESTEP"; changing the choice changes the temporal discretization and therefore requires a new timestep-convergence study.

35.11 Domain decomposition and load balancing

Explain which mathematical data are repartitioned and why the field, particle, and solver state must be refreshed in a defined order.

35.12 Current implementation architecture

The following diagram is retained as TikZ source for PDF output. HTML uses a small generated PNG of the same source so the page does not depend on a browser-side TikZ renderer.

Current OPALX space-charge class diagram

Current OPALX space-charge ownership, solver, data, and repartition relationships.
Figure 35.1: Current OPALX space-charge class relationships and repartition refresh order. The editable source is figures/current-space-charge-class-diagram.tex.

35.13 Verification and benchmarks

A one-turn coasting benchmark compared OPALX with OPAL 2022.1 at 72 MeV using a 2 mA proton bunch, 262144 macroparticles, a \(32^3\) open mesh, one momentum bin, GREENSF=STANDARD, and the common timestep \(1.645278052\times10^{-10}\) s. After applying the common-frame momentum rotation, the endpoint comparison was:

Observable OPAL 2022.1 OPALX Relative difference
radial RMS size [mm] 4.608578 4.605885 -0.0584%
vertical RMS size [mm] 4.215521 4.217434 +0.0454%
longitudinal RMS size [mm] 1.980226 1.981539 +0.0663%
radial normalized RMS emittance [mm mrad] 2.793744 2.793274 -0.0168%
vertical normalized RMS emittance [mm mrad] 1.012587 1.014261 +0.1654%
longitudinal normalized RMS emittance [mm mrad] 0.192261 0.190979 -0.6667%
RMS energy spread [keV] 43.354672 43.176349 -0.4113%

These values establish a cross-code regression point at one discretization; they are not a mesh, particle-number, or timestep-convergence result. A clean comparison of the two SCFIELDUPDATE conventions with the production field reconstruction remains to be added.

35.14 Assumptions and known limitations

The list covers the models documented above; other solver families remain to be added.

  • All self-fields are quasi-static. Retardation and radiation are neglected, also with many bins and with a cathode plane.
  • Binning uses the longitudinal momentum only. The transverse velocity spread inside a bin is not resolved.
  • With binned P3M, the long-range part follows the bin velocity, and only the short-range pair part follows the velocity of each particle.
  • The pair term of P3M models physical collisions only for macroparticles that carry the charge of one physical particle.
  • The cathode is an infinite, flat, perfectly conducting plane normal to the beam axis. Only one emission source may define it. Image charges receive no P3M pair term.
  • REPEATS treats every neighbouring bunch as an exact copy of the tracked bunch. Differences between bunches are not modelled, and the copies cannot be combined with a cathode plane.