Code indexing in gitaly is broken and leads to code not being visible to the user. We work on the issue with highest priority.

Skip to content

Changes

Page history
add tutorial chapter authored by snuverink_j's avatar snuverink_j
Hide whitespace changes
Inline Side-by-side
tutorial.asciidoc 0 → 100644
View page @ 7c3bd344
:toc:
[[chp:opalcycl]]
:stem: latexmath
:sectnums:
[[chp:tutorial]]
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.
[[starting-opal]]
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: +
[cols="<,<,<",]
|=======================================================================
|--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
....
[[sec:trackautoph]]
Auto-phase Example
~~~~~~~~~~~~~~~~~~
This is a partial complete example. First we have to set _OPAL_ in
`AUTOPHASE` mode, as described in Section <<option>> and for example set
the nominal phase to latexmath:[-3.5^{\circ}]). The way how _OPAL_ is
computing the phases is explained in Appendix <<autophasing>>.
....
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.
[[sec:examplesbeamlines]]
Examples of Particle Accelerators and Beamlines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
....
include::examples/OBLA-Gun/OBLA-Gun.in[]
....
[[sec:felinj]]
PSI XFEL 250 MeV Injector
^^^^^^^^^^^^^^^^^^^^^^^^^
....
include::examples/diagnostic.in[]
....
[[sec:inj2]]
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.
....
include::examples/opal-cycl.in[]
....
To run opal on a single node, just use this command:
....
opal testinj2-1.in
....
Here shows some pictures using the resulting data from single particle
tracking using _OPAL-cycl_.
Left plot of Figure <<Inj2ref,1>> 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.
[#Inj2ref]
.Figure 1 : Reference orbit(left) and tune diagram(right) in Injector II
image:figures/cyclotron/AEO_Injector2.png[width=375]
image:figures/cyclotron/nurnuz_Inj2.png[width=375]
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 <<eigen,2>> shows the eigen ellipse at symmetric line of sector
magnet for energy of 2 MeV in Injector II.
[#eigen]
.Figure 2 : Radial and vertical eigenellipse at 2 MeV of Injector II
image:figures/cyclotron/RadialEigen_Inj2.png[width=375]
image:figures/cyclotron/VertEigen_Inj2.png[width=375]
Right plot of Figure <<Inj2ref,1>> 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.
....
include::examples/opal-cycl-sc.in[]
....
To run opal on single node, just use this command:
....
# opal testinj2-2.in
....
To run opal on N nodes in parallel environment interactively, use this
command instead:
....
# mpirun -np N opal testinj2-2.in
....
If restart a job from the last step of an existing file, add a new
argument like this:
....
# mpirun -np N opal testinj2-2.in --restart -1
....
Figure <<cyclParameters,3>> and <<cyclphasespace,4>> are simulation results, shown by
H5ROOT code.
[#cyclParameters]
.Figure 3 : Energy Vs. time (left) and external B field vs. track step (Right, only show for about 2 turns)
image:figures/cyclotron/Inj2-ENERGY-TIME.png[width=375]
image:figures/cyclotron/Inj2-B-ref-z-TrackStep.png[width=375]
[#cyclphasespace]
.Figure 4 : Vertical phase at different energy from left to right: 0.87 MeV, 15 MeV and 35 MeV
image:figures/cyclotron/Inj2-z-pz-step-870KeV.png[width=250]
image:figures/cyclotron/Inj2-z-pz-step-15MeV.png[width=250]
image:figures/cyclotron/Inj2-z-pz-step-30MeV.png[width=250]
[[sec:Ring]]
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.
[#Ringref]
.Figure 5 : Reference orbit(left) and tune diagram(right) in Ring cyclotron
image:figures/cyclotron/AEO_Ring.png[width=375]
image:figures/cyclotron/nurnuz_Ring.png[width=375]
Figure <<Ringref,5>> 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.
[[sec:oldtonewdist]]
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.)
[[sec:oldtonewdistgungaussandastra]]
`GUNGAUSSFLATTOPTH` and `ASTRAFLATTOPTH` Distribution Types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The `GUNGAUSSFLATTOPTH` and `ASTRAFLATTOPTH` distribution types
see Section <<gungaussflattopthdisttype,astraflattopthdisttype>> 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 `EMISSIONSTEPS` see Table <<distattremitted>> to a
value that is 10 latexmath:[\times] the value of the distribution
attribute `NBIN` see Table <<distattruniversal>> in order for your
simulation to behave the same as before.
[[fromfile-gauss-and-binomial-distribution-types]]
`FROMFILE`, `GAUSS` and `BINOMIAL` Distribution Types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The `FROMFILE` see Section <<fromfiledisttype>>, `GAUSS`
see Section <<gaussdisttype>> and `BINOMIAL`
see Section <<binomialdisttype>> 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` see Section <<unitsdistattributes>> to:
....
INPUTMOUNITS = EV
....