BEAM

    Defines a beam. (Append particles to the existing list.) There are two ways to create a beam, one by specifying the Twiss parameters, etc, and the other by reading data from a file.

Note that the beam is defined on a plane s=constant, rather than on the t=constant plane (snap shot). Thus, e.g., the bunch length is a spread in t rather than in s. BEAM RIGHTLEFT, KIND=k, AN=N, NP=, E0=, [TXYS=(t,x,y,s),] BETA=(,), [ALPHA=(,),] [EMIT=(,),] [SIGT=,] [SIGE=,] [GCUT=(,),] [GCUTT=,] [GCUTE=,] [GAUSSWEIGHT=,] [ELLIPTIC,] [TUNIFORM,] [EUNIFORM,] [SLOPE=(,),] [CRAB=(,),] [ETA=(,),] [ETAPRIME=(,),] [ESLOPE=,] [XYROLL=,] [SPIN=(,,),] ;

RIGHTLEFT

Specify whether the beam is right-going or left-going.

k

Particle species. 1 for photon, 2 for electron, 3 for positron. If you cannot remember these codes, you can do
SET photon=1, electron=2, positron=3 ;
BEAM RIGHT, KIND=electron

N

Number of real particles.

Number of macro-particles.

Beam energy. (eV)

t,x,y,s

Location of the reference point and the time when the beam center comes there. In units of meter. This is the point where the Twiss parameters are to be defined. Default=(0,0,0,0).

,

Beta functions (m).

,

Alpha functions. Default=(0,0). The sign of is positive when the beam is going to diverge, whichever the beam is right-going or left-going.

,

R.m.s geometric emittance (radm).   Deafault=(0,0).

R.m.s. bunch length (m). Default=0.

Relative r.m.s. energy spread. Default=0.

,,,

Gaussian tail cutoff in units of corresponding sigmas. The default values are 3.0 for and , and 2.5 for and . (For transverse variables the cut off is done in the action variable, which means (i=x,y).)

0 or 1. There is a subtle problem on how to take into account the Gaussian cut off (,,) in the macro-particle weight. CAIN throws away the random numbers outside this range and generates exactly macro-particles. This means some fraction outside the region is moved inside. Therefore, if the simple weight is assigned to macroparticles (), the effective particle density would become slightly larger than the physical value, although the sum of the weight is equal to N. If one is interested in the quantities related to the density (such as luminosities), this would cause an overestimation.
When (default), a correction factor is multiplied to the weight such that the real particle density becomes correct. In this case, the sum of the macro-particle weights is less than N. (When the default n's are adopted, for example, the correction of the weight amounts to 3.4%.) In most cases, will be better.

ELLIPTIC

Uniform transverse distribution.   (Default is Gaussian.) (x,y) distribution is a uniform ellips with radii , where (j=x,y). In this case the beam is parallel, in spite the finite emittances are specified. The emittance and beta are only used to define . ALPHA and GCUT are not used.

TUNIFORM

Uniform t-distribution.  (Default is Gaussian.) The full length is . GCUTT is not used.

EUNIFORM

Uniform E-distribution. (Default is Gaussian.) The full relative energy spread is . GCUTE is not used.

,

Angle offset (radian). The right and left-going beams have the same sign of slope when there is a crossing angle . Default=(0,0).

,

Crab angle  . (radian). Positive when the bunch tail has larger x (y).
When the full crossing angle in the horizontal plane is and this is to be compensated by the crab angle, the SLOPE and CRAB parameters should be SLOPE=, CRAB=, for both right-going and left-going beams.
If you are not confident, after beam definition try, for example,
D RIFT T=t0-dt ;
P LOT SCAT, H=S, V=X,
H SCALE=(smin,smax), VSCALE=(xmin,xmax),
H TITLE='S(m)', VTITLE='X(m)' ;
D RIFT T=t0 ;
P LOT SCAT, NONEWPAGE, H=S, V=X,
H SCALE=(smin,smax), VSCALE=(xmin,xmax),
D RIFT T=t0+dt ;
P LOT SCAT, NONEWPAGE, H=S, V=X,
H SCALE=(smin,smax), VSCALE=(xmin,xmax),
with appropriate definitions of t0, smin etc. The DRIFT command transports the beam to the plane t=constant (snap shot). NONEWPAGE operand suppresses page break so that the (s,x) profiles at different times appear on the same page.

Eta function (m).

Derivative of eta function.

Coherent energy slope from bunch head to tail (1/m).

Roll angle of the beam in the x-y plane. (radian)

,,

Polarization vector.   Default=(0,0,0). Note the sign of for left-going particles. In the case of photon beams, these are the Stokes parameter .   The basis vector of the Stokes parameter is where is the unit vector along the particle momentum, is the unit vector along , and .

See Sec.5.3 for rigorous definitions.

BEAM FILE='file_name', [N=,] ;

File reference number.

file_name

Existing file name. Must be enclosed by apostrophes. Either full path or relative path. Note that CAIN is run in the directory cain/exec.
When file_name is specified, the input file reference number is ignored. The file is opened with the reference number 99 and is closed after reading.

Maximum number of macro-particles to be read in from file. If 0, non-active. Default=0.

Reading file stops when one of the following conditions are satisfied.

1. Reached (when ).
2. A file line found whose first three characters are `END'.
3. End_of_file detected.

In the present version, only the standard format  is accepted. It is the format created by the following FORTRAN statement.

    WRITE(*,'(I2,I6,1X,A4,1P12D20.12)') KIND,GEN,NAME,WGT,
   1     (TXYS(I),I=0,3),(EP(I),I=0,3),(SPIN(I),I=1,3)

Here, NAME is blanck unless the particle is a test particle or a lost particle or an incoherent-pair particle, WGT is the number of real particles expressed by one macro-particle and GEN is an integer expressing the generation   (1 for the initial particles, 2 for secondaries, etc.). SPIN is the polarization vector  for electron/positron and the Stokes parameter  for photons.

To modify the file data (shift of origin, rotation, etc) can be done to some extent by using the command LORENTZ .

Definition of test particles can also be done by BEAM command. One BEAM command is needed for each test particle. The number of test particles times the number of PUSH time steps must be less than 5000 (parameter MTSTP in the file 'cain/source/include/tstpcm.h'). Test particles do not create a field but feel a field. They do not interact with lasers and do not create particles (such as beamstrahlung, incoherent pair, etc). Therefore, `test photon' does not make sense.

Coordinates and energy-momentum of test particles can be refered to at any time by functions TestT, etc. See Sec.2.5.

BEAM TESTPARTICLE, NAME=n,'name', KIND=k, [TXYS=(t,x,y,s),] P=(,,), ;

n,name

A test particle must have a name, consisting of upto 3 characters. The `name' (left-adjusted) must be enclosed by a pair of apostrophes. It can also be specified by an integer , which is converted to a decimal character string (right-adjusted). Thus, NAME=1 and NAME=' 1' is identical. (In the computer, one character `T' is added at the top. Thus, NAME=999 becomes T999.)

k

Particle specie.

t,x,y,s

Location of the test particle (m).

3-momentum (eV/c). must not be zero (i.e., either right-going or left-going).

1ex

What is actually defined by the particle variables (t,x,y,s) and is not a particle at a definite space-time coordinate, but rather is a straight trajectory (a world line) which passes the space-time point (t,x,y,s). At the time when the PUSH  command is executed, they are first pulled to the intercept on plane, where is the starting time of the PUSH loop.

When a BEAM command is inserted within a PUSH loop, the particles are taken to the corresponding time t=Time . However, it is safer not to insert BEAM command within PUSH loop unless you know well what is going on. One exception is the test particles, which in some cases you want to create during a PUSH loop (for example to see the behavior of a low energy particle created during interaction). If you do not want them to be time-shifted in such cases, you can define the TXYS operand as TXYS=(Time,), where Time is the PUSH running time (`present time').