pbo lab 2 - ghgapbo lab 2.0 user manual supplement: transport module 5 figure 2 is an example of the...

PBO Lab 2.0 User Manual Supplement: TRANSPORT Module

i

PBO Lab™ 2.0(Particle Beam Optics Laboratory)

User Manual Supplement:TRANSPORT Application Module

Distributed by

AccelSoft, Inc.P. O. Box 2813

Del Mar, CA 92014 USA

(858) [email protected]

www.ghga.com/accelsoft


ii

PBO Lab 2.0 User Manual Supplement: TRANSPORT Application Module 1997, 1999, 2000 by G. H. Gillespie Associates, Inc.All Rights Reserved.

Second Printing: March 2001

ISBN 1-892267-04-7

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.


iii

“TRANSPORT User Manual”Third-Order TRANSPORT with MAD Input, A Computer Program for Designing Charged ParticleBeam Transport Systems, by D. C. Carey, K. L. Brown and F. Rothacker, October 1998.

Fermi National Accelerator Laboratory report number Fermilab-Pub-98-310, UC-414.Stanford Linear Accelerator Center report number SLAC-R-530.Reproduced for distribution with PBO Lab by permission.

DISCLAIMER NOTICE (TRANSPORT - Fermi National Accelerator Laboratory):This material was prepared as part of work sponsored by the United States Department of Energy. TheDepartment of Energy, Universities Research Association, Inc., and their agents and employees, makeno warranty, express or implied, and assume no legal liability or responsibility for the accuracy,completeness, or usefulness of any information, apparatus, product, or process disclosed, nor representthat its use would not infringe privately owned rights.

DISCLAIMER NOTICE (TRANSPORT - Stanford Linear Accelerator Center):The items furnished herewith were developed under the sponsorship of the U.S. Government. Neitherthe U.S., nor the U.S. Department of Energy, nor the Leland Stanford Junior University, nor theiremployees, makes any warranty, express or implied, or assumes any liability or responsibility for accuracy,completeness or usefulness of any information, apparatus, product or process disclosed, or representsthat its use will not infringe privately-owned rights. Mention of any product, its manufacturer, or suppliersshall not, nor is it intended to, imply approval, disapproval, or fitness for any particular use. The U.S.and the University at all times retain the right to use and disseminate the furnished items for anypurpose whatsoever.

TRANSPORT is a FORTRAN program maintained and distributed by the Fermi NationalAccelerator Laboratory and the Stanford Linear Accelerator Center. TRANSPORT isincluded with the PBO Lab software with the written permission of both the FermiNational Accelerator Laboratory and the Stanford Linear Accelerator Center.


iv

This page is intentionally blank.


v

Table of Contents

Chapter and Subject Page

1. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Running TRANSPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2. TRANSPORT Application Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Beam Line Global Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Initial Floor Coordinates and Orientation Parameters . . . . . . . . . . . . . . . . . . . 11

3. Beamline Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Beam Piece . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Marker Piece. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Location-Specific Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Location-Specific Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Location-Specific Stored Output Parameters . . . . . . . . . . . . . . . . . . . . . . . 23

Stored Parameters List Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Parameter Piece . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Matrix Piece . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Special Piece . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

4. Special Parameter Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Symbolic Parameter Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Transport Parameter Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Parameter Algebraic Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Updating Parameter Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Parameters & Expressions List Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

5. TRANSPORT Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49TRANSPORT Commands Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Execution Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Matrix Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55List Windows Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Options Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

TRANSPORT View Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56


vi

Table of Contents (continued)

Chapter and Subject Page

6. Displaying and Creating Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Show R-Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Creating a Matrix Piece. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Show Sigma Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Creating a Beam Piece . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Make Matrix Piece Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

7. TRANSPORT Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Calculation Order and Output Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Print Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Output and Punch File Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

8. TRANSPORT Plot Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Plotting Matrix Elements vs. Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Plotting Envelope, Centroid and Lattice Functions

vs. Accumulated Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Plotting Floor Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Plotting Final Ellipses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Graph Plot Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

9. TRANSPORT Fitting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Fitting Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Named Parameter List Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Fitting Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Fitting Constraints Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Constraint Expressions List Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Perform Fitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Update Variables and Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

10. Appendix: “TRANSPORT User Manual” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Third-Order TRANSPORT with MAD Input, A Computer Programfor Designing Charged Particle Beam Transport Systems

PB

O L

abT

M

2.0

PB

O L

abT

M

2.0

Getting Started

1

User ManualSupplement:TRANSPORTApplicationModule


1. Getting StartedThis Section is intended as a quick start introduction forrunning the TRANSPORT Application Module in theParticle Beam Optics Laboratory. The remainder of thisSupplement describes the PBO Lab user interface featuresthat are specific to the TRANSPORT Application Module.Refer to the PBO Lab User Manual for more generalinformation on the PBO Lab user interface. The“TRANSPORT User Manual” describes theTRANSPORT program.

Running TRANSPORTExecution of TRANSPORT is accomplished from theCommands Submenu, shown in Figure 1, by selecting oneof the Write Input and Run Transport commands.

Figure 1. TRANSPORT Commands Menu.

The Write Input and Run Transport command providesoptions for running TRANSPORT with or without Fitting.Both options will generate the native input and executeTRANSPORT for the beamline in the Model Space ofthe Document Window. The second command in thisgroup opens the Transport Plot Specifications Window.

The next group of commands provide options to separatethe generation of input from the execution of TRANSPORT.

The next group of commands is for the display of diagnosticdata, followed by a Submenu that provides access to user-specified Named Parameters, Variables, Expressions andFitting Constraints for the entire beamline.

This Supplement describes the userinterface features specific to theTRANSPORT Application Module.Refer to the main PBO Lab UserManual for more general informationon the PBO Lab user interface. Referto the “TRANSPORT User Manual” fora description of the TRANSPORTprogram.

The Commands Submenu forTRANSPORT is used to set variousoptions and output parameters forthe TRANSPORT Application Moduleas described in this Supplement.

PBO Lab provides a group ofcommands that can be used togenerate the native TRANSPORT inputindependently from the execution ofthe TRANSPORT program. Usingthese commands allows the inputgenerated by PBO Lab to be modifieddirectly before running TRANSPORT.


3


4

The last command in the TRANSPORT Commands menuis used to access various options and output parameters.

To Run the TRANSPORT Application Module simplyselect the command to Write Input and Run Transportwithout Fitting from the Commands Menu as illustratedin Figure 2. The native Transport Output file isautomatically displayed in a scrollable Text Edit Windowupon completion of the run. Use the Save As commandin the File Menu of the Text Edit Window to rename theoutput file if desired. Both the Transport Input and Outputfiles will be overwritten on any subsequent execution ofthe TRANSPORT Application Module.

Selecting the first item in the TRANSPORT Commands Menu generates the native

Transport Input for the beamline model in the Document Window and then executes the

TRANSPORT Application Module

Figure 2. Executing the TRANSPORT Application Module.


5

Figure 2 is an example of the outputwindow that is displayed when theTRANSPORT run is completed. Thecontent of the native TransportOutput file will depend on variousoptions and output parameters setby the user.

Figure 2 illustrates the selection of the first command,which will write the native Transport Input file and runTRANSPORT for the current beamline model. Theselected command is executed after the mouse button isreleased. Following execution, the Transport Output filewill be displayed, as illustrated in Figure 2.

PBO Lab also provides graphic representations of datagenerated from TRANSPORT. The Transport PlotSpecification command in the Commands Menu can beused to direct output to the Transport Plot file which isused by PBO Lab to generate interactive graph plots. Anyplot specifications will result in PBO Lab Graph PlotWindows being opened automatically after execution ofTRANSPORT. A description of Transport PlotSpecifications can be found in Chapter 8 of thisSupplement. The user interface for Graph Plot Windowsis described in the main PBO Lab User Manual.



6

PB

O L

abT

M

2.0

PB

O L

abT

M

2.0

TRANSPORT Application Module



7

2. TRANSPORT Application ModuleThis Section describes the PBO Lab Application Context andGlobal Parameters that are specific to the TRANSPORTApplication Module. Refer to the Getting Started and UserInterface Chapters of the PBO Lab User Manual for moregeneral information on the PBO Lab user interface. The“TRANSPORT User Manual,” included with thisSupplement, describes the TRANSPORT program in generaland each of the native TRANSPORT input parameters.

Tab Panels provide access to additional Global Parameters and Initial Floor Coordinates

for the beamline model

Green dots indicate which Parameters are native inputs for TRANSPORT

Set the Application Context pop-up for the TRANSPORT Application Module

Figure 3. TRANSPORT Application Context and Global Parameters.

The Application Context pop-up in the Button Bar of theDocument Window is shown in Figure 3. The ApplicationContext does not need to be set for TRANSPORT in orderto execute TRANSPORT commands. However, theApplication Context is used to indicate which inputparameters are native inputs for TRANSPORT. Nativeinputs are indicated in the Global Parameters and in eachPiece Window using green dots that appear to the right ofa parameter.

The Application Context is used toidentify native parameters with greendot indicators.

The Application Context is also usedto activate any application-specificbuttons and in some cases, todetermine which application-specificwindows will be opened.


9


10

Beamline Global ParametersThe PBO Lab Beamline Global Parameters are describedin the Getting Started and User Interface Chapters of thePBO Lab User Manual. This Section discusses the GlobalParameters that are used by the TRANSPORT ApplicationModule.

The native Global Parameters for TRANSPORT includethe Particle Charge, Particle Mass, Beam Energy andFrequency. These parameters are indicated with green dotswhen the Application Context is set for TRANSPORT inthe Document Window, as shown in Figures 3 and 4.

The PBO Lab Global Parametersinclude native TRANSPORT inputs suchas the Particle Charge, Particle Mass,Energy and Frequency, which areglobal to the entire beamline model.

Hide and Show the Global Parameters from the View

Menu or the Button Bar

The Beamline Global Parameters are accessed from three tab panels that float over the Work Space of

the Document Window

Figure 4. Beamline Global Parameters in the Document Window.


11

The Particle Charge Global Parameter is not a nativeTRANSPORT input. However, PBO Lab does use anothernative TRANSPORT input, PREF in order to scale allmagnetic fields to a “reference momentum”, which isdifferent from the beam momentum “PO”. InternallyTRANSPORT converts all fields by the ratio of PO/PREFand in the native Transport Output file, the scaled fieldsare printed. The use of PREF in TRANSPORT is describedin the “TRANSPORT User Manual” included with thisSupplement. PBO Lab calculates an effective PREF andwrites it to the Transport Input file, handling all othernecessary conversions as well.

Several of the Global Parameters are also used for a varietyof PBO Lab calculations and displays, although they maynot be native inputs for TRANSPORT. Additional GlobalParameters are accessed from the Tracing/Tracking tabpanel and the Floor Coordinates tab panel as illustratedin Figure 4 on the previous page.

The Tracing/Tracking Global Parameters tab panel (Figure4) has inputs that are used by both the TURTLE andMARYLIE Application Modules. These parameters aredescribed in each of the Supplements for those ApplicationModules. The Tracing/Tracking Global Parameters are notused by the TRANSPORT Application Module.

Initial Floor Coordinates andOrientation Parameters

Included with the beamline Global Parameters are a setof Initial Floor Coordinate Parameters of the beamreference trajectory, which are shown in Figure 4. Theseparameters are used to specify the initial coordinates andthe orientation of the reference trajectory. If theseparameters are zero (default values are zero) thenTRANSPORT assumes that the beamline will start at theorigin and proceed along the positive z-axis. Floor plotsare specified in the Transport Plot Specification Windowdescribed in Chapter 8 of this Supplement.

Although the Particle Charge is nota native TRANSPORT input, PBO Labutilizes another TRANSPORT nativeinput parameter, PREF, that is usedto scale all magnetic fields to a“reference momentum” which isdifferent from the beam momentum.

A green dot next to a parameterindicates that it is a native input forthe current Application Context setin the Document Window.

The Tracking and Tracing GlobalParameters are not used by theTRANSPORT Application Module.

Included with the PBO Lab GlobalParameters are the Initial FloorCoordinates and Orientation inputsthat are used by TRANSPORT.



12

PB

O L

abT

M

2.0

PB

O L

abT

M

2.0

Beamline Elements



13

3. Beamline ElementsThe PBO Lab Pieces implemented for TRANSPORT arelisted in Table 1 below. Native TRANSPORT inputs forthese elements are indicated in the Piece Windows. Aswith the Global Parameters, green dots are found to theright of Piece Parameters that are native inputs. (TheApplication Context must be set for TRANSPORT in theButton Bar of the Document Window.)

Table 1. PBO Lab Pieces supported by TRANSPORT.

The Piece Window user interface is described in the GettingStarted and User Interface Chapters of the PBO Lab UserManual. However, several pieces have features that arespecific to TRANSPORT and those are described separatelyin this Chapter. The “TRANSPORT User Manual”(included with this Supplement) describes theimplementation of the other elements supported by theTRANSPORT Application Module in PBO Lab. ManyPieces also provide run-time Tutorials that are accessed fromthe Tutorial buttons in the Piece Windows.

Table 1 lists all of the Pieces that arerecognized by TRANSPORT. Pieces inthe beamline model that are notsupported by TRANSPORT will betreated as zero-length drifts whenPBO Lab generates the native inputfor TRANSPORT.

Beam Bend Accelerator Eta

Drift Edge Align Param

Quadrupole Lens Kicker Special

Solenoid Plasma Lens ∆RMS Marker

RF Gap Sextupole Rotate Final

Sector Bend Octupole Septum

Rectangular Centroid MatrixBend


15


16

Beam PiecePBO Lab uses the Beam Piece to generate the initialSigma-Matrix for TRANSPORT. The beamline modelmust include a Beam Piece, usually as the first piece inthe beamline as illustrated in Figure 5. The Beam Piece isused to specify the initial Sigma-Matrix for TRANSPORTin two different ways, referred to as the Semi-Axesrepresentation and the Twiss, or Courant-Snyderrepresentation. The Semi-Axes representation is moregeneral and allows for the complete specification of anySigma-Matrix, including correlations between differentphase planes. The Twiss parameter representation is usefulfor specifying initial beams in which the phase planes(horizontal, vertical and longitudinal) are decoupled.TRANSPORT permits the use of the Twiss parameterrepresentation only for the transverse phase planes(horizontal and vertical) of the initial beam.

Double-click the Beam Piece to Access Beam Parameters

Set the Application Context for TRANSPORT

Figure 5. Initial Beam Parameters in the Beam Piece Window.

Beam Piece

The beamline model must include aBeam Piece in order to generate thenative beam inputs for TRANSPORT.

The native beam inputs forTRANSPORT can be generated fromeither the Semi-Axes or Twiss BeamPiece Parameters.

TRANSPORT permits the use of theTwiss parameter representation only forthe transverse phase planes (horizontaland vertical) of the initial beam.


17

Both the Semi-Axes and Twiss parameters are shown inFigure 6 illustrating the Beam Piece Window. There is aButton Bar at the top of the window, two tab panels forparameter inputs (Beam and Centroid Parameters) and aset of dynamic phase space ellipse plots. The Centroid tabpanel of the Beam Piece is not used by TRANSPORT.However, PBO Lab does provide a Centroid Piece that issupported by TRANSPORT. The Particle Distribution Typepop-up does not apply to TRANSPORT but the BeamParameters pop-up is used to select between the Semi-Axesand Courant-Snyder (Twiss) beam parameter sets.

Transverse and Longitudinal Phase Space Ellipse Plots are Provided for Beam Parameters

Select between Semi-Axes or Courant-Snyder (Twiss) Beam

Parameter Representations

The Tutorial Button Opens the Beam Piece Tutorial window, which Provides a Variety of

Information on Beam Parameters

Green Dots Indicate which Parameters will be used to Generate the Native Inputs

for TRANSPORT

Open the TRANSPORT Correlations Matrix Window with Semi-Axes Parameters Selected

Compute Semi-Axes Parameters from Twiss Parametersor Compute Twiss Parameters from Semi-Axes

Auto-Scale Phase Space Ellipse Plots or Set the

Plot Scales Directly

Figure 6 Semi-Axes and Twiss Beam Piece Parameters.

The Centroid Piece can be used toshift the centroid trajectory of thebeam, relative to the referencetrajectory, or axis, of the beamline.

The Beam Parameters pop-up is usedto select between the two independentparameter sets for Semi-Axes orCourant-Snyder beam representations.


18

The two different beam parameter sets (Semi-Axis andTwiss) are independent, although one set may becalculated from the other. When the Twiss BeamParameters are selected, the Compute From Semi-Axesbutton will calculate the equivalent Twiss parameters forthe current Semi-Axes parameters. When the Semi-Axesparameter set is selected the Compute From Twiss buttonwill calculate the equivalent Semi-Axes parameters forthe current Twiss parameters. The Compute From... buttonis in the Button Bar at the top of the Beam Piece Window.

When Semi-Axes Beam Parameters are selected,correlations may be included in the beam description usingthe Correlations button in the Button Bar of the BeamPiece Window. The Correlations button opens theCorrelation Matrix Window shown in Figure 7.Correlations may be entered directly as off-diagonalelements of the Sigma Matrix, or by entering values forthe Reduced Sigma Matrix. The radio buttons at the topof the window toggle between these two modes.Corresponding values are calculated for the inactiveselection using the inputs from the active selection.

Radio buttons are used to select between the Sigma Matrix or the

Reduced Sigma Matrix inputs

Figure 7. TRANSPORT Correlation Matrix Window.

The two different beam parametersets are independent, although oneset may be calculated from the other.

The green dots to the right ofindividual parameters in the PieceWindows indicate which will be usedto generate TRANSPORT input.

The Semi-Axes beam representationincludes a correlation matrix in thebeam description.

The Beam Correlations Matrix Windowis opened with the Correlations buttonin the Beam Piece Window.

Correlations may be entered directlyas off-diagonal elements of theSigma Matrix, or by entering valuesfor the Reduced Sigma Matrix.


19

The Beam Piece Window includes dynamic phase spaceellipse plots for the current beam parameters. The top plotshows the horizontal (red) and vertical (blue) transversephase space ellipses. The bottom plot is the longitudinal(green) phase space ellipse. The axis scales for the phasespace ellipse plots can be calculated automatically withthe Auto Scale Plots button in the Button Bar at the top ofthe window or the scales may be set directly by the userwith the Set Plot Scale button.

The Tutorial button in the Button Bar at the top of theBeam Piece Window opens the PBO Lab Tutorial for theBeam Piece and leads to the Hypertext Tutorial shown inFigure 8. The Beam Piece Tutorial provides a variety ofuseful information including descriptions of the beamSigma Matrix, Semi-Axes and Twiss parameterrepresentations, phase space projections, the beamcentroid and several other related topics.

The Beam Piece Window includesphase space ellipse plots for thecurrent Beam Parameters.

The Beam Piece Tutorial provides avariety of useful information onmodeling beams in TRANSPORT.

Figure 8. PBO Lab Beam Piece Tutorial Windows.


20

Marker PieceThe Marker Piece is a special PBO Lab Piece that is usedto specify application-specific Constraints, Diagnosticsand Stored Parameters at specific locations in the beamlinemodel. An example of the Marker Piece Window is shownin Figure 9.

Marker and Final Pieces

Open a TRANSPORT Stored Parameters Window

Open a TRANSPORT Fitting ConstraintsWindow

Open a TRANSPORT DiagnosticsWindow

TRANSPORT Application Context

The Marker Piece is used to Specify Application-Specific Constraints and

Diagnostics at the Location of the Marker Piece in the Beamline Model

Figure 9. Marker Piece Constraints, Diagnostics and Stored Parameters.

There are three scrollable lists in the Marker Piece Windowthat display selected Constraints, Diagnostics and StoredParameters for installed Application Modules. The examplein Figure 9 has Constraints specified for both theTRANSPORT and MARYLIE Application Modules.Diagnostics have been selected for TRANSPORT andTURTLE. Stored Parameters are specified for TRANSPORTonly. Application-specific windows, tailored to the particularcapabilities of each Application Module, are used to specifyConstraints, Diagnostics and Stored Parameters.

Marker Piece

The Marker and Final Pieces may beused to specify locations in thebeamline where a Constraint is to bebe imposed, Diagnostic data is to beoutput or Stored Parameter data isto be collected.


21

The Application Context pop-up mustbe set for TRANSPORT in order toopen the TRANSPORT windows forConstraints, Diagnostics and StoredParameters.

The Application Context must be set for TRANSPORT to Open the

Constraints, Diagnostics and Stored Parameters Windows

Figure 10. Location Specific Constraints, Diagnostics and Stored Parameters.

The Open buttons in each panel of the Marker PieceWindow are used to open the application-specific windowsfor the current Application Context. In order to open theTRANSPORT application-specific windows forConstraints, Diagnostics and Stored Parameters theApplication Context pop-up must be set forTRANSPORT as illustrated in Figures 9 and 10 TheApplication Context can be set in either the DocumentWindow or directly in the Marker Piece Window.


22

Location-Specific ConstraintsThe Open button in the Constraints panel opens theTransport Fitting Constraints Window as illustrated inFigure 10. Refer to the Transport Fitting Chapter for adescription of using the Marker Piece for location specificfitting constraints.

Location-Specific DiagnosticsThe Open button in the Diagnostics panel of the MarkerPiece Window opens the Transport Location MarkerWindow. This window, shown in Figure 11, is tailored tothe particular capabilities of TRANSPORT for generatingoutput for specific locations in the beamline model. Thereare three panels in the window for selecting various optionsat the location of the Marker Piece in the beamline model.The Print panel provides a variety of diagnostic outputoptions that will result in location-specific data written tothe Transport Output file. The Misalignment andInitialization panels have options for location-specificcommands that are used for misalignment and re-initialization of the R1 and/or R2 transfer matrices.

The Marker Label (Comment) is entered in the text field at the bottom of the window

A check box is also provided to use the Label as a Reference Marker in the Transport Input File

The Transport Location Marker Window, opened from the Diagnostics Panel in the Marker Piece Window, includes panels

for Print Options as well as Misalignment and Initializations

Figure 11. Transport Location Marker Window.

Refer to the TRANSPORT FittingChapter for a description of using thePBO Lab Marker Piece for thespecification of TRANSPORT FittingConstraints.

Many of the Print options in theTransport Location Marker Windowcan also be selected in theTransport Options Window for theend of the beamline model or afterevery element in the beamline.


23

Location-SpecificStored Output Parameters

The Open button in the Store panel of the Marker PieceWindow opens the Transport Stored Parameters Windowshown in Figure 12. This window is used to specify thestorage of TRANSPORT parameters at the location of theMarker Piece in the beamline model. Stored Parametersare shown in the TRANSPORT Output file and can alsobe used in Algebraic Parameter Expressions or in FittingConstraint Expressions.

It is not necessary to know all of the TRANSPORTkeywords, the Stored Parameters Window provides userfriendly controls for selecting any applicableTRANSPORT output parameters.

Refer to Table 5 in theTRANSPORT Fitting Chapter for a listof TRANSPORT keywords.

Refer to the “TRANSPORT UserManual” for a description ofindividual output parameters that canbe stored.

A complete range of matrix elements can be selected with the

radio buttons and the matrix panel.

The application-specific Keyword is generated by the user interface

when a selection is made.

The symbolic name for Stored Parameters can be

specified by the user.

Figure 12. TRANSPORT Stored Parameters Window.


24

To specify a Stored Output Parameter, enter a symbolicparameter name in the Storage Name input field at thetop of the window. Stored Parameter Names should beunique. They should not be identical to any ParameterNames that have been defined for special parametersettings or other Stored Parameters. Note that creating acopy of a Marker Piece will also copy any StoredParameters that have been defined for that Piece. This willresult in duplicate Stored Parameter Names on the twoMarker Pieces. The duplicate names will be sent toTRANSPORT but the value for the first parameter willbe overwritten when the second parameter is encountered.

After a Storage Name has been entered, a TRANSPORToutput parameter can be selected from the five differentmatrices or the four pop-up controls. To select a matrixelement, first select the radio button for the desired matrix:Beam Matrix, Correlation Matrix, R-Matrix, T-Matrix orU-Matrix. Then a matrix element can be selected byclicking on the desired element in the matrix panel. TheR-, T-, and U-Matrices also have pop-up controls to choosebetween Regular or Auxiliary matrices. The T- and U-Matrices have pop-ups for the additional dimensions ofthese matrices. The matrix panel is used to select elementsfor all of the matrices and it will reflect the correspondingelements when a matrix radio button is selected. After aselection has been made, use the Accept button to add itto the storage list at the bottom of the window.

In addition to matrix elements, there are four pop-ups thatmay be selected from: Beam Envelope and Beam Centroidparameters, Lattice Functions and Floor Coordinates.After a selection has been made from any of these pop-ups, the Accept button is used to add it to the storage listat the bottom of the window.

All of the special parameter settings for a PBO Labbeamline model, including any Stored Parameterspecifications, are saved using the Save or Save Ascommands in the File Menu of the Document Window.

To Store a TRANSPORT OutputParameter, enter a unique parametername in the Storage Name input fieldand select the Output Parameter withthe controls provided in the StoredParameters Window.

Copying Marker Pieces with StoredParameters will duplicate ParameterNames and may result in unintendedconsequences.

Stored Output Parameters can beselected from the five differentmatrices or the four pop-up controlsin the Stored Parameters Window.

Stored Output Parameters are savedwith the beamline model document.


25

Stored Parameters List WindowPBO Lab provides application-specific interactive ListWindows that organize related data for the entire beamlinemodel. The Stored Parameters List Window contains alist of location-specific Stored Output Parameters. Figure13 illustrates opening the Stored Parameters List Windowfrom the List Windows Submenu in the TRANSPORTCommands Menu.

The Stored Parameters List Window can be used to quicklyaccess Marker and Final Pieces with user-specified StoredParameters. Double-clicking an entry in the window willopen the associated Marker (or Final) Piece Window inthe beamline model.

To resize a column in a List Window, place the mouseover the divider line in the column header. When the arrowturns into a cross-hair, resize by holding the mouse buttondown while dragging horizontally.

All of the user-specified StoredOutput Parameters can be accessedfrom a convenient List Window.

Double-click an entry in the ListWindow to open the associatedMarker (or Final) Piece Window in thebeamline model.

The header at the top of the ListWindow can be used to adjust thewidth of each column in the window.

Figure 13. Opening the List Window for Stored Output Parameters.


26

Parameter PiecePBO Lab provides a Parameter (Param) Piece for userspecified model parameters. A Param Piece may beinserted anywhere in the beamline model as illustrated inFigure 14. A Param Piece may also be placed on the WorkSpace and referenced from Pieces in the beamline model.Each Param Piece can be used to specify up to eight userdefined parameters. The Param Piece supports SpecialParameter Settings that are accessed with the “S” buttonsto the left of each parameter in the Param Piece Window.

Parameter (Param) Piece

Param Pieces may be placed in theModel Space or the Work Space.Param Piece Parameters can then bereferenced from Pieces in thebeamline model.

Each Param Piece Supports up to eight user defined Parameters

Double-Click the Param Piece Icon in the Document Window to

Open the Param Piece Window

A Param Piece may be Placed Anywhere in the Beamline Model

Figure 14. Parameter (Param) Piece Window.

The S-Buttons open Special Parameter Settings Windows(S-Windows) as illustrated in Figure 15. In the S-Window,a Param Piece Parameter may be defined as a numericalValue and used as a symbolic constant in ParameterAlgebraic Expressions. They may also be selected asFitting Variables or they may be specified by AlgebraicExpressions. However, unlike other beamline elements,the Param Piece requires a Symbolic Parameter Name tobe specified for each of the special parameter settings

Refer to the Section on SpecialParameter Settings in this Chapter.

Param Piece Parameters require aSymbolic Parameter Name to bespecified for each of the specialparameter settings options.


27

options. A Param Piece Parameter will only be written tothe Transport Input file if a Symbolic Parameter Namehas been specified in the S-Window.

The Transport Tab Panel in the Special Parameter Settings Windows (S-Windows)

is used to specify a Param for Transport

The Parameter Name for a Defined Param may be used anywhere in the Beamline Model to Define Algebraic Parameter

Expressions for other Piece Parameters

A Symbolic Parameter Name must be Defined in the S-Window in order to use a Param Piece Parameter with Transport

Figure 15. Param Piece Special Parameter Settings.

A Param Piece Parameter may also be selected as anImport Parameter in the Special Parameter SettingsWindow. Refer to the External Data Interface Section inthe main PBO Lab User Manual for a description of ImportParameters.

The Special Parameter Settings Chapter describes the S-Window in more detail.

Avoid using a Symbolic ParameterName that is the same as a PieceComment. This can cause unintendedconsequences when runningTRANSPORT.


28

Matrix PieceThe PBO Lab Matrix Piece is supported by theTRANSPORT Application Module and provides a meansto represent any arbitrary transformation matrix. First-,Second- and Third-Order matrix elements may bespecified directly in the Matrix Piece Window, which isillustrated in Figure 16 below. Alternatively, PBO Lab canuse TRANSPORT to calculate the transfer matrix for aselection of one or more Pieces in the beamline model orfor the entire beamline.

Matrix Piece

The Radio Buttons and Pop-up Controls at the top of the Matrix

Piece Window provide access to the First-Order R-Matrix, Second-Order T-Matrix and Third-Order U-Matrix

Individual Matrix Elements can be edited directly in the Matrix Panel

Figure 16. Matrix Piece Window.

Radio buttons at the top of the Matrix Piece Window areused to toggle between the R-Matrix, T-Matrix and U-Matrix displays. The R-Matrix represents the First-Ordertransfer matrix R(i,j), displayed in meters and inversemeters. When the T-Matrix radio button is selected, theSecond-Order matrix T(i,j,k), is displayed. The elementsof the T-Matrix have an additional index that is selectedwith the pop-up to the right of the T-Matrix radio button.The Third-Order U-Matrix U(i,j,k,l), is selected with theU-Matrix radio button and has two additional dimensionsthat are also selected with pop-up controls located to theright of the U-Matrix radio button. The pop-up controlsfor the T and U matrices are only activated when thecorresponding radio button has been selected.

The radio buttons and pop-upcontrols at the top of the Matrix PieceWindow provide access to the First-Second- and Third-Order transfermatrices.


29

A Matrix Piece can be placed in the beamline model oron the Work Space by dragging the Matrix Piece iconfrom the Palette Bar of the Document Window. The defaultMatrix Piece Parameters represent the identity matrix.Matrix elements can be entered directly into the MatrixPiece Window.

A Matrix Piece can be also be generated for a selection ofbeamline elements using the Create Matrix command. Aftermaking a selection of Pieces in the beamline model, use theCreate Matrix command in the TRANSPORT CommandsMenu to generate a Matrix Piece on the Work Space thatrepresents the selected beamline elements. Refer to the CreateMatrix Command Section in Chapter 6: Displaying andCreating Matrices.

The Matrix Piece may be useful for speeding upTRANSPORT calculations for very large beamlinemodels. For example, in a typical fitting calculation (Referto Chapter 9: TRANSPORT Fitting) only a few Pieceswill have Variable Parameters specified. The other staticparts of the beamline may be replaced by Matrix Piecesgenerated as described in the preceding paragraph.

A Matrix Piece can also be generated for the entirebeamline model from the Transport R-Matrix Window.After executing TRANSPORT the Show R-Matrixcommand will open the R-Matrix Window and the CreateMatrix button will generate a Matrix Piece representingthe entire beamline. Refer to the Creating a Matrix PieceSection in Chapter 6: Displaying and Creating Matrices.

PBO Lab provides an Output File Option in theTRANSPORT Options Window that causesTRANSPORT to generate the transverse matrixcomponents in millimeters and milliradians. This mixedunits representation will only appear in the TransportOutput File when this option is selected. The Matrix PieceWindow will always display the matrix data in metersand inverse meters regardless of the TRANSPORT OutputFile Option.

An arbitrary transfer matrix can bedefined directly in the Matrix PieceWindow.

A Matrix Piece can be generated fora selection of one or more elementsin the beamline model.

A Matrix Piece can be created for theentire beamline after executingTRANSPORT.

The Matrix Piece Window displays thetransfer matrices in units of meters,radians and inverse meters, radiansregardless of the TRANSPORT OutputFile Option.

Matrix Pieces may be used to replacestatic sections of a large beamline. Ifacceleration elements are in thebeamline, Special Pieces may need tobe added to change the beam (P0)or reference (PREF) momentum. Referto the following Section for adiscussion of the Special Piece.


30

Special PieceThe PBO Lab Special Piece is used by theTRANSPORT and TURTLE Application Modules. TheSpecial Piece Window, shown in Figure 17, contains fivetab panels. The first four tab panels are used exclusivelyfor TRANSPORT. The fifth tab panel is used for theTURTLE Application Module.

Special Piece

The Special Piece is provided for the definition of location specific Special Parameters that can be used to change

TRANSPORT System, Floor Coordinate, Fringe Field and Expansion Parameters

Figure 17. Tab Panels in the Special Piece Window.

The Special Piece is provided for the definition of locationspecific special parameters that can be used to changeTRANSPORT System, Floor Coordinate, Fringe Field andExpansion Parameters. Table 2 list the Special Parametersand the corresponding TRANSPORT keywords.


31

Table 2. Special Piece Parameters and Keywords.

Special Piece Parameter TRANSPORTKeyword

System ParametersSystem Length LENGTHReference Trajectory Momentum P0Magnetic Field Reference Momentum PREFParticle Mass PMASSTilt to Focal Plane FOTILTFloor Coordinate ParametersHorizontal Location XBEGINVertical Location YBEGINLongitudinal Location ZBEGINY-Axis Angle YAWX-Axis Angle PITCHFringe Field ParametersHorizontal Half-Width HWIDTHHalf Pole Spacing HGAPOrbit Displacement Integral FINT0Fringe Field Factor K1 FINTFringe Field Factor K2 FINT2Entrance Pole-Face Curvature H1Exit Pole-Face Curvature H2Expansion ParametersSecond-Order Field EPSThird-Order Field EPS3Excess Field Fraction RMPSField Scaling Factor RNMSVertical Dipole Factor VRVertical Gradient Factor NPVertical Sextupole Factor EPSP

The Special Piece can be placed anywhere in the beamlineby dragging the icon from the Palette Bar of the DocumentWindow and inserting it at the desired location in the beamlinemodel. Special Pieces on the Work Space are ignored whengenerating special instructions (SPEC cards) in theTRANSPORT input file. Special Pieces must precede anyelement(s) to which they apply. Once a Special Parameterhas been defined at a specific location in the beamline, itwill apply to all succeeding elements of the appropriate typeunless reset to a new value.

Special Pieces must precede anyelement(s) to which they apply. Oncea Special Parameter has been definedfor a location in the beamline model,it will apply to all succeedingelements that are the appropriatetype unless reset to a new value.

PBO Lab will only use SpecialParameters that have been definedby a Symbolic Parameter Name in theparameters’ Special ParameterSettings Window.

Note that the Fringe Field Factor K2(FINT2) is no longer used byTRANSPORT, but is included forcompatibility with older versions.

Refer to the “TRANSPORT UserManual” for a description ofindividual special parameters.

Special Pieces on the Work Spaceare ignored when generatingspecial instructions (SPEC cards) inthe TRANSPORT input file.

A single Special Piece may be used to define multipleSpecial Parameters for a specific location in the beamline.Multiple Special Pieces can also be placed at differentlocations in the beamline to redefine a single SpecialParameter. However, PBO Lab will only use SpecialParameters that have been defined by a Symbolic ParameterName in the parameter’s Special Parameter SettingsWindow, as illustrated in Figure 18. Special Parametersshould be defined with unique Parameter Names,particularly when the same Special Parameter is defined atdifferent locations in the beamline model, otherwise thelast non-unique Parameter Name and Value will be usedfor each Special Parameter defined by that Name. Copyinga Special Parameter Piece will also copy any SpecialParameter Settings including Symbolic Parameter Names.When a Special Piece is copied, care should be taken toassign unique Symbolic Parameter Names.

Only Special Parameters that havebeen defined by a SymbolicParameter Name in the parameters’Special Parameter Settings Windowwill be used by TRANSPORT.

Copying Special Pieces wil lduplicate any Symbolic ParameterNames and may result inunintended consequences.

Special Parameters must be defined by a Symbolic Parameter Name in the Special

Parameter Settings Window that is accessed using the parameter's "S-Button"

Figure 18. Defining a Symbolic Parameter Name for a Special Parameter.

Refer to the following Chapter for a description of theSpecial Parameter Settings Window.


32

PB

O L

abT

M

2.0

PB

O L

abT

M

2.0

Special Parameter Settings



33

Refer to the Piece Window Sectionin the PBO Lab User Manual for acomplete description of the PieceWindow user interface.

Access Special Parameter SettingsWindows with the S-Button to theleft of the desired parameter in thePiece Window.

4. Special Parameter SettingsMany Piece Parameters support application-specificspecial parameter settings that are accessed with theSpecial Parameter Settings Buttons (“S-Buttons”) locatednext to each parameter in PBO Lab Piece Windows. TheS-Buttons open a Special Parameter Settings Window (“S-Window”) for the associated Piece Parameter.

To access special parameter settings, select theTRANSPORT Application Context in the DocumentWindow Button Bar and open a Piece Window by double-clicking the Piece icon on the Work Space or Model Space.Then click on the S-Button for the desired parameter asillustrated in Figure 19 below.


35

Special Parameter Settings are accessed with the Special Parameter Settings (“S”) Buttons located next to each parameter in PBO Lab Piece Windows

Double-Click Piece Icons to Open Individual Piece Windows

Select the TRANSPORT Application Context in the Document Window Button Bar

Figure 19. Opening a Special Parameter Settings Window.


36

Many PBO Lab Pieces have multiple parameter sets thatcan be used to specify input parameters. The differentparameter sets are accessed with a pop-up control at thetop of the Piece Window. The S-Buttons will be inactivefor parameters that are not included in the currentparameter set. For example, in the Quadrupole PieceWindow shown in Figure 19, the Quadrupole Strengthpop-up specifies the Field Gradient parameter set. Onlythe three native TRANSPORT parameters for this set(Length, Field Gradient and Roll Angle) can be selectedfor special parameter settings. The native parameters areindicated with green dots on the right edge of the PieceWindow. In order to select special settings for the ApertureRadius parameter, the Field and Aperture parameter setneeds to be selected in the Quadrupole Strength pop-up.Refer to the Piece Window Section in the main PBO LabUser Manual for a description of multiple parameter sets.

The bottom half of the S-Window contains tab panels thatprovide access to application-specific options for thedifferent PBO Lab Application Modules. Your S-Windowswill include tab panels for any installed ApplicationModules. However, some Application Modules may notsupport special settings for a parameter and therefore willnot have a tab panel in the S-Window.

When the TRANSPORT Application Module is installed,there will be a Transport tab panel in the Special ParameterSettings Window if that parameter is a nativeTRANSPORT input and it is supported as a Fitting Variableor Algebraic Expression by the TRANSPORT program.Otherwise there will not be a Transport tab panel in the S-Window.

Special Parameter Settings are saved with the beamlinemodel document. The special parameter settings forTRANSPORT include selecting a parameter as a FittingVariable or defining a parameter with an AlgebraicExpression or selecting it as an Import Parameter. Referto the Transport Parameter Settings Section in this Chapterfor a description of the different parameter settings.

Special parameter settings will beinactive for parameters that are notin the selected parameter set.

Special Parameter Settings Windowscontain tab panels for the installedPBO Lab Application Modules.

Special Parameter Settings areavailable for native TRANSPORTinputs that are supported as FittingVariables or Algebraic Expressions.

All of the special parameter settingsfor a PBO Lab beamline model aresaved from the Document Windowwith the Save or Save As commandsin the File Menu.


37

Creating a copy of a Piece with special parameter settingswill also copy those settings. For example if a PieceParameter is defined by a user-specified Parameter Nameand that Piece is copied in the beamline, then there wouldbe two parameters defined by the same Parameter Name.Both instances of the Parameter Name will be sent toTRANSPORT but the value for the first parameter will beused when the second parameter is encountered. This isalso true for the initial values of Fitting Variables definedwith identical Parameter Names. If there are duplicateFitting Variable Names then the initial value of the firstinstance will be the initial value for all instances of theVariable with the same Symbolic Name. Copying Piecesthat have Parameter Algebraic Expressions will duplicatethose expressions on the copied Piece but otherwise presentno difficulties. In some cases, it is desirable to use multiplePieces with parameters that are defined by the sameParameter Name. However, if this is not the desired result,the Parameter Name will need to be changed to a uniquename after making a copy of a Piece that includes specialparameter settings. An alternative to copying Pieces thatare to be represented with parameters that are defined withthe same special parameter settings is to create an AliasPiece. An Alias Piece will maintain a persistent link to theoriginal Piece so that any changes to the original areautomatically reflected in the Alias. The Alias Piece alsosupports user specified deviations from the original Pieceparameters without duplicating redundant data. Refer tothe Alias Piece Section in the main PBO Lab User Manualfor a discussion of Alias Pieces.

Copying Pieces with specialparameter settings will duplicateParameter Names and may result inunintended consequences.

An alternative to copying a Piece isto create an Alias Piece that willmaintain a persistent link with theoriginal Piece and will automaticallyreflect any changes in the originalPiece Parameters.


38

Symbolic Parameter NamesThe top panel of the S-Window (Figure 20) is application-independent and displays the Piece Comment (Label)along with the name of the selected parameter. TheSymbolic Parameter Name input field is application-independent and provides for a user-specified SymbolicParameter Name to be defined for the parameter. Whenrequired, a default Parameter Name will be generated if aname has not been entered in the field at the top of the S-Window. The same Parameter Name is used for allinstalled Application Modules.

The Parameter Name specified in thetop panel of the S-Window isapplication-independent. The sameParameter Name is used for allinstalled Application Modules.

Using a Symbolic Parameter Namethat is identical to a Piece commentmay cause unintended results.

Application-Specific Special Parameter Settings for TRANSPORT

are in the Transport tab panel

A User-Specified Symbolic Parameter Name is also defined in

the top panel of the S-Window

The Application-Independent top panel of the S-Window displays the User Specified Piece

Comment (Label) and the Name of the selected parameter (e.g. "Magnetic-Field Gradient")

Figure 20. Special Parameter Settings Window.

A Symbolic Parameter Name is required when the parameteris selected as a Fitting Variable or Import Parameter in theTransport tab panel. However, Parameter Names can also beused for defining other parameters in terms of the namedparameter even though the named parameter may not beselected as a Fitting Variable, i.e. the parameter is treated asa numerical constant defined by a symbolic name. When aParameter Name has been specified, there will be a red “S”on the S-Button in the Piece Window and the Parameter Namemay then be used in Parameter Algebraic Expressions forother Piece Parameters.

Parameter Names can be used inParameter Algebraic Expressionsspecified for other Piece Parameters asdescribed in the Parameter AlgebraicExpressions Section of this Chapter.

Symbolic Parameter Names used inthe beamline model sould be unique.To define multiple parameters withthe same value, define oneparameter with a unique name anddefine the other parameters asAlgebraic Expressions of that name.


39

Transport Parameter SettingsThe Transport tab panel in the Special Parameter SettingsWindow has four radio buttons for specifying theassociated parameter as: a numerical Value, a FittingVariable, an Algebraic Expression or an Import Parameter.These choices are exclusive. A parameter can only bedefined by one of these special parameter settings,although the same Symbolic Parameter Name is used forall settings and for all Application Modules.

The first radio button in the Transport tab panel is thedefault selection. It indicates that the parameter is definedby the numerical Value entered in the Piece Window, i.e.there are no special settings currently selected for theparameter. The parameter may be defined with a SymbolicParameter Name, although it is not required for thisselection. If a Parameter Name is defined then that namewill be used to create a symbolic constant in the TransportInput file. The parameter will be defined with thatParameter Name and the Name may then be used to defineAlgebraic Expressions for other Piece Parameters.

The second radio button in the Transport tab panel selectsthe parameter as a Transport Fitting Variable using theSymbolic Parameter Name as described in theTRANSPORT Fitting Chapter of this Supplement.

The third radio button selects the parameter as anAlgebraic Expression. With this selection, the input fieldand pop-up to the right of the radio button are activated.The following Section describes the use of ParameterAlgebraic Expressions.

The last radio button in the Transport tab panel selects theparameter as an Import Parameter. This selection works inconjunction with the PBO Lab External Data InterfaceTools. The import option is not specific to TRANSPORT,but selecting an Import Parameter excludes that parameteras a Fitting Variable or Algebraic Expression. Refer to theExternal Data Interface Section in the PBO Lab UserManual for a description of Import Parameters.

Parameters that have been givenSymbolic Parameter Names aredefined with those Names in theTransport Input file even when theParameter has not been selected asa Fitting Variable or an AlgebraicExpression.

Refer to the Fitting Chapter in thisSupplement for a discussion of FittingVariables.

Refer to the following Section for adescription of Parameter AlgebraicExpressions.

Refer to the External Data InterfaceSection in the main PBO Lab UserManual for a description of the ImportParameter special parameter setting.


40

Parameter Algebraic ExpressionsThe TRANSPORT Application Module supports thedefinition of Piece Parameters using AlgebraicExpressions. Parameter Algebraic Expressions arespecified in the Special Parameter Settings Window. Todefine an Algebraic Expression for a Piece Parameter,select the corresponding radio button in the parameters’Special Parameter Settings Window as illustrated in Figure21. With this selection, the input field and pop-up to theright of the radio button are activated. An algebraicexpression is entered in the input field, which will thenbe used to define the parameter in the Transport Inputfile. The pop-up to the right of the input field contains alist of all the Piece Parameters in the beamline model thathave been given Symbolic Parameter Names in additionto Location Specific Stored Parameters. A ParameterAlgebraic Expression can be defined in terms of theseSymbolic Parameter Names as well as otherTRANSPORT program variables and symbolic constants.Note that a Parameter Algebraic Expression is notevaluated when it is defined in the S-Window. AlgebraicExpressions are evaluated when TRANSPORT executed.

Selecting the Algebraic Expression radio-button will activate the input

field and pop-up control

A convenient pop-up is provided that contains all of the Named

Parameters in the Beamline Model

Symbolic Parameter Names are not used for Parameter Algebraic Expressions

Figure 21. Parameter Algebraic Expressions.

Symbolic Parameter Names may bedefined for Piece Parameters, asdescribed in the previous Sections,and used in Algebraic Expressions forother Piece Parameters.

Parameter Algebraic Expressions arenot evaluated until TRANSPORT isexecuted.

Symbolic Parameter Names are notused for Piece Parameters definedwith Algebraic Expressions.


41

Parameter Algebraic Expressions may be defined in termsof user-specified Parameter Names, Fitting Variables, StoredParameters and may also contain TRANSPORT symbolicconstants including those listed in Table 3 below.

Table 3 TRANSPORT Symbolic Constants.

TRANSPORT NumericalKeyword Value Units

PI 3.12159265358979323

TWOPI 2.0*PI

DEGRAD 180.0/PI

RADDEG PI/180.0

E 2.718281828459045

EMASS 0.510099906E-03 GeV

PMASS 0.93827231 GeV

CLIGHT 2.99792458E+08 m/s

MTOIN 0.0254

INTOM 1.0/MTOIN

Additional symbolic constants can be defined by the userwith the Param Piece (refer to the Parameter Piece Sectionin this Chapter). User-specified Parameter Names shouldnot use the names that are reserved by TRANSPORT forsymbolic constants.

There are a variety of mathematical operators and functionsthat can be used in Parameter Expressions. These are listedin Table 4 with the TRANSPORT keyword or symbol.

Table 4 Operations for Algebraic Expressions.

Keyword- Operation Keyword- OperationSymbol Symbol

+ Addition * Multiplication

- Subtraction / Division

SIN Sine COS Cosine

SINH Hyperbolic Sine COSH Hyperbolic Cosine

ASIN Inverse Sine ACOS Inverse Cosine

SQRT Square Root ALOG Natural Log

EXP Exponential

Named Piece Parameters, FittingVariables and Stored Parameters maybe used to define ParameterAlgebraic Expressions.

Parameter Algebraic Expressions mayinclude TRANSPORT symbolicconstants. Additional symbolicconstants can be defined by the userwith the Param Piece.

A variety of mathematical operatorsand functions may be used inParameter Algebraic Expressions.


42

Algebraic Expressions specified by theuser are saved even when theparameters are not set to use theexpression.

The Parameter Named "DL1" and the Fitting Variable: "LD2" are used to

define an Algebraic Expression for the Effective Drift Length Parameter for

the Drift Piece labled "DRFT-3"

The Effective Drift Length Parameter for the Drift Piece Labeled "DRFT-1"

has been assigned the Symbolic Parameter Name: "LD1"

The Drift Length Parameter for the Drift Piece Labeled "DRFT-2" has been

assigned the Symbolic Parameter Name: "LD2" and it has been selected

as a TRANSPORT Fitting Variable

This Pop-up provides a quick reference of all of the user-defined Parameter

Names for the entire Beamline Model

Figure 22. Parameter Algebraic Expressions.

All of the special parameter settings for a PBO Lab beamlinemodel are saved from the Document Window using theSave or Save As commands in the File Menu. An AlgebraicExpression for a parameter will be saved with the beamlinemodel document even when it is not selected in the SpecialParameter Settings Window. For example, you may definea parameter with an Algebraic Expression and runTRANSPORT to evaluate the expression. You could thenupdate the beamline model and change the specialparameter setting to use that value instead of havingTRANSPORT reevaluate the Algebraic Expression on eachexecution. The expression will still be saved with thebeamline model even though it is not active.


43

Figure 22 on the previous page illustrates a simple exampleof a Parameter Algebraic Expression. The first S-Windowdefines a Parameter Name: “LD1” for the Effective Lengthof a Drift Piece. The second S-Window defines anotherDrift Length parameter with the Parameter Name: “LD2”,which is selected as a TRANSPORT Fitting Variable. Thelast S-Window in Figure 22 defines one more Drift LengthParameter as an Algebraic Expression of NamedParameters. The value of this parameter will be calculatedby Q ANSPORT using the algebraic expression: (LD1 +LD2) / 2.

Updating Parameter ExpressionsParameter Algebraic Expressions are evaluated whenTRANSPORT is executed. The resulting values arepresented in the PBO Lab Update Window following theexecution of TRANSPORT. The Update Window, shownin Figure 23, provides options to individually updateselected parameters or to update all of the parameters atonce. The Update Window also contains an update panelfor any Parameters used as Fitting Variables. There areseparate Update Buttons for Variable Parameters andParameter Expressions in the Update Window. Both theVariable Parameters and Parameter Expressions panelshave scroll bars to access additional entries that may notbe visible. Fitting Variables are described in Chapter 9:TRANSPORT Fitting.

The Expression Parameters panel in the Update Windowhas six columns. The user-specified Piece Label(Comment) is in the first column, the second columncontains the name of the parameter as it appears in thePiece Window. The third column contains the ParameterAlgebraic Expression. The Value column contains thecurrent numerical value of the parameter and the Updatecolumn contains the new value computed byTRANSPORT, which will be assigned when the parameteris updated in the beamline model. If a parameter is notspecifically updated, then the original value will beunchanged in the beamline model. The last column showsthe units for each parameter.

Parameter Algebraic Expressions areevaluated when TRANSPORT isexecuted. An Update Window isautomatically opened for modifyingParameter Expression Values in thebeamline model.

Refer to Chapter 9: TRANSPORTFitting for an explanation of FittingVariables in the Update Window.

If a Parameter Algebraic Expressionis not specifically updated in theUpdate Window, then the originalvalue will be unchanged in thebeamline model.


44

Scrolling List of User Specified

Fitting Variables

Scrolling List of User Specified Parameter

Algebraic Expressions

Update Only Selected Variable Parameters

Update All Variable Parameters in the List

Parameter Values Before and After Fitting

Evaluated Parameter Expressions

Click on a Parameter in the List to Select it for Update

Double Click a Parameter to Open its Piece Window

Update Any or All Evaluated Parameter

Expressions

Figure 23. Parameter Update Window.

Double-clicking a parameter in theUpdate Window will open theassociated Piece Window for thatparameter.

The Update Window is automatically opened afterexecution of TRANSPORT. The Variables andExpressions do not have to be updated immediately.However, if the Update Window is closed prior to updatingany parameters then TRANSPORT will have to be runagain to access the Update Window. The Update Windowcan be left open without updating parameters, in order toexamine other output results, and then parameters can beupdated in the beamline model by bringing the UpdateWindow to the foreground again. The Update Windowmay also be used to locate the Pieces in the beamlinemodel with Variable Parameters or Parameter Expressions.Double-clicking an entry in the Update Window will openthe associated Piece Window for the selected parameter.


45

Parameters & ExpressionsList Windows

PBO Lab provides application-specific interactive ListWindows that organize related data for the entire beamlinemodel. The Named Parameters List Window contains alist of Piece Parameters that have been given SymbolicParameter Names. Figure 24 illustrates opening theNamed Parameters Window from the TRANSPORTCommands Menu. The Named Parameters List Windowcan be used to quickly access Named Parameters. Double-clicking an entry in the window will open the associatedPiece Window in the beamline model.

PBO Lab provides application-specificinteractive List Windows thatorganize related data for the entirebeamline model.

The Named Parameters List Window is opened from the TRANSPORT Commands Menu.The List Window contains all the Named Parameters for the entire beamline model

An "X" in the Fit column indicates that the Parameter has been selected as a Fitting Variable. Clicking in

this column toggles the Fitting Variable selection

Double-clicking an entry in the Parameters Variables window will open the associated Piece window

A Param Piece can be generated for any selected Parameters in the List Window

using the Create Param Piece Button

Figure 24. Named Parameters List Window.


46

The header at the top of all List Windows can be used toadjust the width of each column in the window. To resizea column, place the mouse over the divider line in thecolumn header. When the arrow turns into a cross-hair,resize by holding the mouse button down while dragginghorizontally. The List Windows themselves can also beresized to accommodate the number of entries and desiredcolumn widths.

Any Named Parameters that are selected as TRANSPORTFitting Variables are indicated with an “X” in the Fitcolumn of the List Window as illustrated in Figure 24.Named Parameters can be easily selected (and unselected)as Fitting Variables by clicking in the “Fit” column of theList Window.

A Param Piece can be created for selected parameters inthe List Window by using the Create Param Piece Button.To create a Param Piece, select a parameter by clickingon the entry in the List Window. (Hold down the shift keyto select multiple parameters.) Then use the Create ParamPiece Button at the top of the window to generate a ParamPiece on the Work Space of the Document Window. PBOLab will automatically enter the Parameter Value in theParam Piece and the Symbolic Parameter Name in the S-Window for each parameter selected in the List Window.The Param Piece is described in the Parameter PieceSection of Chapter 3: Beamline Elements.

List windows include entries from Pieces in the ModelSpace and from the Work Space. This provides quickaccess to all Pieces that have special parameter settings.Pieces on the Work Space that have special parametersettings will also be included in the Transport Input file.This allows Pieces in the beamline model to referenceNamed Parameters from the Work Space in the definitionof Parameter Algebraic Expressions.

The header at the top of all ListWindows can be used to adjust thewidth of each column in the window.

Both Parameter Variables andTransport Fitting Variables arecontained in the Named ParametersList Window.

A Parameter (Param) Piece can becreated for selected parameters in theList Window by using the CreateParam Piece Button.

List windows include entries fromPieces in the Model Space and fromthe Work Space.


47

A List Window is also provided for Stored OutputParameters that have been specified with Marker Piecesat specific locations in the beamline model. The StoredParameters List Window supports features that are similarto the Named Parameters List Window and is opened fromthe List Windows Submenu in the TRANSPORTCommands Menu. Refer to the Stored Parameters ListWindow sub-section in the Marker Piece Section ofChapter 3: Beamline Elements.

PBO Lab also provides List Windows for ParameterAlgebraic Expressions and for Fitting ConstraintExpressions. These windows support the same featuresas the Named Parameters and Stored Parameters ListWindows and are also accessed from the List WindowsSubmenu in the TRANSPORT Commands Menu.

Figure 25 illustrates the Parameter Algebraic Expressionsand Fitting Constraint Expressions List Windows. Aswith the other List Windows, the window itself, as wellas individual columns, can be resized. Double-clickingan entry will open the associated Piece Window forAlgebraic Expressions and the associated Marker PieceWindow for Constraint Expressions. Refer to Chapter9: TRANSPORT Fitting for further description of theseList Windows.

PBO Lab also provides a List Windowfor location-specific Stored Parametersin the beamline model. The StoredParameters List Window is describedin a sub-section of the Marker PieceSection in Chapter 3: BeamlineElements.

PBO Lab also provides List Windowsfor Parameter Algebraic Expressionsand Fitting Constraint Expressions.

Double-clicking an entry in theParameter Algebraic Expressions ListWindow will open the associatedPiece Window for that parameter.

The Fitting Constraints List Window provides access to all of the TRANSPORT Fitting Constraint

Expressions for the entire beamline model

The Parameter Algebraic Expressions List Window provides access to all of the Parameter

Expressions for the entire beamline model

Figure 25. Parameter Expressions and Fitting Constraints List Windows.



48

PB

O L

abT

M

2.0

PB

O L

abT

M

2.0

TRANSPORT Menus



49

5. TRANSPORT MenusApplication-specific commands are accessed fromSubmenus in the PBO Lab Commands Menu and ViewMenu at the top of the Document Window. When theTRANSPORT Application Module is installed, both theCommands Menu and the View Menu will containSubmenus for the TRANSPORT application, in additionto any other installed PBO Lab Application Modules. ThisChapter includes an outline of the TRANSPORT Menus,as well as references to other Chapters in this Supplementthat provide more detailed descriptions of specific menucommands.

TRANSPORT Commands MenuThe TRANSPORT Commands Menu is illustrated in Figure26 and contains several options for specifying output andexecuting the TRANSPORT Application Module.

Submenus for the TRANSPORTApplication Module (as well as anyother installed PBO Lab ApplicationModules) are found in both theCommands and View Menus of theDocument Window.

Separate Commands for Generating and Editing the Transport Input File

and Executing TRANSPORT

Commands for Executing TRANSPORT and Setting Up Plot Specifications

Commands for Displaying the TRANSPORT R-Matrix and Sigma Matrix

Set Additional TRANSPORT Options and Output Parameters

Commands for Displaying User Named Parameters, Fitting

Variables, Stored Parameters, Parameter Expressions and

Fitting Constraint Expressions

Command for Creating a Matrix Piece from a beamline selection

Figure 26. PBO Lab Commands Menu for TRANSPORT Module.

The TRANSPORT Commands Menu is divided into sixgroups of commands. The first group contains the twoprimary commands for specifying output and runningTRANSPORT. The second group provides three additionalcommands for setting up and running Transport Input files.These are described in the following ExecutionCommands Section.

The Write Input & Run Transportcommand automatically creates andexecutes the Transport Input filewhich contains all the inputs requiredby TRANSPORT.


51


52

Execution CommandsThe first command in the Commands Menu is used to runTRANSPORT and the second command is used to specifyplot data output. The Write Input & Run TransportSubmenu provides two options that can be used to write aTransport Input file for the beamline defined on the ModelSpace and execute the TRANSPORT program.TRANSPORT reads and executes the instructionscontained in the MAD (Methodical Accelerator Design)formatted input file that is generated by PBO Lab. Figure1 in the Getting Started Chapter illustrates an exampleusing one of these commands.

The Write Input & Run Transport Submenu includes twooptions for running TRANSPORT as illustrated in Figure27. The first includes fitting and the second excludesfitting. The only difference between these two options isthat PBO Lab will include the FIT instruction in the nativeTransport Input file for the first case and will exclude theFIT instruction for the second case. This allows any fittingvariables and constraints that have been defined by theuser to remain part of the model, without actually havingto run the fitting procedure every time TRANSPORT isexecuted. Refer to the Chapter 9: TRANSPORT Fittingfor a description of setting up and executing aTRANSPORT fitting problem.

TRANSPORT is executed from theCommands Menu using the WriteInput & Run Transport Command.TRANSPORT reads and executes aninput file that is generated by PBOLab for the beamline in the ModelSpace of the Document Window.

The Write Input & Run TransportCommand provides two options thatcan be used to run TRANSPORT withor without Fitting.

TheWrite Input & Run Transport Command has options for running

TRANSPORT with or without Fitting

Figure 27. Write Input & Run Transport Submenu.


53

The Transport Plot Specification command opens theTransport Plot Specification Window, which is used toselect a variety of TRANSPORT output parameters thatwill be written to the Transport Plot file. The TransportPlot Specifications are discussed separately in the PlotSpecifications Chapter.

The second group of commands in the TRANSPORTCommands Menu contains items to assist the user indirectly editing the Transport Input file. With thesecommands, the native TRANSPORT input may begenerated from the PBO Lab beamline model withoutautomatically executing the TRANSPORT application.These commands are useful for implementingTRANSPORT instructions which may not be directlysupported by the PBO Lab user interface. Changes madeto the Transport Input file are not retained in the PBOLab model data and the Transport Input file will be overwritten with subsequent Write Input & Run or Write Input& View commands.

These commands can also be used to evaluate anyincompatibilities between TRANSPORT input files thatwere not generated with PBO Lab. For example, an olderTRANSPORT input deck can be pasted into the Text EditWindow that is opened with the View ‘Transport Input’ Filecommand. After saving the new Transport Input file withthe Save command in the Text Edit Window, this file canthen be executed with the Run ‘Transport Input’ Filecommand. PBO Lab will not generate a new input file whenusing this command, instead the current Transport Inputfile will be used to execute the TRANSPORT program.Any incompatibilities will be noted in the Transport Outputfile. The input can then be corrected before Importing thefile into PBO Lab in order to build a PBO Lab beamlinemodel from the native TRANSPORT deck.

Text files can also be edited by using the Open Scratch FileCommand in the View Menu of the Document Window.This command opens an empty Text Edit Window. TheOpen Command in the File Menu of the Text Edit Windowcan be used to open any existing text file.

The Plot Specification command isused to set up options for differenttypes of graphic output and must beset prior to running TRANSPORT.

The Transport Input file may be editedand saved by the user. TRANSPORTwill read and execute the edited file(errors and all!) when the Run‘Transport Input’ File command isselected.

PBO Lab will not generate a newinput file when using the Run‘Transport Input’ File command.Instead the current Transport Inputfile will be used to execute theTRANSPORT program.


54

The different commands that generate the Transport Inputfile and execute TRANSPORT result in a rapid data flowwhich is transparent to the user. Each of these commandsinvolves a few well defined steps which are summarized here.

(1.) Each time they are selected, the following PBO Labcommands write a new Transport Input file for thebeamline in the Model Space of the DocumentWindow, together with the Options settings, PlotSpecifications and Fitting Constraints:

Write Input & Run TransportWrite Input & View

The first command will automatically write theinput file and execute TRANSPORT. The secondcommand will write the input file and display it ina Text Edit Window.

(2.) The following PBO Lab command will open thethe most recent Transport Input file withoutgenerating new input from the beamline model:

View ‘Transport Input’ File

(3.) The following PBO Lab command executes themost recent Transport Input file, created by either(1.) or (2.) above:

Run ‘Transport Input’ File

The Transport Input file is not updated with any changesmade from the interface, this command simply executesan existing Transport Input file.

Other PBO Lab commands or beamline construction tasksmay also cause a Transport Input file to be generated, thusoverwriting any existing file. For example, creating a MatrixPiece from a selection of Pieces in the beamline modelwill cause an input file to be generated, overwriting anyexisting file. This input file is executed by TRANSPORTand any existing output files are overwritten as well. Allthis is transparent to the user. When the Make Matrix PieceCommand is selected, the Matrix Piece simply appears onthe Work Space of the Document Window.

When a Transport Input file isgenerated, the previous input file isoverwritten.

When TRANSPORT is executed, theprevious output files are overwritten.

If the Transport Input file does notexist, then the Run ‘Transport Input’File command will not generate anyoutput.

Some of the PBO Lab commands andbeamline construction tasks mayrequire a Transport Input file to begenerated, thus overwriting anyexisting file.


55

Matrix CommandsThe third and forth groups of commands in theTRANSPORT Commands Menu contain commands forcreating and displaying matrices. The first two commandsin the third group are used for displaying theTRANSPORT R-Matrix and Beam Sigma Matrix. Theforth group contains one command that is used to create aMatrix Piece for a selection of beamline elements. Thesecommands are described separately in Chapter 6:Displaying and Creating Matrices.

List Window CommandsThe fifth group of commands in the TRANSPORTCommands Menu contains commands for displaying userspecified Named Parameters, Parameter Expressions,Storage Parameters, Fitting Variables and FittingConstraints for the entire beamline.

The List Windows Submenu provides commands to openseveral PBO Lab List Windows as illustrated in Figure 28.Each of the List Windows organize related data for all ofthe Pieces in the beamline model and on the Work Space.

Commands for Creating andDisplaying Matrices are describedseparately in Chapter 6 of thisSupplement.

List Windows organize related datafor all of the pieces in the beamlinemodel and on the Work Space.

The List Windows Sub-Menu is accessed from the TRANSPORT Comands Menu

Figure 28. List Windows for TRANSPORT are Accessed from the List WindowsSubmenu in the TRANSPORT Commands Menu.


56

List Windows are provided for Stored Parameters, NamedParameters, Parameter Expressions and Fitting ConstraintExpressions. The Stored Parameters List Window isdescribed in the Marker Piece Section of the BeamlineElements Chapter. The Named Parameters List Windowand the Parameter Expressions List Window are describedin the Parameters and Expressions List Windows Sectionof the Special Parameter Settings Chapter. The FittingConstraint Expressions List Window is described inChapter 9: TRANSPORT Fitting.

Options CommandThe last group in the TRANSPORT Commands Menucontains one command. The Option Command is used toaccess TRANSPORT Options for the Order of Calculationand Output Result in addition to parameters for specifyingdata to be written to the Transport output files. Thesecommands are discussed separately in Chapter 7:TRANSPORT Options.

TRANSPORT View MenuThe View Menu in the Document Window containsSubmenus for any installed PBO Lab Modules. TheTRANSPORT Submenu is illustrated in Figure 29 andcontains several commands to open input, output,diagnostic and auxiliary files for the TRANSPORTApplication Module.

TRANSPORT Input File generated by PBO Lab and used to execute TRANSPORT

Standard TRANSPORT Output File

Plot Data File generated by TRANSPORT and used by PBO Lab Graph Plot Windows

TRANSPORT Punch and Data Output Files

Submenu for Auxiliary Files

Figure 29. PBO Lab View Menu for TRANSPORT Module.

List Windows are provided for StoredParameters, Named Parameters,Parameter Expressions and FittingConstraint Expressions.

The TRANSPORT Options Window isdescribed in Chapter 7: TRANSPORTOptions.

The TRANSPORT Submenu in theView Menu of the DocumentWindow contains several commandsto open TRANSPORT I/O files.


57

The View Menu commands do not execute TRANSPORTor cause new I/O files to be generated. These commandssimply open the existing input, output and diagnostic filesthat have already been generated from a previousTRANSPORT run.

Each of the View Menu commands opens the associatedfile in a PBO Lab Text Edit Window. These windowsprovide standard editing capabilities and typical File, Editand Font Menus. The Save As command in the File Menuof Text Edit Windows can be used to save any of the filesusing a different name. Since these files will be overwrittenwith the next execution of TRANSPORT, they should besaved with a different name if the data is to be retained.Renamed Text Edit Windows can remain open forcomparison with other results. However, if the file is notrenamed and the window is left open the new data from asubsequent TRANSPORT run will overwrite the existingdata in the open window.

There are five native TRANSPORT I/O files that can beaccessed from the TRANSPORT View Submenu. Theseinclude the standard input and output files, in addition tothe plot, punch and data files. The Transport Input file isthe native input that is generated by PBO Lab for thebeamline on the Model Space. The Transport Output fileis the main output file generated with the execution ofTRANSPORT. The Transport Plot file is the raw datagenerated by TRANSPORT and plotted by PBO Lab. TheTransport Data file is an additional diagnostic output filethat is provided for PBO Lab Professional users. This filemay be used to add diagnostic write statements to theTRANSPORT FORTRAN source code. The TransportPunch file contains user-specified output data that isselected in the Punch File Options tab panel in theTRANSPORT Options Window. Refer to the Output andPunch File Options Section in Chapter 7:TRANSPORT Options.

The View Menu commands do notexecute TRANSPORT or cause newI/O files to be generated.

The Save As command in the FileMenu of Text Edit Windows can beused to save any of the files using adifferent name.

The last command in the TRANSPORT View Submenuis itself a Submenu for several Auxiliary input files thatcan be generated by TRANSPORT. The AuxiliarySubmenu is illustrated in Figure 30. Table 5 lists thedifferent Auxiliary files that can be generated for abeamline model. These files are not generated unless theyhave been selected in the Output File Options tab panel inthe TRANSPORT Options Window. Refer to the OutputFile Options Section in Chapter 7: TRANSPORT Options.If an auxiliary file does not exist (has not been previouslygenerated), then an alert will be given. If an auxiliary filehas been previously generated, it will be opened with theassociated View command in a PBO Lab Text EditWindow. Any of the Auxiliary files can be renamed withthe Save As command in the File Menu of the Text EditWindow. Auxiliary files are named with the root name“Auxiliary.tout”. Each file type is then given its’ ownextension which is appended to the root name. If a file ofthe same name exists when a new file is generated, then itwill be overwritten with the new file.

Table 5. Auxiliary Files Generated by TRANSPORT

Keyword DescriptionMAD Methodical Accelerator Definition Input FileTRANSPORT TRANSPORT Input FileLATDEF Lattice Definition Input FileSTRUCT STRUCT Input FileACAD Autocad Input File

The Auxiliary Files Submenu containscommands to view several Auxiliaryinput files that can be generated byTRANSPORT. These files are notgenerated unless they have beenselected in the Output File Optionstab panel in the TRANSPORT OptionsWindow. Refer to the Output FileOptions Section in Chapter 7:TRANSPORT Options.

The Auxiliary Submenu provides commands to open several Auxiliary files after they

have been generated by TRANSPORT

Figure 30. View Menu Commands to Open Auxiliary Files.


58

PB

O L

abT

M

2.0

PB

O L

abT

M

2.0

Displaying & Creating Matrices



59

6. Displaying and Creating MatricesThere are three commands in the TRANSPORTCommands Menu that are used for displaying and creatingmatrices. These commands are separated into two groups.The first group has two commands for displaying matrixdata from the last execution of TRANSPORT. The secondgroup contains one command that is used to executeTRANSPORT in order to create a Matrix Piece for aselection of beamline elements in the Model Space of theDocument Window.

Show R-MatrixThe Show R-Matrix Command in the TRANSPORTCommands Menu opens the R-Matrix Window shown inFigure 31. This R-Matrix Window displays the transferR-Matrix data at the end of the beamline for the lastTRANSPORT run executed. No specific options settingsare required to generate the data for the R-Matrix Window.However, the Show R-Matrix command will be inactiveif TRANSPORT has not been executed.

Creating a Matrix PieceThe Create Matrix Piece button in the Button Bar of theR-Matrix Window is used to generate a Matrix Piece fromthe R-Matrix data. The Matrix Piece is created on the WorkSpace of the Document Window as illustrated in Figure31. The Matrix Piece represents the entire beamline modelfrom the previous TRANSPORT execution that wasdisplayed in the R-Matrix Window and may be used inplace of the individual beamline elements. This may speedup calculations for very large models that have particularsections where the parameters are fixed so that MatrixPieces can be generated and used to replace the individualbeamline elements.

The Show R-Matrix Commanddisplays the R-Matrix for the lastexecution of TRANSPORT.

An unlimited number of R-MatrixWindows may be left open forcomparing results from multipleTRANSPORT runs.

Matrix Pieces may be used in abeamline model to replace entirebeamline segments with a single R-Matrix representation for thatsegment.

The Output File Option in theTRANSPORT Options Window thatcauses TRANSPORT to generate thetransverse matrix components inmillimeters and milliradians does noteffect the R-Matrix Window, whichwill always display the matrix data inmeters and inverse meters.


61


62

The Show R-Matrix Command Opens the Transport R-Matrix Window

The Create Matrix Piece Button Generates a Matrix Piece on the Work

Space for the Current R-Matrix

The Matrix Piece may be Inserted into the Beamline Model by

Dragging it to the Model Space

Double Click the Matrix Piece to Open the Piece Window

Figure 31. Creating a Matrix Piece from the Transport R-Matrix Window.


63

Show Sigma MatrixThe Show Sigma Matrix Command in the TRANSPORTCommands Menu opens the Output Sigma-MatrixWindow as illustrated in Figure 32. This window displaysthe Output Sigma-Matrix (Beam Matrix) at the end of thebeamline from the last TRANSPORT run executed.

There are no specific option settings required to generatethe data for the Sigma-Matrix Window. However, theShow Sigma-Matrix Command will be inactive ifTRANSPORT has not been executed. An unlimitednumber of Matrix Windows may be left open forcomparing results from multiple TRANSPORT runs.

There are two panels in the Output Sigma-Matrix Window.The top panel shows the TRANSPORT Reduced Sigma-Matrix and the bottom panel shows the full Output Sigma-Matrix in units of meters and radians. The first column ofthe Reduced Sigma-Matrix display, labeled: Diagonal,represents the half widths of the beam ellipsoid in each ofthe six beam coordinates. The remaining elementsrepresent the correlation coefficients between coordinates.

Creating a Beam PieceThe Button Bar at the top of the Sigma-Matrix Windowprovides an option for creating a PBO Lab Beam Piecefrom the TRANSPORT Output Sigma-Matrix data. TheCreate Beam Piece button will generate a new Beam Pieceand place it on the Work Space of the Document Windowas illustrated in Figure 32. The Beam Piece Parameterswill be generated for the Sigma Matrix data and PhaseSpace Ellipse Plots will be displayed in the Beam PieceWindow. The Beam Piece can be used in the beamlinemodel or simply left on the Work Space for comparisonwith subsequent TRANSPORT runs.

The Show Sigma-Matrix Commanddisplays the Sigma-Matrix for the lastexecution of TRANSPORT.

Refer to the “TRANSPORT UserManual” for a description of theSigma Matrix and Reduced SigmaMatrix formulation.

The Sigma-Matrix Window providesa button for creating a PBO Lab BeamPiece from the TRANSPORT OutputSigma-Matrix data.


64

The Show Sigma Matrix Command Opens the Transport Output

Sigma-Matrix Window

The Create Beam Piece Button Generates a Beam Piece on the Work

Space for the Current Output Sigma-Matrix

Double Click the Beam Piece to Open the Piece Window

Figure 32. Creating a Beam Piece from the Output Sigma Matrix Window.


65

Make Matrix Piece CommandThe Make Matrix Piece Command is used to create aMatrix Piece for a selection of pieces in the beamlinemodel. Using a single Matrix Piece to replace a staticbeamline segment that contains many pieces cansignificantly speed up calculations for large models. Thiscommand is similar to using the Create Matrix Piecebutton in the Show R-Matrix Window. However, thiscommand operates on a selection of pieces in the beamlinemodel, unlike the R-Matrix Window button, which alwayscreates a Matrix Piece for the entire beamline. The MakeMatrix Piece Command in the Commands Menu is alsodifferent because TRANSPORT is automatically executedto compute the R-Matrix for the beamline model selection.When creating a Matrix Piece from the Show R-MatrixWindow, the R-Matrix data from the last TRANSPORTexecution is always used. Refer to the Show R-MatrixSection in this Chapter.

To create a Matrix Piece with the Make Matrix PieceCommand, first make a selection of pieces in the beamlinemodel and then select the Make Matrix Piece Command inthe TRANSPORT Commands Menu. TRANSPORT will beexecuted to calculate the R-Matrix for the beamline selection.A Matrix Piece will automatically be generated and placedin the lower left corner of the Work Space as illustrated inFigure 33. The Matrix Piece can then be used to replace theoriginal beamline selection in the Model Space.

The original selection of pieces in the beamline modelthat are used to create the Matrix Piece are not changedor replaced automatically. Drag a copy of the originalselection to the Work Space before deleting these piecesin the beamline because they can not be re-generated fromthe corresponding Matrix Piece. The Matrix Piece canthen be placed in the beamline at the location of theoriginal pieces. This command can also be used to generatean R-Matrix through a specific location in the beamlinemodel for comparison with other results.

The Create Matrix Piece Commandis used to create a Matrix Piece for aselection of pieces in the beamlinemodel.

A Matrix Piece can also be createdfor the entire beamline model fromthe R-Matrix Window. Refer to theShow R-Matrix Section in thisChapter.

To create a Matrix Piece first make aselection of pieces in the beamlinemodel and then select the MakeMatrix Piece Command in theTRANSPORT Commands Menu.

The original selection of pieces in thebeamline model that are used tocreate a Matrix Piece are notmodified. The Matrix Piece willappear on the Work Space and canthen be used to replace the originalselection in the beamline model.


66

The Make Matrix Piece Command generates a Matrix Piece for the beamline model selection and places it in the lower left corner of the Work Space

Drag a copy of the Matrix Piece from the Work Space and replace the original selection of pieces

in the beamline model

Drag a copy of the beamline model selection to the Work Space prior to replacing it in the beamline

with the new Matrix Piece

(Use the View Menu Command or the Button Bar control to Hide/Show the Global Parameters panel)

Make a selection of Pieces in the beamline model and use the Make Matrix Piece Command to generate a Matrix Piece on the Work Space

for the beamline selection

Figure 33. Creating a Matrix Piece for a Beamline Selection.


67

PBO Lab provides an Output File Option in theTRANSPORT Options Window that causesTRANSPORT to generate the transverse matrixcomponents in millimeters and milliradians. This mixedunits representation will only appear in the Transport OutputFile when this option is selected. The Matrix Piece Windowwill always display the matrix data in meters and inversemeters regardless of the TRANSPORT Output File Option.

The Matrix Piece Window is described in more detail inthe Matrix Piece Section of Chapter 3: Beamline Elements.

The Matrix Piece Window displays thetransfer matrices in units of meters,radians and inverse meters, radiansregardless of units selection for theOutput File in the TRANSPORTOptions Window.


68


PB

O L

abT

M

2.0

PB

O L

abT

M

2.0

TRANSPORT Options



69

7. TRANSPORT OptionsPBO Lab provides several options for specifyingparameters which direct TRANSPORT to write data tothe Output and Punch files. TRANSPORT options alsoinclude parameters for setting the Calculation Order andOutput Result for TRANSPORT runs. The OptionsWindow is accessed with the last item in the TRANSPORTCommands menu as illustrated in Figure 34.

All of the TRANSPORT Options aresaved with the beamline model in theDocument Window when a Save, ora Save As command is executed.

The TRANSPORT Options Window is Opened from the Commands Menu

Figure 34. Opening the TRANSPORT Options Window.

TRANSPORT Options are presented in a single windowwith multiple tab panels for (1) calculation order andoutput result, (2) printing matrices after every beamlineelement, (3) printing matrices after the last element, (4)various format options for the Transport Output file, and(5) printing matrices to the Transport Punch file. All ofthe TRANSPORT Options are saved with the model fileusing the Save or Save As commands in the File Menu.

TRANSPORT output may also bespecified at specific locations in thebeamline using Marker Pieces asdescribed in the previous Section.


71


72

Calculation Order & Output ResultThe TRANSPORT Application Module integrated withPBO Lab can model optics problems up to the third order.The first tab panel in the TRANSPORT Options Windowillustrated in Figure 35, is used to set up the CalculationOrder and the Output Result matrices for TRANSPORT.

The Calculation Order represents the order to which thetransfer matrices are calculated about the referencetrajectory. Calculating to Zero Order simply traces thebeam centroid through the beamline elements. Tracingthe beam centroid has meaning only when the beamcentroid is displaced from the reference trajectory with aCentroid Piece after the Beam Piece in the beamlinemodel. The Output Result selection determines the Orderof the transfer matrix to be written to the Transport Outputand Transport Punch files.

Figure 35. Calculation Order and the Output Result.

The Order of the Output Result can not be higher then theOrder of Calculation. Output Result options higher thanthe specified Calculation Order will be inactive.

The TRANSPORT Calculation Orderand Output Result are set in theTRANSPORT Options Window.

The order of the Output Result cannot be higher then the CalculationOrder.

The options in the Order ofCalculation Window are saved withthe Document using the Save or SaveAs commands.


73

The Calculation Order tab panel also includes a checkbox to specify the use of a second-order path lengthdifference correction. This second-order path lengthcorrection option corrects a long standing calculation errorin TRANSPORT that has only recently been identified.The error involves the second-order path length differencefor beamlines that use radiofrequency (RF) acceleratorelements. The second-order path length option correctsthis historical error in TRANSPORT. Transverse resultsfor magnetic systems will be identical to the originalTRANSPORT. However, for beamlines withRF accelerator elements the new path length correctionwill change (correctly) the second-order transverse results.

Print OptionsThe tab panels illustrated in Figure 36 may be used tospecify Print Options at the end of the beamline model orafter every piece in the model. However, it is also possibleto specify output at specific locations in the beamline usingthe Marker or Final Pieces.

This correction only applies to thesecond-order path length withsecond or third-order calculations.The path length correction is on bydefault.

The Marker and Final Pieces may beused to specify output at specificlocations in the beamline. Refer tothe Marker Piece Section in theBeamline Elements Chapter.

Output Options may be Specified After each Piece or at the End of the Beam Line Model

Marker or Final Pieces Could be Inserted in the Beam Line to Request the Same

Output at Specific Locations or at the End of the Beam Line Model

Figure 36. Specifying Output after every Piece or at the end of the Model.


74

Output and Punch File OptionsThe TRANSPORT Options Window is also used to set upseveral parameters for specifying and formatting data to bewritten to the Transport Output file and to the TransportPunch file. In addition, the Output File Options tab panelincludes several options for generating Auxiliary files.

The Output File Options tab panel, shown in Figure 37,includes two options panels, one for Transport Output FileOptions and another for selecting among a variety ofAuxiliary Files that can be generated from TRANSPORT.The File Options panel provides selections that effect thecontent and format of the Transport Output file. TheTransport Output file is the native text file generated byTRANSPORT and displayed by PBO Lab automaticallyafter TRANSPORT is executed. The options provided arethose most frequently encountered by TRANSPORT users.Note that the Output File Options effect the TransportOutput file only, not other PBO Lab display windows.

The Output File Options tab panel includes various content and format options for the

Transport Output File and selections for generating a variety of Auxiliary Files

Figure 37. TRANSPORT Output File Options and Auxiliary Files.

The Auxiliry Files panel includes several different inputfiles that can be generated by TRANSPORT for thebeamline model in the Document Window.


75

The different Auxiliary files that can be generated include:(1) Methodical Accelerator Definition (MAD) input file,(2) TRANSPORT input file (created by TRANSPORT,not PBO Lab), (3) Latice Definition (LATDEF) input file,(4) STRUCT input file, and (5) Autocad input file. Thesefiles will be generated when TRANSPORT is executedfor the corresponding selections in the Auxiliary Filespanel. Once these files are generated, they can be viewedin Text Edit Windows using the PBO Lab View Menucommands in the Document Window. Refer to theTRANSPORT View Menu Section in Chapter 5:TRANSPORT Menus. All of the files use “Auxiliary.tout”as a root name with their own extensions appended to theend. For example if the MAD option is selected, a filenamed “Auxiliary.tout.mad” will be generated. If a file ofthe same name exists when a new file is generated then itwill be overwritten with the new file.

The Punch File Options tab panel, shown in Figure 38,provides options for writing transfer matrices to theTransport Punch file. The Punch file is a secondary datafile generated by TRANSPORT that can be viewed in TextEdit Windows using the PBO Lab View Menu commandsfor TRANSPORT. As with the other TRANSPORT I/Ofiles, the data will be overwritten each time TRANSPORT isexecuted. You can save previously generated output by usingthe Save As command in the File Menu of the Text EditWindows used to view the files.

Refer to the “TRANSPORT UserManual” for a description of theAuxiliary files that can be generated.

The Punch File Options tab panelprovides options for writing transfermatrices to the Transport Punch file.

Additional output can be directed to the Transport Punch file from the

Punch File Options tab panel

Figure 38. TRANSPORT Punch File Options.



76

PB

O L

abT

M

2.0

PB

O L

abT

M

2.0

TRANSPORT Plot Specifications



77

8. TRANSPORT Plot SpecificationsThe Transport Plot Specification Window is used to definethe type of plot data that will be generated byTRANSPORT and the Graph Plot Window that will bedisplayed by PBO Lab after TRANSPORT is executed.Figure 39 shows the window that is brought up when theTransport Plot Specification Command is selected inTRANSPORT Commands Menu.

Any Plot Specifications will be savedwith the beamline model when theSave, or Save As, command isselected in the Document Window.

The Transport Plot Specification Window is Opened from the

TRANSPORT Commands Menu

Figure 39. Opening the Transport Plot Specification Window.

The Plot Specification Window is used to set up a varietyof different graphic output plots. TRANSPORT can onlygenerate data for one plot type in a given run, so one ofthe available plot types must be selected using the radiobuttons in the Plot Selection panel in the upper left cornerof the window. Four plot types are available: (1) MatrixElements vs. Length, (2) Envelope, Centroid and Latticefunctions vs. Length, (3) Floor Plots, (4) Final EllipsePlots, or No Plots.


79


80

The Matrix Elements vs. Length selection uses the matrixcontrols to select specific matrix elements (Figure 40). TheEnvelope, Centroid and Lattice functions vs. Length panelis used when the Plot Selection is set for this plot type. TheFloor Plot type has an adjacent pop-up to specify Side Viewor Top View. The Final Ellipse Plot type and No Plotselections require no additional user input. The last panelin the lower right corner of the Plot Specifications Windowis used to select up to four different plot variables for boththe Matrix Elements vs. Length and Envelope, Centroidand Lattice functions vs. Length plot types.

In order to activate the Plot Selectionspanel so a different plot type can beselected, all plot variables for thecurrent plot type must be clearedwith the Delete All button.

S11S12S33S34

Matrix Elements vs. Length Panel -

Select the desired matrix, Beam, Sigma, etc. then pick the desired element in the matrix panel, use the Set Button to add the element

to the Plot Variables list

Envelope, Centroid and Lattice Functionsvs. Length Panel -

Select up to four Plot Variables from the different Envelope, Centroid and Lattice Function pop-ups in this panel, use the Set

Button to add the selection to the Plot Variables list

Plot Selection Panel -

Select the Desired Plot TypeAny Previously Selected Plot

Variables Must be Deleted Before Changing the Plot Type

(Use the Delete All Button)

Plot Variables Panel -

Selected Plot Variables for a Matrix Elements vs. Length Plot or for an

Envelope, Centroid and Lattice Functions vs. Length Plot

(Use the Set Button to add a plot variable for the current Plot Selection)

The Graph Plot Window is Automatically Opened Following

the Execution of TRANSPORT

Four Beam Matrix Elements are Set as Plot Variables for a Matrix Elements vs. Length Graph Plot

Figure 40. Transport Plot Specifications Window.


81

Clicking in a cell of the matrix tablewill highlight that cell and theselection can then be added using theSet button.

The last plot type in the Plot Selection panel is for noplots. This is the default plot type. When a new untitledDocument is created the No Plots option is selected. Plotdata will not be generated and a Graph Plot window willnot be opened following the execution of TRANSPORT.

The following Sections describe each of the PlotSelections types separately. A description of the differentfeatures available in the PBO Lab Graph Plot Windowscan be found in the main PBO Lab User Manual. TheTRANSPORT keywords that are used to generate plot dataare listed in Table 6.

Plotting Matrix Elements vs. LengthWhen choosing to plot Matrix Elements vs. Length, asmany as four different matrix elements may be selectedfor an individual Graph Plot. The Matrix elements maybe selected from: (a) Rij, First-Order Transfer Matrix, (b)RAij, Auxiliary First-Order Transfer Matrix, (c) Tijk ,Second-Order Transfer Matrix, (d) TAijk , AuxiliarySecond-Order Transfer Matrix, (e) Uijkl , Third-OrderTransfer Matrix, (f) UAijkl , Auxiliary Third-Order TransferMatrix, (g) Beam Matrix, and (h) Correlation Matrix. TheMatrix Elements panel in the lower left corner of the PlotSpecification Window is active only when the MatrixElements vs. Length radio button is selected in the PlotSelection panel (Figure 40).

To select a matrix element, first chose the radio button inthe Matrix Elements vs. Length panel for the desiredtransfer matrix: R-Matrix, T-Matrix, U-Matrix, BeamMatrix or Correlation Matrix. The R and T Matrixselections also provide a pop-up to select between theRegular Matrix or the Auxiliary Matrix. The T-Matrixselection requires an additional selection to specify the iindex, and the U-Matrix requires both i and j indices tobe specified. This is done with the pop-ups to the right ofthe Matrix radio buttons. The 6x6 matrix table at thebottom of the Matrix Elements panel is then used to selectindividual matrix elements.


82

Clicking in a cell of the matrix table will highlight that celland the selection can then be added using the Set button.After a selection is made, the corresponding TRANSPORTkeyword (Table 6) will appear in the plot variable list in thelower right corner of the Plot Specification Window (Figure40). Selections can also be removed from the list; firsthighlight the item to be removed by clicking on it, thenpress the Delete button. The Delete All button clears allplot variables from the list.

Table 6. TRANSPORT Keywords.

Beam & Correlation: Beam Correlation

i, j, k & l = 1,6 S ij Cij

Transfer Matrices: Regular Auxiliary

First-Order Rij RAij

Second-Order Tijk TAijk

Third-Order Uijkl UAijkl

Beam Envelopes: Half Width Half Angle

Horizontal XBEAM XPBEAM

Vertical YBEAM YPBEAM

Longitudinal LBEAM DELBEAM

Beam Centroids: Position Angle

Horizontal XC XPC

Vertical YC YPC

Longitudinal DLC DELC

Lattice Functions: Horizontal Vertical

βx βy BETAX BETAY

αx αy ALPHAX ALPHAY

ηx ηy ETAX ETAY

η,x η,y DETAX DETAY

Plotting Envelope, Centroid and LatticeFunctions vs. Accumulated Length

The Envelope, Centroid and Lattice Functions vs. Lengthpanel in the upper right corner of the Plot SpecificationWindow is active only when the corresponding radiobutton is selected in the Plot Selection panel.

Table 6 shows the TRANSPORTKeywords that can be used for PlotSpecifications.

When a plot selection is made,the TRANSPORT keyword will appearin the Plot Variable panel in the lowerright corner of the Plot SpecificationWindow.


83

Only one of the three options (Envelopes, Centroids orLattice Functions) can be chosen at a time. First selectone of the radio buttons and then make a selection fromthe corresponding pop-up (Figure 41). Up to fourselections can be set for a given option by choosing thedesired pop-up item and pressing the Set button. Use theDelete or Delete All buttons to removed a selected variableor clear all the plot variables from the list.

This Graph Plot shows the Accelerator Functions (ALPHAY), (BETAY), (ALPHAX) and (BETAX) plotted as a function of the Accumulated Beam Line Length

βxβy α x

α y

This Graph Plot shows the Horizontal Beam Half Width (XBEAM), Horizontal Beam Half Angle

(XPBEAM), Vertical Beam Half Width (YBEAM) and Vertical Beam Half Angle (YPBEAM) plotted as a

function of Accumulated Beam Line Length

This Graph Plot shows the Horizontal Beam Centroid Position (XC), Horizontal Beam Centroid Angle (XPC), Vertical Beam Centroid Position (YC), Vertical Beam Centroid Angle (YPC)

plotted as a function of Accumulated Beam Line Length

Figure 41. Beam Envelopes, Beam Centroids and Lattice Functions.

This Graph Plot shows the Horizontal Beam HalfWidth (XBEAM), Horizontal Beam Half Angle

(XPBEAM), Vertical Beam Half Width (YBEAM) andVertical Beam Half Angle (YPBEAM) plotted as a

function of Accumulated Beam Line Length

This Graph Plot shows the Accelerator Functions αy

(ALPHAY), βy (BETAY), αx (ALPHAX) and βx (BETAX)plotted as a function of the Accumulated Beam Line Length

Plotting Floor CoordinatesThis plot type is used to generate top and side view GraphPlots for floor coordinates of the reference trajectory. Thepop-up to the right of the Floor Coordinates radio buttonis used to select between top and side views. There is noadditional input required in the Plot Specification Window.However, included with the Global Parameters in theDocument Window are a set of Initial Floor CoordinateParameters (Figure 4). These are used to specify the initialcoordinates and the orientation of the reference trajectoryfor plotting floor coordinates.

Plotting Final EllipsesThis plot type is used to generate horizontal and verticalTransverse Phase Space Ellipse Plots for the end of thebeamline. There are no additional inputs required for thisplot type, simply choose the Final Ellipse Plots radiobutton in the Plot Selection panel (Figure 39). A FinalEllipse Graph Plot Window (Figure 42) will be openedautomatically after running TRANSPORT.

Example of a Phase Space Ellipse Plot (XP vs. X and YP vs. Y)

Figure 42. Phase Space Ellipse Plot.

Graph Plot WindowsThe selected Transport Plot Specification will beautomatically generated in a PBO Lab Graph Plot Windowafter TRANSPORT is executed. The Graph Plot Windowsprovide a variety of interactive features which aredescribed in the PBO Lab User Manual. Refer to the GraphPlot Windows Section in the Analysis Tools Chapter ofthe main PBO Lab User Manual.

Floor plots can also be generatedusing the PBO Lab Tools for Focusingand Bending Trajectories in the ToolsMenu.

You may need to clear previouslyselected plot variables with the DeleteAll button, in order to activate thePlot Selection radio buttons.

A Graph Plot window is automaticallyopened, for the Transport PlotSpecifications selected when the WriteInput & Run Transport command isissued.


84

PB

O L

abT

M

2.0

PB

O L

abT

M

2.0

TRANSPORT Fitting



85

9. TRANSPORT FittingThe TRANSPORT program can be used to find solutionsfor a wide of variety of beamline fitting problems. Fittingproblems are formulated in terms of constraints andvariables. Selected beamline element parameters arevaried in an effort to satisfy (“fit”) the constraints. Fittingconstraints are algebraic expressions defined in terms ofuser-specified Named Parameters and Fitting Variablesin the beamline model as well as a number of differentTRANSPORT output parameters.

PBO Lab provides a drag & drop - point & click userinterface for setting up and running a TRANSPORT fittingproblem. Fitting Constraints are specified in user friendlywindows accessed from Marker or Final Pieces that canbe inserted anywhere in the beamline model. ParameterVariables are specified in Special Parameter SettingsWindows accessed from any Piece Window. InteractiveList Windows that organize all of the Fitting Variablesand Constraints for the entire beamline model are accessedfrom the TRANSPORT Commands Menu. FittingVariables can be examined after fitting and the beamlinemodel can be updated with any or all of the fit values inthe Update Window which is opened automaticallyfollowing the fit procedure.

A Symbolic Parameter Name may be defined for a PieceParameter without using it as a Fitting Variable. TheseNamed Parameters may then be used to define ParameterAlgebraic Expressions for other Piece Parameters.Parameter Expressions can also be specified in terms ofuser-defined Fitting Variables and TRANSPORT programvariables. Refer to chapter 4: Special Parameter Settings,for a description of Symbolic Parameter Names, ParameterExpressions and selecting a Parameter as a Fitting Variable.

This Chapter describes the user interface for setting up aTRANSPORT fitting problem. The “TRANSPORT UserManual” describes specific fitting capabilities of theprogram in more detail.

Fitting problems are formulated interms of fitting constraints andvariables. Selected beamline modelparameters are varied in an effort tosatisfy (“fit”) the constraints.

Fitting Constraints can be specifiedwith Marker or Final Pieces that canbe inserted anywhere in the beamlinemodel.

Interactive List Windows providequick access to all of the user-specified Variables, Expressions andConstraints for the entire beamlinemodel.

A Symbolic Parameter Name may bedefined for a Piece Parameter withoutusing it as a Fitting Variable.

Parameter Algebraic Expressions maybe defined in terms of user-specifiedNamed Parameters and/or FittingVariables.

Refer to the Special ParameterSettings Section in Chapter 4 of thisSupplement.


87


88

Fitting VariablesMany of the input parameters for the various beamlineelements can be selected by the user as TRANSPORTFitting Variables. Fitting Variables are selected in SpecialParameter Settings Windows that are opened with theSpecial (“S”) button to the left of most parameters in PBOLab Piece Windows. Figure 43 illustrates selecting theMagnetic-Field Gradient parameter in a Quadrupole PieceWindow; pressing the “S” button opens the SpecialParameter Settings Window for the associated parameter.The second radio button in the TRANSPORT tab panelof the S-Window, selects the parameter as a TRANSPORTFitting Variable using the Parameter Name specified atthe top of the window.

Fitting Variables are selected inSpecial Parameter Settings windowsthat are opened with the Special (“S”)button to the left of most parametersin PBO Lab Piece Windows.

A Fitting Variable that has a SymbolicParameter Name identical to a PieceComment will also result in the firstparameter (regardless of name) forthat Piece to be varied.

Special Parameter Settings are accessed with the Special Parameter Settings (“S”) Buttons located next to each parameter in PBO Lab Piece Windows

Double-Click Piece Icons to Open Individual Piece Windows

Select the TRANSPORT Application Context in the Document Window Button Bar

Figure 43. Opening a Special Parameter Settings Window.


89

Transport Fitting Variables must be native inputs toTRANSPORT in order to be varied during fitting. Greendots appear next to “native” TRANSPORT parameters inPiece Windows when the Application Context is set forTRANSPORT as illustrated in Figure 43. The S-Buttonswill be inactive for those parameters without green dots.Native (green dot) parameters that do not support specialparameter settings will not have a Transport tab panel inthe Special Parameter Settings Window.

Many PBO Lab Pieces provide alternative parameter setsfor specifying inputs for TRANSPORT. For example theQuadrupole Piece illustrated in Figure 43 can be definedin terms of three different parameter sets (selected withthe Quadrupole Strength pop-up at the top of the QuadPiece Window). Depending on the users preferred set,different Piece Parameters will be used as native inputs toTRANSPORT. The green dots next to native parameterswill reflect the current parameter set and only thoseparameters will be used as TRANSPORT inputs for thePiece. A Fitting Variable previously defined for a differentparameter set will have no effect. For example, both theMagnetic Field at Pole Tip and the Magnetic-FieldGradient parameters could be selected as Fitting Variablesby switching the Quadrupole Strength selection. However,only one of these parameters will be used as input forTRANSPORT (according to the current QuadrupoleStrength selection), so the other will not be an input forthe Quad and will not be varied during fitting.

The example illustrated in Figure 43 shows the Magnetic-Field Gradient defined by the Symbolic Parameter Name“VARY4”. This parameter has been selected as a FittingVariable in the Transport tab panel of the S-Window.Fitting Variables are always defined by the application-independent Symbolic Parameter Name specified in theS-Window. If a name has not been specified it will begenerated when the Fitting Variable selection is made inthe TRANSPORT tab panel.

Some (but not all) Piece Parametersmay be selected as Fitting Variablesand used by TRANSPORT to fit user-specified Constraint Expressions.

TRANSPORT supports up to twenty(20) independent user-specifiedFitting Variables.

The green dots next to PieceParameters reflect the currentApplication Context and the usersparameter set selection. Only greendot parameters will be used asTRANSPORT input for the Piece.

All special parameter settings aresaved with the beamline model whenusing a Save, or Save As, command.


90

The Symbolic Parameter Names can also be used inAlgebraic Expressions specified for other Pieceparameters as described in the Parameter AlgebraicExpressions Section of Chapter 4: Special ParameterSettings. During a fitting procedure, Algebraic ParameterExpressions are evaluated at each iteration. After fittinghas completed, the new values for all of the FittingVariables and Parameter Algebraic Expressions can beused to update the beamline model.

Alias Pieces can also be used to couple multiple beamlineelements during a fitting procedure. Refer to the AliasesSection in the User Interface Chapter of the main PBO LabUser Manual, for a description of Alias Pieces.

Creating a copy of a Piece with Special Parameter Settingswill also copy those settings. For example if a PieceParameter has been selected as a Fitting Variable and thatPiece is copied in the beamline, then there would be twoparameters defined by the same Parameter Name. Bothinstances of the Parameter Variable will be sent toTRANSPORT but the initial value for the first FittingVariable encountered will be used for any other Variablesin the beamline that have the same Parameter Name.Copying Pieces that have Parameter AlgebraicExpressions will duplicate those expressions on the copiedPiece but otherwise present no difficulties.

A Piece with a Comment that is the same as any SymbolicParameter Name selected as a Fitting Variable can causethe first parameter of that Piece to be varied. This may beunintended. To avoid this, make sure that no SymbolicParameter is used as a Piece Comment.

A Parameter Name may be definedfor use in an Parameter AlgebraicExpression without selecting theParameter as a Fitting Variable.

A Piece Parameter may be varied orit may be defined by an expression,but not both.

Alias Pieces can also be used tocouple multiple beamline elementsfor a fitting problem.

Creating a copy of a Piece withSpecial Parameter Settings, eitherwith the cut/copy/paste commandsor by simply dragging a copy to thework space, will also copy the SpecialParameter Settings from the originalPiece to the duplicate.

Using a Symbolic Parameter Namethat is identical to a Piece commentmay cause unintended results.


91

Named Parameters List WindowAll of the Piece Parameters in the beamline model and onthe Work Space that have been given Symbolic ParameterNames will be listed in the Named Parameter List Window.Named Parameters that are selected as Fitting Variables areindicated with an “X” in the Fit column of the NamedParameters List Window as illustrated in Figure 44.

Any Parameter with a SymbolicParameter Name will be included inthe Named Parameters List Window.Fitting Variables are indicated with an“X” in the Fit column of the NamedParameters List Window.

The Named Parameters List Window is opened from the TRANSPORT Commands Menu.The List Window contains all the Named Parameters for the entire beamline model

An "X" in the Fit column indicates that the Parameter has been selected as a Fitting Variable. Clicking in

this column toggles the Fitting Variable selection

Double-clicking an entry in the Parameters Variables window will open the associated Piece window

A Param Piece can be generated for any selected Parameters in the List Window

using the Create Param Piece Button

Figure 44. Named Parameters List Window.

Named Parameters can be easily selected (and unselected)as Fitting Variables by clicking in the “Fit” column of theList Window. A Param Piece can be created for selectedparameters in the List Window by using the Create ParamPiece Button. Refer to the Parameters and Expressions ListWindows Section in Chapter 4: Special Parameter Settings.

Refer to the Parameters andExpressions List Windows Section inChapter 4: Special Parameter Settings.


92

Fitting ConstraintsTRANSPORT Fitting Constraints are defined as location-specific algebraic expressions of user-specified NamedParameters and Fitting Variables, as well as a variety ofTRANSPORT output parameters. Multiple FittingConstraint Expressions may be defined for differentlocations in the beamline model.

Fitting Constraints are defined at user-specified locationsin the beamline model using Marker or Final Pieces. Draga Marker or Final Piece from the Palette Bar and insert itat the desired location in the beamline model. Open theMarker Piece Window by double-clicking the Piece iconas illustrated in Figure 45.

Marker and Final Pieces

The Marker and Final Pieces are usedto define application-specific FittingConstraints and Diagnostics atspecific beamline locations.

Open a TRANSPORT Fitting ConstraintsWindow

TRANSPORT Application Context

The Marker Piece is used to Specify Application-Specific Constraints and

Diagnostics at the Location of the Marker Piece in the Beamline Model

Figure 45. Marker and Final Pieces are used to mark locationsin the beamline for specifying TRANSPORT Fitting Constraints.


93

A Marker Piece is used to define application-specificConstraints, Diagnostics and Stored Parameters that aredependent on a specific location in the beamline model.A Marker Piece can be used by all installed ApplicationModules and therefore depends on the current ApplicationContext. The Application Context can be changed in theDocument Window or directly in the Marker PieceWindow as illustrated in Figure 46. Refer to the MarkerPiece Section in Chapter 3:Beamline Elements for adescription of using the Marker and Final Pieces.

The Constraints panel of the Marker Piece Window containsa list of all the specified Constraint Expressions for thislocation in the beamline. Each entry is preceded by theApplication Module name. Making a selection in this listand pressing the Remove button will delete that entry fromthe list without having to open the Constraints Window.

The Open buttons in the MarkerPiece window use the ApplicationContext to open the appropriateapplication-specific user interfacewindow.

The Constraints panel of the MarkerPiece Window contains a list of allthe specified Constraints for thislocation in the beamline model.

The Application Context must be set for TRANSPORT to Open the TRANSPORT

Fitting Constraints Window

Figure 46. Marker Piece Window Constraints and Diagnostics.

With TRANSPORT as the selected Application Contextin the Marker Piece Window, pressing the Open button inthe Constraints panel will open the TRANSPORT FittingConstraints Window (Figure 46).

To open the Transport FittingConstraints Window the ApplicationContext switch must be set forTRANSPORT.


94

Fitting Constraints WindowA TRANSPORT Fitting Constraints Window is openedby double-clicking any Marker or Final Piece in thebeamline model. The Open button in the Constraints panelof the Marker Piece Window opens the Fitting ConstraintsWindow (Figure 46) for the current Application Context.The Application Context can be set in the Documentwindow or directly in the Marker Piece window.

The Constraint Expression field at the top of the FittingConstraints Window (Figure 47) can be used to directlyenter expressions in terms of Named Parameters, FittingVariables and TRANSPORT output parameters. Afterassigning a Fit Value and Tolerance, the Accept button isused to add the Constraint to the list at the bottom of thewindow. Figure 47 illustrates the primary features of theTransport Fitting Constraints Window.

Transport Fitting ConstraintsWindows are accessed from Markeror Final Pieces placed in the beamlinemodel.

The Constraint Expression field at thetop of the Fitting Constraints Windowcan be used to directly enterexpressions defined in terms of NamedParameters, Fitting Variables as well asa variety of TRANSPORT outputparameters.

Specify a Value and Tolerance to the "Fit" Constraint

Type in Mathematical Operators and Functions directly or use the

Operators Panel

The "Accept" Button accepts the user-specified Expression, Value and Tolerance and adds it to the

Constraint Experession List at the bottom of the window

The "Delete" Button will Remove a Selected Constraint from the

Constraint Expression List

Make a selection the Constraints List to edit the Expression and change the Value or Tolerance

Enter an Algebraic Constraint Expression in terms of TRANSPORT program variables and user-specified Parameter and Fitting Variables

Figure 47. Transport Fitting Constraints Window.


95

Several TRANSPORT output parameters can be selectedfor use in Constraint Expressions. Table 7 lists theTRANSPORT keywords (output parameters) that aresupported in Constraint Expressions. Each category inTable 7 is represented in the point & click interface of theTRANSPORT Fitting Constraints Window.

Several TRANSPORT output parameterscan be selected for use in ConstraintExpressions.

Table 7. TRANSPORT Keywords for use in Constraint Expressions.

The Beam Matrix, Correlation Matrix and Transfer Matricesare selected with the radio buttons shown in Figure 47. TheMatrix panel in the lower left portion of the window willreflect the current matrix selection and is used to selectspecific matrix elements for all matrices. The pop-ups forthe first-, second- and third-order Transfer Matrices are usedto specify Regular and Auxiliary Matrices. The second- andthird-order Transfer Matrices also have pop-ups for theadditional dimensions required for these selections.

Beam Matrix (i,j =1,6) KeywordReduced Sigma Matrix Element S ij

Correlation Matrix (i,j =1,6) KeywordBeam Correlation Matrix Element C ij

Transfer Matrices (i,j,k,l =1,6) Keyword1st-Order Transfer Matrix Element R ij2nd-Order Transfer Matrix Element T ijk3rd-Order Transfer Matrix Element U ijkl

Transfer Matrices (i,j,k,l =1,6) Keyword1st-Order Auxiliary Matrix RA ij2nd-Order Auxiliary Matrix TA ijk3rd-Order Auxiliary Matrix UA ijkl

Beam Centroids KeywordHorizontal Beam Centroid Position XBEAMHorizontal Beam Centroid Angle XPBEAMVertical Beam Centroid Position YBEAMVertical Beam Centroid Angle YPBEAMLongitudinal Beam Centroid Position LBEAMLongitudinal Beam Centroid Angle DELBEAM

Beam Envelopes KeywordHorizontal Beam Half Width XBEAMHorizontal Beam Half Angle XPBEAMVertical Beam Half Width YBEAMVertical Beam Half Angle YPBEAMLongitudinal Beam Half Width LBEAMLongitudinal Beam Half Angle DELBEAM

Floor Coordinates KeywordBeamline Accumulated Length LFloor Coordinate X Value XFLOORFloor Coordinate Y Value YFLOORFloor Coordinate Z Value ZFLOORView Reference Trajectory Angle YAWReference Trajectory Horz. Angle PITCHNet Rotation Angle about TrajectoryROLLElevation ELEVATION

Lattice Functions KeywordAccelerator Function BetaX BETAXAccelerator Function AlphaX ALPHAXAccelerator Function BetaY BETAYAccelerator Function AlphaY ALPHAYAccelerator Function EtaX ETAXAccelerator Function DeltaX DETAXAccelerator Function EtaY ETAYAccelerator Function DeltaY DETAY

The Beam Matrix, Correlation Matrixand Transfer Matrices are selectedwith radio buttons; the Matrix panelin the lower left portion of thewindow is used to select specificmatrix elements for all matrices.


96

There are also pop-up controls, which have severalselections each, for four different categories: BeamEnvelopes, Beam Centroids, Lattice (Accelerator)Functions as well as Floor Coordinates and Orientationvariables. You don’t need to know the TRANSPORTkeywords in order to formulate a Constraint Expressionwith TRANSPORT output parameters. Simply chose acategory, either from the matrix radio buttons or thevarious pop-up controls. Use the matrix panel to select aspecific matrix element or make a selection from one ofthe pop-ups; the keyword for your selection will begenerated automatically in the Constraint Expression Fieldat the top of the window. After assigning a Fit Value andTolerance, use the Accept button to add the constraint tothe list at the bottom of the window.

The Constraint Expression list at the bottom of the windowcontains all of the Fitting Constraints defined for thislocation in the beamline model. To select an existingConstraint Expression click on the entry in the list. Theselection will be highlighted and the edit fields at the topof the window will be updated with the selection. Pressthe Accept button to update the expression with anychanges. The Delete button is used to remove an existingconstraint. Select the constraint in the ConstraintExpression list and press the Delete button. A constraintcan also be deleted directly from the Marker Piece windowwithout opening the Fitting Constraints Window. Selectthe constraint in the constraints list in the Marker (or Final)Piece Window and then press the Remove button in theConstraint panel.

The expression list in the Fitting Constraints Windowincludes only the constraints for that location in thebeamline. Other constraints may be specified at differentlocations with additional Marker or Final Pieces. All of theuser-specified Fitting Constraint Expressions for the entirebeamline model are organized in the Constraint ExpressionsList Window, which is described in the next Section.

Any keyword for a TRANSPORToutput parameters including matrixelements, may be typed directly in theConstraint Expression field. Forexample “T346” would be entered asthe keyword for the second-orderTransfer matrix element T3,4,6.

The Constraint Expression list at thebottom of the window contains allof the fitting constraints defined forthis location in the beamline model.


97

Constraint Expressions List WindowMultiple Marker and Final Pieces can be used to specifyFitting Constraints at different locations in the beamlinemodel. PBO Lab provides a Constraint Expressions ListWindow that groups all of the application-specificconstraints over the entire beamline model. The ConstraintExpressions List Window (shown in Figure 48) is openedfrom the TRANSPORT Commands menu.

PBO Lab provides a ConstraintExpressions List Window that groupsall of the application-specific user-specified constraints over the entirebeamline model.

The Fitting Constraints List Window provides access to all of the TRANSPORT Fitting

Constraints for the entire beamline model

Double-Click an entry in the List Window to open the corresponding

Marker or Final Piece Window

Figure 48. Constraint Expressions List Window.

This List Window provides quick access to TRANSPORTFitting Constraints over the entire beamline. Simplydouble click an entry in the list to open the associatedMarker or Final Piece Window. Only TRANSPORTFitting Constraints are contained in this window. OtherApplications have their own List Windows that areaccessed from their respective Command Menus.

PBO Lab List Windows may be resized to accommodatethe number of entries. The columns in the List Windowsmay also be resized by placing the mouse over the columndivider in the header of the List Window. The arrow cursorwill turn into a cross-hair cursor and the column can beresized by holding down the mouse button and dragingthe column divider to the desired position.

All of the user-specified FittingConstraint Expressions for the entirebeamline model are organized in theFitting Constraint Expressions ListWindow.

List Windows may be resized toaccommodate the number of entries.Column widths can also be adjustedwithin the List Windows.


98

Perform FittingThere are two options for running TRANSPORT with the“Write Input and Run Transport” Command. TheSubmenu for this command (Figure 49), can be used torun TRANSPORT “with Fitting” or “without Fitting”.Once Fitting Variables and Constraints have been defined,the “with Fitting” option will generate the required nativeinput to execute TRANSPORT with fitting. It is notnecessary to remove Fitting Variables and Constraints fromthe beamline model in order to executeTRANSPORT without fitting. The only differencebetween the two options (with or without fitting) is thatPBO Lab will not include the FIT instruction in the nativeTRANSPORT input if “without Fitting” is selected.Otherwise the Fitting Variables and ConstraintExpressions are unchanged in the beamline model.

The “Write Input and Run Transport”Command can be used to runTRANSPORT “with Fitting” or“without Fitting”.

Run Transport Fitting from the TRANSPORT Commands Menu

Figure 49. Execute TRANSPORT and Perform Fitting.

Output File Options in theTRANSPORT Options Window can beused to specify fitting output duringand after fitting.

Output results and diagnostics for fitting are found in theTransport Output Window, which is automatically openedfollowing the execution of TRANSPORT. Output FileOptions in the TRANSPORT Options Window can be usedto specify fitting output during and after fitting.


99

After a fitting operation, FittingVariables are displayed in an UpdateWindow along with ParameterAlgebraic Expressions.

The Update Window allows you toexamine fitted parameter values andevaluated parameter expressionsbefore deciding if the beamlinemodel should be updated. Thebeamline model is not changed untilthe new values are explicitly acceptedin the Update Window.

In addition to the native Transport Output for fitting, PBOLab provides an Update Window for examining the fittedparameter values and evaluated parameter expressionsbefore deciding if the beamline model should be updatedwith any or all of these new values. The following Sectiondescribes the Update Variables & Expressions Window.

Update Variables & ExpressionsAfter TRANSPORT has completed a fitting task, the newvalues for Fitting Variables and Parameter Expressionscan be used to update Piece Parameters in the beamlinemodel. The Update Parameter Variables & ExpressionsWindow, shown in Figure 50, is automatically openedfollowing the execution of TRANSPORT. The UpdateWindow is used to examine the new values for FittingVariables and Parameter Expressions and to update thebeamline model with those values if desired.

Scrolling List of User Specified

Fitting Variables

Scrolling List of User Specified Parameter

Algebraic Expressions

Update Only Selected Variable Parameters

Update All Variable Parameters in the List

Parameter Values Before and After Fitting

Evaluated Parameter Expressions

Click on a Parameter in the List to Select it for Update

Double Click a Parameter to Open its Piece Window

Update Any or All Evaluated Parameter

Expressions

Figure 50. Update Variables and Expressions Window.

Double-click a Fitting Variable orParameter Expression to open thePiece Window for that parameter.

Both the Variables and Expressionslists have buttons for updating thespecific Piece Parameters in thebeamline model with the new valuesdisplayed in the Update Window.

Using the mouse to double-click anentry in the Update Window, willopen the Piece Window for thatparameter.

If the Update Window is closed priorto updating the beamline, then thefitting results will be disposed and thebeamline model will remainunchanged.

Refer to the “TRANSPORT UserManual” for additional informationon the TRANSPORT program.


100

The Update Window contains two scrolling lists, one forFitting Variables and the other for Parameter Expressions.The list at the top of the window displays all of the userspecified TRANSPORT Fitting Variables for the entirebeamline model along with the initial and final values.

The list at the bottom of the Update Window contains allof the Piece Parameters that have been specified byParameter Algebraic Expressions through out the beamlinemodel, along with the final evaluation of those expressions.

Both the Variables and Expressions lists have buttons forupdating the specific Piece Parameters in the beamlinemodel with the new values displayed in the UpdateWindow. The Update All Values button can be used toupdate all of the parameters in one step. Alternatively, theUpdate Selected Value button can be used to updateparameters individually. (There are identical buttons forParameter Algebraic Expressions in the lower half of thewindow.) To update Piece Parameters individually makea selection in the list of parameters and press the UpdateSelected Value button. When a selection is made in thelist it will be highlighted. Using the mouse to double-click an entry in the list will open the Piece Windowcontaining that parameter.

The Update Window can be left open and the beamlinewill not be updated with the new parameter values untilone of the Update buttons is used. However, if the windowis closed prior to updating the beamline, then the fittingresults are disposed and the beamline model will beunchanged.

This concludes the TRANSPORT Fitting Chapter andthe TRANSPORT Application Module Supplement forthe Particle Beam Optics Laboratory. Additionalinformation about the TRANSPORT program can befound in the “TRANSPORT User Manual.” Refer to thePBO Lab User Manual for general information aboutthe PBO Lab user interface..

PB

O L

abT

M

2.0

PB

O L

abT

M

2.0

Appendix: “TRANSPORT User Manual”



101

pbo lab 2 - ghgapbo lab 2.0 user manual supplement: transport module 5 figure 2 is an example of the...

Documents