% I still maintain the ``old'' Peano in the repository (version 3), and most users
% consider this to be the standard Peano generation.
% For the present document, it is thus important that you manually switch to the
% branch \texttt{p4}.
% \end{remark}
%
%
%
% \section{Prepare the configure environment}
%
% This step should only required if you work directly against the git repository.
% If you prefer to download a snapshot of \Peano, then you can skip this section
% and continue with \ref{section:installation:configure}.
%
%
% \begin{itemize}
% \item Ensure you have the autotool packages installed on your system. They
% typically are shipped in the packages \texttt{autoconf}, \texttt{automake} and
% \texttt{libtool}.
% \item Set up the configure environment:
% \begin{code}
% libtoolize; aclocal; autoconf; autoheader;
% cp src/config.h.in .;
% automake --add-missing
% \end{code}
% \end{itemize}
%
%
% \noindent
% These steps should only be required once, unless you push major revisions to the
% development branch.
%
%
% \section{Configure}
% \label{section:installation:configure}
%
%
% \Peano\ relies on the autotools to set up its build environment.
% Change into the project's directory and type in
% \begin{code}
% ./configure --help
% \end{code}
%
%
% The \texttt{--help} option should give you some information about the available
% variants of \Peano.
% In principle, a sole \texttt{./configure} call is sufficient, but you might want
% to adopt your build; notably as the default build is serial and does not bring
% along any support for postprocessing.
% While the help output should be reasonable verbose, I summarise key options
% below:
%
% \begin{center}
% \begin{tabular}{lp{10cm}}
% \texttt{--prefix=/mypath} & Will install \Peano\ in \texttt{/mypath}.
% \\
% \texttt{--with-multithreading} & Switch on multithreading. By default, we
% build without multithreading, but a \texttt{--with-multithreading=cpp}, e.g.,
% makes \Peano\ use the C++ threading model. Please consult \texttt{--help} for
% details. Note: To use OpenMP multithreading, you will need a compiler which
% supports OpenMP 5.0 (e.g - GCC 9.x).
% \\
% \texttt{--with-mpi} & Enable the MPI version of \Peano. You have to tell the
% build environment however which compile command to use. Please note that
% we need a C++ MPI wrapper. So \texttt{--with-mpi=mpcxx} is a typical call.
% \\
% \texttt{--with-vtk} & Inform \Peano\ that VTK is available on the system.
% \Peano\ mainly
% relies on its own IO data format. Even some VTK dump routines (used usually
% only for debugging) are written by hand, i.e.~do not rely on the VTK
% libraries.
% However, \Peano\ comes along with some command line conversion tools that can convert its tailored data
% dumps into VTK, and they do rely on the VTK libraries. With this flag, you
% tell \Peano\ to build these tools.
% The VTK installation is sometimes not easy (and you might have to provide additional parameters depending on your installation). I dedicate Chapter \ref{chapter:vtk} on VTK.
% \\
% \texttt{--with-hdf5} & Make \Peano\ support HDF5 output. Not stable at the
% moment.
% \\
% \texttt{--with-delta} & Configure \Peano\ such that the geometry library
% $\Delta $ is used. Not stable at the moment.
% \end{tabular}
% \end{center}
%
%
% \begin{remark}
% I recommend that you start a first test without any additional flavours of
% \Peano, i.e.~to work with a plain \texttt{./configure} call. Once the tests
% pass, I recommend that you first add IO (VTK) and then parallelisation.
% \end{remark}
%
%
% \noindent
% Compilers, linkers and both compiler and linker flags can be changed by
% resetting the corresponding environment variables \emph{prior} to the configure
% call.
% Alternatively, you can pass the variables to be used to \texttt{configure}
% through arguments.
% Please consult the \texttt{--help} output for details.
% For some supercomputers that we use frequently, there are recommendations which
% setting to use (Chapter~\ref{chapter:selected-HPC-platforms}).
%
%
%
% \section{Build}
%
% Once the configuration has been successful, a simple
% \begin{code}
% make
% \end{code}
% should build the \Peano\ core and some examples.
%
%
% \begin{code}
% make install
% \end{code}
% finally will deploy the \Peano\ files in the directory specified via the
% \texttt{prefix} before.
% If you haven't set the prefix, then the default will likely be a system
% directory.
% Unless you have superuser rights, the installation then will fail.
% So I recommend that you install \Peano\ into a local directory specifying it via
% the \texttt{--with-prefix} option.
%
%
% \begin{remark}
% To develop with \Peano, you don't have to install it. You can instead just skip
% the installation and work in the download directory.
% \end{remark}
%
%
%
%
% \section{Installation test}
%
% Once you have compiled \Peano\, I recommend that you run all tests using
%
% \begin{code}
% make check
% \end{code}
% or to run 2D and 3D tests individually, use
%
% \begin{code}
% src/examples/unittests/UnitTests2d
% src/examples/unittests/UnitTests3d
% \end{code}
%
% \noindent
% You can run these builds with different core counts and also MPI support if you
% have compiled with MPI.
% The executables contain both node correctness tests and MPI ping-pong tests,
% i.e.~you can both assess a valid build plus a working MPI environment.
%
%
%
% \section{Python configuration}
%
% \Peano\ is developed with Python 3. Python 2 is not supported.
% To make any Python example pass, you have to set the Python paths.
% There are multiple ways to do so.
%
% The standard way is to set the \texttt{PYTHONPATH}:
% \begin{code}
% export PYTHONPATH=myPeanoDirectory/python
% \end{code}
% This can even be done in the \texttt{.bashrc}.
%
% Alternatively, you can augment your Python scripts later on with
% \begin{code}
% import sys
% PEANO4_PYTHON_DIR="myPeanoDirectory/python"
% sys.path.append(PEANO4_PYTHON_DIR)
% \end{code}
%
%
% \noindent
% Please note that most Python scripts require you to set the
% \texttt{LD\_LIBRARY\_PATH}.
% If you install \Peano, then this path should be automatically right.
% If you work with a local \Peano\ installation, you can either tell \Peano\
% through its API where to search for the library (all routines that add a
% library accept additional search paths), or you can again use the
% \texttt{sys.path.append} command to extend \texttt{LD\_LIBRARY\_PATH}.
%
%
% \begin{remark}
% I personally prefer the variant to go through the environment variable.
% \Peano's Python API yield plain old makefiles building executables that work
% completely without any Python.
% This way, we ensure that we work smoothly on supercomputers, too, where Python
% sometimes is not available in the latest version or on the compute nodes.
% As long as you run through environment variables or the \Peano\ routines to
% specify paths, your makefiles also will continue to work that way.
% \end{remark}
%
%
%
% \section{Fortran}
%
% \begin{remark}
% If you don't use Fortran in your own code, ignore this section.
% \end{remark}
%
% \Peano's core does not use any Fortran at all.
% However, many users use Fortran for their domain-specific programming.
% If you want to have a seemless integration of your particular Fortran choice
% through \Peano's Python API, invoke \texttt{./configure} ensuring that the
% Fortran variables---in particular the environment variable \texttt{FC}
% identifying the compiler---are properly set.
%
%
% For many codes and the GNU Fortran compiler, you need the flag
% \texttt{-fdefault-real-8}.
% You can export \texttt{FCFLAGS} and make it contain this argument before you
% invoke \texttt{configure}.
% As the \Peano's core does not use Fortran---it is only applications built on top
% of \Peano---you can redefine the flags later on (see \ref{section:installation:applications-built-with-Peano}).
%
%
%
% \section{\Peano\ components and build variants}
% \label{chapter:installation:build-variants}
%
% \Peano\ currently is delivered as a set of archives, i.e.~static libraries:
% \begin{itemize}
% \item There is a technical architecture (\texttt{Tarch}) and the actual
% \texttt{Peano4Core}.
% \item Each archive variant is available as a release version, as a debug
% version, as a version with tracing and assertions and as a tracing-only
% version.
% \item Each archive variant is available as 2d build and as 3d build. If you
% need higher dimensions, you have to build the required libraries manually.
% \end{itemize}
%
%
% The version terminology is as follows:
% \begin{itemize}
% \item {\bf debug} The debug versions of the archives all have the postfix
% \texttt{\_debug}. If you link against these versions, the full set of
% assertions, of all tracing and all debug messages is available; though you can
% always filter on the application-level which information you want to see
% (cmp.~Chapter \ref{section:logging}).
% \item {\bf asserts} Thsee versions of the archives all have the postfix
% \texttt{\_asserts}. If you link against these versions, all assertions are on.
% The code also contains tracing macros (see below).
% \item {\bf tracing} The release versions of the archives all have the postfix
% \texttt{\_trace}. If you link against these versions, all assertions and debug
% messages are removed, but some tracing is active. You can switch on/off the
% tracing per class (cmp.~Chapter \ref{section:logging}), and different tracing
% backends allow you to connect to different (profiling) tools.
% \item {\bf release} The release versions of the archives have no
% particular postfix. They disable tracing, any debugging and all assertions.
% These archives should be used by production runs.
% \end{itemize}
%
%
% \begin{remark}
% Peano's release components still write info messages (they suppress debug,
% tracing and logging, but not essential information). If you want to filter out
% these messages, too, you have to apply a log filter (Chapter
% \ref{section:logging:log-filter}).
% \end{remark}
%
%
% \noindent
% Besides these archives, the \Peano\ installation also comes along with a set of
% example applications.
% They are found in the directory \texttt{src/examples}.
% Most examples create by default two variants of the example: a debug
% version and one with only tracing enabled.
% Several examples furthermore come along as 2d and 3d build.
