Commit cb12dfd5 authored by Dave Moxey's avatar Dave Moxey

Merge branch 'feature/documentation-updates' into 'master'

Feature/documentation updates

See merge request nektar/nektar!1051
parents bfbc57f4 09bcc658
......@@ -201,6 +201,8 @@ v5.0.0
**Documentation**:
- Added an initial developer's guide (!1001)
- Updated user guide to reflect current implementation (!1051)
- Added manpages for key solvers and utilities (!1051)
**Tester**
- Fix build with boost 1.67 (!947)
......
......@@ -200,6 +200,91 @@ development team using the {\nek} gitlab website:
Submitting a merge request will automatically trigger the continuous integration (CI) system, which will build and test your code on a range of platforms. You can monitor the progress of these tests from the merge request page. Selecting individual workers will take you to the buildbot website from which you can examine any failures which have occurred.
\section{Documentation and Tutorials}
Documentation for Nektar++ is provided in a number of forms:
\begin{itemize}
\item User Guide (LaTeX, compiled to pdf or html)
\item Source code documentation (Doxygen compiled to html)
\end{itemize}
\subsection{Dependencies}
To build the User Guide and Developer's Guide, the following dependencies are required:
\begin{itemize}
\item texlive-base
\item texlive-latex-extra
\item texlive-science
\item texlive-fonts-recommended
\item imagemagick
\end{itemize}
\subsection{Compiling the User Guide}
To compile the User Guide:
\begin{enumerate}
\item Configure the Nektar++ build tree as normal.
\item Run
\begin{lstlisting}[style=BashInputStyle]
make user-guide-pdf
\end{lstlisting}
to make the PDF version, or run
\begin{lstlisting}[style=BashInputStyle]
make user-guide-html
\end{lstlisting}
to make the HTML version.
\end{enumerate}
\subsection{Developers Guide}
To compile the Developer's Guide:
\begin{enumerate}
\item Configure the Nektar++ build tree as normal.
\item Run
\begin{lstlisting}[style=BashInputStyle]
make developers-guide-pdf
\end{lstlisting}
to make the PDF version, or run
\begin{lstlisting}[style=BashInputStyle]
make developers-guide-html
\end{lstlisting}
to make the HTML version.
\end{enumerate}
\subsection{Compiling the code documentation}
To build the Doxygen documentation, the following dependencies are required:
\begin{itemize}
\item doxygen
\item graphviz
\end{itemize}
To compile the code documentation enable the \inltt{NEKTAR\_BUILD\_DOC} option
in the \inlsh{ccmake} configuration tool.
You can then compile the HTML code documentation using:
\begin{lstlisting}[style=BashInputStyle]
make doc
\end{lstlisting}
\section{Compiling Tutorials}
If you are using a clone of the \nekpp git repository, you can also download
the source for the \nekpp tutorials which is available as a \emph{git submodule}.
\begin{enumerate}
\item From a \nekpp working directory (e.g. \inlsh{\$NEKPP}):
\begin{lstlisting}[style=BashInputStyle]
git submodule init
git submodule update --remote
\end{lstlisting}
\item From your build directory (e.g. \inlsh{\$NEKPP/build}), re-run \inlsh{cmake} to update the build system to include the tutorials
\begin{lstlisting}[style=BashInputStyle]
cmake ../
\end{lstlisting}
\item Compile each required tutorial, for example
\begin{lstlisting}[style=BashInputStyle]
make flow-stability-channel
\end{lstlisting}
\end{enumerate}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
......
.\" Manpage for ADRSolver
.\" Contact c.cantwell@imperial.ac.uk to correct errors or typos
.TH man 1 "07 Aug 2019" "5.0" "ADRSolver man page"
.SH NAME
ADRSolver \- solves Advection-diffusion-reaction problems
.SH SYNOPSIS
ADRSolver [ option(s) ] [ [ session.xml ] ... ]
.SH DESCRIPTION
.B ADRSolver
solves Advection-diffusion-reaction type partial differential
equations using the spectral/hp element method. It is built on the
.B Nektar++
high-order spectral/hp element framework.
The
.B ADRSolver
can solve a range of steady and unsteady scalar problems:
.IP \(em 3
Projection
.IP \(em 3
Laplace equation
.IP \(em 3
Poisson equation
.IP \(em 3
Helmholtz equation
.IP \(em 3
Steady Advection-Diffusion equation (2D only)
.IP \(em 3
Steady Diffusion-Reaction equation (2D only)
.IP \(em 3
Steady Advection-Diffusion-Reaction equation (2D only)
.IP \(em 3
Unsteady Advection equation
.IP \(em 3
Unsteady Diffusion equation
.IP \(em 3
Unsteady Reaction-Diffusion equation (Continuous Galerkin only)
.IP \(em 3
Unsteady Advection-Diffusion equation
.IP \(em 3
Unsteady Inviscid Burgers equation
.SS Further information
For further details and specific configuration options, please consult the
.B Nektar++ user guide
available from the website \(la www.nektar.info \(ra.
.SH OPTIONS
.SS General Options
.TP 4
.B \-h [ \-\-help ]
.TP 4
.B \-I [ \-\-solverinfo ] arg
Overrides a SOLVERINFO property in the XML input files.
.TP 4
.B \-P [ \-\-parameter ] arg
Overrides a PARAMETER in the XML input files.
.TP 4
.B \-v [ \-\-verbose ]
Displays additional diagnostic information during the solver execution.
.TP 4
.B \-V [ \-\-version ]
Prints the version of the Nektar++.
.SS Parallelisation Options
.TP 4
.B \-\-npx arg
Specifies the number of processes in the x-direction.
.TP 4
.B \-\-npy arg
Specifies the number of processes in the y-direction.
.TP 4
.B \-\-npz arg
Specifies the number of processes in the z-direction.
.TP 4
.B \-\-part-info
Output partition information.
.TP 4
.B \-\-part-only N
Partitions the input mesh into N partitions and exits.
.TP 4
.B \-\-part-only-overlapping N
Partitions mesh into N overlapping partitions and exits.
.TP 4
.B \-\-use-ptscotch
Use PT-Scotch for parallel mesh partitioning.
.TP 4
.B \-\-use-scotch
Use Scotch for mesh partitioning.
.SH EXAMPLE
To run the solver on a single input file which contains both the geometry and
the solver parameter specifications
.RS
.B ADRSolver session.xml
.RE
It is often helpful to separate the geometry specification from the remaining
solver parameters. In this case multiple .xml files may be provided
.RS
.B ADRSolver session.xml conditions.xml
.RE
.SH BUGS
No known bugs.
.SH AUTHOR
Chris Cantwell (c.cantwell@imperial.ac.uk)
.\" Manpage for AcousticSolver
.\" Contact c.cantwell@imperial.ac.uk to correct errors or typos
.TH man 1 "07 Aug 2019" "5.0" "AcousticSolver man page"
.SH NAME
AcousticSolver \- predicts acoustic wave propagation
.SH SYNOPSIS
AcousticSolver [ option(s) ] [ [ session.xml ] ... ]
.SH DESCRIPTION
.B AcousticSolver
predicts acoustic wave propagation using the spectral/hp element method. It is built on the
.B Nektar++
high-order spectral/hp element framework. It utilises a splitting technique
which decouples the flow-induced acoustic field from the underlying hydrodynamic
field.
The
.B AcousticSolver
can solve two types of problems:
.IP \(em 3
Linearised Euler Equations
.IP \(em 3
Acoustic Perturbation Equations (APE-1/APE-4)
.SS Further information
For further details and specific configuration options, please consult the
.B Nektar++ user guide
available from the website \(la www.nektar.info \(ra.
.SH OPTIONS
.SS General Options
.TP 4
.B \-h [ \-\-help ]
.TP 4
.B \-I [ \-\-solverinfo ] arg
Overrides a SOLVERINFO property in the XML input files.
.TP 4
.B \-P [ \-\-parameter ] arg
Overrides a PARAMETER in the XML input files.
.TP 4
.B \-v [ \-\-verbose ]
Displays additional diagnostic information during the solver execution.
.TP 4
.B \-V [ \-\-version ]
Prints the version of the Nektar++.
.SS Parallelisation Options
.TP 4
.B \-\-npx arg
Specifies the number of processes in the x-direction.
.TP 4
.B \-\-npy arg
Specifies the number of processes in the y-direction.
.TP 4
.B \-\-npz arg
Specifies the number of processes in the z-direction.
.TP 4
.B \-\-part-info
Output partition information.
.TP 4
.B \-\-part-only N
Partitions the input mesh into N partitions and exits.
.TP 4
.B \-\-part-only-overlapping N
Partitions mesh into N overlapping partitions and exits.
.TP 4
.B \-\-use-ptscotch
Use PT-Scotch for parallel mesh partitioning.
.TP 4
.B \-\-use-scotch
Use Scotch for mesh partitioning.
.SH EXAMPLE
To run the solver on a single input file which contains both the geometry and
the solver parameter specifications
.RS
.B AcousticSolver session.xml
.RE
It is often helpful to separate the geometry specification from the remaining
solver parameters. In this case multiple .xml files may be provided
.RS
.B AcousticSolver session.xml conditions.xml
.RE
.SH BUGS
No known bugs.
.SH AUTHOR
Chris Cantwell (c.cantwell@imperial.ac.uk)
.\" Manpage for CardiacEPSolver
.\" Contact c.cantwell@imperial.ac.uk to correct errors or typos
.TH man 1 "07 Aug 2019" "5.0" "CardiacEPSolver man page"
.SH NAME
CardiacEPSolver \- solves models of action potential propagation
.SH SYNOPSIS
CardiacEPSolver [ option(s) ] [ [ session.xml ] ... ]
.SH DESCRIPTION
.B CardiacEPSolver
solves models of action potential propagation in cardiac tissue using the spectral/hp element method. It is built on the
.B Nektar++
high-order spectral/hp element framework. These models are continuum models and
represent the average of electrical activity over many cells. They are
reaction-diffusion systems, where the reaction terms models the flow of ions in
and out of a cell as a system of ordinary differential equations.
The
.B CardiacEPSolver
can solve the following models
.RS
.IP \(em 3
Monodomain equation
.IP \(em 3
Bidomain equation
.RE
These are coupled to a model of the cardiac action potential. Available models
include:
.RS
.IP \(em 3
Aliev-Panfilov
.IP \(em 3
Courtemanche-Ramirez-Nattel
.IP \(em 3
Fenton-Karma
.IP \(em 3
Fitzhugh-Nagumo
.IP \(em 3
Luo-Rudy
.IP \(em 3
Ten-Tusscher
.RE
among others.
.SS Further information
For further details and specific configuration options, please consult the
.B Nektar++ user guide
available from the website \(la www.nektar.info \(ra.
.SH OPTIONS
.SS General Options
.TP 4
.B \-h [ \-\-help ]
.TP 4
.B \-I [ \-\-solverinfo ] arg
Overrides a SOLVERINFO property in the XML input files.
.TP 4
.B \-P [ \-\-parameter ] arg
Overrides a PARAMETER in the XML input files.
.TP 4
.B \-v [ \-\-verbose ]
Displays additional diagnostic information during the solver execution.
.TP 4
.B \-V [ \-\-version ]
Prints the version of the Nektar++.
.SS Parallelisation Options
.TP 4
.B \-\-npx arg
Specifies the number of processes in the x-direction.
.TP 4
.B \-\-npy arg
Specifies the number of processes in the y-direction.
.TP 4
.B \-\-npz arg
Specifies the number of processes in the z-direction.
.TP 4
.B \-\-part-info
Output partition information.
.TP 4
.B \-\-part-only N
Partitions the input mesh into N partitions and exits.
.TP 4
.B \-\-part-only-overlapping N
Partitions mesh into N overlapping partitions and exits.
.TP 4
.B \-\-use-ptscotch
Use PT-Scotch for parallel mesh partitioning.
.TP 4
.B \-\-use-scotch
Use Scotch for mesh partitioning.
.SH EXAMPLE
To run the solver on a single input file which contains both the geometry and
the solver parameter specifications
.RS
.B CardiacEPSolver session.xml
.RE
It is often helpful to separate the geometry specification from the remaining
solver parameters. In this case multiple .xml files may be provided
.RS
.B CardiacEPSolver session.xml conditions.xml
.RE
.SH BUGS
No known bugs.
.SH AUTHOR
Chris Cantwell (c.cantwell@imperial.ac.uk)
.\" Manpage for CompressibleFlowSolver
.\" Contact c.cantwell@imperial.ac.uk to correct errors or typos
.TH man 1 "07 Aug 2019" "5.0" "CompressibleFlowSolver man page"
.SH NAME
CompressibleFlowSolver \- solves unsteady compressible flow problems
.SH SYNOPSIS
CompressibleFlowSolver [ option(s) ] [ [ session.xml ] ... ]
.SH DESCRIPTION
.B CompressibleFlowSolver
solves the unsteady compressible Euler or Navier-Stokes equations, in a
discontinuous Galerkin formulation, using the
spectral/hp element method. It is built on the
.B Nektar++
high-order spectral/hp element framework.
.SS Further information
For further details and specific configuration options, please consult the
.B Nektar++ user guide
available from the website \(la www.nektar.info \(ra.
.SH OPTIONS
.SS General Options
.TP 4
.B \-h [ \-\-help ]
.TP 4
.B \-I [ \-\-solverinfo ] arg
Overrides a SOLVERINFO property in the XML input files.
.TP 4
.B \-P [ \-\-parameter ] arg
Overrides a PARAMETER in the XML input files.
.TP 4
.B \-v [ \-\-verbose ]
Displays additional diagnostic information during the solver execution.
.TP 4
.B \-V [ \-\-version ]
Prints the version of the Nektar++.
.SS Parallelisation Options
.TP 4
.B \-\-npx arg
Specifies the number of processes in the x-direction.
.TP 4
.B \-\-npy arg
Specifies the number of processes in the y-direction.
.TP 4
.B \-\-npz arg
Specifies the number of processes in the z-direction.
.TP 4
.B \-\-part-info
Output partition information.
.TP 4
.B \-\-part-only N
Partitions the input mesh into N partitions and exits.
.TP 4
.B \-\-part-only-overlapping N
Partitions mesh into N overlapping partitions and exits.
.TP 4
.B \-\-use-ptscotch
Use PT-Scotch for parallel mesh partitioning.
.TP 4
.B \-\-use-scotch
Use Scotch for mesh partitioning.
.SH EXAMPLE
To run the solver on a single input file which contains both the geometry and
the solver parameter specifications
.RS
.B CompressibleFlowSolver session.xml
.RE
It is often helpful to separate the geometry specification from the remaining
solver parameters. In this case multiple .xml files may be provided
.RS
.B CompressibleFlowSolver session.xml conditions.xml
.RE
.SH BUGS
No known bugs.
.SH AUTHOR
Chris Cantwell (c.cantwell@imperial.ac.uk)
.\" Manpage for FieldConvert
.\" Contact c.cantwell@imperial.ac.uk to correct errors or typos
.TH man 1 "07 Aug 2019" "5.0" "FieldConvert man page"
.SH NAME
FieldConvert \- post-process Nektar++ field files
.SH SYNOPSIS
FieldConvert [ option(s) ] input output
.SH DESCRIPTION
.B FieldConvert
is a utility primarily for the conversion of
.B Nektar++
output binary files into a range of other visualisation formats for analysis.
It is built on the
.B Nektar++
high-order spectral/hp element framework.
It also includes a range of modules for manipulating the output, such as
computing derived fields, extracting planes and isosurfaces or interpolating
onto other grids or point distributions.
.SS Further information
For further details and specific configuration options, please consult the
.B Nektar++ user guide
available from the website \(la www.nektar.info \(ra.
.SH OPTIONS
.SS General Options
.TP 4
.B \-h [ \-\-help ]
Print the help message.
.TP 4
.B \-r [ \-\-range ] arg
Define output range to process, where
.I arg
is specified as
.I xmin,xmax,ymin,ymax,zmin,zmax
.TP 4
.B \-v [ \-\-verbose ]
Displays additional diagnostic information during the solver execution.
.TP 4
.B \-V [ \-\-version ]
Prints the version of the Nektar++.
.SS Modules and Module Options
.TP 4
.B \-l [ \-\-modules-list ]
Print the list of available modules.
.TP 4
.B \-m [ \-\-module ] arg
Specify module to be used.
.TP 4
.B \-p [ \-\-modules-opt ] arg
Print options for the module given by
.I arg
.SS Advanced Options
.TP 4
.B \-e [ \-\-error ]
Write error of fields for regression checking.
.TP 4
.B \-f [ \-\-forceoutput ]
Force the output to be written without any checks.
.TP 4
.B \-n [ \-\-output-points ] arg
Output at n equispaced points along the collapsed coordinate (for .dat, .vtu).
.TP 4
.B \-\-noequispaced
Do not use equispaced output.
.TP 4
.B \-\-onlyshape arg
Only use element with defined shape, where
.I arg
is, for example,
.I Tetrahedron
.TP 4
.B \-\-output-points-hom-z arg
Specify number of planes in the z-direction for output of Homogeneous 1D
expansions (for .dat, .vtu).
.TP 4
.B \-\-useSessionVariables
Use variables defined in session for output.
.TP 4
.B \-\-useSessionExpansion
Use expansion defined in session.
.SS Parallelisation Options
.TP 4
.B \-\-nparts arg
Process partitions of parallel run in serial. The
.I arg
parameter specifies the number of partitions in the input field file.
.TP 4
.B \-\-npz arg
Specifies the number of processes in the z-direction.
.TP 4
.B \-\-part-only N
Partitions the input mesh into N partitions and exits.
.TP 4
.B \-\-part-only-overlapping N
Partitions mesh into N overlapping partitions and exits.
.TP 4
.B \-\-use-ptscotch
Use PT-Scotch for parallel mesh partitioning.
.TP 4
.B \-\-use-scotch
Use Scotch for mesh partitioning.
.SH EXAMPLE
To compute the vorticity field
.RS
.B FieldConvert -m vorticity in.xml in.fld out_vorticity.fld
.RE
To convert a field file to an unstructured VTK file
.RS
.B FieldConvert in.xml in.fld out.vtu
.RE
To compute vorticity and write output to an unstructured VTK file
.RS
.B FieldConvert -m vorticity in.xml in.fld out_vorticity.vtu
.RE
.SH BUGS
No known bugs.
.SH AUTHOR
Chris Cantwell (c.cantwell@imperial.ac.uk)
.\" Manpage for IncNavierStokesSolver
.\" Contact c.cantwell@imperial.ac.uk to correct errors or typos
.TH man 1 "07 Aug 2019" "5.0" "IncNavierStokesSolver man page"
.SH NAME
IncNavierStokesSolver \- solves incompressible flow problems
.SH SYNOPSIS
IncNavierStokesSolver [ option(s) ] [ [ session.xml ] ... ]
.SH DESCRIPTION
.B IncNavierStokesSolver
solves the incompressible form of the Navier-Stokes partial differential
equations using the spectral/hp element method. It is built on the
.B Nektar++
high-order spectral/hp element framework.
The
.B IncNavierStokesSolver
uses a velocity-correction splitting scheme to reduce the solution of a vector
form of the Navier-Stokes equations to a series of scalar problems. The
non-linear advection terms are evaluated, followed by solving a pressure Poisson
problem. Finally, a set of Helmholtz problems are solved to correct the velocity
for the computed pressure field. The solver uses a semi-implicit
time-integration scheme with the advection term evaluated explicitly and the
Poisson and Helmholtz problems being evaluated implicitly.
.SS Further information
For further details and specific configuration options, please consult the
.B Nektar++ user guide
available from the website \(la www.nektar.info \(ra.
.SH OPTIONS
.SS General Options
.TP 4
.B \-h [ \-\-help ]
.TP 4
.B \-I [ \-\-solverinfo ] arg
Overrides a SOLVERINFO property in the XML input files.
.TP 4
.B \-P [ \-\-parameter ] arg
Overrides a PARAMETER in the XML input files.
.TP 4
.B \-v [ \-\-verbose ]
Displays additional diagnostic information during the solver execution.
.TP 4
.B \-V [ \-\-version ]
Prints the version of the Nektar++.
.SS Parallelisation Options
.TP 4
.B \-\-npx arg
Specifies the number of processes in the x-direction.
.TP 4
.B \-\-npy arg
Specifies the number of processes in the y-direction.
.TP 4
.B \-\-npz arg
Specifies the number of processes in the z-direction.
.TP 4
.B \-\-part-info
Output partition information.
.TP 4
.B \-\-part-only N
Partitions the input mesh into N partitions and exits.
.TP 4
.B \-\-part-only-overlapping N
Partitions mesh into N overlapping partitions and exits.
.TP 4
.B \-\-use-ptscotch
Use PT-Scotch for parallel mesh partitioning.
.TP 4
.B \-\-use-scotch
Use Scotch for mesh partitioning.
.SH EXAMPLE
To run the solver on a single input file which contains both the geometry and
the solver parameter specifications
.RS
.B IncNavierStokesSolver session.xml
.RE
It is often helpful to separate the geometry specification from the remaining
solver parameters. In this case multiple .xml files may be provided
.RS
.B IncNavierStokesSolver session.xml conditions.xml
.RE
.SH BUGS
No known bugs.
.SH AUTHOR
Chris Cantwell (c.cantwell@imperial.ac.uk)
.\" Manpage for ADRSolver
.\" Contact c.cantwell@imperial.ac.uk to correct errors or typos
.TH man 1 "07 Aug 2019" "5.0" "NekMesh man page"
.SH NAME
NekMesh \- generates, converts and manipulates high-order meshes
.SH SYNOPSIS
.B NekMesh
[option(s)] input output
.SH DESCRIPTION
.B NekMesh
is a high-order finite element mesh generator and general pre-processing
mesh utility, that can be used to either generate meshes directly from an
underlying CAD representation of a geometry, or alternatively to import and
process linear meshes from a range of other mesh generation tools to make them
suitable for high-order simulations.
.B NekMesh
is designed around the concept of modules that run sequentially in a
pipeline.
.B Input modules
read either a file from an external mesh generation utility, or a
.B NekMesh
.B .mcf
mesh configuration file which can be used to read CAD geometry. The input module
is selected based on the input filename.
Optionally, one or more
.B processing modules
can be used to modify the mesh in some way, for e.g. the creation of boundary
layers or the optimisation of the input mesh. Finally, a
.B output module
is used to write out the resulting mesh, depending on the extension of the
filename. All modules typically support a number of options that can be defined
on the command line.
.SH OPTIONS
.TP 4
.B \-h [ \-\-help ]
Prints a help message and program synopsys.
.TP 4
.B \-l [ \-\-modules-list ]
Prints a list of all input, processing and output modules that can be used
within NekMesh.
.TP 4
.B \-p [ \-\-modules-opt ] module
Prints the list of options for a given module.
.TP 4
.B \-m [ \-\-module ] module
Specifies a module to be used. Modules are run in the order that they are
defined in the command line options.
.TP 4
.B \-v [ \-\-verbose ]
Print additional debugging and mesh generation information to screen.
.SH BUGS
No known bugs.