elements.asciidoc 107 KB
 gsell committed Jun 22, 2018 1 ifdef::env-gitlab[]  gsell committed Aug 10, 2020 2 3 4 include::Manual.attributes[] include::env-gitlab.attributes[] {link_home}  gsell committed May 24, 2018 5 6  toc::[]  gsell committed Jun 22, 2018 7 endif::[]  gsell committed May 24, 2018 8   gsell committed Mar 20, 2020 9 10 11 ifdef::backend-docbook5[:fig-width-default: scaledwidth=10cm] ifdef::backend-html5,env-gitlab[:fig-width-default: width=50%]  gsell committed May 30, 2018 12 13 [[chp.elements]] == Elements  gsell committed May 24, 2018 14   gsell committed May 30, 2018 15 16 [[sec.elements.input-format]] === Element Input Format  gsell committed May 24, 2018 17 18 19  All physical elements are defined by statements of the form  gsell committed Apr 17, 2019 20 ----  gsell committed May 24, 2018 21 label:keyword, attribute,..., attribute  gsell committed Apr 17, 2019 22 ----  gsell committed May 24, 2018 23 24 25 26 27  where label:: Is the name to be given to the element (in the example QF), it is an  snuverink_j committed Jun 07, 2018 28  identifier see link:format#sec.format.label[Identifiers or Labels].  gsell committed May 24, 2018 29 keyword::  snuverink_j committed Jun 07, 2018 30  Is a keyword see link:format#sec.format.label[Identifiers or Labels], it is an element type keyword (in  gsell committed May 24, 2018 31 32 33 34  the example QUADRUPOLE), attribute:: normally has the form +  gsell committed Apr 17, 2019 35 ----  gsell committed May 24, 2018 36 attribute-name=attribute-value  gsell committed Apr 17, 2019 37 ----  gsell committed May 24, 2018 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  snuverink_j committed Jun 07, 2018 41  see link:format#sec.format.label[Identifiers or Labels].  gsell committed May 24, 2018 42 attribute-value::  snuverink_j committed Jun 07, 2018 43  gives it a value see link:format#sec.format.attribute[Command Attribute Types] (in the example 1.8 and  gsell committed May 24, 2018 44 45 46 47 48 49  0.015832). Omitted attributes are assigned a default value, normally zero. Example:  gsell committed Apr 17, 2019 50 ----  gsell committed May 24, 2018 51 QF: QUADRUPOLE, L=1.8, K1=0.015832;  gsell committed Apr 17, 2019 52 ----  gsell committed May 24, 2018 53   gsell committed May 30, 2018 54 55 [[sec.elements.common]] === Common Attributes for all Elements  gsell committed May 24, 2018 56 57 58 59  The following attributes are allowed on all elements: TYPE::  snuverink_j committed Jun 07, 2018 60  A string value see link:format#sec.format.astring[String Attributes]. It specifies an "engineering  gsell committed May 24, 2018 61 62  type" and can be used for element selection. APERTURE::  snuverink_j committed Jun 07, 2018 63  A string value see link:format#sec.format.astring[String Attributes] which describes the element  gsell committed May 24, 2018 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::  kraus committed Jul 24, 2020 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 committed May 24, 2018 107 Y::  kraus committed Jul 24, 2020 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 committed May 24, 2018 110 Z::  kraus committed Jul 24, 2020 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 committed May 24, 2018 113 THETA::  kraus committed Jul 24, 2020 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 committed May 24, 2018 116 PHI::  kraus committed Jul 24, 2020 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 committed May 24, 2018 119 PSI::  kraus committed Jul 24, 2020 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 committed May 24, 2018 123 124 125 126 127 ORIGIN:: 3D position vector. An alternative to using X, Y and Z to position the element. Can’t be combined with THETA and PHI. Use ORIENTATION instead. ORIENTATION::  gsell committed Jun 04, 2018 128  Vector of Tait-Bryan angles <>. An alternative to rotate  gsell committed May 24, 2018 129 130  the element instead of using THETA, PHI and PSI. Can’t be combined with X, Y and Z, use ORIGIN instead.  kraus committed Jul 24, 2020 131 ////  gsell committed May 24, 2018 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 DX:: Error on x-component of position of element. Doesn’t affect the design trajectory. DY:: Error on y-component of position of element. Doesn’t affect the design trajectory. DZ:: Error on z-component of position of element. Doesn’t affect the design trajectory. DTHETA:: Error on angle THETA. Doesn’t affect the design trajectory. DPHI:: Error on angle PHI. Doesn’t affect the design trajectory. DPSI:: Error on angle PSI. Doesn’t affect the design trajectory.  kraus committed Jul 24, 2020 147 148 WAKEF:: Attach wakefield that was defined using the WAKE command.  kraus committed Jul 24, 2020 149 PARTICLEMATTERINTERACTION::  ext-calvo_p committed Feb 16, 2021 150  Attach a handler for particle-matter interaction, see Chapter link:partmatter#chp.partmatter[Particle Matter Interaction].  ext-calvo_p committed Jun 01, 2021 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 committed May 24, 2018 157 158 159 160  All elements can have arbitrary additional attributes which are defined in the respective section.  gsell committed May 30, 2018 161 162 [[sec.elements.drift]] === Drift Spaces  gsell committed May 24, 2018 163   gsell committed Apr 17, 2019 164 ----  gsell committed May 24, 2018 165 label:DRIFT, TYPE=string, APERTURE=string, L=real;  gsell committed Apr 17, 2019 166 ----  gsell committed May 24, 2018 167 168 169  A DRIFT space has no additional attributes. Examples:  gsell committed Apr 17, 2019 170 ----  gsell committed May 24, 2018 171 172 DR1:DRIFT, L=1.5; DR2:DRIFT, L=DR1->L, TYPE=DRF;  gsell committed Apr 17, 2019 173 ----  gsell committed May 24, 2018 174 175  The length of DR2 will always be equal to the length of DR1. The  snuverink_j committed Jan 16, 2019 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 committed May 24, 2018 178 179 given, if no field is present.  gsell committed May 30, 2018 180 181 [[sec.elements.bend]] === Bending Magnets  gsell committed May 24, 2018 182 183 184  Bending magnets refer to dipole fields that bend particle trajectories. Currently _OPAL_ supports the following different bend elements: RBEND, (valid  gsell committed Jun 07, 2018 185 186 187 in _OPAL-t_, see <>), SBEND (valid in _OPAL-t_, see <>), RBEND3D, (valid in _OPAL-t_, see <>) and SBEND3D (valid in _OPAL-cycl_, see <>).  gsell committed May 24, 2018 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 committed Jun 07, 2018 193 1. <> and <> describe the geometry and attributes of the  gsell committed May 24, 2018 194 _OPAL-t_ bend elements RBEND and SBEND.  gsell committed Jun 07, 2018 195 2. <> describes how to implement an RBEND or  gsell committed May 24, 2018 196 SBEND in an _OPAL-t_ simulation.  gsell committed Jun 07, 2018 197 3. <> is self contained. It describes how to implement  gsell committed May 24, 2018 198 199 an SBEND3D element in an _OPAL-cycl_ simulation.  gsell committed Jun 07, 2018 200 <> 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 committed May 24, 2018 201   gsell committed May 30, 2018 202 .Illustration of a general rectangular bend (RBEND) with a positive bend angle latexmath:[\alpha].  gsell committed Mar 18, 2020 203 [[fig_rbend,Figure {counter:fig-cnt}]]  gsell committed Mar 20, 2020 204 image::figures/Elements/rbend.png[{fig-width-default}]  gsell committed May 30, 2018 205 206 207  [[sec.elements.RBend]] ==== RBend (_OPAL-t_)  gsell committed May 24, 2018 208 209  An RBEND is a rectangular bending magnet. The key property of an  gsell committed Jun 07, 2018 210 RBEND is that it has parallel pole faces. <> shows an  gsell committed May 24, 2018 211 212 213 RBEND with a positive bend angle and a positive entrance edge angle. L::  gsell committed Jun 07, 2018 214  Physical length of magnet (meters, see <>).  gsell committed May 24, 2018 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 committed Jun 07, 2018 234  where latexmath:[R] is the bend radius as defined in <>.  snuverink_j committed Jan 16, 2019 235  Not supported in _OPAL-t_ any more. Superimpose a Quadrupole  gsell committed May 24, 2018 236 237  instead. E1::  gsell committed Jun 07, 2018 238  Entrance edge angle (radians). <> shows the definition of  gsell committed May 24, 2018 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 committed Jun 07, 2018 244  approximately the path shown in <>.  gsell committed May 24, 2018 245 246 FMAPFN:: Name of the field map for the magnet. Currently maps of type  snuverink_j committed Jun 07, 2018 247  link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1] can be used. The default option  gsell committed May 24, 2018 248  for this attribute is FMAPN = 1DPROFILE1-DEFAULT  snuverink_j committed Jun 07, 2018 249 250  see_<>. The field map is used to describe the fringe fields of the magnet see link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1].  gsell committed May 24, 2018 251   gsell committed May 30, 2018 252 253 [[sec.elements.RBend3D]] ==== RBend3D (_OPAL-t_)  gsell committed May 24, 2018 254 255  An RBEND3D3D is a rectangular bending magnet. The key property of an  gsell committed Jun 07, 2018 256 RBEND3D is that it has parallel pole faces. <> shows an  gsell committed May 24, 2018 257 258 259 RBEND3D with a positive bend angle and a positive entrance edge angle. L::  gsell committed Jun 07, 2018 260  Physical length of magnet (meters, see <>).  gsell committed May 24, 2018 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 committed Jun 07, 2018 280  where latexmath:[R] is the bend radius as defined in <>.  snuverink_j committed Jan 16, 2019 281  Not supported in _OPAL-t_ any more. Superimpose a Quadrupole  gsell committed May 24, 2018 282 283  instead. E1::  gsell committed Jun 07, 2018 284  Entrance edge angle (radians). <> shows the definition of  gsell committed May 24, 2018 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 committed Jun 07, 2018 290  approximately the path shown in <>.  gsell committed May 24, 2018 291 292 FMAPFN:: Name of the field map for the magnet. Currently maps of type  snuverink_j committed Jun 07, 2018 293  link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1] can be used. The default option  gsell committed May 24, 2018 294  for this attribute is FMAPN = 1DPROFILE1-DEFAULT  gsell committed Jun 07, 2018 295  see <>. The field map is used to  snuverink_j committed Jun 07, 2018 296  describe the fringe fields of the magnet link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1].  gsell committed May 24, 2018 297   gsell committed Jun 07, 2018 298 <> 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 committed May 30, 2018 299 300  .Illustration of a general sector bend(SBEND) with a positive bend angle latexmath:[\alpha]  gsell committed Mar 18, 2020 301 [[fig_sbend,Figure {counter:fig-cnt}]]  gsell committed Mar 20, 2020 302 image::figures/Elements/sbend.png[{fig-width-default}]  gsell committed May 24, 2018 303   gsell committed May 30, 2018 304 305 [[sec.elements.SBend]] ==== SBend (_OPAL-t_)  gsell committed May 24, 2018 306 307  An SBEND is a sector bending magnet. An SBEND can have independent  gsell committed Jun 07, 2018 308 entrance and exit edge angles. <> shows an SBEND with a  gsell committed May 24, 2018 309 310 311 312 positive bend angle, a positive entrance edge angle, and a positive exit edge angle. L::  gsell committed Jun 07, 2018 313  Chord length of the bend reference arc in meters (see <>),  gsell committed May 24, 2018 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 committed Jun 07, 2018 337  where latexmath:[R] is the bend radius as defined in <>.  snuverink_j committed Jan 16, 2019 338  Not supported in _OPAL-t_ any more. Superimpose a Quadrupole  gsell committed May 24, 2018 339 340  instead. E1::  gsell committed Jun 07, 2018 341  Entrance edge angle (rad). <> shows the definition of a  gsell committed May 24, 2018 342 343  positive entrance edge angle. E2::  gsell committed Jun 07, 2018 344  Exit edge angle (rad). <> shows the definition of a  gsell committed May 24, 2018 345 346 347  positive exit edge angle. DESIGNENERGY:: Energy of the bend reference particle (MeV). The reference particle  gsell committed Jun 07, 2018 348  travels approximately the path shown in <>.  gsell committed May 24, 2018 349 350 FMAPFN:: Name of the field map for the magnet. Currently maps of type  snuverink_j committed Jun 07, 2018 351  link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1] can be used. The default option  gsell committed May 24, 2018 352  for this attribute is FMAPN = 1DPROFILE1-DEFAULT  snuverink_j committed Jun 07, 2018 353 354  see_<>. The field map is used to describe the fringe fields of the magnet see link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1].  gsell committed May 24, 2018 355   gsell committed May 30, 2018 356 357 [[sec.elements.RBendSBendExamp]] ==== RBend and SBend Examples (_OPAL-t_)  gsell committed May 24, 2018 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  snuverink_j committed Jun 07, 2018 362 two types of bends sees <> and <>, and an SBEND has an  gsell committed May 24, 2018 363 additional attribute E2 that has no effect on an RBEND, see  gsell committed Jun 07, 2018 364 <>. Therefore, in this section, we will give several  gsell committed May 24, 2018 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 committed Jun 07, 2018 373 <> and <>. Bends in other directions within the x/y plane are  gsell committed May 24, 2018 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 doesn’t correspond to the DESIGNENERGY. 4. Internally the bend geometry is setup based on the ideal reference  gsell committed Jun 07, 2018 381 trajectory, as shown in <> and <>.  gsell committed May 24, 2018 382 5. If the default field map, 1DPROFILE-DEFAULT  gsell committed Jun 07, 2018 383 see <>, is used, the fringe fields will  gsell committed May 24, 2018 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 committed Jun 07, 2018 391 the default field map see <> for  snuverink_j committed Jun 07, 2018 392 describing the magnet fringe fields see link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1]:  gsell committed May 24, 2018 393   gsell committed Apr 17, 2019 394 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 401 ----  gsell committed May 24, 2018 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 committed Jun 07, 2018 405 <>). It has a design energy of 10 MeV, a length of 0.5 m, a  gsell committed May 24, 2018 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 committed Jun 07, 2018 409 see <> which describes the magnet fringe  snuverink_j committed Jun 07, 2018 410 fields see link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1]. When _OPAL_ is run, you will get the  gsell committed May 24, 2018 411 412 413 following output (assuming an electron beam) for this RBEND definition:  gsell committed Apr 17, 2019 414 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 438 ----  gsell committed May 24, 2018 439 440  The first section of this output gives the properties of the reference  gsell committed Jun 07, 2018 441 trajectory like that described in <>. From the value of  gsell committed May 24, 2018 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  snuverink_j committed Jun 07, 2018 456 see link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1]. So, once the hard edge bend/reference  gsell committed May 24, 2018 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:  gsell committed Apr 17, 2019 476 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 483 ----  gsell committed May 24, 2018 484 485 486  The output from _OPAL_ now reads as follows:  gsell committed Apr 17, 2019 487 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 511 ----  gsell committed May 24, 2018 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.  gsell committed Apr 17, 2019 519 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 526 ----  gsell committed May 24, 2018 527 2.  gsell committed Apr 17, 2019 528 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 536 ----  gsell committed May 24, 2018 537 3.  gsell committed Apr 17, 2019 538 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 545 ----  gsell committed May 24, 2018 546 4.  gsell committed Apr 17, 2019 547 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 555 ----  gsell committed May 24, 2018 556 557 558 559  In each of these cases, we get the following output for the bend (to within small numerical errors).  gsell committed Apr 17, 2019 560 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 584 ----  gsell committed May 24, 2018 585 586  In general, we suggest to always define a bend in the positive x  gsell committed Jun 07, 2018 587 direction (as in <>) and then use the ROTATION attribute  gsell committed May 24, 2018 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:  gsell committed Apr 17, 2019 594 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 630 ----  gsell committed May 24, 2018 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 committed Jun 07, 2018 635 attribute according to <> and <>, and by adding the  gsell committed May 24, 2018 636 637 638 639 640 641 appropriate definitions of the E2 attribute, we could even get identical results using SBENDs instead of RBENDs. (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  snuverink_j committed Jun 07, 2018 642 see link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1]:  gsell committed May 24, 2018 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  snuverink_j committed Jun 07, 2018 660 the entrance and exit points of the magnet see link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1].  gsell committed May 24, 2018 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:  gsell committed Apr 17, 2019 668 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 676 ----  gsell committed May 24, 2018 677 678 679 680  We can use this field map to define the following bend (note we are now using the SBEND command):  gsell committed Apr 17, 2019 681 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 689 ----  gsell committed May 24, 2018 690 691 692 693 694 695  *Notice that we do not set the magnet length using the L attribute.* (In fact, we don’t 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:  gsell committed Apr 17, 2019 696 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 720 ----  gsell committed May 24, 2018 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:  gsell committed Apr 17, 2019 731 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 739 ----  gsell committed May 24, 2018 740 741 742  and change the bend input to:  gsell committed Apr 17, 2019 743 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 752 ----  gsell committed May 24, 2018 753 754 755  This results in the same output as the previous example, as we expect.  gsell committed Apr 17, 2019 756 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 780 ----  gsell committed May 24, 2018 781 782 783 784  As a final example, let us now use the previous field map with the following input:  gsell committed Apr 17, 2019 785 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 794 ----  gsell committed May 24, 2018 795 796 797 798  Instead of setting the bend strength using ANGLE, we use K0. This results in the following output:  gsell committed Apr 17, 2019 799 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 823 ----  gsell committed May 24, 2018 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:  gsell committed Apr 17, 2019 836 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 844 ----  gsell committed May 24, 2018 845   snuverink_j committed Jun 07, 2018 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 committed May 24, 2018 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:  gsell committed Apr 17, 2019 851 ----  gsell committed May 24, 2018 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;  gsell committed Apr 17, 2019 860 ----  gsell committed May 24, 2018 861 862 863  produces  gsell committed Apr 17, 2019 864 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 888 ----  gsell committed May 24, 2018 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 committed May 30, 2018 895 896 [[sec.elements.opaltrbendsbendfields]] ==== Bend Fields from 1D Field Maps (_OPAL-t_)  gsell committed May 24, 2018 897   snuverink_j committed Jun 08, 2018 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 <> with the parameters from the default 1DProfile1 field map described in <>. The exit fringe field of this magnet is the mirror image.  gsell committed Mar 18, 2020 899 [[fig_rbend_enge_fringe,Figure {counter:fig-cnt}]]  gsell committed Mar 20, 2020 900 image::figures/Elements/Enge-func-plot.png[{fig-width-default}]  gsell committed May 24, 2018 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.  gsell committed Mar 18, 2020 911 This can be seen clearly in <>.  gsell committed May 24, 2018 912   snuverink_j committed Jun 07, 2018 913 The purpose of the 1DProfile1 field map see link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1]  gsell committed May 24, 2018 914 associated with the element is to define the Enge functions  snuverink_j committed Jun 08, 2018 915 (<>) that model the entrance and exit fringe fields.  gsell committed May 24, 2018 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 committed Jun 08, 2018 920 921 .Enge function [latexmath#eq-enge_func]  gsell committed May 24, 2018 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 committed Jun 07, 2018 934 field is shown in <>.  gsell committed May 24, 2018 935 936  Let us assume we have a correctly defined positive RBEND or SBEND  gsell committed Jun 07, 2018 937 element as illustrated in <> and <>. (As already stated, any  gsell committed May 24, 2018 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 committed Jun 08, 2018 958 field regions have the form of <> with parameters  gsell committed May 24, 2018 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 particle’s 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 committed May 30, 2018 1041 1042 [[sec.elements.benddefaultfieldmapopalt]] ==== Default Field Map (_OPAL-t_)  gsell committed May 24, 2018 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 committed Jun 04, 2018 1046 simulation, we have a default set of values we use from <> that are  gsell committed May 24, 2018 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  snuverink_j committed Jun 07, 2018 1067 1DProfile1 (see link:fieldmaps#sec.fieldmaps.1DProfile1[1DProfile1] for an explanation of the field  gsell committed May 24, 2018 1068 1069 map format) map:  gsell committed Apr 17, 2019 1070 ----  gsell committed May 24, 2018 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  gsell committed Apr 17, 2019 1086 ----  gsell committed May 24, 2018 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 committed Jun 07, 2018 1090 magnet (see <> and <>).  gsell committed May 24, 2018 1091   gsell committed May 30, 2018 1092 1093 [[sec.elements.SBend3D]] ==== SBend3D (_OPAL-cycl_)  gsell committed May 24, 2018 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_.  gsell committed Apr 17, 2019 1099 ----  gsell committed May 24, 2018 1100 label: SBEND3D, FMAPFN=string, LENGTH_UNITS=real, FIELD_UNITS=real;  gsell committed Apr 17, 2019 1101 ----  gsell committed May 24, 2018 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