User Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 8
| Download | |
| Open PDF In Browser | View PDF |
SIMULINAC User’s Guide
v7.0.1
W.D. Klotz, wdklotz@alceli.com
October 7, 2018
1
Getting Started
SIMULINAC is a set of pure Python3 modules to simulate proton dynamics in
a LINAC lattice. It has two main modules simu.py and tracker.py. simu.py is
an envelope code and traker.py is a tracking code.
All files should be installed in a root directory like $HOME/SIMULINAC. The
Python3 executable should be on your PATH environment variable. The Python
installation must have matplotlib, numpy and pyaml installed.
To start simu.py type python simu.py .
To start tracker.py type python tracker.py .
Both will print on your terminal and before finishing display results in several
figures.
2
Preparing Input
Input to the two programs has to be provided by a text file written in YAML
syntax. The input-file is generated from a template-file also written in YAML. The
template-file contains immutable information and mutable information coded
as m4 macros. Before each program reads its input-file it invokes the m4 macro
processor which reads a macro-definition-file and replaces the macros in the
template-file.
macro-definitions
template
input
standard file names
simu.py
tracker.py
yml/macros.sh
yml/macos.sh
ymlworktmpl.yml yml/worktmpl.yml
yml/simuIN.yml yml/trackerIN.yml
1
The standard files in the distribution are good examples to see how this works.
2.1
Special Input Parameters
In the current version some input parameters have to set directly in the Python
code. The corresponding code lines are behind the if __name__ == ’__main__’:
line. For simu.py these are:
if __name__ == ’__main__’:
# launch m4 to fill macros in template file
template_file = ’yml/worktmpl.yml’
# template file
input_file
= ’yml/simuIN.yml’
# input file
macros_file
= ’yml/macros.sh’
# macro definitions
they allow to customize the standard file names.
In tracker.py the code is:
if __name__ == ’__main__’:
:
:
# launch m4 to fill macros in template file
template_file = ’yml/worktmpl.yml’
# template file
input_file
= ’yml/trackIN.yml’
# input file
macros_file
= ’yml/macros.sh’
# macro definitions
:
:
options = dict( input_file = input_file,
particles_per_bunch = 10000,
show
= True,
save
= False,
skip
= 1
The standard file names, the particles_per_bunch and the two flags show and
save can be customized here. The skip-flag is not used in this version. The
show-flag is used to switch fugures on/off. The save-flag is supposed to save
figures but is not working in this version.
3
Input File Structure
In this section the structure of the standard input-file is discussed.
2
3.1
Flags
The flags-block is used to select different features the programs provide. Both
programs have access to the flag-settings but make different use of them or
ignore them. The current set of flags is given below. The {value}s are the
default values. To change from default values the corresponding line in the
input-file has to be uncommented.
flags:
# # # # # # # # # # # -
accON:
egf:
sigma:
KVout:
periodic:
express:
useaper:
csTrak:
bucket:
pspace:
verbose:
False
True
False
True
True
True
True
False
True
True
2
#
#
#
#
#
#
#
#
#
#
#
{True} acceleration on/off flag
{False} emittance growth flag
{True} beam sizes by sigma-matrix
{False} print a dictionary of Key-Value pairs
{False} treat lattice as ring
{False} use express version of thin quads
{False} use aperture check for lattice elements
{True} plot CS trajectories
{False} plot the bucket
{False} plot the twiss ellipses at entrance
{0} print flag (0 = minimal print), try 0,1,2,3
Their use in both programs is tabeled below.
flag
accON
egf
sigma
KVout
periodic
express
useaper
csTrack
bucket
pspace
verbose
simu.py
acceleration on/off
emittance growth flag
beam sizes by sigma-matrix
no display, Key/Value dictionary only
treat lattice as ring
express version of thin quads
aperture check for lattice elements
plot CS trajectories
plot the RF bucket
plot entrance twiss ellipses
verbose level 0=minimal
tracker.py
acceleration on/off
emittance growth flag
not used
not used
meaningless
express version of thin quads
not used
not used
plot the RF bucket
not used
not used
Notes:
• egf stands for emittance growth formula. For details see the TRACE 3-D
Documentation1 .
• sigma selects the way to calculate beam envelope sigmas. If True the
sigma-matrix method is used to calulate beam sizes2 else the standard
formulas from twiss3 functions are used.
1 TRACE
3-D Documentation by K.R.Crandal, D.P.Rusthoi, 1997, Appendix F
3-D Documentation by K.R.Crandal, D.P.Rusthoi, 1997, Appendix A
3 see Snyder & Courant therory
2 TRACE
3
• KVout = True prints a long dictionary of internal parameters and supresses garaphics output.
• periodic is used for testing purposes to see if the linear matrices produce
correct results.
• express replaces thick quadrupoles by thin quadrupoles with up- and
downstream drift space.
• useapaer: in envelope calculation the transverse 1-sigma beam envelope is
checked against aperture limitations.
• pspace plots the two transverse sphase space ellipses to check for transverse
beam matching.
3.2
Sections
The sections-block can be used to divide the lattice into different sections. Sections are not mandatory. If commented the whole lattice is one single unnamed
section. If sections are defined, each element4 must be assigned a section.
sections:
- [&LE 5/30,
&HE 30/200]
Note:
• [&LE 5/30, &HE 30/200] defines a list of section tags. &LE defines a
link that can be referenced elsewhere in the YAML-file as ∗LE. The entry
behind ‘5/30’ can be any name and defines the name of the section. In
this example a shortcut for the section from 5 to 30 Mev.
3.3
parameters
The parameters-block defines global parameters as key-value pairs. Some prameters are defined with fixed values others by macro-variables.
parameters:
- Tkin:
- emitx_i:
- emity_i:
- emitw_i:
- betax_i:
- betay_i:
- phi_sync:
- alfax_i:
- alfay_i:
4 see
&emx
&emy
&emw
&btx
&bty
&phs
_TKIN
_EMITX
_EMITY
_EMITW
_BETAX
_BETAY
_PHISY
0.
0.
Elements below
4
#
#
#
#
#
#
#
#
#
[MeV] energy @ entrance (injection)
[m*rad] {x,x’} emittance @ entrance
[m*rad] {y,y’} emittance @ entrance
[rad] {Dphi,w} emittance @ entrance
[m] twiss beta @ entrance x
[m] twiss beta @ entrance y
[deg] synchronous phase
[1] twiss alpha x @ entrance
[1] twiss alpha y @ entrance
-
frequency:
ql0:
ql:
quad_bore:
windings:
gap:
n_sigma:
aperture:
&p01
&p02
&p03
&p04
&p15
816.e+6
0.10
0.05
0.011
30
0.048
10
15.e-3
#
#
#
#
#
#
#
#
[Hz] frequency
[m] quad-length
[m] 1/2 quad-length
[m] quad bore radius
[1] quad-coil windings
[m] RF gap
[m] sigma aperture
[m] global aperture setting (default = None)
Notes:
• Tkin: is the key for the kinetic energy at injection in [Mev]. Its value is
the macro-name TKIN.
• emitx i: is the transvese emmittance in x-plane in [m ∗ rad]. Its value is
the macro-name EMITX and &emx its link-id.
• aperture has a fixed value of 15. ∗ 10−3
3.4
elements
The elements-block defines the elements (a.k.a nodes) in the lattice.
elements:
# HE
- D3:
&D3
- type:
D
- length:
0.08
- sec:
*HE
- D5:
&D5
- type:
D
- length:
0.022
- sec:
*HE
- QFH:
&QFH
- type:
QF
- length:
*p03
- aperture: *p04
- B’:
&Bgrad
- slices:
0
- sec:
*HE
- QDH:
&QDH
- type:
QD
- length:
*p02
- aperture: *p04
- B’:
*Bgrad
- slices:
0
- sec:
*HE
#
#
#
#
#
#
#
#
30. #
#
#
5
ID:&link
type:class
[m]
section
ID:&link
type:class
[m]
[m] quad bore
[T/m] gradient
slices
section
- RFGH: &RFGH
#
- type:
RFG
#
- EzAvg:
1.00
#
- EzPeak:
1.40
#
- PhiSync: *phs
#
- fRF:
*p01
#
- gap:
*p15
#
- aperture: *p04
#
- aperture: 10.e-3
#
- SFdata:
SF_WDK2g44.TBL
- mapping:
t3d
#
- mapping:
simple
#
- mapping:
base
#
# - mapping:
ttf
#
# - mapping:
dyn
#
:
:
ID:&link
type:class
[MV/m] average E-field
[MV/m] peak E-field
[deg] synchronous phase
[Hz] frequency
[m] length
[m] quad bore
[m] quad bore
# superfish tbl-data file
Trace 3D linear map model
Shishlo/Holmes linear map model
Shishlo/Holmes base map model
Shishlo/Holmes three point TTF RF gap-model
Tanke/Valero RF gap-model
Notes:
•
- D3:
&D3
- type:
D
- length:
0.08
- sec:
*HE
#
#
#
#
the node-ID is D3, link-id is &D3
dipole node
[m]
section
type:D defines the node as an object of class ‘D’, which is a dipole.
length:0.08 defines its length in [m] and sec:∗HE says that this dipole
belongs to section ‘HE’ by reference.
•
- QFH:
&QFH
- type:
- length:
- aperture:
- B’:
- slices:
- sec:
#
#
#
#
30. #
#
#
QF
*p03
*p04
&Bgrad
0
*HE
ID:&link
type:class
[m]
[m] quad bore
[T/m] gradient
slices
section
The type:QF defines an x-focussing quadrupole. It has attributes length,
aperture, B’, slices and belongs to a section. ∗p03 and ∗p04 are references
to links. B’ has the value of 30. [T /m] and defines a link-id &Bgrad. The
slices attribute defines the number of slices a thick node is cut into. slices
= 0 or 1 means don’t slice the thick node. slices = n means means cut it
into n slices. The sec attribute references the HE section.
•
- RFGH: &RFGH
- type:
- EzAvg:
- EzPeak:
- PhiSync:
#
#
#
#
#
RFG
1.00
1.40
*phs
6
ID:&link
type:class
[MV/m] average E-field on axis
[MV/m] (EzAvg = 1.00[MV/m])
[deg] synchronous phase
#
#
-
fRF:
*p01
#
gap:
*p15
#
aperture: 10.e-3
#
SFdata:
SF_WDK2g44.TBL
mapping:
t3d
#
mapping:
simple
#
mapping:
base
#
- mapping:
ttf
#
- mapping:
dyn
#
sec:
*HE
#
[Hz] frequency
[m] length
[m]
# superfish tbl-data file
Trace 3D linear map model
Shishlo/Holmes linear map model
Shishlo/Holmes base map model
Shishlo/Holmes three point TTF RF gap-model
Tanke/Valero RF gap-model
section
The type:RFC defines a radio frequency cavity. It is modeled as a kick of
zero length. EzAvg is the average E-field on the axis E(r=0,z). PhiSync
is the synchronous phase in [deg]. It takes its value from the link reference
∗phs. fRF is the rf frequency in [Hz] given here from the link reference
∗p15. aperture is the cavity bore radius. SFdata is the file name of a table
for field profile data from ‘SuperFish’. The mapping attribute specifies
which cavity model to use. The cavity node is part of section HE - sec
attribute.
3.5
segments
segments:
# LE
# empty section
# HE
# high energy section
- SEG1H:
- *QFH
- *D3
- SEG2H:
- *D3
- *QDH
- *D3
- SEG3H:
- *D3
- *QFH
- RFGH:
- *D5
- *RFGH
- *D5
#
- *D5
- *RFGH
- *D5
#
- *D5
7
#
#
#
#
#
#
#
#
#
#
#
*RFGH
*D5
*D5
*RFGH
*D5
*D5
*RFGH
*D5
*D5
*RFGH
*D5
*D5
*RFGH
*D5
*D5
*RFGH
*D5
*D5
*RFGH
*D5
- *D5
- *RFGH
- *D5
# 10th cavity makes it unstable!!
8
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Count : 8 Producer : pdfTeX-1.40.18 Creator : TeX Create Date : 2018:10:07 23:55:33+02:00 Modify Date : 2018:10:07 23:55:33+02:00 Trapped : False PTEX Fullbanner : This is pdfTeX, Version 3.14159265-2.6-1.40.18 (TeX Live 2017) kpathsea version 6.2.3EXIF Metadata provided by EXIF.tools