Beamopt User Guide

SL/EA/LG January 6, 1999

BEAMOPT

( Version 3.0 on RSPLUS)

L. Gatignon/ SL-EA

Abstract

The BEAMOPT program is a utility, originally implemented on VM/CMS and now ported to CERNSP, that helps the preparation of colour optics drawings for the SPS secondary beams. The program makes this task semi-automatic by taking its input from Beatch and Transport outputs.

Nevertheless some 'operator intervention' remains necessary mainly for the final naming of elements and positioning of comments in the figure. However, these 'manual' interventions are easy and fast modifications in a standard text file, e.g. by using the EMACS text editor. A large amount of flexibility exists in redefining standard paper layouts and default colours. However, the standard settings should provide adequate results without the user having to worry. If it is preferrable to quickly make a plot, just showing the optics, but no instrumentation, another program exists to do so: BEAMPLT.

The program should be easy to use, but all ideas, comments and suggestions for improvement are welcomed. Also at the moment the programis in its very first version and remaining small bugs may still exist. Please report them to the author!

BEAMOPT

1. General Introduction

A large amount of flexibility exists in redefining standard paper layouts and default colours. However, the standard settings should provide adequate results without the user having to worry.

The package consists of the following files:

beamopt	The main EXEC that allows to steer the program execution and define the input files and options.
beamopt.panel	The description of the panel from which you control the job.
beamopt.maggaps	Apertures for standard beam magnets.
beamopt.colours	Standard colour settings.
beamopt.monochr	Colour settings for monochrome printers.
beamopt.a4p	Standard paper layout for A4 portrait format.
beamopt.a4l	Standard paper layout for A4 landscape format.
beamopt.a3l	Standard paper layout for A3 landscape format.
beamopt1.f	Source code for preparation of plot description file, starting from Beatch and Transport output.
beamopt1.out	The executable version of beamopt1.f .
beamopt2.f	Source code for preparation of plot from the plot description file.
beamopt2.out	The compiled version of beamopt2.f .

All these files reside, like the other SL-EA specific utilities, in the SL-EA group folder /afs/cern.ch/user/e/eagroup/public, which you have probably anyway attached automatically all the time through your PROFILE EXEC procedure.

The graphics package used is the HIGZ interface to GKS.

As you may have seen from the above list, the program runs in two separate steps:

BEAMOPT1 reads the Beatch and Transport output files, selects and merges the relevant informations and writes a 'draft version' of the plot description file. This standard text file will have the same filename as the Transport file, but it will be stored in your folder ~/private/layodata. The Beatch and Transport outputs are assumed to be in their standard locations, namely in the folders ~/private/beatchout and ~/private/transout, respectively.
BEAMOPT2 reads the plot description file and produces a postscript file that can be sent to your favourite postscript printer. Only at this second stage you define the scale factors for longitudinal and transverse dimensions and for the optics trajectories. The postscript file will be written into foder ~/private/beamoptps and have the transport filename with extension .ps .

Both beamopt1 and beamopt2 produce log-files in ~/private/beamopttmp. In there also an intermediate file, called cards, is created for job control.

The BEAMOPT steering procedure allows you to select which of the steps should be run (either one or both). This strategy allows to make small modifications to the plot by making only fast and easy changes to the plot description file. In fact it is quite difficult for a program to decide where e.g. to put various comments or to change the colour for one specific element, whereas it is quite straightforward to do so for the user.

Therefore the non-expert user only intervenes at the level of the plot description file. Expert users may also make private and modified copies of the default setting files. The only other modifications occur at the level of the Beatch input file, where the element types should be made more specific for the purpose of plotting.

2. Preparations for the creation of the Plot Description File

The Plot descripton file is prepared from Transport and Beatch output files. These files are standard, with the following exceptions:

The transport output should contain the table of optical coefficients, that are generated by the card " 13. 41. ; ". Also it is useful to specify at the initial target and at the end a drift space with zero length: " 3.0 0.0 ;".
The element types normally known to and used by Beatch are the following:

1 Drift space
2 Focussing quadrupole
3 Defocussing quadrupole
4 Horizontal bending magnet
5 Vertical bending magnet
8 Tilted magnet

All other elements are considered as drift spaces. In fact all types lead to an identical treatment in Beatch, with the exception of types 4, 5 and 8 that allow a bending angle to be defined. Note that type 8 is the only one that allows a tilted bend.

For BEAMOPT a more specific list is required. Typically there are many drift spaces in a Beatch output and they should normally not appear in the optics plot. Therefore we require a more explicit list, following the definitions in Table 1. All types occur on the plot, except type 1. For every type a name has been defined, such as BENDH for type 4. The fifth character (H, V or T) specifies in which plane the element is drawn. Tilted elements (T) are drawn in both planes. Note that for quadrupoles H and V define the plane in which the quadrupole is focussing. For quadrupoles the types in Beatch will be overruled by the field integrals in the transport output. Quadrupoles with zero current will appear as QUADT.

These changes should not interfere with the normal functioning of Beatch.

Type

Name

Description

1

DRIFT

Drift space, not indicated

2

QUADH

Horizontally focussing quadrupole

3

QUADV

Vertically focussing quadrupole

4

BENDH

Horizontal Bend

5

BENDV

Vertical Bend

6

DETEH

Horizontal detector

7

DETEV

Vertical detector

8

BENDT

Tilted Bend
If tilt angle < 2^o away from horizontal ® horizontal bend
If tilt angle < 2^o away from vertical ® vertical bend

9

DETET

Detector in both planes

10

COLLH

Horizontal slit

11

COLLV

Vertical slit

12

COLLT

Slit in both planes (e.g. TAX holes)

13

TRIMH

Horizontal Trim

14

TRIMV

Vertical Trim

15

TRIMT

Tilted Trim

16

DUMPT

Dump (mobile or not)

17

CONVT

Absorber or converter

18

SEXTT

Sextupole

19

MULTT

Higher order multipole

20

TARGT

Target

21

THRET

Threshold Cerenkov

22

CEDAT

CEDAR Cerenkov

Table 1

Once you have prepared the Transport and Beatch output files you can invoke BEAMOPT simply by typing beamopt. As a result a panel will show up on your screen. An example is shown in figure 1. Only part of the inputs on the panel control BEAMOPT1. Some of the parameters affect only the plot creation in BEAMOPT2 and will be described in section 3.

******************* BEAMOPT JOB SUBMISSION MAIN PANEL ************


   Selected input files are :
        Transport :    X7TRANS               Start at :    0.000 (m)
        Beatch    :    X7BEATCH              Start at :   77.207 (m)
 
            (space foreseen for warning messages)     
 
 ________________________________________________________________________________

   Paper format :  A3L            Length scale     :    10.0 m  per cm
   Size of names : 0.20           Transverse scale :    20.0 mm per cm
 
   Optics term  :   R11       R12       R33       R34       R16       R36
   Scale factor :   1.0       1.0       1.0       1.0       1.0       1.0

                  (mm/mm)   (mm/mr)   (mm/mm)   (mm/mr)   (mm/pct)  (mm/pct)
 
   Prepare new file,   Overwrite old one   (option 1)
   OR produce new plot from existing file (option 2)            Option:  1
 
   Colour/BW (B/W)?  C         Workstation type?   5005          Print?    N

                                                                                
    <CR>:Run    <PF1>:Run    <PF3>:Quit

Figure 1

First you have to specify the filenames of the Beatch and Transport output files. They are assumed to be in the ~/private/beatchout and ~/private/transout folders as usual.

As Beatch and Transport do not always start from an identical longitudinal position, you also need to specify where you want to start in each of the two outputs (position in meters). The program synchronises itself, assuming that positions correspond to within ± 25 cm. In case of discrepancy the Beatch position has priority.

The name of each element on the plot is taken from the comment in Beatch. Therefore it is a good habit to specify adequate names as comments (such as B3, Q18, TRIM4) in the Beatch files.

Finally in the Beamopt panel you have to activate the option 1 to create a new datafile, which may very well overwrite an existing old one (be careful!).

3. Preparation of a plot starting from the Plot Description File

The BEAMOPT2 program prepares a postscript file starting from the Plot Description file. The Plot Description File has a fairly rigid format, in particular the colums have to be respected rigorously (due to Fortran formatted read). The file contains several sections:

1. A short header, containing mainly a reference to the Beatch and Transport files used as an input.

2. The main part of the file contains a list of all active elements with their properties, positions and (in the case of magnetic elements) the main optics coefficients (R11 , R12 , R16 , R33 , R34 and R36 ). The format of this section is described in table 2. It ends with a card containing 'FINIS' in columns 2-6. The user may decide to add, modify or delete cards. However, the order of the longitudinal positions along the beamline should be respected.

3. A list of comments (up to 50 characters long) to be printed on the plot. This section also ends with a card containing 'FINIS' in columns 2-6. Each comment text is followed by its position (left adjusted) in centimeters X (col. 52-61), Y (col.62-71) , angle in degrees (col. 72-81), character size (col. 82-91), colour (col. 101) and page-number (col. 111). The automatically generated LAYODATA file contains a single comment, namely the title of the Transport run.

4. A section of 7 lines indicating the positions of some standard comments. The six lines starting with R11 to R36 specify the positions in cm X (col. 12-21) and Y (col. 22-31), angle in degrees (col. 32-41), character size (col. 42-51) and page number (col 61). The seventh line, starting with RSC, gives the position of the scale description arrows X (col. 12-21) and Y (col.22-31). These arrows are always printed on the last page. This section also ends with a FINIS card.

Columns	Description
2 – 5	Type of element, e.g. BEND, QUAD, SLIT
6 – 6	Plane, namely H, V and T (indicating Tilted = Both planes) For quadrupoles the plane indicates the focussing plane
8 – 16	Horizontal aperture or size
18 – 26	Vertical aperture or size
28 – 36	Length of element
38 – 46	Central coordinate
48 – 56	Name of element
58 – 66	Comment to be printed
68 – 70	'To be completed' indications: A: Aperture size to be defined B: Colour to be defined C: Ambiguity in magnet gap D: Quadrupole polarity missing
71 – 80	R11 coordinate
81 – 90	R12 coordinate
91 – 100	R16 coordinate
101 – 110	R33 coordinate
111 – 120	R34 coordinate
121 – 130	R36 coordinate
131 – 133	Colour index

Table 2

The available colours and line styles are shown in tables 3.a and 3.b, respectively.

Colour index

Colour

1

Black

2

Red

3

Green

4

Pink

5

Yellow

6

Magenta

7

Blue

8

White ( invisible ! )

Table 3a

Style index

Line style

1

Solid

2

Dashed

3

Dotted

4

Dash-dotted

Table 3b

For the creation of the Plot Description file ("Transport-filename LAYODATA") you have to specify:

the filename of the Transport output (Beatch filename no more necessary),
the scaling factors for the optics trajectories (0.0 means that that trajectory will not be drawn),
the paper format (e.g. A4L for A4 landscape, A4P for A4 portrait mode),
The length scale and transverse scale,
The character size for the element names.

In addition one has to activate the option 2 to prepare a new plot from an old file.

As already mentioned above, you may and must modify this LAYODATA file for good results. In figure 2 a plot is shown as produced from the initial LAYODATA file. You see immediately that the main comment (FIGURE 2 etcetera) as well as the scaling factors for the optics trajectories are badly positioned. Also some elements may overlap, leading to unreadable element names. An example of a LAYODATA file is shown in Table 4. This file has been modified already for nicer results.

The paper format is specified in files called beamopt.axx, where the filetype axx indicates the paper format. An example of such a file is listed in Table 5. Available types are a4p, a4l and a3l. Other files may be created by the user. The paper format definition has to take into account the edges of the paper on which most printers cannot print.

A4P                                    PORTRAIT FORMAT                        
PSTPC     -4111                        POSTSCRIPT OPTION IN GRCONV            
20.0      1.0                          HORIZONTAL PAPER SIZE AND OFFSET       
29.0      0.0                          VERTICAL PAPER SIZE AND OFFSET       
 6.5      23.0                         AXIS POSITIONS                       
 0.5      16.5                         NAME POSITIONS                        
12.0      27.0                         COMMENT POSITIONS                      
15.75     1.0                          VERTICAL SCALE POSITION/COLOUR

Table 5

Therefore an effective paper size and offsets are defined as shown in Figure 3. From the paper size and the length scale the number of pages is calculated. The maximum number of pages is 10.

Figure 3

The default colours are defined in a file called beamopt.colours. This file is listed in Table 6. For black-and-white printers a different file is used: beamopt.monochr. This option can be selected in the panel by typing a B in the appropriate case.

  ITYP TYPE    COL     THICK     STYLE
    1  DRIFT     0         1         1 
    2  QUADH     7         1         1
    3  QUADV     7         1         1
    4  BENDH     7         3         1
    5  BENDV     7         3         1
    6  DETEH     3         1         1
    7  DETEV     3         1         1
    8  BENDT     7         3         1
    9  DETET     3         1         1
   10  COLLH     2         1         1
   11  COLLV     2         1         1
   12  COLLT     2         1         1
   13  TRIMH     6         1         1
   14  TRIMV     6         1         1
   15  TRIMT     6         1         1
   16  DUMPT     1         1         1
   17  CONVT     4         5         1
   18  SEXTT     1         1         1
   19  MULTT     1         1         1
   20  TARGT     4         5         1
   21  THRET     3         2         2
   22  CEDAT     1         2         2  
     FINIS
       R11       3         3         2
       R12       2         3         1
       R16       4         3         3
       R33       3         3         2
       R34       2         3         1
       R36       4         3         3
    FINIS

Table 6

A final option is the workstation type in HIGZ. The default type, 7878, is correct for Macintoshes with a vt100 emulator, as well as for NCD X-terminals. For other terminal types you may have to change this number. Please consult the HIGZ manual for details.

In the beamopt.axx files you will find the POSTSCRIPT conversion mode. To define the paper format one has to define the Postscript workstation type in HIGZ. For a detailed definition, see section 3.3.2 of the HIGZ manual (version of October 1993). This value is right adjusted in columns 10-15 and is –N111 for portrait and –N112 for landscape where N denotes the paper size AN.

Note that BEAMOPT will automatically overwrite the LAYODATA file, unless you select "2" for the option "Create new plot from an existing file".

4. Modifying and final layout of the plot

The raw version of the plot is typically not good enough for distribution and some interventions are required. Usually these interventions should be done at the level of the LAYODATA file, using e.g. emacs or nedit. The common modifications are listed below:

1. Sometimes two elements are so close that their symbols or text labels overlap. The easiest way out is to 'fudge' the longitudinal positions by a small amount, so that the labels become separate again and the essence of the information content remains valid.

2. Sometimes you may decide to change the name of an element to something different from Beatch. This is easily done by changing the decsription in colums 58-66 of the LAYODATA file.

3. If no special colour is indicated in column 133, the default colour will be taken. If you specify some non-zero number in column 133, this will override the standard, which is defined in Table 6.

4. Comments may be moved by changing the X,Y positions. More comments may be added if you wish (up to 20 are allowed). You can also change the character size, angle (in degrees) and colour. See under section 2 ( point 3) for details on the format.

5. The indications of the scale factors for the optics trajectories are printed by default at the beginning of the beamline. You may wish to move their positions to a convenient and empty part along the beamline. The angle can be adapted to the local slope of the trajectory (in degrees).

6. The 1 cm long arrows with scale information are printed at a somewhat random location, compatible with every reasonable page format. It is always printed on the last page.

The modifications listed above have already been applied to the LAYODATA file listed in Table 4. The resulting plot is shown in Figure 4. The paper format used in this example was A4L.

5. How to print or look at the plots

Normally the postscript file can be printed on any Postscript compatible laserprinter connected to Ethernet and declared on the Springer service, by typing

xprint filename .ps -Pprinter-name

In building 866 the printers that we commonly use are called 866_2_d11_ps (in the EA archives), 866_1_ps and 866_1_a04_cj (in the helio room on the first floor).

Before printing on 866_1_a04_cj one should make sure (before printing) that the correct paper and paper format have been selected on the printer. Unfortunately in the case of the Lexmark colourjet printer, this can only be done locally.

The plots can be inspected on RSPLUS using one of the several Postscript viewers, e.g. ghostview or gv. On the PC a Postscript viewer is available under Nice via Start -> More Applications -> Shareware -> 4 - Postscript Viewer. On the Macintosh a shareware programme Mac GS allows to look at the file.

Modifying the Postscript file is not so easy. One possibility is to FTP the file from RSPLUS to your Nice-PC, then import the Postscript file into Designer version 7 and modify it there.

6. Final remarks from the author

As mentioned before, this is a very first version of the programme. On the few optics that I have tried, it seems to work. Nevertheless the package contains some 2,000 lines of code and it is difficult to exclude bugs at this stage. But do not hesitate to give it a try and report any bugs, comments and suggestions for improvement.

Even though the creation of plots is not yet fully automatic, I hope that the program makes it easy and fast enough to allow our sets of plots in the handbooks to be more up-to-date than in the past.

7. New features of versions 2.0 and 3.0

1. Several small bugs repaired.

2. Element types 21 (Threshold Cerenkov) and 22 (CEDAR) added.

3. Monochrome option added.

4. Workstation type can be redefined interactively.

5. More appropriate defaults in panel for Beamopt phase 2.

8. Appendix: How to modify existing Postscript files on your Macintosh ?

The Postscript files coming from a mainframe are usually not directly readable by the more common Macintosh drawing programmes. However, there is a public domain utility that allows previewing of such Postscript files on your Macintosh and even to convert it into Pict2 format, which can be read by e.g. MacDraw II and GraphicsConverter. The program is called Ghostscript and can be found on the Mac-DC server. You may get hold of it as follows:

Go into Chooser
Select Appleshare zone AS
Select the Mac-DC file-server
Connect to it as guest
Select the Public Domain item
Copy the folder MacGS 2.5.2 ß2 Runtime to your hard disk.

The latter folder contains the programme Ghostscript 2.5.2 ß3. After having copied it, click once on its icon, type Command-I (or Get Info in the Files menu) and change the memory size to at least 2048k. Never change names inside the MacGS folder, as the the Ghostscript software uses hardwired file references. Also it should be noted that Ghostscript is incompatible with the 'Be Hierarchic' control panel. The latter utility (if used on your Mac) should therefore be removed from your system folder.

To preview the Postscript file, you should run through the following steps:

Start the Ghostscript program
In the MacGS menu: Load Laserprep
Open File . .
Resume (at the end of each page)
Graphics Window (to see the full plot)
Save File (to create a Pict2 file)
In the File menu : Quit

The Pict2 file can be read and modified with most Macintosh graphics programs, e.g. by MacDraw.

Lau Gatignon, 6 January 1999

1	Drift space
2	Focussing quadrupole
3	Defocussing quadrupole
4	Horizontal bending magnet
5	Vertical bending magnet
8	Tilted magnet

Type	Name	Description
1	DRIFT	Drift space, not indicated
2	QUADH	Horizontally focussing quadrupole
3	QUADV	Vertically focussing quadrupole
4	BENDH	Horizontal Bend
5	BENDV	Vertical Bend
6	DETEH	Horizontal detector
7	DETEV	Vertical detector
8	BENDT	Tilted Bend If tilt angle < 2^o away from horizontal ® horizontal bend If tilt angle < 2^o away from vertical ® vertical bend
9	DETET	Detector in both planes
10	COLLH	Horizontal slit
11	COLLV	Vertical slit
12	COLLT	Slit in both planes (e.g. TAX holes)
13	TRIMH	Horizontal Trim
14	TRIMV	Vertical Trim
15	TRIMT	Tilted Trim
16	DUMPT	Dump (mobile or not)
17	CONVT	Absorber or converter
18	SEXTT	Sextupole
19	MULTT	Higher order multipole
20	TARGT	Target
21	THRET	Threshold Cerenkov
22	CEDAT	CEDAR Cerenkov

Colour index	Colour
1	Black
2	Red
3	Green
4	Pink
5	Yellow
6	Magenta
7	Blue
8	White ( invisible ! )