Skip to content
Snippets Groups Projects
Commit c7657965 authored by OObukohwo's avatar OObukohwo
Browse files

Updates user guide

parent 505b8e60
No related branches found
No related tags found
1 merge request!4Updates user guide
Hide whitespace changes
Inline Side-by-side
.DS_Store 0 → 100644
+ 0
− 0
View file @ c7657965
File added
documentation/.DS_Store 0 → 100644
+ 0
− 0
View file @ c7657965
File added
documentation/userGuide/pafiX_userGuide.pdf 100755 → 100644
+ 0
− 0
View file @ c7657965
No preview for this file type
documentation/userGuide/pafiX_userGuide.tex
+ 224
− 222
View file @ c7657965
\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}
\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}
Currently, one case is released, and more releases are planned in the future.
The pafiX release history is given in Table~\ref{tab:release}.
\begin{table}[h]
\caption{Release history.} % \cite{Gro19a}
\begin{center}
\label{tab:release}
\begin{tabular}[t]{p{2.3cm} p{12.4cm}}
\hline
Version & pafiX \\
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 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}
\noindent 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}
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment