\chapter{Example programs }
\hypertarget{Examples}{}\label{Examples}\index{Example programs@{Example programs}}
Here you can find example programs that demonstrate the usage of Ginkgo.

Some examples are built on one another and some are stand-\/alone and demonstrate a concept of Ginkgo, which can be used in your own code.

You can browse the available example programs 
\begin{DoxyEnumerate}
\item as {\bfseries{\href{\#graph}{\texttt{a graph}}}} that shows how example programs build upon each other. 
\item as {\bfseries{\href{\#list}{\texttt{a list}}}} that provides a short synopsis of each program. 
\item or {\bfseries{\href{\#topic}{\texttt{grouped by topic}}}}. 
\end{DoxyEnumerate}

By default, all Ginkgo examples are built using CMake.

An example for building the examples and using Ginkgo as an external library without CMake can be found in the script provided for each example, which should be called with the form:\+ {\ttfamily ./\+build.sh PATH\+\_\+\+TO\+\_\+\+GINKGO\+\_\+\+BUILD\+\_\+\+DIR }

By default, Ginkgo is compiled with at least {\ttfamily -\/DGINKGO\+\_\+\+BUILD\+\_\+\+REFERENCE=ON}. Ginkgo also tries to detect your environment setup (presence of CUDA, ...) to enable the relevant accelerator modules. If you want to target a specific GPU, make sure that Ginkgo is compiled with the accelerator specific module enabled, such as:\+ 
\begin{DoxyEnumerate}
\item {\ttfamily -\/DGINKGO\+\_\+\+BUILD\+\_\+\+CUDA=ON} option for NVIDIA GPUs. 
\item {\ttfamily -\/DGINKGO\+\_\+\+BUILD\+\_\+\+HIP=ON} option for AMD or NVIDIA GPUs. 
\item {\ttfamily -\/DGINKGO\+\_\+\+BUILD\+\_\+\+SYCL=ON} option for Intel GPUs (and possibly any other platform). 
\end{DoxyEnumerate}

\label{Examples_graph}%
\Hypertarget{Examples_graph}%
 \label{Examples_ExampleConnectionGraph}%
\Hypertarget{Examples_ExampleConnectionGraph}%
 \doxysubsubsection*{Connections between example programs}

The following graph shows the connections between example programs and how they build on each other. Click on any of the boxes to go to one of the programs. If you hover your mouse pointer over a box, a brief description of the program should appear. 
\begin{DoxyImageNoCaption}%
  \doxymbox{\includegraphics[width=\textwidth,height=\textheight/2,keepaspectratio=true]{dot_inline_dotgraph_ec3e538546ccb8d568b6d6723c9caddf}}%
\end{DoxyImageNoCaption}


{\bfseries{Legend:\+}}~\newline
 
\begin{DoxyImageNoCaption}%
  \doxymbox{\includegraphics[width=\textwidth,height=\textheight/2,keepaspectratio=true]{dot_inline_dotgraph_f330efff3b6db15046814438f8c8c1f6}}%
\end{DoxyImageNoCaption}


\label{Examples_list}%
\Hypertarget{Examples_list}%
 \doxysubsubsection*{Example programs }


\begin{DoxyTable}{2}{}{}{0}
\doxysectlink{simple_solver}{The simple-\/solver program}{0}&A minimal CG solver in Ginkgo, which reads a matrix from a file. \\
\doxysectlink{minimal_cuda_solver}{The minimal-\/cuda-\/solver program}{0}&A minimal solver on the CUDA executor than can be run on NVIDIA GPU\textquotesingle{}s. \\
\doxysectlink{poisson_solver}{The poisson-\/solver program}{0}&Solve an actual physically relevant problem, the poisson problem. The matrix is generated within Ginkgo. \\
\doxysectlink{preconditioned_solver}{The preconditioned-\/solver program}{0}&Using a Jacobi preconditioner to solve a linear system. \\
\doxysectlink{ilu_preconditioned_solver}{The ilu-\/preconditioned-\/solver program}{0}&Using an ILU preconditioner to solve a linear system. \\
\doxysectlink{performance_debugging}{The performance-\/debugging program}{0}&Using Loggers to debug the performance within Ginkgo. \\
\doxysectlink{three_pt_stencil_solver}{The three-\/pt-\/stencil-\/solver program}{0}&Using a three point stencil to solve the poisson equation with array views. \\
\doxysectlink{nine_pt_stencil_solver}{The nine-\/pt-\/stencil-\/solver program}{0}&Using a nine point 2D stencil to solve the poisson equation with array views. \\
external\+\_\+lib\+\_\+interfacing&Using Ginkgo\textquotesingle{}s solver with the external library deal.\+II. \\
\doxysectlink{custom_logger}{The custom-\/logger program}{0}&Creating a custom logger specifically for comparing the recurrent and the real residual norms. \\
\doxysectlink{custom_matrix_format}{The custom-\/matrix-\/format program}{0}&Creating a matrix-\/free stencil solver by using Ginkgo\textquotesingle{}s advanced methods to build your own custom matrix format. \\
\doxysectlink{inverse_iteration}{The inverse-\/iteration program}{0}&Using Ginkgo to compute eigenvalues of a matrix with the inverse iteration method. \\
\doxysectlink{simple_solver_logging}{The simple-\/solver-\/logging program}{0}&Using the logging functionality in Ginkgo to get solver and other information to diagnose and debug your code. \\
\doxysectlink{papi_logging}{The papi-\/logging program}{0}&Using the PAPI logging library in Ginkgo to get advanced information about your code and its behaviour. \\
\doxysectlink{ginkgo_overhead}{The ginkgo-\/overhead program}{0}&Measuring the overhead of the Ginkgo library. \\
\doxysectlink{custom_stopping_criterion}{The custom-\/stopping-\/criterion program}{0}&Creating a custom stopping criterion for the iterative solution process. \\
\doxysectlink{ginkgo_ranges}{The ginkgo-\/ranges program}{0}&Using the ranges concept to factorize a matrix with the LU factorization. \\
\doxysectlink{mixed_spmv}{The mixed-\/spmv program}{0}&Shows the Ginkgo mixed precision spmv functionality. \\
\doxysectlink{mixed_precision_ir}{The mixed-\/precision-\/ir program}{0}&Manual implementation of a Mixed Precision Iterative Refinement (MPIR) solver. \\
\doxysectlink{adaptiveprecision_blockjacobi}{The adaptiveprecision-\/blockjacobi program}{0}&Shows how to use the adaptive precision block-\/\+Jacobi preconditioner. \\
\doxysectlink{cb_gmres}{The cb-\/gmres program}{0}&Using the Ginkgo CB-\/\+GMRES solver (Compressed Basis GMRES). \\
\doxysectlink{heat_equation}{The heat-\/equation program}{0}&Solving a 2D heat equation and showing matrix assembly, vector initialization and solver setup in a more complex setting with output visualization. \\
\doxysectlink{iterative_refinement}{The iterative-\/refinement program}{0}&Using a low accuracy CG solver as an inner solver to an iterative refinement (IR) method which solves a linear system. \\
\doxysectlink{ir_ilu_preconditioned_solver}{The ir-\/ilu-\/preconditioned-\/solver program}{0}&Combining iterative refinement with the adaptive precision block-\/\+Jacobi preconditioner to approximate triangular systems occurring in ILU preconditioning. \\
\doxysectlink{par_ilu_convergence}{The par-\/ilu-\/convergence program}{0}&Convergence analysis at the examples of parallel incomplete factorization solver. \\
\doxysectlink{preconditioner_export}{The preconditioner-\/export program}{0}&Explicit generation and storage of preconditioners for given matrices. \\
\doxysectlink{multigrid_preconditioned_solver}{The multigrid-\/preconditioned-\/solver program}{0}&Use multigrid as preconditioner to a solver. \\
\doxysectlink{mixed_multigrid_solver}{The mixed-\/multigrid-\/solver program}{0}&Use multigrid with different precision multigrid\+\_\+level as a solver. \\
\doxysectlink{distributed_solver}{The distributed-\/solver program}{0}&Use a distributed solver to solve a 1D Laplace equation. \\
\end{DoxyTable}


\label{Examples_topic}%
\Hypertarget{Examples_topic}%
 \doxysubsubsection*{Example programs grouped by topics}

\doxysubsubsubsection*{{\bfseries{Basic techniques}}}


\begin{DoxyTable}{2}{}{}{0}
Solving a simple linear system with choice of executors &\doxysectlink{simple_solver}{The simple-\/solver program}{0} \\
Debug the performance of a solver or preconditioner &\doxysectlink{performance_debugging}{The performance-\/debugging program}{0} \doxysectlink{preconditioner_export}{The preconditioner-\/export program}{0} \\
Using the CUDA executor &\doxysectlink{minimal_cuda_solver}{The minimal-\/cuda-\/solver program}{0} \\
Using preconditioners &\doxysectlink{preconditioned_solver}{The preconditioned-\/solver program}{0}, \doxysectlink{ilu_preconditioned_solver}{The ilu-\/preconditioned-\/solver program}{0}, \doxysectlink{ir_ilu_preconditioned_solver}{The ir-\/ilu-\/preconditioned-\/solver program}{0}, \doxysectlink{adaptiveprecision_blockjacobi}{The adaptiveprecision-\/blockjacobi program}{0}, \doxysectlink{par_ilu_convergence}{The par-\/ilu-\/convergence program}{0}, \doxysectlink{preconditioner_export}{The preconditioner-\/export program}{0} \doxysectlink{multigrid_preconditioned_solver}{The multigrid-\/preconditioned-\/solver program}{0} \\
Iterative refinement &\doxysectlink{iterative_refinement}{The iterative-\/refinement program}{0}, \doxysectlink{mixed_precision_ir}{The mixed-\/precision-\/ir program}{0}, \doxysectlink{ir_ilu_preconditioned_solver}{The ir-\/ilu-\/preconditioned-\/solver program}{0} \\
Solving a physically relevant problem &\doxysectlink{poisson_solver}{The poisson-\/solver program}{0}, \doxysectlink{three_pt_stencil_solver}{The three-\/pt-\/stencil-\/solver program}{0}, \doxysectlink{nine_pt_stencil_solver}{The nine-\/pt-\/stencil-\/solver program}{0}, \doxysectlink{custom_matrix_format}{The custom-\/matrix-\/format program}{0} \\
Reading in a matrix and right hand side from a file &\doxysectlink{simple_solver}{The simple-\/solver program}{0}, \doxysectlink{minimal_cuda_solver}{The minimal-\/cuda-\/solver program}{0}, \doxysectlink{preconditioned_solver}{The preconditioned-\/solver program}{0}, \doxysectlink{ilu_preconditioned_solver}{The ilu-\/preconditioned-\/solver program}{0}, \doxysectlink{inverse_iteration}{The inverse-\/iteration program}{0}, \doxysectlink{simple_solver_logging}{The simple-\/solver-\/logging program}{0}, \doxysectlink{papi_logging}{The papi-\/logging program}{0}, \doxysectlink{custom_stopping_criterion}{The custom-\/stopping-\/criterion program}{0}, \doxysectlink{custom_logger}{The custom-\/logger program}{0} \\
\end{DoxyTable}


\doxysubsubsubsection*{{\bfseries{Advanced techniques}}}


\begin{DoxyTable}{2}{}{}{0}
Using Ginkgo with external libraries &external\+\_\+lib\+\_\+interfacing \\
Customizing Ginkgo &\doxysectlink{custom_logger}{The custom-\/logger program}{0}, \doxysectlink{custom_stopping_criterion}{The custom-\/stopping-\/criterion program}{0}, \doxysectlink{custom_matrix_format}{The custom-\/matrix-\/format program}{0} \\
Writing your own matrix format &\doxysectlink{custom_matrix_format}{The custom-\/matrix-\/format program}{0} \\
Using Ginkgo to construct more complex linear algebra routines &\doxysectlink{inverse_iteration}{The inverse-\/iteration program}{0} \\
Logging within Ginkgo &\doxysectlink{simple_solver_logging}{The simple-\/solver-\/logging program}{0}, \doxysectlink{papi_logging}{The papi-\/logging program}{0}, \doxysectlink{performance_debugging}{The performance-\/debugging program}{0} \doxysectlink{custom_logger}{The custom-\/logger program}{0} \\
Constructing your own stopping criterion &\doxysectlink{custom_stopping_criterion}{The custom-\/stopping-\/criterion program}{0} \\
Using ranges in Ginkgo &\doxysectlink{ginkgo_ranges}{The ginkgo-\/ranges program}{0} \\
Mixed precision &\doxysectlink{mixed_spmv}{The mixed-\/spmv program}{0}, \doxysectlink{mixed_precision_ir}{The mixed-\/precision-\/ir program}{0}, \doxysectlink{adaptiveprecision_blockjacobi}{The adaptiveprecision-\/blockjacobi program}{0} \doxysectlink{mixed_multigrid_solver}{The mixed-\/multigrid-\/solver program}{0} \\
Multigrid &\doxysectlink{multigrid_preconditioned_solver}{The multigrid-\/preconditioned-\/solver program}{0} \doxysectlink{mixed_multigrid_solver}{The mixed-\/multigrid-\/solver program}{0} \\
Configure a solver from a config file &\doxysectlink{file_config_solver}{The file-\/config-\/solver program}{0} \\
Distributed &\doxysectlink{distributed_solver}{The distributed-\/solver program}{0} \\
\end{DoxyTable}
