ORBIT User Manual

Version 1.10

SNS Building MS-8218, Oak Ridge National Laboratory

104 Union Valley Road, Oak Ridge, TN 37831-8218, U.S.A.

Brookhaven National Laboratory

Upton, NY.

July 16, 1999

Number 011, Rev. 1

Acknowledgements

This code was written with the help from many people. Many of the specific actions of the macro-particle ‘injection’ nodes follow methods from ACCSIM, written by Fed Jones of TRIUMF . Many thanks to Scott Haney of Los Alamos National Laboratory for useful discussions on the macro-particle ‘herd’ architecture and for writing the SuperCode driver shell. Thanks also the Geoff Furnish for not dropping PLPLOT support. Finally thanks are due to the Spallation Neutron Source project for supporting work on this code.

ORBIT (Objective Ring Beam Injection and Tracking) is a particle tracking code for Rings. This document is intended to be an introduction on how to use the ORBIT code. This includes a 1) description of the general code architecture, 2) a description of how to implementation specific features and 3) some examples of how to use features. As this is a user manual, documentation of the underlying physics is not provided here. Rather a description of how to use the code to simulate various problems is given.

ORBIT is a C++ code and requires a C++ compiler to build. It is distributed as source. It has been built successfully with various versions of the GNU g++ compiler, as well as proprietary compilers. It also uses several additional freely available packages, as discussed below. Note: it is important to build the SuperCode driver shell (see below) with the same compiler as used to build ORBIT, to avoid name mangling problems when linking.

ORBIT uses a number of freely available packages. The SuperCode driver shell (see below) is required. A number of additional packages are optional, and provide additional capabilities. These packages should be built first. They are included in ORBIT during the build by previously defining the following environment variables, that should be defined in a logon script (e.g. .profile or .login file) :

This library is required for the interactive plotting capability. If it is not installed on your machine, ORBIT and SuperCode should build fine, but the plotting capability will not be available. After obtaining the PLPLOT lib from the above address, followthe instructions in the README and INSTALL file. Be sure to build it with double precision (i.e. with the –with-double flag) and without shared libraries (i.e. –without-shared flag). Then install it (preferably with root privilege in a normal place like /usr/local/plplot directory). Try building and running some of the ditributed examples to see if it’s working (esp. the postscript and X-window drivers).

This package is used and needed for the FFT space charge routines in ORBIT. If you think you may want to use the space charge capabilities, build this package first. Get it from the above WWW address and follow the instructions to build it. It does not have an ‘install’ capability to copy the built libraries etc. to a common area, so you must either define FFTW_ROOT to the directory where you built this package, or else manually copy the library and header files to an appropriate common directory (e.g. /usr/local/fftw/…).

If the SuperCode driver shell is already built on your system, just define your SUPERCODE_ROOT environment variable to be the installation directory, and skip the rest of this section.

The SuperCode driver shell must be built on the platform you want to run on. Start by defining CPU, and PLPLOT as described above. This shell has been built on Alpha, IBM, HP, SUN workstations, as well as LINUX running on PCs and Alphas. Additionally, for this package you may want to define the optional environment variables, before building it:

READLINE_ROOT – directory for the libreadline.a and libtermcap.a libraries. These are standard on many systems, and are also available from GNU. Building with READLINE_ROOT defined permits interactive command line history and editing capability when running ORBIT.

GALIB – The installation directory for the GALib genetic algorithm optimization class library, see http://lancet.mit.edu/galib-2.4/ for the source . This allows use of the genetic algorithm optimizer in the Solver module. It is unlikely you’ll need it for ORBIT however.

With these environment variables defined, get the SuperCode distribution (i.e. the sc.tar tar file) and untar it by typing

tar –xvf sc.tar

and then change directories to the newly created SuperCode directory. Then type

Then be sure there is a file Config/$(CPU).mak, where CPU is whatever you decided to call your CPU environement variable. There are a number of example ".mak" files you can use. Edit this file appropriately to define the compilers on your machine, and flags you wish to use for building. Also check to ensure there is a file called SCL/$(CPU).config . This file contains all device dependent source code. Again find an example that looks close to the configuration you are using and try using it. Both of these files are used later in the ORBIT build.

Documentation for this driver shell is provided in the SuperCode/Docs/SCManual.ps file. Warning: the section about support for FORTRAN modules is obsolete.

Next untar the ORBIT distribution (ORBIT.tar) file by typing

tar –xvf ORBIT.tar

Make sure that the executable you created in the step above, is in your PATH environment variable, relative to wherever to want to work with it. Then just type "ORBIT" to start it up. You can not only run the accelerator routines from here, but you can also do the general programmable script stuff described in the SuperCode documentation.

ORBIT will automatically read in the file ORBIT.sc on startup, if it exists in the directory you are running in. An example ORBIT.sc file is distributed with the code, which includes some general settings and routines. Be sure to comment out the plotting stuff if you did not build your Shell with the interactive plotting. This is not meant to be a problem specific input file.

Usually, a run will be configured by appropriate settings in an input script file. You can have this input file read at startup by including its name as the first argument to the executable ORBIT, e.g.: typing

ORBIT case1.sc

include "case1.sc" // read the file case1.sc

(the ‘//’ and following text is treated as a comment, see Ref. [1]). Note that one input file can include others. For example, the file case1.sc could include a line like:

include "standardLatticeSetup.sc" // do a common lattice configuration.

OFstream fio("fileout", ios::out);

OFstream fio("fileout", ios::app);

See the SuperCode manual [1] for more information on inputting/outputting information from the Shell.

Just type "quit" and hit return. This can also be included in script files as well.

You can suspend whatever is happening by hitting ‘control-c’. On some systems, doing this multiple times also kills the run, so be careful.

The ORBIT code is written in C++, and operates using the SuperCode [1] driver shell. Before discussing any specifics of the ORBIT code itself, a few words are useful to explain the relationship between user provided "physics" modules and the driver shell. Conventional scientific programs typically have a prescribed flow of logic originating in a main program. Often there are several program flow choices, governed by appropriate choice of input variable settings. The program execution remains in compiled code until program completion. If the user desires some new flow logic, an edit-compile (debug) programming cycle is required.

On the other-hand, the SuperCode is a programmable driver shell, which can execute interpreted script files as well as compiled "physics" modules. Generally runs are done by reading in a "script" input file. These script input files are more general than typical "namelist" files which simply assign values to variables. Since SuperCode is a programmable interface, calling sequences to compiled code can be customized within a script "input" file (without recompiling). In fact there is no fully compiled set of logic to do a run. Rather the "general purpose" workhorse physics modules are compiled as a "tool-set", and the calling sequences, looping, initial variable settings etc. are done through the shell. Additionally, routines can be created on-the-fly in script files and included in the customized run sequence. This driver shell is described in detail in Reference [1].

Both interpreted and compiled code have their place. Compiled code is much faster in general. Compiling everything however leads to code clutter (i.e. one-off numerical experiments, or scans that are never used again, along with variables to control them). The general philosophy for the separation of interpreted and compiled code is: code that is execution intensive, and/or general purpose is compiled. Examples of compiled code would be particle transport through a matrix multiplication operation. Code that is problem specific and generally not called often during a run is interpreted. Interpreted code examples are variable initialization, setting up "one-off" parametric scans, etc.

SuperCode comes with a number of general purpose modules (see [1]). These include: (1) optimization (calculus based and genetic-algorithm), (2) Probabilistic risk analysis (or uncertainty analysis), (3) Mathematical tools ( splines, B-splines, random numbers, Bessel functions, …), (4) interactive plotting, and (5) parallel processing. ( Note - the shell plotting capability provides rudimentary, X-Y and 3-D capabilities, and is intended to provide a quick diagnostic capability, not an exhaustive plotting capability). Note also that a number of these features require special libraries to be installed on your system as discussed in section 1.2. All of these libraries are free, and generally run on most UNIX platforms. These general purpose modules are described in Ref. 1. The Shell is also buildable on Mac and PC OS’s. for those so inclined.

The procedure for actually constructing "physics modules" to be run with the SuperCode shell is described in Ref.1. When adding a new module in practice, it’s usually sufficient to mimic the method of an existing physics module. The general relationship between the user supplied physics modules and the driver shell is shown schematically in Fig. 1.1.

The Module Descriptor File is a useful place to get information about a module. It lists all the variables and routines that the Driver shell knows about in that particular Module. This is the place where these quantities should be documented. Variable quantities in these files can be manipulated from the Shell. The routines in the Module descriptor files can also be called from the Shell. In fact, putting together a set of variable initializations, and routine calls in a script file is how a "run" is typically done.

Note that the driver shell can not directly access class members. To access class members from the Shell (manipulate, view, etc.), a Module routine must be written (and compiled) to perform the appropriate manipulation. Examples where this may be done would be a routine to create a macro-particle, or a routine to dump macro-particle information to a stream. These compiled routines could then be called from the Shell, and the actual class member manipulations would be performed in the compiled routine.

Unless stated otherwise, MKS units are employed. There are a number of notable exceptions however. Macro-particle coordinates are in mm for distance and mrad for angles. Also the particle energy is in GeV, and RF and space charge voltages are in kV. Generally the units of variables are documented throughout the code. Every module member has a description with should include its unit (if any). The description can be found by looking in the module descriptor file (*.mod), or for example by typing in the shell:

ORBIT[1]: about("lRing"); // find out what lRing is.

The result:

// Total ring length [m]

static Real Ring::lRing;

In thinking about the tracking of macro-particles around a ring, two main ideas come to mind: the macro-particles themselves and the Ring elements which operate on them in various ways. These are each represented as distinct classes, and much of the code is based on these. As such they are described in some detail here. We stress that the class structure adopted here has separated the macro-particle information container (MacrPart class) and actions done on macro-particles (Node base class) into two separate class structures. The connection between these classes is that the Node classes require a reference to a MacroPart herd. This separation facilitates the easy tracking of multiple herds through a single ring, which, for example, is useful for tracking prescribed test particles in the presence of a main herd.

We reiterate that the actual user implementation of these classes is done via "modules". These modules contain the user interaction mechanisms for instantiating objects, performing member function calls, etc. The modules and actual use of the classes are described later in Section 3.

//////////////////////////////

// Make a synchronous particle:

//////////////////////////////

Real TSync = 1.; // Kinetic Energy (GeV)

Real mSync = 1; // Mass (AMU)

Real charge = 1; // charge number

addSyncPart(mSync,charge,TSync);

mainHerd = addMacroHerd(12000);

Integer testHerd = addMacroHerd(100);

Real x,xp,y,yp, dE, phi;

x = 1.;xp = 0., y=0., yp=1.; // mm, mrad

addMacroPart(x, xp, y, yp);

x = 2.;xp = -1., y=1., yp=-1.; // mm, mrad

addMacroPart(x, xp, y, yp);

addMacroPartBase(testHerd, x, xp, y, yp); .

To also specify the macro-particle longitudinal coordinates, use

x = 1.;xp = 0., y=0., yp=1.; // mm, mrad

dE = 0.001; phi=90.; // GeV, degrees

addMacroPart2(x, xp, y, yp, dE, phi);

addMacroPartBase2(testHerd, x, xp, y, yp, dE, phi);

These routines are the core means of adding particles to a herd, and can be called directly from the shell as shown above. However it is too cumbersome to actually directly use these routines to create a herd of say 100,000 particles. In practice, they are more often called automatically from routines that sample from a prescribed distribution type (see the Injection Module below), or by using a feature to read from a file. For example, using:

readParts(mainHerd, "filename", nParts);

Real x1 = xpVal(11); // x1 contains the x’ value of the 11^th

// macro-particle in the mainHerd.

Real x2, yp3;

X2 = xValBase(2, testHerd); // x2 now contains the x value

// of the 2^nd particle in herd testHerd

yp3 = ypValBase(3, testHerd); // yp3 now contains the y’ value

// of the 3^rd particle in herd testHerd

RealVector xx;

xVals(xx); // xx now contains all nMacroParticles x values of the mainHerd

Ofstream fio("particle.dmp", ios::out); // create a stream to a new

// file called "particle.dmp"

dumpParts(mainHerd, fio); // dump the coordinates of the mainHerd

// macro-particles to stream fio

It is also possible to calculate and send the extrema information (maximum /minimum particle coordinates) of a herd to a specified stream. For example,

OFstream fio("case1.out", ios::app); // create a stream to an

//existing file called "case1.out"

showExtrema(mainHerd, fio); // dump the extrema of the mainHerd

// particles to stream fio

showExtrema(mainHerd, cout); // dump the extrema of the mainHerd

// particles to the screen

showHerd(cout, testHerd);

The Ring module is a general module, which controls the overall execution flow for the macro-particle tracking. Although it has no classes itself, it contains some tracking initialization and "hooks" that actually perform the calls to the Node class calculators. Some of the important routines from this Module are described below.

doTurn(100);

doTurnBase(mainHerd, 100);

doTurnBase(testHerd, 2);

turnToNode(mainHerd, 23);

This module implements diagnostic class objects in routines that are accessible from the shell. The classes are declared in file DiagClass.h. Some of these are implemented so that they can be called directly from the shell, and provide information about some aspect of a herd. Other diagnostics are implemented as ring Nodes, which can be called regularly as the beam traverses the ring.

nEmitBins = 50; deltaEmitBin = 2.; // Bin from 0 to 100 pi-mm-mrad

calcEmitBase(mainHerd); // Calculate the main herd emittance

cerr << "X RMS Emit = " << xEmitRMS << "\n";

cerr << xEmitFrac; // Dump the vector of the horizontal emittance

// distribution to the console.

A simpler way to get these calculations done for you, and have the results printed in a readable format to a stream, use either:

showEmitBase(mainHerd, cout); // this routine dumps emittance

// information for any specified herd.

showEmit(cout); // this only works for the mainHerd.

The canonical coordinates of a particle are the coordinates in the transformed coordinate system, in which the betatron oscillations are circular. These are used in many of the diagnostic calculations, but may also be of interest to the user. Executing

OFstream fio("test.dat", ios::app) // get a file ready to append to.

dumpEAndCC(mainHerd, fio); // dump the tunes and canonical coordinates

The action variables (i.e. Courant-Snyder actions) of a herd can be calculated and dumped to a stream. For example:

calcActions(mainHerd); // calculate the action variables for each

// macro-particle in the mainHerd.

OFstream fio("Actions.dat", ios::out) // create a file.

dumpActions(mainHerd, fio); // calculate and print the action variables

// for each particle in the mainHerd.

< (x - <x>)^i-1 > * < (y - <y>)^j-1 >

showMoments(mainHerd, 3, fio); // calculate up to 2^nd order moments

// of the main herd and dump

// them to stream fio.

The Diagnostic nodes can be added anytime during a run. By default they are inactive, and are skipped over until they are activated. After they are used, they may subsequently be deactivated, and "normal" tracking calculations can be continued. These nodes can be activated and deactivated as much as needed, but use caution with them, as large amounts of data may be output when they are active.

// stick a moment node at node position 22,

// calculating beam moments up to order 3:

addMomentNode("moment Node", 22, 4, "MomentDump.dat");

activateMomentNodes(); // activate this momentNode

doTurn(10); // turn the mainHerd 10 turns

deactivateMomentNodes(); // deactivate this momentNode

doTurn(100); // track the mainHerd some more

Where the first index = (horizontal moment+1) and the second index = (vertical moment+1).

It is possible to add a set of moment nodes after each transfer matrix advance all around the ring with:

// stick a moment node after every transfer matrix in the ring

// calculating beam moments up to order 3:

addMomentNodeSet(4, "MomentDump.dat");

activateMomentNodes(); // activate this momentNode

doTurn(10); // turn the mainHerd 10 turns

deactivateMomentNodes(); // deactivate this momentNode

doTurn(100); // track the mainHerd some more.

If the transfer matrix advance is small compared to the betatron oscillation length, the output from this set of diagnostics is useful for looking at the oscillations in the moments of the beam.

Statistical lattice parameters for a herd can be calculated using this diagnostic. The statistical lattice parameters are calculated using the moments of the canonical coordinate variables discussed above, along with the emittance. These nodes are called "StatLat" nodes and use the StatLatDiagnostic class. A single statistical lattice parameter node can be added using:

// stick a StatLatnode at node position 22,

addStatLatNode("StatLat Node", 22, "StatLat.dat");

activateStatLatNodes(); // activate this StatLatNode

doTurn(20); // turn the mainHerd 20 turns

deactivateStatLatNodes(); // deactivate this StatLatNode

Each line in the output file ("StatLat.dat" above) contains: (1) the turn number, (2) the azimuthal position around the ring (m), (3) the statistical horizontal beta (m), (4) the statistical vertical beta (m), (5) the statistical horizontal alpha, (6) the statistical vertical alpha, (7) the lattice horizontal beta (m), (8) the lattice vertical beta (m), (9) the lattice horizontal alpha, and (10) the lattice vertical alpha. It is possible to add a set of statistical lattice nodes all around the ring, to get "high frequency" lattice information dumped to a file, e.g.:

// stick a StatLat node after every transfer matrix in the ring

addStatLatNodeSet(4, "MomentDump.dat");

activateStatLatNodes(); // activate this StatLatNode

doTurn(3); // turn the mainHerd 3 turns

deactivateStatLatNodes(); // deactivate this StatLatNode

doTurn(100); // track the mainHerd some more.

// Add a PMT set:

addPMTNodeSet("PMTTest.dat", 2,1); // track at horizontal 1st order moment

// oscillations

// Make a test herd:

Integer testHerd = addMacroHerd(10); // small test herd

setHerdFeelLevel(testHerd, 1); // this herd only feels the mainHerd.

addMacroPartBase(testHerd, 10., 0.1, 5., 0.1);

addMacroPartBase(testHerd, 1., 1., 0.1, 1.);

doTurn(2); // Turn the main herd a few turns:

// Turn both herds 3 turns with PMT's on:

activatePMTNodes();

turnHerds(3);

deactivatePMTNodes();

The output in the file "PMTTest.dat" contains on each line: (1) the turn number, (2) the azimuthal position (m). Then on the same line, for each particle in the test herd being used : (3) the canonical horizontal position (mm), (4) the canonical vertical position (mm), (5) the canonical horizontal momentum (mrad), and (6) the canonical vertical momentum. This technique can create large output files if test herds with many particles are tracked.

One can get a status report of all the diagnostic nodes in the ring sent to a stream with the command:

OFstream fio("Case_1_2_3.out", ios::out) // create a file.

showDiagnostics(fio);

showDiagnostics(cout); // show a list of all diagnostic nodes in the

// ring to the screen

It is possible to run ORBIT in a parallel processing mode. The approach taken here is to launch multiple ORBIT processes on different CPUs, each parsing the same input script file. Most of the calculation proceeds independently on each processor, with the exceptions:

• Initialization of the random number seed used to generate macro-particles from prescribed distributions
• Space charge calculations
• Diagnostic calculations
• Output

Other calculations such as lattice matrix advances, aperture checks, thin lens kicks, etc. have no need for parallel communication and are exactly the same as for a serial run.

We use a message passing "master-slave" method for the parallel implementation here. In particular, PVM is used to do the message passing (see reference 6). This package is free, and available for most computing platforms. It has been tested with ORBIT using version 3.4.0. The PVM package must be installed on your computer before you build ORBIT. Then define the environment variable PVM_ROOT to be the installed directory of PVM. Then build ORBIT. If you do not have PVM installed on your system, ORBIT will build fine, but the parallel capability will not work. Also, If you want to run parallel, it is advisable to have a system of CPUs connected with fast (at least 100 Mbs) switching. Parallel space charge calculations on work station clusters connected with 10 Mbs TCP will perform poorly.

Before starting a parallel run, the vitual parallel machine must be set up. This is done by running the pvm daemon. It is possible to construct a "hostfile" containing the names of all the nodes of the parallel computer, and the directories containing the ORBIT executable and the input script file (i.e. where you want to work). Here’s an example hostfile (see the PVM manual for details):

Some parallel settings and output of interest are

Also note that timing a run is different for a parallel run. A useful indicator of run time is the wall clock time. An example of getting this is shown in the example in the section below.

Parallel runs must be run with an input script file. The basic structure of a parallel input script is shown schematically in Fig. 3.1. An example script file is shown below also, with the parallel calculation dependent pieces highlighted. The parallel calculation is started by having ORBIT read an input file that is set up to do a parallel calculation, e.g., by typing

ORBIT parallel.sc

The ring node structure set up is the same as for a serial run. The macro-particle setup is pretty much the same, except do not track any macro-particles on the parent (see the example below). The strategy taken in the present ORBIT parallization is to use the parent to corredinate all the message passing, and not spend time tracking. If you do not like wasting a CPU with no tracking, set the spawnOnParent to 1, and a child ORBIT process will be spawned on the same CPU as the parent.

An example of a parallel calculation is shown below.

The most time critical parallel calculation is the transverse space charge calculation, and as such is described briefly here. As herds are tracked in parallel around a turn on different processors, at each space charge kick node, the collective force must be gathered and communicated between nodes. Typically this will happen 100’s of times per turn. The strategy taken to parallelize this calculation is shown in Fig. 3.2. Note that each child calculates its own FFT of the Greens function and the global charge distribution. This is faster than waiting for one processor to do it, and passing the results.

• All moment diagnostics
• StatLat diagnostics
• Cannonical coordinate diagnostic
• Poincarre moment tracking diagnostic

4. Modules Governing Derived Node Classes

Void addTransferMatrix(const String &name, const Integer &order,

const RealMatrix &R, const Real &bx, const Real &by,

const Real &ax, const Real &ay, const Real &ex, const Real

&epx, const Real &l)

Void readDIMADFile(const String &s1 )

Void readMADFile(const String &s, const String &s) .

readDIMADFile("SNSLattice.dmo");

print

interval marker1 marker2 99 end,

-11 1,

readMADFile("SNSTwiss.out", "SNSTM.out");

There is one piece of information that should be input independently from the above call, namely the transition gamma. E.g., also include a line like:

gammaTrans = 4.93;

The Twiss file can be generated by including a line in the MAD input file like:

TWISS, SAVE, TAPE=SNSTwiss.out

SELECT, FLAG=FIRST, RANGE=#S/#E

Presently the code simply advances the macro-particles of a specified herd through the linear transfer matrix. The same transport equations as used in ACCSIM [2] are employed here. Also, as discussed below, some tune shift calculations are optionally provided here.

This capability is experimental at present.

Note: this set of calculations will likely be moved to a diagnostic module in the future.

Tune shifts calculations are possible for a herd. This is useful when transverse space charge kicks are employed, or a second order matrix advance is used (otherwise the particles just have the bare lattice tune). There are two tune shift calculations provided. One method involves following the phase advance of each macro-particle as it is advanced through each transfer matrix. As long as the are enough transfer matrices included to allow tracking steps small compared to the betatron period, this technique will allow computation of the absolute tune of each particle.

This method is slow and should not be employed during long runs, but rather at the end of a run or during a "snapshot turn". The following input file fragment shows how the tunes could be calculated and dumped to a file during a run:

doTurn(1000); // do 1000 turns of the mainHerd

useSimpleTuneCalc=False; // default value anyway, but let’s be clear

startTuneCalc(); // start calculating tunes

doTurn(1); // calculate the tunes over one turn.

stopTuneCalc(); // stop calculating the tunes, and tally the

// tunes for each particle.

OFstream fio("tunes.out", ios::out); // make a file to dump tunes to

dumpTAndA(mainHerd, fio); // print the tunes and actions to fio

// plot tunes to screen, for those with the PLPLOT package built in:

scatterplot = True;

xyPlot(yTune, xTune, xLabel="nu-x", yLabel="nu-y", mark=dot);

doTurn(999); // do more turns without calculating the tunes.

doTurn(1000); // do 1000 turns of the mainHerd

useSimpleTuneCalc=True; // Only get the fractional tune

for(_i=1; _i <= 10; _i++) // Average tunes over 10 turns.

// Note: _i is a built-in SuperCode Integer

{

startTuneCalc(); // start calculating tunes

doTurn(1); // calculate the tunes over one turn.

stopTuneCalc(); // stop calculating the tunes, and tally the

} // tunes for each particle.

WARNING: Do not try to calculate the tune with closed orbit bumps on, unless the closed orbit bumps to not have any transfer matrices between them. For example, the following sequence is OK:

The following sequence would give incorrect tunes:

This module includes capabilities for creating particles from specified distributions. It also contains a Foil node class. One can generate a specified number of macro-particles at the start of a run and track them, or automatically inject a specified number of macro-particles at the foil at each turn. Also foil scattering can be used.

Void addXInitializer(const String &n, Subroutine subX)

Void addYInitializer(const String &n, Subroutine subY)

Void addLongInitializer(const String &n, Subroutine subL)

x0Inj = 30.; xP0Inj = 0.; // horizontal center of the injected

// distributiom (mm, mrad)

alphaXInj = 0.5;betaXInj = 10.; // lattice parameters for the injected

MXJoho = 3; // binomial factor.

addXInitializer("Truncated Gaussian X", JohoXDist);

It is possible to add tails to the "Joho" distributions. For example the following additional specifications:

xTailFraction = 0.3; // 30% of the particles are in the "tail"

xTailFactor = 2.2; // The "tail" dist is

specifies that 30% of the particles created will have an emittance 2.2 times that of the nominally specified value (with epsXLimInj). The vertical distributions can be set up similarly by substituting "y" for "x" above. There is an option to use a longitudinal Joho distribution also, but here the distribution extent is determined by specifying the limiting longitudinal phase angle (phiLimInj in degrees) and the limiting energy spread (dELimInj in GeV). For example:

MLJoho = 1; // uniform longitudinal.

A UniformLongDist() routine supplies samples from a uniform longitudinal distribution in energy and phase. Also the GULongDist can be used for longitudinal distributions which are uniform in f and gaussian (optionally truncated) in energy. See the Injection.mod and Injection.cc files for a complete description of the built-in sampling routines.

Note that the user can provide her own, say, horizontal distribution sampling routine in an input script file, and simply point to it with the "addXInitializer" call, without recompiling. For example,

The Injection module contains a Foil class which includes information about the foil. Generally a Foil node will be at the beginning of the ring, but it doesn’t have to be. A Foil node can be included with a call to the routine:

Here name is a name of the node, order is the _oindex Node value, xMin(xMax) is the minimum (maximum) horizontal foil extent in mm, yMin(yMax) is the minimum (maximum) vertical foil extent in mm, and thick is the foil thickness (mg/cm²). For example, the call:

inserts a Foil node at point 2 in the ring, with 20 < x(mm) < 30, and 20 < y(mm) < 100, and with a thickness of 300 (mg/cm²). Each time the Foil node is encountered the routine InjectParts(nMacrosPerTurn) is called. This routine will pick nMacrosPerTurn macro-particles from the prescribed distributions (see above), and add them to the mainHerd ensemble until a maximum of nMaxMacroParticles macro-particles have been injected.

In the _nodeCalcutor routine, particles are injected as described above(if the mainHerd is being pushed through the ring). Also if foil scattering is active, some beam energy dependent quantities are calculated. In the _updatePartAtNode routine, foil traversal events are tallied for each macro-particle. Also if foil scattering is active, each macro-particle is scattered if it intersects the foil.

If the variable useFoilScattering == 1 (or True), foil scattering is modeled, using the ACCSIM single scattering model described in Ref. 2. In this case the following quantities are used:

showFoil(fio);

where fio is a defined Ostream such as "cout" for the console. One can manually cause the foil parameters to be updated with the call:

miscFoilCalcs();

and subsequently dump specific foil information to a stream. A common foil quantity of interest is avgFoilHits, which is the total number of foil traversals divided by the total number of macro-particles. See the file Injection.mod for more information on foil parameters.

A set of macro-particles for the mainHerd can be created using the initializtion routines discussed above without using a foil. The addXInitializer, addYInitializer, and addLongInitializer routines are called as above to specify the distributions you want to sample from. Then, for example, calling

nMaxMacroParticles = 10000;

will add 10000 macro-particles to mainHerd , which can subsequently be tracked. Be sure you have first specified which distribution functions to use though (see above).

The closed orbit of the ring can be artificially altered anywhere in the Ring by introducing an ideal bump. The bump positions can also be a function of time. This is typically done directly before (and after) a Foil node to facilitate painting of the ring phase space distributions. The node sub-class used to contain the bumps is the IdealBump. WARNING: Bumps should be added in pairs: an "up" bump, and a "down" bump! An IdealBump node can be added with the routine:

Here order is the _oindex value specifying where in the ring the bump is. sub is the name of a routine that will specify the bump values as a function of time, and upDown is a switch indicating whether the bump is moving the closed orbit up (==1) or down (!=1). Note that the same routine should be specified by "sub" when adding both the "up" and "down" bumps, to ensure no net movement of the closed orbit. The routine specified by sub, which is called to provide the bumps as a function of time is expected to set the variables:

xIdealBump - "The x value of the ideal bump at a point in time (mm)",

xPIdealBump - "The x prime of the ideal bump at a point in time (mrad)",

yIdealBump - "The y value of the ideal bump at a point in time (mm)",

yPIdealBump - "The y prime of the ideal bump at a point in time (mrad)"

as a function of the variable time [msec]. These variables are then used to modify the closed orbit parameters, and accordingly the values of x,x’,y,and y’ of each macro-particle.

An exponentially decaying bump profile is provided in the routine eFoldBump. It assumes profiles of the form

where x_0(f) is the initial (final) x bump position, D_t is the total bump period, and t_x is a normalized time constant. The x’, y and y’ bumps are specified in a similar manner in the eFoldBump() routine. The variable names for these quantities are described in the Bump.mod file. For example,

Similar notation is used for the vertical bump setup with x(X) replaced by y(Y). If times > tBumpF are used, the final bump values are used (i.e, xBumpF, xPBumpF, yBumpF, yPBumpF).

Using the eFoldBump2 routine. For example:

Similar notation is used for the vertical bump setup with x(X) replaced by y(Y).

The closed orbit bump coordinates can be prescribed by linear interpolating between input data points using the interpolateBumps routine. The procedure is to first size and fill a set of vectors containing the bump points to use for interpolation. Then insert a pair of up/down bumps which use the interpolateBumps routine to scale the ideal bump coordinates. The following example illustrates this procedure for a case with two points for interpolation (i.e. a linear bump):

The user can add a routine to specify any sort of bump profile in the input script file, and simply refer to this routine in the addIdealBump call. For example the following set of commands would create and activate the use of trigonometric bump forms :

This node is provided to add RF cavities. The Node sub-class for this purpose is the RFCav class, which inherits the base class AccelerateBase. For this class of RF Cavity the synchronous phase is always assumed to be 0. The general capability is to provide the voltage as the sum of an arbitrary number of harmonics, and as a function of time. The user must specify the number of harmonics to be used, vectors containing the amplitudes and phases of each voltage harmonic, and (if the voltage is ramped with time) a routine providing their waveforms. The RF Voltage for a cavity is assumed to be of the form:

where n is the number of RF harmonics used, V_i is the i’th harmonic voltage (kV), h_i is the i’th harmonic number, f_i is the i’th harmonic phase (rad) and t is the time (msec). A steady state RF cavity with an arbitrary number of harmonics can be added with the routine:

The first argument is a name for the node, the second argument is the order number where this RF cavity appears in the Ring, the third argument is the number of harmonic components the RF Voltage waveform has, and the fourth, fifth and sixth arguments are references to Real Vectors containing the RF voltage (kV), harmonic number, and phase offset(rad) of each harmonic component of the RF voltage, respectively. The RealVectors referenced in this call can be created, and initialized, on the fly prior to this call. An example of this is:

When the calculation gets to the accelerating node, the "_nodeCalculator" first calls the specified routine to update the field and RF voltage. The user can create some vectors to hold the RF voltages and phases and write his own routine to scale these parameters in the driver shell. The field variable that should be provided here is called "Accelerate::BSynch" and the independent time variable is "Ring::time" .

However, there are several built-in capabilities for modeling commonly used accelerating cycles. One is to assume sine waveforms for the dipole and interpolate RF voltages from an input set of data. This is done by using the InterpolateV routine. Here the dipole filed is assumed to be of the form:

The user must specify the "fixed" field level (B₀, in T with variable BSynch0), the "varying" field level (B₁, in T with vaiable BSynch1) and the ramp frequency (Hz) with the variable BSynchFreq. The RF voltage is assumed to be of the form

The voltage at each node is calculated by interpolating between data read in before the run starts. The A routine getRampedV(String) is provided to read in this data. The argument here is the name of the file to read, and the file format is expected to be of the form:

• the first line contains an integer specifying the number of RF harmonics (n)
• each subsequent line contains the following white-space delimited parameters: the time t (msec), V₁(t), f₁(t), … V_n(t), f_n(t)

The InterpolateV routine puts the interpolated values of the RF voltages and phases into predefined vectors RFVolts and RFPhase, and the number of RF harmonics in nRFHarmonics, so be sure to specify these in the call to addRampedBAccel.

The input file SNSCosForm1 must be lying around, and here what it looks like:

This case is similar to that above case except that the B field is also calculated by interpolating between input data instead of assuming a cos waveform. In this case the InterpolateBV routine is specified in the call to addRampedBAccel . Also routine (getRampedBV(String)) is provided for use with this option that will read in data to interpolate both B and V. It expects an argument with the filename of a file containing the following format:

• the first line contains an integer specifying the number of RF harmonics (n)
• each subsequent line contains the following white-space delimited parameters: the time t (msec), B(T), V₁(t), f₁(t), … V_n(t), f_n(t)

The InterpolateV routine also puts the interpolated values of the RF voltages and phases into predefined vectors RFVolts and RFPhase, and the number of RF harmonics in nRFHarmonics, so be sure to specify these in the call to addRampedBAccel.

The input file SNSWaveForm5 must be lying around, and here what it looks like:

To get output about acceleration, try using showAccelerate(Ostream) . This routine dumps the time (msec), synchronous particle kinetic energy (GeV), the bunch factor, the relativistic beta, the synchronous phase (deg), the primary harmonic RF voltage, the syncrotron frequency, the bucketHeight (eV), the bunch height (eV), the bucket area (eV-sec), the bunch area (eV-sec) and the maximum dp/p (%) (all on a single line). Here’s an example of its use:

An FFT longitudinal space charge kick node can be added anywhere in the ring with the addFFTLSpaceCharge routine. This routine takes 6 arguments:

Also the number of longitudinal bins to use is specified independently as the integer nLongBins. The wall impedance input vector for argument 3 has values for each harmonic number, and should be dimensioned to at least the number of longitudinal bins/2 and is in units of Ohms. The real part of element i contains the resistive impedance in Ohms /(harmonic number i) , and the imaginary part of the vector contains the reactive part of the impedance (Ohms) /(harmonic number i). Setting this vector = 0, is equivalent to ignoring wall impedance effects.

The pair-wise sum transverse space charge method simply calculates the Coulomb force on one particle by summing the force over all other particles. A smoothing parameter (e_s) is included in the calculation as an additional length used in calculating the particle separation distances. Typically one uses a length very small compared to the beam transverse size, in which case it only reduces the Coulomb force between near-neighbors. This smoothing parameter can prevent spurious kicks. No binning is done with this scheme. This scheme is simple, but requires ~ (n_p)² operations to calculate the kicks, where n_p is the number of macro-particles. This is exceedingly slow, and has only been used for checking other faster methods. It is not recommended for normal usage, but none-the-less may be implemented by:

An aperture node can be placed anywhere in the ring to either (a) count particle hits beyond a certain position (transparent), or (b) remove macro-particles from the tracking if they extend beyond a certain position (non-transparent). The aperture position in the ring is determined by its node index value. Generally the mechanism for determining what index value to use is to first read in the transfer matrix set. An aperture can be placed after or before any of the transfer matrix nodes. If you are not sure which transfer matrix node corresponds to the longitudinal ring position you want to put the aperture at, read in the transfer matrix and do a "showRing(cout)" and a "showTransMatrix(cout)" to help figure out the node index where you would like to place the aperture. As each transfer matrix index is incremented by 10 from the previous transfer matrix index, just pick an index value between the two transfer matrices you are interested in. You can always do another "showRing(cout)" after adding the aperture node to see if you have it right.

At some point you may want to see what the aperture has collected. The showApertures routine will dump some information about all apertures in the ring:

This output includes the aperture dimensions and how many particles have hit it. It is also possible to get a dump of all the lost particles for a herd with the routine Particles:: dumpLostParts . For example:

The first line of this file contains a description of the information dumped for each lost particle. Then a separate line is printed for each lost macro-particle containing the phase parameters x (mm), x’ (mrad), y (mm) , y’ (mrad), f (rad), DE (GeV), the longitudinal ring position where the macro-particle was lost (m), the node number where the macro-particle was lost, and the turn number when the macro-particle was lost.

(1) cout - long buffered output to the screen,

(2) cerr - short buffered output to the screen, or

3. any user defined stream.

A user defined stream called "fio" to a file called "fileout" can be created on the fly by

This stream will delete any previously defined file called "fileout". The command

is similar, but will append the prescribed output to whatever exists (if anything) in a file called "fileout". See Reference 1 for more information on general inputting/outputting information from the Shell.

The string runName can be defined at the beginning of a run. It is used in the showStart output and on the plots (see below) for labeling output.