__
__

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.

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

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

Thu Dec 3 17:27:26 JST 1998