EXPLANATION



  MATHEMATICAL FORMULATION OF "TRANSPORT"


 General Conventions:
     A beam line is comprised of a set of magnetic elements placed
 sequentially at intervals along an assumed reference trajectory.
 The reference trajectory is here taken to be a path of a charged
 particle passing through idealized magnets (no fringing fields)
 and having the central design momentum of the beam line.
     In TRANSPORT, a beam line is described as a sequence of
 elements.  Such elements may consist not only of magnets and the
 intervals between them, but also of specifications of the input
 beam, calculations to be done, or special configurations of the
 magnets.  A certain relation, described below, of the magnets and
 their fields to the assumed reference trajectory is considered
 normal.  Alternative configurations can be described by means of
 elements provided for such purposes.
     The two coordinates transverse to the initial reference
 trajectory are labelled as horizontal and vertical.  A bending
 magnet will normally bend in the horizontal plane.  To allow for
 other possibilities a coordinate rotation element is provided.
 Because of such other possibilities, when describing bending
 magnets we shall often speak of the bend and non-bend planes.
 The transverse coordinates will also often be labelled x and y,
 while the longitudinal coordinate will be labelled z.
     All magnets are normally considered "aligned" on the central
 trajectory.  A particle following the central trajectory through
 a magnet experiences a uniform field which begins and ends abruptly
 at the entrance and exit faces of the idealized magnet.  Therefore
 through a bending magnet the reference trajectory is the arc of
 a circle, while through all other magnetic elements it is a
 straight line.  To accommodate a more gradual variation of field
 at the ends of a bending magnet a fringing field element is
 provided.  In order to represent an orientation with respect to
 the reference trajectory other than normal of a magnet or section
 of beamline, a misalignment element also exists.
     The magnetic field of any magnet, except of a solenoid, is
 assumed to have midplane symmetry.  This means that the scalar
 potential expanded in transverse coordinates about the reference
 trajectory is taken to be an odd function of the vertical coordinate.
 If a coordinate rotation is included, then the potential is odd in
 the coordinate to which the vertical has been rotated.  For a
 bending magnet this will always be in the non-bend plane.
     The program TRANSPORT will step though the beam line, element
 by element, calculating the properties of the beam or other
 quantities, described below, where requested.  Therefore one of
 the first elements is a specification of the last space region
 occupied by the beam entering the system.  Magnets and intervening
 spaces and other elements then follow in the sequence in which
 they occur in the beam line.  Specifications of calculations to
 be done or of configurations other than normal are placed in the
 same sequence, at the point where there effect is to be made.

Additional Information on:

 INPUT



 INPUT FORMAT FOR TRANSPORT


     By the TRANSPORT input DATA SET is meant the totality of data
 read by the program in a single job.  A DATA SET may consist of
 one or more problems placed sequentially.  A problem specifies a
 calculation or set of calculations to be done on a given beam
 line.
     A problem, in turn, may consist of one or more problem sets.
 The data in the first step of a problem specify the beam line and
 the calculations to be made.  The data in succeeding steps of the
 same problem specify only changes to the data given in the first
 step.
     A common example of a problem with several steps is sequential
 fitting.  In the first step one may specify that certain parameters
 are to be varied to satisfy certain constraints.  Once the desired
 fit has been achieved the program will then proceed to the next
 step.  The data in this step now need specify only which new
 parameters to vary, or old ones no longer to vary, or which
 constraints to add or delete.  The values of the varied parameters
 that are passed from one step to the next one are those that
 are the result of the fitting procedure.
     A problem step contains three kinds of DATA cards:  the TITLE
 card, the INDICATOR card, and the ELEMENT cards.
     The TITLE card contains a string of characters and blanks
 enclosed by single quotes.  Whatever is between the quotes will
 be used as a heading in the output of a TRANSPORT run.
     The second card of the input is the INDICATOR card.  If the
 data which follow describe a new problem, a zero (0) is punched
 in any column on the dard.  If the data which follow describe
 changes to be made in the previous step, a one (1) or minus 1
 (-1) is punched in any column on the card.  For further explanation
 read the Indicator Card section in this documenation.
     The remaining cards in the deck for a given problem step
 contain the DATA describing the beam line and the calculations to
 be done.  The DATA consist of a sequence of elements whose order
 is the same as encountered as one proceeds down the beam line.
 Each element specifies a magnet or portion thereof or other piece
 of equipment, a drift space, the initial beam phase space, a
 calculation to be done, or a print instruction.  Calculation
 specifications, such as misalignments and constraints, are placed
 in sequence with the other beam line elements where their effect
 is to take place.  The input format of the cards is "free-field",
 which is described below.  The data for a given problem step are
 terminated by the word SENTINEL, which need not be punched on a
 separate card.
     Each element, in turn, is given by a sequence of items (mostly
 numbers), separated by spaces and terminated by a semicolon.  The
 items, in order, are a type code number, a vary field, the
 physical parameters, and an optional label.
     The type code number identifies the element, indicating what
 sort of entity (such as a magnet, drift space, constraint, etc.)
 is represented.  It is an integer (number) followed by a decimal
 point.  The interpretation of the physical parameters which follow
 is therefore dependent on the type code number.  The type code
 numbers and their meanings are summarized in Table 1.  If the
 type code number is negative, the element will be ignored in the
 given problem step.  However, storage for that element will be
 allocated by the program, so that the element may be introduced
 in a later step of the same problem.  Storage space for any
 element in any problem step must be allocated in the first step
 of the problem.
     The vary field indicates which physical parameters of the
 element are to be adjusted if there is to be any fitting.  It is
 punched immediately (no intervening blanks) to the right of the
 decimal point of the type code number.  See the section under type
 type code 10.0 for an explanation of the use of vary codes.
     The physical parameters are the quantities which describe
 the physical element represented.  Such parameters may be lengths,
 magnetic fields, apertures, rotation angles, beam dimensions, or
 other quantities, depending on the type code number.  The meanings
 for the physical parameters of each type code are described
 thoroughly in the section for that type code.  A summary, indicating
 the order in which the physical parameters should be punched, is
 given in Table 1.  For any element the first physical parameter
 is the second entry in Table 1 or the second parameter in the
 section describing a given element.  In some cases the parameters
 of an element do not really refer to physical quantities, but
 will nevertheless be referred to as such in this manual.
     The label, if present, contains one to four characters and is
 enclosed by single quotes, slashes or equal signs.  During the
 calculation the elements will be printed in sequence and the label
 for a given element will be printed with that element.  Labels
 are useful in problems with many elements and/or when sequential
 fitting is used.  They must be used to identify any element to be
 changed in succeeding steps of a given problem.
     Provision has been made in the program to allow the user to
 introduce comments before any type code entry in the data deck.
 This is accomplished by enclosing the comments made on each card
 within single parentheses.
     Each element must be terminated by a semicolon(;). Optionally,
 a semicolon may be replaced by an asterisk (*) or a dollar sign
 ($).  Spaces before and after the semicolon are allowed but not
 required.  If the program encounters a semicolon, dollar sign or
 asterisk before the expected number of parameters has been read
 in and if the indicator card was a zero (0), the remaining
 parameters are set to zero.  If the indicator card was a one (1)
 or minus one (-1), then the numbers indicated on the card are
 substituted for the numbers remaining from the previous solution;
 all other numbers are unchanged.
     The "free-field" input format of the data cards makes it
 considerably easier to prepare input than the standard fixed-
 field formats of FORTRAN.  Numbers may be punched anywhere on the
 card a d must simply be in the proper order.  They must be separated
 by one or more blanks.  Several elements may be included on the
 same card and a single element may continue from one card to the
 next.  A single number must be all on one card, it may not continue
 from one card to the next.  The program storage is limited to a
 total of 2000 locations (including type codes and those parameters
 not punched but implied equal to zero) and 500 elements.
   A decimal number (e.g. 2.47) may be represented in any of the
 following ways:
                          2.47
                          .00247+3
                          .0247e+2
                           247e-2
                           247000-5


     The sample problem below contains two problem steps, each
 beginning with title and indicator cards and terminating with a
 SENTINEL.  The first step causes TRANSPORT to do a first-order
 calculation with fitting.  The second initiates a second-order
 calculation.  The vary codes for elements DR1 are set to zero
 for the second-order problem.  The second-order element, SEC1,
 is ineffective during the fitting, but causes the program to
 compute the second-order matrices in the second calculation.


 An Example of a TRANSPORT Input Deck:


 'FORTRAN H CHECK ON BETA FIT'       title card    \
 0                                   indicator card |
 1 .5 1 .5 1 .5 1 1 ;           \                   |
 -17  'SEC1'  ;                  |                  |
 3.3  2.745  'DR1'  ;            |                   > first problem
 2  0 ; 4 9.879 10 .5 ; 2 0 ;     >  elements       |  step
 3.3  2.745   'DR1'   ;          |                  |
 13   4   ;                      |                  |
 10 -1 2   0 .0001 'FIT1'  ;    /                   |
 SENTINEL                                          /
 'SECOND ORDER'                      title card    \
 1                                   indicator card |
 17  'SEC1'   ;                 \                   |
 3   'DR1'    ;                  >   elements to     > second problem
 -10  'FIT1'   ;                /    be changed     |  step
 SENTINEL                                          /
 SENTINEL            second Sentinel signifies end of run.


     As many problems and problem steps as one wishes may be stacked
 in one job.
     Note that in previous versions of TRANSPORT a decimal point
 was required with every numerical entry except the indicator card
 (which must not have a decimal point in any version of TRANSPORT).

Additional Information on:

 OUTPUT



 OUTPUT FORMAT


    *******************************************************
    *                                                     *
    *   This section applies only to the standard output  *
    *   generated by TRANSPORT when the TPRINT option is  *
    *   used (user specifies output file name). Else the  *
    *   output is controlled by the PLOT, BEAM, MATRIX,   *
    *   CS, TMAT, LIST, etc set of interactive commands.  *
    *                                                     *
    *******************************************************
 General Appearance:


     Here we give a brief description of the general appearance of
 the output and its meaning.  The user may refer to the sample
 output shown below.  It is the printed output resulting from the
 sample data shown in the section on input format.  In a simple
 example it is not possible to show each of the different type
 codes.  Several of the type codes produce output which is not
 characteristic of all other type codes.  We therefore refer the
 user to the sections on the various type codes for an explanation
 of any features peculiar to a given type code.
     The output for each step of a given problem is printed
 separately.  The printing for one step is completed before that
 for the next step is begun.  Therefore we will describe the output
 for a single problem step.  The output shown below is from a
 problem with two steps.


 Initial listing:


     For each problem step, the program begins by printing out the
 user's input records.  For the first problem step of a problem,
 the program also prints a column of element numbers to the left
 of the input records.  The element numbers provide a unique
 identification of each element in the system.  The element numbers
 are also printed out whenever the element is printed during
 calculation.  The element number appears between the element name
 and the type code number on the printout.


 Listing during the Calculation:


     The program now begins the calculation.  If there is no
 fitting, one listing of the beam line will be made.  If there is
 fitting there will normally be two listings.  The first will
 represent the beam line before any fitting has occurred.  The
 second will be based on the new values of the physical parameters
 which were altered by the fitting process.  If sequential fitting
 is employed and an indicator card of minus one is used the first
 run will be omitted.  The user should read the section describing
 the indicator card for further explanation.
     In any listing the elements are printed in order with their
 labels and physical parameters.  elements with negative type code
 numbers are ignored.  Each listed element is preceded by the name
 of that type of element, enclosed in asterisks.  All physical
 elements are listed in this way. Some of the other elements are
 not explicitly listed but produce their effect in either the
 calculated quantities or the listing of the  beam line.  For
 descriptions of individual cases, the reader should consult the
 sections on the type codes.
     Calculated quantities appear in the listing as requested in
 the input data.  Important cases will be described in greater
 detail below.  The physical parameters for each element are printed
 with the appropriate units.  For some elements a calculated
 quantity, not in the input data, will appear, enclosed in
 parenthesis.  Such quantities are explained in the sections under
 the individual type codes.


 Calculated Quantities:


     The important cases of calculated quantities which appear in
 the output are the transfer matrices, the beam matrix, the layout
 coordinates, and the results of the fitting procedure.  The transfer
 and beam matrices and layout coordinated appear as requested in
 the listing of the beam line.  The results of the fitting procedure
 appear between the two listings.  All these quantities are
 explained in greater detail below.
     The transfer matrices appear only where requested.  The beam
 matrix appears automatically after each element, unless suppressed
 in which case an individual printing may be requested.  A request
 for printing of layout coordinates should be made at the beginning
 of the beam line.  The coordinates will then be printed wherever
 the beam matrix appears.  In all cases the quantities printed are
 the values at the interface between two elements.  They are
 evaluated at a point after the element listed above them and
 before the element listed below.  For further explanation of
 calculated quantities the user should read the section on the
 mathematical formulation of TRANSPORT, the Appendix to the manual,
 and the section on the apropriate type code.  for the transfer
 matrix the appropriate type code is thirteen, for the beam matrix
 it is one, and for the coordinate layout it is again thirteen.
     Quantities relevant to the fitting appear between the two
 listings of the beam line.  At each iteration of the fitting
 prodedure a line is printed containing the value of the relaxation
 factor used, the value of chi-squared before the iteration was
 made, and the corrections made to each of the varied parameters.
 Once the fitting is complete the final chi-squared and the
 covariance matrix are printed.  For further details the user
 should read the section of type code 10.0, and the section on
 fitting in the Appendix.



 TYPE_CODES



 SUMMARY OF TRANSPORT TYPE CODES


   Element       Type Code  Other entries (in order)


 Beam                  1.  X(cm), Theta(mr), Y(cm), Phi(mr), Len(cm),
                           Delta(%), Po.
 Pole Face Rotation    2.  Angle of rotation.
 Drift                 3.  Length(metres)
 Bend                  4.  Length(metres), Field(kG), Field Gradient(n-value).
 Quadrupole            5.  Length(metres), Field(kG), Half-Aperture(cm).
 Centroid Shift        7.  (Shift in parameters of type 1, in same order).
 Mag Align Tolerances  8.  (see description of type  8.)
 Repetition            9.  Code digit indicating number of repetitions.
 Fitting Constraint   10.  (see description of type 10.)
 Acceleration         11.  accelerator length(m), energy gain(GeV,
                           phase lag(degrees), wavelength(cm) 
 Beam(rotated ellipse)12.  The 15 correlations (r(ij)) among the 6 beam comp.
 Input-Output         13.  (see description of type 13.)
 Arbitrary R Matrix   14.  R(j,1), R(j,2), . . ., R(j,6), j.
 Input-output Units   15.  code digit, abbrev. of unit, scale factor
 Special Input Par    16.  (see description of type 16.)
 Second-Order Calc    17.  (see description of type 17.)
 Third-Order Calc     17.  3. 
 Sextupole            18.  Length(metres), Field(kG), Half-Aperture(cm).
 Solenoid             19.  Length(metres), Field(kG).
 Beam Rotation        20.  Angle of Rotation(degrees).
 Stray Field          21.  (See later section of documentation).  (This
                            includes Steering Magnets and Fringe Fields).
 Space charge         22.  STEP(m), AMPS, FReq(0.),
 * Algebraic Comb.   
    Def. Reg. Content 22.  Code digit i, Code digit j, Register Number 
    Forming Comb.     23.  First input reg., Second input reg., Operation,
                           Output reg.
 Defined Section      24.  Code digit, Section Name (See description of
                           type code 24. for code explanation) 
 Octupole             25.  
    * Fermilab version only.

Additional Information on: