next up previous contents index
Next: LASER Up: Commands Previous: SET


    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 RIGHTtex2html_wrap_inline7312LEFT, KIND=k, AN=N, NP=tex2html_wrap_inline7358, E0=tex2html_wrap_inline7362, [TXYS=(t,x,y,s),] BETA=(tex2html_wrap_inline7376,tex2html_wrap_inline7378), [ALPHA=(tex2html_wrap_inline7382,tex2html_wrap_inline7384),] [EMIT=(tex2html_wrap_inline7388,tex2html_wrap_inline7390),] [SIGT=tex2html_wrap_inline7394,] [SIGE=tex2html_wrap_inline7398,] [GCUT=(tex2html_wrap_inline7402,tex2html_wrap_inline7404),] [GCUTT=tex2html_wrap_inline7408,] [GCUTE=tex2html_wrap_inline7412,] [GAUSSWEIGHT=tex2html_wrap_inline7416,] [ELLIPTIC,] [TUNIFORM,] [EUNIFORM,] [SLOPE=(tex2html_wrap_inline7426,tex2html_wrap_inline7428),] [CRAB=(tex2html_wrap_inline7432,tex2html_wrap_inline7434),] [ETA=(tex2html_wrap_inline7438,tex2html_wrap_inline7440),] [ETAPRIME=(tex2html_wrap_inline7444,tex2html_wrap_inline7446),] [ESLOPE=tex2html_wrap_inline7450,] [XYROLL=tex2html_wrap_inline7454,] [SPIN=(tex2html_wrap_inline7458,tex2html_wrap_inline7460,tex2html_wrap_inline7462),] ;

Specify whether the beam is right-going or left-going.
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 tex2html_wrap_inline7230
Number of real particles.
Number of macro-particles.
Beam energy. (eV)
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 tex2html_wrap_inline7492 is positive when the beam is going to diverge, whichever the beam is right-going or left-going.
R.m.s geometric emittance (radtex2html_wrap_inline7234m).   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 tex2html_wrap_inline7402 and tex2html_wrap_inline7404, and 2.5 for tex2html_wrap_inline7408 and tex2html_wrap_inline7412. (For transverse variables the cut off is done in the action variable, which means tex2html_wrap_inline7520 (i=x,y).)
0 or 1. There is a subtle problem on how to take into account the Gaussian cut off (tex2html_wrap_inline7402,tex2html_wrap_inline7404,tex2html_wrap_inline7408) in the macro-particle weight. CAIN throws away the random numbers outside this range and generates exactly tex2html_wrap_inline7358 macro-particles. This means some fraction outside the region is moved inside. Therefore, if the simple weight tex2html_wrap_inline7538 is assigned to macroparticles (tex2html_wrap_inline7540), 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 tex2html_wrap_inline7544 (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 tex2html_wrap_inline75503.4%.) In most cases, tex2html_wrap_inline7544 will be better.
Uniform transverse distribution.   (Default is Gaussian.) (x,y) distribution is a uniform ellips with radii tex2html_wrap_inline7556, where tex2html_wrap_inline7558 (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 tex2html_wrap_inline7566. ALPHA and GCUT are not used.
Uniform t-distribution.  (Default is Gaussian.) The full length is tex2html_wrap_inline7570. GCUTT is not used.
Uniform E-distribution. (Default is Gaussian.) The full relative energy spread is tex2html_wrap_inline7574. 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  tex2html_wrap_inline7584. (radian). Positive when the bunch tail has larger x (y).
When the full crossing angle in the horizontal plane is tex2html_wrap_inline7590 and this is to be compensated by the crab angle, the SLOPE and CRAB parameters should be SLOPE=tex2html_wrap_inline7592, CRAB=tex2html_wrap_inline7592, for both right-going and left-going beams.
If you are not confident, after beam definition try, for example,
D RIFT T=t0-dt ;
H SCALE=(smin,smax), VSCALE=(xmin,xmax),
H TITLE='S(m)', VTITLE='X(m)' ;
D RIFT T=t0 ;
H SCALE=(smin,smax), VSCALE=(xmin,xmax),
D RIFT T=t0+dt ;
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 tex2html_wrap_inline7462 for left-going particles. In the case of photon beams, these are the Stokes parameter tex2html_wrap_inline7622.   The basis vector of the Stokes parameter is tex2html_wrap_inline7624 where tex2html_wrap_inline7626 is the unit vector along the particle momentum, tex2html_wrap_inline7628 is the unit vector along tex2html_wrap_inline7630, and tex2html_wrap_inline7632.

See Sec.5.3 for rigorous definitions.

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

File reference number.
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. tex2html_wrap_inline7358 Reached (when tex2html_wrap_inline7650).
  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,tex2html_wrap_inline7312'name', KIND=k, [TXYS=(t,x,y,s),] P=(tex2html_wrap_inline7676,tex2html_wrap_inline7678,tex2html_wrap_inline7680), ;

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 tex2html_wrap_inline7298, 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.)
Particle specie.
Location of the test particle (m).
3-momentum (eV/c). tex2html_wrap_inline7680 must not be zero (i.e., either right-going or left-going).


What is actually defined by the particle variables (t,x,y,s) and tex2html_wrap_inline7702 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 tex2html_wrap_inline7706 plane, where tex2html_wrap_inline7708 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,tex2html_wrap_inline7230), where Time is the PUSH running time (`present time').

next up previous contents index
Next: LASER Up: Commands Previous: SET

Toshiaki Tauchi
Thu Dec 3 17:27:26 JST 1998