add example how to use ParILU to generate an ILU-preconditioned solver

examples/CMakeLists.txt

@@ -7,6 +7,7 @@ if(GINKGO_BUILD_EXTLIB_EXAMPLE)
 endif()
 add_subdirectory(ginkgo-overhead)
 add_subdirectory(ginkgo-ranges)
+add_subdirectory(ilu-preconditioned-solver)
 add_subdirectory(inverse-iteration)
 add_subdirectory(minimal-cuda-solver)
 add_subdirectory(nine-pt-stencil-solver)

examples/ilu-preconditioned-solver/CMakeLists.txt

@@ -0,0 +1,6 @@
+add_executable(ilu-preconditioned-solver ilu-preconditioned-solver.cpp)
+target_link_libraries(ilu-preconditioned-solver ginkgo)
+target_include_directories(ilu-preconditioned-solver PRIVATE ${PROJECT_SOURCE_DIR})
+configure_file(data/A.mtx data/A.mtx COPYONLY)
+configure_file(data/b.mtx data/b.mtx COPYONLY)
+configure_file(data/x0.mtx data/x0.mtx COPYONLY)

examples/ilu-preconditioned-solver/build.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# set up script
+if [ $# -ne 1 ]; then
+    echo -e "Usage: $0 GINKGO_BUILD_DIRECTORY"
+    exit 1
+fi
+BUILD_DIR=$1
+THIS_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" &>/dev/null && pwd )
+
+# copy libraries
+LIBRARY_DIRS="core core/device_hooks reference omp cuda"
+LIBRARY_NAMES="ginkgo ginkgo_reference ginkgo_omp ginkgo_cuda"
+SUFFIXES=".so .dylib .dll d.so d.dylib d.dll"
+for prefix in ${LIBRARY_DIRS}; do
+    for name in ${LIBRARY_NAMES}; do
+        for suffix in ${SUFFIXES}; do
+            cp ${BUILD_DIR}/${prefix}/lib${name}${suffix} \
+                ${THIS_DIR}/lib${name}${suffix} 2>/dev/null
+        done
+    done
+done
+
+# figure out correct compiler flags
+if ls ${THIS_DIR} | grep -F "libginkgo." >/dev/null; then
+    LINK_FLAGS="-lginkgo -lginkgo_omp -lginkgo_cuda -lginkgo_reference"
+else
+    LINK_FLAGS="-lginkgod -lginkgo_ompd -lginkgo_cudad -lginkgo_referenced"
+fi
+if [ -z "${CXX}" ]; then
+    CXX="c++"
+fi
+
+# build
+${CXX} -std=c++11 -o ${THIS_DIR}/ilu-preconditioned-solver \
+    ${THIS_DIR}/ilu-preconditioned-solver.cpp \
+    -I${THIS_DIR}/../../include -I${BUILD_DIR}/include \
+    -L${THIS_DIR} ${LINK_FLAGS}

examples/ilu-preconditioned-solver/data/A.mtx

@@ -0,0 +1,114 @@
+%%MatrixMarket matrix coordinate integer symmetric
+%-------------------------------------------------------------------------------
+% UF Sparse Matrix Collection, Tim Davis
+% http://www.cise.ufl.edu/research/sparse/matrices/JGD_Trefethen/Trefethen_20b
+% name: JGD_Trefethen/Trefethen_20b
+% [Diagonal matrices with primes, Nick Trefethen, Oxford Univ.]
+% id: 2203
+% date: 2008
+% author: N. Trefethen
+% ed: J.-G. Dumas
+% fields: name title A id date author ed kind notes
+% kind: combinatorial problem
+%-------------------------------------------------------------------------------
+% notes:
+% Diagonal matrices with primes, Nick Trefethen, Oxford Univ.          
+% From Jean-Guillaume Dumas' Sparse Integer Matrix Collection,         
+% http://ljk.imag.fr/membres/Jean-Guillaume.Dumas/simc.html            
+%                                                                      
+% Problem 7 of the Hundred-dollar, Hundred-digit Challenge Problems,   
+% SIAM News, vol 35, no. 1.                                            
+%                                                                      
+% 7. Let A be the 20,000 x 20,000 matrix whose entries are zero        
+% everywhere except for the primes 2, 3, 5, 7, . . . , 224737 along the
+% main diagonal and the number 1 in all the positions A(i,j) with      
+% |i-j| = 1,2,4,8, . . . ,16384.  What is the (1,1) entry of inv(A)?   
+%                                                                      
+% http://www.siam.org/news/news.php?id=388                             
+%                                                                      
+% Filename in JGD collection: Trefethen/trefethen_20__19_minor.sms     
+%-------------------------------------------------------------------------------
+19 19 83
+1 1 3
+2 1 1
+3 1 1
+5 1 1
+9 1 1
+17 1 1
+2 2 5
+3 2 1
+4 2 1
+6 2 1
+10 2 1
+18 2 1
+3 3 7
+4 3 1
+5 3 1
+7 3 1
+11 3 1
+19 3 1
+4 4 11
+5 4 1
+6 4 1
+8 4 1
+12 4 1
+5 5 13
+6 5 1
+7 5 1
+9 5 1
+13 5 1
+6 6 17
+7 6 1
+8 6 1
+10 6 1
+14 6 1
+7 7 19
+8 7 1
+9 7 1
+11 7 1
+15 7 1
+8 8 23
+9 8 1
+10 8 1
+12 8 1
+16 8 1
+9 9 29
+10 9 1
+11 9 1
+13 9 1
+17 9 1
+10 10 31
+11 10 1
+12 10 1
+14 10 1
+18 10 1
+11 11 37
+12 11 1
+13 11 1
+15 11 1
+19 11 1
+12 12 41
+13 12 1
+14 12 1
+16 12 1
+13 13 43
+14 13 1
+15 13 1
+17 13 1
+14 14 47
+15 14 1
+16 14 1
+18 14 1
+15 15 53
+16 15 1
+17 15 1
+19 15 1
+16 16 59
+17 16 1
+18 16 1
+17 17 61
+18 17 1
+19 17 1
+18 18 67
+19 18 1
+19 19 71

examples/ilu-preconditioned-solver/data/b.mtx

@@ -0,0 +1,21 @@
+%%MatrixMarket matrix array real general
+19 1
+1
+1
+1
+1
+1
+1
+1
+1
+1
+1
+1
+1
+1
+1
+1
+1
+1
+1
+1

examples/ilu-preconditioned-solver/data/x0.mtx

@@ -0,0 +1,21 @@
+%%MatrixMarket matrix array real general
+19 1
+0
+0
+0
+0
+0
+0
+0
+0
+0
+0
+0
+0
+0
+0
+0
+0
+0
+0
+0

examples/ilu-preconditioned-solver/doc/builds-on

@@ -0,0 +1 @@
+simple-solver

examples/ilu-preconditioned-solver/doc/intro.dox

@@ -0,0 +1,8 @@
+<a name="Intro"></a>
+<h1>Introduction</h1>
+
+<h3> About the example </h3>
+This example shows how to use incomplete factors generated via the ParILU 
+algorithm to generate an incomplete factorization (ILU) preconditioner, how to
+specify the sparse triangular solves in the ILU preconditioner application, and
+how to generate an ILU-preconditioned solver and apply it to a specific problem.

examples/ilu-preconditioned-solver/doc/kind

@@ -0,0 +1 @@
+preconditioners

examples/ilu-preconditioned-solver/doc/results.dox

@@ -0,0 +1,35 @@
+<h1>Results</h1>
+This is the expected output:
+
+@code{.cpp}
+Solution (x):
+%%MatrixMarket matrix array real general
+19 1
+0.252218
+0.108645
+0.0662811
+0.0630433
+0.0384088
+0.0396536
+0.0402648
+0.0338935
+0.0193098
+0.0234653
+0.0211499
+0.0196413
+0.0199151
+0.0181674
+0.0162722
+0.0150714
+0.0107016
+0.0121141
+0.0123025
+Residual norm sqrt(r^T r): 
+%%MatrixMarket matrix array real general
+1 1
+9.08137e-16
+
+@endcode
+
+<h4> Comments about programming and debugging </h4>
+

examples/ilu-preconditioned-solver/doc/short-intro

@@ -0,0 +1 @@
+The ILU-preconditioned solver example.

examples/ilu-preconditioned-solver/doc/tooltip

@@ -0,0 +1,4 @@
+Generate an incomplete factorization. 
+Generate an ILU preconditioner from a factorization. 
+Use an ILU preconditioner in an iterative solver. 
+Solve a linear system.

examples/ilu-preconditioned-solver/ilu-preconditioned-solver.cpp

@@ -0,0 +1,120 @@
+/*******************************<GINKGO LICENSE>******************************
+Copyright (c) 2017-2019, the Ginkgo authors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+******************************<GINKGO LICENSE>*******************************/
+
+
+#include <ginkgo/ginkgo.hpp>
+
+
+#include <cstdlib>
+#include <fstream>
+#include <iostream>
+#include <string>
+
+
+int main(int argc, char *argv[])
+{
+    // Some shortcuts
+    using vec = gko::matrix::Dense<>;
+    using mtx = gko::matrix::Csr<>;
+    using gmres = gko::solver::Gmres<>;
+
+    // Print version information
+    std::cout << gko::version_info::get() << std::endl;
+
+    // Figure out where to run the code
+    std::shared_ptr<gko::Executor> exec;
+    if (argc == 1 || std::string(argv[1]) == "reference") {
+        exec = gko::ReferenceExecutor::create();
+    } else if (argc == 2 && std::string(argv[1]) == "omp") {
+        exec = gko::OmpExecutor::create();
+    } else if (argc == 2 && std::string(argv[1]) == "cuda" &&
+               gko::CudaExecutor::get_num_devices() > 0) {
+        exec = gko::CudaExecutor::create(0, gko::OmpExecutor::create());
+    } else {
+        std::cerr << "Usage: " << argv[0] << " [executor]" << std::endl;
+        std::exit(-1);
+    }
+
+    // Read data
+    auto A = gko::share(gko::read<mtx>(std::ifstream("data/A.mtx"), exec));
+    auto b = gko::read<vec>(std::ifstream("data/b.mtx"), exec);
+    auto x = gko::read<vec>(std::ifstream("data/x0.mtx"), exec);
+
+    // Generate incomplete factors using ParILU
+    auto par_ilu_fact = gko::factorization::ParIlu<>::build().on(exec);
+    // Generate concrete factorization for input matrix
+    auto par_ilu = par_ilu_fact->generate(A);
+
+    // Generate an ILU preconditioner factory by setting lower and upper
+    // triangular solver - in this case the exact triangular solves
+    auto ilu_pre_factory =
+        gko::preconditioner::Ilu<gko::solver::LowerTrs<>,
+                                 gko::solver::UpperTrs<>, false>::build()
+            .on(exec);
+
+    // Use incomplete factors to generate ILU preconditioner
+    auto ilu_preconditioner = ilu_pre_factory->generate(gko::share(par_ilu));
+
+    // Use preconditioner inside GMRES solver factory
+    // Generating a solver factory tied to a specific preconditioner makes sense
+    // if there are several very similar systems to solve, and the same
+    // solver+preconditioner combination is expected to be effective.
+    auto ilu_gmres_factory =
+        gko::solver::Gmres<>::build()
+            .with_criteria(
+                gko::stop::Iteration::build().with_max_iters(1000u).on(exec),
+                gko::stop::ResidualNormReduction<>::build()
+                    .with_reduction_factor(1e-15)
+                    .on(exec))
+            .with_generated_preconditioner(gko::share(ilu_preconditioner))
+            .on(exec);
+
+    // Generate preconditioned solver for a specific target system
+    auto ilu_gmres = ilu_gmres_factory->generate(A);
+
+    // Solve system
+    ilu_gmres->apply(gko::lend(b), gko::lend(x));
+
+    // Print solution
+    std::cout << "Solution (x): \n";
+    write(std::cout, gko::lend(x));
+
+    // Calculate residual
+    auto one = gko::initialize<vec>({1.0}, exec);
+    auto neg_one = gko::initialize<vec>({-1.0}, exec);
+    auto res = gko::initialize<vec>({0.0}, exec);
+    A->apply(gko::lend(one), gko::lend(x), gko::lend(neg_one), gko::lend(b));
+    b->compute_norm2(gko::lend(res));
+
+    std::cout << "Residual norm sqrt(r^T r): \n";
+    write(std::cout, gko::lend(res));
+}