elements.asciidoc 107 KB
Newer Older
gsell's avatar
gsell committed
1
ifdef::env-gitlab[]
gsell's avatar
gsell committed
2 3 4
include::Manual.attributes[]
include::env-gitlab.attributes[]
{link_home}
gsell's avatar
gsell committed
5 6

toc::[]
gsell's avatar
gsell committed
7
endif::[]
gsell's avatar
gsell committed
8

9 10 11
ifdef::backend-docbook5[:fig-width-default: scaledwidth=10cm]
ifdef::backend-html5,env-gitlab[:fig-width-default: width=50%]

gsell's avatar
gsell committed
12 13
[[chp.elements]]
== Elements
gsell's avatar
gsell committed
14

gsell's avatar
gsell committed
15 16
[[sec.elements.input-format]]
=== Element Input Format
gsell's avatar
gsell committed
17 18 19

All physical elements are defined by statements of the form

20
----
gsell's avatar
gsell committed
21
label:keyword, attribute,..., attribute
22
----
gsell's avatar
gsell committed
23 24 25 26 27

where

label::
  Is the name to be given to the element (in the example QF), it is an
28
  identifier see link:format#sec.format.label[Identifiers or Labels].
gsell's avatar
gsell committed
29
keyword::
30
  Is a keyword see link:format#sec.format.label[Identifiers or Labels], it is an element type keyword (in
gsell's avatar
gsell committed
31 32 33 34
  the example `QUADRUPOLE`),
attribute::
  normally has the form
+
35
----
gsell's avatar
gsell committed
36
attribute-name=attribute-value
37
----
gsell's avatar
gsell committed
38 39 40
attribute-name::
  selects the attribute from the list defined for the element type
  `keyword` (in the example `L` and `K1`). It must be an identifier
41
  see link:format#sec.format.label[Identifiers or Labels].
gsell's avatar
gsell committed
42
attribute-value::
43
  gives it a value see link:format#sec.format.attribute[Command Attribute Types] (in the example `1.8` and
gsell's avatar
gsell committed
44 45 46 47 48 49
  `0.015832`).

Omitted attributes are assigned a default value, normally zero.

Example:

50
----
gsell's avatar
gsell committed
51
QF: QUADRUPOLE, L=1.8, K1=0.015832;
52
----
gsell's avatar
gsell committed
53

gsell's avatar
gsell committed
54 55
[[sec.elements.common]]
=== Common Attributes for all Elements
gsell's avatar
gsell committed
56 57 58 59

The following attributes are allowed on all elements:

TYPE::
60
  A string value see link:format#sec.format.astring[String Attributes]. It specifies an "engineering
gsell's avatar
gsell committed
61 62
  type" and can be used for element selection.
APERTURE::
63
  A string value see link:format#sec.format.astring[String Attributes] which describes the element
gsell's avatar
gsell committed
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
  aperture. All but the last attribute of the aperture have units of
  meter, the last one is optional and is a positive real number.
  Possible choices are
+
  * `APERTURE`="SQUARE(a,f)" has a square shape of width and
  height `a`,
  * `APERTURE`="RECTANGLE(a,b,f)" has a rectangular shape of width
  `a` and height `b`,
  * `APERTURE`="CIRCLE(d,f)" has a circular shape of diameter `d`,
  * `APERTURE`="ELLIPSE(a,b,f)" has an elliptical shape of major
  `a` and minor `b`.
+
The option `SQUARE`(`a,f`) is equivalent to `RECTANGLE`(`a,a,f`) and
`CIRCLE`(`d,f`) is equivalent to `ELLIPSE`(`d,d,f`). The size of the
exit aperture is scaled by a factor latexmath:[f]. For
latexmath:[f < 1] the exit aperture is smaller than the entrance
aperture, for latexmath:[f = 1] they are the same and for
latexmath:[f > 1] the exit aperture is bigger.
+
Dipoles have `GAP` and `HGAP` which define an aperture and hence do
not recognise `APERTURE`. The aperture of the dipoles has rectangular
shape of height `GAP` and width `HGAP`. In longitudinal direction it
is bent such that its center coincides with the circular segment of
the reference particle when ignoring fringe fields. Between the
beginning of the fringe field and the entrance face and between the
exit face and the end of the exit fringe field the rectangular shape
has width and height that are twice of what they are inside the
dipole.
+
Default aperture for all other elements is a circle of 1.0m.
L::
  The length of the element (default: 0m).
ELEMEDGE::
  The edge of an element is specified in s coordinates in meters. This
  edge corresponds to the origin of the local coordinate system and is
  the physical start of the element. (Note that in general the fields
  will extend in front of this position.) The physical end of the
  element is determined by `ELEMEDGE` and its physical length. (Note
  again that in general the fields will extend past the physical end of
  the element.)
X::
105 106
  X-component of the position of the element relative to the position of the first
  beamline which it is part of and which uses absolute positioning.
gsell's avatar
gsell committed
107
Y::
108 109
  Y-component of the position of the element relative to the position of the first
  beamline which it is part of and which uses absolute positioning.
gsell's avatar
gsell committed
110
Z::
111 112
  Z-component of the position of the element relative to the position of the first
  beamline which it is part of and which uses absolute positioning.
gsell's avatar
gsell committed
113
THETA::
114 115
  Angle of rotation of the element about the y-axis relative to the orientation
  of the first beamline which it is part of and which uses absolute positioning.
gsell's avatar
gsell committed
116
PHI::
117 118
  Angle of rotation of the element about the x-axis relative to the orientation
  of the first beamline which it is part of and which uses absolute positioning.
gsell's avatar
gsell committed
119
PSI::
120 121 122
  Angle of rotation of the element about the z-axis relative to the orientation
  of the first beamline which it is part of and which uses absolute positioning.
////
gsell's avatar
gsell committed
123 124 125 126 127
ORIGIN::
  3D position vector. An alternative to using `X`, `Y` and `Z` to
  position the element. Cant be combined with `THETA` and `PHI`. Use
  `ORIENTATION` instead.
ORIENTATION::
gsell's avatar
gsell committed
128
  Vector of Tait-Bryan angles <<bib.tait-bryan_elements,bib.tait-bryan>>. An alternative to rotate
gsell's avatar
gsell committed
129 130
  the element instead of using `THETA`, `PHI` and `PSI`. Cant be
  combined with `X`, `Y` and `Z`, use `ORIGIN` instead.
131
////
gsell's avatar
gsell committed
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
DX::
  Error on x-component of position of element. Doesnt affect the design
  trajectory.
DY::
  Error on y-component of position of element. Doesnt affect the design
  trajectory.
DZ::
  Error on z-component of position of element. Doesnt affect the design
  trajectory.
DTHETA::
  Error on angle `THETA`. Doesnt affect the design trajectory.
DPHI::
  Error on angle `PHI`. Doesnt affect the design trajectory.
DPSI::
  Error on angle `PSI`. Doesnt affect the design trajectory.
kraus's avatar
kraus committed
147 148
WAKEF::
  Attach wakefield that was defined using the `WAKE` command.
149
PARTICLEMATTERINTERACTION::
150
  Attach a handler for particle-matter interaction, see Chapter link:partmatter#chp.partmatter[Particle Matter Interaction].
151 152 153 154 155 156
OUTFN::
  The file name into which the element should write the collected data.
  The user must only provide the output name without the extension. The 
  extension will be set according to the link:control#sec.control.option[`OPTION`] 
  statements. If this attribute is empty, the file will be named as the
  element label.
gsell's avatar
gsell committed
157 158 159 160

All elements can have arbitrary additional attributes which are defined
in the respective section.

gsell's avatar
gsell committed
161 162
[[sec.elements.drift]]
=== Drift Spaces
gsell's avatar
gsell committed
163

164
----
gsell's avatar
gsell committed
165
label:DRIFT, TYPE=string, APERTURE=string, L=real;
166
----
gsell's avatar
gsell committed
167 168 169

A DRIFT space has no additional attributes. Examples:

170
----
gsell's avatar
gsell committed
171 172
DR1:DRIFT, L=1.5;
DR2:DRIFT, L=DR1->L, TYPE=DRF;
173
----
gsell's avatar
gsell committed
174 175

The length of `DR2` will always be equal to the length of `DR1`. The
176 177
reference system for a drift space is a Cartesian coordinate system. This
is a restricted feature of _OPAL-t_. In _OPAL-t_ drifts are implicitly
gsell's avatar
gsell committed
178 179
given, if no field is present.

gsell's avatar
gsell committed
180 181
[[sec.elements.bend]]
=== Bending Magnets
gsell's avatar
gsell committed
182 183 184

Bending magnets refer to dipole fields that bend particle trajectories.
Currently _OPAL_ supports the following different bend elements: `RBEND`, (valid
gsell's avatar
gsell committed
185 186 187
in _OPAL-t_, see <<sec.elements.RBend>>), `SBEND` (valid in _OPAL-t_, see
<<sec.elements.SBend>>), `RBEND3D`, (valid in _OPAL-t_, see <<sec.elements.RBend3D>>)
and `SBEND3D` (valid in _OPAL-cycl_, see <<sec.elements.SBend3D>>).
gsell's avatar
gsell committed
188 189 190 191 192

Describing a bending magnet can be somewhat complicated as there can be
many parameters to consider: bend angle, bend radius, entrance and exit
angles etc. Therefore we have divided this section into several parts:

gsell's avatar
gsell committed
193
1.  <<sec.elements.RBend>> and <<sec.elements.SBend>> describe the geometry and attributes of the
gsell's avatar
gsell committed
194
_OPAL-t_ bend elements `RBEND` and `SBEND`.
gsell's avatar
gsell committed
195
2.  <<sec.elements.RBendSBendExamp>> describes how to implement an `RBEND` or
gsell's avatar
gsell committed
196
`SBEND` in an _OPAL-t_ simulation.
gsell's avatar
gsell committed
197
3.  <<sec.elements.SBend3D>> is self contained. It describes how to implement
gsell's avatar
gsell committed
198 199
an `SBEND3D` element in an _OPAL-cycl_ simulation.

gsell's avatar
gsell committed
200
<<fig_rbend>> illustrates a general rectangular bend (`RBEND`) with a positive bend angle latexmath:[\alpha]. The entrance edge angle, latexmath:[E_{1}], is positive in this example. An `RBEND` has parallel entrance and exit pole faces, so the exit angle, latexmath:[E_{2}], is uniquely determined by the bend angle, latexmath:[\alpha], and latexmath:[E_{1}] (latexmath:[E_{2}=\alpha - E_{1}]). For a positively charge particle, the magnetic field is directed out of the page.
gsell's avatar
gsell committed
201

gsell's avatar
gsell committed
202
.Illustration of a general rectangular bend (`RBEND`) with a positive bend angle latexmath:[\alpha].
203
[[fig_rbend,Figure {counter:fig-cnt}]]
204
image::figures/Elements/rbend.png[{fig-width-default}]
gsell's avatar
gsell committed
205 206 207

[[sec.elements.RBend]]
==== RBend (_OPAL-t_)
gsell's avatar
gsell committed
208 209

An `RBEND` is a rectangular bending magnet. The key property of an
gsell's avatar
gsell committed
210
`RBEND` is that it has parallel pole faces. <<fig_rbend>> shows an
gsell's avatar
gsell committed
211 212 213
`RBEND` with a positive bend angle and a positive entrance edge angle.

L::
gsell's avatar
gsell committed
214
  Physical length of magnet (meters, see <<fig_rbend>>).
gsell's avatar
gsell committed
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233
GAP::
  Full vertical gap of the magnet (meters).
HAPERT::
  Non-bend plane aperture of the magnet (meters). (Defaults to one half
  the bend radius.)
ANGLE::
  Bend angle (radians). Field amplitude of bend will be adjusted to
  achieve this angle. (Note that for an `RBEND`, the bend angle must be
  less than latexmath:[\frac{\pi}{2} + E1], where `E1` is the entrance
  edge angle.)
K0::
  Field amplitude in y direction (Tesla). If the `ANGLE` attribute is
  set, `K0` is ignored.
K0S::
  Field amplitude in x direction (Tesla). If the `ANGLE` attribute is
  set, `K0S` is ignored.
K1::
  Field gradient index of the magnet,
  latexmath:[K_1=-\frac{R}{B_{y}}\frac{\partial B_y}{\partial x}],
gsell's avatar
gsell committed
234
  where latexmath:[R] is the bend radius as defined in <<fig_rbend>>.
235
  Not supported in _OPAL-t_ any more. Superimpose a `Quadrupole`
gsell's avatar
gsell committed
236 237
  instead.
E1::
gsell's avatar
gsell committed
238
  Entrance edge angle (radians). <<fig_rbend>> shows the definition of
gsell's avatar
gsell committed
239 240 241 242 243
  a positive entrance edge angle. (Note that the exit edge angle is
  fixed in an `RBEND` element to
  latexmath:[\mathrm{E2} = \mathrm{ANGLE} - \mathrm{E1}]).
DESIGNENERGY::
  Energy of the reference particle (MeV). The reference particle travels
gsell's avatar
gsell committed
244
  approximately the path shown in <<fig_rbend>>.
gsell's avatar
gsell committed
245 246
FMAPFN::
  Name of the field map for the magnet. Currently maps of type
snuverink_j's avatar
snuverink_j committed
247
  link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`] can be used. The default option
gsell's avatar
gsell committed
248
  for this attribute is `FMAPN` = `1DPROFILE1-DEFAULT`
249 250
  see_<<sec.elements.benddefaultfieldmapopalt>>. The field map is used to
  describe the fringe fields of the magnet see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`].
gsell's avatar
gsell committed
251

gsell's avatar
gsell committed
252 253
[[sec.elements.RBend3D]]
==== RBend3D (_OPAL-t_)
gsell's avatar
gsell committed
254 255

An `RBEND3D3D` is a rectangular bending magnet. The key property of an
gsell's avatar
gsell committed
256
`RBEND3D` is that it has parallel pole faces. <<fig_rbend>> shows an
gsell's avatar
gsell committed
257 258 259
`RBEND3D` with a positive bend angle and a positive entrance edge angle.

L::
gsell's avatar
gsell committed
260
  Physical length of magnet (meters, see <<fig_rbend>>).
gsell's avatar
gsell committed
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279
GAP::
  Full vertical gap of the magnet (meters).
HAPERT::
  Non-bend plane aperture of the magnet (meters). (Defaults to one half
  the bend radius.)
ANGLE::
  Bend angle (radians). Field amplitude of bend will be adjusted to
  achieve this angle. (Note that for an `RBEND3D`, the bend angle must
  be less than latexmath:[\frac{\pi}{2} + E1], where `E1` is the
  entrance edge angle.)
K0::
  Field amplitude in y direction (Tesla). If the `ANGLE` attribute is
  set, `K0` is ignored.
K0S::
  Field amplitude in x direction (Tesla). If the `ANGLE` attribute is
  set, `K0S` is ignored.
K1::
  Field gradient index of the magnet,
  latexmath:[K_1=-\frac{R}{B_{y}}\frac{\partial B_y}{\partial x}],
gsell's avatar
gsell committed
280
  where latexmath:[R] is the bend radius as defined in <<fig_rbend>>.
281
  Not supported in _OPAL-t_ any more. Superimpose a `Quadrupole`
gsell's avatar
gsell committed
282 283
  instead.
E1::
gsell's avatar
gsell committed
284
  Entrance edge angle (radians). <<fig_rbend>> shows the definition of
gsell's avatar
gsell committed
285 286 287 288 289
  a positive entrance edge angle. (Note that the exit edge angle is
  fixed in an `RBEND3D` element to
  latexmath:[\mathrm{E2} = \mathrm{ANGLE} - \mathrm{E1}]).
DESIGNENERGY::
  Energy of the reference particle (MeV). The reference particle travels
gsell's avatar
gsell committed
290
  approximately the path shown in <<fig_rbend>>.
gsell's avatar
gsell committed
291 292
FMAPFN::
  Name of the field map for the magnet. Currently maps of type
snuverink_j's avatar
snuverink_j committed
293
  link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`] can be used. The default option
gsell's avatar
gsell committed
294
  for this attribute is `FMAPN` = `1DPROFILE1-DEFAULT`
gsell's avatar
gsell committed
295
  see <<sec.elements.benddefaultfieldmapopalt>>. The field map is used to
snuverink_j's avatar
snuverink_j committed
296
  describe the fringe fields of the magnet link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`].
gsell's avatar
gsell committed
297

gsell's avatar
gsell committed
298
<<fig_sbend>> illustrates a general sector bend(`SBEND`) with a positive bend angle latexmath:[\alpha]. In this example the entrance and exit edge angles latexmath:[E_{1}] and latexmath:[E_{2}] have positive values. For a positively charge particle, the magnetic field is directed out of the page.
gsell's avatar
gsell committed
299 300

.Illustration of a general sector bend(`SBEND`) with a positive bend angle latexmath:[\alpha]
301
[[fig_sbend,Figure {counter:fig-cnt}]]
302
image::figures/Elements/sbend.png[{fig-width-default}]
gsell's avatar
gsell committed
303

gsell's avatar
gsell committed
304 305
[[sec.elements.SBend]]
==== SBend (_OPAL-t_)
gsell's avatar
gsell committed
306 307

An `SBEND` is a sector bending magnet. An `SBEND` can have independent
gsell's avatar
gsell committed
308
entrance and exit edge angles. <<fig_sbend>> shows an `SBEND` with a
gsell's avatar
gsell committed
309 310 311 312
positive bend angle, a positive entrance edge angle, and a positive exit
edge angle.

L::
gsell's avatar
gsell committed
313
  Chord length of the bend reference arc in meters (see <<fig_sbend>>),
gsell's avatar
gsell committed
314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
  given by: latexmath:[L = 2 R \sin\left(\frac{\alpha}{2}\right)]
GAP::
  Full vertical gap of the magnet (meters).
HAPERT::
  Non-bend plane aperture of the magnet (meters). (Defaults to one half
  the bend radius.)
ANGLE::
  Bend angle (radians). Field amplitude of the bend will be adjusted to
  achieve this angle. (Note that practically speaking, bend angles
  greater than latexmath:[\frac{3 \pi}{2}] (270 degrees) can be
  problematic. Beyond this, the fringe fields from the entrance and exit
  pole faces could start to interfere, so be careful when setting up
  bend angles greater than this. An angle greater than or equal to
  latexmath:[2 \pi] (360 degrees) is not allowed.)
K0::
  Field amplitude in y direction (Tesla). If the `ANGLE` attribute is
  set, `K0` is ignored.
K0S::
  Field amplitude in x direction (Tesla). If the `ANGLE` attribute is
  set, `K0S` is ignored.
K1::
  Field gradient index of the magnet,
  latexmath:[K_1=-\frac{R}{B_{y}}\frac{\partial B_y}{\partial x}],
gsell's avatar
gsell committed
337
  where latexmath:[R] is the bend radius as defined in <<fig_sbend>>.
338
  Not supported in _OPAL-t_ any more. Superimpose a `Quadrupole`
gsell's avatar
gsell committed
339 340
  instead.
E1::
gsell's avatar
gsell committed
341
  Entrance edge angle (rad). <<fig_sbend>> shows the definition of a
gsell's avatar
gsell committed
342 343
  positive entrance edge angle.
E2::
gsell's avatar
gsell committed
344
  Exit edge angle (rad). <<fig_sbend>> shows the definition of a
gsell's avatar
gsell committed
345 346 347
  positive exit edge angle.
DESIGNENERGY::
  Energy of the bend reference particle (MeV). The reference particle
gsell's avatar
gsell committed
348
  travels approximately the path shown in <<fig_sbend>>.
gsell's avatar
gsell committed
349 350
FMAPFN::
  Name of the field map for the magnet. Currently maps of type
snuverink_j's avatar
snuverink_j committed
351
  link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`] can be used. The default option
gsell's avatar
gsell committed
352
  for this attribute is `FMAPN` = `1DPROFILE1-DEFAULT`
353 354
  see_<<sec.elements.benddefaultfieldmapopalt>>. The field map is used to
  describe the fringe fields of the magnet see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`].
gsell's avatar
gsell committed
355

gsell's avatar
gsell committed
356 357
[[sec.elements.RBendSBendExamp]]
==== RBend and SBend Examples (_OPAL-t_)
gsell's avatar
gsell committed
358 359 360 361

Describing an `RBEND` or an `SBEND` in an _OPAL-t_ simulation requires
effectively identical commands. There are only slight differences
between the two. The `L` attribute has a different definition for the
362
two types of bends sees <<sec.elements.RBend>> and <<sec.elements.SBend>>, and an `SBEND` has an
gsell's avatar
gsell committed
363
additional attribute `E2` that has no effect on an `RBEND`, see
gsell's avatar
gsell committed
364
<<sec.elements.SBend>>. Therefore, in this section, we will give several
gsell's avatar
gsell committed
365 366 367 368 369 370 371 372
examples of how to implement a bend, using the `RBEND` and `SBEND`
commands interchangeably. The understanding is that the command formats
are essentially the same.

When implementing an `RBEND` or `SBEND` in an _OPAL-t_ simulation, it is
important to note the following:

1.  Internally _OPAL-t_ treats all bends as positive, as defined by
gsell's avatar
gsell committed
373
<<fig_rbend>> and <<fig_sbend>>. Bends in other directions within the x/y plane are
gsell's avatar
gsell committed
374 375 376 377 378 379 380
accomplished by rotating a positive bend about its z axis.
2.  If the `ANGLE` attribute is set to a non-zero value, the `K0` and
`K0S` attributes will be ignored.
3.  When using the `ANGLE` attribute to define a bend, the actual beam
will be bent through a different angle if its mean kinetic energy
doesnt correspond to the `DESIGNENERGY`.
4.  Internally the bend geometry is setup based on the ideal reference
gsell's avatar
gsell committed
381
trajectory, as shown in <<fig_rbend>> and <<fig_sbend>>.
gsell's avatar
gsell committed
382
5.  If the default field map, `1DPROFILE-DEFAULT`
gsell's avatar
gsell committed
383
see <<sec.elements.benddefaultfieldmapopalt>>, is used, the fringe fields will
gsell's avatar
gsell committed
384 385 386 387 388 389 390
be adjusted so that the effective length of the real, soft edge magnet
matches the ideal, hard edge bend that is defined by the reference
trajectory.

For the rest of this section, we will give several examples of how to
input bends in an _OPAL-t_ simulation. We will start with a simple
example using the `ANGLE` attribute to set the bend strength and using
gsell's avatar
gsell committed
391
the default field map see <<sec.elements.benddefaultfieldmapopalt>> for
392
describing the magnet fringe fields see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`]:
gsell's avatar
gsell committed
393

394
----
gsell's avatar
gsell committed
395 396 397 398 399 400
Bend: RBend, ANGLE = 30.0 * Pi / 180.0,
         FMAPFN = "1DPROFILE1-DEFAULT",
         ELEMEDGE = 0.25,
         DESIGNENERGY = 10.0,
         L = 0.5,
         GAP = 0.02;
401
----
gsell's avatar
gsell committed
402 403 404

This is a definition of a simple `RBEND` that bends the beam in a
positive direction 30 degrees (towards the negative x axis as if
gsell's avatar
gsell committed
405
<<fig_rbend>>). It has a design energy of 10 MeV, a length of 0.5 m, a
gsell's avatar
gsell committed
406 407 408
vertical gap of 2 cm and a 0latexmath:[^{\circ}] entrance edge angle.
(Therefore the exit edge angle is 30latexmath:[^{\circ}].) We are
using the default, internal field map "1DPROFILE1-DEFAULT"
gsell's avatar
gsell committed
409
see <<sec.elements.benddefaultfieldmapopalt>> which describes the magnet fringe
410
fields see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`]. When _OPAL_ is run, you will get the
gsell's avatar
gsell committed
411 412 413
following output (assuming an electron beam) for this `RBEND`
definition:

414
----
gsell's avatar
gsell committed
415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437
RBend > Reference Trajectory Properties
RBend > ===============================
RBend >
RBend > Bend angle magnitude:    0.523599 rad (30 degrees)
RBend > Entrance edge angle:     0 rad (0 degrees)
RBend > Exit edge angle:         0.523599 rad (30 degrees)
RBend > Bend design radius:      1 m
RBend > Bend design energy:      1e+07 eV
RBend >
RBend > Bend Field and Rotation Properties
RBend > ==================================
RBend >
RBend > Field amplitude:         -0.0350195 T
RBend > Field index (gradient):  0 m^-1
RBend > Rotation about x axis:   0 rad (0 degrees)
RBend > Rotation about y axis:   0 rad (0 degrees)
RBend > Rotation about z axis:   0 rad (0 degrees)
RBend >
RBend > Reference Trajectory Properties Through Bend Magnet with Fringe Fields
RBend > ======================================================================
RBend >
RBend > Reference particle is bent: 0.523599 rad (30 degrees) in x plane
RBend > Reference particle is bent: 0 rad (0 degrees) in y plane
438
----
gsell's avatar
gsell committed
439 440

The first section of this output gives the properties of the reference
gsell's avatar
gsell committed
441
trajectory like that described in <<fig_rbend>>. From the value of
gsell's avatar
gsell committed
442 443 444 445 446 447 448 449 450 451 452 453 454 455
`ANGLE` and the length, `L`, of the magnet, _OPAL_ calculates the 10 MeV
reference particle trajectory radius, `R`. From the bend geometry and
the entrance angle (0latexmath:[^{\circ}] in this case), the exit
angle is calculated.

The second section gives the field amplitude of the bend and its
gradient (quadrupole focusing component), given the particle charge
(latexmath:[-e] in this case so the amplitude is negative to get a
positive bend direction). Also listed is the rotation of the magnet
about the various axes.

Of course, in the actual simulation the particles will not see a hard
edge bend magnet, but rather a soft edge magnet with fringe fields
described by the `RBEND` field map file `FMAPFN`
456
see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`]. So, once the hard edge bend/reference
gsell's avatar
gsell committed
457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475
trajectory is determined, _OPAL_ then includes the fringe fields in the
calculation. When the user chooses to use the default field map, _OPAL_
will automatically adjust the position of the fringe fields
appropriately so that the soft edge magnet is equivalent to the hard
edge magnet described by the reference trajectory. To check that this
was done properly, _OPAL_ integrates the reference particle through the
final magnet description with the fringe fields included. The result is
shown in the final part of the output. In this case we see that the soft
edge bend does indeed bend our reference particle through the correct
angle.

What is important to note from this first example, is that it is this
final part of the bend output that tells you the actual bend angle of
the reference particle.

In this next example, we merely rewrite the first example, but use `K0`
to set the field strength of the `RBEND`, rather than the `ANGLE`
attribute:

476
----
gsell's avatar
gsell committed
477 478 479 480 481 482
Bend: RBend, K0 = -0.0350195,
         FMAPFN = "1DPROFILE1-DEFAULT",
         ELEMEDGE = 0.25,
         DESIGNENERGY = 10.0E6,
         L = 0.5,
         GAP = 0.02;
483
----
gsell's avatar
gsell committed
484 485 486

The output from _OPAL_ now reads as follows:

487
----
gsell's avatar
gsell committed
488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510
RBend > Reference Trajectory Properties
RBend > ===============================
RBend >
RBend > Bend angle magnitude:    0.523599 rad (30 degrees)
RBend > Entrance edge angle:     0 rad (0 degrees)
RBend > Exit edge angle:         0.523599 rad (30 degrees)
RBend > Bend design radius:      0.999999 m
RBend > Bend design energy:      1e+07 eV
RBend >
RBend > Bend Field and Rotation Properties
RBend > ==================================
RBend >
RBend > Field amplitude:         -0.0350195 T
RBend > Field index (gradient):  0 m^-1
RBend > Rotation about x axis:   0 rad (0 degrees)
RBend > Rotation about y axis:   0 rad (0 degrees)
RBend > Rotation about z axis:   0 rad (0 degrees)
RBend >
RBend > Reference Trajectory Properties Through Bend Magnet with Fringe Fields
RBend > ======================================================================
RBend >
RBend > Reference particle is bent: 0.5236 rad (30.0001 degrees) in x plane
RBend > Reference particle is bent: 0 rad (0 degrees) in y plane
511
----
gsell's avatar
gsell committed
512 513 514 515 516 517 518

The output is effectively identical, to within a small numerical error.

Now, let us modify this first example so that we bend instead in the
negative x direction. There are several ways to do this:

1.
519
----
gsell's avatar
gsell committed
520 521 522 523 524 525
Bend: RBend, ANGLE = -30.0 * Pi / 180.0,
         FMAPFN = "1DPROFILE1-DEFAULT",
         ELEMEDGE = 0.25,
         DESIGNENERGY = 10.0E6,
         L = 0.5,
         GAP = 0.02;
526
----
gsell's avatar
gsell committed
527
2.
528
----
gsell's avatar
gsell committed
529 530 531 532 533 534 535
Bend: RBend, ANGLE = 30.0 * Pi / 180.0,
         FMAPFN = "1DPROFILE1-DEFAULT",
         ELEMEDGE = 0.25,
         DESIGNENERGY = 10.0E6,
         L = 0.5,
         GAP = 0.02,
         ROTATION = Pi;
536
----
gsell's avatar
gsell committed
537
3.
538
----
gsell's avatar
gsell committed
539 540 541 542 543 544
Bend: RBend, K0 = 0.0350195,
         FMAPFN = "1DPROFILE1-DEFAULT",
         ELEMEDGE = 0.25,
         DESIGNENERGY = 10.0E6,
         L = 0.5,
         GAP = 0.02;
545
----
gsell's avatar
gsell committed
546
4.
547
----
gsell's avatar
gsell committed
548 549 550 551 552 553 554
Bend: RBend, K0 = -0.0350195,
         FMAPFN = "1DPROFILE1-DEFAULT",
         ELEMEDGE = 0.25,
         DESIGNENERGY = 10.0E6,
         L = 0.5,
         GAP = 0.02,
         ROTATION = Pi;
555
----
gsell's avatar
gsell committed
556 557 558 559

In each of these cases, we get the following output for the bend (to
within small numerical errors).

560
----
gsell's avatar
gsell committed
561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583
RBend > Reference Trajectory Properties
RBend > ===============================
RBend >
RBend > Bend angle magnitude:    0.523599 rad (30 degrees)
RBend > Entrance edge angle:     0 rad (0 degrees)
RBend > Exit edge angle:         0.523599 rad (30 degrees)
RBend > Bend design radius:      1 m
RBend > Bend design energy:      1e+07 eV
RBend >
RBend > Bend Field and Rotation Properties
RBend > ==================================
RBend >
RBend > Field amplitude:         -0.0350195 T
RBend > Field index (gradient):  -0 m^-1
RBend > Rotation about x axis:   0 rad (0 degrees)
RBend > Rotation about y axis:   0 rad (0 degrees)
RBend > Rotation about z axis:   3.14159 rad (180 degrees)
RBend >
RBend > Reference Trajectory Properties Through Bend Magnet with Fringe Fields
RBend > ======================================================================
RBend >
RBend > Reference particle is bent: -0.523599 rad (-30 degrees) in x plane
RBend > Reference particle is bent: 0 rad (0 degrees) in y plane
584
----
gsell's avatar
gsell committed
585 586

In general, we suggest to always define a bend in the positive x
gsell's avatar
gsell committed
587
direction (as in <<fig_rbend>>) and then use the `ROTATION` attribute
gsell's avatar
gsell committed
588 589 590 591 592 593
to bend in other directions in the x/y plane (as in examples 2 and 4
above).

As a final `RBEND` example, here is a suggested format for the four bend
definitions if one where implementing a four dipole chicane:

594
----
gsell's avatar
gsell committed
595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629
Bend1: RBend, ANGLE = 20.0 * Pi / 180.0,
              E1 = 0.0,
              FMAPFN = "1DPROFILE1-DEFAULT",
              ELEMEDGE = 0.25,
              DESIGNENERGY = 10.0E6,
              L = 0.25,
              GAP = 0.02,
              ROTATION = Pi;

Bend2: RBend, ANGLE = 20.0 * Pi / 180.0,
              E1 = 20.0 * Pi / 180.0,
              FMAPFN = "1DPROFILE1-DEFAULT",
              ELEMEDGE = 1.0,
              DESIGNENERGY = 10.0E6,
              L = 0.25,
              GAP = 0.02,
              ROTATION = 0.0;

Bend3: RBend, ANGLE = 20.0 * Pi / 180.0,
              E1 = 0.0,
              FMAPFN = "1DPROFILE1-DEFAULT",
              ELEMEDGE = 1.5,
              DESIGNENERGY = 10.0E6,
              L = 0.25,
              GAP = 0.02,
              ROTATION = 0.0;

Bend4: RBend, ANGLE = 20.0 * Pi / 180.0,
              E1 = 20.0 * Pi / 180.0,
              FMAPFN = "1DPROFILE1-DEFAULT",
              ELEMEDGE = 2.25,
              DESIGNENERGY = 10.0E6,
              L = 0.25,
              GAP = 0.02,
              ROTATION = Pi;
630
----
gsell's avatar
gsell committed
631 632 633 634

Up to now, we have only given examples of `RBEND` definitions. If we
replaced "RBend" in the above examples with "SBend", we would still
be defining valid _OPAL-t_ bends. In fact, by adjusting the `L`
gsell's avatar
gsell committed
635
attribute according to <<sec.elements.RBend>> and <<sec.elements.SBend>>, and by adding the
gsell's avatar
gsell committed
636 637 638 639 640 641
appropriate definitions of the `E2` attribute, we could even get
identical results using `SBEND`s instead of `RBEND`s. (As we said, the
two bends are very similar in command format.)

Up till now, we have only used the default field map. Custom field maps
can also be used. There are two different options in this case
642
see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`]:
gsell's avatar
gsell committed
643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659

1.  Field map defines fringe fields and magnet length.
2.  Field map defines fringe fields only.

The first case describes how field maps were used in previous versions
of _OPAL_ (and can still be used in the current version). The second
option is new to _OPAL_ __OPAL__version 1.2.00 and it has a couple of
advantages:

1.  Because only the fringe fields are described, the length of the
magnet must be set using the `L` attribute. In turn, this means that the
same field map can be used by many bend magnets with different lengths
(assuming they have equivalent fringe fields). By contrast, if the
magnet length is set by the field map, one must generate a new field map
for each dipole of different length even if the fringe fields are the
same.
2.  We can adjust the position of the fringe field origin relative to
660
the entrance and exit points of the magnet see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`].
gsell's avatar
gsell committed
661 662 663 664 665 666 667
This gives us another degree of freedom for describing the fringe
fields, allowing us to adjust the effective length of the magnet.

We will now give examples of how to use a custom field map, starting
with the first case where the field map describes the fringe fields and
the magnet length. Assume we have the following `1DProfile1` field map:

668
----
gsell's avatar
gsell committed
669 670 671 672 673 674 675
1DProfile1 1 1 2.0
 -10.0  0.0  10.0 1
  15.0  25.0 35.0 1
  0.00000E+00
  2.00000E+00
  0.00000E+00
  2.00000E+00
676
----
gsell's avatar
gsell committed
677 678 679 680

We can use this field map to define the following bend (note we are now
using the `SBEND` command):

681
----
gsell's avatar
gsell committed
682 683 684 685 686 687 688
Bend: SBend, ANGLE = 60.0 * Pi / 180.0,
             E1 = -10.0 * Pi / 180.0,
             E2 = 20.0  Pi / 180.0,
             FMAPFN = "TEST-MAP.T7",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             GAP = 0.02;
689
----
gsell's avatar
gsell committed
690 691 692 693 694 695

*Notice that we do not set the magnet length using the `L` attribute.*
(In fact, we dont even include it. If we did and set it to a non-zero
value, the exit fringe fields of the magnet would not be correct.) This
input gives the following output:

696
----
gsell's avatar
gsell committed
697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719
SBend > Reference Trajectory Properties
SBend > ===============================
SBend >
SBend > Bend angle magnitude:    1.0472 rad (60 degrees)
SBend > Entrance edge angle:     -0.174533 rad (-10 degrees)
SBend > Exit edge angle:         0.349066 rad (20 degrees)
SBend > Bend design radius:      0.25 m
SBend > Bend design energy:      1e+07 eV
SBend >
SBend > Bend Field and Rotation Properties
SBend > ==================================
SBend >
SBend > Field amplitude:         -0.140385 T
SBend > Field index (gradient):  0 m^-1
SBend > Rotation about x axis:   0 rad (0 degrees)
SBend > Rotation about y axis:   0 rad (0 degrees)
SBend > Rotation about z axis:   0 rad (0 degrees)
SBend >
SBend > Reference Trajectory Properties Through Bend Magnet with Fringe Fields
SBend > ======================================================================
SBend >
SBend > Reference particle is bent: 1.0472 rad (60 degrees) in x plane
SBend > Reference particle is bent: 0 rad (0 degrees) in y plane
720
----
gsell's avatar
gsell committed
721 722 723 724 725 726 727 728 729 730

Because we set the bend strength using the `ANGLE` attribute, the magnet
field strength is automatically adjusted so that the reference particle
is bent exactly `ANGLE` radians when the fringe fields are included.
(Lower output.)

Now we will illustrate the case where the magnet length is set by the
`L` attribute and only the fringe fields are described by the field map.
We change the _TEST-MAP.T7_ file to:

731
----
gsell's avatar
gsell committed
732 733 734 735 736 737 738
1DProfile1 1 1 2.0
 -10.0  0.0  10.0 1
 -10.0  0.0  10.0 1
  0.00000E+00
  2.00000E+00
  0.00000E+00
  2.00000E+00
739
----
gsell's avatar
gsell committed
740 741 742

and change the bend input to:

743
----
gsell's avatar
gsell committed
744 745 746 747 748 749 750 751
Bend: SBend, ANGLE = 60.0 * Pi / 180.0,
             E1 = -10.0 * Pi / 180.0,
             E2 = 20.0  Pi / 180.0,
             FMAPFN = "TEST-MAP.T7",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             L = 0.25,
             GAP = 0.02;
752
----
gsell's avatar
gsell committed
753 754 755

This results in the same output as the previous example, as we expect.

756
----
gsell's avatar
gsell committed
757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779
SBend > Reference Trajectory Properties
SBend > ===============================
SBend >
SBend > Bend angle magnitude:    1.0472 rad (60 degrees)
SBend > Entrance edge angle:     -0.174533 rad (-10 degrees)
SBend > Exit edge angle:         0.349066 rad (20 degrees)
SBend > Bend design radius:      0.25 m
SBend > Bend design energy:      1e+07 eV
SBend >
SBend > Bend Field and Rotation Properties
SBend > ==================================
SBend >
SBend > Field amplitude:         -0.140385 T
SBend > Field index (gradient):  0 m^-1
SBend > Rotation about x axis:   0 rad (0 degrees)
SBend > Rotation about y axis:   0 rad (0 degrees)
SBend > Rotation about z axis:   0 rad (0 degrees)
SBend >
SBend > Reference Trajectory Properties Through Bend Magnet with Fringe Fields
SBend > ======================================================================
SBend >
SBend > Reference particle is bent: 1.0472 rad (60 degrees) in x plane
SBend > Reference particle is bent: 0 rad (0 degrees) in y plane
780
----
gsell's avatar
gsell committed
781 782 783 784

As a final example, let us now use the previous field map with the
following input:

785
----
gsell's avatar
gsell committed
786 787 788 789 790 791 792 793
Bend: SBend, K0 = -0.1400778,
             E1 = -10.0 * Pi / 180.0,
             E2 = 20.0  Pi / 180.0,
             FMAPFN = "TEST-MAP.T7",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             L = 0.25,
             GAP = 0.02;
794
----
gsell's avatar
gsell committed
795 796 797 798

Instead of setting the bend strength using `ANGLE`, we use `K0`. This
results in the following output:

799
----
gsell's avatar
gsell committed
800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822
SBend > Reference Trajectory Properties
SBend > ===============================
SBend >
SBend > Bend angle magnitude:    1.0472 rad (60 degrees)
SBend > Entrance edge angle:     -0.174533 rad (-10 degrees)
SBend > Exit edge angle:         0.349066 rad (20 degrees)
SBend > Bend design radius:      0.25 m
SBend > Bend design energy:      1e+07 eV
SBend >
SBend > Bend Field and Rotation Properties
SBend > ==================================
SBend >
SBend > Field amplitude:         -0.140078 T
SBend > Field index (gradient):  0 m^-1
SBend > Rotation about x axis:   0 rad (0 degrees)
SBend > Rotation about y axis:   0 rad (0 degrees)
SBend > Rotation about z axis:   0 rad (0 degrees)
SBend >
SBend > Reference Trajectory Properties Through Bend Magnet with Fringe Fields
SBend > ======================================================================
SBend >
SBend > Reference particle is bent: 1.04491 rad (59.8688 degrees) in x plane
SBend > Reference particle is bent: 0 rad (0 degrees) in y plane
823
----
gsell's avatar
gsell committed
824 825 826 827 828 829 830 831 832 833 834 835

In this case, the bend angle for the reference trajectory in the first
section of the output no longer matches the reference trajectory bend
angle from the lower section (although the difference is small). The
reason is that the path of the reference particle through the real
magnet (with fringe fields) no longer matches the ideal trajectory. (The
effective length of the real magnet is not quite the same as the hard
edged magnet for the reference trajectory.)

We can compensate for this by changing the field map file _TEST-MAP.T7_
file to:

836
----
gsell's avatar
gsell committed
837 838 839 840 841 842 843
1DProfile1 1 1 2.0
 -10.0  -0.03026  10.0 1
 -10.0  0.03026  10.0 1
  0.00000E+00
  2.00000E+00
  0.00000E+00
  2.00000E+00
844
----
gsell's avatar
gsell committed
845

846 847
We have moved the Enge function origins see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`] outward
from the entrance and exit faces of the magnet see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`]
gsell's avatar
gsell committed
848 849 850
by 0.3026 mm. This has the effect of making the effective length of the
soft edge magnet longer. When we do this, the same input:

851
----
gsell's avatar
gsell committed
852 853 854 855 856 857 858 859
Bend: SBend, K0 = -0.1400778,
             E1 = -10.0 * Pi / 180.0,
             E2 = 20.0  Pi / 180.0,
             FMAPFN = "TEST-MAP.T7",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             L = 0.25,
             GAP = 0.02;
860
----
gsell's avatar
gsell committed
861 862 863

produces

864
----
gsell's avatar
gsell committed
865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887
SBend > Reference Trajectory Properties
SBend > ===============================
SBend >
SBend > Bend angle magnitude:    1.0472 rad (60 degrees)
SBend > Entrance edge angle:     -0.174533 rad (-10 degrees)
SBend > Exit edge angle:         0.349066 rad (20 degrees)
SBend > Bend design radius:      0.25 m
SBend > Bend design energy:      1e+07 eV
SBend >
SBend > Bend Field and Rotation Properties
SBend > ==================================
SBend >
SBend > Field amplitude:         -0.140078 T
SBend > Field index (gradient):  0 m^-1
SBend > Rotation about x axis:   0 rad (0 degrees)
SBend > Rotation about y axis:   0 rad (0 degrees)
SBend > Rotation about z axis:   0 rad (0 degrees)
SBend >
SBend > Reference Trajectory Properties Through Bend Magnet with Fringe Fields
SBend > ======================================================================
SBend >
SBend > Reference particle is bent: 1.0472 rad (60 degrees) in x plane
SBend > Reference particle is bent: 0 rad (0 degrees) in y plane
888
----
gsell's avatar
gsell committed
889 890 891 892 893 894

Now we see that the bend angle for the ideal, hard edge magnet, matches
the bend angle of the reference particle through the soft edge magnet.
In other words, the effective length of the soft edge, real magnet is
the same as the hard edge magnet described by the reference trajectory.

gsell's avatar
gsell committed
895 896
[[sec.elements.opaltrbendsbendfields]]
==== Bend Fields from 1D Field Maps (_OPAL-t_)
gsell's avatar
gsell committed
897

snuverink_j's avatar
snuverink_j committed
898
.Plot of the entrance fringe field of a dipole magnet along the mid-plane, perpendicular to its entrance face. The field is normalized to 1.0. In this case, the fringe field is described by an Enge function see <<eq-enge_func>> with the parameters from the default `1DProfile1` field map described in <<sec.elements.benddefaultfieldmapopalt>>. The exit fringe field of this magnet is the mirror image.
899
[[fig_rbend_enge_fringe,Figure {counter:fig-cnt}]]
900
image::figures/Elements/Enge-func-plot.png[{fig-width-default}]
gsell's avatar
gsell committed
901 902 903 904 905 906 907 908 909 910

So far we have described how to setup an `RBEND` or `SBEND` element, but
have not explained how _OPAL-t_ uses this information to calculate the
magnetic field. The field of both types of magnets is divided into three
regions:

1.  Entrance fringe field.
2.  Central field.
3.  Exit fringe field.

911
This can be seen clearly in <<fig_rbend_field_profile>>.
gsell's avatar
gsell committed
912

913
The purpose of the `1DProfile1` field map see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`]
gsell's avatar
gsell committed
914
associated with the element is to define the Enge functions
snuverink_j's avatar
snuverink_j committed
915
(<<eq-enge_func>>) that model the entrance and exit fringe fields.
gsell's avatar
gsell committed
916 917 918 919
To model a particular bend magnet, one must fit the field profile along
the mid-plane of the magnet perpendicular to its face for the entrance
and exit fringe fields to the Enge function:

snuverink_j's avatar
snuverink_j committed
920 921
.Enge function
[latexmath#eq-enge_func]
gsell's avatar
gsell committed
922 923 924 925 926 927 928 929 930 931 932 933
++++
  F(z) = \frac{1}{1 + e^{\sum\limits_{n=0}^{N_{order}} c_{n} (z/D)^{n}}}
++++

where latexmath:[D] is the full gap of the magnet,
latexmath:[N_{order}] is the Enge function order and latexmath:[z]
is the distance from the origin of the Enge function perpendicular to
the edge of the dipole. The origin of the Enge function, the order of
the Enge function, latexmath:[N_{order}], and the constants
latexmath:[c_0] to latexmath:[c_{N_{order}}] are free parameters
that are chosen so that the function closely approximates the fringe
region of the magnet being modeled. An example of the entrance fringe
gsell's avatar
gsell committed
934
field is shown in <<fig_rbend_enge_fringe>>.
gsell's avatar
gsell committed
935 936

Let us assume we have a correctly defined positive `RBEND` or `SBEND`
gsell's avatar
gsell committed
937
element as illustrated in <<fig_rbend>> and <<fig_sbend>>. (As already stated, any
gsell's avatar
gsell committed
938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957
bend can be described by a rotated positive bend.) _OPAL-t_ then has the
following information:

[latexmath]
++++
\begin{aligned}
B_0 &= \text{Field amplitude (T)} \\
R &= \text{Bend radius (m)} \\
n &= -\frac{R}{B_{y}}\frac{\partial B_y}{\partial x} \text{ (Field index, set using the parameter } \mathrm{K1} \text{)} \\
F(z) &= \left\{
\begin{array}{lll}
    & F_{entrance}(z_{entrance}) \\
    & F_{center}(z_{center}) = 1 \\
    & F_{exit}(z_{exit})
\end{array}
\right.\end{aligned}
++++

Here, we have defined an overall Enge function, latexmath:[F(z)], with
three parts: entrance, center and exit. The exit and entrance fringe
snuverink_j's avatar
snuverink_j committed
958
field regions have the form of <<eq-enge_func>> with parameters
gsell's avatar
gsell committed
959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040
defined by the `1DProfile1` field map file given by the element
parameter `FMAPFN`. Defining the coordinates:

[latexmath]
++++
\begin{aligned}
y &\equiv \text{Vertical distance from magnet mid-plane} \\
\Delta_x &\equiv \text{Perpendicular distance to reference trajectory (see Figures)} \\
\Delta_z &\equiv \left\{
\begin{array}{lll}
    & \text{Distance from entrance Enge function origin perpendicular to magnet entrance face.} \\
    & \text{Not defined, Enge function is always 1 in this region.} \\
    & \text{Distance from exit Enge function origin perpendicular to magnet exit face.}
\end{array}
\right.\end{aligned}
++++

using the conditions

[latexmath]
++++
\begin{aligned}
\nabla \cdot \vec{B} &= 0 \\
\nabla \times \vec{B} &= 0
\end{aligned}
++++

and making the definitions:

[latexmath]
++++
\begin{aligned}
F'(z) &\equiv   \frac{\mathrm{d} F(z)}{\mathrm{d} z} \\
F''(z) &\equiv  \frac{\mathrm{d^{2}} F(z)}{\mathrm{d} z^{2}} \\
F'''(z) &\equiv \frac{\mathrm{d^{3}} F(z)}{\mathrm{d} z^{3}}
\end{aligned}
++++

we can expand the field off axis, with the result:

[latexmath]
++++
\begin{aligned}
B_x(\Delta_x, y, \Delta_z) &= -\frac{B_0 \frac{n}{R}}{\sqrt{\frac{n^2}{R^2} +  \frac{F''(\Delta_z)}{F(\Delta_z}}} e^{-\frac{n}{R} \Delta_x} \sin \left[ \left( \sqrt{\frac{n^2}{R^2} + \frac{F''(\Delta_z)}{F(\Delta_z)}} \right) y \right] F(\Delta_z) \\ \\
B_y(\Delta_x, y, \Delta_z) &= B_0 e^{-\frac{n}{R} \Delta_x} \cos \left[ \left( \sqrt{\frac{n^2}{R^2} + \frac{F''(\Delta_z)}{F(\Delta_z)}} \right) y \right] F(\Delta_z) \\ \\
B_z(\Delta_x, y, \Delta_z) &= B_0 e^{-\frac{n}{R} \Delta_x} \left\{\frac{F'(\Delta_z)}{\sqrt{\frac{n^2}{R^2} + \frac{F''(\Delta_z)}{F(\Delta_z)}}} \sin \left[ \left( \sqrt{\frac{n^2}{R^2} + \frac{F''(\Delta_z)}{F(\Delta_z)}} \right) y \right] \right. \\ \\
&- \frac{1}{2 \sqrt{\frac{n^2}{R^2} + \frac{F''(\Delta_z)}{F(\Delta_z)}}} \left(F'''(\Delta_z) - \frac{F'(\Delta_z) F''(\Delta_z)}{F(\Delta_z)} \right) \left[ \frac{\sin \left[ \left( \sqrt{\frac{n^2}{R^2} + \frac{F''(\Delta_z)}{F(\Delta_z)}} \right) y \right]}{\frac{n^2}{R^2} + \frac{F''(\Delta_z)}{F(\Delta_z)}} \right. \\ \\
&- \left. \left. y \frac{\cos \left[ \left( \sqrt{\frac{n^2}{R^2} + \frac{F''(\Delta_z)}{F(\Delta_z)}} \right) y \right]}{\sqrt{\frac{n^2}{R^2} + \frac{F''(\Delta_z)}{F(\Delta_z)}}} \right] \right\}\end{aligned}
++++

These expression are not well suited for numerical calculation, so, we
expand them about latexmath:[y] to latexmath:[O(y^2)] to obtain:

* In fringe field regions:

[latexmath]
++++
\begin{aligned}
B_x(\Delta_x, y, \Delta_z) &\approx -B_0 \frac{n}{R} e^{-\frac{n}{R} \Delta_x} y \\
B_y(\Delta_x, y, \Delta_z) &\approx B_0 e^{-\frac{n}{R} \Delta_x} \left[ F(\Delta_z) - \left( \frac{n^2}{R^2} F(\Delta_z) + F''(\Delta_z) \right) \frac{y^2}{2} \right] \\
B_z(\Delta_x, y, \Delta_z) &\approx B_0 e^{-\frac{n}{R} \Delta_x} y F'(\Delta_z)
\end{aligned}
++++

* In central region:

[latexmath]
++++
\begin{aligned}
B_x(\Delta_x, y, \Delta_z) &\approx -B_0 \frac{n}{R} e^{-\frac{n}{R} \Delta_x} y \\
B_y(\Delta_x, y, \Delta_z) &\approx B_0 e^{-\frac{n}{R} \Delta_x} \left[ 1 -  \frac{n^2}{R^2} \frac{y^2}{2} \right] \\
B_z(\Delta_x, y, \Delta_z) &\approx 0
\end{aligned}
++++

These are the expressions _OPAL-t_ uses to calculate the field inside an
`RBEND` or `SBEND`. First, a particles position inside the bend is
determined (entrance region, center region, or exit region). Depending
on the region, _OPAL-t_ then determines the values of
latexmath:[\Delta_x], latexmath:[y] and latexmath:[\Delta_z], and
then calculates the field values using the above expressions.

gsell's avatar
gsell committed
1041 1042
[[sec.elements.benddefaultfieldmapopalt]]
==== Default Field Map (_OPAL-t_)
gsell's avatar
gsell committed
1043 1044 1045

Rather than force users to calculate the field of a dipole and then fit
that field to find Enge coefficients for the dipoles in their
gsell's avatar
gsell committed
1046
simulation, we have a default set of values we use from <<bib.enge_elements>> that are
gsell's avatar
gsell committed
1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066
set when the default field map, `1DPROFILE1-DEFAULT` is used:

[latexmath]
++++
\begin{aligned}
  c_{0} &= 0.478959 \\
  c_{1} &= 1.911289 \\
  c_{2} &= -1.185953 \\
  c_{3} &= 1.630554 \\
  c_{4} &= -1.082657 \\
  c_{5} &= 0.318111\end{aligned}
++++

The same values are used for both the entrance and exit regions of the
magnet. In general they will give good results. (Of course, at some
point as a beam line design becomes more advanced, one will want to find
Enge coefficients that fit the actual magnets that will be used in a
given design.)

The default field map is the equivalent of the following custom
1067
`1DProfile1` (see link:fieldmaps#sec.fieldmaps.1DProfile1[`1DProfile1`] for an explanation of the field
gsell's avatar
gsell committed
1068 1069
map format) map:

1070
----
gsell's avatar
gsell committed
1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085
1DProfile1 5 5 2.0
 -10.0 0.0 10.0 1
 -10.0 0.0 10.0 1
  0.478959
  1.911289
 -1.185953
  1.630554
 -1.082657
  0.318111
  0.478959
  1.911289
 -1.185953
  1.630554
 -1.082657
  0.318111
1086
----
gsell's avatar
gsell committed
1087 1088 1089

As one can see, the default magnet gap for `1DPROFILE1-DEFAULT` is
set to 2.0 cm. This value can be overridden by the `GAP` attribute of the
gsell's avatar
gsell committed
1090
magnet (see <<sec.elements.RBend>> and <<sec.elements.SBend>>).
gsell's avatar
gsell committed
1091

gsell's avatar
gsell committed
1092 1093
[[sec.elements.SBend3D]]
==== SBend3D (_OPAL-cycl_)
gsell's avatar
gsell committed
1094 1095 1096 1097 1098

The SBend3D element enables definition of a bend from 3D field maps.
This can be used in conjunction with the `RINGDEFINITION` element to
make a ring for tracking through _OPAL-cycl_.

1099
----
gsell's avatar
gsell committed
1100
label: SBEND3D, FMAPFN=string, LENGTH_UNITS=real, FIELD_UNITS=real;
1101
----
gsell's avatar
gsell committed
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112

FMAPFN::
  The field map file name.
LENGTH_UNITS::
  Units for length (set to 1.0 for units in mm, 10.0 for units in cm,
  etc).
FIELD_UNITS::
  Units for field (set to 1.0 for units in T, 0.001 for units in mT,
  etc).

Field maps are defined using Cartesian coordinates but in a polar