OPA Tutorial (4.

030) Andreas Streun,

PSI, January 2022
Let’s design a small storage ring in order to get started with OPA and demonstrate its features!
This is OPA’s start panel:

Fig.1 OPA start panel

File is for reading and saving .opa files and for exporting files to other codes.
Edit contains two editors, a plain text editor, and the interactive OPA Editor.
Design is the main part of OPA leading to modules for linear lattice design in terms of beta
functions, non-linear optimization, orbit correction etc.
Tracking is for simulation of dynamic aperture, beam lifetime etc. in order to test the
performance of the lattice.
Extra contains special options, some of them implemented preliminary or temporary only.

Editor
We don’t load an existing .opa file but start from scratch, by using Edit  OPA Editor :

Fig. 2 OPAEditor panel

At first, enter the (maximum) energy of our storage ring, and an optional short description.
The two areas underneath list variables/elements and segments:
 A segment is a line-up of elements. There can be a hierarchical structure of many segments.
In the end one of them will represent the complete ring.
 An element is a quadrupole, a bending magnet, a drift space etc.
 Further there may be variables, which allow algebraic expressions to be entered as element
parameter.
For a ring, we need a bending magnet. So click “new entry” in the left
field, then a small panel pops up to select the kind of element (scroll the
list to see which elements are available!) - and give it a name.
After pressing “Create”, a new panel pops up which lists all the
properties of a bending magnet: Now we should have an idea about the
Fig.
3 Create element panel
layout of our proposed 1.5 GeV ring. Of course, this requires some knowledge on storage rings in
order to start with reasonable parameters:
Assume we want a compact light source ring with only one or two beam lines operating in
the vacuum ultraviolet range (which already motivated the energy of 1.5 GeV based on
similar machines, e.g. SOLARIS). So the ring may have a four-fold symmetry with four
straights, two for undulators serving the beam lines, one for injection, and one for RF cavities
etc. VUV is the 10…100 nm wavelength range. In order to get a large coherent fraction,
emittance should be a few nm (wavelength/4). Minimum achievable emittance
approximately scales as
emittance  1/6 pm  (angle per bend [degrees])3  (energy [GeV])2
however, in a realistic lattice it is about a factor 3 larger than that. So with a bending angle of
22.5=90/4, i.e. 4 bends per arc (or 3 full + 2 half bends anticipating dispersion suppressors),
an emittance of about 13 nm could be expected.
We set the bending magnet half angle to 11.25, because we are interested in the parameters at the
bending magnet center, and therefore prefer to make it from half pieces. Assuming a half
rectangular magnet (as preferable for technical reasons), the entry angle is identical to the bending
angle, and the exit angle, which actually will become the midplane, is zero:

Fig 4. Element Setup

Pressing Apply shows/updates the magnet profile and field strength (no automatic update). The
length was set to 0.8 m in this case to get a reasonable field strength of 1.228 T.
In a similar way, drift spaces D1, D2 and a quadrupole QF was added.
Pressing “new entry” in the right field opens a panel to create a segment, i.e. to enter a line-up of
elements. We create a half unit cell starting from the bend center and call it “HCELL”. However, the
bend was entered with zero exit angle, considering the exit plane as midplane. So it has to be turned
around, which is done by inversion, typing “-B1”.

Fig 5: Segment editor

Colors are assigned to different element types. Non-existent elements are with red background like
CRAP in the example and have to be corrected or deleted. Segments have a pink background like
HCELL . We further create segment CELL = -HCELL, HCELL, which is a full unit cell.
Now, close the OPA Editor panel and open Edit  TextEditor which shows a conventional text
representation of the lattice, rather similar to a MAD or ELEGANT input. The experienced designer
may prefer to enter everything in TextEditor rather than in OPAEditor.
Buttons Test or OK check the syntax and return error messages if something is wrong.
{C:\as\opa\test\[Link]}
{com My little storage ring com}
Energy = 1.500000;
{----- Variables ---------------------------------------------------}
{----- Table of elements ---------------------------------------------}
D1 : Drift, L = 0.200000, Ax = 50.00, Ay = 50.00;
D2 : Drift, L = 0.150000, Ax = 50.00, Ay = 50.00;
QF : Quadrupole, L = 0.15000, K = 6.000000, Ax = 50.00, Ay = 50.00;
B1 : Bending, L = 0.800000, T = 11.250000, K = 0.000000, T1 = 11.250000,
T2 = 0.000000, Ax = 50.00, Ay = 50.00;
{----- Table of segments ---------------------------------------------}
HCELL : -B1, D1, QF, D2;
CELL : -HCELL, HCELL;
{C:\as\opa\test\[Link]}

The file has already been saved, that’s why [Link] appears in the comment. All text in
{curly brackets} is neither read nor saved, except text in {com ... com}, which is the
comment we entered above.
Close editor, select “CELL” in the listbox of the main menu and press “Show Lattice expansion”:

Fig. 6 Lattice expansion

Now the element line-up is shown. Note, that the first B1 was inverted twice (-HCELL in CELL, and
-B1 in HCELL), so it appears in original orientation.

Linear optics
Design  Linear optics opens two panels, a start panel and a plot panel. Select “periodic solution” in
the start panel, because the segment CELL should become our periodic unit cell, and Apply:

Fig. 7: Linear optics and start menu

Blue, red and green curves are horizontal and vertical beta functions and dispersion. Of course, no
periodic solutions was found, because no focusing was entered for the quad and the bending
magnet. The status flag in the main panel (see in background) shows a red skull.
Drag the magnet to a knob: press mouse on the colored magnet bar, drag into the knob field and
release. Now by moving the slider or entering a number in the field, the focusing strength of the
element is changed. The <> >< buttons allow the range to be increased or decreased.

Fig.8: Periodic solution, knobs and the tune diagram

Once a periodic solution is found, a tune diagram pops up to show the location of the working point
(Qx, Qy). The table right of the plot shows the results. In this case, the emittance (“EmitA”) of about
19 nm is rather large, we have to increase Qx and prefer a nice number.
Pressing Matching opens the minimizer window:

Fig.9 Matching minimizer

Select “periodic” as starting conditions, check target functions “Tune X”, “Tune Y” and enter target
values (red column; green shows current values), select knobs “QF”, “B1”, which are our quad and
bend (the box “incl. bends” needs to be checked to see bending magnets which are otherwise
hidden). Then press Go, and if it was successful, press Accept to take over the solution and close
the minimizer. In this example, we get an emittance of 10.5 nm at working point (0.4, 0.05).
Exit closes the Linear Optics windows (either from Start or Plot panel).
Now we have a periodic unit cell of 22.5 deflection. Dispersion is minimum in the bend center, so a
90-arc is conveniently built from 3 unit cells with half cells at the ends in order to suppress
dispersions in straights. In order to do so, we perform the following steps:
1. In the OPAEditor we create a new element of type “Opticsmarker” and name it “OMID”. This
 is just a marker to store a complete set of optics data (betas and dispersion [also orbit and
coupling]) at a particular location. This marker is inserted at the center of the unit cell:

Fig. 10 Inserting an optics marker

2. In Design  Linear optics get again the periodic solution, and then press Write OMK. A small
pup-up panel will ask for confirmation.

3. Back in editor we design a dispersion suppressor: this is a half cell, but with modified values
for quad focusing and drift length in order to have 2 knobs to suppress D and D’, i.e. the
dispersion and its slope. We thus copy quad QF to QFM and drift D1 to D1M, which may be
easier to do in the TextEditor. We further create a dispersion suppressor DSUP, which is just
an inverted half cell HCELL using the new quad and drift, and a half arc HARC, made from 1½
cells and DSUP, followed by a long straight D0, and with the optics marker OMID in front,
from where we want to start:
{----- Table of elements ---------------------------------------------}
D1 : Drift, L = 0.200000, Ax = 50.00, Ay = 50.00;
D1M : Drift, L = 0.200000, Ax = 50.00, Ay = 50.00;
D2 : Drift, L = 0.150000, Ax = 50.00, Ay = 50.00;
D0 : Drift, L = 3.000000, Ax = 50.00, Ay = 50.00;
QF : Quadrupole, L = 0.140000, K = 7.328467, Ax = 50.00, Ay = 50.00;
QFM : Quadrupole, L = 0.140000, K = 7.328467, Ax = 50.00, Ay = 50.00
B1 : Bending, L = 0.800000, T = 11.250000, K = -0.810401, T1 = 11.250000,
T2 = 0.000000, Ax = 50.00, Ay = 50.00;
OMID : OpticsMarker, BetaX = 0.312720, AlphaX = 0.000000, BetaY = 14.152986,
AlphaY = 0.000000, EtaX = 0.103319, EtaXP = 0.000000,
EtaY = 0.000000, EtaYP = 0.000000, Ax = 50.00, Ay = 50.00;
{----- Table of segments ---------------------------------------------}
HCELL : -B1, D1, QF, D2;
CELL : -HCELL, OMID, HCELL;
DSUP : D2, QFM, D1M, B1;
HARC : OMID, HCELL, CELL, DSUP, D0;

4. Again in Design Linear optics, we now select “Optics marker OMID” as start point to do a
forward calculation for segment HARC. Of course, dispersion will not be suppressed, see
Fig.12 left (by the way, double clicking into the figure copies it to the Clipboard). So we
either manually use QFM and D1M to get the dispersion to zero, or, more conveniently we
use the minimizer with starting point “initial” or “OMID” (because OMID is at the begin of
the segment in this case), matching point “final”, check “Dispersion” and “d/ds Disp.”, and
select QFM and D1M as knobs. We get an odd number, 0.89… m in this case, which we don’t
like, so set it to 0.80 m exactly and repeat the matching now selecting QF and QFM. Of
course, this perturbs a bit the periodicity of the unit cell, but only by a small amount. We
then get the plot of Fig.12 right:
 Fig. 12 dispersion suppression

5. Now dispersion is matched to zero, but the beam is not focused in the straight. We need two
more quadrupoles, Q1 and Q2 for matching the alpha-functions to zero at the end
(“Alpha X/Y” in minimizer). Further we adjust the lattice length to a nice number, in this case
a multiple of 60 cm considering use of a 500 MHz RF system ( = 60 cm). Matching may not
succeed immediately, it may help to manually set the quads to reasonable values. When
done, we can add another segment ARC for the complete 90 arc with dispersion free
straights of 22.97 m length at both ends. Here are the new elements/segments only:
“NPER=4” in segment ARC indicates that some quantities like length, energy loss etc. are
multiplied by 4 to get the values for the complete ring, see right column in Fig.13.
D0 : Drift, L = 2.940000, Ax = 50.00, Ay = 50.00;
D3 : Drift, L = 0.300000, Ax = 50.00, Ay = 50.00;
Q1 : Quadrupole, L = 0.150000, K = -3.770451, Ax = 50.00, Ay = 50.00;
Q2 : Quadrupole, L = 0.150000, K = 6.692579, Ax = 50.00, Ay = 50.00;
HARC : OMID, HCELL, CELL, DSUP, D3, Q1, D3, Q2, D0;
ARC : -HARC, HARC, NPER=4;

Fig.13: one arc (note that the buttons on top to zoom in or change scale.)

6. We now have a ring made from four arcs, providing a natural emittance of 9 nm at 1.5 GeV
in a circumference of 76.8 m. The working point (Qx, Qy) can be moved around in the tune
diagram without introducing dispersion in straights by slightly changing Q1 and Q2. Also the
QFM, QF quads in the arcs may be used if some leakage of dispersion is accepted. The
TuneMatrix button calculates a sensitivity matrix and allows the tunes to be set (within a
small range of, say ±0.1).

Nonlinear optimization
Now we need to insert sextupoles to correct the negative chromacities to zero or small positive
values, and, since sextupoles are non-linear elements, we have to take care to provide a sufficiently
large dynamic aperture, i.e. a sufficiently large amplitude where particle motion is still stable.
To get a feeling, let’s insert SF sextupoles for horizontal chromaticity correction at large beta-x and
large dispersion between the quadrupole pairs in the arc. For the vertical chromaticity, we need SD
sextupoles at large beta-y and large dispersion. There is a suitable place in the dispersion suppressor
D1M drift, so we split it to insert the SD. However depending where we insert the SD we either have
larger beta-y or larger dispersion. In order to find the best place we define a variable named DSD:
{----- Variables ---------------------------------------------------}
DSD = 0;
{----- Table of elements ---------------------------------------------}
D1MA : Drift, L = 0.36000+DSD, Ax = 50.00, Ay = 50.00;
D1MB : Drift, L = 0.36000-DSD, Ax = 50.00, Ay = 50.00;
SF : Sextupole, L = 0.080000, K = 0.000000, N = 3, Ax = 50.00, Ay = 50.00;
SD : Sextupole, L = 0.080000, K = -5.566250, N = 3, Ax = 50.00, Ay = 50.00;
{----- Table of segments ---------------------------------------------}
DSUP : D2, QFM, D1MA, SD, D1MB, B1;
HARC : OMID, HCELL, SF, CELL, SF, DSUP, D3, Q1, D3, Q2, D0;

Fig. 14: inserting sextupoles and optimize location

The variables appear as yellow boxes under the plot and can be dragged to a knob. If is is changed,
the SD slides back and forth. We also get knobs for SD and SF and switch optics mode to nonlinear :
now SD can be set to make vertical chromaticity (“ChromB”) zero. Then DSD is varied to get the
highest positive value. It turns out that DSD = -0.015 m is best (but dependence is weak). The
sextupoles are internally modeled as a number (N=3) of thin sextupole kicks.
Now close linear optics panels and go to Design  nonlinear dynamics , which opens a new panel
(Fig. 15): The left half shows 1st, 2nd and 3rd order chromaticities (“CrX/Y lin,sqr,cub”) with yellow
background. Checking the boxes left of SF, SD adjusts the chromaticities to the target value (not
exactly, since chromaticity is calculated by numeric differentiation). The tune diagram shows a
prediction of the tune footprint: pink/turquoise for ±p/p and in green for the amplitude dependent
tune shifts (“dQxx…”). For the range the values for betatron amplitudes “2Jx/y” and “dpp” at the
bottom of the panel are used.
As one can see, the result is not satisfactory: SD is rather strong, and in the tune diagram it is well
visible that major resonance lines are crossed in the amplitude and momentum range considered.
The reason is, that we have only a few, strong SD sextupoles, so we need more to distribute the
correction – but there is no space. We therefore introduce a small sextupole component in the
bending magnets. For that purpose, we turn them into another element type called “Combined”.
Virtually it is the same like a bending magnet, but it allows a sextupole component to be inserted
(actually the parallel existence of “Bending” and “Combined” makes no sense and has just historical
reasons.)
Repeating the nonlinear optimization, B1 becomes a free knob, while SF, SD are constrained by
chromaticity. Manually tuning B1 efficiently compresses the tune footprint as visible in Fig. 16.
Fig.15: the non-linear optimization panel showing a plain chromaticity correction with 2 sextupoles

Fig.16: improved tune footprint by introducing a third sextupole component

A large number of kicks was set, since B1 is rather long. M is the sextupole component:
B1 : Combined, L = 0.800000, T = 11.250000, K = -0.810401, T1 = 11.250000,
T2 = 0.000000, M = -4.5, N = 8, Ax = 50.00, Ay = 50.00;

Note that combined function magnets are only included if the “[Link].” box is checked in the
panel. Reduction of chromatic footprint is confirmed by Design  Off-momentum optics. Fig.17
shows the tune shifts of the periodic solutions for ±4% momentum and a magnified tune diagram
with more resonances:
Fig. 17: off momentum periodic solutions: fit to chromatic tune shifts

Tracking, part 1
Tracking proves the performance. There are three options under main menu button Tracking :

 Phase space : a particle can be started either by clicking in the phase spaces or by entering data
in the “Start” field in the middle of the panel, then press Run. The lower plots show the Fourier
spectra with guesses for the found peaks, and the tunes are added to the tune diagram (pink cross):

Fig 18: phase space tracking with FFTs

The sub-panel “ADTS” ramps up a virtual pinger, first x’ (y’=0), then x’ and y’ at a ratio corresponding
to the available acceptances, and finally y’ (x’=0). Afterwards the three data sets are plotted in blue,
purple and red in the tune diagram and in the two fields of the panel. Left field gives Qx and right
field Qy for the three cases. The button Amplitude allows to switch between betatron amplitude,
pinger kick and beam position as abscissa of the plots. -- This is the result for the little storage ring:

Fig. 19: amplitude dependent tune shifts from tracking. The dotted lines are the tune shifts as calculated
analytically in the non-linear optimizer panel.
As one can see, a rather large betatron amplitude of almost 40 [Link] is still stable, but around
20 [Link] the working point moves to the half integer at Qx = 8.5. This could be problematic at
injection, but can be cured by inserting an octupole or a harmonic sextupole or, most simply, by
shifting up the working point slightly detuning the arc. But before doing so, let’s see what we need.

 Dynamic Aperture : performs a grid probing in the {x, y}, {p/p, x} or {p/p, y} planes.

 Touschek Lifetime : this module is for calculation of local momentum acceptance to estimate the
beam lifetime. But before starting tracking, the linear model can be used already to get an estimate
how much momentum acceptance is needed. This has much impact on cost-sensitive parameters
like RF voltage and vacuum chamber aperture, we come back to that in a minute.

RF-system and apertures of beam pipe and magnets

These considerations are iterative. We anticipate the result, that we get 15 h of Tosuchek lifetime
with 2.5% of momentum acceptance (Of course, less lifetime could be acceptable assuming more
frequent top-up and would relax parameters and save costs). We start with the RF-system:

Running Design  off momentum optics again, we select the “Dpath” plot, which fits and saves the
coefficients for some orders of the momentum compaction factor.

Then open Design  RF bucket viewer : the column entitled “MCP” gives the polynomial fit for the
momentum compaction. The “Voltage” columns allows the fundamental and harmonic voltages to
be entered. The frequency is determined by the field “harmonic number”, which is 128 for 500 MHz
in our storage ring.

The momentum acceptance (green

line) is estimated from the
separatrix, also the bunch length is
derived from the equipotentials.

In this example, a voltage of

1.8 MV, which can be realized with
three 500 MHz cavities would
provide the ±2.5% momentum
acceptance. The bucket is
symmetric, because the higher
orders of momentum compaction Fig. 20: The RF bucket
are small.

Looking at Fig.13 or 14, we see the maximum dispersion is about Dmax = 0.3 m. A Touschek scattered
particle oscillates around the dispersive orbit, so it needs a free space of x = ± 2Dmaxp/p, which
is ±15 mm for ±2.5% momentum range. So this aperture is sufficient for the beam pipe aperture.

Going back to Edit  OPA Editor we set all apertures to ±15 mm by ±10 mm. In the vertical even
less is needed, since the small gaps of the undulators will limit the aperture anyway later. Smaller
height saves dipole gap and with it current (or permanent magnet load). For technical reasons the
beam pipe must not be too flat, so this 3:2 ratio ellipse is a good compromise (like SLS-booster…):
Fig. 21 setting apertures (black ellipse) and magnet pole radius (blue circle).

In the panel the apertures are entered at the bottom, then press “Set all apertures”. The magnet
pole radius can be set as well. It should be larger considering some thickness and some play of the
beam pipe in the magnet, see left figure for the QF quad.

It’s now time to check the magnet strength. In the Design  Linear optics panel is a knob
Plot Mode. It opens a panel to select and set parameters for beta function, envelope and magnetic
field plots: As one can see, the sextupoles are very weak.

Fig.22 Magnetic field plot. Dipole, Quadrupole B’R, Sextupole ½B”R2

Tracking, part 2
Now go back to main menu, select segment ARC again, perform the same steps for off-momentum
optics and RF-bucket in order to save momentum compaction and momentum acceptance data (by
the way, the status field on the left side of the main menu shows flags if data have been saved!)

Then do Tracking  Touschek Lifetime , see Fig. 23: Tracking determines the effective momentum
acceptance at each location in the lattice by binary search. The green line is the RF momentum
acceptance, brown is the linear acceptance as given in the linear model from the beam pipe width,
and red is the tracking result. The minimum of all three is used for the Touschek integral.

Lifetime results are given in the lowest three fields of the right column, and total lifetime for the
linear model and from tracking in large brown and red numbers at right.

Track starts the tracking. Note, that it is only 4D tracking at fixed pp.
Fig. 23: Touschek lifetime tracking.

The left panel are input values, the right panel is derived:

 “Coupling” distributes the natural emittance to horizontal and vertical.

 “Beam current” is distributed on “number of bunches”, which should be smaller than
“harmonic number” considering a gap for ion clearing.
 “Cavity voltage” and “harmonic number” were set by the RF bucket panel and cannot be
modified here, they determine bunch length and momentum acceptance.
 “Longitudinal resolution” is the minimum distance to do another tracking in order to get a
good sampling of the Touschek integral.
 “Momentum resolution” is precision of binary search.
 “Number of turns to track” should be at least one synchrotron period (= 1/”[Link]”)
 The last three fields define species and partical pressure of residual gas.

Coupling
Up to now emittance coupling was just given as a number for Touschek tracking. Now we introduce
coupling with skew quadrupoles. As we have seen, the sextupoles are rather weak, so we may
assume that skew quadrupoles (of moderate field quality) are realized by additional coils in the
sextupoles (as it has been done in SLS). In order to not affect the straight sections, we will generate
vertical emittance by a closed bump of vertical dispersion in the arc, while suppressing any coupling
in the straights. Therefore we need two dispersive skew quad families, named QSF1, QSF2 to create
and terminate the bump, and a third non-dispersive skew quad family QS0 to avoid a tilted (in x-y
space) beam in the straights. OPA does not allow two thick multipoles at the same location, so we
split the sextupole and insert the skew quad between and remember that the real strength will be
only half of the set strength, because the real magnet, where the two fields are superimposed, has
the full length. Rot = 45 identifies a skew quad, i.e. a quad rotated by 45:
QSF1 : Quadrupole, L = 0.0400, K = 0.64974, Rot = 45.00, Ax = 15.00, Ay = 10.00;
QSF2 : Quadrupole, L = 0.0400, K = -0.74035, Rot = 45.00, Ax = 15.00, Ay = 10.00;
QS0 : Quadrupole, L = 0.0400, K = -0.56808, Rot = 45.00, Ax = 15.00, Ay = 10.00;
SFQ : Sextupole, L = 0.0200, K = 134.1361, N = 2, Ax = 15.00, Ay = 10.00;
NOS : Drift, L = 0.0200, Ax = 15.00, Ay = 10.00;
SFC1 : SFQ, QSF1, SFQ;
SFC2 : SFQ, QSF2, SFQ;
QS0C : NOS, QS0, NOS;

An additional [sextupole & skew quad] of same type named QS0C is installed in the straight, but not
using the sextupole coils is indicated by inserting a drift space NOS.
If Linear optics design is started again, the startmenu will show a checked field “coupling”, and the
beta functions displayed are the normal-modes. Here a manual set-up was done, dragging the three
skew quads to knobs (zoom in to grab small elements!) and adjusting them such, that the “vertical”
emittance “EmitB” (which actually is the b-mode emittance) is about 5% of “Emit A”, and that the
coupling is suppressed in the straights, i.e. det C  0, to avoid beam tilt (“Tilt XY”) in the straights.
The various plot options are available from the Plot Mode button:

Fig. 24: setting 5% emittance coupling with 3 skew quad families. Upper left: horizontal and vertical dispersion
and normal-mode betas. Upper right: determinant of the coupling matrix and projected betas.
Lower plot: envelope with equilibrium beam parameters. Green and pink lines are contributions from
dispersion to beam size, and dotted lines are contributions from coupling of the other mode.

Another Touschek lifetime calculation (not shown) gave slightly less total lifetime of 8.6 h
(cf. Fig. 23), since coupling of course, excites more resonances.

Note that the OPA modules are not yet fully consistent with regard to coupling, for example the non-
linear optimization is not aware of coupling, so results may not be valid for strongly coupled lattices.
Furthermore, the effect known as “mode-flip” in strongly coupled lattices is not yet handled
correctly (wrong phase advances).
Real lattice: coils, BPMs and correctors
A lattice needs beam position monitors and correctors to correct for misalignments of magnets.
Phase advance between corrector/BPM stations has to be less than 180, ideally 90. With a
horizontal cell tune of 0.4, corresponding to 144, one station per unit cell is sufficient. Since the
sextupoles turned out to be weak, we also add corrector coils, i.e. insert [thin] correctors, in order to
save space (like it was done at SLS). Moving towards a realistic lattice, we also reserve space for coils
at the electromagnets. The bending magnets are assumed to be permanent, so they have no coils. -
Several changes are made to the lattice file (only showing relevant lines):
{----- Variables ---------------------------------------------------}
QSFAC = 2;
{----- Table of elements ---------------------------------------------}
DQUA : Drift, L = 0.040000, BLOCK, Ax = 15.00, Ay = 10.00;
DQSX : Drift, L = 0.020000, BLOCK, Ax = 15.00, Ay = 10.00;
DBPM : Drift, L = 0.015000, BLOCK, Ax = 15.00, Ay = 10.00;
QSF1 : Quadrupole, L = 0.0200, K = 0.645*QSFAC, Rot = 45.0, Ax = 15.00, Ay = 10.00;
SFQ : Sextupole, L = 0.010, K = 268.272316, N = 2, Ax = 15.00, Ay = 10.00;
MON : Monitor, Ax = 15.00, Ay = 10.00;
CH : H-Corrector, Ax = 15.00, Ay = 10.00;
CV : V-Corrector, Ax = 15.00, Ay = 10.00;
{----- Table of segments ---------------------------------------------}
BPM : DBPM, MON, DBPM;
QFC : DQUA, QF, DQUA;
SFC1 : DQSX, SFQ, CV, QSF1, CH, SFQ, DQSX;
QS0C : DQSX, NOQS, CV, QS0, CH, NOQS, DQSX;
HCELLX : -B1, D1, QFC, D2X, BPM, D2X;
HCELL : -B1, D1, QFC, D2;
CELL : -HCELLX, HCELL;
DSUP : D2X, BPM, D2X, QFMC, D1MA, SDC, D1MB, B1;
STR : D3, Q1C, D3X, BPM, D3X, QS0C, D3H, Q2C, D0;
HARC : omid, HCELL, SFC1, CELL, SFC2, DSUP, STR;
ARC : -HARC, OMID, HARC, NPER=4;
RING: 4*ARC;

Drift spaces with the flag BLOCK are protected; presently the only difference to normal drifts is, that
they are shown as grey boxes grey in the plots. Now short segments with suffix C are compound
elements containing a magnet with coils and additional functions, for example SFC is a split SF
sextupole with horizontal and vertical correctors and space for coils. Other drifts (not shown) have
been adjusted to maintain the positions and lattice length. Since sextupole and skew quad lengths
have been halved to gain space for coils, the strength had to be double. For the skew quads, a
variable QSFAC hase been introduced which allows to control the vertical emittance. Finally, a
segment RING for the whole ring has been added.

We select segment RING and proceed to Design  Orbit Correction . The known start panel and a
new panel will open, see Fig.25.

Select “periodic” and Apply: two plots show horizontal and vertical orbit, which is still at zero,
because no misalignment was set. In the “misalign+correct” panel set rms misalignments for
elements, i.e. in the “Elem.” Column, and press Set! The orbit gets distorted. The box “include
nonlinear” should be checked to include non-linear orbit distortions too. Pressing correct performs
the orbit correction. A plot at the bottom shows the weight factors of the singular value
decomposition (SVD), they may be filtered using the slider if the correction was too hard.

The button in the “show” panels allows the plot to change between orbit, corrector values and
misalignments. If girders are used, correlated misalignments will be set, i.e. element errors on top of
girder errors. Series of magnets with no space between, e.g. SFQ,CV,QSF1,CH,SFQ are treated as a
rigid entity like a mini-girder, i.e. the single element misalignments are on a straight line.
Note that the names MON for BPMs and CH, CV for correctors are protected names recognized by
the orbit procedure. A series of elements CH001… etc. is created internally to address them
individually. BPMs and correctors with other names may be used manually, but they will be ignored
by the orbit correction. Correctors and BPMs are shown as colored symbols under the plot window
and may be dragged to one of the knobs to set correctors manually, or to read out a BPM. It is also
possible to set a reference to a BPM (actual / set buttons).

Fig. 25: Orbit correction

Returning from the orbit panel, the corrector values are remembered and affect the optics as visible
in the Linar Optics windows. Switching the PlotMode to “Envelope” the distorted and corrected
beam can be seen, with orbit offsets now added to the contributions from Fig.24/bottom:

Fig.26 Envelope after orbit correction in a ring with misalignments.

Undulators
The little test storage ring should work as a VUV source, so undulators need to be installed in the
straights. Following steps are performed:
  In OPAEditor a new element of type “undulator” name UND is created. The parameters
include length, period, gap and peak field. An undulator is terminated with end poles of ¼
and -¾ field strength to center the trajectory. However, if the flag HALF is set, the rear end is
open in order to insert it as two halves, like UND, -UND, which is often convenient. F1,2,3
are factors for the radiation integrals, default values are for a sine-shaped field.
UND : Undulator, L = 1.500000, Lamb = 0.020, Bmax = 1.00, F1 = 0.636620,
F2 = 0.500, F3 = 0.424410, GAP = 4.000, HALF, Ax = 20.00, Ay = 2.00;
 We will install undulators in two straights, the other will be used for injection and RF. Since
the undulator has some focusing, we need to copy the quad families Q1, Q2 to Q1U and Q2U
and reorganize the lattice file to have two different types of straights and arcs:
Q1U : Quadrupole, L = 0.150000, K = -3.807939, Ax = 15.00, Ay = 10.00;
Q2U : Quadrupole, L = 0.150000, K = 6.704586, Ax = 15.00, Ay = 10.00;
STRI : D3, Q1C, D3X, BPM, D3X, QS0C, D3H, Q2C, D0;
STRU : D3, Q1UC, D3X, BPM, D3X, QS0C, D3H, Q2UC, DUND, UND;
HARC0 : OMID, HCELL, SFC, CELL, SFC, DSUP;
HARCI : HARC0, STRI;
HARCU : HARC0, STRU;
ARCI : HARCI, -HARCI, NPER=4;
ARCU : HARCU, -HARCU, NPER=4;
RING : -HARCI, ARCU, ARCI, ARCU, HARCI;
 The easiest way to adjust the optics to the undulator is to first select ARCI and get the
periodic solution in Linear Optics. It will be saved as initial values too. Then select HARCU
and start from initial values. Perform a matching using Q1U, Q2U to set the alphas at the end
(= mid of undulator) to zero.
 Finally select RING to see the optics with two undulators. Zooming into the undulator shows
its inner dispersion. Note the overshoot at the entry due to the special end poles which is
missing at the center (dotted line), where the two halves connect:

Fig.27: ring optics with two VUV undulators (skew quads off), and magnification of undulator dispersion.

Injection
Injection will be done horizontally because vertical aperture is too restricted due to the small
undulator gaps. Before starting, we realize that the tune footprint is affected by a 4 th order skew
resonance (Qx + 3Qy = 15), which causes strong coupling and with it risk to lose the injected beam at
the undulator gaps, see Fig.28, left: coloured
points are inside the physical acceptance, grey
points are outside. The most simple cure is to
tune all available quads by a small amount to move the working point away (to 8.60/2.155) using the
TuneMatrix button in Linear Optics. The impact on the optics is too small to be seen. Fig. 28 shows
the ADTS in the tune diagram before and after. The same would be done empirically in the control
room to improve injection efficiency.

There are many ways to inject: using a closed kicker bump or a single multipole kicker, injection can
be done in single or multi-turn, from the inside or the outside etc. We demonstrate here as an
example aperture sharing using a single dipole kicker. OPAEditor shows the parameters for the
kicker:

 multipole order n, where n=1 for a dipole kicker.

 If “Xpeak” = 0 it is a multipole kicker and the next
field “BnL” gives its integrated multipole strength.
 If “Xpeak”  0 it is a nonlinear kicker with
B(x)  sinn-1(x/2Xpeak), i.e. it has the 2n-pole
dependence for small x. Then the next field “kick”
is just the kick at x=Xpeak in mrad (for n>1).
 Half sine is the time for the pulse.
 Delay is time of flight from start of lattice Fig. 29, the kicker panel
A dipole kicker works best, if the phase advance between
the point of injection, where the injected beam leaves the septum with an offset, and the kicker is an
odd multiple of 90. The test ring has a tune Qx near to 8.5, so half the ring fulfills this condition.
Therefore we install the kicker opposite to the injection point. Again, this requires a minor
modification of the lattice file (excerpt):
KIN : Kicker, L = 0.500000, N = 1, K = 0.700, X = 0.000, T = 500.000,
DELAY = 119.416 NK = 1, Ax = 20.00, Ay = 10.00;
STRI0 : D3, Q1C, D3X, BPM, D3X, QS0C, D3H, Q2C;
STRY : STRI0, DY2, KIN, DY1;
HARCY : HARC0, STRY;
RING : -HARCI, ARCU, HARCY, -HARCI, ARCU, HARCI;

Now use Design  Injection Bumps . It opens a very similar panel to orbit correction, but with
kickers as orange boxes, and the start panel. In Fig. 30 below some manual optimization has been
done already:

Fig. 30: two turns of the injected beam

The kicker (orange) is in the straight opposite to injection (which is begin of lattice). The “include
nonlinear” flag was set, because it significantly affects the orbit at large amplitudes. The injected
beam was set to x = 16 mm, i.e. coming from the outside of the ring.

From the Touschek lifetime estimates we know the maximum of the dispersion’s betatron
amplitude H (“H-invariant” in Fig.23). In order to not affect Touschek lifetime, the septum
edge has to be at x > (betaseptum Hmax)½p/pmax, which gives about 14.5 mm in our case. (There
is no dispersion at septum, but Touschek particles pick up a betatron oscillation).

The injection angle was set to a small nonzero value in order to cross the axis at the kicker location,
because the phase advance is not an exact odd multiple of 90. Then the kicker was switched on and
synchronized using the ON and Sync buttons. Synchronization sets the delay such that the kick is
maximum when the injected beam arrives. The kicker was dragged to a knob and increased until the
injected beam is put on axis, then half of this value was set to do aperture sharing. Fig.30 shows first
(blue) and second turn for the injected beam.

Then the panel is closed, go back to Design  Linear Optics to refresh the periodic solution and then
to Tracking  Phase space. Fig. 31 shows the injection process:

Fig.31 aperture sharing injection showing turns 0…4 (greenyellowblue) and 128 (pink) for stored (small
circles) and injected (larger ellipses) beams. Septum (grey bar) added by hand.

The stored beam starts at zero position and angle (green circle) and is kicked out, see the smaller
circles for the first four turns. The injected beam start right of the septum and is kicked in, these are
the larger, oblong objects. Both beams filament due to nonlinearities and give the pink structures.
The beam centroid is set in the middle panel. After pressing Beam, the lower panel opens and
parameters can be set. A 5-sigma emittance of 212 nm was set for the stored beam, and a 3-sigma
emittance of 450 nm for an injected beam with assumed 50 nm. With beta = 5 m of the injected
beam, it needs ±1.5 mm space around the centroid, i.e. the septum outer edge could be at 14.5 mm.
With a thickness of 1.5 mm, inner edge would be 13 mm.

Checking lifetime again (not shown), reduced apertures at septum and undulators lead to a mild
decrease of Touschek lifetime from former 14.9 h to 13.4 h linear, resp. from 13.7 h to 12.3 h in
tracking, and to a strong decrease of elastic scattering gas lifetime from former 27 h to 8.8 h, which
results in a total lifetime of 4.8 h.
Finalization
The last step is cosmetics. In order to get the nice plot of Fig. 32 from Design  Geometry, we
introduce a few more elements: there are no RF cavities in OPA, therefore we use solenoids of zero
strength (cyan) as placeholders. Further we insert a “PhotonBeam” marker in the undulator center
to plot the photon beam, and a marker with the reserved name CENTER to enable centering of the
lattice. The septum is entered as a dummy kicker on the left side (the septum element is not yet
implemented completely):

Fig. 32: Layout of the final lattice.

In Linear Optics Design is a button --> txt to write several data to files for documentation, one of
them is *_dat.txt (note, emittance was reduced further due to the radiation from the undulators):
Lattice Parameters

C:\as\opa\test\[Link]:RING

Circumference [m] 76.800000

Horizontal Tune 8.579979
Vertical Tune 2.155121
Nat. hor. Chromaticity -16.669362
Nat. [Link] -15.703606
Momentum compaction 8.7037595E-03
a-mode damping Ja 1.663843
b-mode damping Jb 1.004294

Energy [GeV] 1.500000

Radiated energy/turn [MeV] 0.118377
a-mode Emittance [nm] 8.555525
b-mode Emittance [nm] 0.415807
Natural energy spread 7.7135098E-04
a-mode damping time [ms] 3.901954
b-mode damping time [ms] 6.464482
Long. damping time [ms] 4.874554

Radiation Integrals (for one period):

I1 [m] 6.6844873E-01
I2 [1/m] 1.6608612E+00
I3 [1/m2] 3.9861225E-01
I4a/b [1/m] -1.1025514E+00 -7.1312386E-03
I5a/b [1/m] 7.1605444E-03 2.1005794E-04

The final lattice file is given in the appendix. In the process it acquired some complexity and could be
cleaned up or reorganized in a final step (not done).
So, we have reached the point, where the draft design of our VUV ring has to be handed over to
other, more powerful codes like MAD, ELEGANT or TRACY for detailed analysis of misalignments,
multipole errors and 6-D tracking. – OPA was made to start a design from scratch but cannot do the
complete design.
File  Export allows lattice files for other codes to be exported, however, not all OPA features are
included, but the basic elements are converted correctly. Some codes cannot do inversion of
bending magnets properly (a bend with different edges has to be inverted several times when
expanding nested segments), therefore, mirrored copies of all asymmetric elements and segments
are generated if needed. Of course, some manual work is required to finalize the exported files.

Conclusion
This tutorial demonstrated how to design a lattice from scratch using OPA. However, to be honest,
the process may be less straightforward than it seems and involve some iterations of trial & error.

There are some issues with OPA, which are subject to ongoing debugging and completion:

 The effect known as “mode flip” in strongly coupled lattices is not yet implemented
completely, in particular tunes will be wrong.
 Not all modules (e.g. nonlinear optimization) work with coupling.
 Tracking including misalignments and corrections does not yet work properly.
 There are still some bugs in the code which can cause program crashes or strange results.

Work is in progress.
Appendix
The final lattice file
{C:\as\opa\test\[Link]}

Energy = 1.500000;
( the initial values from the last run: )
BetaX = 10.3264633; AlphaX = -0.0000004;
EtaX = 0.0023545; EtaXP = 0.0000000;
BetaY = 1.7003305; AlphaY = 0.0000009;
EtaY = 0.0001077; EtaYP = 0.0000000;

{----- Variables ---------------------------------------------------}

QSFAC = 2; (useful to switch on/ off the skew quads for coupling)

{----- Table of elements ---------------------------------------------}

D1 : Drift, L = 0.160000, Ax = 15.00, Ay = 10.00;
D1MA : Drift, L = 0.305000, Ax = 15.00, Ay = 10.00;
D1MB : Drift, L = 0.375000, Ax = 15.00, Ay = 10.00;
D2 : Drift, L = 0.070000, Ax = 15.00, Ay = 10.00;
D2X : Drift, L = 0.020000, Ax = 15.00, Ay = 10.00;
D0 : Drift, L = 2.900000, Ax = 15.00, Ay = 10.00;
D3 : Drift, L = 0.260000, Ax = 15.00, Ay = 10.00;
D3H : Drift, L = 0.080000, Ax = 15.00, Ay = 10.00;
D3X : Drift, L = 0.015000, Ax = 15.00, Ay = 10.00;
DQUA : Drift, L = 0.040000, BLOCK, Ax = 15.00, Ay = 10.00;
DQSX : Drift, L = 0.020000, BLOCK, Ax = 15.00, Ay = 10.00;
DBPM : Drift, L = 0.015000, BLOCK, Ax = 15.00, Ay = 10.00;
DUND : Drift, L = 1.400000, Ax = 15.00, Ay = 10.00;
DY2 : Drift, L = 0.300000, Ax = 15.00, Ay = 10.00;
DY1 : Drift, L = 2.100000, Ax = 15.00, Ay = 10.00;
NOQS : Drift, L = 0.010000, BLOCK, Ax = 15.00, Ay = 10.00;
DS1 : Drift, L = 0.700000, Ax = 15.00, Ay = 10.00;
DRF : Drift, L = 0.200000, BLOCK, Ax = 15.00, Ay = 10.00;
D0R : Drift, L = 0.250000, Ax = 15.00, Ay = 10.00;

CENTER : Marker, Ax = 15.00, Ay = 10.00;

QSF1 : Quadrupole, L = 0.020000, K = 0.645000*QSFAC, Rot = 45.0, Ax = 15.00, Ay =

10.00;
QSF2 : Quadrupole, L = 0.020000, K = -0.740000*QSFAC, Rot = 45.0000,
Ax = 15.00, Ay = 10.00;
QS0 : Quadrupole, L = 0.020000, K = -0.570000*QSFAC, Rot = 45.0000,
Ax = 15.00, Ay = 10.00;
QF : Quadrupole, L = 0.140000, K = 7.407734, Ax = 15.00, Ay = 10.00;
QFM : Quadrupole, L = 0.140000, K = 5.897098, Ax = 15.00, Ay = 10.00;
Q1 : Quadrupole, L = 0.150000, K = -3.758661, Ax = 15.00, Ay = 10.00;
Q2 : Quadrupole, L = 0.150000, K = 6.693474, Ax = 15.00, Ay = 10.00;
Q1U : Quadrupole, L = 0.150000, K = -3.783635, Ax = 15.00, Ay = 10.00;
Q2U : Quadrupole, L = 0.150000, K = 6.701448, Ax = 15.00, Ay = 10.00;

SFQ : Sextupole, L = 0.010000, K = 268.272316, N = 2, Ax = 15.00, Ay = 10.00;

SDQ : Sextupole, L = 0.010000, K = -172.613692, N = 2, Ax = 15.00,Ay = 10.00;

RFC : Solenoid, L = 0.400000, K = 0.000000, Ax = 15.00, Ay = 10.00; (dummy)

UND : Undulator, L = 1.50, Lamb = 0.020, Bmax = 1.00, F1 = 0.636620,

F2 = 0.500000, F3 = 0.424410, GAP = 4.000, HALF, Ax = 15.00, Ay = 2.00;

KIN : Kicker, L = 0.500000, N = 1, K = 0.700, X = 0.000, T = 500.000,

DELAY = 119.416 NK = 1, Ax = 15.00, Ay = 10.00;
SEPT : Kicker, L = 1.500000, N = 1, K = 0.000, X = 0.000, T = 0.000,
DELAY = 0.000 NK = 1, Ax = 12.00, Ay = 10.00;
OMID : OpticsMarker, BetaX = 0.307958, AlphaX = 0.000000, BetaY = 17.270700,
AlphaY = 0.000000, EtaX = 0.103330, EtaXP = 0.000000, EtaY = 0.020711,
EtaYP = 0.000000, C11 = -0.0294571, C12 = 0.0000000, C21 = 0.0000000,
C22 = -0.2284860, Ax = 15.00, Ay = 10.00;

B1 : Combined, L = 0.800000, T = 11.250000, K = -0.810401, T1 = 11.250000,

T2 = 0.000000, M = -4.5, N = 8, Ax = 15.00, Ay = 10.00;

XUND : PhotonBeam, XL = 20.00, Style = 0, Snap = 1, Ax = 15.00, Ay = 10.00;

MON : Monitor, Ax = 15.00, Ay = 10.00;

CH : H-Corrector, Ax = 15.00, Ay = 10.00;

CV : V-Corrector, Ax = 15.00, Ay = 10.00;

{----- Table of segments ---------------------------------------------}

BPM : DBPM, MON, DBPM;
QFC : DQUA, QF, DQUA;
QFMC : DQUA, QFM, DQUA;
Q1C : DQUA, Q1, DQUA;
Q2C : DQUA, Q2, DQUA;
Q1UC : DQUA, Q1U, DQUA;
Q2UC : DQUA, Q2U, DQUA;
SFC1 : DQSX, SFQ, CV, QSF1, CH, SFQ, DQSX;
SFC2 : DQSX, SFQ, CV, QSF2, CH, SFQ, DQSX;
SDC : DQSX, SDQ, NOQS, NOQS, SDQ, DQSX;
QS0C : DQSX, NOQS, CV, QS0, CH, NOQS, DQSX;

HCELLX : -B1, D1, QFC, D2X, BPM, D2X;

HCELL : -B1, D1, QFC, D2;
CELL : -HCELLX, HCELL;
DSUP : D2X, BPM, D2X, QFMC, D1MA, SDC, D1MB, B1;
STRI0 : D3, Q1C, D3X, BPM, D3X, QS0C, D3H, Q2C;
STRI : STRI0, D0;
STRY : STRI0, DY2, KIN, DY1;
STRU : D3, Q1UC, D3X, BPM, D3X, QS0C, D3H, Q2UC, DUND, UND;
HARC0 : OMID, HCELL, SFC1, CELL, SFC2, DSUP;
HARCI : HARC0, STRI;
HARCU : HARC0, STRU;
HARCY : HARC0, STRY;
STRRF : STRI0, D0R, DRF, RFC, DRF, DRF, RFC, DRF, DRF, RFC, DRF, D0R;
STRSP : STRI0, DS1, SEPT, DS1;
HARCSP : HARC0, STRSP;
HARCRF : HARC0, STRRF;

ARC : -HARCI, OMID, HARCI;

ARCI : HARCI, -HARCI, NPER=4;
ARCU : HARCU, XUND, CENTER, -HARCU, NPER=4;
RING0 : 4*ARC;
RING : -HARCSP, ARCU, HARCY, -HARCRF, ARCU, HARCI;

{C:\as\opa\test\[Link]}{C:\as\opa\test\[Link]}