\documentstyle[titlepage,a4]{article}

\topmargin -1.5cm

\oddsidemargin  0.5cm
\evensidemargin 0.5cm

\textheight 23cm
\textwidth  16cm

\newenvironment{parameternote}%
{\begin{list}{note--\arabic{note}}%
{\usecounter{note}\setlength{\rightmargin}{\leftmargin}}}{\end{list}}

\newenvironment{parameterlist}%
{\begin{list}{}{%
\setlength{\leftmargin}{60pt}%
\setlength{\labelwidth}{60pt}%
}}%
{\end{list}}

\input{fel.inc}

\title{ELFIN V7 Users Manual}
\input{author.inc}

\date{\today}

\begin{document}
\maketitle
ELFIN is the code which simulates 
three dimensional time-independent free electron lasers. 
\\
ELFIN assume input and output are
standard input and standard output, respectively. 
To run ELFIN with 'inputfile' for input and 'outputfile' for output type 
\begin{verbatim}
 % ELFIN < 'inputfile' > 'outputfile'
\end{verbatim}

\section{Structure of Input Files}

A input file is composed of three parts. Those are

\begin{itemize}
  \item  Part 1 : Numerical constants. \\
The numerical constants used in  ELFIN are defined. 
Those are the number of grid points and the number of superparticles.

  \item  Part 2 : A configuration of an FEL system.  \\
The configuration of the FEL system is defined. 
This is the list of names of elements which the component an FEL system, such
as amplifiers, mirrors, free spaces for the laser field, etc.

  \item Part 3 : The definitions of element \\
Elements used in part 2 are defined with their parameters.

For example,  if the element name 'FELAMP' is used in part 2 as 
an FEL amplifier, 
then in  part 3, the element 'FELAMP' should has type 'FEL'
  which is an FEL amplifier.  

The parameters for the FEL amplifier 'FELAMP',
such as
length, period, strength of the wiggler,
are also given in this part.

\end{itemize}

The strings written with {\tt typewriting characters} are 
a part of an input file.

Input files are read with list input {\tt READ(*,*)} in Fortran77.


Lines represented with {\tt COMMENT} appear below 
are ignored by ELFIN.  
This line can be used as comment lines.

The structure of input field is
two comment lines plus one line for parameters.

%********************************

\section{Part 1 : Numerical constants}

The numerical constants are defined.
Those are the number of grid points in a transverse space $(x,y)$ and 
the number of superparticles which are used instead of a huge number 
of electrons in real FEL systems.

\subsection{Format}
\begin{verbatim}
COMMENT
COMMENT
Na   Np 
\end{verbatim}

\subsection{Parameters and Variable Types}

\begin{parameterlist}
\item[{\tt Na}] INTEGER \\
ELFIN uses {\tt Na}$\times${\tt Na} square grid points 
in the transverse space $(x,y)$. 
{\tt Na} must be $2^n$  where n is positive integer,
which is for FFT,
and must not exceed the value {\tt nam} 
which is defined in the file paramsv.inc.


\item[{\tt Np}] INTEGER \\
The number of superparticles. 
This value must not exceed the value {\tt npm} which is defined in the
file paramsv.inc.

\end{parameterlist}

If users want to change {\tt nam } and {\tt npm },
 change the values {\tt nam } and {\tt npm }
  in the file 'paramsv.inc' and complile ELFIN.

%********************************

\section{Part 2 : Configuration of an FEL system}

The configuration of an FEL system is defined. 

\subsection{Format}
\begin{verbatim}
  COMMENT    
  COMMENT    
  Nrep        
  COMMENT     
  COMMENT     
 'name1  name2  name3  ... ' 
\end{verbatim}

\subsection{Parameters and Variable Type} 
\begin{parameterlist}
 \item[{\tt Nrep}] INTEGER  \\

If there exist  {\tt BEGIN}  and {\tt END} in the configuration list
 shown below, 
ELFIN repeats the elements between them {\tt Nrep} times. 

  This can be used in a case for oscillators.

\item[{\tt 'name1 name2 name3  \dots'}] CHARACTER*1024 \\

The list of element names which compose an FEL system. 
The order of the element names 
 is along the propagation of the laser field and the electron beam. 

This list is read as single string which surrounded with  \' . 
Each element name is delimited with spaces.

The length of element names must be less than 6 characters. 
 
The last element name in the list must be of the type {\tt TERM}. 
ELFIN notices that this element is the last element in the list.

\end{parameterlist}

%********************************

\section{Part 3 :  Definitions of Types and Parameters for Elements}

For each element name used in part 2, 
its type and parameters are defined.
The type of the last element in this part must be {\tt TERM}. 

The order of the name is not restricted except the type {\tt TERM}.

Each definition of elements has the format below.

\subsection{Format}

\begin{verbatim}
  COMMENT 
  COMMENT 
  'name'  'type'  
  COMMENT                                                           
  COMMENT                                                           
  parameter11 parameter12  ...
  COMMENT                                                           
  COMMENT                                                           
  parameter21 parameter22  ...
   .
   .
   .
\end{verbatim}

\subsection{Parameters and Variable Type} 
\begin{parameterlist}
 \item[{\tt 'name'}]  CHARACTER*6  \\   a name of the element
 \item[{\tt 'type'}]  CHARACTER*6  \\   a type of the element 
 \item[{\tt parameter\#}] data type is depends on parameter \\
                        parameters for the element 
\end{parameterlist}

\section{Types and Parameters of Elements}
The types which can be used in part3 are listed below.

\begin{tabular}{ll}
 {\tt FEL}    & A free electron laser amplifier \\
 {\tt ESOURC} & An electron source which creates superparticles \\
 {\tt AINIT}  & An initial laser field \\
 {\tt AFREE,ADRIFT}  & A free space for a laser field \\
 {\tt MIRROR} & A mirror \\
 {\tt EDRIFT} & A drift space for an electron beam \\
 {\tt TERM}   & Terminator of the element list 
\end{tabular}

.
The formats for the parameters of these types are mentioned below.
ELFIN uses SI units for the parameters.

The widths of calculation areas of the elements 
which are neighborhood each other must have the same values.

\section{Type :  FEL}

A free electron laser amplifier is simulated.

The output is the laser power, gain and 
the histogram of the laser field and the electron beam.

\subsection{Format}

\begin{verbatim}
================================================================================
<Element name> <Element Type>
   'Name'          'FEL'
--------------------------------------------------------------------------------
<width of the calculation area>
    Width 
--------------------------------------------------------------------------------
<# of sampling to z axis> <# of steps to z axis>
    Nsmp                        Nz   
---------wiggler parameters-----------------------------------------------------
<Length> <Period>    <Strength>       <transverse dependencies>   <WigglerType>
 Length     lw    (Re(aw0),Im(aw0))      hx2         hy2          WigType  
--------------------------------------------------------------------------------
<Wiggler Number> --<Wiggler Parameters (Not used in this version)>--------------
  WigNum             wigpar(1)  wigpar(2)  wigpar(3)  wigpar(4) 
-------Spatial filter parameter-------------------------------------------------
<width of filtering> <# of times of splining>
   fltwid                      Nspln      
-------- Laser Field  ----------->|<---- Particles ----------------------------
-<histogram>----<list of values>--|--<histogram>--<values>----
  ahswx  ahswy   ameswx ameswy       phswx  phswy  parsw
\end{verbatim}

\subsection{Parameters}

\begin{parameterlist}
\item[{\tt Width}] REAL    \\ 
           Width of the calculation area $[m]$ in $(x,y)$ space. 
\item[{\tt Nsmp}] INTEGER  \\  Sampling step to output.
            ELFIN outputs every {\tt Nz}/{\tt Nsmp} step. 
\item[{\tt Nz}] INTEGER    \\ 
            The number of step to divide an FEL system along $z$ axis. 
            The wiggler is equally divided to $N_z$ peacies. 
            For positive value of this,
              the corrector step \cite{theory} 
              in subroutine feladv for
                particles and fields is applied twice.
            For Negative value,
              the corrector step is applied once.
\item[{\tt Length}] REAL \\ 	The length of the wiggler $[m]$.
\item[{\tt lw}] REAL  \\ 	The Period of the wiggler $[m]$.
\item[{\tt Re(aw0),Im(aw0)}] REAL \\ 
            The amplitude of a complex dimensionless vector potential
           of the wiggler $( 99.8  B_{W}[T](r.m.s.)\lL[m] )$.
            For an usual wiggler, $Im(aw0) = 0$.  
\item[{\tt hx2}] REAL\\
    The coefficient of the x dependence of the wiggler field $[m^{-2}]$.
    $hx2 = h_x^2$.
\item[{\tt hy2}] REAL  \\
    The coefficient of the y dependence of the wiggler field $[m^{-2}]$. 
    $hy2 = h_y^2$.

    $aw(x,y) = 
    aw0\left(1 + \frac{1}{2}h_x^2  x^2 +\frac{1}{2} h_y^2  y^2\right)$ ,
       $h_x^2 + h_y^2 = k_w^2$.
 
\item[{\tt WigType}] CHARACTER*6  \\  A type of the wiggler
 For the static field wiggler, it is set to be {\tt 'STATIC'} and 
     for  an electromagnetic wiggler, it is set to be {\tt 'OPTIC'}.

\item[{\tt WigNum}] INTEGER  \\
   It is used to specify which subroutine for a wiggler field is to be used in
this element. In this version, an usual planer wiggler is assigned to be 1.

\item[{\tt wigpar(1-4)}] REAL \\ 
   Data for wigglers.
   Users can use these data in their own subroutine for a wiggler 
   specified in {\tt WigNum}.

\item[{\tt fltwid}] REAL   \\  
   The width for a spatial filtering $[m]$ .

\item[{\tt Nspln}] INTEGER  \\  
  The order of the splining of the spatial filtering.

\item[{\tt ahswx},{\tt ahswy}] INTEGER  \\
Switches to control the output of the histograms 
of the strength of the laser field 
along the x axis and the y axis,respectively. 
1 is on  and 0 is off.

\item[{\tt ameswx},{\tt ameswy}] INTEGER\\ 
Switches to contorol numerical output of the laser field 
along the x axis and the y axis , respectively.
1 is on  and 0 is off.

\item[{\tt phswx},{\tt phswy}] INTEGER\\
Switches to control the histogram of the distribution of the particles 
along the x axis and the y axis, respectively.
1 is on  and 0 is off.

\item[{\tt parsw}] INTEGER\\ 
Switch to controls numerical output of the parameters of the particles.
1 is on  and 0 is off.

\end{parameterlist}

\subsection{Parameters}

\begin{itemize}
\item {\tt aw0 },{\tt hx },{\tt  hy }\\
It is assumed that the dimensionless vector potential of the wiggler field
   has the form of
\[
a_{W}(x,y,z) =
 a_{W0}(1 + \frac{1}{2}{h_x}^2 x^2  + \frac{1}{2}{h_y}^2 y^2 ) 
\]
.

\item {\tt fltwid},{\tt Nspln} \\
{\tt fltwid } is  the size for the spatial filtering which is applied 
to the laser field at each step.
{\tt Nspln } is the order of splining at the spatial filtering.

 The spatial filtering is off.
if {\tt fltwid} is larger than {\tt width } or {\tt Nspln} is 0,

{\tt WigNum } : 
   user subroutine wiggl\# and bexf\# is called 
   for the wiggler and the external magnetic field, respectively. 
   \# is the number specified by WigNum. 
  For example, 
     if {\\t Wignum} = 1, then subroutines wiggl1 and bexf1 is called 
        and wiggl1 and bexf1 are preinstalled in ELFIN as 
       a planer and constant field undulator 
        and no exteranl magnetic field.
\end{itemize}

\section{Type : ESOURC}

An initial electron beam is simulated.

This module generate superparticles according to the assumed distribution.
ELFIN treats small number of the superparticles 
instead of  huge number of the real electrons which interact with the 
laser field in actual FEL because of the limitation of cpu time and 
memory. 

\subsection{Format}

\begin{verbatim}
================================================================================
<Element name>      <Element Type>
   'Name'             'ESOURC'
--------------------------------------------------------------------------------
<Peak Current>
   icurr
--------------------------------------------------------------------------------
<Ave. of Gamma>   <Spread of Gamma>  
   gmave0              gmspd0       
--------------------------------------------------------------------------------
<Distribution Form>
   gmdst
--------------------------------------------------------------------------------
<Ave. of X> <Spread of X> <Ave. of BetaX> <Spread of BetaX>
   xpave0       xpspd0         bxave0           bxspd0
--------------------------------------------------------------------------------
<Ave. of Y> <Spread of Y> <Ave. of BetaY> <Spread of BetaY>
   ypave0      ypspd0          byave0           byspd0 
--------------------------------------------------------------------------------
<Distribution Form>
   trsdst
--------------------------------------------------------------------------------
<# of points on zeta axis>
   NL
--------------------------------------------------------------------------------
<seed of random number>   <renew the seed or not>
   parnr                        nrupdt 
--------------------------------------------------------------------------------
<Factor of spontaneous emission>
   sptfct
\end{verbatim}

\subsection{Parameters and Variable Type} 

\begin{parameterlist}
\item[{\tt icurr}]  REAL\\  The peak current$[A]$ of the electron beam.
\item[{\tt gmave0}] REAL\\  The average of $\gamma$.  
\item[{\tt gmspd0}] REAL\\  The spread of $\gamma$. 
\item[{\tt gmdst}]  REAL\\  The form of the distribution of $\gamma$.
\item[{\tt xpave0}] REAL\\  The average of $x$  $[m]$.
\item[{\tt xpspd0}] REAL\\  The spread of $y$ $[m]$.
\item[{\tt bxave0}] REAL\\  The average of $\bx$.
\item[{\tt bxspd0}] REAL\\  The spread of $\bx$.
\item[{\tt ypave0}] REAL\\  The average of $y$  $[m]$.
\item[{\tt ypspd0}] REAL\\  The spread of  $y$  $[m]$.
\item[{\tt bxave0}] REAL\\  The average of $\bx$.
\item[{\tt bxspd0}] REAL\\  The spread  of $\by$.
\item[{\tt trdst}]  REAL\\   The distribution form of $(x,\bx,y,\by)$
\item[{\tt NL}]     INTEGER\\ The number of the points in $\zeta$ space to
place the superparticles. 
\item[{\tt parnr}]  INTEGER \\ The seed for random number generations. 
\item[{\tt nrupdt}] INTEGER\\  The switch which specifies if 
the random series is reset with the seed defined with {\tt parnr},
    when this element was called. 
 \item[sptfct] REAL \\  Set to be 0 on usual usage.  
\end{parameterlist}

\subsection{Parameters}

$\gamma$ and $\beta_x$, $\beta_y$ are the Lorents factor of the electron beam. 

\begin{itemize}

\item {\tt gmdst}, {\tt trdst} \\
They specify the distribution form of $\gamma$ and $(x,\bx,y,\by)$,
respectively.

If they are set to $0$ then the distribution is aumed to be Gaussian
and
{\tt gmspd0},{\tt xpspd0},{\tt ypspd0},{\tt bxspd0},{\tt byspd0} are 
root mean squares.

If they are set to be a positive value $n$, 
then the distribution form is assumed to be
\begin{eqnarray*}
  f(x,\bx,y,\by) dx d\bx dy d\by & = & N_{n} \exp(-B^{n}) dx d\bx dy d\by \\
   B &=&
  \left( \frac{x-\xbar}{\Dx}     \right)^{2} 
+ \left( \frac{\bx-\bxbar}{\Dbx} \right)^{2} 
+ \left( \frac{y-\ybar}{\Dy}     \right)^{2}
+ \left( \frac{\by-\bybar}{\Dby} \right)^{2}
  \nonumber
\end{eqnarray*} 
.
The values of 
 {\tt gmspd0}, {\tt xpspd0}, {\tt ypspd0}, {\tt bxspd0}, {\tt byspd0} 
are \[ \Dx, \Dbx, \Dy, \Dby \].

If they are set to $-1$,
then the distribution is uniform in 4-dimensional sphere.
In this case,
 {\tt gmspd0}, {\tt xpspd0}, {\tt ypspd0}, {\tt bxspd0}, {\tt byspd0} 
is the values of the crossing point of the sphere at each axis.

If they are set to $-2$,
 the distribution is uniform in $ |x| < x_bound $ and $x_bound$ are  
 {\tt gmspd0}, {\tt xpspd0}, {\tt ypspd0}, {\tt bxspd0}, {\tt byspd0} 
 for each directions. 

\item{\tt gmspd0},{\tt xpspd0},{\tt ypspd0},{\tt bxspd0},{\tt byspd0} \\
The parameters which define the scale of the distribution for each axis,
respectively.

\item {\tt parnr} \\
The random seed which is used to generate superparticles.

\item {\tt nrupdt} \\
If {\tt parnr } is set to 0 
then this element reset the random series with the seed {\tt parnr } 
but if {\tt parnr } is set to 1, 
then this element does not update the random series and 
uses the next value of this series.

\end{itemize}
 
\section{Type : AINIT}

An initial laser field is generated.

This element assumes the laser field to be Gaussian( $TEM_{00}$ mode).

\subsection{Format}

\begin{verbatim}
================================================================================
<Element name>   <Element type>
    'Name'          'AINIT'
--------------------------------------------------------------------------------
<width of calculation area>
         width
--------------------------------------------------------------------------------
<The wave length>   <The input power>  <waist size>  <point of focus> ---------
         ll                 Pin             w0             lfa
\end{verbatim}

\subsection{Parameters and Variable Types}

\begin{parameterlist}
\item[{\tt width}] REAL \\ 
         The width$[m]$ of the calculation area in $(x,y)$ space. 
\item[{\tt ll}] REAL \\ The wave length of the laser field $[m]$. 
\item[{\tt Pin}] REAL \\ The input power of the laser field  $[W]$. 
\item[{\tt w0}] REAL \\  The waist size of the laser field when 
it propagates in free space.
 This define the width of 1/e point of the laser field $[m]$.
\item[lfa] REAL\\ The distance to the waist point in free space  $[m]$. 
\end{parameterlist}

\section{Type : MIRROR}

A reflection of a laser field by a circular spherical mirror is simulated.

\subsection{Format}

\begin{verbatim}
================================================================================
<Element name>   <Element type>
    'Name'          'MIRROR'
--------------------------------------------------------------------------------
<width of calculation area>
   width
------------------ Mirror parameter-----------------------------------------------
<Diameter> <Curvature> <Reflectance>  ----<Tilt>---- -<Shift of the center> ---
  Diam         Rho         Ref        ThetaX  ThetaY       DeltaX   DeltaY
\end{verbatim}

\subsection{Parameters and Variable Type} 
\begin{parameterlist}
\item[{\tt width}] REAL \\ 
      The width$[m]$ of the calculation area in $(x,y)$ space.
\item[{\tt Diam}] REAL\\ The diameter of the mirror $[m]$.
\item[{\tt rho}] REAL\\ The curvature of the mirror $[m]$.
\item[{\tt ref}] REAL\\    The reflectance of the mirror.
\item[{\tt ThetaX}] REAL \\
     The $x$ component of the normal vector of the mirror axis. 
\item[{\tt ThetaY}] REAL \\
     The $y$ component of the normal vector of the mirror axis. 
\item[{\tt DeltaX}] REAL\\ The shift of the mirror center to x direction $[m]$.
\item[{\tt DeltaY}] REAL\\ The shift of the mirror center to y direction $[m]$.
\end{parameterlist}

\section{Type :  AFREE}

A free space for a laser field is simulated.

\subsection{Format}

\begin{verbatim} 
================================================================================
<Element name>  <Element type>
    'Name'         'AFREE'
--------------------------------------------------------------------------------
<width at the entrance>   <width at the exit>
     Width_In                   Width_Out
--------------------------------------------------------------------------------
<The length of the drift space>
     Length
\end{verbatim}

\subsection{Parameters and Variable Type} 
\begin{parameterlist}
\item[{\tt Width\_In}] REAL\\ The width of the calculation area
 at the entrance to the drift space $[m]$.
\item[{\tt Width\_Out}] REAL\\ The width of the calculation area 
at the exit from drift space $[m]$. 
\item[{\tt Length}] REAL\\ The length of the drift space $[m]$.
\end{parameterlist}

\section{Type :  ADRIFT}

A drift space for a laser field is simulated.
Completely same as type AFREE except differece of names of types.

\subsection{Format}

\begin{verbatim} 
================================================================================
<Element name>  <Element type>
    'Name'         'ADRIFT'
--------------------------------------------------------------------------------
<width at the entrance>   <width at the exit>
        Width_In                   Width_Out
--------------------------------------------------------------------------------
<The length of the drift space>
    Length
\end{verbatim}

\subsection{Parameters and Variable Type} 
\begin{parameterlist}
\item[{\tt Width\_In}] REAL\\ The width of the calculation area
 at the entrance to the drift space $[m]$.
\item[{\tt Width\_Out}] REAL\\ The width of the calculation area 
at the exit from drift space $[m]$. 
\item[{\tt Length}] REAL\\ The length of the drift space $[m]$.
\end{parameterlist}

\section{Type : EDRIFT} 

A drift space for electrons is simulated.

\subsection{Format}

\begin{verbatim}
================================================================================
<Element name>   <Element type>
   'Name'            'EDRIFT'
--------------------------------------------------------------------------------
<The length of drift space>
        Length
\end{verbatim}

\subsection{Parameters and Variable Type} 

\begin{parameterlist}
\item[{\tt Length}] REAL \\  The length of drift space $[m]$. 
\end{parameterlist}

\section{Type : DSPSCT} 

A dispersive section for bunching like used in optical klystrons.

\subsection{Format}

\begin{verbatim}
================================================================================
<Element name> <Element type>
   'Name'         'DSPSCT'
--------------------------------------------------------------------------------
<width at the entrance> <width at the exit>
    Width_In                Width_Out
--------------------------------------------------------------------------------
<The physical length> <effective length>
    Length              Lengthd
\end{verbatim}

\begin{parameterlist}
\item[{\tt Width\_In}] REAL\\ The width of the calculation area
 at the entrance to the dispersive section $[m]$.
\item[{\tt Width\_Out}] REAL\\ The width of the calculation area 
at the exit from the dispersive section $[m]$. 
\item[{\tt Length}] REAL\\ The physicsl length of 
      the dispersive section $[m]$. 
\item[{\tt LengthD}] REAL\\The effective length of 
      the dispersive section $[m]$. 
      $LengthD$ is related to $\Delta\phi$, the difference of the phase of
      a laser between the entrance and the exit of the dispersive
      section. If we use $L_d$ for $LengthD$, $\Delta\phi$ is 
      \begin{eqnarray}
           \Delta\phi &=& k_L (L_d - \frac{c}{v} L_d) \nonumber \\
                      &=& -\frac{k_L L_d}{2\gamma^{2}} \nonumber   
      \end{eqnarray}
      and if we define $N_d$ as 
      \begin{eqnarray}
           \Delta\phi &=& -2 \pi N_d  \nonumber \\
      \end{eqnarray}
      then 
      \begin{eqnarray}
           N_d &=& \frac{k_L L_d}{4 \pi \gamma^{2}} \nonumber   
      \end{eqnarray}
\end{parameterlist}

\subsection{Parameters and Variable Type} 

\begin{parameterlist}
\item[{\tt Length}] REAL \\  The length of drift space $[m]$. 
\end{parameterlist}

\section{type : TERM}

This shows ELFIN that this is the last element of the list of elements which
defined in part 2.

This also shows ELFIN that this is the end of part 3.

\subsection{Format}

\begin{verbatim}
================================================================================
 <Element name>   <Element type>
   'Name'            'TERM'
\end{verbatim}

\section{USER ROUTINES}
  Users can integrate your subroutine to ELFIN.
  and sample subroutines are pre-installed in ELFIN.

  The type of a sample user element is 'new'.

  Assume that the element name for a sample element is 'newname'.

  The parameters for the element 'newname' 
  are read from file with the soubroutine 'innew'
  then these data are saved to a buffer for element name 'newname'
  with subroutine 'ptnew'.

  When this element was called in main with call rnnew' with 
  element name 'new', 
  then rnnew call gtnew first to load data from the buffer for
  element name 'new' then
  the data was passwd to subroutine new which is 
  the main routine of element type new.
  new runs with the data for element name 'new'.
\end{document}
