\documentclass[10pt,a4paper,oneside]{book}
\usepackage[latin1]{inputenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{listings}
\usepackage{wrapfig}
\usepackage{units}
\usepackage[block=ragged,backend=bibtex]{biblatex}
\usepackage[acronym,toc,automake]{glossaries}
\usepackage[hidelinks]{hyperref}
\hypersetup{
  breaklinks = true,                                               % Allows break links in lines
  colorlinks = true,                                               % Colours links instead of ugly boxes
  urlcolor   = blue,                                               % Colour for external hyperlinks
  linkcolor  = blue,                                               % Colour of internal links
  citecolor  = blue,                                               % Colour of citations
  pdfinfo    = {
    Title    = {fpakc User Manual},
    Author   = {Jorge Gonzalez}
  }
}
\makeglossaries

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newacronym{fpakc}{fpakc}{Finite Element PArticle Code}
\newacronym{mpi}{MPI}{Message Passing Interface}
\newacronym{gpu}{GPU}{Graphics Processing Unit}
\newacronym{cpu}{CPU}{Central Processing Unit}
\newacronym{json}{JSON}{JavaScript Object Notation}
\newacronym{io}{I/O}{input/output}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newglossaryentry{openmp}{name={OpenMP},description={Shared-memory parallelization}}
\newglossaryentry{gfortran}{name={GFortran},description={Open-source compiler for fortran source code}}
\newglossaryentry{ifort}{name={ifort},description={Intel\textsuperscript{\textregistered} Fortran compiler}}
\newglossaryentry{opensource}{name={Open Source},description={Source code that is made freely available for possible modification and redistribution}}
\newglossaryentry{openblas}{name={OpenBLAS},description={Open-source implementation of BLAS and LAPACK APIs}}
\newglossaryentry{git}{name={Git},description={Git is a distributed version-control system for tracking changes in a set of files}}
\newglossaryentry{gitlab}{name={GitLab},description={GitLab is a web-based lifecycle tool that provides a \Gls{git}-repository manager}}
\newglossaryentry{gmsh}{name={Gmsh},description={A three-dimensional finite element mesh generator with built-in pre- and post-processing facilities.}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\bibliography{bibliography}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
  \title{\includegraphics{figures/logos/fpakc}\\\vspace{2cm}fpakc User Manual}
  \author{Jorge Gonzalez}
  \date{\today\\v0.1}
  
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  
  \maketitle
  
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \tableofcontents
  
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \chapter{Introduction}
    \section{About fpakc}
      The \Gls{fpakc} is a simulation tool that models species in plasmas (ions, electrons and neutrals) following the trajectories of macro-particles as they move and interact between them and the boundaries of the domain.
      The code is currently in very early steps of development and further improvements are expected very soon.
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Main Guidelines}
      The \acrshort{fpakc} environment aims to be a fully functional tool for the simulation of plasmas from a kinetic point of view.
      The main guidelines in the creation of the code are:
      \begin{enumerate}
        \item The code is \Gls{opensource} and freely distributed. This means the code can be used and modified by anyone.
               Nevertheless, the official version distributed in the official repository will be managed by the developed team, which members have to be given direct permission by the lead developer.
              \acrshort{fpakc} is distributed with a GNU General Public License v3.0 that covers all files in the repository.
              Moreover, there should always be an open-source free alternative for external tools required by the program (post-processing, mesh generation, input file generation \ldots).
        \item \acrshort{fpakc} is coded in a \textit{understandable} way.
              This means that the code is required to be written in a clear way that is easy to understand and maintain.
              Variables and procedure names need to be self-understanding.
              This ease the process of fixing bugs and improving the codes by a large team of developers.
              For more information, please refer to the \acrshort{fpakc} Coding Style document.
        \item \acrshort{fpakc} requires to be ease to use.
              Input files are required to be in a \textit{human} format, meaning that the different options can be easily understander without constant reference to the user guide.
              \acrshort{fpakc} is aimed to be used in a wide range of applications and by a variety of scientist: from very established ones to newcomers to the field and students.
      \end{enumerate}
    
      These are foundation stones of the code and code development and should always be followed, at least for the releases in the official repository.
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{How to collaborate}
      Right now, development of \acrshort{fpakc} is closed to third parties until a stable version with the basic functionality is released.
      However, if you have a huge interest in the project please contact \href{mailto:jorge.gonzalez@upm.com}{jorge.gonzalez@upm.com}.
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \chapter{Operation Scheme}
    \section{The Particle Method}
      \acrshort{fpakc} uses macro-particles to simulate the dynamics of different plasma species (mainly ions, electrons and neutrals).
      These macro-particles represent a large amount of real particles.
      For now own, macro-particles will be referred as just particles by abusing of language.
      In the evolution of these particles, external forces (as the electromagnetic field), interaction between particles (as collisions) and interaction with the boundaries of the domain are included.
    
      At each time step, particles are first pushed accounting for possible acceleration by external forces.
      Then, the cell in which the particle ends up is located.
      If a boundary is encountered, the interaction between the particle and the boundary is calculated.
      Next, collisions for the particles in each cell are carried on.
      This may include different collision processes for each particle.
      Finally, the particles properties are scattered into the mesh nodes.
      These properties are density, momentum and the stress tensor.
      Non-dimensional units are used for this, but output files are converted into dimensional units.
      If requested, the electromagnetic field is computed.
    
      More in depth explanation of the different steps are given in the following sections.
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Injection of new particles}
      \acrshort{fpakc} has the capability of injecting particles at different velocities, temperatures, distributions and mass flows in boundary sections defined by the user.
      Particles are distributed uniformly along the edge.
      Their velocities are computed from the distribution function selected by the user.
    
      The injection of particles is controlled in the \lstinline|moduleInject| module.
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Pushing}
      Particles are pushed in the selected domain.
      Velocity and position are updated according to the old particle values and the external forces.
      All the push routines for the different geometries can be found in \lstinline|moduleSolver|.
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{3D Cartesian pusher}
        Moving particles in a simple 3D Cartesian space.
        
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{2D Cylindrical}
        When a 2D cylindrical geometry is used ($z$, $r$), a Boris solver\cite{boris1970relativistic} is used to move particles accounting for the effect of the symmetry axis.
        This pusher removes the issue with particles going to infinite velocity when $r \rightarrow 0$ by pushing the particles in Cartesian space and then converting it to $r-z$ geometry.
        Velocity in the $\theta$ direction is updated for collision processes, although the dynamic in the angular direction is assumed as symmetric.
        
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{2D Cartesian pusher}
        Moving particles in a simple 2D Cartesian space.
        
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{1D Radial pusher}
        Same implementation as 2D cylindrical pusher but direction $z$ is ignored.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{1D Cartesian pusher}
        Moving particles in a simple 1D Cartesian space. Same implementation as in 2D Cartesian but $y$ direction is ignored.
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Find new cell}      
      Once the position and velocity of the particle are updated, the new cell that contains the particle is searched.
      This is done by a neighbor search, starting from the previous cell containing the particle.
      In the process of finding the new cell, it is possible that a particle encounters a boundary.
      When the particle interacts with the boundary, the particle may continue its life in the simulation (reflected) or might be eliminated from it (absorbed).
      Once that the new cell is found or that the particle life has been terminated, the pushing is complete.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Variable Weighting Scheme\label{sec:weightingScheme}}
      One of the issues in particle simulations, specially for axial-symmetrical cases, is that due to the disparate volume of cells, specially close to the axis, the statistics in some cells is usually poor.
      To try to fix that, the possibility to include a Variable Weighting Scheme in the simulations is available in \Gls{fpakc}.
      This schemes detect when a particle change cells and modify its weight accordingly.
      To avoid particles having a larger weight than the rest, particle can be split in multiple particles if weight become too large.
                  
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Reset of particle array}
      Once that the pushing is complete, the array of particles that remain inside the domain is copied to a new array.
      The new array containing only the particles inside the domain will be the one used in the next steps.
      In this section, particles are assigned to the list of particles inside each individual cell.
      Unfortunately, this is done right now without parallelisation and is very CPU consuming.
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Interaction between species}\label{ssec:collisions}
      For each cell, interaction among the particles in it are carried out.
      The type of interaction between the different particles is defined by the user.
      In general, the maximum number of interaction in a cell is computed.
      For each collision, a pair of particles is selected.
      A loop over all possible collisions for the pair of particles is performed.
      If a random number generated is above the probability of collision for the type divided by the maximum one, the collision take place.
      
      Collisions can change the velocity of the particles involved (elastic), create new particles (ionization-recombination) or change the type of particle (charge-exchange).
      
      Below are described the type of collision process implemented between species.
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{Elastic collision}
        In this type of collision, particles exchange energy due to hard-sphere model.
        Total energy is conserved.
        Resulting velocity directions are chosen from Maxwellian distribution functions.
        This interaction is useful for short-range collisions as neutral-neutral and charged-neutral elastic collisions.
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{Charge Exchange}
        When an ion interacts with a neutral particle, an electron is exchanged between the two particles with no exchange of energy.
        This is called a resonant charge-exchange.
        
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{Electron Impact Ionization}
        When the relative energy between a neutral and an electron is above the ionization threshold, there is a probability that the neutral particle will become ionized.
        This ionization emits and additional electron

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{Recombination}
        When an electron and an ion interact, there is a possibility for them to be recombined into a neutral particle.
        The photon emitted by this process is not modeled yet.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Scattering}
      The properties of each particle are deposited in the nodes from the containing cell.
      This process depend on the cell type, but in general, each node receive a proportional part of the particle properties as a function of the particle position inside the cell.
      Figure \ref{fig:scatteringQuad} shows how a particle at a generic position $p(x_1, x_2)$ inside the cell is scattered to the four nodes.
      \begin{wrapfigure}{l}{0.4\textwidth}
        \centering
        \includegraphics{figures/scatteringQuad}
        \caption{\label{fig:scatteringQuad}Example of how a particle is weighted in a quadrilateral cell.}
      \end{wrapfigure}
      Each node receives a proportional part of the area formed by dividing the cell in for rectangles using as an additional vertex the particle position.
      These properties are dimensionless, but they are converted to the correct units once the output is printed.
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Electromagnetic field}
      WIP.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  
  \chapter{Installation}
    \section{Required Packages}
      In order to properly compile \gls{fpakc}, the following packages are required.
      \subsection{Gfortran}
        The \Gls{opensource} free compiler \Gls{gfortran}\cite{gfortranURL} from GCC is the basic way to compile \acrshort{fpakc}.
        It is distributed with all GNU/Linux distributions.
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{Ifort}
        The \Gls{ifort}\cite{ifortURL} compiler is a proprietary Fortran compiler developed by Intel\textsuperscript{\textregistered}.
        The makefile distributed with \Gls{fpakc} is prepared to be used with ifort with minor modifications.
        However, \Gls{gfortran} is recommended for compiling fpakc.
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{OpenBlas}
        \Gls{openblas}\cite{openblasURL} is used by \acrshort{fpakc} to solve the electromagnetic field in the finite element mesh.
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{JSON-Fortran}
        To read \acrshort{json}\cite{jsonURL} input files in Fortran, the API JSON-Fortran\cite{jsonfortranURL} is used.
        This needs to be compiled and placed in a folder accessible from the root directory of \Gls{fpakc}.
        The same compiler as the one used to compile \Gls{fpakc} needs to be used to generate a compatible library.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{Gmsh}
        Although \Gls{gmsh}\cite{gmshURL} is not required to compile and run \Gls{fpakc}, it is the default tool to generate finite element meshes and post-processing.
        Right now, the only \acrshort{io} format available in \Gls{fpakc} is the v2.0 .msh format.
        
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Installation steps}
      Once you have been added to the \Gls{fpakc} \Gls{gitlab} repository, and have added an ssh key to your account, you will be able to clone the repository using:
      \begin{lstlisting}
git clone git@gitlab.com:<YourGitLabUsername>/fpakc.git
      \end{lstlisting}
      in which you have to substitute \lstinline|<YourGitLabUsername>| for your \Gls{gitlab} username.
      
      Go into the new downloaded directory with
      \begin{lstlisting}
cd fpakc
      \end{lstlisting}
      Clone the json-fortran repository with:
      \begin{lstlisting}
git clone https://github.com/jacobwilliams/json-fortran.git
      \end{lstlisting}
      This will create the  \lstinline|json-fortran-8.2.0| directory.
      Go into this new folder and create a new \lstinline|build-gfortran| directory, enter it and execute:
      \begin{lstlisting}
cmake ../
      \end{lstlisting}
      Once it finish, just compile the json-fortran library with
      \begin{lstlisting}
make
      \end{lstlisting}
      This creates the \lstinline|include| and \lstinline|lib| folders that contain the required files for \acrshort{fpakc} compilation.
      
      Go back to the \acrshort{fpakc} root folder and execute
      \begin{lstlisting}
make
      \end{lstlisting}
      to compile the code.
      If everything is correct, an executable named \textit{fpakc} will be generated.
  
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Running the code}
      To run a case, simply execute:
      \begin{lstlisting}
./fpakc path/to/input-file.json
      \end{lstlisting}
  	  in a command line from the root \acrshort{fpakc} folder.
      Substitute \lstinline|path/to/input-file.json| with the path to the input file of the case you want to run.
      The examples in the run directory are presented in Chapter \ref{ch:exampleRuns}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \chapter{Input File}\label{ch:input_file}
    The input files for \Gls{fpakc} is divided between to files: a mesh file and a case file.
    The mesh file contains the descriptions for the different elements composing a mesh (nodes, edges and volumes).
    The case file contains the required information to define a simulation case: reference parameters, initial state, injection of particles, boundary conditions, species, number of iterations\ldots
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Mesh file}
      \Gls{fpakc} accepts right now the version 2.0 of \Gls{gmsh} mesh format .msh in ASCII format.
      This file contains information about the nodes, edges and volumes that define the finite element mesh used by \Gls{fpakc} to scatter particle properties and compute the self-consistent electromagnetic field.
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Case file}
      The required format for the case file is \Gls{json}.
      \Gls{json} is a case-sensitive format, so input must be written with the correct capitalisation.
      The basic structure and options available for the case file are explained below.
      The order of the objects and variables is irrelevant, but the structure needs to be maintained.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{output}
        The object \textbf{output} in the \Gls{json} case file determines the different options to define how and when the simulation produces files:
        The available options are:
        \begin{itemize}
          \item \textbf{path}: Character.
                               Path for the output files. This path is also used to locate the mesh input file.
          \item \textbf{folder}: Character.
                                 Base name of the folder in wich output files are placed.
                                 The date and time is appended to this name.
                                 If none is provided, only the date and time is writted as the folder name.
          \item \textbf{triggerOutput}: Integer.
                                        Determines the number of iterations between writing output files for macroscopic quantities.
          \item \textbf{cpuTime}: Logical. 
                                  Determines if the \Gls{cpu} time per iteration is written into a file.
                                  Each row in the file determine the iteration, number of particles in the simulation and the multiple times spend per action.
                                  Each action in the iteration (pushing, collisions, weighting\ldots) has its own column.
          \item \textbf{triggerCPUTime}: Integer.
                                          Determines the number of iterations between writing \Gls{cpu} time for macroscopic quantities.
                                          This option is irrelevant if \textbf{cpuTime} is set to \textit{false}.
          \item \textbf{numColl}: Logical.
                                  Determines if the number of collisions per cell are outputted in a separated file.
                                  Trigger between writings is the same as in \textbf{triggerOutput}.
          \item \textbf{EMField}: Logical.
                                  Determines if the electromagnetic field is printed.
        \end{itemize}
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{geometry}
        The object \textbf{geometry} contains information about the type of geometry, the mesh file format and the mesh filename.
        The accepted parameters are:
        \begin{itemize}
          \item \textbf{type}: Character. 
                               Type of geometry.
                               Current accepted vaules are
                               \begin{itemize}
                                 \item \textbf{3DCart}: Three-dimensional grid ($x \hyphen y \hyphen z$) in Cartesian coordinates..
                                                        For \Gls{gmsh} mesh format, the coordinates $x$, $y$ and $z$ correspond to $x$, $y$ and $z$ respectively.
                                 \item \textbf{2DCyl}: Two-dimensional grid ($z \hyphen r$) with symmetry axis at $r = 0$.
                                                       For \Gls{gmsh} mesh format, the coordinates $x$ and $y$ correspond to  $z$ and $r$ respectively.
                                 \item \textbf{2DCart}: Two-dimensional grid ($x \hyphen y$) in Cartesian coordinates..
                                                        For \Gls{gmsh} mesh format, the coordinates $x$ and $y$ correspond to  $x$ and $y$ respectively.
                                 \item \textbf{1DRad}: One-dimensional grid ($r$) in radial coordinates
                                                       For \Gls{gmsh} mesh format, the coordinates $x$ corresponds to $r$.
                                 \item \textbf{1DCart}: One-dimensional grid ($x$) in Cartesian coordinates
                                                        For \Gls{gmsh} mesh format, the coordinates $x$ corresponds to $x$.
                               \end{itemize}
          \item \textbf{meshType}: Character.
                                   Format of mesh file.
                                   Currently, only the value \textbf{gmsh} is accepted, which makes reference to \Gls{gmsh} v2.0 output format.
          \item \textbf{meshFile}: Character.
                                   Mesh filename.
                                   This file is searched in the path \textbf{output.path} and must contain the file extension.
        \end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{species}
        The array object \textbf{species} contains the data relevant to identify the different species in the simulation.
        Multiple species can be defined as elements in the array.
        For each species, the following parameters need to be defined:
        \begin{itemize}
          \item \textbf{name}: Character.
                               Name of the species.
          \item \textbf{type}: Character.
                               Defines the type of species.
                               Current values are:
                               \begin{itemize}
                                 \item \textbf{neutral}: Neutral species.
                                 \item \textbf{charged}: Charged species.
                                                         The parameter \textbf{charge} is required for this type of species.
                               \end{itemize}
          \item \textbf{mass}: Real.
                               Particle mass in $\unit{kg}$.
          \item \textbf{charge}: Real. 
                                 Particle charge in elementary charge units.
                                 This parameter is only relevant if \textbf{type} is \textbf{charged}.
          \item \textbf{ion}: Character.
                              Name of species resulting of ionizing the current one.
          \item \textbf{neutral}: Character.
                                  Name of species resulting of neutralizing the current one.
        \end{itemize}
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{boundary}
        The array object \textbf{boundary} determines the interaction between surfaces and particles.
        These boundaries need to be linked to a specific edge in the mesh.
        The accepted variables are:
        \begin{itemize}
          \item \textbf{name}: Character.
                               Name of the boundary.
          \item \textbf{type}: Character.
                               Type of boundary.
                               Accepted values are:
                               \begin{itemize}
                                 \item \textbf{reflection}: Elastic reflection of particles.
                                 \item \textbf{absorption}: Particle is eliminated from the domain.
                                                            The particle is first moved into the edge and its properties are scattered among the edge nodes.
                                 \item \textbf{transparent}: Particle abandon the numerical domain.
                                 \item \textbf{wallTemperature}: Reflective wall with cosntant temperature that exchange heat with particles.
                                                                 Required parameters are:
                                                                 \begin{itemize}
                                                                   \item \textbf{temperature}: Real.
                                                                                               Units of $\unit{K}$.
                                                                                               Temperature wall.
                                                                   \item \textbf{specificHeat}: Real.
                                                                                                Units of $\unit{J kg^{-1} K^{-1}}$.
                                                                                                Specific heat capacity of the material.
                                                                 \end{itemize}
                                 \item \textbf{ionization}: Per each particle crossing the surface with this type of boundary, a number of ionization events are calculated.
                                                            A pair of ion-electron is generated for each ionization event taking as a reference a neutral background.
                                                            Secondary electron is taken as same type as incident particle.
                                                            The available input is:
                                                            \begin{itemize}
                                                              \item \textbf{neutral}: Object.
                                                                                      Information about the neutral background.
                                                                                      Required parameters are:
                                                                                      \begin{itemize}
                                                                                        \item \textbf{ion}: Character.
                                                                                                            Species name of the ion generated as defined in object \textbf{species}.
                                                                                                            Required parameter.
                                                                                        \item \textbf{mass}: Real.
                                                                                                             Units in $\unit{kg}$.
                                                                                                             Mass of neutral species.
                                                                                                             If missing, the mass of the ion is ussed
                                                                                        \item \textbf{density}: Real.
                                                                                                                Units in $\unit{m^{-3}}$.
                                                                                                                Density of neutral background.
                                                                                                                Required parameter.
                                                                                        \item \textbf{velocity}: Real.
                                                                                                                 Units in $\unit{m^{-3}}$.
                                                                                                                 Array of dimension $3$.
                                                                                                                 Mean velocity of neutral background.
                                                                                                                 Required parameter.
                                                                                        \item \textbf{temperature}: Real.
                                                                                                                    Units in $\unit{K}$.
                                                                                                                    Temperature of neutral background.
                                                                                                                    Required parameter.
                                                                                                             
                                                                                      \end{itemize}
                                                              \item \textbf{effectiveTime}: Real.
                                                                                            Units in $\unit{s}$.
                                                                                            As the particle is no longer simulated once it crossed the boundary, this time represent the effective time in which the particle produces ionization processes in the neutral background.
                                                                                            Required parameter.
                                                              \item \textbf{energyThreashold}: Real.
                                                                                               Units in $\unit{eV}$.
                                                                                               Ionization energy threshold for the simulated process.
                                                                                               Required parameter.
                                                              \item \textbf{crossSection}: Character.
                                                                                           Complete path to the cross section data for the ionization process.
                                                                                            
                                                            \end{itemize}
                                 \item \textbf{axis}: Identifies the symmetry axis for 2D cylindrical simulations.
                                                      If for some reason a particle interact with this axis, it is reflected.
                               \end{itemize}
          \item \textbf{physicalSurface}: Integer.
                                          Identification of the edge in the mesh file.
        \end{itemize}
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{boundaryEM}
        The array object \textbf{boundaryEM} determines the boundary conditions for the electromagnetic field.
        As with the \textbf{boundary} definition, these must be linked to an edge identified in the mesh file.
        The variables for each array element are:
        \begin{itemize}
          \item \textbf{name}: Character.
                               Name of the boundary.
          \item \textbf{type}: Character.
                               Type of boundary.
                                Accepted values are:
                               \begin{itemize}
                                 \item \textbf{dirichlet}: Elastic reflection of particles.
                                \end{itemize}
           \item \textbf{potential}: Real.
                                     Fixed potential for Dirichlet boundary condition.
          \item \textbf{physicalSurface}: Integer.
                                          Identification of the edge in the mesh file.
        \end{itemize}
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{inject}
        The array \textbf{inject} specifies the injection of particles from different surfaces.
        The injection of particles need to be associated to a physicalSurface in the mesh file.
        Multiple injections can be associated to the same surface.
        \begin{itemize}
          \item \textbf{name}: Character.
                               Name of the injection.
          \item \textbf{species}: Character.
                                  Name of the species that is being injected.
          \item \textbf{flow}: Real.
                               Flow of particles going through the surface.
          \item \textbf{units}: Character.
                                Units for the \textbf{flow} parameter.
                                Available values are:
                                \begin{itemize}
                                  \item \textbf{A}: Ampere.
                                  \item \textbf{sccm}: Standard cubic centimeter.
                                \end{itemize}
          \item \textbf{v}: Real.
                            Module of velocity vector, in $\unitfrac{m}{s}$.
          \item \textbf{n}: Real.
                            Array dimension $3$.
                            Direction of injection.
                            Norm of vector must be equal $1$.
          \item \textbf{velDist}: Character.
                                  Array dimension $3$.
                                  Type of distribution function used to obtain injected particle velocity:
                                  \begin{itemize}
                                    \item \textbf{Maxwellian}: Maxwellian distribution of temperature \textbf{T} and mean \textbf{v} times the value of \textbf{n} in the specified direction.
                                    \item \textbf{Delta}: Dirac's delta distribution function. All particles are injected with velocity \textbf{v} times the value of \textbf{n} in the specified direction.
                                  \end{itemize}
          \item \textbf{T}: Real.
                            Array dimension $3$.
                            Temperature in each direction.
          \item \textbf{physicalSurface}: Integer.
                                          Identification of the edge in the mesh file.
        \end{itemize}        
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{reference}
        This object indicates the reference values used by \Gls{fpakc} to scale the problem variables.
        The required parameters are:
        \begin{itemize}
          \item \textbf{density}: Real.
                                  Reference density in $\unit{m^-3}$.
          \item \textbf{mass}: Real.
                               Reference particle mass in $\unit{kg}$.
          \item \textbf{temperature}: Real.
                                      Reference temperature in $\unit{K}$.
          \item \textbf{radius}: Real.
                                 Reference atomic radius in $\unit{m}$.
          \item \textbf{crossSection}: Real.
                                       Reference cross section in $\unit{m^2}$.
                                       If this value is present, radius is ignored.
        \end{itemize}
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{case}
        This object determines the simulation time, time step, pushers, weighting scheme and solver for the electromagnetic field.
        Accepted variables are:
        \begin{itemize}
          \item \textbf{tau}: Real.
                              Array dimension 'number of species'.
                              Defines the different time steps for each species.
                              Even if all time steps are equal, they need to be defined as an array.
          \item \textbf{time}: Real.
                               Total simulation time in $\unit{s}$.
          \item \textbf{pusher}: Character.
                                 Array dimension 'number of species'.
                                 Indicates the type of pusher used for each species:
                                 \begin{itemize}
                                   \item \textbf{3DCartNeutral}: Pushes particles in a 3D Cartesian space ($x \hyphen y \hyphen z$) without any external force.
                                   \item \textbf{3DCartCharged}: Pushes particles in a 3D Cartesian space ($x \hyphen y \hyphen z$) including the effect of the electrostatic field.
                                   \item \textbf{2DCylNeutral}: Pushes particles in a 2D cylindrical space ($z \hyphen r$) without any external force.
                                   \item \textbf{2DCylCharged}: Pushes particles in a 2D cylindrical space ($z \hyphen r$) including the effect of the electrostatic field.
                                   \item \textbf{2DCartNeutral}: Pushes particles in a 2D Cartesian space ($x \hyphen y$) without any external force.
                                   \item \textbf{2DCartCharged}: Pushes particles in a 2D Cartesian space ($x \hyphen y$) including the effect of the electrostatic field.
                                   \item \textbf{1DRadNeutral}: Pushes particles in a 1D cylindrical space ($r$) without any external force.
                                   \item \textbf{1DRadCharged}: Pushes particles in a 1D cylindrical space ($r$) accounting the the electrostatic field.
                                   \item \textbf{1DCartNeutral}: Pushes particles in a 1D Cartesian space ($x$) without any external force.
                                   \item \textbf{1DCartCharged}: Pushes particles in a 1D Cartesian space ($x$) accounting the the electrostatic field.
                                 \end{itemize}
          \item \textbf{WeightingScheme}: Character.
                                          Indicates the variable weighting scheme to be used in the simulation.
                                          Check Section \ref{sec:weightingScheme} for more information.
                                          If this variable is not present, no scheme is used.
                                          The current available schemes are:
                                          \begin{itemize}
                                            \item \textbf{Volume}: Modifies particle weight as a function of cell volume.
                                          \end{itemize}
          \item \textbf{EMSolver}: Character.
                                   Determines the solver for the electromagnetic field.
                                   If no value is supplied, no field is solved.
                                   \begin{itemize}
                                      \item \textbf{Electrostatic}: Solves the Poison equation to obtain the self-consistent electrostatic potential.
                                   \end{itemize}
          \item \textbf{initial}: Object.
                                  Array.
                                  Determines initial values for the species.
                                  Required values are:
                                  \begin{itemize}
                                    \item \textbf{speciesName}: Character.
                                                                Name of species.
                                    \item \textbf{initialState}: Character.
                                                                 Plain text file that contains the information about the species macroscopic properties in the grid.
                                                                 Initial particles are assumed to be Maxwellian.
                                                                 File must be located at \textbf{output.path}.
                                                                 The file must contain the following columns in this specific order:
                                                                 \begin{itemize}
                                                                   \item \textit{Element}: Integer. 
                                                                                           Identifier of the volume in the mesh.
                                                                                           It is not required to specify empty volumes.
                                                                   \item \textit{Density}: Real.
                                                                                           Species density in $\unit{m^-3}$.
                                                                   \item \textit{Velocity}: Real.
                                                                                            Three colums representing the initial velocity in each direction.
                                                                                            Units are $\unit{m s^-1}$.
                                                                   \item \textit{Temperature}: Real.
                                                                                               One column that represents the initial temperature in $\unit{K}$.
                                                                                 
                                                                 \end{itemize}
                                  \end{itemize}
        \end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{interactions}\label{ssec:input_interactions}
        This object determine the different interactions among species.
        Acceptable values are:
        \begin{itemize}
          \item \textbf{folderCollisions}: Character.
                                           Indicates the path to in which the cross section tables are allocated.
          \item \textbf{collisions}: Object.
                                     Array.
                                     Contains the different binary collisions.
                                     Multiple collision types can be defined for each pair of species.
                                     Each object in the array is defined by:
                                     \begin{itemize}
                                       \item \textbf{species\_i}, \textbf{species\_j}: Character.
                                                                                     Define the two species involved in the collision processes.
                                                                                     Order is indiferent.
                                       \item \textbf{cTypes}: Object.
                                                              Array.
                                                              Defines all the collisions between \textbf{species\_i} and \textbf{species\_j}.
                                                              Required values are:
                                                              \begin{itemize}
                                                                \item \textbf{type}: Character.
                                                                                     Collision type.
                                                                                     Accepted values are \textbf{elastic}, \textbf{chargeExchange}, \textbf{ionization} and \textbf{recombination}.
                                                                                     Please refer to Sec. \ref{ssec:collisions} for a description of the different collision types.
                                                                \item \textbf{crossSection}: Character.
                                                                                             File in \textbf{interactions.folderCollisions} that contains the cross section data as a 1D table of relative energy (in $\unit{eV}$) and cross section (in $\unit{m^-2}$).
                                                                \item \textbf{energyThreshold}: Real.
                                                                                                Energy threshold of the collisional process in $\unit{eV}$.
                                                                                                Only valid for \textbf{ionization} and \textbf{recombination} processes.
                                                                \item \textbf{electron}: Character.
                                                                                         Name of species designed as electrons.
                                                                                         Only valid for \textbf{ionization} and \textbf{recombination} processes.
                                                              \end{itemize}
                                     \end{itemize}
        \end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      \subsection{parallel}
        This object contains the information related to parallelization of \Gls{fpakc}.
        Current values accepted are:
        \begin{itemize}
          \item \textbf{OpenMP}: Object.
                                 Defines the parameters for the \Gls{openmp} shared memory parallelization.
                                 \begin{itemize}
                                    \item \textbf{nThreads}: Integer.
                                                             Number of threads to be used by \Gls{openmp}.
                                                             Try to match this to the number of threads of the \acrshort{cpu} used.
                                 \end{itemize}
                                 
        \end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \chapter{Example runs\label{ch:exampleRuns}}
    \section{1D Cathode}
      Emission from a 1D cathond in both, cartesian and radial coordinates.
      Both cases insert the same amount of electrons from the minimum coordinate and have the same boundary conditions for particles and the electrostatic field.
      This case is useful to ilustrate hoy \acrshort{fpakc} can deal with different geometries by just modifiying some parameters in the input file.
      The same mesh file (\lstinline|mesh.msh|) is used for both cases.
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{ALPHIE Grid system}
      Two-dimensional axialsymmetry case to study the counterflow of electrons and Argon ions going trhough the ALPHIE grid system.
      A \lstinline|mesh.geo| file is provided to easily modify the parameters of the grid system and generate a new mesh with \Gls{gmsh}.
      
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    \section{Flow around cylinder}
      Simple case of neutral Argon flow around a cylinder in a 2D axialsymmetry geometry.
      Elastic collisions between argon particles are included as default.
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \printglossaries

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \printbibliography

\end{document}
