modified: documentation/userGuide/pafiX_userGuide.pdf

	new file:   documentation/userGuide/pafiX_userGuide.tex
	new file:   documentation/userGuide/pafiXlogo.pdf
	new file:   documentation/userGuide/publications.bib
	modified:   run.sh
	modified:   src/makefile

documentation/userGuide/pafiX_userGuide.tex

+\documentclass[12pt,a4paper,oneside,headings=small]{scrartcl}
+\usepackage[utf8]{inputenc}
+\usepackage{amsmath}
+\usepackage{amsfonts}
+\usepackage{amssymb}
+\usepackage{graphicx}
+\usepackage[sort&compress,comma,numbers]{natbib}
+\bibliographystyle{unsrtnat}
+\clubpenalty=10000
+\widowpenalty=10000 
+\displaywidowpenalty=10000
+\usepackage[hidelinks,
+            pdftex,
+%            pdfauthor={H. Grosshans},
+            pdftitle={pafiX},
+            pdfsubject={user guide},
+%            pdfkeywords={Some Keywords},
+%            pdfproducer={Latex with hyperref, or other system},
+%            pdfcreator={pdflatex, or other tool}
+]{hyperref}
+\usepackage{array}
+\newcolumntype{L}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+\usepackage{authblk}
+%	\renewcommand{\Authfont}{\small}
+	\renewcommand{\Affilfont}{\footnotesize\slshape}
+\usepackage{dirtree}
+\usepackage{fancyhdr}
+\pagestyle{fancy} %eigener Seitenstil
+\fancyhf{} %alle Kopf- und Fußzeilenfelder bereinigen
+\fancyfoot[C]{\thepage}
+\fancyhead[R]{\small pafiX user guide}
+\renewcommand{\footrulewidth}{0.0pt} %obere Trennlinie
+\renewcommand{\headrulewidth}{0.0pt} %obere Trennlinie
+
+
+\title{user guide}
+
+\author[]{Holger Grosshans}
+%\subtitle[]{holger.grosshans@ptb.de}
+\affil[]{holger.grosshans@ptb.de\\ \bigskip
+Working group ``Analysis and Simulation in Explosion Protection''\\
+Physikalisch-Technische Bundesanstalt (PTB), Bundesallee 100, 38116 Braunschweig, Germany}
+
+\date{\small \today}
+
+
+\begin{document}
+\makeatletter
+    \begin{titlepage}
+        \begin{center}
+            \includegraphics[width=0.6\linewidth]{pafiXlogo}\\[10ex]
+            {\huge \bfseries  \@title }\\[10ex] 
+            {Last update: \@date}\\[30ex] 
+            {\LARGE  \@author}\\[20ex] 
+        \end{center}
+    \end{titlepage}
+\makeatother
+\newpage
+%\maketitle
+
+\section{About this guide}
+
+This guide describes the usage of pafiX by the end user, i.e.~the file structure, the content of input and result files and how to run the code.
+As regards the underlying mathematical model, numerical methods, and scientific contributions we refer to our publications~\citep{Gro16a,Gro16b,Gro16f,Gro17a,Gro17e,Gro18c,Gro18d}.
+
+\section{About pafiX}
+
+\textit{pafiX} (particle flow simulation in explosion protection) is a computational fluid dynamics (CFD) solver optimized to analyze pneumatic transport of powders.
+It is developed by the \textit{Analysis \& Simulation in Explosion Protection} group at PTB in collaboration with the \textit{Multi-phase \& Reacting Flows} group of Prof.~M.V.~Papalexandris at UCLouvain.
+While there are a number of commercial and open source software packages on the market with the capability to compute powder flows, the development of pafiX aims to address the specific need for the theoretical evaluation of various kinds of arising explosion hazards.
+These hazards may be due to deposit formation, triboelelectric charging, external heating, etc. which have initiated fatal events in process and chemical industries in the past (see \citet{Eck03} for an exhaustive discussion).
+
+Another feature differentiating pafiX from comparable software is that we stripped of all parts from the code, input masks and output files which are not directly related to explosion protection.
+Further, pafiX comes with already set up exemplary cases.
+This enables a non-CFD-expert to relatively fast set up new cases and comprehend obtained results.
+
+
+\section{Release history}
+
+
+Tar archives of the compiled executable and case set up of pafiX are distributed for free download on our group's website
+\begin{center}
+\large
+\url{www.ptb.de/cms/asep}
+\end{center}
+following the link \textit{software}.
+Each version's archive name is build up in the manner
+\begin{center}
+\large
+pafiX.xxx.yyzzz-aa.aa
+\end{center}
+where \textit{xxx} denotes the case, \textit{yyzzz} the development status, and \textit{aa.aa} the architecture for which the files have been compiled.
+The case identifier relates to a certain geometry or mathematical model.
+Currently one case is released and further releases are planned in the future.
+The development status number is increased in case of bug fixes or code improvements.
+If a new development status is released it supersedes previous releases.
+The digits \textit{yy} indicate major and \textit{zzz} minor updates.
+
+The pafiX release history is given in Table~\ref{tab:release}.
+If you use pafiX to generate images and/or movies please cite the given reference.
+Doing so helps to sustain funding for future improvements and on going maintenance.
+
+In case of bugs, questions or requests for new features or other architectures please contact H.~Grosshans (holger.grosshans@ptb.de).
+
+\begin{table}[h]
+\caption{Release history.}
+\begin{center}
+\label{tab:release}
+\begin{tabular}[t]{l p{12cm}}
+\hline
+Version & pafiX.001.00100 \\
+Release date & March 1, 2019 \\
+Architecture & Ubuntu~16.04 64 bit and Ubuntu~18.04 64 bit \\
+Ref. & \citep{Gro19a}\\
+Brief case description &
+Powder flow through a squared duct, particles are initially assigned an electrostatic charge which is then constant in time.
+A fully-developed turbulent flow field and a converged field of uncharged particles is provided which can be used as starting condition.
+For example, charge can be be assigned to the particles and its influence on the particle trajectories observed.
+It is noted that the provided initial flow field is essentially under-resolved and is merely provided to demonstrate the capability of pafiX and less to provide accurate results.  
+\\
+\hline
+\end{tabular}
+\end{center}
+\end{table}
+
+\section{How to run pafiX}
+
+\begin{itemize}
+\item Download the archive from \url{www.ptb.de/cms/asep}.
+\item Open a terminal and move to the directory where the archive is saved.
+\item Unpack the archive:
+\begin{verbatim}
+tar -xf pafiX.xxx.yyzzz-aa.aa.tar
+\end{verbatim}
+\item Enter the source directory, link the code, and leave the directory:
+\begin{verbatim}
+cd pafiX.xxx.yyzzz-aa.aa/src
+make -f link.mk
+cd ..
+\end{verbatim}
+\item Execute pafiX:
+\begin{verbatim}
+. run.sh
+\end{verbatim}
+\item Monitor the evolution of some parameters of the simulation:
+\begin{verbatim}
+gnuplot monitor.plt
+\end{verbatim}
+\end{itemize}
+
+
+\section{File structure}
+
+\subsection{Case structure}
+
+Each pafiX case is structured as follows: 
+\medskip
+\dirtree{%
+.1 pafiX.xxx.yyyyy-aa.aa.
+.2 input.
+.3 \textit{input.dat}.
+.2 restart.
+.3 \textit{fluidField\_pmmm\_ii\_jj\_ll\_nnnnnn}.
+.3 \textit{particleField\_ii\_jj\_ll\_pmmm\_nnnnnn}.
+.3 $\ldots$.
+.2 results.
+.3 \textit{fluid\_xz\_pmmm\_nnnnnn.vtk}.
+.3 \textit{particles\_pmmm\_nnnnnn.vtk}.
+.3 \textit{fluid\_xz.visit}.
+.3 \textit{particles.visit}.
+.3 \textit{fluid\_u\_xz\_pmmm\_nnnnnn.dat} .
+.3 $\ldots$.
+.2 output.
+.3 \textit{grid\_pmmm.vtk}.
+.3 \textit{monitor.dat}.
+.3 \textit{output.dat}.
+.2 src.
+.3 \textit{pafiX}.
+.2 \textit{clean.sh}.
+.2 \textit{run.sh}.
+.2 \textit{monitor.plt}.
+}
+
+\subsection{File contents}
+
+In all file names \textit{mmm} denotes the number of the processor that wrote the file, \textit{nnnnnn} the respective time-step and \textit{ii}, \textit{jj}, and \textit{ll} the number of grid cells per processor in $x$, $y$, and $z$ direction, respectively.
+
+\paragraph{input.dat}
+This file is the only mask for the user to control all conditions of simulation.
+
+\paragraph{restart/$\ldots$}
+This folder contains binary files for the fluid and particle phase which are written out during the computation and can be used later on to restart the simulation at time-step \textit{nnnnnn}.
+
+\paragraph{results/$\ldots$}
+The folder \textit{results} contains all result files of the simulation.
+The \textit{*.vtk} files are for visualization.
+While most post-processing tools read vtk format we have tested with Visit~\citep{Visit} which is open source.
+Since it is elaborative to load a large amount of data files stemming from multiple processors and time-steps into Visit, additionally \textit{*.visit} files are provided.
+These files are containers, i.e.~it is sufficient to open the container file to visualize all data at once.
+The \textit{.dat} files essentially contain the same information than the \textit{*.vtk} but are optimized for post-processing instead of visualization.
+
+\paragraph{output/$\ldots$}
+Folder containing files to monitor the status of the simulation.
+\textit{grid\_pmmm.vtk} can be read by Visit to visualize the grid,
+\textit{monitor.dat} can be read by the script \textit{monitor.plt} to plot the current status of key parameters of a running simulation, and in \textit{output.dat} the simulation conditions are documented.
+
+\paragraph{pafiX/pafiX}
+Executable of the source code.
+
+\paragraph{clean.sh}
+This script cleans the case folder from all simulation results and output data.
+
+\paragraph{run.sh}
+Script to start the simulation and to control the number of used processors.
+
+\paragraph{monitor.plt}
+A gnuplot \citep{gnuplot} script to plot the current status of key parameters of a running simulation.
+
+{\setlength{\bibsep}{1pt} \small
+\bibliography{publications.bib}\label{sec:bib}}
+
+\end{document}

documentation/userGuide/publications.bib

+@article{Gro16a,
+title = {Large Eddy Simulation of Triboelectric Charging in Pneumatic Powder Transport},
+journal = {Powder Technol.},
+volume = {301},
+pages = {1008--1015},
+year = {2016},
+author = {Grosshans, H. and Papalexandris, M. V.},
+}
+@article{Gro16b,
+title = {Evaluation of the Parameters Influencing Electrostatic Charging of Powder in a Pipe Flow},
+journal = {J. Loss Prev. Process Ind.},
+year = {2016},
+volume = {43},
+pages = {83--91},
+author = {Grosshans, H. and Papalexandris, M. V.},
+}
+@article{Gro16f,
+title = {A Model for the Non-uniform Contact Charging of Particles},
+journal = {Powder Technol.},
+volume = {305},
+pages = {518--527},
+year = {2016},
+author = {Grosshans, H. and Papalexandris, M. V.},
+}
+@article{Gro17a,
+title = {Direct Numerical Simulation of Triboelectric Charging in a Particle-laden Turbulent Channel Flow},
+journal = {J. Fluid Mech.},
+volume = {818},
+pages = {465--491},
+year = {2017},
+author = {Grosshans, H. and Papalexandris, M. V.},
+doi = {10.1017/jfm.2017.157},
+}
+@article{Gro17e,
+title = {On the accuracy of the numerical computation of the electrostatic forces between charged particles},
+journal = {Powder Technol.},
+volume = {322},
+pages = {185--194},
+year = {2017},
+author = {Grosshans, H. and Papalexandris, M. V.},
+}
+@article{Gro18c,
+title = {Exploring the mechanism of inter-particle charge diffusion},
+journal = {Eur. Phys. J. Appl. Phys.},
+volume = {82},
+number = {1},
+pages = {11101},
+year = {2018},
+author = {Grosshans, H. and Papalexandris, M. V.},
+}
+@article{Gro18d,
+author = {Grosshans, H.},
+volume = {30},
+number = {8},
+journal = {Phys. Fluids},
+title = {Modulation of particle dynamics in dilute duct flows by electrostatic charges},
+pages = {083303},
+year = {2018},
+}
+@book{Eck03,
+author = {Eckhoff, R. K.},
+title = {Dust Explosions in the Process Industries},
+edition = {3rd},
+publisher = {Gulf Professional  Publishing},
+year = {2003}
+}
+@inproceedings{Gro19a,
+author = {Grosshans, H.},
+title = {Modeling the agglomeration of electrostatically charged particles},
+booktitle = {BAM-PTB Kolloquium 2019},
+address = {Braunschweig, Germany},
+month = {May},
+year = {2019}
+}
+@InCollection{Visit,
+author = {H. Childs and E. Brugger and et al.},
+title = {{VisIt}: An End-User Tool For Visualizing and Analyzing Very Large Data},
+year = {2012},
+pages = {357-372},
+month = {Oct},
+booktitle = {High Performance Visualization--Enabling Extreme-Scale Scientific Insight},
+}
+@misc{gnuplot,
+author = {Thomas Williams and Colin Kelley and {many others}},
+title = {Gnuplot 5.2: an interactive plotting program},
+month = {November},
+year = {2017},
+howpublished={\url{http://www.gnuplot.info}}
+}

run.sh

 mkdir -p results restart output
-mpiexec -np 1 --oversubscribe src/pafiX
+mpiexec -np 4 --oversubscribe src/pafiX

src/makefile

@@ -9,9 +9,9 @@ INC =
 # gcc:
 CMP = mpifort
 #O3: optimization
-#FLAGS   = -O3 -mcmodel=medium
+FLAGS   = -O3 -mcmodel=medium
 #debugging:
-FLAGS   = -g3 -O0 -fbounds-check -mcmodel=medium -fimplicit-none -fcheck=all -fbacktrace -floop-nest-optimize -ffpe-trap=invalid,zero,overflow -Wconversion -fno-tree-vectorize 
+#FLAGS   = -g3 -O0 -fbounds-check -mcmodel=medium -fimplicit-none -fcheck=all -fbacktrace -floop-nest-optimize -ffpe-trap=invalid,zero,overflow -Wconversion -fno-tree-vectorize 
 #-Wall
 FFLAGS  = -c $(FLAGS)