PBO Lab 2 - GHGA Homepage · ii. PBO Lab 2.0 User ... PBO Lab 2.0 User Manual Supplement: TRACE 3-D Module ... the Final Beam parameters are not contained in a PBO The Particle Distribution

PBO Lab 2.0 User Manual Supplement: TRACE 3-D Module

PBO Lab™ 2.0(Particle Beam Optics Laboratory)

User Manual Supplement:TRACE 3-D Application Module

Distributed by

AccelSoft, Inc.P. O. Box 2813

Del Mar, CA 92014 USA

(858) [email protected]

www.ghga.com/accelsoft

i


PBO Lab 2.0 User Manual Supplement: TRACE 3-D Application Module 1999, 2001 by G. H. Gillespie Associates, Inc.All Rights Reserved.

ISBN 1-892267-06-3

All rights reserved. No part of this book may bereproduced, in any form or by any means, withoutpermission from the publisher.

Printed in the United States of America.

Published by AccelSoft Inc., San Diego, California.

ii


Included with this supplement is the following document, reproduced and distributed as part of a licenseagreement between G. H. Gillespie Associates, Inc. and the Regents of the University of California,operator of the Los Alamos National Laboratory (“LANL”):

Appendix: “TRACE 3-D Documentation”

TRACE 3-D Documentation, by K. R. Crandall and D. P. Rusthoi, Third Edition, May 1997.Los Alamos National Laboratory Report Number LA-UR-97-886copyright 1987, 1990, 1997 by The Regents of the University of California.All Rights Reserved.

TRACE 3-D is a FORTRAN program maintained and distributed by the Los Alamos Accelerator CodeGroup at LANL. The program is included with PBO Lab TRACE 3-D Application Module under alicense agreement.

Running TRACE 3-D is accomplished directly from the PBO Lab interface - the TRACE 3-D programis fully integrated with the PBO Lab environment. This supplement discusses the PBO Lab Commandsand the output options for the TRACE 3-D Application Module. The TRACE 3-D program is describedin the TRACE 3-D Documentation, which is included as Appendix A to this supplement.

iii


This page is intentionally blank.

iv


Table of Contents

Chapter and Subject Page

1. Getting Started 1Running TRACE 3-D 3TRACE 3-D Elements 5

Initial Beam Parameters 6Final Beam Parameters 7Plot Control Parameters 8

2. TRACE 3-D Output 11Text Output Window 13Graphic Output Window 13

3. TRACE 3-D File Menu 15Import 17Export 17

4. TRACE 3-D View Menu 19View Input File 21View Output File 22View Profile Data 22View Aperture Data 22View PARMILA Units 23View Match File 23

5. TRACE 3-D Commands Menu 25Beam Dynamics Commands 28

Graph Beam Line 28Trace on Background 30Plot Projection 31Calculate Phase Advance 32Calculate Phase & Energy 32

v


Chapter and Subject Page

5. TRACE 3-D Commands Menu (continued)Matching Commands 33

Match Specification 33Perform Matching 33Calculate Mismatch 34Match and Couple Variables 34

Display Commands 34Show Beam Vectors 35Show R Matrix 35Show Modified Sigma 35Calculate PARMILA Units 36

Options 36

6. TRACE 3-D Matching 37Beam Matching 42Parameter Fitting 43TRACE 3-D Matching Types 46Find Matched Twiss Parameters 46Find Variables For Match 46Match and Couple Variables 47Match and Couple List Windows 49Matching the R and s Matrices 50Matching for Round Beam 50Matching for X,Y,Z Planes 50Matching for Phase Advance 51

7. TRACE 3-D Options 53Graphic Scaling Parameters 55Element Options 56Profile and Aperture Options 57Generate Aperture File 57Generate Profile Data 57

Appendix: “TRACE 3-D Documentation” 59

vi


User ManualSupplement:TRACE 3-DApplicationModule

PB

O L

abT

M

2.0

PB

O L

abT

M

2.0


Getting Started

1


2



3

1. Getting StartedThis Getting Started Section is intended as a quick startintroduction for running the TRACE 3-D ApplicationModule. The remainder of this Supplement describes thePBO Lab user interface features that are specific to theTRACE 3-D Application Module. The TRACE 3-D Documentation describes the TRACE 3-D program.

When the TRACE 3-D Application Module is installedin PBO Lab, a TRACE 3-D option will be added to theApplication Context pop-up in Document windows. TheApplication Context is used to indicate native inputs andin some cases access application-specific user interfacewindows. TRACE 3-D sub-menus will also be placed inthe View and Commands menus.

Running TRACE 3-DA Variety of TRACE 3-D commands can be executed fromthe pull-down Commands menu, shown in Figure 1.

Figure 1 TRACE 3-D Commands Menu.

The Graph Beam Line command generates the TRACE3-D beam envelopes and phase-space ellipses in the GraphEllipses & Profile Window. Figure 2 shows the result ofexecuting the Graph Beam Line command using theExample B model distributed with the application anddescribed in the TRACE 3-D Documentation.

TRACE 3-D Commands include avariety of beam dynamics, matchingand display commands for the TRACE3-D Application Module.



Figure 2 TRACE 3-D Graph Ellipses & ProfileWindow.

The TRACE on Background and Projections commandsalso use the Graph Ellipses & Profile Window. OtherTRACE 3-D Commands use the History Window shownin Figure 3. The History Window is cleared automaticallywhen the Window is closed. Leave the Window open fora continuous history or use the Save As command in theWindow’s File menu to save the data prior to closing theWindow.

Figure 3 TRACE 3-D History Window.

Figure 2 is an example of the TRACE3-D Graphic Output Window afterthe execution of the Graphcommand.

Figure 3 is an example of the TRACE3-D History Window after a series ofoutput commands were executed.

The History Window is editable andits content can be saved to a diskfile.

4


TRACE 3-D ElementsThere are several elements supported by PBO Lab whichare not supported by TRACE 3-D. These are treated aszero length drift elements in the execution of a TRACE3-D command and will have no effect on dynamicscalculations. Figure 4 lists all of the beamline piecessupported by TRACE 3-D.

TRACE 3-D native inputs areindicated in each Piece Window withgreen dots which appear to the rightof a parameter.

Figure 4 PBO Lab Pieces supported by TRACE 3-D.

Quadrupole

Type Piece PieceCode Icon Type

- Initial Beam

1 Drift

2 Thin Lens

3 Quadrupole

4 Permanent Magnet

5 Solenoid

6 Doublet

7 Triplet

- Marker

Type Piece PieceCode Icon Type

8 Bend

9 Edge

10 Radio Frequency Gap

11 RFQ

12 Radio Frequency

13 Tank

14 Wiggler

15 Rotate

- Final

Cavity

5

Initial Beam ParametersThe Initial Beam Piece is not a beamline element inTRACE 3-D, it is a specialized PBO Lab piece. However,the Initial Beam Piece parameters are used define theinitial emittances (EMITI) and the initial Twiss parameters(BEAMI) inputs for TRACE 3-D. As with other PieceWindows this window is opened by double clicking onthe Initial Beam Piece icon in the Model Space or WorkSpace. This is illustrated in Figure 5. The Initial BeamPiece also provides a tab panel for initial centroid offsetparameters (BEAMCI) which are used by TRACE 3-D.

The PBO Lab Beam Piece provides a variety of featuresincluding scalable ellipse plots of the beam parameters,calculation of equivalent Semi-Axis and Twiss parametersand initial centroid offset parameters, and access to theCorrelation Matrix Window.

In addition to Courant-Snyder (Twiss) parameters theBeam Parameters selection includes Semi-Axisparameters for defining the Initial Beam.

Figure 5 PBO Lab Initial Beam Piece Window.

6

The Semi-Axis parameters are not supported directly byTRACE 3-D, however they can be used to specify aninitial Sigma matrix input for TRACE 3-D using theCorrelation Matrix Window. The Correlations button inthe Initial Beam Window opens the Correlation MatrixWindow. This window is used to specify an Initial SigmaMatrix for TRACE 3-D. The Correlations button is onlyactive with the Semi-Axis Beam Parameters Selection.The Initial Sigma Matrix (SIGI) and the TRACE 3-D flag(IBS) are assigned when the Semi-Axis Beam Parametersare selected.

The Comp From Axis Button in the Beam Piece Windowcomputes the Twiss Parameters from the Semi-AxisParameters and the Correlations Matrix. If the BeamParameters selection is Semi-Axis then the Comp FromTwiss button will calculate Semi-Axis and Correlationvalues from the current Twiss Parameters.

Final Beam ParametersThe Copy From Output button copies the TRACE 3-DOutput Beam Twiss parameters (BEAMO) into the Twissparameters of the Initial Beam Piece (BEAMI). The CopyFrom Final button copies the Twiss parameters specifiedin the Final Beam Window (BEAMF used for matching)into the Twiss parameters of the Initial Beam Piece(BEAMI). These buttons provide the TRACE 3-D Exchange Beams functionality described in Section10.24 of the TRACE 3-D Documentation. An unlimitednumber of Beam Pieces may be stored on the Work Spaceand can be used to save copies of the TRACE 3-D BEAMI,BEAMF and BEAMO beam vectors.

The Final Beam Twiss parameters (BEAMF, used formatching) are set via a similar window which can beopened in the Matching Specification Window. The FinalBeam Window can also be opened by double clicking ona “Final” Piece icon and pressing the New Constraintsbutton. The Final Beam Window also provides buttonsto copy the Initial Beam Twiss parameters and the TRACE3-D output beam vector. Unlike the Initial Beam Piece,the Final Beam parameters are not contained in a PBO

The Particle Distribution Typespecified in the Beam Piece Windowis not used for TRACE 3-D.

Refer to Sections 9.2 and 10.24 ofthe TRACE 3-D Documentation.

7

Lab beamline Piece. There is only one set of Final Beamparameters for each PBO Lab Document, although theseparameters may be accessed through the Final Piece.Multiple Final Pieces do not create multiple Final beamparameter sets. The Final Piece in PBO Lab is used as aspecial type of Marker Piece for TRACE 3-D. Thelocation of the Final Piece in the beamline model is usedto define the the point that beam propagation stops in theprofile plot of the Graph Ellipses and Profile Window.The Initial Beam Piece defines the starting location forbeam propagation. These TRACE 3-D parameters andthe remaining plot control parameters are described next.

Plot Control ParametersThe TRACE 3-D control parameters: N1 and N2 specifythe start and stop locations for beam propagation throughthe beamline model. The NP1 and NP2 parameters specifythe start and stop locations for the beamline model in theprofile plot. The NEL1 and NEL2 parameters specifythe locations for the initial and final phase space ellipseplots. These are illustrated in Figure 6.

Plot Beamline Model Startingat NP1 and ending at NP2

TransversePhase-SpaceEllipses at

NEL1

TransversePhase-SpaceEllipses at

NEL2

LongitudinalPhase-Space

Ellipse at NEL1

LongitudinalPhase-Space

Ellipse at NEL2

Propagate BeamStartingat N1 and ending at N2

Figure 6 TRACE 3-D Plot Control inputs.

The Beam and Final Pieces are usedto define the start and stop locationsfor beam propagation through thebeamline model.

8

The locations of the both the Initial and Final Pieces inthe beamline model are used to define the TRACE 3-D plot control parameters: N1 and N2. There must be anInitial Beam Piece in the beamline model to executeTRACE 3-D. However, a Final Piece is not required. Ifthere is no Final Piece in the model then the sequence ofthe last Piece in the Model used to define N2. If there aremultiple Initial Beam Pieces in the model then the rightmost Beam Piece will be used. If there are multiple FinalPieces in the model than the left most Final Piece will beused.

The model is sequenced left to right. N1 is initiallyassigned the sequence of the Initial Beam Piece and N2the Final Beam Piece. TRACE 3-D supports forward andbackward beam propagation. The direction is determinedby comparing the N1 and N2 values. If N1 < N2 thenforward propagation is used with N1=N1+1 and N2=N2-1. If N1 > N2 then beam propagation is backward. Bydefault NP1=NEL1=N1 and NP2=NEL2=N2. However,a Marker Piece (or Final Piece) may be used to specifyalternate locations for NP and NEL parameters.

Figure 7 Final (Marker) Piece Window.

There must be an Initial Beam Piecein the beam line model in order toexecute TRACE 3-D.

All pieces are sequenced includingPieces which are not supported asbeamline elements by TRACE 3-D.Unsupported Pieces are defined aszero length drift elements in TRACE3-D.

9

Figure 7 illustrates the Final Piece Window which issimilar to the general Marker Piece Window. The NewConstraints button opens the Matching SpecificationWindow. The New Diagnostics button opens the PlotControl Window shown in Figure 8.

Figure 8 Plot Control Window.

Markers for NP are only valid outside the range of N1-N2, e.g. NP1 <= N1 and NP2 >= N2 for forwardpropagation and NP1 >= N1 and NP2 <= N2 for backwardpropagation; Markers for NEL are only valid inside therange of N1-N2, e.g. NEL1 >= N1 and NEL2 <= N2 forforward propagation and NEL1 <= N1 and NEL2 >= N2for backward propagation. The last valid Marker for NP1(left to right) is used to assign the NP1 value and the firstvalid Marker for NP2 (left to right) is used to assign theNP2 value. The last valid Marker for NEL1 (left to right)is used to assign the NEL1 value and the first valid Markerfor NEL2 (left to right) is used to assign the NEL2 value.

This Getting Started Section is only intended to providethe user with a brief overview of the PBO Lab TRACE 3-D Application Module. Refer to the PBO Lab UserManual for more general information on the PBO Labuser interface. The remainder of this Section providesmore information on the material presented in the GettingStarted Section, as well as other important subjects onthe use of TRACE 3-D in PBO Lab. All users areencouraged to read the entire User Manual.

10



PB

O L

abT

M

2.0

PB

O L

abT

M

2.0


TRACE 3-D Output

11

12


2. TRACE 3-D OutputOutput from TRACE 3-D is sent to two different windowsin PBO Lab. Text and numerical data is sent to theTRACE 3-D Text Output Window. Graphic output suchas beam envelopes and phase-space ellipses are drawn inthe TRACE 3-D Graphic Output Window. Additionaloutput such as Aperture and Profile data, PARMILA Unitsdata and Matching data are written to disk files whichcan be opened from the View menu.

Text Output WindowText output from TRACE 3-D is sent to the TRACE 3-DText Output Window. The Text Output Window has adefault size and location but can be resized in both verticaland horizontal directions. Text output is appended toprevious output when this window remains open. Closingthe window will clear the previous content. File, Editand Font menus provide the standard commands in theText Output Window, including the Save As commandwhich can be used to save the output from TRACE 3-D to a named text file prior to closing the window.

Graphic Output WindowGraphic output from TRACE 3-D is sent to a graphicoutput window. The Graphic Output window has a defaultsize and location but can be resized in both vertical andhorizontal directions. The current window contents arere-scaled when the window is resized. The graphic outputwindow can be resized, positioned and left open forsubsequent graphic commands. The size is only limitedby the size of the monitor. Graphic output can not be sentto the window if it has been minimized.

13


The Text Output Window is clearedautomatically when the window isclosed. Leave the window open forcontinuous history or use the SaveAs command to save the data priorto closing the window.

When resized the Graphic Outputwindow will scale the output for thenew size.


14



PB

O L

abT

M

2.0

PB

O L

abT

M

2.0


TRACE 3-D File Menu

15

16


17


3. TRACE 3-D File MenuThere are two TRACE 3-D specific commands: Importand Export, in the PBO Lab File menu which is shown inFigure 9. The remaining commands in the File menu areapplication independent and are described in Section 3,“PBO Lab Interface” of the PBO Lab User Manual.

Figure 9 TRACE 3-D File Menu Commands.

ImportThe Import command is used to import a native TRACE3-D input file (Historically referred to as Tape 30). Aftera file is selected for import, PBO Lab will construct abeamline model from the native TRACE 3-D input file.The resulting model can then be saved as PBO Lab modelfile.

ExportThe Export command is used to export a native TRACE3-D input file. After a name is specified for the Exportfile, PBO Lab will write the native TRACE 3-D formattedinput file for the beam line model in a PBO Lab Documentwindow.



18




PB

O L

abT

M

2.0

PB

O L

abT

M

2.0


TRACE 3-D View Menu

19

20


21


4. TRACE 3-D View MenuThere are six commands in the PBO Lab View menu thatare specific to viewing TRACE 3-D data files. Figure 10shows the TRACE 3-D View sub-menu. The remainingcommands in the View menu are application independentand are described in Section 3, “PBO Lab Interface” ofthe PBO Lab User Manual.

Figure 10 TRACE 3-D View Menu Commands.

View Input FileThe Input File command is used to create and view a nativeTRACE 3-D input file (Tape 30) which is generated byPBO Lab from the Document beamline model. Thiscommand will create a “Trace3DInput” ASCII text file(any previous file is overwritten) and that file will beopened in an editable text window. The standard File,Edit and Font menus are provided. The Save As commandcan be used to save the input file with a unique name.Access to the TRACE 3-D native input file is providedfor informational purposes, the text file is not used toexecute TRACE 3-D. PBO Lab implements a dynamicdata interface with the TRACE 3-D application.

View Output FileThe Output File command is used to create and view anative TRACE 3-D data file (historically referred to asTape 31) which is generated by PBO Lab from the datareturned by TRACE 3-D after execution of a BeamDynamics command. The format of this data file is thesame as the Tape 30 input file. However, the output filewill also contain return data such as the output beam(BEAMO) and the output emittances (EMITO), for apreviously executed TRACE 3-D Beam Dynamicscommand.

View Profile DataThe Profile Data command is used to open an existing“Profile Data” file. The profile data file will be openedin an editable text window. The standard File, Edit andFont menus are provided. The Save As command can beused to save the input file with a unique name. The ProfileData file is created during the execution of the GraphBeam Line command when the Profile Data Option hasbeen selected in the TRACE 3-D Options window. Witheach execution of the Graph command a new Profile Datafile will be created, over writing any previous file.

View Aperture DataThe Aperture Data command is used to open an existing“Aperture Data” file. The aperture data file will be openedin an editable text window. The standard File, Edit andFont menus are provided. The Save As command can beused to save the input file with a unique name. TheAperture Data file is created during the execution of theGraph Beam Line command when the Aperture DataOption has been selected in the TRACE 3-D Optionswindow. With each execution of the Graph command anew Aperture Data file will be created, over writing anyprevious file.

Beam Dynamics commands aredescribed in in the TRACE 3-DCommands Menu Section.

The Profile Data Option is accessedwith the TRACE 3-D Optionscommand in the Commands menu.

The Aperture Data Option is accessedwith the Options command in theCommands menu.

22

View PARMILA UnitsThe PARMILA Units command is used to open an existing“PARMILA Units” file. The PARMILA Units file willbe opened in an editable text window. The standard File,Edit and Font menus are provided. The Save As commandcan be used to save the input file with a unique name.This command will not generate the file if it does notexist in the application directory. The PARMILA Unitsfile is created with the Compute PARMILA Unitscommand in the Commands menu. The file containsunnormalized input units and normalized output unitsconverted from TRACE 3-D BEAMI, BEAMO, EMITI,and EMITO parameters.

View Match FileThe Match Output command is used to view the“match.out” data file which is generated during a PerformMatching command. The match output file will be openedin an editable text window. The standard File, Edit andFont menus are provided. The Save As command can beused to save the input file with a unique name. Matchspecification and execution are described in the “TRACE3-D Matching” Section.

When the PARMILA Units commandis executed, any existing PARMILAData file will be over written.

The match output file will be overwritten on each execution of thePerform Matching command.

23



24




PB

O L

abT

M

2.0

PB

O L

abT

M

2.0


TRACE 3-D Commands Menu

25


26



27


5. TRACE 3-D Commands MenuThe Commands menu illustrated in Figure 11, is used toexecute TRACE 3-D specific commands. The majority ofcommands correspond directly to the native TRACE 3-Dcommands described in the TRACE 3-D Documentation.

Figure 11 TRACE 3-D Commands Menu.

TRACE 3-D Commands are organized in four functionalgroups. The first group contains beam dynamics relatedcommands. The second group of commands supportmatching operations. The third group contains displaycommands and the last command is for the TRACE 3-DOptions window.

Some TRACE 3-D commands that are not present in thePBO Lab TRACE 3-D Commands menu such asNEWFILE, INPUT, ADD, DELETE, QUERY and SAVEare found in the File menu or are effectively incorporatedinto the PBO Lab graphic user interface. Equivalentcommands for NEWFILE in PBO Lab are the New, Openand Import commands in the File menu. The INPUT,ADD, DELETE and QUERY commands are not usedsince the PBO Lab interface handles these functions withgraphical beamline set up and access to elementparameters by double-clicking Pieces in the beamlinemodel. The SAVE command equivalents in PBO Lab arethe Save, Save As and Export commands in the File menu.The END command is equivalent to Exit in the File menu.These menu commands are discussed in Section 3 “PBOLab Interface” in the PBO Lab User Manual. Two other

Most of the PBO Lab TRACE 3-DCommands correspond directly to thenative TRACE commands describedin the TRACE 3-D Documentation.


TRACE 3-D commands, CENTROID and APERTUREare integrated into the PBO Lab user interface. TheCENTROID equivalent in PBO Lab is the CentroidParameters tab panel in the Initial Beam Piece, whichprovides access to beam centroid offsets. TheAPERTURE command is implemented in PBO Lab as auser option. This is described in the “TRACE 3-DOptions” Section.

Most TRACE 3-D commands result in output to one oftwo different TRACE 3-D output windows. Graph BeamLine, Trace on Background and Plot Projectionscommands send graphics to a Graphic Output Window.Other Beam dynamics commands and the displaycommands send text to a Text Output window.

Beam Dynamics CommandsThere are five commands in the Beam Dynamics groupof the TRACE 3-D Commands menu. Each of thesecommands are described here.

Graph Beam LineThe Graph Beam Line command generates the TRACE3-D beam envelopes and phase-space ellipses in theGraphic Output window. Figure 12 shows the result ofexecuting the Graph Beam Line command using theExample B model distributed with the application anddescribed in the TRACE 3-D Documentation.

The beamline elements are drawn first in the profile boxat the bottom of the window. The initial phase spaceellipses are then drawn. Horizontal (solid red) and vertical(dashed blue) ellipses in the top plot and longitudinal(dashed green) in the bottom plot. If the Initial Piece is tothe right of the Final Piece in the beamline model, thenthe initial ellipses will be drawn on the left-hand side ofthe window; if the Initial Piece is to the right of the FinalPiece in the beamline model then the beam traverses themodel in the reverse direction and the initial ellipses willbe drawn on the right-hand side of the window.

The Graph Beam Line commandgenerates beam envelopes andphase-space ellipses in the GraphicOutput window.

28


Figure 12 Output from the Graph Beam Line Command.

Beam envelopes are then drawn in the beam profile boxat the bottom of the window. The horizontal (solid red)and longitudinal (dotted green) beam profiles in the upperhalf of the profile box and the vertical (dashed blue) profilein the lower half. After the beam envelopes are complete,the final ellipses are drawn followed by various parametervalues which are displayed in the center of the window asshown in Figure 12.

29


Trace on BackgroundThe Trace on Background command generates beamenvelopes and phase-space ellipses over the output froma previous Graph Beam Line command. The Tracecommand will be dimmed if a Graph command has notbe executed.

The Trace on Background command is not useful if thebeamline length has been changed or the Graphic OutputWindow has been resized since the last Graph command.The Graphic Output window must be left open after aGraph command to use the Trace on Backgroundcommand. Figure 13 shows the results from the Traceon Background command over the Graph exampleillustrated in Figure 16.

The Trace on Background commandgenerates an overlay of beamenvelopes and phase-space ellipsesin the current Graphic OutputWindow.

Figure 13 Output from the Trace on Background Command.

30


Plot ProjectionsThe Plot Projections command requires the previousexecution of a Graph command and will be dimmed if aGraph command has not be executed. Projections of thebeam in x-y, x-z and x-∆p/p are displayed in the GraphicOutput window. The upstream end of the system is shownon the left-hand side of the window and the downstreamend on the right. Figure 14 shows the resulting displayafter executing the Plot Projections command.

The Plot Projections command is usedto plot initial and final projections onx-y, x-z and x-∆p/p planes.

Figure 14 Output from the Plot Projections Command.

31

Calculate Phase AdvanceThe Calculate Phase Advance command is used tocalculate and display the phase advance (σ) and the Twiss(α & β) beam ellipse parameters for each of the threephase-space planes. This command requires a previousexecution of the Graph command. The phase advance isgiven in degrees, alpha and beta are in mm/mrad. Theresults are sent to the Text Output window. An exampleof the resulting output from this command is shown inFigure 15.

Calculate Phase & EnergyThe Calculate Phase & Energy command is used tocalculate and display information about the thelongitudinal plane of the output beam. This includes thephase and energy of the beam center, the phase and energyhalf-widths, the length on the longitudinal semi axis, thehalf-width and the longitudinal emittance. An example ofthe resulting output from the Calculate Phase & Energycommand is shown in Figure 15. Refer to Section 10.23in the TRACE 3-D Documentation for additionalinformation on Phase and Energy.

Figure 15 Output from Calculate Phase Advance andCalculate Phase & Energy Commands.

The Calculate Phase Advancecommand calculates and displays thephase advance and Twiss parametersfor the three phase-space planes.

32

Matching CommandsThere are five different matching related commands inthe TRACE 3-D commands menu. These are brieflydescribed here. The “Matching Options” Section describesthe steps for setting the match type and specifying matchand couple variables for a matching problem.

Match SpecificationThe Match Specification command opens the TRACE 3-D Match Specification window. Depending on theparticular match type selected, TRACE 3-D will attemptto find matched-ellipse parameters or values for specifiedmatch variables, in order to fit the final beam or specifiedmatrix elements. The match procedure searches for asolution to a set of nonlinear, simultaneous equations inan iterative procedure. The maximum number of iterations(NIT) and the matching tolerance (DELTA) are set in theMatch Specification Window as described in the“Matching Options” Section. If a solution has not beenfound within the specified number of iterations, then thematch variables will be set to the values found whichminimize the convergence factor.

Perform MatchingThe Perform Matching command is used to start thematching process. The match type must be set prior toexecution of this command. Output from the matchingprocess includes the convergence factor and the valuesfor each of the match variables. This data is written tothe match.out file for each iteration. Matching willproceed until the maximum number of iterations has beenreached or when the convergence factor falls below the

The “Matching Options” sectiondescribes the steps for setting thematch type and specifying match andcouple variables for a matchingproblem.

33

user specified Tolerance. The final values calculated forthe selected match variables and the associatedconvergence factor are sent to the Update Match Variableswindow as described in the “Matching Options” Section.

Calculate MismatchThe Calculate Mismatch command calculates and displaysthe mismatch factor between the output beam (BEAMO)and the desired final beam (BEAMF). Note that a matchtype must be set in the Match Specification window.Output from the Calculate Mismatch command is sent tothe Text Output window.

Match and Couple VariablesThe Match Variables command opens the TRACE 3-DMatch Variables window which displays the current matchvariable selections and there values. The CoupledVariables command opens the TRACE 3-D CouplingVariables window which displays the currently selectedTRACE 3-D coupling variables and their associated matchvariables.

Display CommandsA variety of commands are available for displaying databefore and after a Graph command has been executed.Most of these commands display data calculated from aprevious Graph command. Figure 16 illustrates the TextOutput window after executing the Show Beam Vectors,Show R-Matrix and Show Modified Sigma commands.This output is from Example B after matching toconvergence.

For a definition of the TRACE 3-Dmismatch factor refer to theTRACE 3-D Documentation.

The Match and Coupling windowsare discussed in the “MatchingOptions” Section.

34

Show Beam VectorsThe Show Beam Vectors command is used to display allof the TRACE 3-D beam vectors. The initial beam(BEAMI), the final beam (BEAMF) and the output beam(BEAMO) are displayed, followed by the beam centroidoffsets (BEAMC) and the initial beam centroid offsets(BEAMCI). The output for this command is illustratedin Figure 18. The output beam (BEAMO) must becalculated in a previous Graph command.

Show R MatrixWhen a Graph command is executed the 6x6 transfermatrix is stored in the RM array. The Show R Matrixcommand displays this R matrix. A description of the Rmatrix for each element can be found in Section 6“Transfer Matrices” in the TRACE 3-D Docu-mentation.An example of the output generated by this command isillustrated in Figure 18.

Show Modified SigmaThe Show Modified Sigma command displays themodified Sigma matrix in the Text Output window in theformat shown in Figure 17. Output from the ShowModified Sigma command is shown in Figure 16.

x max

x 'max

y max

y 'max

z max∆p

p max

r12r13r14

r15r16

r 23r 24

r 25r 26

r 34

r 35r 36 r 56

r 45r 46

Figure 17 Modified Sigma Matrix Format.

Because the Sigma matrix is asymmetric matrix, only half of theelements are displayed.

35


Figure 18 shows of the resulting output from the threedisplay commands: Show Beam Vectors, Show R Matrix,and Show Modified Sigma.

Figure 18 Example Output from Various Display Commands.

Calculate PARMILA UnitsThe Calculate PARMILA Units command will causeTRACE 3-D to calculate and write the “PARMILA Units”file. This file will then be opened in a text window. ThePARMILA Units file contains PARMILA unnormalizedinput units and normalized output units converted fromTRACE 3-D BEAMI, EMITI, inputs and BEAMO,EMITO outputs. The PARMILA Data file may be openedusing the Show PARMILA Data command in the Viewmenu.

OptionsThe Options command is used to open the TRACE 3-DOptions window which provides access to additionalTRACE 3-D parameters, including graphic scales, elementoptions for the PMQ Step size and fringe field extensionfactor and Thin Lens chromatic aberrations, and profile/aperture data output options. The Options window isdescribed in the “TRACE 3-D Options” Section.

When the PARMILA Units commandis executed any existing PARMILA Datafile will be over written.

The Options command is used toaccess graphic scales, elementoptions and profile/aperture datapreferences.


36



PB

O L

abT

M

2.0

PB

O L

abT

M

2.0


TRACE 3-D Matching

37


38



39


6. TRACE 3-D MatchingThe matching capabilities of TRACE 3-D are among itsmost powerful features. This section discusses the use ofPBO Lab to implement the various matching optionsavailable in TRACE 3-D. The set up of matchingproblems is the focus of this section. The Matchcommands are discussed in the “TRACE 3-D CommandsMenu” Section.

Fourteen different beam matching or parameter fittingoptions are available in TRACE 3-D. The match type(MT) indicates the type of matching desired. Types 1-4specify that matched Twiss parameters are to be found.Type 13 specifies that initial Twiss parameters are to befound to fit desired final Twiss parameters. Types 5-12specify that values are to be found for selected elementparameters to fit final Twiss parameters, or to fit selectedR matrix or Sigma matrix elements. Type 14 specifiesthat values are to be found for selected element parametersto fit for desired phase advances in selected phase planes.

The PBO Lab TRACE 3-D Match Specification Windowshown in Figure 19 is used to set the match type and toaccess other matching parameters. Matching types aredivided into two groups: “Find Matched TwissParameters” and “Find Variables For Match”. Match types1-4 are used to find matched Twiss parameters, similarlymatch type 13 varies initial Twiss parameters to matchfor desired final Twiss parameters. Match types 5-12 areused to find variables for a match by varying elementparameters.

TRACE 3-D supports fourteendifferent types of beam matchingand fitting.

Match types are divided into BeamMatching and Parameter Fittinggroups.


Figure 19 TRACE 3-D Match Specification Window.

The Match Specification window also provides access toadditional parameters for the maximum number of matchiterations (NIT) and the tolerance for matchingconvergence (DELTA). All of the matching proceduresuse the convergence criteria which are specified in theMatch Specification Window. Matching is terminated ifthe calculated mismatch factor is below the specifiedTolerance value or when the maximum number ofiterations has been reached.

40


The Match Specification Window provides a Final Beambutton which opens the Final Beam Window. Thiswindow, shown in Figure 20 is used to specify the desiredfinal (output) beam for match types 5-9 and 12.

Figure 20 Final Beam Window.

The Matrix Element button in the Match SpecificationWindow opens the Matrix Goal Selections Window shownin Figure 21. This window allows the user to specifyvalues of selected R matrix elements (match type 10) orSigma matrix elements (match type 11).

Figure 21 Matrix Goal Selections Window.

A detailed definition of the mismatchfactor can be found in the TRACE3-D Documentation.

41


For match type 14, the Phase Advances button is used toopen the window shown in Figure 22 in order to fit forspecified phase advances in the selected phase planes.

Figure 22 Match for Phase Advancesin Selected Phase Planes.

Beam Matching(Find Matched Twiss Parameters)

Beam Matching procedures are specified in the MatchSpecification Window. The Initial Beam Twiss Parametersare varied with these procedures but they are not explicitlyselected as match variables. The Perform Matchingcommand in the TRACE 3-D Commands menu is usedto execute the matching procedure. Following thematching procedure, the Update Beam Parameterswindow, shown in Figure 23 is automatically opened. TheInitial Beam Parameters will not be updated in thebeamline model until they are explicitly updated by theuser. Parameters may be updated individually or all atonce. All parameter updates must be made prior to closingthe window. Continue the matching procedure withadditional executions of the Perform Matching commandafter updating the beam parameters. The variables foreach match iteration and the associated mismatch factorare written to the “match.out” file which can be openedwith button in the Update Window or by using the matchoutput View menu command.

42


Figure 23 TRACE 3-D Beam Update Window.

Parameter Fitting(Find Variables For Match)

Parameter Fitting procedures are specified in the MatchSpecification Window. The beamline element parametersvaried with these procedures must be explicitly selectedas match variables in the Special Parameter Settingwindow. The S-Window, shown in Figure 24 is accessedwith the S-button located to left of the parameter name inthe Piece Windows of beamline elements.

Application specific inputs are accessed in the TRACE3-D tab panel of the Special Parameter Settings Window.The example in Figure 24 shows the Magnetic FieldGradient parameter being selected as a match variable inthe Quadrupole element labeled QUAD1.

43


Application Specific settings for TRACE 3-D include specifying parameter as a Match Variable, Coupled to

a Match Variable or as an Import Parameter.

Application Independent Variable Name

Figure 24 Special Parameter Setting Window.

Depending on the type of Parameter Fitting selected, thefitting constraints are specified with the Final Beam,Matrix Elements or Phase Advances buttons in the MatchSpecification window shown in Figure 19. The PerformMatching command in the TRACE 3-D Commands menuis used to execute the matching procedure.

44


Figure 25 Update Match and Couple Variables Window.

Following the matching procedure, the Update MatchVariable window shown in Figure 25 is automaticallyopened.

The fitted match variables will not be used to update thebeamline model until they are explicitly updated by theuser. Parameters may be updated individually or all atonce. All parameter updates must be made prior to closingthe window. The variables for each match iteration andthe associated mismatch factor are written to the“match.out” file which can be opened with button in theUpdate Window or by using the match output View menucommand. The Update Window also displays anyparameters which have been coupled to a match variable.As with the match variables, the couple variables will notbe used to update the beamline model until they areexplicitly updated by the user.

45


TRACE 3-D Matching TypesEach of the TRACE 3-D match types for Beam Matchingand Parameter Fitting are briefly described here. Adetailed definition is presented in the TRACE 3-DDocumentation.

Find Matched Twiss Parameters(Match Types 1-4)

Once a beamline is defined the only action necessary forsetting up a beam matching problem to Find MatchedTwiss Parameters (match types 1-4) is to select the matchtype in the Match Specification Window. Once the matchtype is specified, select the Perform Matching Commandsin the TRACE 3-D Commands menu to execute theTRACE 3-D matching procedure. These commands arediscussed further in the “TRACE 3-D Commands”Section.

Find Variables For Match(Match Types 5-12 & 14)

Once a beamline is defined, match variables must bespecified for parameter fitting in order to Find VariablesFor Match (match types 5-12 & 14). These match typeshave been further divided in the Match SpecificationWindow according to whether the objective is to adjustbeamline element parameters to achieve (a) specified finalvalues of certain Twiss parameters (match types 5-9), (b)specified values of selected R matrix elements (match type10) or Sigma matrix elements (match type 11), (c) fit fora round beam (match type 12), or (d) fit for specifiedphase advances in selected phase planes (match type 14).

Use the Match Output button in theUpdate Window to view matchingresults.

PBO Lab automatically sets up the MPand MVC arrays that are used byTRACE 3-D.

46


Match and Couple VariablesBeamline element parameters are selected as matchingTRACE 3-D (MP) or coupling (MVC) variables in aSpecial Parameter Settings windows described previously.This is illustrated in Figure 26 with a Quadrupole PieceWindow. In this example the “S” button is pressed forthe Magnetic Field Gradient parameter. This opens theSpecial Parameter Settings window (S-Window). The S-Window is a PBO Lab window with application specifictab panels. The number of tab panels depends on thenumber of installed applications. Only the TRACE 3-DSpecial Parameter Setting are described here.

The "S" button opens the Special Parameter Settings Window for a parameter.

This parameter has been defined as a TRACE 3-D

Match Variable.

Figure 26 Special Parameter Settings Window.

47

By default there are no active Special Parameter Settingsfor Piece Parameters. Initially the Parameter Variablename field at the top of the S-Window is empty and theradio button selection indicates the parameter value asspecified in the Piece Window.

The only thing that is required to specify a parameter asa match variable is to select the “Match Variable” radiobutton in the TRACE 3-D tab panel. A default variablename will be generated in the Parameter Variable text fieldin the upper (application independent) portion of the S-Window. The Parameter Variable name is applicationindependent which means that it is used by PBO Lab andit may also be used by any installed application.TRACE 3-D does not use this variable name directly. Thename is used in the PBO Lab interface to identify theSpecial Settings for this parameter. This name can bechanged but must always be unique among other variablenames in a beamline model. The variable name is alsoused when specifying a coupling variable

This parameter has been Coupled to a previously defined Match Variable.

Figure 27 Specifying Coupling Parameters.

TRACE 3-D supports coupling element parameters tomatch variables. PBO Lab identifies match variables by

48

name and this name is used to specify which matchvariable will be used for coupling a parameter. This isillustrated in Figure 27.

In this example the radio button for “Couple to MatchVariable” has been selected and user has previouslyspecified four match variables which appear in the popup to the right.

This parameter will be coupled to the chosen matchvariable in the pop up list. The “Coupling K factor” isspecified in the field to the right. It’s use is described inthe TRACE 3-D Documentation. The default value ofone has no effect.

Match and Couple List WindowsThere are additional windows available to show all of thematch and coupling selections. The Match Variablescommand in the TRACE 3-D Commands menu opens theMatch Variables list window shown in Figure 28. TheCoupled Variables command in the TRACE 3-DCommands menu opens the Coupling Variables listwindow shown in Figure 28. Double clicking on any entryin these windows will open the associated Piece Windowcontaining that match or couple variable.

Figure 28 Match & Coupling Selections.

49

Matching the R and s Matrices(Match Types 10 & 11)

Both the R Matrix option (match type 10) and the SigmaMatrix option (match type 11) use the Matrix GoalSelections Window (Figure 21) for inputting the goalvalues for up to six (6) of these matrix elements. Theprocess for making goal selections in this window is thesame for either matrix. To specify a matrix element value,click on the desired element in the matrix display andenter the value in the Matrix Value field. Use the Acceptbutton to add it to the list. An entry in the list can beremoved by selecting it with the mouse and pressing thedelete button.

Matching for Round Beam(Match Type 12)

Match Type 12 is used to vary element parameters to fitfor a round beam (equal X and Y envelopes at the end ofthe beamline). Matching variables (beamline elementparameters which are to be varied) must be specified asdescribed previously. The Perform Matching commandcan then be executed to find values for match variablesthat satisfy the desired round beam.

Matching for X,Y,Z Planes(Match Type 13)

Match Type 13 is used to vary initial Twiss parameters(BEAMI) to fit a desired beam in X,Y,Z planes(BEAMF).The initial Twiss parameters in the Initial PieceWindow will be varied by TRACE 3-D to fit a desiredfinal beam which is specified in the Final Beam Window.The Final Beam Window (Figure 20) is opened with theFinal Beam buttons in the Match Specification Window.The Perform Matching command can then be executed tofind the initial Twiss parameters that satisfy the desiredFinal Beam.

The VAL and IJM arrays areautomatically set up from the usersMatrix Goal Selections.

50

Matching for Phase Advance(Match Type 14)

Match Type 14 is used to vary element parameters to fitfor specified phase advances in specified phase-spaceplanes. Match variables (beamline element parameterswhich are to be varied) must be specified as describedpreviously. The desired phase-space planes and phaseadvances are set in the Match for Phase Advance Windowillustrated in Figure 22. This window is opened with thePhase Advances button in the Match SpecificationWindow.

The match output file will be overwritten on each execution of thePerform Matching command.

51



52




PB

O L

abT

M

2.0

PB

O L

abT

M

2.0


TRACE 3-D Options

53

54


55


7. TRACE 3-D OptionsThe TRACE 3-D Options Window is opened with theOptions command in the TRACE 3-D Commands Menu.The Options window, shown in Figure 29 provides accessto TRACE 3-D graphic scales, element options for thePMQ Step size and fringe field extension factor as wellas Thin Lens chromatic aberrations, and profile/aperturedata output options.

Figure 29 TRACE 3-D Options Window.

Graphic Scaling ParametersThe Graphic Scales tab panel of the Options Windowprovides access to the TRACE 3-D graphics scales XM,XPM, DPP, YM, XMI, XPMI, DPMI, DWMI, XMF,XPMF, DWMF, DPMF. These parameters set values forthe boundaries of the phase-space and profile plots in theTRACE 3-D Graph Ellipses & Profile Window.

The XMI (mm) and XPMI (mrad) parameters are the axesfor the initial transverse phase-space plots. DPMI (deg)and DWMI (keV) are the axes for the initial longitudinalphase-space plots. YM (mm) is the vertical axis for thetransverse beam profiles and DPP (deg) is the maximumphase profile. XMF (mm) and XPMF (mrad) are the axes

for the final transverse phase-space plots. DPMF (deg)and DWMF (keV) are the axes for the final longitudinalphase-space plots. XM (mm) and XPM (mrad) are theaxes for the projection phase-space plots.

The following equations are used to initially estimatevalues for the TRACE 3-D graphics scales:

XMI = GraphScale1*SQRT((Betah)*(Emith)),XPMI = GraphScale1*SQRT((Gammah)*(Emith)),

where Gammah = (1.0 + Alphah**2)/Betah.

Emith, Alphah and Betah are the current values for theseinput parameters shown in the Initial Beam Piece window.This is repeated for the vertical plane, and the larger ofthe two values of XMI and XPMI are used. Similarly forthe longitudinal plane

DPMI = GraphScale3 *SQRT((Betaz)*(Emitz)),and DWMI = GraphScale3*SQRT((Gammaz)*(Emitz)),where Gammaz = (1.0 + Alphaz**2)/Betaz),The same scalingis done for the final graphics scales (XMF, XPMF, DPMFand DWMF, which set values for the boundaries of thefinal phase-space plots).

The profile and projection graphics scales are set as

YM = GraphScale2*larger(XMI,XMF),DPP = GraphScale4*larger(DPMI,DPMF),XM = GraphScale2*larger(XMI,XMF),

and XPM = GraphScale4*larger(XPMI,XPMF).

The values used for the GraphScale factors are:

GraphScale1 = 2.0GraphScale2 = 1.2GraphScale3 = 2.0GraphScale4 = 1.2

Element OptionsThe Element tab panel in the TRACE 3-D OptionsWindow allows the user to specify the PMQ step size andfringe field extension factor and select an option for theuse of Thin Lens chromatic aberrations.

Refer to subheading 9.5 from Section9 “Input Variables” of the TRACE3-D Documentation.

56

The PMQ Maximum Step Size (PQSMAX) parameter isused in TRACE 3-D dynamics calculations. Otherelements use the Maximum Step Size Global Parameter(SMAX). The Fringe Field Extension Factor (PQEXT)is used for calculating the extension of the fringe field ofpermanent-magnet quadrupole elements.

The Chromatic Aberrations option specifies whetherchromatic aberrations are to be taken into account in theThin Lens element. Refer to Section 9.1 and Appendix Iof the TRACE 3-D Documentation for a detaileddescription of this option.

Profile and Aperture OptionsThe Profiles and Apertures tab panel of the OptionsWindow, provides access to the TRACE 3-D options forgenerating Profile and Aperture data files and forspecifying a the Aperture Multiplication Factor.

Generate Aperture FileIf the Generate Aperture Data option is selected thenaperture data will be written during the execution of theGraph Beam Line command. Any existing “ApertureData” file will be overwritten. The Aperture Data filecan be opened using the View menu Aperture Datacommand. The Aperture Multiplication Factor is used inthe generation of the aperture data.

Generate Profile DataIf the Generate Profile Data option is selected then profiledata will be written during the execution of the GraphBeam Line command. Any existing “Profile Data” filewill be overwritten. The Profile Data file can be openedusing the View menu Profile Data command. TheAperture Multiplication Factor is used in the generationof the profile data.

For further definitions and discussionrefer to sub-headings 9.1 and 9.3from Section 9 “Input Variables,”of the TRACE 3-D Documentation.

For definitions and discussion referto Section 10.8 of the TRACE 3-DDocumentation.

57


58



PB

O L

abT

M

2.0

PB

O L

abT

M

2.0


Appendix “TRACE 3-D Documentation”

59

60


Documents

PBO Lab 2 - GHGA Homepage · ii. PBO Lab 2.0 User ... PBO Lab 2.0 User Manual Supplement: TRACE 3-D Module ... the Final Beam parameters are not contained in a PBO The Particle Distribution