opalt

We define the global cartesian coordinate system, also known as floor coordinate system with K, a point in this coordinate system is denoted by (X, Y, Z) \in K. In Figure [KS1] of the accelerator is uniquely defined by the sequence of physical elements in K. The beam elements are numbered e_0, \ldots , e_i, \ldots e_n.

A local coordinate system K'_i is attached to each element e_i. This is simply a frame in which (0,0,0) is at the entrance of each element. For an illustration see Figure [KS1]. The local reference system (x, y, z) \in K'_n may thus be referred to a global Cartesian coordinate system (X, Y, Z) \in K.

The local coordinates (x_i, y_i, z_i) at element e_i with respect to the global coordinates (X, Y, Z) are defined by three displacements (X_i, Y_i, Z_i) and three angles (\Theta_i, \Phi_i, \Psi_i).

\Psi is the roll angle about the global Z-axis. \Phi is the pitch angle about the global Y-axis. Lastly, \Theta is the yaw angle about the global X-axis. All three angles form right-handed screws with their corresponding axes. The angles (\Theta,\Phi,\Psi) are the Tait-Bryan angles [bib:tait-bryan].

The displacement is described by a vector \mathbf{v} and the orientation by a unitary matrix \mathcal{W}. The column vectors of \mathcal{W} are unit vectors spanning the local coordinate axes in the order (x, y, z). \mathbf{v} and \mathcal{W} have the values:

where

We take the vector \mathbf{r}_i to be the displacement and the matrix \mathcal{S}_i to be the rotation of the local reference system at the exit of the element i with respect to the entrance of that element.

Denoting with i a beam line element, one can compute \mathbf{v}_i and \mathcal{W}_i by the recurrence relations

where \mathbf{v}_0 corresponds to the origin of the LINE and \mathcal{W}_0 to its orientation. In OPAL-t they can be defined using either X, Y, Z, THETA, PHI and PSI or ORIGIN and ORIENTATION, see Section [line:simple].

In order to calculate space charge in the electrostatic approximation, we introduce a co-moving coordinate system K_{\text{sc}}, in which the origin coincides with the mean position of the particles and the mean momentum is parallel to the z-axis.

In order to compute statistics of the particle ensemble, K_s is introduced. The accompanying tripod (Dreibein) of the reference orbit spans a local curvilinear right handed system (x,y,s). The local s-axis is the tangent to the reference orbit. The two other axes are perpendicular to the reference orbit and are labelled x (in the bend plane) and y (perpendicular to the bend plane).

K_\text{sc} and K_s">

Both coordinate systems are described in Figure [KS2].

The reference orbit consists of a series of straight sections and circular arcs and is computed by the Orbit Threader i.e. deduced from the element placement in the floor coordinate system.

To facilitate the change for users we will provide a compatibility mode. The idea is that the user does not have to change the input file. Instead OPAL-t will compute the positions of the elements. For this it uses the bend angle and chord length of the dipoles and the position of the elements along the trajectory. The user can choose whether effects due to fringe fields are considered when computing the path length of dipoles or not. The option to toggle OPAL-t’s behavior is called IDEALIZED. OPAL-t assumes per default that provided ELEMEDGE for elements downstream of a dipole are computed without any effects due to fringe fields.

Elements that overlap with the fields of a dipole have to be handled separately by the user to position them in 3D.

We split the positioning of the elements into two steps. In a first step we compute the positions of the dipoles. Here we assume that their fields don’t overlap. In a second step we can then compute the positions and orientations of all other elements.

The accuracy of this method is good for all elements except for those that overlap with the field of a dipole.

The OrbitThreader integrates a design particle through the lattice and setups up a multi map structure (IndexMap). Furthermore when the reference particle hits an rf-structure for the first time then it auto-phases the rf-structure, see Appendix [autophasing]. The multi map structure speeds up the search for elements that influence the particles at a given position in 3D space by minimizing the looping over elements when integrating an ensemble of particles. For each time step, IndexMap returns a set of elements \mathcal{S}_{\text{e}} \subset {e_0 \ldots e_n} in case of the example given in Figure [KS1]. An implicit drift is modelled as an empty set \emptyset.

A regular time step in OPAL-t is sketched in Figure [OPALTSchemeSimple]. In order to compute the coordinate system transformation from the reference coordinate system K_s to the local coordinate systems K'_n we join the transformation from floor coordinate system K to K'_n to the transformation from K_s to K. All computations of rotations which are involved in the computation of coordinate system transformations are performed using quaternions. The resulting quaternions are then converted to the appropriate matrix representation before applying the rotation operation onto the particle positions and momenta.

As can be seen from Figure [OPALTSchemeSimple] the integration of the trajectories of the particles are integrated and the computation of the statistics of the six-dimensional phase space are performed in the reference coordinate system.

This file is used to log the statistical properties of the bunch in the ASCII variant of the SDDS format [bib:borland1995]. It can be viewed with the SDDS Tools [bib:borland2016] or GNUPLOT. The frequency with which the statistics are computed and written to file can be controlled With the option STATDUMPFREQ. The information that is stored are found in the following table.

OPAL-t computes the statistics of the bunch for every MONITOR that it passes. The information that is written can be found in the following table.

OPAL-t copies the input file into this file and replaces all occurrences of ELEMEDGE with the corresponding position using X, Y, Z, THETA, PHI and PSI.

OPAL-t stores for every element the position of the entrance and the exit. Additionally the reference trajectory inside dipoles is stored. On the first column the name of the element is written prefixed with BEGIN: '', END: '' and ``MID: '' respectively. The remaining columns store the z-component then the x-component and finally the y-component of the position in floor coordinates.

This Python script can be used to generate visualizations of the beam line in different formats. Beside an ASCII file that can be printed using GNUPLOT a VTK file and an HTML file can be generated. The VTK file can then be opened in e.g. ParaView [paraview,bib:paraview] or VisIt [bib:visit]. The HTML file can be opened in any modern web browser. Both the VTK and the HTML output are three-dimensional. For the ASCII format on the other hand you have provide the normal of a plane onto which the beam line is projected.

The script is not directly executable. Instead one has to pass it as argument to python:

The following arguments can be passed

• -h or --help for a short help

• --export-vtk to export to the VTK format

• --export-web to export for the web

• --project-to-plane x y z to project the beam line to the plane with the normal with the components x, y and z

This file can be used when plotting the statistics of the bunch to indicate the positions of the magnets. It is written in the SDDS format. The information that is written can be found in the following table.

The trajectory of the reference particle is stored in this ASCII file. The content of the columns are listed in the following table.

(for a straight multipole)

Most accelerator modeling codes use the hard-edge model for magnets - constant Hamiltonian. Real magnets always have a smooth transition at the edges - fringe fields. To obtain a multipole description of a field we can apply the theory of analytic functions.

Assuming that A has only a non-zero component A_s we get

These equations are just the Cauchy-Riemann conditions for an analytic function \tilde{A} (z) = A_s (x, y) + i V(x,y). So the complex potential is an analytic function and can be expanded as a power series

with \lambda_n, \mu_n being real constants. It is practical to express the field in cylindrical coordinates (r, \varphi, s)

From the real and imaginary parts of equation () we obtain

Taking the gradient of -V(r, \varphi) we obtain the multipole expansion of the azimuthal and radial field components, respectively

Furthermore, we introduce the normal multipole coefficient b_n and skew coefficient a_n defined with the reference radius r_0 and the magnitude of the field at this radius B_0 (these coefficients can be a function of s in a more general case as it is presented further on).

To obtain a model for the fringe field of a straight multipole, a proposed starting solution for a non-skew magnetic field is

It is straightforward to derive a relation between coefficients

By identifying the term in front of the same powers of r we obtain the recurrence relation

The solution of the recursion relation becomes

Therefore

The transverse components of the field are

where the following gradients determine the entire potential and can be deduced from the function C_{n,0}(z) once the harmonic n is fixed.

The z-directed component of the filed can be expressed in a similar form

The gradient functions g_{rn}, g_{\varphi n}, g_{zn} are obtained from

One preferred model to approximate the gradient profile on the central axis is the k-parameter Enge function

where d(z) is the distance to the field boundary and \lambda characterizes the fringe field length.

(fixed radius)

We consider the Frenet-Serret coordinate system ( \hat{\mathbf{x}}, \hat{\mathbf{s}}, \hat{\mathbf{z}} ) with the radius of curvature \rho constant and the scale factor h_s = 1 + x/ \rho. A conversion to these coordinates implies that

To simplify the problem, consider multipoles with mid-plane symmetry, i.e.

The most general form of the expansion is

Maxwell’s equations \nabla \cdot \mathbf{B} = 0 and \nabla \times \mathbf{B} = 0 in the above coordinates yield

The substitution of (1) into Maxwell’s equations allows for the derivation of recursion relations. ([eq:23]) gives

Equating the powers in x^i z^{2k}

A similar result is obtained from ([eq:24])

The last equation from \nabla \times \mathbf{B} = 0 should be consistent with the two recursion relations obtained. ([eq:22]) implies

This results follows directly from ([eq:11]) and ([eq:12]); therefore the relations are consistent. Furthermore, the last required relations is obtained from the divergence of B

Using the relation ([eq:11]) to replace the a coefficients with b’s we arrive at

All the coefficients above can be determined recursively provided the field B_z can be measured at the mid-plane in the form

where B_{i,0} are functions of s and they can model the fringe field for each multipole term x^n. As an example, for a dipole magnet, the B_{1,0} function can be model as an Enge function or tanh.

(variable radius of curvature)

The difference between this case and the above is that \rho is now a function of s, \rho(s). We can obtain the same result starting with the same functional forms for the field (1). The result of the previous section also holds in this case since no derivative \frac{\partial}{\partial s} is applied to the scale factor h_s. If the radius of curvature is set to be proportional to the dipole filed observed by some reference particle that stays in the centre of the dipole

This is a different, more compact treatment The derivation is more clear if we gather the variables together in functions. We assume again mid-plane symmetry and that the z-component of the field in the mid-plane has the form

where T(s) is the transverse field profile and S(s) is the fringe field. One of the requirements of the symmetry is that B_z(z) = B_z(-z) which using a scalar potential \psi requires \frac{\partial \psi}{\partial z} to be an even function in z. Therefore, \psi is an odd function in z and can be written as

The given transverse profile requires that f_0(x,s) = T(x)S(s), while \nabla^2 \psi = 0 follows from Maxwell’s equations as usual, more explicitly

For a straight multipole h_s = 1. Laplace’s equation becomes

By equating powers of z we obtain the recursion relation

The general expression for any f_n(x,s) is then obtained from the mid-plane field by

For a curved multipole of constant radius h_s = 1 + \frac{x}{\rho} \quad \text{with} \quad \rho = const. The corresponding Laplace’s equation is

Again we substitute with the functional form of the potential to get the recursion

Finally consider what changes for \rho = \rho (s). Laplace’s equation is

The last step is again the substitution to get

If the radius of curvature is proportional to the dipole field in the centre of the multipole (the dipole component of the transverse field is a constant T_{dipole}(x) = B_0 and

This expression can be replaced in ([eq:40]) to obtain a more explicit equation.