tutorial.asciidoc

Back to Main Page

Table of Contents

• 1. Tutorial
  • 1.1. The Simulation Cycle
  • 1.2. Starting OPAL
  • 1.3. Auto-phase Example
  • 1.4. Examples of Particle Accelerators and Beamlines
    • 1.4.1. Laser emission, OBLA (SwissFEL test facility) 4 MeV Gun and Beamline
    • 1.4.2. PSI Injector II Cyclotron
    • 1.4.3. PSI Ring Cyclotron
  • 1.5. Translate Old to New Distribution Commands
    • 1.5.1. GUNGAUSSFLATTOPTH and ASTRAFLATTOPTH Distribution Types
    • 1.5.2. FROMFILE, GAUSS and BINOMIAL Distribution Types

1. Tutorial

This chapter will provide a jump start describing some of the most common used features of OPAL. The complete set of examples can be found and downloaded at https://gitlab.psi.ch/OPAL/src/wikis/home. All examples are requiring a small amount of computing resources and run on a single core, but can be used efficiently on up to 8 cores. OPAL scales in the weak sense, hence for a higher concurrency one has to increase the problem size i.e. number of macro particles and the grid size, which is beyond this tutorial.

1.1. The Simulation Cycle

Figure 1. The simulation cycle

1.2. Starting OPAL

The name of the application is opal. When called without any argument an interactive session is started.

\$ opal
Ippl> CommMPI: Parent process waiting for children ...
Ippl> CommMPI: Initialization complete.
>                ____  _____       ___
>               / __ \|  __ \ /\   | |
>              | |  | | |__) /  \  | |
>              | |  | |  ___/ /\ \ | |
>              | |__| | |  / ____ \| |____
>               \____/|_| /_/    \_\______|
OPAL >
OPAL > This is OPAL (Object Oriented Parallel Accelerator Library) Version 2.0.0 ...
OPAL >
OPAL > Please send cookies, goodies or other motivations (wine and beer ... )
OPAL > to the OPAL developers opal@lists.psi.ch
OPAL >
OPAL > Time: 16.43.23 date: 30/05/2017
OPAL > Reading startup file "/Users/adelmann/init.opal".
OPAL > Finished reading startup file.
==>

One can exit from this session with the command QUIT; (including the semicolon).

For batch runs OPAL accepts the following command line arguments:

Argument	Values	Function
--input	<file >	the input file. Using "--input" is optional. Instead the input file can be provided either as first or as last argument.
--info	0 – 5	controls the amount of output to the command line. 0 means no or scarce output, 5 means a lot of output. Default: 1. Full support currently only in OPAL-t.
--restart	-1 – <Integer>	restarts from given step in file with saved phase space. Per default OPAL tries to restart from a file <file>.h5 where <file>is the input file without extension. -1 stands for the last step in the file. If no other file is specified to restart from and if the last step of the file is chosen, then the new data is appended to the file. Otherwise the data from this particular step is copied to a new file and all new data appended to the new file.
--restartfn	<file>	a file in H5hut format from which OPAL should restart.
--help		Displays a summary of all command-line arguments and then quits.
--version		Prints the version and then quits.

Example:

opal input.in --restartfn input.h5 --restart -1 --info 3

1.3. Auto-phase Example

This is a partially complete example. First we have to set OPAL in AUTOPHASE mode, as described in Option Statement and for example set the nominal phase to -3.5^{\circ}). The way how OPAL is computing the phases is explained in Appendix Auto-phasing Algorithm.

Option, AUTOPHASE=4;

REAL FINSS_RGUN_phi= (-3.5/180*Pi);

The cavity would be defined like

FINSS_RGUN: RFCavity, L = 0.17493, VOLT = 100.0,
    FMAPFN = "FINSS-RGUN.dat",
    ELEMEDGE =0.0, TYPE = "STANDING", FREQ = 2998.0,
    LAG = FINSS_RGUN_phi;

with FINSS_RGUN_phi defining the off crest phase. Now a normal TRACK command can be executed. A file containing the values of maximum phases is created, and has the format like:

1
FINSS_RGUN
2.22793

with the first entry defining the number of cavities in the simulation.

1.4. Examples of Particle Accelerators and Beamlines

1.4.1. Laser emission, OBLA (SwissFEL test facility) 4 MeV Gun and Beamline

LaserEmission-1.in

All supplementary files can be found in the laser emission regression test.

1.4.2. PSI Injector II Cyclotron

Injector II is a separated sector cyclotron specially designed for pre-acceleration (inject: 870 keV, extract: 72 MeV) of high intensity proton beam for Ring cyclotron. It has 4 sector magnets, two double-gap acceleration cavities (represented by 2 single-gap cavities here) and two single-gap flat-top cavities.

Following is an input file of Single Particle Tracking mode for PSI Injector II cyclotron.

Injector2.in

The supplementary files should be placed in the same directory.

• Cav1.dat

• Cav3.dat

• ZYKL9Z.NAR

• scdist.opal

• spdist.opal

• tdist.opal

To run opal on a single node, just use this command:

 opal Injector2.in

Here shows some pictures using the resulting data from single particle tracking using OPAL-cycl.

Left plot of Figure 2 shows the accelerating orbit of reference particle. After 106 turns, the energy increases from 870 keV at the injection point to 72.16 MeV at the deflection point.

Figure 2. Reference orbit(left) and tune diagram(right) in Injector II

From theoretic view, there should be an eigen ellipse for any given energy in stable area of a fixed accelerator structure. Only when the initial phase space shape matches its eigen ellipse, the oscillation of beam envelop amplitude will get minimal and the transmission efficiency get maximal. We can calculate the eigen ellipse by single particle tracking using betatron oscillation property of off-centered particle as following: track an off-centered particle and record its coordinates and momenta at the same azimuthal position for each revolution. Figure 3 shows the eigen ellipse at symmetric line of sector magnet for energy of 2 MeV in Injector II.

Figure 3. Radial and vertical eigenellipse at 2 MeV of Injector II

Right plot of Figure 2 shows very good agreement of the tune diagram by OPAL-cycl and FIXPO. The trivial discrepancy should come from the methods they used. In FIXPO, the tune values are obtained according to the crossing points of the initially displaced particle. Meanwhile, in OPAL-cycl, the Fourier analysis method is used to manipulate orbit difference between the reference particle and an initially displaced particle. The frequency point with the biggest amplitude is the betatron tune value at the given energy.

Following is the input file for single bunch tracking with space charge effects in Injector II.

Injector2-sc.in

For the supplementary files see above, PSI Injector II Cyclotron

To run opal on single node, just use this command:

 opal Injector2-sc.in

To run opal on N nodes in parallel environment interactively, use this command instead:

 mpirun -np N opal Injector2-sc.in

If restart a job from the last step of an existing .h5 file, add a new argument like this:

 mpirun -np N opal Injector2-sc.in --restart -1

Figure 4 and Figure 5 are simulation results, shown by H5root code.

Figure 4. Energy vs. time (left) and external B field vs. track step (Right, only show for about 2 turns)

Figure 5. Vertical phase at different energy from left to right: 0.87 MeV, 15 MeV and 35 MeV

1.4.3. PSI Ring Cyclotron

From the view of numerical simulation, the difference between Injector II and Ring cyclotron comes from two aspects:

B Field

The structure of Ring is totally symmetric, the field on median plain is periodic along azimuthal direction, OPAL-cycl take this advantage to only store field data to save memory.

RF Cavity

In the Ring, all the cavities are typically single gap with some parallel displacement from its radial position.OPAL-cycl have an argument PDIS to manipulate this issue.

Figure 6. Reference orbit(left) and tune diagram(right) in Ring cyclotron

Figure 6 shows a single particle tracking result and tune calculation result in the PSI Ring cyclotron. Limited by size of the user guide, we don’t plan to show too much details as in Injector II.

1.5. Translate Old to New Distribution Commands

As of OPAL 1.2, the distribution command see Chapter Distribution was changed significantly. Many of the changes were internal to the code, allowing us to more easily add new distribution command options. However, other changes were made to make creating a distribution easier, clearer and so that the command attributes were more consistent across distribution types. Therefore, we encourage our users to refer to when creating any new input files, or if they wish to update existing input files.

With the new distribution command, we did attempt as much as possible to make it backward compatible so that existing OPAL input files would still work the same as before, or with small modifications. In this section of the manual, we will give several examples of distribution commands that will still work as before, even though they have antiquated command attributes. We will also provide examples of commonly used distribution commands that need small modifications to work as they did before.

An important point to note is that it is very likely you will see small changes in your simulation even when the new distribution command is nominally generating particles in exactly the same way. This is because random number generators and their seeds will likely not be the same as before. These changes are only due to OPAL using a different sequence of numbers to create your distribution, and not because of errors in the calculation. (Or at least we hope not.)

1.5.1. GUNGAUSSFLATTOPTH and ASTRAFLATTOPTH Distribution Types

The GUNGAUSSFLATTOPTH and ASTRAFLATTOPTH distribution types are two common types previously implemented to simulate electron beams emitted from photocathodes in an electron photoinjector. These are no longer explicitly supported and are instead now defined as specialized sub-types of the distribution type FLATTOP. That is, the emitted distributions represented by GUNGAUSSFLATTOPTH and ASTRAFLATTOPTH can now be easily reproduced by using the FLATTOP distribution type and we would encourage use of the new command structure.

Having said this, however, old input files that use the GUNGAUSSFLATTOPTH and ASTRAFLATTOPTH distribution types will still work as before, with the following exception. Previously, OPAL had a Boolean OPTION command FINEEMISSION (default value was TRUE). This OPTION is no longer supported. Instead you will need to set the distribution attribute [tab_distattremitteddist] to a value that is 10 \times the value of the distribution attribute [tab_distattruniversal] in order for your simulation to behave the same as before.

1.5.2. FROMFILE, GAUSS and BINOMIAL Distribution Types

The FROMFILE, GAUSS and BINOMIAL distribution types have changed from previous versions of OPAL. However, legacy distribution commands should work as before with one exception. If you are using OPAL-cycl then your old input files will work just fine. However, if you are using OPAL-t then you will need to set the distribution attribute INPUTMOUNITS to:

INPUTMOUNITS = EV