Merge branch pafix:master into master

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 the user 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 off all parts from the code, input masks and output files which are not directly related to explosion protection.
+Further, pafiX comes with an already-set-up exemplary case.
+This enables a non-CFD-expert to relatively quickly set up new cases and comprehend obtained results.
+
+\section{How to install and run pafiX}
+
+\subsection{Prerequisite Installations}
+
+\begin{itemize}
+\item Before compiling and running paifX, the following installations are required: make, gfortran, and Open MPI. The installation processes for a linux machine is described below.
+\item If make is not installed:
+\begin{verbatim}
+sudo apt-get update
+sudo apt install build-essential
+\end{verbatim}
+\item If FORTRAN is not installed:
+\begin{verbatim}
+sudo apt install gfortran
+\end{verbatim}
+\item If Open MPI is not installed:
+\begin{verbatim}
+sudo apt-get install openmpi-bin openmpi-doc libopenmpi-dev
+\end{verbatim}
+
+\subsection{Installation and Execution}
+
+\item Clone the repository from the terminal:
+\begin{verbatim}
+git clone https://gitlab1.ptb.de/asep/pafix.git
+\end{verbatim}
+\item Enter the source directory, compile the code, and leave the directory:
+\begin{verbatim}
+cd pafix/src
+make
+cd ..
+\end{verbatim}
+\item Create a copy of the input file:
+\begin{verbatim}
+cp input/input_example.dat input/input.dat
+\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{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, additional \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 as the \textit{*.vtk} files 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.
+
+\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}.
+}
+
+\section{Release history}
+
+pafiX is released and versioned through git and gitlab.
+
+In case of bugs, questions or requests for new features or other architectures please contact H.~Grosshans (holger.grosshans@ptb.de).
+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 ongoing maintenance.
+
+{\setlength{\bibsep}{1pt} \small
+%\bibliographystyle{unsrtnat}
+\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)