TraceWin
D. Uriot, N. Pichoff
Université ParisSaclay, CEA, Département des Accélérateurs, de la Cryogénie et du Magnétisme, 91191, GifsurYvette, France.
Updated, Mai 14, 2024
The TraceWin code calculates the beam dynamics in a particle accelerator. The beam is modelled both by its secondorder momentum (fast computation, in linearised force) and/or by a macroparticle distribution (longer computation, in nonlinear forces). Their simultaneous use makes it easy to study the influence of nonlinear effects.
The different elements of a linac can be modelled either by analytical expressions or by field maps. The code is able to perform automatic procedures of accelerator and beam tuning, including statistical errors on elements and diagnostics.
TraceWin uses a very powerful GUI capable of providing a wide variety of plots. The user can modify any parameter and observe the effect very easily with the very powerful graphical display that allows visualising most of the useful parameters of the simulation (envelopes, beam ellipses, emittances, phase advances...). All this output can be easily saved to disk, saved in various image formats and inserted into reports (using copy and paste tools).
A large number of cases can be simulated remotely via a homemade client/server architecture. A heterogeneous array of machines can be used (Windows, Linux, MacOS). It is mainly written in C++ and Qt5.4 for Windows, Linux and MacOS operating systems. Started in 1998 (URIOT Didier and PICHOFF Nicolas), it is distributed under CEA licence since 2009.
Technical support & maintenance services
Using TraceWin in a batch command
Develop its own element or diagnostics
RF cavity transient analysis with TraceWin
CEA agrees to provide Licensee with updates and corrected versions of the Software. The content of Updates will be determined by CEA in its sole discretion and will include bug fixes, improvements and upgrades to bring the Software up to date with the latest version of the Software. However, Updates may not include: versions of the Software that are compatible with new operating systems, improvements, updates or new versions that are sold separately.
Updates and Corrected Versions shall be made available to Licensee in executable form by email in the manner specified by CEA.
CEA agrees to correct reproducible errors in the software programming. The Licensee shall notify CEA of any unidentified error and provide CEA with all information necessary to reproduce the error. The means used by CEA to correct an error will depend on the seriousness of the error.
If the error is due to a modification not made by or expressly authorised by CEA, the Licensee agrees to reimburse CEA for the time spent in correcting the error and restoring the Software to good working order, at CEA's rates in force at the time.
The CEA shall provide technical support to the Licensee during its normal office hours, Monday to Friday (excluding bank holidays and annual closing weeks). The CEA will use its best efforts to provide a detailed response within a maximum period of thirty (30) business days depending on the human resources available at the time of the request.
Requests should be sent to the CEA by email to the contact address setout below. The Code can be downloaded at: http://irfu.cea.fr/Sacm/logiciels/ .
The CEA will add new features to the Software as required by a changes in the legal or regulatory requirements or in the software or hardware environment. New versions shall be made available to the Licensee, in executable form by email in the manner specified by the CEA.
This version of TraceWin is maintained by Didier URIOT. We would appreciate to hear from you if you have a bug. You can send your questions or comments to the following emails address:
Very important: How to report a bug: Please use the button “Send project” on the main page and attach the specified files. In this way we will be able to know which system you are using and which version produced the bug and finally with the include files we can easily reproduce it and thus fix it
New: since December 2020, our communication policy regarding hotline, requests, bugs, help or more generally any question related to this software has evolved. We now offer an exchange via a dedicated forum: https://dacmcodes.fr/forum/
1 gigahertz (GHz) or faster 32bit (x86) or 64bit (x64) processor
1 gigabyte (GB) RAM (32bit or 64bit)
30 megabytes (MB) available hard drive space (32bit or 64bit)
Operating system:
Window (32bit or64bit), version equal to or greater then WinXp
Linux (32bit or64bit) with GLIBC library version equal to or greater than 2.6 (“ldd version”)
MacOS with system version equal to or greater than 10.6
You're on a 64bit system, you probably don’t have 32bit library support installed. It’s mandatory for the defaut WebBrowser, QtWeb, internally used to get direct access to manual and also if want to use a 32bits TraceWin version.
(if you don't use sudo in your setup read note below)
Most desktop Linux systems in the Fedora/Red Hat family:
pkcon install glibc.i686
Possibly some desktop Debian/Ubuntu systems:
pkcon install ia32libs
Fedora or newer Red Hat, CentOS:
sudo dnf install glibc.i686
Older RHEL, CentOS:
sudo yum install glibc.i686
Even older RHEL, CentOS:
sudo yum install glibc.i386
Debian or Ubuntu:
sudo aptget install ia32libs
should grab you the (first, main) library you need.
Anyone needing to install glibc.i686 or glibc.i386 will probably run into other library dependencies, as well. To identify a package providing an arbitrary library, you can use
ldd /usr/bin/YOURAPPHERE
if you're not sure it's in /usr/bin you can also fall back on
ldd $(which YOURAPPNAME)
The output will look like this:
linuxgate.so.1 => (0xf7760000)
libpthread.so.0 => /lib/libpthread.so.0 (0xf773e000)
libSM.so.6 => not found
Check for missing libraries (e.g. libSM.so.6 in the above output), and for each one you need to find the package that provides it.
Fedora/Red Hat Enterprise/CentOS:
dnf provides /usr/lib/libSM.so.6
or, on older RHEL/CentOS:
yum provides /usr/lib/libSM.so.6
or, on Debian/Ubuntu:
first, install and download the database for aptfile
sudo aptget install aptfile && aptfile update
then search with
aptfile find libSM.so.6
Note the prefix path /usr/lib in the (usual) case; rarely, some libraries still live under /lib for historical reasons … On typical 64bit systems, 32bit libraries live in /usr/lib and 64bit libraries live in /usr/lib64.
(Debian/Ubuntu organise multiarchitecture libraries differently.)
The above should give you a package name, e.g.:
libSM1.2.02.fc15.i686 : X.Org X11 SM runtime library
Repo : fedora
Matched from:
Filename : /usr/lib/libSM.so.6
In this example the name of the package is libSM and the name of the 32bit version of the package is libSM.i686.
You can then install the package to grab the requisite library using pkcon in a GUI, or sudo dnf/yum/aptget as appropriate…. E.g pkcon install libSM.i686. If necessary you can specify the version fully. E.g sudo dnf install ibSM1.2.02.fc15.i686.
Some libraries will have an “epoch” designator before their name; this can be omitted.
Incidentially, the issue you are facing either implies that your RPM (resp. DPkg/DSelect) database is corrupted, or that the application you're trying to run wasn't installed through the package manager. If you're new to Linux, you probably want to avoid using software from sources other than your package manager, whenever possible...
Type
su c
every time you see sudo, eg,
su c dnf install glibc.i686
No installation is required; all additional files used by TraceWin are extracted directly from the main code and installed when a process requires them.
The downloadable version is not a fully functional version. To activate its full capabilities, you must include a key file in the TraceWin executable directory: "tracewin.key".
Since TraceWin version 2.4.1.0 :
The activation key is generated automatically when the code is launched, when it is connected to the WEB and when the user is registered in the user database. To use the code on a computer without network access, you must bring this key file with the executable file to preserve the user rights.
Run the code directly by doubleclicking the executable or the bundle for MacOS. To run from a batch command file, see the "Using the TraceWin batch command file" chapter.
· TraceWin is based in part on the work of the Qt project (http://qt.nokia.com) under the Qt Commercial Licence Agreement Version: 5.4
· TraceWin is partly based on the work of the Qwt project (http://qwt.sf.net).
· Documentation browser is provided by QtWeb, developed as a project of LogicWare & LSoft Technologies (http://qtweb.net/).
· A wide range of elements including RFQ with Toutatis module,
· 2D and 3D space charge,
· 1D, 2D and 3D static and RF magnetic and/or electric field maps (with superposition capability),
· Envelope simulation,
· macroparticle tracking simulations (number of particles depends on free memory),
· Each particle has a detailed analysis of its trajectory available,
· Starttofinish simulations from source to target,
· transport of two beams in the same structure,
· and scattering analysis,
· Automatic transverse and longitudinal beam tuning in envelope and/or tracking mode,
· Beam tuning in period structure based on smoothing phase advances,
· Diagnosticbased correction procedures,
· Static and dynamic error simulations for all elements,
· Large particle number simulations for large scale calculations (Monte Carlo) based on client/server architecture,
· Statistical analysis including beam loss location,
· GUI and various auxiliary tools,
· Windows/Linux/MACOS versions,
· Reference code for the IFMIF, LINAC4, SPIRAL2, EUROTRANS, EURISOL and SPL projects.
TraceWin’s program is organized into 8 pages and 3 toolbars. These pages are described in more details below.
Menu : Displays the last 20 last projects currently open.
First toolBar : Open save or create a project file (configuration file, *.ini), display the currently open project.
Second toolBar : Start, pause or stop the process and set "auto_calculation".
Third toolBar : Visible only during matching, to stop or visualise the variation of the criteria.
Main page : To set input beam parameters, structure options and calculation options.
Multiparticle page : To configure multiparticle code options.
Matching page : To configure beam matching options
Output page : To visualise the calculation stages
Edit page : To modify or visualize the main input and output files.
Data page : To visualise the list of elements and commands from the data file
Charts page : To visualize the results with plots.
Errors page : To parameterise the error study and visualise results.
Epics page : To configure the EPICS virtual machine.
Each input or widget item of TraceWin GUI has an explanatory text. The default way for users to view the help is to move the focus to the relevant widget and press Shift+F1. The help text is displayed immediately. A second way is to use the Help button, see the following image.
TraceWin process is organized in several stages. The stages can automatically run one behind the other or not (“Auto calculation” button of ToolBar). Some of them can be disabled according to some options and commands.



Results saved 
Affected or used beam 


Different stages 
Needed Condition(s) 

Main 
Second 
1 
Read input data file and set tab in “Data” page 




2 
Transport of the reference particle 


X 

3 
Set Phase advance law (set Quadrupole, Solenoid, Field map strengths) 
SET_ADV commands in data file or “Use file for phase adv definition” checked LATTICE commands in data file 

X 

4 
Read particle files 
Particle file defined in “Main” page 

X 
X 
5 
Calculate the input matched beam 
“Calculate match beam” checked in “Matching” page 

X 
X 
6 
Set quads or cavity strengths to match the beam through the different linac sections or set Twiss parameters (In order of theirs positions) 
“Matching with family” checked in page “Matching” MATCH_FAM commands and (LATTICE or SET_TWISSSet twiss parameters command) in data file 
X 
X 

7 
Diagnostics (Example: Steerers) calculations (In the order of theirs numbers) 
“Match with diagnostics” checked in page “Matching” 
X 
X 
X 
8 
Input beam distribution (*.dst) is adjusted in order to fit the input beam defined in “Main” page or to fit the input matched beam calculated in (5) 
“Calculate match beam” > “With partran” checked in “Matching” page “Use particle file” in “Input distribution type” in “Multipart” page Particle file defined in “Main” page 



9 
Repetition of the preceding stages (5)(6)(7) using mutliparticle code 
On or several options “With partran” checked in “Match” page 
X 
X 
X 
10 
Random errors generator initialised 
“Reinitialize random generator” checked in “Main” page. 



11 
Apply Static errors 
“Include error defined in…” checked in “Main” page “..Data No” in “Main” page set to errors defined in “Errors setup” of page “Error” “ERROR_xxx_STAT_xxxx” commands in data file 

X 
X 
12 
Diagnostics (Example: Steerers) calculations 
“Match wiht diagnostics” in “Match” page Diagnostic elements and ADJUST commands in data file 

X 
X 
13 
Repetition of the preceding stages (10 to 13) using mutliparticle code 
“Launch Partran” checked in “Multiparticle” page 

X 
X 
14 
Apply dynamic errors 
“Include error defined in…” checked in “Main” page “..Data No” in “Main” page set to errors defined in “Errors setup” of page “Error” “ERROR_xxx_DYN_xxxx” commands in data file 

X 
X 
15 
Calculates the transport line envelope 
Always 

X 
X 
Losses and beam parameters variations estimated in envelope transport 
“Nbr of particles” in “Main” page greater then 10 “Use aperture element” checked in “Main” page 

X 
X 

16 
Write new data file in “calculation directory” 
Always 



17 
Make the Error studies (envelope). N linacs, Loop with stage (10,11,12,14,15) 
“Study Envelope” checked in “Errors” page and error selection done 

X 
X 
18 
Make the Error studies (Particles). N linacs, Loop with stage (10,11,12,13,14,15,19) 
“Study Multipartilce” checked in “Errors” page and error selection done 

X 
X 
19 
Write input files of multiparticle codes PARTRAN and TOUTATIS and launch them 
“Launch Partran or Toutatis” checked in “Multiparticle” page 

X 
X 
Some help on elements or commands in the data file editor can be obtained by using the right mouse button. If you don’t release it; the element number is displayed first.
Different king of plots, explore and test all the top buttons to well understand all the available options.
Zoom in by dragging a rectangle with the left mouse button.
Doubleclick the left mouse button to zoom out.
Move the plot area (only after zooming), with the right mouse button.
Save by clicking on the appropriate icon in various image formats, pdf, ps, data ASCII file.
Copy by clicking on dedicated icon in png format.
Plot options, colour, size, font, dots type… are configurable from icons .
All charts can be synchronised (refreshed after each calculation) by clicking on the dedicated icon.
The plot window can contain a maximum 6 plots using this icon .
For envelope plots, contextual information can be obtained by right clicking on any element; the envelope types (X, Y, X’, Y’, Z, Z’, Phase, Energy, Z, dp/p…) by right clicking on the plot.
For phasespace plots, the coordinates are selected by right clicking on the chart. In this case, you can either select one of the 8 proposed 2D phasespaces or select the variable for each axis. It is possible to “Select” or “Unselect” the particles visible in the chart area. The sizes, colours of the selected or unselected particles can be configurated using the options button. This is very ususful for locating some particles in 6D phasespace and studing their behaviour in a line.
The emittance icon calculates and displays statistical information about the plotted distribution. The code performs the same calculations for all plotted the phasespace [x, y], whatever they are.
§ _{},
§ _{}
§ _{}
Emit [xx%] gives the ellipse surface, divided by p, homothetic to the rms ellipse, containing xx% of the beam particles. The xx is either the calculated fraction of particles within a homothetic ellipse whose area is N times the rms ellipse, or a given fraction of the beam. The plotted ellipses are the latter. The position of the c.o.g. and the size of the beam can also be calculated. Finally, two graphs can be plotted, the first showing the evolution of the number of particles outside a given emittance (scaled to the rms emittance calculated above), the second showing the evolution of the number of particles outside a given size (scaled to the rms size calculated above). The last button (s beam) shows the 6x6 beam matrix.
The emittances are calculated according to the “Energy and Phase limit” defined on the “Multipartcle” page.
Envelope plot example
Multiparticle phase space plot
There are 3 ways to run TraceWIN in batch command corresponding to 3 types of executable files:
On an X console, hide the full TraceWin GUI / X11 with the “hide” command.
In this case, multithreading and full code functionality is available, such as, for example, statistical error studies.
Syntax examples:
 For Linux or Mac:
./TraceWin /full_path/project_name.ini hide current1=80 freq1=352
 For Windows use a bat file and send the standard output to a file :
TraceWin d:\full_path\project_name.ini hide freq1=352 path_cal=c:\temp > output.txt
On a command console:
 Linux executables: “./TraceWin64_noX11 ../projet_path/project.ini”
 Windows executables: “./TraceWin64_noGUI ../projet_path/project.ini”
 MacOS version could be suggested, if some users need them.
This executable is fully similar to GUI version except that no X11 / GUI is required. Multithreading and full error study on local and remote computers are also performed. The project configuration and file localisations must be exactly the same than for the GUI version. In other words, use the GUI version to configure your project or visualise results during an error study for example, but use the noX11 version to run the code if you need to exit the GUI during a process.
These versions are internally used by the main code for remote calculations performed during error studies. They are not available on the website but can be directly extracted using the top menu “Exe”.
On a command console:
 Windows executables: “tracew32.exe” & “tracew64.exe”
 Linux executables: “tracelx” & “tracelx64”
 MacOS executables: “tracemac” & “tracemac64”
In this case, multithreading and statistical error studies are not possible. All project files must be located in the same directory as the executable file, so no path needs to be specified in the command line. Here, The “hide” argument means no standard output and the “hide_esc” argument means standard output without the ‘esc’ character.
Examples of syntax:
 For Linux or Mac:
./tracelx project_name.ini hide current1=80 freq1=352
 For Windows use bat file and send standard output to a file
Tracew32 project_name.ini freq1=352 current1=80
For all the cases, the project file *.ini is automatically loaded. Input variables listed as arguments are modified. The calculation is started and TraceWin is closed at the end. The project name must be the first parameter and the input available variables are shown in the following tab. Input variables don’t need to be casesensitive. The syntax is always “variable=value” without spaces, except for the “hide” variable. If the user needs another one, please, contact the developer.
The “tracewin.key” and possibly the “toutatis.key” must always be copied with the executable file.
In addition to these generic variables defined in the following table, the parameters of the element can be modified.
Examples of syntax for modifying element parameters:
tracew32 project_name.ini freq1=352 current1=80 Ele[15][2]=10
In this example, the second parameter of the 15^{th} element will be set to 10. Respect the parameter units defined in the documentation for each element.
./tracelx64 project_name.ini freq1=352 current1=80 ele[15][2]=10 ele[25][3]=0.255
Ele[n][v] 
Change the v^{th} parameter of for the n^{th} element 
hide 
Hide the GUI, or cancel console output (no parameter) 
tab_file 
Save to file the data sheet at the end of calcul (by default in calculation directory) 
upgrade 
Upgrade with last version available on CEA server 
Synoptic_file 
Save the geometric layout at (entance (=1), middle (=2), exit (=3) of elements. (See “Synoptic” tools for file name) . 
nbr_thread 
Set the max. number of core/thread used 
path_cal 
Calculation directory 
dat_file 
Full name of structure file 
dst_file1 
Full name Input dst of main beam (*) 
dst_file2 
Full name Input dst of second beam (*) 
current1 
Input beam current (mA) of main beam 
current2 
Input beam current (mA) of second beam 
nbr_part1 
Number of particle of main beam 
nbr_part2 
Number of particle of second beam 
energy1 
Input kinetic energy (MeV) of main beam 
energy2 
Input kinetic energy (MeV) of second beam 
etnx1 
Input XX’ emittance (mm.mrad) of main beam 
etnx2 
Input XX’ emittance (mm.mrad) of second beam 
etny1 
Input YY’ emittance (mm.mrad) of main beam 
etny2 
Input YY’ emittance (mm.mrad) of second beam 
eln1 
Input ZZ’ emittance (mm.mrad) of main beam 
eln2 
Input ZZ’ emittance (mm.mrad) of second beam 
freq1 
Input beam frequency (MHz) of main beam 
freq2 
Input beam frequency (MHz) of second beam 
duty1 
Duty cycle of main beam 
duty2 
Duty cycle of second beam 
mass1 
Input beam mass (eV) of main beam 
mass2 
Input beam mass (eV) of second beam 
charge1 
Input particle charge state of main beam 
charge2 
Input particle charge state of second beam 
alpx1 
Input twiss parameter alpXX’ of main beam 
alpx2 
Input twiss parameter alpXX’ of second beam 
alpy1 
Input twiss parameter alpYY’ of main beam 
alpy2 
Input twiss parameter alpYY’ of second beam 
alpz1 
Input twiss parameter alpZZ’ of main beam 
alpz2 
Input twiss parameter alpZZ’ of second beam 
betx1 
Input twiss parameter betXX’ of main beam 
betx2 
Input twiss parameter betXX’ of second beam 
bety1 
Input twiss parameter betYY’ of main beam 
bety2 
Input twiss parameter betYY’ of second beam 
betz1 
Input twiss parameter betZZ’ of main beam 
betz2 
Input twiss parameter betZZ’ of second beam 
x1 
Input X position of main beam 
x2 
Input X position of second beam 
y1 
Input Y position of main beam 
y2 
Input Y position of second beam 
z1 
Input Z position of main beam 
z2 
Input Z position of second beam 
xp1 
Input X angle of main beam 
xp2 
Input X angle of second beam 
yp1 
Input Y angle of main beam 
yp2 
Input Y angle of second beam 
zp1 
Input Z angle of main beam 
zp2 
Input Z angle of second beam 
dw1 
Input Dw of main beam 
dw2 
Input Dw of second beam 
spreadw1 
Input spread energy for CW beam of main beam 
spreadw2 
Input spread energy for CW beam of second beam 
part_step 
Partran calculation step per meter (per beta.lambda if < 0) 
vfac 
Change RFQ Ucav (ex : “vfac 0.5”, half reduce of Ucav) 
random_seed 
Set the random seed 
partran 
Force or avoid tracking simulation (1 / 0) 
toutatis 
Force or avoid Toutatis simulation (1 / 0) 
algo 
Optimization using algorithm (0: Owner, 1: Simplex, 2: Diff. evo.) 
cancel_matcthing 
Cancel all matching procedure (Envelope) 
cancel_matcthingp 
Cancel all matching procedure (Tracking) 
picnir_2d 
Spacecharge routine is defined as picnir2D 
picnic_3d 
Spacecharge routine is defined as picnic3D 
picnir_r_mesh 
R mesh of picnir 2D 
picnir_z_mesh 
Z mesh of picnir 2D 
picnic_xy_mesh 
X&Y mesh of picnic 3D 
picnic_z_mesh 
Z mesh of picnic 3D 
input_dist_type 
Input distribution type from 1 to 5, see GUI menu 
use_dst_file 
dst file is used as input beam distribution 
trans_dist_mask 
Mask of the transverse input distribution from 1 to 7, see GUI menu 
long_dist_mask 
Mask of the longitudinal input distribution from 1 to 7, see GUI menu 
lost_e_limit 
Particle is lost if WW_{s} > lost_e_limit 
lost_p_limit 
Particle is lost if Ф Ф_{ s} > lost_p_limit 
emit_e_limit 
Particle is excluded form emit. calculation if WW_{s}/ W_{s} > emit_e_limit 
emit_p_limit 
Particle is excluded form emit. calculation if Ф Ф_{ s} > emit_p_limit 
(*): If the input dst file is specified, the input beam parameters (number of particles, emittances, Twiss parameters, beam centroid, beam current and energy) are automatically extracted from the specified file and used for the calculation. The emittances and Twiss parameters cannot be modified by the corresponding input commands, but it is still possible to modify the beam centroid, current, energy and number of particles.
Step that allows to perform the calculation of the longitudinal acceptance on axis, zero current.
· Set the transverse emittances to a very small value (not zero).
· Set the longitudinal emittance and Twiss parameters in order to obtain a phase and energy spread greater than the expected acceptance of your structure.
· Set current to zero.
· Select uniform distribution.
· Set the number of particles to e.g. 10.000, for example.
· Set in “Multiparticle” page → “Distribution option file, PLT” option → “Last element” in order to avoid to generating a huge plt file size.
· Remove plt compression level.
· Remove in “Multiparticle” page → “Phase en energy limits” all condition (set everything to zero).
· Make a run in multipartcle mode (no matching have to be done here).
· In the “Chart” page, start “PlotWin” tool (if you don’t get it, upload it on the CEA site. This code must be started once for TraceWin to recognise it). Starting PlotWin from TraceWin allows to PlotWin to use the good PLT file directly, but you can also open the good one directly from PlotWin.
· In PlotWin, plot phasespace distribution of the last element of your structure. Here are only the surviving particles. If the number of particle is to small compared to your input beam, you probably have to reduce the phase or/and the energy spread of your input beam.
· Remove charts options such as “Losses” and “Create a 360° period”.
· Either select all the particles in the output distribution graph (leftclick and "Select particles", as in the previous image) or, in most cases, it is preferable not to select the tails of particles that are too far from the expected reference energy.
· Now, in PlotWin, change the element number from the last one to 0, and plot the phasespace distribution again. The selected surviving particles should appear in a different colour. In the chart option (button at the top of the chart, you can choose the size, colour of the unselected and selected particles, you can also hide the unselected particles, in order to have only the input surviving particles).
· You visualise your longitudinal acceptance.
· In the ”Save” menu, you have the possibility of saving it (select “Particle checked”) in a dst file.
· You can, now, restart the whole step increasing the number of input particles in order to precisely define the acceptance (be careful, close PlotWin starting another process).
Input beam distribution at element 0, small in transverse and big in longitudinal
Surviving output distribution at last element (use menu to select all of them)
Input distribution at element 0, where acceptance is visible, here the space spread could be reduced.
PlotWin is a postprocessing tool allowing to projecting and plotting a 6D beam distribution in 2D subphasespaces and associated 1D beam density profiles. As many as 6 phasespaces can be plotted on the same chart. The number of phasespaces and the plot distribution can be selected. The beam is represented by a set of particles of equal weight. This tool allows each particle transport to be observed individually.
The code can be found at: http://irfu.cea.fr/Sacm/logiciels/
The beam density profile performed by TraceWin with the “Density” button is only a rough view of the beam density in R space. The aperture of the elements is divided into 100 rings, where the number of particles is counted in order to generate the density plot.
PlotWin provides much better quality density plots, as shown on in the following page.
Distribution plot from TraceWin
The same distribution plot from PlotWin
This option allows to transport a beam upside down through the machine from the end to the beginning. When the option “Back Simulation” is selected in the “Main” tabsheet, the input beam has to be defined as the output beam of the machine. At the beginning of the run the structure of the machine is reversed (including the FIELD_MAP elements even superposed and other elements, accelerating or not). The space charge is also taken into account.
Two additional matrix elements are added at the beginning and end of the structure to apply the following changes to the beam.
_{}
L is the length of the elements.
For the FIELD_MAP elements specific case, two transformations are made:
_{}
And the name is change from “FIEL_MAP” to “MAP_FIELD” to make a clear distinction
A new structure file (*.dat ) is created corresponding to the reversed machine
The following example includes quadrupole and cavity field map:
SUPERPOSE_MAP 0
LMEQ11 : FIELD_MAP 70 480 0 40 9.174 0 0 0 qpole480_lme_25_01_07b
SUPERPOSE_MAP 250
LMEQ12 : FIELD_MAP 70 480 0 30 7.4796 0 0 0 qpole480_lme_25_01_07b
DRIFT 70 40 0
SUPERPOSE_MAP 0
SET_SYNC_PHASE
LMEGr1 : FIELD_MAP 7700 300 20 30 0.33 0.33 0 0 carte_3gap_2b
SUPERPOSE_MAP 250
LMEQ13 : FIELD_MAP 70 480 0 40 2.784 0 0 0 qpole480_lme_25_01_07b
DRIFT 100 40 0
END
Once the run is finished,, we can find in the “Calculation” directory the new structure file corresponding to the back simulation done (bellow). Two THIN_MATRIX elements are there to reverse the beam and reverse back at the end, FIEL_MAP has been renamed to MAP_FIELD.
;
; ELEMENTS OF BACK TRACKING FILE
; ELEMENTS OF BACK TRACKING FILE
; 2 THIN_MATIRIX has been added at the beginning
; and at the end of the structure to reverse the
; beam for back transport
;
THIN_MATRIX 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1
DRIFT 100 40 0 0 0
SUPERPOSE_MAP 0 0 0 0 0 0
LMEQ13 : MAP_FIELD 70 480 0 40 2.784 0 0 0 qpole480_lme_25_01_07b
SET_SYNC_PHASE
SUPERPOSE_MAP 430 0 0 0 0 0
LMEGr1 : MAP_FIELD 7700 300 160 30 0.33 0.33 0 0 carte_3gap_2b
DRIFT 70 40 0 0 0
SUPERPOSE_MAP 0 0 0 0 0 0
LMEQ12 : MAP_FIELD 70 480 0 30 7.4796 0 0 0 qpole480_lme_25_01_07b
SUPERPOSE_MAP 250 0 0 0 0 0
LMEQ11 : MAP_FIELD 70 480 0 40 9.174 0 0 0 qpole480_lme_25_01_07b
THIN_MATRIX 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1
END
Back simulation option is unchecked; this is the normal and usual beam transport.
Input beam distribution. Holes are intentionally introduced into the transverse and longitudinal phase space. 
Output beam distribution 
Beam envelops. 
Emittances. 
Back simulation option is checked and output beam distribution of preceding simulation is used as input beam
Another way consists to uncheck the “Back simulation” option and to use in normal simulation mode, the reversed structure file.
Both methods give the same results.
Input beam distribution 
Output beam distribution 
Beam envelops. 
Emittances. 
Because reverse a structure could be a complex work and because it’s a nice way to verify this point and to check if the transport model (tracking or envelop) is consistent, it could be interesting to transport beam in the structure and in the reverse structure together. If every is good, you have to get output distribution identical to output one and also the transfer matrix of both structures has to be equal to the identity matrix. So considering the following structure file (Back simulation option unchecked)
SUPERPOSE_MAP 0
LMEQ11 : FIELD_MAP 70 480 0 40 9.174 0 0 0 qpole480_lme_25_01_07b
SUPERPOSE_MAP 250
LMEQ12 : FIELD_MAP 70 480 0 30 7.4796 0 0 0 qpole480_lme_25_01_07b
DRIFT 70 40 0
SUPERPOSE_MAP 0
SET_SYNC_PHASE
LMEGr1 : FIELD_MAP 7700 300 20 30 0.33 0.33 0 0 carte_3gap_2b
SUPERPOSE_MAP 250
LMEQ13 : FIELD_MAP 70 480 0 40 2.784 0 0 0 qpole480_lme_25_01_07b
DRIFT 100 40 0
;
; ELEMENTS OF BACK TRACKING FILE
; ELEMENTS OF BACK TRACKING FILE
;
THIN_MATRIX 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1
DRIFT 100 40 0 0 0
SUPERPOSE_MAP 0 0 0 0 0 0
LMEQ13 : MAP_FIELD 70 480 0 40 2.784 0 0 0 qpole480_lme_25_01_07b
SET_SYNC_PHASE
SUPERPOSE_MAP 430 0 0 0 0 0
LMEGr1 : MAP_FIELD 7700 300 160 30 0.33 0.33 0 0 carte_3gap_2b
DRIFT 70 40 0 0 0
SUPERPOSE_MAP 0 0 0 0 0 0
LMEQ12 : MAP_FIELD 70 480 0 30 7.4796 0 0 0 qpole480_lme_25_01_07b
SUPERPOSE_MAP 250 0 0 0 0 0
LMEQ11 : MAP_FIELD 70 480 0 40 9.174 0 0 0 qpole480_lme_25_01_07b
THIN_MATRIX 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1
END
There is a perfect symmetry of the different beam parameters like output/input distributions, envelops and emittances.
Input beam distribution 
Output beam distribution 
Beam envelops. 
Emittances. 
Transfer matrix closed to be identical matrix, higher is the step of calculation, closer is this equality
Data file (*.dat)
Init project file (*.ini)
Results file (*.cal)
Adjusted value file (*.txt)
Steerer strength file (*.txt)
Cavity setting point file (*.txt)
Sigma0 file (*.sig0)
Input file for multiparticle program (*.par, *.dat)
Density file (*.dat)
Particle distribution (*.dat)
Lost particles (*.dat)
Error file results (*.txt)
Error set of data (*.txt)
Input & Output particle distribution (*.dst, *.plt)
Partran or Toutatis output (*.out)
Electric or magnetic field map
Current or space charge compensation map (*.scc)
Aperture map (*.ouv)
Magnetic stripping file (*.los)
Gas stripping file (*.los)
Random seed (*.log)
Transfer matrix (*.dat)
The data file ("*.dat") contains the list of elements and commands. It must be terminated with the "END" command. The syntax of the elements and commands is described in the "Element definitions" and "Command definitions" sections. The comment line starts with the ';' character.
A name of up to 50 characters can be specified for each element (see example below).
Result files are automatically created the first time the data file is used. At the end of a run, TraceWin creates another data file with the same name but located in the calculation directory and containing the new element list. For example, with the quadrupole values calculated to have the desired phase advance law. If the calculation directory is the same as the data file directory, the name of the new data file will begin with "new_...".
Warning:
Each command affects the following element, e.g. "SET_TWISS" will set some Twiss parameters at the output of the following element.
Two identical commands cannot follow each other.
; **********************************************
DRIFT 1e08 100
SPACE_CHARGE_COMP 0.7
DRIFT 350 100
DRIFT 60 100
DRIFT 192 100
MATCH_FAM_GRAD 1 1
ADJUST 1 2 1 0 0
SOLENOID 410 0.25 100
DRIFT 100 100
MATCH_FAM_GRAD 1 2
STEERER 0 0 100 0
ADJUST_STEERER 2
ADJUST 1 2 2 0 0
QUAD 200 0.18 100 0
DRIFT 150 100
END
;**********************************************
; **********************************************
DR1 : DRIFT 1e08 100
SP1 : SPACE_CHARGE_COMP 0.7
DR2 : DRIFT 350 100
DR3 : DRIFT 60 100
SOL 1 : SOLENOID 410 0.25 100
DR5 : DRIFT 100 100
QPF1 : QUAD 200 0.18 100 0
DR6 : DRIFT 150 100
;***********************************************
The init file “project_name.ini” contains all the TraceWin project parameters. It can be loaded, saved, copied by using the TraceWin menu.
It is created by TraceWin, its name is "Data_file_name.cal", it is located in the data file directory and it contains the results of the matching calculations already performed to avoid redundant calculations. See the following example.
Twiss_parameters_of_matched_beam
0.3167415265 0.1850852302 0.5246751875
0.0938830920 0.0822867115 0.0875778140
Matching_Between_Section_1_to_2
8.11004 8.16711 8.19803 8.21871
3.8207 2.8207 4.1476 1.1476
0.00834559 0.000887792
BEAM_FAM_69_0.DST
The first three lines are written after a matching beam calculation. The second line contains the Twiss parameters βxx', βyy', βzz' and the last αxx', αyy', αzz'.
The following five lines are written after a matching calculation, they contain the result of a matching between two sections. The first line contains the quadrupole gradients that have been adjusted ("MATCH_FAM_GRAD" command), the second line is either the phase shift or the field factor correction or both, of the accelerator elements that have been matched ("MATCH_FAM_PHASE", "MATCH_FAM_FIELD" or "MATCH_FAM_LFOC" command). The third line corresponds to the element length that has been adjusted ("MATCH_FAM_LENGTH" command) and the last is the name of a ray distribution file (located in the file data path) that will be saved when the matching family is calculated with the "With rays from Partran" option. All these lines are optional and depend on the "MATCH_FAM..." command in your data file.
For more details, see the matching commands and their examples. You can also force the optimisation of the calculation with initial values by using the following commands.
Init_Matching_Between_Section_1_to_2
8.11004 8.16711 8.19803 8.21871
2.8207 2.8207 3.1476 3.1476
To comment on a result, simply add the character ";" as the first character.
This file also contains all the diagnostic results, as in the following example. For more details, see the adjust commands and their examples. You can also force the optimisation process of the diagnostic calculation with initial values by using the "Init_" syntax.
Diagnostic_10
10.7992 10.5893 5.81701
Init_Diagnostic_10
10.7992 10.5893 5.81701
For all these result, an extension “_PAR” is added when the result comes from a multiparticle optimization ‘With Partran” is checked
Created by TraceWin or No, its name is "*.sig". It's located in the data file directory and contains the transverse phase advance law without current, one value per lattice. See the example below, where the red values correspond to the optional vertical phase advance, sigy=sigx by default.
60 40
60 41
61 41
62 42
…
..
.
Input field for “FIELD_MAP” element, see also FIELD_MAP details.
In “Chart” page a tool allows the visualization (1D or 2D) the field maps from elements defined in data file. This tool also allows to convert the field ASCII format to binary format. This allows the code to be faster if the size of the field maps is too large.
The field map file syntax in ASCII format is as follows:
Fz are in MV/m for electric field or in T for magnetic field.
For specific 3D aperture field map file, Fz = 0 or 1, 1 corresponding to material.
The dimensions are in metres.
 Dimension 1 :
Pay attention, to the number of data requested, N=(nz+1)
nz zmax
Norm
for k=0 to nz
Fz(k.zmax/nz)
Return
 Dimension 2 :
Pay attention, to the number of data requested, N=(nz+1)*(nr+1)
nz zmax
nr rmax
Norm
for k=0 to nz
for i=0 to nr
Fz(k×z_{max}/nz, i×r_{max}/nr)
Return
or
Pay attention, to the number of data requested, N=(nx+1)*ny+1)
nx xmin xmax
ny ymin ymax
Norm
for k=0 to ny
for i=0 to nx
Fz(k×x_{max}/nx, i×y_{max}/ny)
Return
 Dimension 3 :
nz zmax
nx xmin xmax
ny ymin ymax
Norm
for k=0 to nz
for j=0 to ny
for i=0 to nx
Fz(k×z_{max}/nz, y_{min}+j×(y_{max}y_{min})/ny, x_{min}+i×(x_{max}x_{min})/nx)
Return
The field map file syntax is the following in the BINARY format:
 Dimension 1 :
nz (integer 4 bytes) zmax (double 8 bytes)
Norm (double 8 bytes)
for k=0 to nz
Fz(k.zmax/nz) (float 4 bytes)
 Dimension 2 :
nz (integer 4 bytes) zmax (double 8 bytes)
nr (integer 4 bytes) rmax (double 8 bytes)
Norm (double 8 bytes)
for k=0 to nz
for i=0 to nr
Fz(k×z_{max}/nz, i×r_{max}/nr) (float 4 bytes)
 Dimension 3 :
(Pay attention to the dimention order)
nz (integer 4 bytes) zmax (double 8 bytes)
nx (integer 4 bytes )xmin (double 8 bytes) xmax (double 8 bytes)
ny (integer 4 bytes) ymin (double 8 bytes) ymax (double 8 bytes)
Norm (double 8 bytes)
for k=0 to nz
for j=0 to ny
for i=0 to nx
Fz(k×z_{max}/nz, y_{min}+j×(y_{max}y_{min})/ny, x_{min}+i×(x_{max}x_{min})/nx) (float 4 bytes)
Warning: The lattice has to be regular.
The normalization factor is equal to ke/Norm or kb/Norm.
Fz are in MV/m for electric field or in T for magnetic field.
For specific 3D aperture field map file, Fz = 0 or 1, 1 corresponding to material.
The dimensions are in meter.
“FileMapName.scc”
A flag in “FIELD_MAP” element syntax allow to include it.
The space charge compensation or current file syntax is like following:
 Space charge compensation according to Z format:
0 N
for i=0 to N1
Z_{i} Scc_{i}
 Current evolution according to Z file format:
1 N
for i=0 to N1
Z_{i} I_{i}
 Zi is the position (m)
 Scci is the space charge compensation at the Zi position, (1 for 100%)
 Ii is the current (mA) at the Zi position
Partran and TraceWin codes make an interpolation in between this figure.
“FileMapName.ouv”
A flag in FIELD_MAP element syntax allow to include it.
For the field map elements, sometime we need to define a beam pipe radius geometry according to z axis. The file syntax is the following:
Warning in case of superposed field map these aperture map have to be defined in the first FIELD_MAP element and have to get a length equivalent to all field_map.
 Aperture according to Z format:
N
for i=0 to N1
Z_{i} OuvX_{i} OuvY_{i}
 Zi is the position (m)
 OuvXi is the horizontal aperture radius(m) at Zi.
 OuvYi is the vertical aperture radius(m) at Zi.
OuvYi is optional, but if OuvYi is defined and no egal to OuvXi, then aperture is an elipse.
The first location Zi has to be 0.
At the end of a calculation TraceWin creates the input files for multiparticle library, PARTRAN (Data_file_name.par), and TOUTATIS (toutatis.dat).
Since TraceWin version 2.4.2.0, the files “Desnity_PAR.dat” (for multiparticle) and “Density_Env.dat” (for envelope) replace the “Dist_Error_PAR.dat” and “Dist_Error_Env.dat” respectively. These new files contain much more data in order to visualize the transverse and longitudinal beam densities according to Z and some other beam parameters (all these data can come from the sum of statistical studies). All available charts are accessible via the Toolbox "Density". This tool is still able to read old density file version.
The following C++ example shows how density files are written.
These files replace also the obsolete file (particle loss distribution, “Dist_Error_Tot_PAR.loss”)
In case of statistical error study 2 new files are created name Density_tot_ENV.dat and Density_tot_PAR.dat witch contain the sum of all the simulation.
If the “Nbr of Step” parameter of the tabsheet “Error” is bigger than 1 the name of the 2 files become for example for 5 steps
“Density_Tot_Env_0.2000.dat“ for 20%
“Density_Tot_Env_0.4000.dat“ for 40%,
…
“Density_Tot_Env_1.0000.dat“ for 100%,
Example to read the Density_XXX file.
#define den_year 2011
#define den_version 11
#include <stdio.h>
void Density_file_reading()
{
short int ver,year,vlong;
int nelp,Nrun,n=7,step;
float moy[7],moy2[7],maxb[7],minb[7], maxR[7],minR[7],rms_size[7],rms_size2[7];
float rms_emit[3],rms_emit2[3],min_pos_moy[7],max_pos_moy[7];
float Zg,Xouv,Youv,dXouv,dYouv,ib,Eouv,PhPouv,PhMouv,Mipowlost,Mapowlost;
long long int Np=0,lost2,Milost,Malost,longfichier=0;
double powlost2;
// All the following tables have to be correclty initialized
long long int *lost=NULL;
unsigned long long int **tab=NULL;
unsigned int **stab=NULL;
float **tabp=NULL,*powlost=NULL;
FILE *f=fopen("Density_PAR.dat","rb");
if (f==NULL) {
printf("Erreur: Impossible to open Density file\n");
exit(1);
}
if (fseek(f,0,SEEK_END)==0) {
longfichier=ftell(f);
fseek(f,0,SEEK_SET);
}
do {
/* The following sequence is repeated for each position (Zg) in the machine */
fread(&ver,sizeof(short int),1,f); /* Density file version : 3 to 10*/
fread(&year,sizeof(short int),1,f); /* year of development : 2011 */
fread(&vlong,sizeof(short int),1,f); /* vlong=1 if the number of particle is greater than 2e9 */
fread(&Nrun,sizeof(int),1,f); /* Number of run (1 for envelop or multiparicle simulation) more for statistical error studies */
fread(&nelp,sizeof(int),1,f); /* element # */
fread(&ib,sizeof(float),1,f); /* Beam courant (A) */
fread(&Zg,sizeof(float),1,f); /* Position (m), end of element or at step position calculation in field_map or in envelope mode */
fread(&Xouv,sizeof(float),1,f); /* Horizontal aperture */
fread(&Youv,sizeof(float),1,f); /* Vertical aperture */
if (ver>=9) {
fread(&dXouv,sizeof(float),1,f); /* Horizontal aperture shift */
fread(&dYouv,sizeof(float),1,f); /* Vertical aperture shift*/
}
fread(&step,sizeof(int),1,f); /* The beam is slice en step from max. to min. beam size */
/* n=7 (0:X(m)) (1:Y(m)) (2:Phase(°)) (3:Energy(MeV)) (4:R(m)) (5:Z(m)) (6:dp/p) */
fread(moy,sizeof(float),n,f); /* Beam average for each plane */
fread(moy2,sizeof(float),n,f); /* Squared beam average for each plane (needed when Nrun>1) */
fread(maxb,sizeof(float),n,f); /* Maximum beam size or particle excursion for each plane */
fread(minb,sizeof(float),n,f); /* Minimum beam size or particle excursion for each plane */
if (ver>=11) {
fread(&phaseF,sizeof(float),1,f); /* Absolute beam phase */
fread(&phaseG,sizeof(float),1,f); /* Absolute referenve beam phase */
}
if (ver>=10) {
fread(maxR,sizeof(float),n,f); /* Minimum of maximum beam size or particle excursion for each plane */
fread(minR,sizeof(float),n,f); /* Maximum of minimum beam size or particle excursion for each plane */
}
if (ver>=5) {
fread(rms_size,sizeof(float),n,f); /* rms beam size */
fread(rms_size2,sizeof(float),n,f); /* Squared beam rms size */
}
if (ver>=6) {
fread(min_pos_moy,sizeof(float),n,f); /* Min. if the beam average */
fread(max_pos_moy,sizeof(float),n,f); /* Maximum if the beam average */
}
if (ver>=7) {
fread(rms_emit,sizeof(float),3,f); /* rms emittances, xx’, yy’, zdp (m.rad)*/
fread(rms_emit2,sizeof(float),3,f); /* Squared rms emittances, xx’, yy’, zdp (m.rad)2 */
}
if (ver>=8) {
fread(&Eouv,sizeof(float),1,f); /* Energy Acceptance (eV) */
fread(&PhPouv,sizeof(float),1,f); /* Positive Phase acceptance (deg)*/
fread(&PhMouv,sizeof(float),1,f); /* Negative Phase acceptance (deg)*/
}
fread(&Np,sizeof(long long int),1,f);
if (Np>0) { //several linac simulation
/* particle lost and beam power lost for each linac */
if (lost!=NULL && powlost!=NULL) {
for (int i=0;i<Nrun;i++) {
fread(&lost[i],sizeof(long long int),1,f); /* Number of particle lost at position Zg */
fread(&powlost[i],sizeof(float),1,f); /* Beam power lost(W) at position Zg */
}
}
else fseek(f,Nrun*(sizeof(long long int)+sizeof(float)),SEEK_CUR);
fread(&lost2,sizeof(long long int),1,f); /* Squared particle number lost at position Zg */
fread(&Milost,sizeof(long long int),1,f); /* Minimum particle lost at position Zg when Nrun>1 */
fread(&Malost,sizeof(long long int),1,f); /* Maximum particle lost at position Zg when Nrun>1 */
fread(&powlost2,sizeof(double),1,f); /* Squared beam power lost(W) at position Zg */
fread(&Mipowlost,sizeof(float),1,f); /* Minimum beam power lost at position Zg when Nrun>1 */
fread(&Mapowlost,sizeof(float),1,f); /* Maximum beam power lost at position Zg when Nrun>1 */
/*tab or stab contains beam distribution from max. to min. size for each plane (7) slice in step*/
if (tab!=NULL && stab!=NULL) {
for (int j=0;j<n;j++) {
if (vlong==1) fread(tab[j],sizeof(unsigned long long int),step,f);
else fread(stab[j],sizeof(unsigned int),step,f);
}
}
else {
if (vlong==1) fseek(f,n*step*sizeof(unsigned long long int),SEEK_CUR);
else fseek(f,n*step*sizeof(unsigned int),SEEK_CUR);
}
if (ib>0) {
/* tabp contains beam power distribution from max. to min. size for X, Y and R planes */
if (tab!=NULL && stab!=NULL && tabp!=NULL) {
for (int j=0;j<3;j++) {
fread(tabp[j],sizeof(float),step,f);
}
}
else fseek(f,3*step*sizeof(float),SEEK_CUR);
}
}
/* next step */
/* break when Zg>=Linac length */
if (ftell(f)+16>=longfichier) break;
} while (!feof(f));
fclose(f);
}
Dist_Error_Env.dat (OBSOLETE see Density_Env.dat file)
Contain the beam distribution at the end of each element after an envelope calculation. This file is created if “nbr of particles” is greater than 10 and “Use aperture element” of “Main” page is selected. During an error study the condition “nbr of particles” is sufficient. You can visualize these results in the “Error” page by setting the “Distribution file” and using the right buttons
Dist_Error_PAR.dat (OBSOLETE see Density_PAR.dat file)
Contain the beam distribution at the end of each element after a multiparticle calculation. This file is created either by PARTRAN or TOUTATIS. You can visualize these results in the “Error” page by setting the “Distribution file” and using the right buttons
§ N: Number of linac = 1
§ Element number
§ Element aperture (cm)
§ Element aperture (cm)
§ _{ }(cm)
§ _{}(cm^{2})
§ _{ }(cm)
§ _{ }(cm^{2})
§ _{ }(cm)
§ _{ }(cm^{2})
§ 100 integers corresponding to the particle distribution along the aperture divided in 100 steps.
§ 100 Doubles corresponding to the power distribution along the aperture divided in 100 steps.
§ _{}
§ _{}
§ Max particle lost
§ Min particle lost
§ _{ } (w)
§ _{ } (w)
§ Max power lost (w)
§ Min power lost (w)
In case of statistical error study 2 new files are created name Dist_Error_tot_ENV.dat and Dist_Error_tot_PAR.dat witch contain the sum of the 2 preceding files (N>1).
If the “Nbr of Step” parameter of the tabsheet “Error” is bigger than 1 the name of the 2 files become for example for 5 steps
“Dist_Error_Tot_Env_0.2000.dat“ for 20%
“Dist_Error_Tot_Env_0.4000.dat“ for 40%,
…
“Dist_Error_Tot_Env_1.0000.dat“ for 100%,
The file “Steerer_Values.txt” is created after diagnostic position calculation. Its syntax is number of diagnostic follows by all the steerer strengths associated in T.m (Plane X and Y).
In case of statistical error study a new file named “Steerer_Values_Tot_X_XX.txt” is written including all the steerer strength of the whole linac simulated. A tool available in the “Errors” pagesheet allows to extract all useful statistical results from this file.
The file “Cav_set_point_res.txt” is created after envelope calculation. It contains the synchronous phase and Voltage for each RF cavity of the structure. Reference values and final tuned values are included.
In case of statistical error study a new file named “Cav_set_point_res_Tot_X_XX.txt” is written including all the cavity setting points of the whole linac simulated. A tool available in the “Errors” pagesheet allows to extract all useful statistical results from this file.
The file “Adjusted_Values.txt” is created after each diagnostic optimization adjusting some elements parameters.
In case of statistical error study a new file named “Adjusted_value_Tot_X_XX.txt” is written including all the element parameters adjusted of the whole linac simulated.
The file “MAGSTRIP1.LOS” is created only in multiparticle mode if option “Magnetic stripping” is selected in “Option” of multiparticle codes. You can directly exploit these results using “Stripping” button in tabsheet “Graphs”. It contains the probability losses due to Lorentz magnetic stripping. The syntax is the following. (One line per element):
Number of element, Position (m), Energy (MeV), Losses probability
In case of statistical error study a new file named “MAGSTRIP1_TOT.LOS” is written including the probability sum of the whole linacs simulated. You can directly exploit these results using “Stripping losses probability results” button in “Errors” page. The syntax is the following (One line per element):
Number of element, Number of linac simulated, Sum of losses probability
The probability corresponding to Sum of Magnetic stripping probability divided by Number of linac simulated.
The file “GASSTRIP1.LOS” is created only in multiparticle mode if option “Gas stripping” is selected in “Option” of multiparticle codes and if command Gas pressure is included in the data file. It contains the probability losses due to Gas stripping. The syntax is the following. (One line per element):
Number of element, Position (m), Energy (MeV), Losses probability
In case of statistical error study a new file named “GASSTRIP1_TOT.LOS” is written including the probability sum of the whole linacs simulated. You can directly exploit these results using “Stripping losses probability results” button in “Errors” page. The syntax is the following (One line per element):
Number of element, Number of linac simulated, Sum of losses probability
The probability corresponding to Sum of Gas stripping probability divided by Number of linac simulated.
Losses_PAR.dat
Losses_PAR_TOT.dat (in statistical error study)
These ASCII files are created only while multiparticle simulation, if the option “Losses file“ is activated in the “Multparticle” page. These files contain all coordonates of each lost particles. The syntax of the file is described at the first line.
These following files are created while multiparticle simulation
part_dtl1.dst: Binary file containing the output beam distribution at the end of the linac.
part_rfq1.dst: Binary file containing the beam distribution at the entrance of the linac.
A .dst file use a binary format. It contains information of a beam at a given longitudinal position: number of particles, beam current, repetition frequency and rest mass as well as the 6D particles coordinates. The format is the following:
2xCHAR+INT(Np)+DOUBLE(Ib(mA))+DOUBLE(freq(MHz))+CHAR+
Np×[6×DOUBLE(x(cm),x'(rad),y(cm),y'(rad),phi(rad),Energie(MeV))]+
DOUBLE(mc2(MeV))
Comments:
§ CHAR is 1 byte long ,
§ INT is 4 bytes long,
§ DOUBLE is 8 bytes long.
§ Np is the number of particles,
§ Ib is the beam current,
§ freq is the bunch frequency,
§ mc2 is the particle rest mass.
dtl1.plt: Binary file containing the beam distribution at the end of each element (Ne). In the case of field map type elements, Nstep is greater than 1 (in fact, beam distributions are present at different positions along the length of the field map), for other elements Nstep is equal to 1. Note that the value of Nstep is not specified and that you have to read the data sequentially while monitoring Ne to know if you are leaving the field map.)
A .plt file use a binary format. It contains information of a beam at many longitudinal positions: longitudinal position, number of particles, beam current, repetition frequency and rest mass as well as the 6D particles (Np) coordinates. The format is the following according to compression level. The two first CHAR read define the compression level.
No compression (char1=125, char2=100):
2xCHAR+INT(Ne)+INT(Np)+DOUBLE(Ib(A))+DOUBLE(freq(MHz))+DOUBLE(mc2(MeV))+
Ne×[
Nstep×[
CHAR+INT(Nelp)+DOUBLE(Zgen)+DOUBLE(phase0(deg))+DOUBLE(wgen(MeV))+
Np×[
7×FLOAT(x(cm),x'(rad),y(cm),y'(rad),phi(rad),Energie(MeV),Loss)
]
]
]
Compression level 1 (char1=124, char2=99):
2xCHAR+INT(Ne)+INT(Np)+DOUBLE(Ib(A))+DOUBLE(freq(MHz))+DOUBLE(mc2(MeV))+
Ne×[
Nstep×[
CHAR+INT(Nelp)+DOUBLE(Zgen)+DOUBLE(phase0(deg))+DOUBLE(wgen(MeV))+
6×FLOAT(p0)
6×FLOAT(m0)
Np×[
7×SHORT_INT(x(cm),x'(rad),y(cm),y'(rad),phi(rad),Energie(MeV),Loss)
]
]
]
for (int i=0;i<=5;i++) {
k0[i]=(float)(m0[i] / 65534.);
}
for (int i=0;i<Np;i++) {
x[i] = k0[0]*((FLOAT)Np[0+i]+p0[0]);
x’[i] = k0[1]*((FLOAT)Np[1+i]+p0[1]);
y[i] = k0[2]*((FLOAT)Np[2+i]+p0[2]);
y’[i] = k0[3]*((FLOAT)Np[3+i]+p0[3]);
W[i] = k0[4]*((FLOAT)Np[4+i]+p0[4]);
P[i] = k0[5]*((FLOAT)Np[5+i]+p0[5]);
loss[i] =(FLOAT)Np[6+i];
}
Compression level 2 (char1=123, char2=98):
2xCHAR+INT(Ne)+INT(Np)+DOUBLE(Ib(A))+DOUBLE(freq(MHz))+DOUBLE(mc2(MeV))+
Ne×[
Nstep×[
CHAR+INT(Nelp)+DOUBLE(Zgen)+DOUBLE(phase0(deg))+DOUBLE(wgen(MeV))+
6×FLOAT(p0)
6×FLOAT(m0)
Np×[
8×UNSIGNED_CHAR(x(cm),x'(rad),y(cm),y'(rad),phi(rad),Energie(MeV),Loss)
]
]
]
for (int i=0;i<=5;i++) {
k0[i]=(float)(m0[i] / 255.);
}
for (int i=0;i<Np;i++) {
x[i] = k0[0]*((FLOAT)Np[0+i]+p0[0]);
x’[i] = k0[1]*((FLOAT)Np[1+i]+p0[1]);
y[i] = k0[2]*((FLOAT)Np[2+i]+p0[2]);
y’[i] = k0[3]*((FLOAT)Np[3+i]+p0[3]);
W[i] = k0[4]*((FLOAT)Np[4+i]+p0[4]);
P[i] = k0[5]*((FLOAT)Np[5+i]+p0[5]);
loss[i] =(FLOAT)Np[6+i]+256×(FLOAT)Np[7+i];
}
Compression level 3 (char1=122, char2=97):
Not relevant, don’t use this level of compression
Comments:
§ CHAR is 1 byte long,
§ UNSIGNED_CHAR is 1 byte long,
§ INT is 4 bytes long integer,
§ SHORT_INT is 8 bytes long integer.
§ FLOAT is 4 bytes long real.
§ DOUBLE is 8 bytes long real.
§ Ne is the number of different positions,
§ Np is the number of particles,
§ Ib is the beam current,
§ freq is the bunch frequency,
§ mc2 is the particle rest energy,
§ Nelp is the longitudinal element position,
§ Zgen is the longitudinal position in cm,
§ Phase0 & wgen are the phase and energy references of the beam,
At the end of a simulation, the list of the final errors applied on each element can be found on the calculation directory in the file “Error_Datas.txt”. A file using the same syntax can be use associated with the boith commands, ERROR_STAT_FILE & ERROR_DYN_FILE.
During a statistical error study, for each linac a file, “Error_Datas_XX.txt” is saved.
QUAD_ERROR dx(mm),dy(mm),drx(°),dry(°),drz(°),dG(%),L(mm),dG3(%),dG4(%),dG5(%),dG6(%)
CAV_ERROR dx(mm),dy(mm),drx(°),dry(°),drz(°),dE(%),dPhase(°),L(mm)
BEND ERROR dx(mm),dy(mm),drx(°),dry(°),drz(°),dg(%),dz(mm)
BEAM_ERROR dx(mm), dy(mm), dφ(°), dxp(mrad), dyp(mrad), de(MeV), dEx(%), dEy(%), dEz(%), mx(%), my(%), mz(%), dib(mA ),αxx’_min, αxx’_max, βxx’_min(mm/mrad), βxx’_max(mm/mrad), αyy’_min, αyy’_max, βyy’_min(mm/mrad), βyy’_max(mm/mrad), αzdp_min, αzdp_max, βzdp_min(mm/mrad), βzdp_max(mm/mrad)
ERROR_BEAM 0.0180812 0.029287 0 0.0815901 0.0979198 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
QUAD_ERROR [1] 0.0358043 0.106052 0.0152857 0.0392236 0.0497174 0.790136 0.73 0 0 0 0
QUAD_ERROR [2] 0.0629623 0.053688 0.0216135 0.07538 0.0389759 0.0504835 0 0 0 0 0
CAV_ERROR [4] 0.00226118 0.00857076 0.00804547 0.000738873 0 0.785965 0.0847529 0.73
QUAD_ERROR [5] 0.0661981 0.0781597 0.0605019 0.0523095 0.0493564 0.0607798 0 0 0 0 0
CAV_ERROR [160] 0.00875094 0.00181656 0.0293326 0.0246627 0 0.618743 0.408912 0.3
QUAD_ERROR [167] 0.0792799 0.0387784 0.010346 0.00170561 0.193866 0.958619 0.13 0 0 0 0
QUAD_ERROR [168] 0.0792799 0.0387784 0.010346 0.00170561 0.193866 0.958619 0.13 0 0 0 0
QUAD_ERROR [169] 0.0792799 0.0387784 0.010346 0.00170561 0.193866 0.958619 0.13 0 0 0 0
QUAD_ERROR [170] 0.0792799 0.0387784 0.010346 0.00170561 0.193866 0.958619 0.13 0 0 0 0
QUAD_ERROR [176] 0.0648002 0.0634561 0.00654776 0.00490306 0.162641 0.214648 0.13 0 0 0 0
CAV_ERROR [183] 0.000958443 0.00685156 0.0171741 0.0266001 0 0.0191761 0.132693 0.3
QUAD_ERROR [190] 0.0676107 0.0954914 0.0285646 0.0129899 0.0218936 0.436949 0.13 0 0 0 0
QUAD_ERROR [191] 0.0676107 0.0954914 0.0285646 0.0129899 0.0218936 0.436949 0.13 0 0 0 0
QUAD_ERROR [192] 0.0676107 0.0954914 0.0285646 0.0129899 0.0218936 0.436949 0.13 0 0 0 0
QUAD_ERROR [193] 0.0676107 0.0954914 0.0285646 0.0129899 0.0218936 0.436949 0.13 0 0 0 0
QUAD_ERROR [199] 0.0884702 0.103422 0.0626978 0.0526471 0.164511 0.561579 0.13 0 0 0 0
CAV_ERROR [206] 0.00760207 0.00346884 0.00935432 0.00380327 0 0.965653 0.852592 0.3
[X] is the element number, L(mm) parameters can be use to find the particle coordinates at the input of the considered element.
Horizontal example:
,
The final results can be found on the calculation directory. Named “Error_study_Name_TRA.txt” when the result comes from an envelope calculation and “Error_study_Name_PAR.txt” when it is a PARTRAN study. The format of these files is the same for each kind of error. For each step of calculation one line of 32 parameters is written with the following format.
§ Step of error (0>1)
§ 1(Nbr of particles)/(Nbr of particles, reference case)
§ (Emittance rms xx’,yy’,zz’)/ (Reference rms emittance xx’,yy’,zz’)1
§ X beam center (m)
§ Y beam center (m)
§ X’ beam center (rad)
§ Y’ beam center (rad)
§ Energy beam center (keV)
§ Phase beam center (deg)
§ RMS Beam X size (m)
§ RMS Beam Y size (m)
§ RMS Beam X’ size (m)
§ RMS Beam Y’ size (m)
§ RMS Beam Energy size (keV)
§ RMS Beam Phase size (deg)
§ Halo parameter xx’
§ Halo parameter yy’
§ Halo parameter zz’
§ Horizontal dispersion (m)
§ Vertical dispersion (m)
§ Horizontal dispersion / dz
§ Vertical dispersion /dz
§ Apha_XX’
§ Beta_XX’ (m/rad)
§ Apha_YY’
§ Beta_YY’ (m/rad)
§ Apha_PE
§ Beta_PE (deg/MeV)
§ Emittance 4D/Reference emittance 4D1
§ Emittance 6D/Reference emittance 6D1
All these values are relative to the output beam without errors.
In case of statistical study, where each step of calculation contains several runs, the format becomes:
§ Step of error (0>1)
§ AVERAGE(1(Nbr of particles)/(Nbr of particles, reference case))
§ (AVERAGE(Emittance rms xx’,yy’,zz’))/ (Reference rms emittance xx’,yy’,zz’)1
§ RMS(X beam center (m))
§ RMS(Y beam center (m))
§ RMS(X’ beam center (rad))
§ RMS(Y’ beam center (rad))
§ RMS(Energy beam center (keV))
§ RMS(Phase beam center (deg))
§ AVERAGE(RMS Beam X size (m))
§ AVERAGE(RMS Beam Y size (m))
§ AVERAGE(RMS Beam X’ size (m))
§ AVERAGE(RMS Beam Y’ size (m))
§ AVERAGE(RMS Beam Energy size (keV))
§ AVERAGE(RMS Beam Phase size (deg))
§ AVERAGE(Halo parameter xx’)
§ AVERAGE(Halo parameter yy’)
§ AVERAGE(Halo parameter zz’)
§ AVERAGE(Apha_XX’)
§ AVERAGE(Beta_XX’ (m/rad))
§ AVERAGE(Apha_YY’)
§ AVERAGE(Beta_YY’ (m/rad))
§ AVERAGE(Apha_PE)
§ AVERAGE(Beta_PE (deg/MeV))
§ AVERAGE(X beam center (m))
§ AVERAGE(Y beam center (m))
§ AVERAGE(X’ beam center (rad))
§ AVERAGE(Y’ beam center (rad))
§ AVERAGE(Energy beam center (keV))
§ AVERAGE(Phase beam center (deg))
And a file call “Error_study_Name_TRA_tot.txt” or “Error_study_Name_PAR_tot.txt” is written containing all run results.
The final multiparticle results contain one line by element output, the first line being the input beam parameters. The format is like following.
§ Element number
§ Element position (m)
§ Relativistic parameters: (γ1)
§ Centroid position: x(mm), y(mm), j(deg), x’(mrad), y’(mrad), W(MeV)
§ RMS_SIZE [ σ_{x}(mm), σ_{y}(mm), σ_{j}(deg) ]
§ áxx'ñ (mm.mrad), áyy'ñ (mm.mrad), áWφñ (deg.MeV)
§ Normalized rms emit: xx’(mm.mrad), yy’(mm.mrad), jW (deg.MeV).
§ Halo parameters: (H_{xx}_{’}, H_{YY’}, H_{z.}_{dp/p})
§ Number of particles
§ Phase advance with space charge (deg/mm): σ_{x}, σ_{y}, σ_{z}.
§ Emittance at 99%: ε_{xx’}, ε_{yy’}, ε_{z.}_{dp/p}
§ Dj_{s }(°), average beam phase  reference beam phase
§ DW_{s }(MeV), average beam energy  reference beam energy
§ Beam currant (mA) used for space charge calculation
§ Aperture (mm)
§ Normalized 4D transverse emittance E_{xx’yy’ }(mm.mrad)^{2}
§ Normalized rms emit (mm.mrad): ε_{rr’}
§ Phase advance with space charge (deg/mm): σ_{r}
§ Lost power (W)
§ Maximum excursion particle : X_{max}(mm), Y_{max}(mm),
§ Normalized long. rms emit: ε_{z.}_{dp/p} (mm.%) [replace jW(deg.MeV) value]
§ RMS_SIZE [σ_{z}(mm)]
§ áz.dp/pñ (mm.%)
§ Dispersion: D_{h} (mm), D_{v}(mm)
§ Derivative dispersion: D_{h’} (mrad), D_{v’}(mrad)
§ σ_{xy}
§ σ_{x’y’}
§ σ_{xy’}
§ σ_{x’y}
with , same equations for phase spaces [yy'] and [z. dp/p] to get σ_{y} and σ_{dp/p}
Since TraceWin version 2.1.0.0 longitudinal rms emittance jW is set to zero and has been replaced by ε_{z.}_{dp/p}
User has the possibility to set the random seed, in “main” page, in order to regenerate an error case. For remote computing the seed values are saved in a file name “Random_seed.log”.
“Transfer_matrix1.dat” file contains the 6x6 tranfer matrix of the structure from the first to the last element. The syntax is similar to the outputs visible in the tool “Structure tranfer Matrix” from the “Charts” tabsheet.
In “Charts” tabsheet the option “Include structure errors in transfer matrix” defined if the transfer matrix shown in the corresponding tools or saved into the file take or not into account the errors applied to the structure.
During error study, if option “Keep all result files” is selected in tab_shhet “Errors” a list of file ““Transfer_matrix1.dat_XXX” is created.
Circular or rectangular aperture
Electromagnetic static or RF field (Field Map)
Field map with curved reference trajectory
Mnemonic 
Parameter 
Definition 
DRIFT 
L 
Length (mm) 
R 
Aperture (mm) 


R_{y} 
Aperture (mm) 

R_{x}_shift 
Orizontal aperture shift (mm) 
R_{y}_shift 
Vertical aperture shift (mm) 
If R_{y} equals 0, aperture is circular with R radius.
If R_{y} is not equal 0, aperture is rectangular with R the half dimension in x plane and Ry in y plane.
R_{x/y}_shift allows to introduce a noncental aperture.
Link to Drift matrix
Mnemonic 
Parameter 
Definition 
QUAD 
L 
Length (mm) 
QUAD_SPEC 
G 
Magnetic field gradient (T/m) 
R 
Aperture (mm) 

Θ 
Skew Angle (°) 

G_{3} / u_{3} 
Sextupole gradient (T/m^{2}) or relative sex. component 

G_{4} / u_{4} 
Octupole gradient (T/m^{3}) or relative oct. component 

G_{5} / u_{5} 
Decapole gradient (T/m^{4}) or relative deca. component 


G_{6} / u_{6} 
Dodecapole gradient (T/m^{5}) or relative dode. component 
GFR 
Good field radius (mm) 
Attention to the TraceWin gradient definition.
Red values are optional.
If L equals 0, the quadrupole is simulated as thin lens and all gradients have to be replaced by their integral (over longitudinal direction) values.
Multipole kicks are applied at the middle of the quadrupole.
If GFR is non null, u_{n }are relative multipole components will defined such as:
_{}
QUAD_SPEC : is similar to an usual QUAD element except that it is focusing in both horizontal and vertical plane.
Link to Quadrupole matrix
Mnemonic 
Parameter 
Definition 
CONF 
L 
Length (mm) 
ns 
Number of spcecharge kick (Partran only) 

R 
Aperture (mm) 

kx 
Horizontal focusing 

ky 
Vertical focusing 

kz 
Longitudinal focusing 
Link to Containment channel
Mnemonic 
Parameter 
Definition 
BEAM_ROT 
θxy 
Angle (°) in the XY space around Z 
θxz 
Angle (°) in the XZ space around Y 

θyz 
Angle (°) in the YZ space around X 

dx 
X shift (mm) 

dy 
Y shift (mm) 

dxp 
Xp shift (mrad) 

dyp dz centroid_flag 
Yp shift (mrad) Z (mm) 0 : turn around gravity center 
Rotations are first performed in the following order: around Z, Y and X, and finally the shifts. Centroid_flag defines if the rotation is done around beam center of gravity (=0) or if the rotation is done around the synchronous particle (also applied on beam centroid, except energy). BEAM_ROT is considered as an element
Link to Beam rotation matrix
Mnemonic 
Parameter 
Definition 
THIN_LENS 
fx 
Focal Length (m) 
fy 
Focal Length (m) 

R 
Aperture (mm) 
Link to Thin lens matrix
Mnemonic 
Parameter 
Definition 
THIN_MATRIX 
lg 
Length (mm) 

a_{00} to a_{55} 
Matrix terms, row per row 
The 36 terms of a transfer matrix have to be set row by row from a_{00} to a_{55}. Length, lg, is just used in graphic view.
Link to matrix format R
The associated phasespace are respectively: x (m), x’ (rad), y (m), y’ (rad), z (m), dp/p (rad)
Quadrupole Example: THIN_MATRIX 10.0 1 0 0 0 0 0 2.5 1 0 0 0 0 0 0 1. 0 0 0 0 0 2.5 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1
Mnemonic 
Parameter 
Definition 
QUAD_ELE 
L 
Length (mm) 
Vo 
Voltage between electrodes (V) 

R 
Aperture (mm) 

Θ 
Skew Angle (°) 

V_{3} / u_{3} 
Sextupole voltage gradient component (V/m) or relative 

V_{4}/ u_{4} 
Octupole voltage gradient component (V/m^{2}) or relative 

V_{5}/ u_{5} 
Decapole voltage gradient component (V/m^{3}) or relative 


V_{6}/ u_{6} 
Dodecapole voltage gradient component (V/m^{4}) or relative 
GVR 
Good voltage radius (mm) 
Attention to the TraceWin gradient definition.
Vo is the voltage difference between neighboring electrodes (+Vo/2 on one and –Vo/2 on its neighbors). The distance between opposite electrodes is 2R.
In order to keep coherence with old TraceWin version, all electrostatic components are in voltage: (V) and not in field: E (V/m)
If L equals 0, electrostatic quadrupoles are simulated as thin lens and all voltage components have to be replaced by their integral (over longitudinal direction) values.
Multipole kicks are applied at the middle of the electrostatic quadrupole.
If VFR is non null, u_{n }are relative multipole components will defined such as:
_{}
Link to Quadrupole matrix
Mnemonic 
Parameter 
Definition 
GAP 
E_{0}TL 
Effective gap voltage (V) 
θs 
RF phase (deg) (absolute or relative) 

R 
Aperture (mm) 

P 
0: θs is relative, 1: θs is absolute phase, 2: θs is relative + beam phase error set to 0 3: θs if set to 0 all phases are absolute including phase error resulting in preceding structures. If not set to 0, θs is the relative phase including phase error resulting in preceding structure. 

βs 
Particle reduced velocity 

Ts 
Transit time factor 

kT’s 
(*) 

k²T”s 
(*) 
Red parameters are optional
(*) See Transit time factor definition
Bunched cavity or thin gap matrix
Mnemonic 
Parameter 
Definition 
CAVSIN 
L 
Length (mm) 
N 
Cell number 

EoT 
Average accelerating field (V/m) 

θs 
Phase of the synchronous particle at the entrance(deg)(*) 

R 
Aperture (mm) 

P 
1: θs is absolute phase, 0: θs is relative 
(*) Use SET_SYNC_PHASE command in order to change this phase as the synchronous phase
Link to Sinus cavity or CCL matrix
Mnemonic 
Parameter 
Definition 
BEND 
α 
Bend angle in the rotation plane (deg) 
ρ 
Curvature radius of central trajectory (mm) 

N 
Field gradient index 

R 
Aperture (mm) 

HV 
0 : horizontal, 1 : vertical 
Warning: A bend always have to be surrounded by an edge element, even if edge is set to zero.
By definition: a positive bend (denoted α>0) bends the trajectory to the right in the horizontal plane, whatever the sign of the particle charge state.
The field gradient index is treated in the first order and applies only for horizontal bending.
Link to Bending magnet matrix
Mnemonic 
Parameter 
Definition 
EDGE 
b 
Pole face rotation angle (deg) 
ρ 
Curvature radius of bend (mm) 

G 
Total gap of magnet (mm) 

K_{1} 
Fringefield factor (default = 0.45) 

K_{2} 
Fringefield factor (default = 2.80) 

R 
Aperture (mm) 

HV 
0 : horizontal, 1 : vertical 
By definition: an edge focalizes if β < 0, whatever the curvature radius sign, the bending angle sign and the particle charge state.
Set K_{1} and K_{2} to a very small values to disable fringe field estimation.
G is used for particle loss estimation in bend.
Link to Edge angle on bending magnet matrix
Mnemonic 
Parameter 
Definition 
BEND_ELE 
α 
Bend angle in the rotation plane (deg) 
ρ 
Curvature radius of central trajectory (mm) 

ne 
1:Cylindrical, 2:Spherical, 3:Toroidal 

R 
Aperture (mm) 

HV 
0 : horizontal, 1 : vertical 
By definition: a positive bend (denoted α>0) bends the trajectory to the right in the horizontal plane, whatever the sign of the particle charge state.
Only cylindrical bends are available in multiparticle mode.
Mnemonic 
Parameter 
Definition 
APERTURE 
dx 
X half width (mm) or radius hole (pepperpot) 
dy 
Y half width (mm) or distance between hole (pepperpot) 

n 
Type : 0 : Rectangular aperture 1 : Circular aperture 2 : Pepperpot mode 3 : Rectangular aperture with dx & dy corresponding to a beam fraction intercepted by the aperture (adjusted with 0.1 mm step) if value <1, otherwise dx or dy are used as type=0 4 : Horizontal finger with dx=finger center position, dy=total finger width. 5 : vertical finger with dx=finger center position, dy=total finger width. 6 : Ring aperture if particle radius, r>dy or r<dx with (dx<dy) particle is lost. 
Mnemonic 
Parameter 
Definition 
SPACE_CHARGE_COMP 
k 
Beam current is compensated by a factor k 
Set a beam new current: Ib = (1k)×Ib.
Mnemonic 
Parameter 
Definition 
CURRENT 
Ib 
Beam current (mA) 
Set a beam new current: Ib (mA).
Mnemonic 
Parameter 
Definition 
SOLENOID 
L 
Length (mm) 
B 
Magnetic field (T) 

R 
Aperture (mm) 
Solenoid treated as thick length.
Link to Solenoid matrix
Mnemonic 
Parameter 
Definition 
THIN_STEERING 
BLx or ELx 
xcomponent (T.m or V) 
Bly or ELy 
ycomponent (T.m or V) 

r 
Aperture (mm) 

Elec 
0: magnetic deviation (default) 1: electric deviation 
Transverse kick.
Link to Thin steering matrix
Mnemonic 
Parameter 
Definition 
DTL_CEL 
L 
Cell length (mm) 
Lq1 
First ½ quadruploe length (mm) 

Lq2 
Second ½ quadruploe length (mm) 

g_{c }(*) 
Gap center shift (mm) (*) 

B1’ 
First magnetic field gradient (T/m) 

B2’ 
Second magnetic field gradient (T/m) 

EoTL 
Effective gap voltage (V) 

θs 
RF phase (deg) 

R 
Aperture (mm) 

P (**) 
0: θs is relative (**), 1: θs is absolute phase, 2: θs is relative + beam phase error set to 0 3: θs if set to 0 all phases are absolute including phase error resulting in preceding structures. If not set to 0, θs is the relative phase including phase error resulting in preceding structure. 

βs 
Particle reduced velocity 

Ts 
Transit time factor 

kT’s 
(***) 

k²T”s 
(***) 
Define a cell of a classical Drift Tube Linac (DTL).
(*) The g_{c}(mm) dimension is defined as: gap position
(**) This following example is the most realistic RF sequence: All synchronous phase are absolute phase and calculated according to the cell lengths, excepted for the first one which is set to the relative value. The phase error resulting in preceding structures is taken into account. You can canceled the preceding structure phase error by replacing type 3 by type 2 for the first cell
LATTICE 4 1
DTL_CEL 68.729 22.5 22.5 0.0125565 52.5 52.5 176568 30 10 3 0.0807374 0.778491 0.377246 0.1456
DTL_CEL 70.4468 22.5 22.5 0.00912044 52.5 52.5 182799 0 10 3 0.0827489 0.786305 0.366349 0.150419
DTL_CEL 72.1883 22.5 22.5 0.00491998 52.5 52.5 188980 0 10 3 0.0847886 0.79329 0.356535 0.154494
DTL_CEL 73.9529 22.5 22.5 0.000837313 52.5 49.5 195297 0 10 3 0.0868553 0.800245 0.346592 0.157865
DTL_CEL 75.74 22.5 22.5 0.0035088 49.5 49.5 201675 0 10 3 0.0889485 0.806881 0.336968 0.16056
(**) See Transit time factor definition
Red parameters are optional.
If βs does not equal 0, Ts is mandatory.
Link to DTL cell matrix
Mnemonic 
Parameter 
Definition 
NCELLS 
Mode 
(0)2π, (1)π, (2)π & 2π 
Nc 
Number of cell 

βg 
Geometric β > 0: all cell lengths are the same according to βg = 0: cell lengths are set according to beam velocity < 0: cell lengths are set according to an initial beam velocity –βg, which is increasing from cell to cell according to θ_{s} and EoT parameters. 

EoT 
Effective gap voltage (V/m) 

θ_{s} 
RF phase at the first gap position (deg) (**) 

R 
Aperture (mm) 

P 
0: θs is relative , 1: θs is absolute phase, 2: θs is relative + beam phase set to 0 

kEoT_{i} 
Input field correction, Eo = Eo*(1+k) 

kEoTo 
Output field correction, Eo = Eo*(1+k) 

dzi 
First gap displacement (mm) 

dzo 
Last gap displacement (mm) 

βs 
Particle reduced velocity 

Ts 
Transit time factor of the middle gaps 

kT’s 
(*) 

k²T”s 
(*) 

Ti 
Transit time factor of the input gaps 

kT’i 
(*) 

k²T”i 
(*) 

To 
Transit time factor of the output gaps 

kT’o 
(*) 

k²T”o 
(*) 
Modelisation of a multicell cavity by a set of gaps, with one gap at the middle of each cell.
Red parameters are optional
If βs is not equal to 0 Ts become needed
(*) See Transit time factor definition
(**) Use SET_SYNC_PHASE command in order to change this phase as the synchronous phase
Link to Cavity multigap matrix
Mnemonic 
Parameter 
Definition 
RFQ_CELL 
V 
Effective gap voltage (V) 
Ro 
Vane average radius (mm) (*) 

A10 
Acceleration parameter 

m 
Vane modulation 

L 
Cell length (mm) 

θs 
RF phase (deg) 

Type 


Tc 
Transverse curvature (mm) 

 
Not used any more 


a 
Minimum radius (**) 
(*) Vane geometry plotted in envelope chart is made for illustrate the RFQ_CELL element. It’s a rought drawing, expecialy for frontend cells.
(**) Optional parameter, but necessary defined for TWOTERM RFQ.
Link to RFQ cell matrix
Diagnostics measure beam properties at given position.
These measurements are used for the automatic tuning of transport elements to set the measured beam properties to wanted ones. The diagnostics and the associated adjustable transport elements are then linked with a common number. The association is made by preceding the transport elements with the adjust commands followed by the number of the associated diagnostics. The tuning is made in the order of the diagnostic numbers.
In these conditions, a uniform random measurement error is used according to the diagnostic accuracy. If accuracy > 0, the errors are uniformly distributed between ± accuracy value. If accuracy < 0, the errors are Gaussian distributed; accuracy value is then the rms value of the distribution.
Mesured property 
Mnemonic 
Parameter 
Definition 
DIAG_CURRENT 
N 
Diagnostic number 


Ib 
Wanted beam current (mA) or transmission (%) [both could be 0] If input beam current is 0 or flag parameter is not 0 transmission will be used. 



dIb 
Accuracy (mA) or (%) 


flag 





Delta Current 
DIAG_DCURRENT 
N 
Diagnostic number 
(2 are needed) 

Ib_{n}Ib_{n1} 
Wanted Δcurrent (mA) or Δtransmission (%) [both could be 0] If input beam current is 0 or flag parameter is not 0, transmission will be used. 


dIb 
Accuracy (mA) or (%) 


flag 





DIAG_POSITION 
N 
Diagnostic number 



X 
Wanted X beam position (mm), _{(If X<1e50)} 


Y 
Wanted Y beam position (mm), _{(If Y<1e50)} 


dm 
Diagnostic Accuracy (mm) 




Delta position 
DIAG_DPOSITION 
N 
Diagnostic number 


XY 
Wanted XY beam position (mm) 


dm 
Diagnostic Accuracy (mm) 




Divergences 
DIAG_DIVERGENCE 
N 



X’ 
Wanted X divergence (mrad), _{(If Y’<1e50)} 


Y’ 
Wanted Y divergence (mrad), _{(If Y’<1e50)} 


dm 
Diagnostic Accuracy (mrad) 




Delta Divergence 
DIAG_DDIVERGENCE 
N 
Diagnostic number 


X’Y’ 
Wanted XY divergence (mrad) 


dm 
Diagnostic Accuracy (mrad) 




Full Width at Half 
DIAG_SIZE_FWHM 
N 
Diagnostic number 
Maximum (FWHM) 

Sx 
Wanted FHHM X size (mm) _{(If ≠ 0)} 


Sy 
Wanted FHHM Y size (mm) _{(If ≠ 0)} 


ΔP 
Wanted FHHM Phase spread (°) _{(If ≠ 0)} 


Dm 
Size Accuracy (mm) 


dΔP 
Phase spread Accuracy (°) 


fo 
ΔP Lowpass filter frequency (MHz) 




DIAG_SIZE 
N 
Diagnostic number 



Sx 
Wanted X rms size (mm) _{(If ≠ 0)} 


Sy 
Wanted Y rms size (mm) _{(If ≠ 0)} 


ΔP 
Wanted rms Phase spread (°) _{(If ≠ 0)} 


Dm 
Size Accuracy (mm) 


dΔP 
Phase spread Accuracy (°) 


fo 
ΔP Lowpass filter frequency (MHz) 




Divergences 
DIAG_SIZEP 
N 
Diagnostic number 

Sx’ 
Wanted X’rms divergence (mrad) (If _{≠ }0) 



Sy’ 
Wanted Y’rms divergence (mrad) (If _{≠ }0) 
if S<0 Twiss 

ΔW 
Wanted rms Energy spread (MeV) (If _{≠ }0) 
parameter alpha will 

Dm 
Divergence Accuracy (mrad) 
set <0 

dW 
Energy spread Accuracy (%) 




Delta Full Width at 
DIAG_DSIZE_FWHM 
N 
Diagnostic number 
Half Maximum 

x_{n}y_{n} 
Wanted xy FWHM delta size (mm) 
(FWHM) 

dm 
dxy size Accuracy (mm) 




Delta size 
DIAG_DSIZE 
N 
Diagnostic number 
XrmsYrms 

x_{n}y_{n} 
Wanted xy rms beam delta size (mm) 


dm 
dxy size Accuracy (mm) 




Delta Full Width at 
DIAG_DSIZE2_FWHM 
N 
Diagnostic number 
Half Maximum 

x_{n}x_{n1} 
Wanted x HWHM delta size (mm) 
between 2 positions 

y_{n}y_{n1} 
Wanted y HWHM delta size (mm) 
(At least 2 are 

dm 
dx & dy size accuracy (mm) 
needed) 



Delta size 
DIAG_DSIZE2 
N 
Diagnostic number 
between 2 positions 

x_{n}x_{n1} 
Wanted x rms beam delta size (mm) 
(At least 2 are 

y_{n}y_{n1} 
Wanted y rms beam delta size (mm) 
needed) 

dm 
dx & dy size accuracy (mm) 




Delta phase spread 
DIAG_DSIZE3 
N 
Diagnostic number 
Measurement 2 

ΔP_{n}ΔP_{n1} 
Wanted rms delta phase spread (°) 
(At least 2 are 

dΔP 
Phase spread accuracy (°) 
Needed) 

fo 
dΔP Lowpass filter frequency (MHz) 




Delta divergence 
DIAG_DPSIZE2 
N 
Diagnostic number 
between 2 positions 

x'_{n}x’_{n1} 
Wanted x’ rms beam delta div. (mrad) 
(At least 2 are 

y’_{n}y’_{n1} 
Wanted y’ rms beam delta div. (mrad) 
needed) 

dpm 
dx' & dy’ div. accuracy (mrad) 




DIAG_PHASE 
N 
Diagnostic number 



Θ 
Wanted centroïd Phase (°) 




Energy measurement 
DIAG_ENERGY 
N 
Diagnostic number 


W 
Wanted Energy (MeV) 


dw 
Accuracy (%) 




Beam energy  Perfect 
DIAG_DENERGY 
N 
Diagnostic number 
linac energy measurement 

W 
Wanted Delta Energy (MeV) 


dw 
Accuracy (%) 




Beam phase  Perfect 
DIAG_DPHASE 
N 
Diagnostic number 
linac phase measurement 

Θ 
Wanted delta centroïd Phase (°) 




Luminosity 
DIAG_LUMINOSITY 
N 
Diagnostic number 


Lu 
Wanted luminosity (mm^{}²) 


Dlu 
Luminosity accuracy (mm^{}²) 




Waist setting 
DIAG_WAIST 
N 
Diagnostic number 


fx 
XX’ waist asked (for fx not equal to 0) 


fy 
YY’ waist asked (for fy not equal to 0) 


dxy 
Transverse waist Accuracy 




Achromat setting 
DIAG_ACHROMAT 
N 
Diagnostic number 


Ele# ^{(**)} 
First element number ^{(**)} 


f1 
If =1 set achromatic position 


f2 
If =1 set achromatic angle 


plan 
0 : X or Y or both planes acccoding to bend direction are concerned 1 : only X plan is concerned 2 : only Y plan is concerned 3 : both planes are concerned 
Emittance setting 
DIAG_EMIT 
N 
Diagnostic number 
(rms values) 

Exx’ 
Wanted emittance if greater than 0 


Eyy’ 
Wanted emittance if greater than 0 


Epw 
Wanted emittance if greater than 0 




Emittance setting 
DIAG_EMIT_99 (*) 
N 
Diagnostic number 
(99% value or others) 

Exx’ 
Wanted emittance if greater than 0 


Eyy’ 
Wanted emittance if greater than 0 


Epw 
Wanted emittance if greater than 0 




Halo setting 
DIAG_HALO 
N 
Diagnostic number 


Hx 
Wanted haloX if greater than 0 


Hy 
Wanted haloY if greater than 0 


Hz 
Wanted haloZ if greater than 0 




Transfer matrix 
DIAG_SET_MATRIX 
N 
Diagnostic number 
setting 

Ele# ^{(**)} 
Transfer matrix form element number, Ele#, to diag. position ^{(**)} 


Row(i) 
Row transfer matrix term 


Column(j) 
Column transfer matrix term 


k 
Corrector coefficient 


Mij 
Wanted transfer matrix term value 
Beam Twiss parameters setting
Parameter is used if it is not equal to 0,
If you want α=0 set very small α 
DIAG_TWISS 
N 
Diagnostic number 
α_{xx'} 
Wanted alpXX’ 


β_{xx’} 
Wanted betXX’ (mm/mrad) 


α_{yy'} 
Wanted alpYY’ 

β_{yy’} 
Wanted betYY’ (mm/mrad) 

α_{zdp/p} 
Wanted alpZdp/p 

β_{zdp/p} 
Wanted betZdp/p (mm/mrad) = 10 x time betZdp/p (mm/%) 

Make equal 2 beam Twiss parameters between 2 positions or more, (At least 2 are needed). The flag parameters must be defined in the first diagnostics to decide which quantity will be equalised.

DIAG_DTWISS 
N 
Diagnostic number 
fα_{xx'} 
(1/0) 

fβ_{xx’} 
(1/0) 

fα_{yy'} 
(1/0) 

fβ_{yy’} 
(1/0) 

fα_{zdp/p} 
(1/0) 

fβ_{zdp/p} 
(1/0)


Make equal transverse Twiss parameter at diagnostic position 
DIAG_DTWISS2 
N 
Diagnostic number 

fα 
If (fα=1) α_{xx’ }– α_{yy}’ is set to 0 


fβ 
If (fβ=1) β_{xx’ }– β_{yy}’ is set to 0


Beam separation setting 
DIAG_SEPARATION 
N k 
Diagnostic number Correction factor (set 1) 

S 
Wanted separation (ks.Size/Position+kc.Position) 



0/1 
0 for X plane, 1 for Y 

ks 
Weigth on separation 


kc 
Weigth on position 





Limit beam size max 
DIAG_SIZE_MAX ^{(***)} 
N N_ele
S_{x0} 
Diagnostic number Number of upstream elements concerned Wanted max beam size X (mm), if !=0 
Limit beam size min 
DIAG_SIZE_MIN ^{(***)} 
S_{y0} 
Wanted max beam size Y (mm), if !=0 

S_{z0} 
Wanted max beam size Z (mm,deg), if !=0 If S_{z} < 0 Z size in mm otherwise in deg 


Flag_cent 
If 1, beam size includes beam centroid 





Set beam phase advance 
DIAG_PHASE_ADV 
N Ele# ^{(**)}
σ_{x0} 
Diagnostic number Phase advance form element number, Ele#, to diag. position ^{(**)} Wanted X phase advance (deg), if !=0 

σ_{y0} 
Wanted Y phase advance (deg), if !=0 

Set beam beta 
DIAG_BETA 
N 
Diagnostic number 


β_{x} 
Wanted betX (mm/mrad) if >0 


β_{y} 
Wanted betY (mm/mrad) if >0 


β_{z} 
Wanted betZ (mm/(dp/p)) if >0 


f 
0: Twiss beta / 1: Beta function 


Dm 
Accuracy 
Set delta Beam beta 
DIAG_DBETA 
N 
Diagnostic number 


β_{x}  β_{y} 
Wanted Delta beta (mm/mrad) 


f 
0: Twiss beta / 1: Beta function 


Dm 
Accuracy 
^{(*) }99% fraction must be set in “Multiparticle” tabsheet, then go to “99.XX% emittance and halo”,then select the fraction you want.
^{ }
^{(**) }if ( Ele#>0 ) then Ele# is absolute
if ( Ele#<0 ) then Ele# is relative, e.g. 15 means relative to location 15 elements upstream.
TraceWin can be used to verify if a beam line contains enough diagnostics to control the beam and correct the errors coming from the input beam or from the different element errors. In order to put one diagnostics in the line use the elements “DIAG_…” followed by the diagnostic number and the wanted parameters which have to be imposed at the diagnostic location (current, position, size or emittance). Precede the associated adjustable transport elements by the adjust commands followed by the number of the associated diagnostic.
There are two ways of using these diagnostics. The first one is for example to see if your design is able to control the beam position at a given location when you input beam is not at the center or if a few elements, like steerers induce misalignment. The second way is to use diagnostics in an error study in order to see if you scheme of misalignment correction for example is efficient enough.
The diagnostics adjustments are independent process, which occurs after the matching process. If any diagnostic element is present any adjustment is started. Finally, at the end of a line design process, only diagnostic elements should be used to tune it.
Warning: They are treated in the order of the diagnostic number.
Link to Adjust and diagnostics examples
Note: many transport elements can be coupled to many diagnostics. The tuning is made by minimizing a criterium being the quadratic sum of the differences between effective beam properties and wanted ones divided by the wanted one. The relative weight on the criterion of each difference can be changed by putting a weight factor between brackets like following:
DIAG_EMIT(1e4) 1 0.1 0.1 0.2 , here this diagnostic emittance criteria is reduced by a factor 10000.
MY_DIAG(my_diag_func)(1e4) 1 0.1 0.1 0.2 , for diagnostic developed by user.
By default, without bracket, the factor is set to 1.
NEW (2.13.0.5): Diagnostics transverse positions can be linked to following element position affected by errors and SHFIT commands. The syntax consists to add @ to the diagnostic name, ex: “DIAG_POSITION@ “.
NEW (2.15.0.0): Diagnostics can overlop Field map elements, see SHIFT_IN_FIELD_MAP
(***) DIAG_SIZE_MAX / MIN
S_{x}, S_{y}, S_{z,φ} are the imposed beam size max in the N_ele elements upstream this diagnostic.
When Sx > Sx_{0} set size max criterion: _{ }
When Sx < Sx_{0} set size min criterion: _{ }
Otherwiser vcr = 0
With Sx(mm), Sy(mm), Sz(mm,deg) being the beam maximum sizes in the N_ele elements upstream the diag “DIAG_SIZE_MAX / MIN” position, and Sxo(mm), Sxo(mm), Szo (mm,deg) being the wanted beam sizes. The sizes are the effective beam sizes (rms* for bunched beam or rms* for CW beam. If S_{z} is lower than 0 the longitudinal size used is (mm) otherwize (deg). If Flag_cent=0, the transverses sizes are is calculated without taking account the beam centroid position.
Does not work in tracking mode
A funneling gap models a RF cavity filed with a RF transverse electric field allowing to merging two beam lines into one.

Mnemonic 
Parameter 
Definition 
Funneling Gap 
FUNNEL_GAP 
EoTL 
Effective gap voltage (V) 


Θs 
RF phase (deg) (absolute or relative) 


R 
Aperture (mm) 


p 
1: θs is absolute phase, 0: θs is relative 




Frame change 
CHFRAME 
Xo 
(mm) 


X’o 
(deg) 
Link to Funneling gap matrix
An alpha magnet is a magnetic element elongating the trajectory of particles with higher energy. It is used to compress bunched beam.
Mnemonic 
Parameter 
Definition 
ALPHA_MAGNET 
Θ 
Entrance angle (°) 

K 
(T/m) 

R 
Aperture (mm) 

plan 
0 (x)/1 (y) 
Link to Alpha magnet matrix
The element simulates acceleration in electrostatic accelerators.
Mnemonic 
Parameter 
Definition 
ELECTROSTA_ACC 
Vo 
Voltage (V) 

L 
Length (mm) 

K 
Transverse defocal (eV/ mm²) 

R 
Aperture (mm) 
Link to Electrostatic Acceleration matrix
This element introduces static or RF electromagnetic elements whose field maps (1D, 2D or 3D) are given in files. These maps can be superimposed. Dedicated to linac, it was initially dedicated to fields not deflecting the main trajectory (quadrupoles, solenoids, cavities). Since version xxx, it can also deal with fields deflecting the beam main trajectory.
Mnemonic 
Parameter 
Definition 
FIELD_MAP 
geom 
Field map type 

L 
Field map length (mm) 

θi 
RF phase (°) 

R 
Aperture (mm) 

kb 
Magnetic field intensity factor 

ke 
Electric field intensity factor 

Ki 
Space charge compensation factor 

Ka 
Aperture flag 

FileName 
File name without extension (abs. or relative path) 

P 
0: θi is relative phase 1: θi is absolute phase 
geom parameter is an integer, made of 5 figures, defining the field map type :
o unit figure (10^{0}) : static electric field,
o tens figure (10^{1}) : static magnetic field,
o hundreds figure (10^{2}) : RF electric field,
o thousands figure (10^{3}) : RF magnetic field,
o ten thousands figure (10^{4}) : 3D aperture map (since 2.4.0.1 version),
where each figure describes the field geometry :
0  no field,
1  1D : Fz(z),
2  not available,
3  not available,
4  2D cylindrical static or RF electric field : Ez(r,z), Er(r,z) and Bθ(r,z) for RF,
5  2D cylindrical static or RF magnetic field : Bz(r,z), Br(r,z) and Eθ(r,z) for RF,
6  2D Cartesian field: Fx(x,y), Fy(x,y),
7  3D Cartesian field: Fx(x,y,z), Fy(x,y,z), Fz(x,y,z),
8  3D cylindrical field : Fr(r, θ,z), Fθ (r,θ,z), Fz(r,θ,z), not implemented yet,
9  1D : G(z), only use for magnetic quadrupole, thus geom parameter has to be set to 0090 (see 3D field development for more details).
By convention, one uses: Ez(x,y,z,t) = Ez0(x,y,z).cos(wt+j) and Bz(x,y,z,t) = Bz0(x,y,z).sin(wt+j).
Be careful, the relative sign of the electric and magnetic fields given in the files should be coherent with this convention.
For example, the given magnetic field should be the one obtained a quarter of RF period after the electric one. In another words, if the electric field amplitude is given at a time when it is fully real, one should give the opposite of the imaginary part of the magnetic field at the same time.
For cylindrical field the convention is following:
Bx=  Bθ(r,z) y/r
By= + Bθ(r,z) x/r
x, y, z is in a direct frame.
L is the field map length along z direction.
θi is the RF phase when the generatrix particle enters the cavity.
Use SET_SYNC_PHASE command in order to change this phase as the synchronous phase.
R is the pipe radius along synchronous trajectory.
kb and ke are multiplicative factors between the field (respectively magnetic and electric) stored in the file anf the field used in the simulation. Kb can be defined as power supply current, if an excitation curbe is defined, see EXCITATION_CURVE command
If Ki is greater than 0, a space charge compensation map or current map is readed in “FileName.scc” and Ki is the normlization factor (see Space charge compensation file syntax). In the case overlapping field map, the length of the space charge compensation map must cover the whole set of field maps and must start at position 0.
If Ka equals 0, a particle is considered as lost when it comes out of the aperture R or field_map frame size defined in field_map files. If Ka equals 1, a beam pipe radius map is read in “FileName.ouv” factor (see Aperture map file syntax). If Ka equals 2, R is not used and the particle is not lost when it comes out field map frame. That allows superposing small size field maps inside bigger one. In the case overlapping field map, the length of the pipe map must cover the whole set of field maps and must start at position 0.
FileName is the root name (without extension) of the files where are localized the field maps (extension: .bsz, .bsr, .edx …), the space charge compensation map (.scc) and the beam pipe radius evolution with z (.ouv). See the file formats description
The file extensions are the following:
 the first character indicates the field nature : either electric (à ‘e’) or magnetic (à ‘b’),
 the second character indicates the field type : either static (à ‘s’) or RF (à ‘d’),
 the third character indicates the field component : ‘x’, ‘y’, ‘z’, ‘r’ (radial) or ‘q’ (azimuthal),
Field in 1D: the field can be described in 1D, field according to z position
 1 file contains the static electric field : *.esz
 1 file contains the static magnetic field : *.bsz
 1 file contains the RF electric field : *.edz
 1 file contains the RF magnetic field : *.bdz
 1 file contains the G(z) : *.bsz
From v.2.3.1.8, if the geom parameter value is negative, the offaxis development is performed at second order (default: first order).
Field in 2D: the fields can be described in 2D Cartesian (invariant through translation on z axis) or in cylindrical (invariant through rotation around the z axis) coordinates.
 In Cartesian coordinates (x, y) :
o 2 files contain the static electric field : *.esx, *.esy
o 2 files contain the static magnetic field : *.bsx, *.bsy
o 2 files contain the RF electric field : *.edx, *.edy
o 2 files contain the RF magnetic field : *.bdx, *.bdy
 In cylindrical coordinates (r, z, θ) :
o 2 files contain the static electric field : *.esr, *.esz
o 2 files contain the static magnetic field : *.bsr, *.bsz
o 3 files contain the RF fields (TM) : *.edr, *.edz, *.bdq
o 3 files contain the RF fields (TE) : *.bdr, *.bdz, *.edq
Field in 3D: the fields can be described in 3D either Cartesian or cylindrical frame.
 In Cartesian coordinates (x, y, z)
o 3 files contain the static electric field : *.esx, *.esy, *.esz
o 3 files contain the static magnetic field : *.bsx, *.bsy, *.bsz
o 3 files contain the RF electric field : *.edx, *.edy, *.edz
o 3 files contain the RF magnetic field : *.bdx, *.bdy, *.bdz
 In cylindrical coordinates (r, θ, z)
o 3 files contain the static electric field : *.esr, *.esq, *.esz
o 3 files contain the static magnetic field : *.bsr, *.bsq, *.bsz
o 3 files contain the RF electric field : *.edr, *.edq, *.edz
o 3 files contain the RF magnetic field : *.bdr, *.bdq, *.bdz
3D aperture: the aperture file has to be described in 3D Cartesian coordinates. ‘1’ for matter and ‘0’ for air.
o 1 file contains 3D aperture data : *.ouv
File name syntax:
 without extension and without path if files are in the data file (*.dat) directory,
 including path without extension if not.
 including path without extension between quote marks, if there are some space characters in the path.
 for simplicity, use “FIELD_MAP_PATH path of my_field_map_files” command at the beginning of the data file (.dat), replacing all the defined field map path. No quote is needed. Path can be defined as relative of absolute to ini project file path.
Link to Particle motion in electromagnetic field
Each individual element, described by a field map, is associated to a FIELD_MAP keyword:
FIELD_MAP xxxx L θ R kb ke Ke Ka Filename
The file Filename contains the field value in a regular mesh (x, y, z) in the element frame.
If field maps of different elements are superposed, their respective positions are given in the laboratory frame (X, Y, Z) where:
 (X=0, Y=0, Z=0) is the position of the reference particle when entering the field map(s) superposition,
 are along the associated directions in TraceWin when entering the field map(s) superposition.
In this frame, each field map is located using the SUPERPOSE_MAP keyword whose syntax is:
SUPERPOSE_MAP Z_{0} X_{0} Y_{0} θ_{ Z0} θ_{ X0} θ_{ Y0}
Where:
(X_{0}, Y_{0}, Z_{0}) gives to the position in [mm], in (X, Y, Z) frame, of the (x=0, y=0, z=0) point of the field map. To start at the Z(mm) position in a field map, set Z_{0} = Z.
(θ_{ X0}, θ_{ Y0}, θ_{ Z0}) gives the rotation angles in [°] between and ,
θ_{ X0 }corresponds to the rotation angle around X axis (in YZ plane).
θ_{ y0 }corresponds to the rotation angle around Y axis (in XZ plane).
θ_{ z0 }corresponds to the rotation angle around Z axis (in XY plane).
The first applied rotation is around Z, then Y, and finally X.
Be careful to the order of parameters!
Before version 2.8.0.0, the preceding keywords were already valid and could be used only when the field map were not deviating the beam for which the reference trajectory was a straight line (describing, for example, solenoids, quadrupole or RF cavities).
From version xxx, they can also be used to indicate that the reference trajectory is curved by the elements. The SUPERPOSE_MAP_OUT keyword informs it to TraceWin. It has to be placed before the description of the field maps. Its syntax is:
SUPERPOSE_MAP_OUT Z_{0} X_{0} Y_{0} θ_{ Z0} θ_{ X0} θ_{ Y0}
(X_{0}, Y_{0}, Z_{0}) gives to the position in [mm], in (X, Y, Z) frame, of the exit point of the simulation in the field map,
(θ_{ X0}, θ_{ Y0}, θ_{ Z0}) gives the rotation angles in [°] between the reference trajectory directions at the exit point of the simulation in the field map and,
θ_{ X0 }corresponds to the rotation angle around X axis (in YZ plane).
θ_{ y0 }corresponds to the rotation angle around Y axis (in XZ plane).
θ_{ z0 }corresponds to the rotation angle around Z axis (in XY plane).
The first applied rotation is around Z, then Y, and finally X.
Be careful to the order of parameters!
TraceWin calculates the deviated reference trajectory until it crosses the exit plan. The beam dynamics is then calculated around this reference trajectory. At the exit of calculation, TraceWin displaces and rotates the beam according to the positions and angles given with SUPERPOSE_MAP_OUT.
In the following example, available in the menu “Examples” of the mneu Help”, (“field_map_dipole.ini” project), a magnetic dipole field map is partially superposed with a quadrupole magnetic field map.
A second example more complexe is also available, “field_map_dipole2.ini”.
This configuration is described with the following TraceWin file:
; F2
SUPERPOSE_MAP_OUT 1573.29 164.27 0 0 0 9.59023
; F0
SUPERPOSE_MAP 0 0 0 0 0 0
FIELD_MAP 0070 1200 0 1000 1.0 0.0 0 0 dipole
; F1
SUPERPOSE_MAP 1100 84.27 0 0 0 9.59023
FIELD_MAP 70 480 0 200 10.0 0.0 0 0 qpole
DRIFT 100 100
END
This configuration can be visualized using the "Synotic" tool of the "Charts" page without any simulation, this allows to check the right position of each element before starting a simulation.
The associated beam envelopes are given below.
If your ouptut frame is not correctly defined in SUPERPOSE_MAP_OUT, positions and angles shifts are applied at the end of the calculation in the superposed field_map.
Using: SUPERPOSE_MAP_OUT 1573.29 170.0 0 0 0 11.0
Instead of: SUPERPOSE_MAP_OUT 1573.29 164.27 0 0 0 9.59023
Positioning of field maps
Each individual element, described by a field map, is associated to a FIELD_MAP keyword:
FIELD_MAP xxxx L θ R kb ke Ke Ka Filename
It is possible to place the field map with any shifted position or/and orientation relatively to the reference frame. The principle is to give the coordinates of the field map origin along with the angle of its frame in the reference frame.
Let's (0, X, Y, Z) be the origin and the axes of the initial reference frame, at the exit of the upstream element, and (0_{i}, X_{i}, Y_{i}, Z_{i}) those of the frame of the field map i. In order to place the field map i as indicated in the figure, use the command SUPERPOSE_MAP before the FIELD_MAP command as following:
SUPERPOSE_MAP Z_{i} X_{i} Y_{i} θ_{Zi} θ_{Xi} θ_{Yi}
Pay attention to the order of parameters!
The lengths are in meter and the angles in degree.
Several field maps can be superimposed in the same space, in any order.
In fact, when the SUPERPOSE_MAP commands are used alone, only the parameter Z_{i} is effective. For the other parameters to be taken into account, those commands must preceded by the SUPERPOSED_MAP_OUT command. The latter can also be used for defining an exit reference frame that is different from the initial one. This is particularly useful in case one of the field maps is a dipole. The principle is the same as for the field map frame. In order to place the exit reference frame as indicated in the figure, use the command SUPERPOSE_MAP_OUT as following:
SUPERPOSE_MAP_OUT Z_{out} X_{out} Y_{out} θ_{Zout} θ_{Xout} θ_{Yout}
Notice that this last command, SUPERPOSE_MAP_OUT, must be used ahead all the SUPERPOSE_MAP commands.
To summarize, the positioning of field maps can be done with the typical commands:
SUPPERPOSE_MAP_OUT ………..
.
.
.
SUPPERPOSE_MAP …………
FIELD_MAP ………….
SUPPERPOSE_MAP …………..
FIELD_MAP ………..
.
.
.
DRIFT ………….
Note that when the SUPERPOSE_MAP_OUT command is used, the reference trajectory is the one linking properly, with the proper deviation, the initial reference frame to the exit one. In graphic representations such as for beam envelope, this reference trajectory is a straight line placed at axis origin. This is what is classically done in accelerator physics.
In order to check if the exit reference frame is correctly positioned as regard to the field map(s) or not, add a drift of enough length at the end of the structure. If it is correct, then the reference trajectory would not present any discontinuity neither in position nor in angle when passing from the field map to the drift.
In order to see the reference trajectory in the field map(s) with its real deviations and positions (and not a straight line), don't use the SUPERPOSE_MAP_OUT command, while keeping the SUPERPOSE_MAP commands. In this case, only the Z_{i} are taken into account and all the other parameters are ignored. So this is only useful when all the maps are aligned with same X, Y, q parameters. Then the beam can be made entering the field map(s) with right X, Y, q parameters by using the Beam Center shifts available at the "Twiss parameters" button of the "Main" tab.
Notice that in all cases, the "Field Map Viewer" will take into account only the Z_{i} parameters and not the other parameters.
Mnemonic 
Parameter 
Definition 
MULTIPOLE 
Order 
Multipole order 

L 
Field map length (mm) 

Nstep 
Number of step along x & y direction 

field 
Magnetic or electic field on pole (T or MV/m) 

R 
Aperture (mm) 

Lsol 
Physical length (mm) of solenoid (Order=0) 

Zstep Elec 
Number of step for solenoid case (Order=0) 0: Magnetic field map, 1:Electrique field map 
Attention to the TraceWin gradient definition.
The mutipole element generates a 2D (x, y) static magnetic field map file whose steps sizes are: dx = dy = 2.R/Nstep. The step along z direction is defined by TraceWin calculation step. The simulation is made in this field map. Be aware that 2.R/Nstep must be much lower than the beam size.
Order parameter sets the order of the multipole field:
 Order = 0: (Special mode) for solenoid field map (Br(r,z) & Bz(r,z)),
 Order = 1: for dipole,
 Order = 2: for quadrupole,
 Order = 3: for sextupole,
 Order = 4: for octupole,
 …
L is the field map length along z direction.
Nstep defines the number of steps in the generated field map.
B is the magnet
SUPERPOSE_MAP command can be used with this element.
Change element parameters:
Add or change variable, (including or not math expressions)
Move diagnostics in field map element
RFQ:
Lattice commands:
Matching commands:
Minimize beam envelope variation
Errors:
Set of field map
Apply phase error to synchronous phase
Read a multiparticle output file
Magnetic or electric static field
Change transverse beam centroid
FREQ f(Mhz)
FREQ command changes the R.F. frequency of the following structure, the beam frequency is not affected. By default, the RF frequency is the beam frequency defined in the TraceWIN GUI.
VARIABLE name value
Varaible can added or changed at any position in the structure as shown in the example below. Name is case sensitive. Attention in the final structure file (*.dat) written at the end of a run, the variables in the elements will all have been replaced by their values.
VARIABLE Gr1 100.0
VARIABLE Gr2 150.0
VARIABLE Apert 35.0
DRIFT 10 10
QUAD 56 Gr1 25
DRIFT 10 10
QUAD 56 Gr1 Apert
DRIFT 10 10
QUAD 56 Gr2 25
DRIFT 10 10
QUAD 56 Gr2 25
DRIFT 10 10
VARIABLE Gr1 120.0
QUAD 56 Gr1 25
END
Mathematical expressions containing the usual mathematical operators (+,,/,*,^,%) and standard mathematical functions can be implemented when at least one variable is used, as in the following examples:
(The following math functions are supported: abs, acos, asin, atan, atan2, ceil, cos, cosh, exp, floor, ln, log, log10, pow, sin, sinh, sqrt, tan, tanh, fac)
VARIABLE VA1 0.11
VARIABLE VA2 0.22
DRIFT VA1 10 OK
DRIFT 2*VA1 10 OK
DRIFT cos(VA1) 10 OK
DRIFT cos(VA1+VA2+0.1) 10 OK
DRIFT cos(VA1 +VA2+0.1) 10 NOT_OK (because space chars in the equation string are not allowed)
DRIFT sqrt(0.2*VA1+0.1) 10 OK
DRIFT sqrt(0.2+0.1) 10 NOT_OK (because there is no variable)
DRIFT sqrt(0.2*VA1+0.1) 10*VAR2 OK
An ADJUST command placed on a variable will not change the variable but the result of the expression, so this variable will not be changed on the other locations where it is located (see following example).
VARIABLE VA1 0.11
ADJUST 1
DRIFT VA1 10 drift length=0.11 value will be adjsuted
DRIFT 2*VA1 10 drift length will be set to 2*0.11, even after adjustment.
DOUBLET_START
DOUBLET_END
When ‘Set doublet with the same gradient’ option from “Main’ page is selected, the quadrupoles of doublet located in the same machine period are set to same gradient. Both command ‘DOUBLET_START’ and ‘DOUBLET_END’ allows to control the zones where are applied this options.
LATTICE n1 n2
LATTICE command defines the periodic focusing lattices, n1 is the number of element per basic lattice, n2 is the number of lattice per macrolattice (usually 1). The number of element per macrolattice is then n1×n2. The basic lattice is used for set the phase advances according to SET_ADV commands. The macrolattice is used for the phase advance calculation and corresponding matching. All following elements are considered as part of the next lattices until reaching the commands LATTICE_END or END.
The following elements are not included in lattice element counting:
· DIAG_XXX,
· APERTURE,
· THIN_STEERING.
LATTICE_END
LATTICE_END command ends the periodic focusing lattices.
END
END command ends a structure file (*.dat) description (compulsory).
SET_ADV kx_{0t} _{ }ky_{0t}
The SET_ADV command sets the zerocurrent horizontal phase advance to kxot and the zerocurrent vertical phase advance to kyot.
By default, without kyot value, kyot = kxot.
The periodic focusing lattices structure has to be defined by using the command LATTICE and LATTICE_END, in order to indicate the number of lattice and the number of element per lattice.
The zerocurrent transverse phase advance law can be imposed in two ways:
When the option “Use phase advance definition” of “Main” page is checked, TraceWin imposes the zerocurrent transverse phase advance law describe in the Sigma0 file . This file is editable in the “Main” page
If the option “Use phase advance definition” is unchecked that means you have to use the commands SET_ADV in you data file in order to describe your phase advance law.
;FODO lattices in a DTL tank
;Tank 1
LATTICE 2 1
SET_ADV 30
DTL_CEL 87.5277 28 28 0.00548673 71.3977 71.6524 74699.4 50 10 0 0.102751 0.723252 0.475485 0.194532
DTL_CEL 87.9518 28 28 0.0080072 71.6524 71.9632 76721.8 49.5 10 0 0.103248 0.726628 0.470582 0.195991
DTL_CEL 88.3919 28 28 0.0112292 71.9632 72.2903 79282.7 49 10 0 0.103764 0.734598 0.458632 0.197949
DTL_CEL 88.8487 28 28 0.0144758 72.2903 72.5931 81864.3 48.5 10 0 0.104299 0.742159 0.447189 0.199371
DTL_CEL 89.3222 28 28 0.0177645 72.5931 72.9101 84484.9 48 10 0 0.104853 0.74948 0.436027 0.200384
DTL_CEL 89.8133 28 28 0.0212224 72.9101 73.1977 87251.7 47.5 10 0 0.105428 0.757488 0.423767 0.201319
DTL_CEL 90.3217 28 28 0.0245936 73.1977 73.4992 89953.5 47 10 0 0.106024 0.764331 0.413161 0.201532
DTL_CEL 90.8475 28 28 0.0280032 73.4992 73.7703 92694.2 46.5 10 0 0.10664 0.770931 0.402823 0.201301
DTL_CEL 91.3909 28 28 0.0314415 73.7703 74.0554 95477.4 46 10 0 0.107276 0.777317 0.392802 0.200986
SET_ADV 60
DTL_CEL 91.952 28 28 0.0349097 74.0554 74.3058 98302.2 45.5 10 0 0.107934 0.783481 0.38306 0.200411
DTL_CEL 92.5298 28 28 0.0379774 74.3058 74.5691 100888 45 10 0 0.108611 0.787243 0.377176 0.2003
DTL_CEL 93.124 28 28 0.0410704 74.5691 74.8056 103520 44.5 10 0 0.109308 0.790922 0.371402 0.200107
DTL_CEL 93.7349 28 28 0.0442596 74.8056 75.056 106233 44 10 0 0.110024 0.794763 0.365289 0.199539
DTL_CEL 94.3626 28 28 0.0473999 75.056 75.2835 108961 43.5 10 0 0.11076 0.798277 0.35973 0.199184
DTL_CEL 95.0078 28 28 0.0507833 75.2835 75.5255 111880 43 10 0 0.111516 0.802715 0.352626 0.198381
DTL_CEL 95.6703 28 28 0.0539705 75.5255 75.7413 114710 42.5 10 0 0.112293 0.80606 0.347306 0.197902
DTL_CEL 96.3499 28 28 0.0571744 75.7413 75.9704 117592 42 10 0 0.11309 0.809328 0.342081 0.197341
DTL_CEL 97.0469 28 28 0.0603973 75.9704 76.1784 120527 41.5 10 0 0.113907 0.812524 0.336963 0.196748
DTL_CEL 97.7612 28 28 0.0636044 76.1784 76.3982 123492 41 10 0 0.114744 0.815493 0.332338 0.196611
SET_ADV 40
DTL_CEL 98.4937 28 28 0.0670821 76.3982 76.5998 126672 40.5 10 0 0.115603 0.819426 0.325941 0.195469
DTL_CEL 99.244 28 28 0.0703571 76.5998 76.8124 129777 40 10 0 0.116483 0.822424 0.321067 0.19464
DTL_CEL 100.013 28 28 0.0738459 76.8124 77.0048 133061 39.5 10 0 0.117384 0.826103 0.315053 0.193443
DTL_CEL 100.8 28 28 0.0771374 77.0048 77.209 136276 39 10 0 0.118307 0.828909 0.31049 0.192635
DTL_CEL 101.604 28 28 0.0804404 77.209 77.395 139551 38.5 10 0 0.11925 0.831652 0.306016 0.191796
DTL_CEL 102.428 28 28 0.0839794 77.395 77.5934 143023 38 10 0 0.120216 0.835125 0.30028 0.190411
DTL_CEL 103.271 28 28 0.0875319 77.5934 77.7738 146561 37.5 10 0 0.121204 0.838521 0.29462 0.188871
DTL_CEL 104.132 28 28 0.0908581 77.7738 77.9644 150025 37 10 0 0.122213 0.841052 0.290457 0.187938
LATTICE_END
END
“LATTICE 2 1” defines the periodic focusing lattices, 2 is the number of element per lattice (2 DTL cell), 1 is the number of lattice per macrolattice (generally 1). And TraceWin imposes a phase advance linear continuity between each “SET_ADV” command. This linear continuity can be per lattice or per meter according to the option “Linear phase advance per meter” of the “Main” page. This option is very useful, if you have lattice length discontinuity in order to keep continuity in the phase advance law per meter. TraceWin calculates the quadrupole gradients to obtain the asked zerocurrent phase advance law, using the lattice transfer matrix.
Warning: it is not always possible to find the required quadrupole gradients.
MATCH_FAM_GRAD fn, n, 1/0
MATCH_FAM_FIELD fn, n
MATCH_FAM_PHASE fn, n
MATCH_FAM_LFOC fn, n
MATCH_FAM_LENGTH fn, n
fn is the family or section number and n is the matching element number. When one of these commands precedes an element, it is used (modified) to match the section fn. For example, if two independent cavities are needed to match the beam at the entrance of a section two commands “MATCH_FAM_FIELD” or “MATCH_FAM_PHASE” or “MATCH_FAM_LFOC”, with different matching element numbers n, have to be placed before these cavity entries. But if these two cavities must have the same field, they must have the same matching element number n. If you need for the matching five different quadrupoles and 2 different cavities, then the last command “MATCH_FAM…” must have n = 7. All combinations are possible. You can use the number of quadrupole, the number of cavity and the number of quadrupole or cavity coupled, you want. The coupled elements are not necessarily consecutive. Two examples are presented below. These commands can also be used to match the beam at the entrance of the linac. The only constraint about the family numbers fn is to have a different number per matching family, you can use for example 5,4,8,1...If you set n=0 in each comment of a matching, TraceWin sets automatically a different number for each command, but no coupling is possible between elements.
New (10/09/2012): The third parameter, (0/1), of the command "MATCH_FAM_GRAD" is used for "DTL_CEL" elements to make a difference between the first half quadrupole (0 by default) and second one (1).
MATCH_FAM_GRAD: the quadrupole gradient is adjusted.
MATCH_FAM_FIELD: the field is adjusted.
MATCH_FAM_PHASE: the synchronous phase is adjusted.
MATCH_FAM_LFOC: the longitudinal focalization is adjusted by moving the field and the synchronous phase and the energy gain is kept.
MATCH_FAM_LENGTH: the element length is adjusted.
TraceWin is able to match the beam at the entrance of the linac or between the different sections. In these two cases the criterion for a good matching is either keep the longitudinal and transverse phase advances as smooth as possible or have at the input and the output lattice the same Twiss parameters (taking into account the acceleration parameters.
TraceWin is also able to impose Twiss parameters at a position in the linac. In this case you have to insert a SET_TWISS command behind the matching commands.
These three processes are named “Optimization”, and can be stop by using the menu “Stop”.
To make the optimization of the beam at the entrance of the linac or between the different sections, TraceWin calculates the phase advance on N lattices, using the option “Nbr of phase advance period to smooth” of “Matching” page “. The choice of the criterion (Twiss parameter or smooth phase advances) depends of this option. If the number of lattice is too small (below 6) or if the number of lattice to optimize is set to 0, the Twiss criterion is used. You can watch the optimization process by plotting the phase advance chart, “Beam” and starting the “Synch.” option in the chart. The results of the optimizations can be found in the Results file . The optimization automatically stops when the criterion reaches “Max. Number of iteration” defined in the “Matching” page, but it can be stopped before in the menu “Stop/Optimize”. During a matching some other criterions can be included in order to control the beam size, the beam separation, the beam transverse position or the beam emittance growth...(See matching commands) In this case all the different criterions are added.
Phase advance criterion:_{ } With _{}
With M=2 for DC beam (x,y) or M=3 for bunched beam (x,y,z), and N is the number of lattice to optimize. σt,φ is in °/m.
See also the phase advance definition and setting
If the option “Matching with family & Twiss commands” of page “Matching” is checked, TraceWin changes some quads and cavities strength or element lengths pointed by “MATCH_FAM…” commands, in order to match the beam between two sections. The syntax is not always very easy to use because it has been defined in order to be able to represent most of the cases. Some examples are shown below to help you and if you meet some difficulties yet, send an Email with your data file attached to the authors.
Matching line calculation between a RFQ and a 352 MHz DTL. Two 704MHz buncher cavities and 4 quadrupoles are used in order to match the beam to the structure. A command SET_SIZE_MAX has been include in order to try to reduce the beam size. To help the matching optimization two drift lengths are adjusted by using the command “MATCH_FAM_LENGTH”.
; ***** RFQDTL Matching line ******
DRIFT 1e05 10
FREQ 704
SET_SIZE_MAX 0.025 25 4.5 4.5 25 1
DRIFT 20 10
MATCH_FAM_GRAD 1 0
QUAD 56 55.9938 10
MATCH_FAM_LENGTH 1 0
DRIFT 58.85 10
MATCH_FAM_FIELD 1 0
GAP 251000 90 10 0 0 0 0 0 0 0
DRIFT 58.85 10
MATCH_FAM_GRAD 1 0
QUAD 56 56.1374 10
MATCH_FAM_LENGTH 1 0
DRIFT 50.0 10
MATCH_FAM_GRAD 1 0
QUAD 56 62.7152 10
DRIFT 58.85 10
MATCH_FAM_FIELD 1 0
GAP 282000 90 10 0 0 0 0 0 0 0
DRIFT 58.85 10
MATCH_FAM_GRAD 1 0
QUAD 56 56.5712 10
DRIFT 70 10
FREQ 352
QUAD 28 71.3977 10
; ***************** DTL *****************
LATTICE 2 1
SET_ADV 46
DTL_CEL 87.5277 28 28 0.00548673 71.3977 71.6524 74699.4 50 10 0 0.102751 0.723252 0.475485 0.194532
DTL_CEL 87.9518 28 28 0.0080072 71.6524 71.9632 76721.8 49.5 10 0 0.103248 0.726628 0.470582 0.195991
DTL_CEL 88.3919 28 28 0.0112292 71.9632 72.2903 79282.7 49 10 0 0.103764 0.734598 0.458632 0.197949
DTL_CEL 88.8487 28 28 0.0144758 72.2903 72.5931 81864.3 48.5 10 0 0.104299 0.742159 0.447189 0.99371
DTL_CEL 89.3222 28 28 0.0177645 72.5931 72.9101 84484.9 48 10 0 0.104853 0.74948 0.436027 0.200384
DTL_CEL 89.8133 28 28 0.0212224 72.9101 73.1977 87251.7 47.5 10 0 0.105428 0.757488 0.423767 0.201319
DTL_CEL 90.3217 28 28 0.0245936 73.1977 73.4992 89953.5 47 10 0 0.106024 0.764331 0.413161 0.201532
…
..
.
The calculation result is the following:
The first line result contains the 4 quadrupole gradients in T/m, the second is the cavity field corrections and the last the drift lengths in mm.
Matching_Between_Section_0_to_1
56.3399 56.1173 62.8806 56.4843
0.934963 0.991466
0.00834559 0.000887792 0.0294733 0.0874924
Matching line calculation between a two super conducting cavity families by adjusting the synchronous phases of the last cavities of the first family and the first cavities of the second family. Four quadrupoles are also adjusted in order to match the beam.
..…
DRIFT 325 100
QUAD 400 10 100
DRIFT 400 100
QUAD 400 10 100
DRIFT 950 100
NCELLS 1 5 0.6579000 1.11349e+07 12.331 100 0 0.1801715 0.2934260 10.0848222 14.7245834 …
DRIFT 475 100
NCELLS 1 5 0.6579000 1.11616e+07 10.584 100 0 0.1801715 0.2934260 10.1057623 14.7737516 …
DRIFT 475 100
NCELLS 1 5 0.6579000 1.11873e+07 8.890 100 0 0.1801715 0.2934260 10.1259198 14.8211363 …
DRIFT 625 100
SET_ADV 70
DRIFT 325 100
MATCH_FAM_GRAD 8 1
QUAD 400 10 100
DRIFT 400 100
MATCH_FAM_GRAD 8 2
QUAD 400 10 100
DRIFT 950 100
MATCH_FAM_PHASE 8 3
NCELLS 1 5 0.6579000 1.12121e+07 7.248 100 0 0.1801715 0.2934260 10.1453288 14.8668118 …
DRIFT 475 100
MATCH_FAM_PHASE 8 3
NCELLS 1 5 0.6579000 1.12361e+07 5.657 100 0 0.1801715 0.2934260 10.1640222 14.9108503 …
DRIFT 475 100
MATCH_FAM_PHASE 8 3
NCELLS 1 5 0.6579000 1.12593e+07 4.114 100 0 0.1801715 0.2934260 10.1820316 14.9533216 …
DRIFT 625 100
LATTICE_END
DRIFT 1187.35 100
; Second superconducting family
LATTICE 13 1
SET_ADV 85
DRIFT 325 100
MATCH_FAM_GRAD 8 4
QUAD 500 10 100
DRIFT 400 100
MATCH_FAM_GRAD 8 5
QUAD 500 10 100
DRIFT 975 100
MATCH_FAM_PHASE 8 6
NCELLS 1 5 0.8458000 1.14453e+07 94.435 100 0 0.1560511 0.2270898 10.0611253 13.2916014 …
DRIFT 525 100
MATCH_FAM_PHASE 8 6
NCELLS 1 5 0.8458000 1.14816e+07 92.773 100 0 0.1560511 0.2270898 10.0883587 13.3415267 …
DRIFT 525 100
MATCH_FAM_PHASE 8 6
NCELLS 1 5 0.8458000 1.15177e+07 91.116 100 0 0.1560511 0.2270898 10.1153599 13.3910179 …
DRIFT 525 100
MATCH_FAM_PHASE 8 6
NCELLS 1 5 0.8458000 1.15536e+07 89.464 100 0 0.1560511 0.2270898 10.1421056 13.4400346 …
DRIFT 650 100
DRIFT 325 100
QUAD 500 10 100
DRIFT 400 100
QUAD 500 10 100
DRIFT 975 100
…
TraceWin sets Twiss parameter to the entrance of a RFQ. To impose Twiss parameter in your structure by adjusting elements you have to use the same “MATCH_FAM…” commands, but a SET_TWISS command has been put in front of the element where you want to impose Twiss parameters at its output. The first parameter of SET_TWISS and “MATCH_FAM…” commands is the family or the section number.
..
…
DRIFT 50.1 100
MATCH_FAM_FIELD 1 0
GAP 154335 90 100 0 0
DRIFT 50.1 100
MATCH_FAM_LENGTH 1 0
DRIFT 60 100
MATCH_FAM_GRAD 1 0
QUAD 60 16.9089 100
MATCH_FAM_LENGTH 1 0
DRIFT 40 100
DRIFT 20 100
MATCH_FAM_GRAD 1 0
QUAD 60 16.9089 100
DRIFT 50.1 100
MATCH_FAM_FIELD 1 0
GAP 154335 90 100 0 0
DRIFT 50.1 100
DRIFT 20 100
MATCH_FAM_GRAD 1 0
QUAD 60 16.9089 100
MATCH_FAM_LENGTH 1 0
DRIFT 40 100
DRIFT 20 100
APERTURE 2.7 2.9 1
FREQ 352.21
DRIFT 0.00001 10
RFQ_CELL 120000 4.96362 0 1 109.954 60 3
RFQ_CELL 120000 4.96362 0.114946 1.13305 27.4884 60 4
SET_TWISS 1 1.5440 0.2462 0.7924 0.1898 0.0754 0.9523 0 0 0 0 0 0
RFQ_CELL 120000 4.96362 0.114946 1.13305 27.4884 60 2
RFQ_CELL 120000 4.96362 0.115356 1.13354 27.5261 60 2
RFQ_CELL 120000 4.96362 0.115799 1.13406 27.567 59.9802 2
RFQ_CELL 120000 4.96362 0.116304 1.13465 27.611 59.9208 2
RFQ_CELL 120000 4.96362 0.116874 1.13532 27.6552 59.822 2
RFQ_CELL 120000 4.96362 0.117509 1.13609 27.6995 59.6843 2
RFQ_CELL 120000 4.96362 0.118213 1.13692 27.7441 59.5081 2
RFQ_CELL 120000 4.96362 0.118987 1.13786 27.789 59.2943 2
RFQ_CELL 120000 4.96362 0.119833 1.13888 27.8343 59.0435 2
RFQ_CELL 120000 4.96362 0.120755 1.13999 27.8799 58.7569 –2
…
..
.
4 quadrupoles and 2 cavities are used to match the beam between section 1 and 2. The longitudinal matching is done by a cavity field modification. This is the simplest case.
LATTICE 7 1 «section 1»
DRIFT 100 100
MATCH_FAM_GRAD 1 1
QUAD 150 10 100 «first quadrupole used for matching »
DRIFT 178.56 100
MATCH_FAM_GRAD 1 2
QUAD 150 10 100 «second quadrupole used for matching»
DRIFT 488.64 100
MATCH_FAM_FIELD 1 3
GAP 2.94577e+06 30.5122 100 «first cavity used for matching, the field is adjusted»
DRIFT 722.08 100
LATTICE 9 1 «section 2»
DRIFT 150 100
MATCH_FAM_GRAD 1 4
QUAD 350 10 100 «third quadrupole used for matching»
DRIFT 100 100
MATCH_FAM_GRAD 1 5
QUAD 350 10 100 «fourth quadrupole used for matching»
DRIFT 935.126 100
MATCH_FAM_FIELD 1 6
GAP 3.04084e+06 30.5122 100 «second cavity used for matching, the field is adjusted»
DRIFT 1385.81 100
GAP 3.07847e+06 30.5122 100
DRIFT 729.063 100
4 quadrupoles and 4 cavities are used for the matching between section 1 and 2. The longitudinal matching is done by a cavity phase adjustment. Here, the cavities are coupled 2 by 2.
LATTICE 8 1 «section 1»
…
DRIFT 100 100
MATCH_FAM_GRAD 1 1
QUAD 150 10 100 «first quadrupole used for matching »
DRIFT 178.56 100
MATCH_FAM_GRAD 1 2
QUAD 150 10 100 «second quadrupole used for matching»
DRIFT 488.64 100
MATCH_FAM_PHASE 1 3
GAP 2.94577e+06 30.5122 100 «first cavity used for matching, the phase is adjusted. n=3 ».
MATCH_FAM_PHASE 1 3
GAP 2.94577e+06 30.5122 100 «second cavity used for matching. It will conserve the same phase as the first cavity. n=3 »
DRIFT 722.08 100
LATTICE 10 1 «section 2»
DRIFT 150 100
MATCH_FAM_GRAD 1 4
QUAD 350 10 100 «third quadrupole used for matching»
DRIFT 100 100
MATCH_FAM_GRAD 1 5
QUAD 350 10 100 «fourth quadrupole used for matching»
DRIFT 935.126 100
MATCH_FAM_PHASE 1 6
GAP 3.04084e+06 30.5122 100 «third cavity used for matching, the phase is adjusted. n=6 ».
DRIFT 1385.81 100
MATCH_FAM_PHASE 1 6
GAP 3.04084e+06 30.5122 100 «fourth cavity used for matching, It will conserve the same phase as the third cavity. n=6 »
DRIFT 729.063 100
SET_TWISS fn, αx, βx(mm/mrad), αy, βy(mm/mrad), αz, βz(mm/mrad),kax,kbx,kay,kby,kaz,kbz
The forces of elements pointed with the matching commands "MATCH_FAM_XXX" are adjusted to impose the Twiss parameters given by the "SET_TWISS" command at the output element following the command. More than one command “SET_TWISS” can be used in the same optimization. In this case, use the same f_{n} parameter.
Twiss criterion: _{}
With _{}
fn is the section or family number.
βj, γj, αj being the beam Twiss parameters of the space phase xx’, yy’, zz’.
The 6 following parameters “k” are optional, set one to “1” allows to not taking account of the corresponding Twiss parameters
Write “SET_TWISS fn” corresponds to write “SET_TWISS fn 0 0 0 0 0 0 1 1 1 1 1 1”. That disables the SET_TWISS.
SET_POSITION k(m^{1}), x(mm), x’(mrad), y(mm), y’(mrad)
x, x’, y, y’ are the centroid beam positions imposed at the point where this command appears, k is used in the criterion calculation.
Set position criterion: _{}
With x(mm), x’(mrad), y(mm), y’(mrad) being the beam centroid transverse positions at the place where the command “SET_POSITION” appears and xo (mm), xo’(mrad), yo (mm), yo’(mrad) being the beam imposed positions.
SET_ACHROMAT k f1 f2 plane
Located after a deviation for instance this command allows to make achromatic the preceding line. k is used to balance the criterion calculation
(f1=1 means set achromatic position).
(f2=1 means set achromatic angle).
If (plane=0) : X or Y or both planes acccoding to bend direction are concerned (default)
If (plane=1) : only X plan is concerned
If (plane=2) : only Y plan is concerned
If (plane=3) : both planes are concerned
Example:
DRIFT 300 100
START_ACHROMAT
EDGE 22.5 500 100 0.45 2.8 50 0
BEND 45 500 0 50 0
EDGE 22.5 500 100 0.45 2.8 50 0
DRIFT 200 100
MATCH_FAM_GRAD 4
QUAD 200 2
DRIFT 200 100
EDGE 22.5 500 100 0.45 2.8 50 0
BEND 45 500 0 50 0
EDGE 22.5 500 100 0.45 2.8 50 0
DRIFT 107 100
SET_ACHROMAT 1.0 1 1
DRIFT 100 100
DRIFT 100 100
END
SET_SIZE_MAX k, N, x(mm), y(mm), θ(°)/z(mm), k2 (0/1)
SET_SIZE_MIN k, N, x(mm), y(mm), θ(°)/z(mm), k2 (0/1)
x, y, θ are the imposed beam size max in the N elements following this command, N, k and k2 is used in the criterion calculation.
When x > x_{0} set size max criterion: _{ }
When x < x_{0} set size min criterion: _{ }
otherwize vcr = 0
With x(mm), y(mm), θ(°) being the beam maximum sizes in the N elements following the command “SET_SIZE_MAX / MIN”, and xo(mm), yo(mm), θo(°) being the beam imposed sizes. If θ is lower than 0 the longitudinal size used is z(mm). If one of these last parameters is set to 0, no optimization is done on this size and M is reduced by one. If k2=0, the transverses sizes are is calculated without taking account the beam centroid position. If one of the parameters x, y or θ is equal to 0, no optimization is done on this size and M is reduced by one.
The sizes are the effective beam sizes (rms. for bunched beam or rms. for CW beam)
SET_SIZE k, x(mm), y(mm), φ(°)/z(mm), k2 (0/1)
x, y, φ are the imposed beam size in the output element following this command, N, k is used in the criterion calculation. If k2=0, the transverses sizes are calculated without taking account the beam centroid position.
Set size criterion: _{}
With x(mm), y(mm), φ(°) being the beam sizes in the output elements following the command “SET_SIZE”, and xo(mm), yo(mm), ), φ_{0}(°) being the beam imposed sizes. If φ is lower than 0 the longitudinal size used is z(mm). If one of these last parameters is equal to 0, no optimization is done on this size and M is reduced by one.
The sizes are the effective beam sizes (rms*sqrt(5) for bunched beam or rms*sqrt(4) for CW beam)
SET_SEPARATION k, Sx, Sy
Sx_{0}, Sy_{0} are the centroid beam positions divided by the imposed beam size max at the point where this command appears, k is used in the criterion calculation.
Set separation criterion:_{ }
MIN_EMIT_GROW k, N, ex, ey, ez, f
k and N are used in the criterion calculation.
ex, ey, ez and f are optional: if ex equal to 1 the criterion doesn’t take into account εx beam emittance. That is the same way for ey and ez. f parameter define if the criterion calculation is relative or not (see formula below).
The emittance growth criterion:
§ If (f=1) _{}
_{§ }If (f=0) _{} at the command position
With εxo, εyo, εzo being the beam emittances where this command appears, and εx, εy, εz being the beam emittances after N elements.
STEERER Bx(T) By_{ }(T) Bmax 0 coef_{1}(m) coef_{2}(m)
STEERER Ex(V/m) Ey_{ }(V/m) Emax(V/m) 1
Its a command not a element (Corresponding element: THIN_STERRING). The magnetic steerer is inserted in the element (magnetic or electric quadrupole, solenoid and field map) placed just after the instruction “Steerer” (keeping the same length). parameters coef_{1} and coef_{2} allow to introduce nonlinear forces.
_{} And _{}
_{} And _{}
Where x’ and y’ being respectively the horizontal and vertical beam centroid slope.
Used in diagnostic optimization (with ADJUST_STERRER), Bmax and Emax is the maximum limit for Bx, By and Ex, Ey, if it’s greater than zero.
FIELD_MAP case: in field map, kick angle is applied on the full field map length.
The both parameters coef_{1} and coef_{2} allow to introduce nonlinear forces in the steerer deviation.
coef_{1} and coef_{2 }units are meter.
 If coef_{1} is not equal to 0 (SPIRAL2 type steerer):
_{ }
_{}
_{ }
_{ }
 If coef_{2} is not equal to 0 (ESS type steerer):
_{ }
_{ }
With: _{}see TraceWin gradient definition.
_{ }
_{ }
_{ }
_{ }
_{ }
CHOPPER N, U(V), D(mm), C(mm), p(0/1)
The chopper is inserted in the N elements placed just after the instruction “Chopper” (keeping the same length). U is the voltage between axis and plates and C is the chopper transverse position. ±D is the distance between axis and plates
If (p=0) _{ } and if (p=1) _{}
_{ }
Where x’ and y’ are respectively the horizontal and vertical beam centroid slope.
ERROR_GAUSSIAN_CUT_OFF cutoff
When the error distribution is defined to Gaussian, this command allow to set a cutoff value.
A new command change this value the following elements concerned by ERROR_XXX commands.
ERROR_BEAM_STAT r(0/1/2), dx(mm), dy(mm), dφ(°), dxp(mrad), dyp(mrad), de(MeV),dEx(%), dEy(%), dEz(%), mx(%), my(%), mz(%), dib(mA), αxx’_min, αxx’_max, βxx’_min(mm/mrad), βxx’_max(mm/mrad), αyy’_min, αyy’_max, βyy’_min(mm/mrad), βyy’_max(mm/mrad), αzdp_min, αzdp_max, βzdp_min(mm/mrad), βzdp_max(mm/mrad)
ERROR_BEAM_DYN
Five kind of error can be set:
Beam displacement: (dx, dy, dr, dxp, dyp, de) The beam input position is not centered.
Emittance growth: (dEx, dEy, dEz) The input beam emittance is increased by a percentage. For CW beam dEz error is applied on the energy spread.
Beam mismatch: (mx, my, mz) The input beam is mismatched by a percentage. A 20 % mismatch in x plane means αx and βx are multiplied by 1.2².
Beam Current error: (dib) Allows to study the effect of the input beam current variation (Ibeam=Ibeam0+dib).
Twiss parameter range: (α_min, α_max, β_min, β_max) The input beam is randomly select in the twiss parameter ranges. The 4 parameters, α_min, α_max, β_min, β_max, must be different of 0 and mismatch parameter m must be equal to 0.
If (r = 0), α_beam = α_min+( α_max α_min)*k
(k varing from 0 to 1 according to the “Nbr o f step” parameter. If “Nbr_step=4”, k={0, 0.25 ,0.50 ,0.75 ,1)
This command concerns only the input beam. The error distribution depends on the r parameter:
· r = 0, the errors are constant and equal to each value of the command line.
· r = 1, the errors are uniformly distributed (+/); each value of the command line is the maximum range error.
· r = 2, the errors are Gaussian distribute; each value of the command line is rms value of the distribution.
A Gaussian cutoff can set using SET_GAUSSIAN_CUT_OFF
See also ERROR_STAT_FILE & ERROR_DYN_FILE.
ERROR_QUAD_NCPL_STAT N r(0/1/2/4/5), dx(mm), dy(mm), φx(°), φy(°), φz(°), dG(%), dz(mm) , dG3(%), dG4(%), dG5(%), dG6(%), Nb
ERROR_QUAD_NCPL_DYN
ERROR_QUAD_CPL_STAT
ERROR_QUAD_CPL_DYN
ERROR_QUAD_NCPL_STAT_FILE file
See also ERROR_STAT_FILE & ERROR_DYN_FILE.
New since version 2.16.1.2:
If ERROR_CAV_CPL_XXX and ERROT_QUAD_CPL_XXX commands are located at the same position with the same N parameters then error displacements and rotations applied on cavities and magnet elements will be the same. In this case, error amplitudes are by default defined by ERROR_CAV_CPL_XX.
New since version 2.16.1.0:
Nb parameter allows to limit the number of elements where error are applied, selecting them randomly. For example if you want to move only one quadrupole randomly chosen, this command will do it: ERROR_QUAD_NCPL_STAT 20000 0 0.1 0 0 0 0 0 0 0 0 0 0 0 1
Nb is possible only for _NCPL_ error types.
The N parameter defines the number of elements following the ERROR command that will be affected by these errors. If in this sequence of elements a new command is present, it cancels the previous command from its position to redefine the errors for the next N elements and so one.
dx and dy being respectively the horizontal and vertical magnetic element displacement. dz being the longitudinal shift. φx ,φy, φz being respectively the quadrupole rotation around x, y, zaxis and dG being the gradient amplitude error. dG3, dG4, dG5, dG6 correspond respectively to the sextupole, octupole, decapole, dodecapole gradient errors and concern only QUAD and QUAD_ELE elements. These errors are applied in the N elements following this command, excepted, if a new error command appears. The error distribution depends on the r parameter:
· r = 0, the errors are constant and equal to each value of the command line.
· r = 1, the errors are uniformly distributed (+/); each value of the command line is the maximum range error.
· r = 2, the errors are Gaussian distribute; each value of the command line is rms value of the distribution.
· r = 4, the errors randomly distributed between 2 values, +MaxErr or MaxErr. MaxErr is the error amplitude set in the command line.
· r = 5, the errors randomly distributed between 2 values, 0 or MaxErr. MaxErr is the error amplitude set in the command line.
A Gaussian cutoff can set using SET_GAUSSIAN_CUT_OFF
Remark about dG3, dG4, dG5, dG6 errors: These errors are only applied on QUAD and QUAD_ELE elements. When the multipole gradients in the QUAD element are set to zero, then the respective gradient errors are introduced in terms of quadrupole main field B2, e.g. _{}, _{}, etc.. With B2 as magnetic field on pole.
The fifth command uses a file to set errors. This file is located by default in structure file (*.dat) path. It contains lines like the following syntax (be careful to Z unit):
Z_{0}(m) r(0/1/2) dx(mm) dy(mm) φx(°) φy(°) φz(°) dG(%) dz(mm), dG3(%) dG4(%) dG5(%) dG6(%)
Z_{1}(m) r(0/1/2) dx(mm) dy(mm) φx(°) φy(°) φz(°) dG(%) dz(mm), dG3(%) dG4(%) dG5(%) dG6(%)
…
Z_{n}(m) r(0/1/2) dx(mm) dy(mm) φx(°) φy(°) φz(°) dG(%) dz(mm) dG3(%) dG4(%) dG5(%) dG6(%)
An interpolation is performed to define errors applied to an element at a given position. It’s not the case for ‘r’ parameter which is defined without interpolation.
A new command “ERROR_QUAD_NCPL_STAT_FILE” without file, put in the *.dat file, stop the action of the preceding similar command.
Be careful: Errors defined by ERROR_QUAD_NCPL_STAT_FILE are added to errors coming from ERROR_QUAD_NCPL_STAT commands.
This error set affects:
 Quadrupole
 Solenoid
 Quadrupole of DTL
 Field map if defined as static magnetic field
PHASE_ERROR_TO_SYNC_PHASE flag
Set to 1 this command allows to apply phase errors directlly to synchronous phase of the cavity instraed to RF phase which is the default case. Set to 0 cancels this feature for all cavities localized after this command.
This command makes errors are canceled and a new synchronous phase setting of the linac are generated.
Phase error amplitudes are defined by ERROR_CAV_NCPL_STAT command, but in this case, errors are transformed in new synchronous phase setting of the linac.
ERROR_CAV_NCPL_STAT N r(0 /±1/2/±3/4/5), dx(mm), dy(mm), φx(°), φy(°), E(%), φ(°), dz(mm), Nb
ERROR_CAV_NCPL_DYN
ERROR_CAV_CPL_STAT
ERROR_CAV_CPL_DYN
ERROR_CAV_NCPL_STAT_FILE file
See also ERROR_STAT_FILE & ERROR_DYN_FILE.
New since version 2.16.1.2:
If ERROR_CAV_CPL_XXX and ERROT_QUAD_CPL_XXX commands are located at the same position with the same N parameters then error displacements and rotations applied on cavities and magnet elements will be the same. In this case, error amplitudes are by default defined by ERROR_CAV_CPL_XX.
New since version 2.16.1.0:
Nb parameter allows to limit the number of elements where error are applied, selecting them randomly. For example if you want to cut off RF field of a cavity randomly chosen, this command will do it: ERROR_CAV_NCPL_STAT 20000 0 0 0 0 0 100 0 0 1
Nb is possible only for _NCPL_ error types.
The N parameter defines the number of elements following the ERROR command that will be affected by these errors. If in this sequence of elements a new command is present, it cancels the previous command from its position to redefine the errors for the next N elements and so one.
dx and dy being respectively the horizontal and vertical electric element displacement. dz being the longitudinal shift, φx, φy _{ }being respectively the cavity rotation around x, yaxis. E being the field amplitude error. φ being the field phase error. These errors are applied in the N elements following this command, excepted, if a new error command appears. The error distribution depends on the r parameter:
· r = 0, the errors are constant and equal to each value of the command line.
· r = 1, the errors are uniformly distributed (±); each value of the command line is the maximum range error.
· r = 1, the errors are Gaussian distribute; each value of the command line is rms value of the distribution.
· r = 4, the errors randomly distributed between 2 values, +MaxErr or MaxErr. MaxErr is error amplitude set in the command line.
· r = 5, the errors randomly distributed between 2 values, 0 or MaxErr. MaxErr is the error amplitude set in the command line.
A Gaussian cutoff can set using SET_GAUSSIAN_CUT_OFF
Specail feature for r=2 or r=±3
According to r parameter:
· r = 2, the errors are constant and equal to each value of the command line.
· r = 3, the errors are uniformly distributed (+/); each value of the command line is the maximum range error.
· r = 3, the errors are Gaussian distribute; each value of the command line is rms value of the distribution.
And the command syntax becomes:
ERROR_CAV_XXX_XXX N r(2/±3), dx(mm), dy(mm), φx(°), φy(°), E(%), kφ(deg/%), dz(mm)
The phase error applied on the cavities is φ_{err}= kφ*E_{rr}
In case of coupled error (_CPL_) the field phase and the field amplitude error sign are reversed each new cavity.
The fifth command uses a file to set errors. This file is located by default in structure file (*.dat) path. It contains lines like the following syntax (be careful to Z unit):
Be careful: Errors defined by ERROR_CAV_NCPL_STAT_FILE are added to errors coming from ERROR_CAV_NCPL_STAT commands.
Z_{0}(m) r(0/±1/2/±3) dx(mm) dy(mm) φx(°) φy(°) E(%) φ(°) dz(mm)
Z_{1}(m) r(0/±1/2/±3) dx(mm) dy(mm) φx(°) φy(°) E(%) φ(°) dz(mm)
…
Z_{n}(m) r(0/±1/2/±3) dx(mm) dy(mm) φx(°) φy(°) E(%) φ(°) dz(mm)
An interpolation is performed to define errors applied to an element at a given position. It’s not the case for ‘r’ parameter which is defined without interpolation.
A new command “ERROR_CAV_NCPL_STAT_FILE” without file, put in the *.dat file, stop the action of the preceding similar command.
By default phase errors are applied to RF phase of concerned cavities. The specific command PHASE_ERROR_TO_SYNC_PHASE allows to applied error directly to synchronous phase, but in this case errors are transformed in new synchronous phase setting of the linac.
This error set affects:
 Bunched cavity
 Cavity multigap
 DTL (Warning the DTL are only concerns by the field errors)
 Sinus cavity
 Field map if not defined as static magnetic field
ERROR_BEND_NCPL_STAT N, r(0/1/2/4/5), dx(mm), dy(mm), φx(°), φy(°), φz(°), dg(%), dz(mm)
ERROR_BEND_NCPL_DYN
ERROR_BEND_CPL_STAT
ERROR_BEND_CPL_DYN
See also ERROR_STAT_FILE & ERROR_DYN_FILE.
The N parameter defines the number of elements following the ERROR command that will be affected by these errors. If in this sequence of elements a new command is present, it cancels the previous command from its position to redefine the errors for the next N elements and so one.
dx and dy being respectively the horizontal and vertical magnetic element displacement. dz being the longitudinal shift. φx ,φy, φz being respectively the bend rotation around x, y, zaxis and dg being the magnetic field amplitude error. These errors are applied in the N elements following this command, excepted, if a new error command appears. The error distribution depends on the r parameter:
· r = 0, the errors are constant and equal to each value of the command line.
· r = 1, the errors are uniformly distributed (±); each value of the command line is the maximum range error.
· r = 2, the errors are Gaussian distribute; each value of the command line is rms value of the distribution.
· r = 4, the errors randomly distributed between 2 possible values, +MaxErr or MaxErr. MaxErr is error amplitude set in the command line.
· r = 5, the errors randomly distributed between 2 values, 0 or MaxErr. MaxErr is the error amplitude set in the command line.
A Gaussian cutoff can set using SET_GAUSSIAN_CUT_OFF
This error set affects only magnet bend and edge
Valid only if the BEND element is not cut in several parts.
Warning, the “ERROR_BEND_CPL_X” commands concern only the magnetic field amplitude errors, all other errors (shift, rotation,…) are not couple.
See detail about bend error treatment.
ADJUST N, v, n, min, max, start_step, kn
Red parameters are optional.
This command has to be associated with a Diagnostic elements number N. v, an integer, is the vth variable to be adjust in the next element list of variable. As an exemple if v=2 and the next element is a quad then the gradient will be adjusted. n (if it’s different from zero) allows to link ADJUST commands each other, therefore, two ADJUST commands with the same n will give the same value to the v variable point. v lower than zero allows to replace both command “ADJUST_DPHASE” and “ADJUST_DFIELD” when v points to phase or field variable.
New in version 2.2.0.16 : The strat_step parameter has been added to select the start step of the fit during optimisation. In other words, the first iteration will be v ± start_step, knowing that the search step may accelerate or decelerate during the optimisation process.
New in version 2.2.1.9: The n parameter allows you to link two variables: If you set the n parameter to the opposite sign, you will get an opposite variation for the linked variables if their initial values are equal. For example, two drifts coupled with (n=1 & n=1) will keep the same total length. If the initial values are different then they will simply have the same opposite sign value.
New in version 2.20.1.0: The new parameter kn when it is different from 0, allows during a linkage between 2 variables to apply in addition a corrective coefficient, kn. For example, the length of a second drift can be set to half the length of a first drift, which is adjusted.
5 consecutives ADJUST command can be set.
(See Adjust and diagnostic examples)
ADJUST_STEERER N, max, first_step
ADJUST_STEERER_BX N, max, first_step
ADJUST_STEERER_BY N, max, first_step
These commands have to be associated with Diagnostic elements number N and should be placed before a STEERER command. It allows to adjust the horizontal and/or vertical magnetic field steering.
Particular case of steerer adjustment: When the number of steerers corresponds to the number of BMP, no optimization is performed and the resolution of the system is directly made by a matrix inversion
New in version 2.2.0.20: Input beam parameters can be adjusted in order to fit with a set of diagnostic values at different positions of a line
(Example adjusted beam emittances and Twiss parameters at the input of a simulated line in order to obtain the beam sizes measured at different positions with real beam)
ADJUST_BEAM_TWISS N, AlpX_flag, betX_flag, AlpY_flag, BetY_flag, AlpZ_flag, betZ_flag
If flag is set to 1 the selected Twiss parameter will be adjusted, if you want to have alpX=AlpY set alpX_flag=1 and alpY_flag=2, same way for Bet_flag)
ADJUST_BEAM_EMIT N, Ex_flag, Ey_flag, Ez_flag
If flag is set to 1 the selected emittance will be adjusted, if you want to have Ex=Ey set Ex_flag=1 and Ey_flag=2)
ADJUST_BEAM_CENTROID N, X_flag, Xp_flag, Y_flag, Yp_flag, Z_flag, Zp_flag
If flag is set to 1 the selected beam centroid parameter will be adjusted, if you want to have X=Y set X_flag=1 and Y_flag=2, same way for Xp_flag)
ADJUST_BEAM_CURRENT N, I_flag
All “ADJUST_BEAM_XXX” commands must be located in front of the first element. Some elements can be also adjusted in the same matching process.
Beam alignment from a RFQ to a DTL. Two ADJUST commands are associated with two STEERER and with two Diagnostic elements.
DRIFT 0.00001 6.5
DRIFT 56.0 6.5
ADJUST_STEERER 1 «Adjust the steerer inside the following quadrupole »
STEERER .01 0.01
ERROR_QUAD_NCPL_STAT 1 0 0.1 0.1 0 0 0 0 «Include 0.1mm misalignment and 0.3° rotation errors in the quad »
QUAD 56.0 55.0 6.5
DRIFT 2.15 6.5
DRIFT 58.85 6.5
GAP 180000 90 6.5
DRIFT 58.85 6.5
ADJUST_STEERER 1 «Adjust the steerer inside the following quadrupole »
STEERER .01 0.01
QUAD 56.0 55.0 6.5
DRIFT 82.9 6.5
DIAG_POSITION 1 0 0 « Position monitor with x and y position imposed to 0 »
DRIFT 20 6.5
QUAD 56.0 55.0 6.5
DRIFT 58.85 6.5
GAP 210000 90 6.5
DRIFT 38.85 6.5
QUAD 56.0 55.0 6.5
DRIFT 54.3 6.5
DIAG_POSITION 1 0 0 « Position monitor with x and y position imposed to 0 »
DRIFT 20.0 6.5
…
You can see the result in the result file. This result is not used in a statistical error study where an adjustment is calculated for each random error distribution.
Diagnostic_1
0.0661744 0.0663664 0.0554 0.0458
Triplet adjusting in order to match a beam size
ADJUST 1 2 1 « Quadrupole 1 and 3 are linked, the point variable ‘2’ is the gradient »
QUAD 152 2.14 52
DRIFT 119 52
ADJUST 1 1 0 200 300 « Here, the quadrupole length is adjusted, but the length will keep between (200 & 300) »
QUAD 281 2.13 52
DRIFT 119 52
ADJUST 1 2 1
QUAD 152 2.0 52
DRIFT 3190 100
APERTURE 2 2 0
DIAG_SIZE 1 2 2
DRIFT 3590 100
DIAG_SIZE 1 4 4
DRIFT 100 100
…
Set achromatic line part from element 3 to achromatic diagnostic position
DRIFT 30 100
DRIFT 30 100
DRIFT 30 100
DRIFT 30 100
EDGE 22.5 500 100 0.45 2.8 50 0
BEND 45 500 0 50 0
EDGE 22.5 500 100 0.45 2.8 50 0
DRIFT 200 100
ADJUST 11 2 1
QUAD 100 200 20
DRIFT 200 100
ADJUST 11 2 1
QUAD 100 200 20
DRIFT 200 100
ADJUST 11 2 1
QUAD 100 200 20
DRIFT 200 100
EDGE 22.5 500 100 0.45 2.8 50 0
BEND 45 500 0 50 0
EDGE 22.5 500 100 0.45 2.8 50 0
DRIFT 107 100
DIAG_ACHROMAT 11 3 1 1
DRIFT 100 100
DRIFT 100 100
End
Find the input beam Twiss parameters and emittances given the rms sizes measured at the end of the line.
; Proton @20 MeV, 10 mA
ADJUST_BEAM_CURRENT 99 1
ADJUST_BEAM_EMIT 99 1 2 0 ; Ex=Ey
ADJUST_BEAM_TWISS 99 1 1 1 1 0 0
DRIFT 0 100
DRIFT 100 100
QUAD 100 15.18 20
DRIFT 200 100
QUAD 100 15.18 20
DRIFT 200 100
QUAD 100 15.18 20
DRIFT 200 100
DIAG_SIZE 99 2.2 1.6
DRIFT 200 100
DIAG_SIZE 99 2.2 1.6
DRIFT 0 100
END
ERROR_RFQ_CEL_NCPL_STAT N, r(0/1/2), dR(mm), d (mm), E(%),φ(°), TEpe(mm), TEpa(mm), DEpe(mm), DEpa(mm), DELong(mm) TSVerti(mm), TSHori(mm), DSVerti(mm), DSHori(mm), DSLong(m)
ERROR_RFQ_CEL_NCPL_DYN (not implemented yet)
dR is the error for the longitudinal profile, d is the error for the transverse curvature of the electrode, E is the voltage amplitude error. φ being the field phase error (uneffective).
For the transverse plane, TEpe is the perpendicular tilt error by electrode, TEpa is the parallel tilt error by electrode, DEpe is the perpendicular displacement error by electrode, DEpa is the parallel displacement error by electrode, DELong is the a longitudinal displacement error by electrode.
For each segment (block of four electrodes defined with the RFQ_GAP command), TSVerti is the vertical tilt error, TSHori is the horizontal tilt error, DSVerti is the vertical displacement error, DSHori is the horizontal displacement error and DSLong is the longitudinal displacement error.
These errors are applied in the N elements following this command, excepted, if a new error command appears. The error distribution depends on the r parameter:
· r = 0, the errors are constant and equal to each value of the command line (only envelope mode).
· r = 1, the errors are uniformly distributed (±); each value of the command line is the maximum range error.
· r = 2, the errors are Gaussian distribute; each value of the command line is rms value of the distribution.
RFQ is a special element in TraceWin and all these errors are no effect in an envelope calculation except the phase and filed errors.
(*) Images provided by Ibon Bustinduy, ESS Bilbao.
PLOT_DST file_out
PLOT_DST_LOST file_out
If file_out parameter is empty, indicate to the multiparticle code to store beam distribution (in the *.plt file) at the end of the next element, otherwise save the beam distribution in file_out as a dst file (.dst extension has to be omitted).
“PLOT_DST_LOST” command allows to include in the dst file, the lost particles.
GAS C, N, P
Only used in multiparticle simulation, this command set the gas pressure parameter until a new command GAS
C is the cross section at 1 MeV (m²), N is the atomic number and P is the pressure (hPa).
You have to select ‘gas stripping’ or ‘gas scattering” in the ‘Multiparticle’ page.
For gas stripping, the actual cross section used in the simulation is:_{ } , E being the beam energy in MeV (N is useless).
For gas scattering calculations, only N and P are used (C is useless).
Several “gas” commands can be set simultaneously (Max. 9).
MIN_ENV_VARIATION k, N
Minimize the variation of the maximum and minimum transverse beam envelope in magnetic element. For bunched beam, the phasespread variation is also minimizing in the accelerating elements. The parameter k is a weighting factor for the contribution of this constraint to the overall penalty function and N is the number of element positions over which the constraint applies. The first affected position is the one immediately following the command. Only magnetic and accelerating elements falling within the specified range are affected.
MIN_PHASE_VARIATION k, N, Δθ_{max}
During a matching procedure it is often useful to limit the maximum cavity (synchronous) phase amplitude variation. The parameter k is a weighting factor for the contribution of this constraint to the overall penalty function, θ is the max allowed angle variation in degrees and N is the number of element positions over which the constraint applies. The first affected position is the one immediately following the command. Only cavities falling within the specified range are affected.
_{ }
_{}
NCPL: means: No Coupled. The errors are individually applied on each element
CPL: means: Coupled. The errors are coupled on the N elements. In other words, a rotation error corresponds to an N elements block rotation.
STAT: means: Static. The effect of these errors can be detected and corrected with appropriate diagnostic and correctors. For example, beam position measurement coupled with steerers can compensate the quadrupole or cavities misalignments. Correction strategy should be known to be able to estimate their impact on beam dynamics
DYN: means: Dynamic. The effect of these errors cannot be measured and then corrected. Fortunately, they have usually lower amplitude than static errors. They are, for example, the vibrations of the elements or the RF field control errors (in phase or amplitude). The knowledge of the correction scheme is not needed to study their statistic impact. They are responsible of orbit oscillations around the corrected orbit (this notion of orbit is also extended in the longitudinal motion).
RFQ_GEOM type N dz
Put this command just before the first RFQ cell.
According to type parameter:
If type = 0: Toutatis generates vane geometry file with 50steps/cell. It’s the default case.
If type = 1: Toutatis reads vane geometry file
Example: RFQ_GEOM 1 c:\my_project\rfq\My_rfq.vane
If type = 2: and N = 0: Toutatis generates vane geometry file with a cell step = dz
Example: RFQ_GEOM 2 0 0.001 for a 1 mm step
If type = 2: and N ≠ 0: Toutatis generates vane geometry file with N step/cell
Example: RFQ_GEOM 2 20
If type = 3: For statistical error study case: (for X cases)
Example: RFQ_GEOM 3 c:\my_project\rfq\My_rfq.vane
Toutatis, for each case, will kook for a RFQ geometry vane file called:
c:\my_project\rfq\My_rfq000001.vane for first run
c:\my_project\rfq\My_rfq000002.vane for second one
…
..
.
c:\my_project\rfq\My_rfq00000X.vane for last one
FOUR_RODS
This option generates electrode profile with varying transverse curvature. By default the transverse curvature is proportional to Ro (four vane type). Put this command just before the first RFQ cell element.
TWOTERMS
This command allows to generate a longitudinal profile (way to modulate) which is governed by the classical 2 terms potential. In case this option is used, only m and a are taken into account, Ro is recomputed. The sinus modulation is the default in case nothing is specified. Put this command just before the first RFQ cell.
RFQ_GAP Lp(m), Lg(m), Sl(m), St(m)
This command defines in a RFQ structure a resonant coupling gap. The position of the command in the data file doesn't matter, if you respect 2 rules: place it before a RFQ cell element, and if you need more than one coupling gap you must avoid to put the new command before the same RFQ cell element. Lp is the longitudinal position of the center of the gap. Lg is gap width. Sl is the halfellipse size in the beam direction and St is the halfellipse height in the perpendicular beam direction.
RFQ_GAP_RMS_FFS GapRMS (mm), GapFFS (mm)
This command defined in a RFQ structure, before the first RFQ_CELL element, allows to redefine the frontend gap of the first (GapRMS) and the last (GapFFS) RFQ_CELL (type 3). In Toutatis, these gaps are by defaut defined as ¼ of the frontend cell length. Set GapRMS or GapFFS parameter to 0 to use the Toutatis default values.
SET_OF_MAP
Put this command just before a FIELD_MAP element. This command provides a way to do an error study using a list of field maps.
Used only during statistical error study case: (for X linac)
For each linac, the reference field map will be replaced by a new one named like in the following example:
SET_OF_MAP
LMEQ11 : FIELD_MAP 70 480 0 40 9.174 0 0 0 qpole480_lme
qpole480_lme000001 for first run
qpole480_lme000002 for second one
…
..
.
qpole480_lme00000X for last run
ERROR_STAT_FILE static_error_file.txt
ERROR_DYN_FILE dynamic_error_file.txt
Put this command wherever in the structure file (*.dat), whatever the position, allow to replace static or/and dynamic errors defined by usual error commands (ERROR_QUAD_.XX, ERROR_CAV_XX…), by the values set in the file. Both definition systems cannot coexist, defined errors in files will always dominate. The syntax of the file is identical to the ouput file, “Error_Datas.txt”, containing the applied errors, defined here.
Example:
ERROR_STAT_FILE D:/temp/temp5/Error_Datas_static.txt
ERROR_DYN_FILE D:/temp/temp5/Error_Datas_dynamic.txt
For the special case of a statistical error study: (for X linac)
For each linac, the error file will be replaced by a new one named like in the following example:
D:/temp/temp5/Error_Datas_static000001.txt for first run
D:/temp/temp5/Error_Datas_dynamic000001.txt for first run
D:/temp/temp5/Error_Datas_static000002.txt for second run
D:/temp/temp5/Error_Datas_dynamic000002.txt for second run
…
..
D:/temp/temp5/Error_Datas_static00000X.txt for last run
D:/temp/temp5/Error_Datas_dynamic00000X.txt forlast run
ERROR_SET_RATIO
‘Nstep’ parameter in “Error” page allows to apply progressively the errors from 0% to 100% of the error amplitudes defined by “ERROR_XX” commands. For example “Nstep=4” will perform 4 error studies applying 0% 25% 50% 75% 100% of the maximal error amplitudes.
The command “ERROR_SET_RATIO” allows to user to choose the ratio values.
Example: “ERROR_SET_RATIO 0 0.25 0.75 1.5” will apply 0%, 25% 75% and 150% of the error amplitudes.
The particle file from the page “Main” allows to define the input particle file, but if you want to force the envelope or multiparticle calculation to load a new particle file characteristics (Twiss parameters, current, emittances, centroid) at a given position in the linac, you have to include the command below followed by the full name of the particle file.
READ_DST full_particle_file_name
Warning: This command is read at its position and not like other commands at the end of the following element.
If you choose to run multiparticle code (Partran or Toutatis), you can avoid to run a linac part or even all the linac which has been already computed. Then, you have to indicate to TraceWin, which part doesn’t have to be run, by insert at the beginning of this part the command “READ_OUT” followed by the full name of the Partran or Toutatis output file
READ_OUT full_output_multiparticle_file_name
This command is necessary associated with a READ_DST command (See examples below).
Warning: This command is read at its position and not like other commands at the end of the following element.
The following examples are allowed:
(Where calculation directory is: “D:\temp\temp3\”)

LBET + RFQ + MEBT: here to avoid to perform the LEBT already calculated, the LEBT is first of all simulated alone and the 3 following file are copied:
No element before READ_OUT command
No element except, RFQ_CEL, afer READ_DST command
; LEBT
READ_OUT d:\temp\temp3\lebt.out
DRIFT 0 40
DRIFT 10 40
SOLENOID 100 1 40
DRIFT 10 40
SOLENOID 100 1 40
DRIFT 10 40
DRIFT 0 40
READ_DST d:\temp\temp3\lebt.dst
;RFQ
RFQ_CELL 70000 9.94396 0 1 66.9319 90 3 7.5 1 0 0 0 0
RFQ_CELL 70000 9.94396 6.69068e05 1.00028 11.1553 90 4 7.5 1 0 0 0 0
LATTICE 2 1
RFQ_CELL 70000 9.94244 0.000125255 1.00052 11.1553 90 2 7.5 1 0 0 0 0
RFQ_CELL 70000 9.93848 0.000206589 1.00086 11.1553 90 2 7.5 1 0 0 0 0
RFQ_CELL 70000 9.93291 0.000269428 1.00112 11.1553 90 2 7.5 1 0 0 0 0
RFQ_CELL 70000 9.92632 0.000314328 1.0013 11.1553 90 2 7.5 1 0 0 0 0
…
…
RFQ_CELL 70000 8.90751 0.0188169 1.06427 11.1553 88.3866 2 7.5 1 0 0 0 0
RFQ_CELL 70000 8.89561 0.0193 1.0658 11.1553 90.8234 2 7.5 1 0 0 0 0
RFQ_CELL 70000 8.88381 0.0198278 1.06748 11.1553 89.3208 2 7.5 1 0 0 0 0
RFQ_CELL 70000 8.87215 0.0203424 1.06911 11.1553 90.7149 2 7.5 1 0 0 0 0
; MEBT
DRIFT 1 40
QUAD 100 1 40
DRIFT 100 40
QUAD 100 1 40
DRIFT 100 40
DRIFT 0 40
END

LBET + RFQ + MEBT: here to avoid to perform the RFQ already calculated, the RFQ is first of all simulated alone and the 3 following file are copied:
No element after READ_OUT command, except RFQ_CEL
No element before READ_DST command, except, RFQ_CEL
If you have some matching commands in line2, it’s strongly recommended to add at least 5 null drifts just after READ_DST command.
; LEBT
DRIFT 0 40
DRIFT 10 40
SOLENOID 100 1 40
DRIFT 10 40
SOLENOID 100 1 40
DRIFT 10 40
DRIFT 0 40
;RFQ
READ_OUT d:\temp\temp3\lebt.out
RFQ_CELL 70000 9.94396 0 1 66.9319 90 3 7.5 1 0 0 0 0
RFQ_CELL 70000 9.94396 6.69068e05 1.00028 11.1553 90 4 7.5 1 0 0 0 0
LATTICE 2 1
RFQ_CELL 70000 9.94244 0.000125255 1.00052 11.1553 90 2 7.5 1 0 0 0 0
RFQ_CELL 70000 9.93848 0.000206589 1.00086 11.1553 90 2 7.5 1 0 0 0 0
RFQ_CELL 70000 9.93291 0.000269428 1.00112 11.1553 90 2 7.5 1 0 0 0 0
RFQ_CELL 70000 9.92632 0.000314328 1.0013 11.1553 90 2 7.5 1 0 0 0 0
…
…