TraceWin

 

D. Uriot, N. Pichoff

 

 

 

Université Paris-Saclay, CEA, Département des Accélérateurs, de la Cryogénie et du Magnétisme, 91191, Gif-sur-Yvette, France.

 

Updated, Mai 14, 2024

Abstract

 

The TraceWin code calculates the beam dynamics in a particle accelerator. The beam is modelled both by its second-order momentum (fast computation, in linearised force) and/or by a macro-particle distribution (longer computation, in non-linear forces). Their simultaneous use makes it easy to study the influence of non-linear 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 home-made 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

Installation      

Main features

Ways of using

Using TraceWin in a batch command

Toutatis using in TraceWin

Back tracking feature

PlotWin code

Files

Elements

Commands

Develop its own element or diagnostics

Transfer matrices

Dynamics calculations

RF cavity transient analysis with TraceWin

Errors study

Virtual accelerator

 


Technical support & maintenance services

Updates of the software

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.

Corrective maintenance

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.

Technical support

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 e-mail to the contact address setout below. The Code can be downloaded at:  http://irfu.cea.fr/Sacm/logiciels/ .

Evolutive maintenance

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 e-mail in the manner specified by the CEA.

Contact

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:

 

didier.uriot@cea.fr

 

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://dacm-codes.fr/forum/

 

Installation

Minimum configuration required

 

1 gigahertz (GHz) or faster 32-bit (x86) or 64-bit (x64) processor

1 gigabyte (GB) RAM (32-bit or 64-bit)

30 megabytes (MB) available hard drive space (32-bit or 64-bit)

 

Operating system:

 

Window (32-bit or-64-bit), version equal to or greater then WinXp

Linux (32-bit or-64-bit) with GLIBC library version equal to or greater than 2.6 (“ldd --version”)

MacOS with system version equal to or greater than 10.6

 

Remark about 64 bits Linux OS:

You're on a 64-bit system, you probably don’t have 32-bit 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.

To install (baseline) support for 32-bit executables

(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 ia32-libs

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 apt-get install ia32-libs

should grab you the (first, main) library you need.

Once you have that, you'll probably need support libs

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:

    linux-gate.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.

Commands to find the package per distribution family

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 apt-file

               sudo apt-get install apt-file && apt-file update

then search with

                apt-file 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 64-bit systems, 32-bit libraries live in /usr/lib and 64-bit libraries live in /usr/lib64.

(Debian/Ubuntu organise multi-architecture libraries differently.)

Installing packages for missing libraries

The above should give you a package name, e.g.:

libSM-1.2.0-2.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/apt-get as appropriate…. E.g pkcon install libSM.i686. If necessary you can specify the version fully. E.g sudo dnf install ibSM-1.2.0-2.fc15.i686.

Some libraries will have an “epoch” designator before their name; this can be omitted.

Warning

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...

If you don't use "sudo" in your set-up

Type

su -c

every time you see sudo, eg,

su -c dnf install glibc.i686

 

 

Installation and start:

 

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 double-clicking 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/).

 

 

Main features

 

·          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,

·          macro-particle tracking simulations (number of particles depends on free memory),

·          Each particle has a detailed analysis of its trajectory available,

·          Start-to-finish 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,

·          Diagnostic-based 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.

Way of using

General description and help

 

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.

 

 

 

Code stages

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

Data file

 

 

 

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 (LATTICEBegin of 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”

Diagnostic elements Diagnostic elements and Adjust commands Adjust commands in data file

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 Diagnostic elements 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

 


 

Editor

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.

 

 

 

 


 

Some output details

 

 

 

Zoom in by dragging a rectangle with the left mouse button.

Double-click 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 phase-space plots, the coordinates are selected by right clicking on the chart. In this case, you can either select one of the 8 proposed 2D phase-spaces 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 phase-space 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 phase-space [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

 

 

 

 


 

Using TraceWin in batch command

 

There are 3 ways to run TraceWIN in batch command corresponding to 3 types of executable files:

X11 or GUI full version

On an X console, hide the full TraceWin GUI / X11 with the “hide” command.

In this case, multi-threading 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

 

NoX11 or noGUI full version

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.

 

noX11 or noGUI minimal version

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, multi-threading 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 case-sensitive. 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 15th 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 vth parameter of for the nth  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

Space-charge routine is defined as picnir2D

picnic_3d

Space-charge 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 |W-Ws| > lost_e_limit

lost_p_limit

Particle is lost if |Ф- Ф s| > lost_p_limit

emit_e_limit

Particle is excluded form emit. calculation if |W-Ws|/ Ws > 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.


 

Acceptance calculation using TraceWin and PlotWin

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 phase-space 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 (left-click 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 phase-space 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 code

 

PlotWin is a post-processing tool allowing to projecting and plotting a 6D beam distribution in 2D sub-phase-spaces and associated 1D beam density profiles. As many as 6 phase-spaces can be plotted on the same chart. The number of phase-spaces 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

Back tracking feature

 

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” tab-sheet, 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

 

Example of reversed transport

The following example includes quadrupole and cavity field map:

 

SUPERPOSE_MAP 0

LME-Q11 : FIELD_MAP 70 480 0 40 9.174 0 0 0 qpole480_lme_25_01_07b

SUPERPOSE_MAP 250

LME-Q12 : 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

LME-Gr1 : FIELD_MAP 7700 300 -20 30 0.33 0.33 0 0 carte_3gap_2b

SUPERPOSE_MAP 250

LME-Q13 : 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

LME-Q13 : 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

LME-Gr1 : 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

LME-Q12 : MAP_FIELD 70 480 0 30 -7.4796 0 0 0 qpole480_lme_25_01_07b

SUPERPOSE_MAP 250 0 0 0 0 0

LME-Q11 : 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

 

Normal transport results

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 transport results

 

 

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.

 

 

 

Checking reversed structure and code

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

LME-Q11 : FIELD_MAP 70 480 0 40 9.174 0 0 0 qpole480_lme_25_01_07b

SUPERPOSE_MAP 250

LME-Q12 : 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

LME-Gr1 : FIELD_MAP 7700 300 -20 30 0.33 0.33 0 0 carte_3gap_2b

SUPERPOSE_MAP 250

LME-Q13 : 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

LME-Q13 : 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

LME-Gr1 : 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

LME-Q12 : MAP_FIELD 70 480 0 30 -7.4796 0 0 0 qpole480_lme_25_01_07b

SUPERPOSE_MAP 250 0 0 0 0 0

LME-Q11 : 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

 

Results

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

 

 

 

 

 

Files

 

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)

 

 

 


 

Data file

 

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.

Example 1:

; **********************************************

DRIFT 1e-08 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

;**********************************************

Example 2:

; **********************************************

DR1     : DRIFT 1e-08 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

;***********************************************

 

 

 

Init project file

 

The init file “project_name.ini” contains all the TraceWin project parameters. It can be loaded, saved, copied by using the TraceWin menu.

 

Results file

 

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

 

 

Sigma0 file

 

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

..

.

 

Magnetic or electric Field map

 

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×zmax/nz, i×rmax/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×xmax/nx, i×ymax/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×zmax/nz, ymin+j×(ymax-ymin)/ny, xmin+i×(xmax-xmin)/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×zmax/nz, i×rmax/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×zmax/nz, ymin+j×(ymax-ymin)/ny, xmin+i×(xmax-xmin)/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.

 

 

Current or space charge compensation map

 

“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 N-1

                Zi Scci

 

- Current evolution according to Z file format:

1 N

for i=0 to N-1

                Zi Ii

 

- 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.

Aperture map

 

“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 N-1

                Zi OuvXi OuvYi

 

- 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.

 

 

Input files for multiparticle programs

 

At the end of a calculation TraceWin creates the input files for multiparticle library, PARTRAN (Data_file_name.par), and TOUTATIS (toutatis.dat).

 

 

New Particle density distribution

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 tab-sheet “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)

}

 

 

 

 

Particle density distribution

 

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)

§  (cm2)

§   (cm)

§   (cm2)

§   (cm)

§   (cm2)

 

§  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 tab-sheet “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%,

 

 

Steerer strength file

 

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” page-sheet allows to extract all useful statistical results from this file.

 

Cavity setting point 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” page-sheet allows to extract all useful statistical results from this file.

 

Adjusted values 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.

 

 

Magnetic stripping file

 

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 tab-sheet “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.

 

Gas stripping file

 

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.

 

 

Lost particles file

 

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.

 

 

Input & Output particle distribution

 

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,

 

 

 

 

Error set of data

 

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:

,          

 

Error file result

 

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 4D-1

§  Emittance 6D/Reference emittance 6D-1

 

 

Halo definition.

 

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.

 

 

 

 

Partran and Toutatis output

 

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), áñ (deg.MeV)

§  Normalized rms emit: xx’(mm.mrad), yy’(mm.mrad), jW (deg.MeV).

§  Halo parameters: (Hxx, HYY’, Hz.dp/p)

§  Number of particles

§  Phase advance with space charge (deg/mm): σx, σy, σz.

§  Emittance at 99%: εxx’, εyy’, εz.dp/p

§  Djs (°), average beam phase  - reference beam phase

§  DWs (MeV), average beam energy  - reference beam energy

§  Beam currant (mA) used for space charge calculation

§  Aperture (mm)

§  Normalized 4D transverse emittance Exx’yy’ (mm.mrad)2

§  Normalized rms emit (mm.mrad): εrr’

§  Phase advance with space charge (deg/mm): σr

§  Lost power (W)

§  Maximum excursion particle : Xmax(mm), Ymax(mm),

§  Normalized long. rms emit: εz.dp/p (mm.%) [replace jW(deg.MeV) value]

§  RMS_SIZE [σz(mm)]

§  áz.dp/pñ (mm.%)

§  Dispersion: Dh (mm), Dv(mm)

§  Derivative dispersion: Dh’ (mrad), Dv’(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

 

 

Random seed file

 

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 matrix file

 

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” tab-sheet.

 

In “Charts” tab-sheet 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.

 


 

Elements

 

Alpha magnet

Beam current

Beam rotation

Bending magnet

Bunched cavity or thin gap

Cavity multi-gap

Circular or rectangular aperture

Containment channel

Diagnostic elements

Drift

DTL cell

Edge angle on bending magnet

Electrostatic Acceleration

Electrostatic bend

Electrostatic quadrupole

Electromagnetic static or RF field (Field Map)

Field map with curved reference trajectory

Funneling gap

Multipole Field Map

RFQ cell

Thin lens

Thin matrix

Thin steering

Sinus cavity or CCL

Solenoid

Space charge compensation

Quadrupole

 

 


 

Drift

 

Mnemonic

Parameter

Definition

DRIFT

L

Length (mm)

R

Aperture (mm)

 

Ry

Aperture (mm)

 

Rx_shift

Orizontal aperture shift (mm)

Ry_shift

Vertical aperture shift (mm)

 

If Ry equals 0, aperture is circular with R radius.

If Ry is not equal 0, aperture is rectangular with R the half dimension in x plane and Ry in y plane.

Rx/y_shift allows to introduce a non-cental aperture.

 

Link to Drift matrix

 

 

Quadrupole

 

Mnemonic

Parameter

Definition

QUAD

L

Length (mm)

QUAD_SPEC

G

Magnetic field gradient (T/m)

R

Aperture (mm)

Θ

Skew Angle (°)

G3 / u3

Sextupole gradient (T/m2) or relative sex. component

G4 / u4

Octupole gradient (T/m3) or relative oct. component

G5 / u5

Decapole gradient (T/m4) or relative deca. component

 

G6 / u6

Dodecapole gradient (T/m5) 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, un 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

 

 

 

Containment channel

 

Mnemonic

Parameter

Definition

CONF

L

Length (mm)

ns

Number of spce-charge kick (Partran only)

R

Aperture (mm)

kx

Horizontal focusing

ky

Vertical focusing

kz

Longitudinal focusing

 

 

Link to  Containment channel

 

 

 

Beam Rotation

 

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

 

Thin Lens

 

Mnemonic

Parameter

Definition

THIN_LENS

fx

Focal Length (m)

fy

Focal Length (m)

R

Aperture (mm)

 

Link to  Thin lens matrix

 

Thin Matrix

 

Mnemonic

Parameter

Definition

THIN_MATRIX

lg

Length (mm)

 

a00 to a55

Matrix terms, row per row

 

The 36 terms of a transfer matrix have to be set row by row from a00 to a55. Length, lg, is just used in graphic view.

Link to  matrix format R

The associated phase-space 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

 

Electrostatic Quadrupole

 

Mnemonic

Parameter

Definition

QUAD_ELE

L

Length (mm)

Vo

Voltage between electrodes (V)

R

Aperture (mm)

Θ

Skew Angle (°)

V3 / u3

Sextupole voltage gradient component (V/m)  or relative

V4/ u4

Octupole voltage gradient component (V/m2) or relative

V5/ u5

Decapole voltage gradient component (V/m3) or relative

 

V6/ u6

Dodecapole voltage gradient component (V/m4) 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, un are relative multipole components will defined such as:

 

 

 

Link to  Quadrupole matrix

 

 

Bunched cavity or thin gap

 

Mnemonic

Parameter

Definition

GAP

E0TL

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

 

 

Sinus cavity or CCL

 

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

 

 

 

Bending magnet

 

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

 

 

Edge angle on bending magnet

 

Mnemonic

Parameter

Definition

EDGE

b

Pole face rotation angle (deg)

|ρ|

Curvature radius of bend (mm)

G

Total gap of magnet (mm)

K1

Fringe-field factor (default = 0.45)

K2

Fringe-field 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 K1 and K2 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

 

Electrostatic bend

 

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.

Circular or rectangular aperture

 

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.

 

 

 

Space charge compensation

 

Mnemonic

Parameter

Definition

SPACE_CHARGE_COMP

k

Beam current is compensated by a factor k

 

Set a beam new current: Ib = (1-k)×Ib.

 

 

Beam current

 

Mnemonic

Parameter

Definition

CURRENT

Ib

Beam current (mA)

 

Set a beam new current: Ib (mA).

 

Solenoid

 

Mnemonic

Parameter

Definition

SOLENOID

L

Length (mm)

B

Magnetic field (T)

R

Aperture (mm)

 

Solenoid treated as thick length.

 

Link to Solenoid matrix

 

Thin steering

 

Mnemonic

Parameter

Definition

THIN_STEERING

BLx or ELx

x-component (T.m or V)

Bly or ELy

y-component (T.m or V)

r

Aperture (mm)

Elec

0: magnetic deviation (default)

1: electric deviation

 

Transverse kick.

 

Link to Thin steering matrix

 

 


 

DTL cell

 

Mnemonic

Parameter

Definition

DTL_CEL

L

Cell length (mm)

Lq1

First ½ quadruploe length (mm)

Lq2

Second ½ quadruploe length (mm)

gc (*)

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 gc(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

 

 

 

Cavity multi-gap

 

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

kEoTi

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 multi-gap matrix

 

 

RFQ cell

 

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 front-end cells.

 

(**) Optional parameter, but necessary defined for TWOTERM RFQ.

 

 

Link to RFQ cell matrix

 


 

Diagnostic elements

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

Current

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)

 

Ibn-Ibn-1

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

 

 

 

 

 

Positions

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

 

 

X-Y

Wanted X-Y 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 X-Y 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 Low-pass filter frequency (MHz)

 

 

 

 

Sizes

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 Low-pass 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

 

xn-yn

Wanted x-y FWHM delta size (mm)

(FWHM)

 

dm

dx-y size Accuracy (mm)

 

 

 

 

Delta size

DIAG_DSIZE

N

Diagnostic number

Xrms-Yrms

 

xn-yn

Wanted x-y rms beam delta size (mm)

 

 

dm

dx-y size Accuracy (mm)

 

 

 

Delta Full Width at

DIAG_DSIZE2_FWHM

N

Diagnostic number

Half Maximum

 

xn-xn-1

Wanted x HWHM delta size (mm)

between 2 positions

 

yn-yn-1

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

 

xn-xn-1

Wanted x rms beam delta size (mm)

(At least 2 are

 

yn-yn-1

Wanted y rms beam delta size (mm)

needed)

 

dm

dx & dy size accuracy (mm)

 

 

 

Delta phase spread

DIAG_DSIZE3

N

Diagnostic number

Measurement 2

 

ΔPn-ΔPn-1

Wanted rms delta phase spread (°)

(At least 2 are

 

dΔP

Phase spread accuracy (°)

Needed)

 

fo

dΔP Low-pass filter frequency (MHz)

 

 

 

 

Delta divergence

DIAG_DPSIZE2

N

Diagnostic number

between 2 positions

 

x'n-x’n-1

Wanted x’ rms beam delta div. (mrad)

(At least 2 are

 

y’n-y’n-1

Wanted y’ rms beam delta div. (mrad)

needed)

 

dpm

dx' & dy’ div. accuracy (mrad)

 

 

 

 

Phase measurement

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

xx'

(1/0)

xx’

(1/0)

yy'

(1/0)

yy’

(1/0)

zdp/p

(1/0)

zdp/p

(1/0)

 

Make equal transverse Twiss parameter at diagnostic position

DIAG_DTWISS2

N

Diagnostic number

 

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

 

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

 

Sx0

Diagnostic number

Number of upstream elements concerned

Wanted max beam size X (mm), if !=0

Limit beam size min

DIAG_SIZE_MIN (***)

Sy0

Wanted max beam size Y (mm), if !=0

 

Sz0

Wanted max beam size Z (mm,deg), if !=0

If Sz < 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(1e-4) 1 0.1 0.1 0.2 , here this diagnostic emittance criteria is reduced by a factor 10000.

 

MY_DIAG(my_diag_func)(1e-4) 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

Sx, Sy, Sz,φ are the imposed beam size max in the N_ele elements upstream this diagnostic.

 

When Sx > Sx0 set size max criterion:     

When Sx < Sx0 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 Sz 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

 

 

 

Funneling gap

 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

 

 

Alpha magnet

 

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

 

 

Electrostatic Acceleration

 

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

 

 

 

Field Map

 

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 (100)                   : static electric field,

o  tens figure (101)                   : static magnetic field,

o  hundreds figure (102)             : RF electric field,

o  thousands figure (103)          : RF magnetic field,

o  ten thousands figure (104)     : 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 off-axis 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

 

 

 

 

 

 

 

 

 

 

 

Field map with curved reference trajectory

 

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 Z0 X0 Y0 θ Z0 θ X0 θ Y0

 

Where:

(X0, Y0, Z0) 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 Z0 = -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 Z0 X0 Y0 θ Z0 θ X0 θ Y0

 

(X0, Y0, Z0) 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 (0i, Xi, Yi, Zi) 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 Zi Xi Yi θ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 Zi 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 Zout Xout Yout θ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 Zi 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 Zi parameters and not the other parameters.

 

 


 

Multipole Field Map

 

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.

 

 

 


 

Commands

Change element parameters:

Add or change variable, (including or not math expressions)

Chopper

Change structure frequency

Change some beam parameters

Duplicate element

Steerer

Shift

Structure file end

Superpose field map

Set field map files path

Set output field map frame

Move diagnostics in field map element

RFQ:

Set RFQ coupling gap

Set RFQ front-end gaps

Set RFQ electrode type

Set RFQ vane geometry

Lattice commands:

Begin of lattice

End of lattice

Set phase advance

Define doublet section

Matching commands:

Minimize beam envelope variation

Matching element commands

Minimize emittance growth

Minimize field variation

Minimize phase variation

Set achromatic line

Set centroid position

Set beam energy and phase

Set beam phase advance

Set beam phase error

Set beam separation

Set beam size

Set maximum beam size

Set minimum beam size

Set synchronous phase

Set Twiss parameters

Errors:

Input beam errors

Bend errors

Cavity errors

RFQ errors

Quadrupole errors

Set of field map

Set error ratios

Set set of error from file

Apply phase error to synchronous phase

Set Gaussian cut-off

Adjust commands

Gas pressure

Plot distribution

Read a multiparticle output file

Read a particle file

Set PARTRAN steps

Change space charge meh

Magnetic or electric static field

Change beam parameters

Set Marker

Change Energy and Phase limit

Change transverse beam centroid

Cavity tuning

Set magnetic excitation curve

 

 

 

 

 

Change structure frequency

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.

 

Add or change variable (including or not mathematical expressions)

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.

 

 

 

Define doublet section

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.

 

 

Begin of lattice

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 macro-lattice (usually 1). The number of element per macro-lattice is then n1×n2. The basic lattice is used for set the phase advances according to SET_ADV commands. The macro-lattice 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.

 

 

 

 

End of lattice

LATTICE_END

 

LATTICE_END command ends the periodic focusing lattices.

 

 

Structure file end

END

 

END command ends a structure file (*.dat) description (compulsory).

 

 

 

 

Set phase advance

SET_ADV kx0t  ky0t

 

The SET_ADV command sets the zero-current horizontal phase advance to kxot and the zero-current vertical phase advance to kyot.

By default, without kyot value, kyot = kxot.

 

the phase advance definition.

 

 

To set a transverse phase advance law

 

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 zero-current 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 zero-current transverse phase advance law describe in the Sigma0 fileSigma0 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.

Phase advance example

 

;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 macro-lattice (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 zero-current phase advance law, using the lattice transfer matrix.

Warning: it is not always possible to find the required quadrupole gradients.

 

Matching commands

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.

 

Matching Way

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”.

 

Optimization

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 fileResults 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

 

Matching section or family

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 example 1

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”.

 

; *****   RFQ-DTL Matching line    ******

DRIFT 1e-05 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 example 2

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

 

Matching example 3

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

..

.

 

 

 

Matching example 4

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

 

 

 

Matching example 5

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 parameters

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 fn 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 beam centroid position

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 achromatic line

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 maximum & minimum beam size

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 > x0 set size max criterion:         

 

When x < x0 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 beam size

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 beam separation

SET_SEPARATION k, Sx, Sy

 

Sx0, Sy0 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:

 

 

 

 

Minimize emittance growth

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

STEERER Bx(T) By (T) Bmax 0 coef1(m) coef2(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 coef1 and coef2 allow to introduce non-linear 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 coef1 and coef2 allow to introduce non-linear forces in the steerer deviation.

coef1 and coef2 units are meter.

 

-          If coef1 is not equal to 0 (SPIRAL2 type steerer):

 

         

 

 

-          If coef2 is not equal to 0 (ESS type steerer):

 

                        

 

With: see  TraceWin gradient definition.

 

 

 

 

 

Chopper

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.

 

 

Set Gaussian cut-off

ERROR_GAUSSIAN_CUT_OFF cut-off

 

When the error distribution is defined to Gaussian, this command allow to set a cut-off value.

A new command change this value the following elements concerned by ERROR_XXX commands.

 

 

 

Input beam errors

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 cut-off can set using SET_GAUSSIAN_CUT_OFF

 

NCP CPL STAT DYN meaning

 

See also  ERROR_STAT_FILE & ERROR_DYN_FILE.

 

 

 

 

 

 

 

Quadrupole errors

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, z-axis 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 cut-off 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):

 

 

Z0(m) r(0/1/2) dx(mm) dy(mm) φx(°) φy(°) φz(°) dG(%) dz(mm), dG3(%) dG4(%) dG5(%) dG6(%)

Z1(m) r(0/1/2) dx(mm) dy(mm) φx(°) φy(°) φz(°) dG(%) dz(mm), dG3(%) dG4(%) dG5(%) dG6(%)

Zn(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

 

NCP CPL STAT DYN meaning

 

 

Set phase error to synchronous phase

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.

 

Cavity errors

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, y-axis. 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 cut-off 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φ*Err

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.

 

Z0(m) r(0/±1/2/±3) dx(mm) dy(mm) φx(°) φy(°) E(%) φ(°) dz(mm)

Z1(m) r(0/±1/2/±3) dx(mm) dy(mm) φx(°) φy(°) E(%) φ(°) dz(mm)

Zn(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 multi-gap

- DTL (Warning the DTL are only concerns by the field errors)

- Sinus cavity

- Field map if not defined as static magnetic field

NCP CPL STAT DYN meaning

 

 

 

Bend errors

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, z-axis 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 cut-off 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.

 

 

NCP CPL STAT DYN meaning

 

See detail about bend error treatment.

 

 

 

Adjust commands

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 v-th 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.

 

 

Adjust and diagnostic examples1

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

 

Adjust and diagnostic examples2

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

 

Adjust and diagnostic examples3

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

 

 

Adjust and diagnostic examples4

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

 

 

 

RFQ errors

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.

 

NCP CPL STAT DYN meaning

 

 

 

(*) Images provided by Ibon Bustinduy, ESS Bilbao.

 

 

 

 

 

Plot distribution

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 pressure

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).

 

Minimize enveloppe variation

MIN_ENV_VARIATION k, N

 

Minimize the variation of the maximum and minimum transverse beam envelope in magnetic element. For bunched beam, the phase-spread 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.

 

 

Minimize phase variation

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 CPL STAT DYN meaning

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).

 

 

Set RFQ vane geometry

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

 

 

Set RFQ electrode type

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.

 

 

Set RFQ coupling gap

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 half-ellipse size in the beam direction and St is the half-ellipse height in the perpendicular beam direction.

 

 

 

Set RFQ front-end cell gaps

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 front-end gap of the first (GapRMS) and the last (GapFFS) RFQ_CELL (type 3). In Toutatis, these gaps are by defaut defined as ¼ of the front-end cell length. Set GapRMS or GapFFS parameter to 0 to use the Toutatis default values.

 

Set of field map

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

LME-Q11 : 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

 

 

 

Set of error from file

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

 

 

 

 

Set error ratios

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.

 

To read a particle file

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.

 

To read a multiparticle output file

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.69068e-05 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.69068e-05 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