Skip to content

Commit 1943075

Browse files
lucbvlucbv
authored
docs: testing literalinclude as proposed by Yuuichi (kokkos#2644)
* docs: testing literalinclude as proposed by Yuuichi This will allow us to save time by not retyping the examples manually in the docs. More importantly, since the examples are tested during CI, it will also keep our documentation up to date when a change is required : ) Signed-off-by: Luc Berger-Vergiat <[email protected]> * docs: adding literalinclude to blas kernels with examples Since this technique works pretty well, let us use it uniformly. Starting with the blas files and next taking care for sparse and batched examples. Signed-off-by: Luc Berger-Vergiat <[email protected]> * docs - examples: adding examples for sparse and graph This inclues the examples directly from the associated source files that are tested with CI thus keeping the code more easily up to date. Removing copyright headers to make things more readable. Signed-off-by: Luc Berger-Vergiat <[email protected]> * docs: fixing typo Signed-off-by: Luc Berger-Vergiat <[email protected]> --------- Signed-off-by: Luc Berger-Vergiat <[email protected]>
1 parent 708ea1d commit 1943075

25 files changed

+67
-1309
lines changed

‎docs/source/API/blas/blas1_dot.rst‎

Lines changed: 2 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -78,32 +78,8 @@ Type Requirements
7878
Example
7979
=======
8080

81-
.. code:: c++
82-
83-
#include <iostream>
84-
#include <Kokkos_Core.hpp>
85-
#include <KokkosBlas1_dot.hpp>
86-
87-
int main(int argc, char* argv[]) {
88-
Kokkos::initialize();
89-
{
90-
int N = 100;
91-
if (argc >= 2) {
92-
N = atoi(argv[1]);
93-
}
94-
95-
Kokkos::View<double*> x("X", N);
96-
Kokkos::View<double*> y("Y", N);
97-
Kokkos::deep_copy(x, 3.0);
98-
Kokkos::deep_copy(y, 2.0);
99-
100-
double x_y = KokkosBlas::dot(x, y);
101-
102-
std::cout << "X_dot_Y: " << x_y << " Expected: " << 1.0 * N * (3.0 * 2.0)
103-
<< " Diff: " << x_y - 1.0 * N * (3.0 * 2.0) << std::endl;
104-
}
105-
Kokkos::finalize();
106-
}
81+
.. literalinclude:: ../../../../example/wiki/blas/KokkosBlas1_wiki_dot.cpp
82+
:language: c++
10783

10884
output:
10985

‎docs/source/API/blas/blas1_iamax.rst‎

Lines changed: 2 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -59,51 +59,8 @@ Type Requirements
5959
Example
6060
=======
6161

62-
.. code:: c++
63-
64-
#include <Kokkos_Core.hpp>
65-
#include <Kokkos_Random.hpp>
66-
#include <KokkosBlas1_iamax.hpp>
67-
68-
int main(int argc, char* argv[]) {
69-
Kokkos::initialize();
70-
{
71-
int N = 100;
72-
if (argc >= 2) {
73-
N = atoi(argv[1]);
74-
}
75-
76-
using ViewType = Kokkos::View<double*>;
77-
using Scalar = typename ViewType::non_const_value_type;
78-
using AT = Kokkos::ArithTraits<Scalar>;
79-
using mag_type = typename AT::mag_type;
80-
using size_type = typename ViewType::size_type;
81-
82-
ViewType x("X", N);
83-
84-
typename ViewType::HostMirror h_x = Kokkos::create_mirror_view(x);
85-
86-
Kokkos::Random_XorShift64_Pool<typename ViewType::device_type::execution_space> rand_pool(13718);
87-
Kokkos::fill_random(x, rand_pool, Scalar(10));
88-
89-
Kokkos::deep_copy(h_x, x);
90-
91-
size_type max_loc = KokkosBlas::iamax(x);
92-
93-
mag_type expected_result = Kokkos::ArithTraits<mag_type>::min();
94-
size_type expected_max_loc = 0;
95-
for (int i = 0; i < N; i++) {
96-
mag_type val = AT::abs(h_x(i));
97-
if (val > expected_result) {
98-
expected_result = val;
99-
expected_max_loc = i + 1;
100-
}
101-
}
102-
103-
printf("Iamax of X: %i, Expected: %i\n", max_loc, expected_max_loc);
104-
}
105-
Kokkos::finalize();
106-
}
62+
.. literalinclude:: ../../../../example/wiki/blas/KokkosBlas1_wiki_iamax.cpp
63+
:language: c++
10764

10865
output:
10966

‎docs/source/API/blas/blas1_nrm1.rst‎

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -59,24 +59,8 @@ Type Requirements
5959
Example
6060
=======
6161

62-
.. code:: c++
63-
64-
#include <iostream>
65-
#include <Kokkos_Core.hpp>
66-
#include <KokkosBlas1_nrm1.hpp>
67-
68-
int main(void) {
69-
Kokkos::initialize();
70-
{
71-
Kokkos::View<double*> x("X", 100);
72-
Kokkos::deep_copy(x, -3.0);
73-
74-
double x_nrm = KokkosBlas::nrm1(x);
75-
76-
std::cout << "X_nrm: " << x_nrm << " Expected: " << 100 * 3.0 << std::endl;
77-
}
78-
Kokkos::finalize();
79-
}
62+
.. literalinclude:: ../../../../example/wiki/blas/KokkosBlas1_wiki_nrm1.cpp
63+
:language: c++
8064

8165
output:
8266

‎docs/source/API/blas/blas1_nrm2.rst‎

Lines changed: 2 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -65,25 +65,8 @@ Return Value
6565
Example
6666
=======
6767

68-
.. code:: c++
69-
70-
#include <cmath>
71-
#include <iostream>
72-
#include <Kokkos_Core.hpp>
73-
#include <KokkosBlas1_nrm2.hpp>
74-
75-
int main(void) {
76-
Kokkos::initialize();
77-
{
78-
Kokkos::View<double*> x("X", 100);
79-
Kokkos::deep_copy(x, 3.0);
80-
81-
double x_nrm = KokkosBlas::nrm2(x);
82-
83-
std::cout << "X_nrm: " << x_nrm << " Expected: " << std::sqrt(100 * 3.0 * 3.0) << std::endl;
84-
}
85-
Kokkos::finalize();
86-
}
68+
.. literalinclude:: ../../../../example/wiki/blas/KokkosBlas1_wiki_nrm2.cpp
69+
:language: c++
8770

8871
output:
8972

‎docs/source/API/blas/blas1_rot.rst‎

Lines changed: 2 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -55,65 +55,6 @@ Example
5555
This example shows how to eliminate an entry using a Givens rotation.
5656
It uses :doc:`rotg <blas1_rotg>` to compute the rotation coefficients and :code:`rot` to apply the rotation.
5757

58-
.. code:: c++
59-
60-
#include <iostream>
61-
#include <Kokkos_Core.hpp>
62-
#include <Kokkos_Random.hpp>
63-
#include "KokkosBlas1_rotg.hpp"
64-
#include "KokkosBlas1_rot.hpp"
65-
#include "KokkosKernels_PrintUtils.hpp"
66-
67-
using execution_space = Kokkos::DefaultExecutionSpace;
68-
using Scalar = double;
69-
using Vector = Kokkos::View<Scalar*, execution_space>;
70-
using ScalarView = Kokkos::View<Scalar, execution_space>;
71-
72-
int main(int argc, char* argv[]) {
73-
Kokkos::initialize();
74-
{
75-
const int N = 10;
76-
Vector x("x", N);
77-
Vector y("y", N);
78-
79-
// Populate x,y with uniform random values between 0 and 10
80-
Kokkos::Random_XorShift64_Pool<execution_space> rand_pool(13718);
81-
Kokkos::fill_random(x, rand_pool, Scalar(10));
82-
Kokkos::fill_random(y, rand_pool, Scalar(10));
83-
84-
std::cout << "x,y before applying Givens rotation:\n";
85-
KokkosKernels::Impl::kk_print_1Dview(std::cout, x);
86-
KokkosKernels::Impl::kk_print_1Dview(std::cout, y);
87-
88-
ScalarView c("c");
89-
ScalarView s("s");
90-
91-
// Calculate Givens rotation coefficients to eliminate y(0)
92-
KokkosBlas::rotg<execution_space, ScalarView, ScalarView>(execution_space(), Kokkos::subview(x, 0),
93-
Kokkos::subview(y, 0), c, s);
94-
95-
std::cout << "\nrotg output (rotation parameters) to eliminate y(0):\n";
96-
std::cout << "c = ";
97-
KokkosKernels::Impl::kk_print_1Dview(std::cout, c);
98-
std::cout << "s = ";
99-
KokkosKernels::Impl::kk_print_1Dview(std::cout, s);
100-
std::cout << "r = x(0) = ";
101-
KokkosKernels::Impl::kk_print_1Dview(std::cout, Kokkos::subview(x, 0));
102-
std::cout << "z = ";
103-
KokkosKernels::Impl::kk_print_1Dview(std::cout, Kokkos::subview(y, 0));
104-
105-
// Zero out y(0), which now contains the output parameter z.
106-
// This completes the replacement of [x(0), y(0)] with [r, 0].
107-
Kokkos::deep_copy(Kokkos::subview(y, 0), Scalar(0));
108-
109-
// Apply the rotation to the remaining entries of x and y
110-
KokkosBlas::rot(execution_space(), Kokkos::subview(x, Kokkos::make_pair(1, N)),
111-
Kokkos::subview(y, Kokkos::make_pair(1, N)), c, s);
112-
113-
std::cout << "\nx,y after applying Givens rotation:\n";
114-
KokkosKernels::Impl::kk_print_1Dview(std::cout, x);
115-
KokkosKernels::Impl::kk_print_1Dview(std::cout, y);
116-
}
117-
Kokkos::finalize();
118-
}
58+
.. literalinclude:: ../../../../example/wiki/blas/KokkosBlas1_wiki_rotg_rot.cpp
59+
:language: c++
11960

‎docs/source/API/blas/blas1_rotg.rst‎

Lines changed: 2 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -45,65 +45,5 @@ Example
4545
This example shows how to eliminate an entry using a Givens rotation.
4646
It uses both :code:`rotg` to compute the rotation coefficients and :doc:`rot <blas1_rot>` to apply the rotation.
4747

48-
.. code:: c++
49-
50-
#include <iostream>
51-
#include <Kokkos_Core.hpp>
52-
#include <Kokkos_Random.hpp>
53-
#include "KokkosBlas1_rotg.hpp"
54-
#include "KokkosBlas1_rot.hpp"
55-
#include "KokkosKernels_PrintUtils.hpp"
56-
57-
using execution_space = Kokkos::DefaultExecutionSpace;
58-
using Scalar = double;
59-
using Vector = Kokkos::View<Scalar*, execution_space>;
60-
using ScalarView = Kokkos::View<Scalar, execution_space>;
61-
62-
int main(int argc, char* argv[]) {
63-
Kokkos::initialize();
64-
{
65-
const int N = 10;
66-
Vector x("x", N);
67-
Vector y("y", N);
68-
69-
// Populate x,y with uniform random values between 0 and 10
70-
Kokkos::Random_XorShift64_Pool<execution_space> rand_pool(13718);
71-
Kokkos::fill_random(x, rand_pool, Scalar(10));
72-
Kokkos::fill_random(y, rand_pool, Scalar(10));
73-
74-
std::cout << "x,y before applying Givens rotation:\n";
75-
KokkosKernels::Impl::kk_print_1Dview(std::cout, x);
76-
KokkosKernels::Impl::kk_print_1Dview(std::cout, y);
77-
78-
ScalarView c("c");
79-
ScalarView s("s");
80-
81-
// Calculate Givens rotation coefficients to eliminate y(0)
82-
KokkosBlas::rotg<execution_space, ScalarView, ScalarView>(execution_space(), Kokkos::subview(x, 0),
83-
Kokkos::subview(y, 0), c, s);
84-
85-
std::cout << "\nrotg output (rotation parameters) to eliminate y(0):\n";
86-
std::cout << "c = ";
87-
KokkosKernels::Impl::kk_print_1Dview(std::cout, c);
88-
std::cout << "s = ";
89-
KokkosKernels::Impl::kk_print_1Dview(std::cout, s);
90-
std::cout << "r = x(0) = ";
91-
KokkosKernels::Impl::kk_print_1Dview(std::cout, Kokkos::subview(x, 0));
92-
std::cout << "z = ";
93-
KokkosKernels::Impl::kk_print_1Dview(std::cout, Kokkos::subview(y, 0));
94-
95-
// Zero out y(0), which now contains the output parameter z.
96-
// This completes the replacement of [x(0), y(0)] with [r, 0].
97-
Kokkos::deep_copy(Kokkos::subview(y, 0), Scalar(0));
98-
99-
// Apply the rotation to the remaining entries of x and y
100-
KokkosBlas::rot(execution_space(), Kokkos::subview(x, Kokkos::make_pair(1, N)),
101-
Kokkos::subview(y, Kokkos::make_pair(1, N)), c, s);
102-
103-
std::cout << "\nx,y after applying Givens rotation:\n";
104-
KokkosKernels::Impl::kk_print_1Dview(std::cout, x);
105-
KokkosKernels::Impl::kk_print_1Dview(std::cout, y);
106-
}
107-
Kokkos::finalize();
108-
}
109-
48+
.. literalinclude:: ../../../../example/wiki/blas/KokkosBlas1_wiki_rotg_rot.cpp
49+
:language: c++

‎docs/source/API/blas/blas1_rotm.rst‎

Lines changed: 2 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -53,78 +53,5 @@ Example
5353
This example shows how to eliminate an entry using a modified Givens rotation.
5454
It uses :doc:`rotmg <blas1_rotmg>` to compute the rotation parameters and ``rotm`` to apply the rotation.
5555

56-
.. code:: c++
57-
58-
#include <iostream>
59-
#include <Kokkos_Core.hpp>
60-
#include <Kokkos_Random.hpp>
61-
#include "KokkosBlas1_rotmg.hpp"
62-
#include "KokkosBlas1_rotm.hpp"
63-
#include "KokkosKernels_PrintUtils.hpp"
64-
65-
using execution_space = Kokkos::DefaultExecutionSpace;
66-
using Scalar = double;
67-
using Vector = Kokkos::View<Scalar*, execution_space>;
68-
using ParamView = Kokkos::View<Scalar[5], execution_space>;
69-
using ScalarView = Kokkos::View<Scalar, execution_space>;
70-
71-
int main(int argc, char* argv[]) {
72-
Kokkos::initialize();
73-
{
74-
const int N = 10;
75-
Vector x("x", N);
76-
Vector y("y", N);
77-
ScalarView d1("d1");
78-
ScalarView d2("d2");
79-
ParamView param("param");
80-
81-
// Populate x,y with uniform random values between 0 and 10
82-
Kokkos::Random_XorShift64_Pool<execution_space> rand_pool(13718);
83-
Kokkos::fill_random(x, rand_pool, Scalar(10));
84-
Kokkos::fill_random(y, rand_pool, Scalar(10));
85-
86-
// Populate input vector scaling factors with 1
87-
Kokkos::deep_copy(d1, Scalar(1));
88-
Kokkos::deep_copy(d2, Scalar(1));
89-
90-
std::cout << "x,y before applying modified Givens rotation:\n";
91-
KokkosKernels::Impl::kk_print_1Dview(std::cout, x);
92-
KokkosKernels::Impl::kk_print_1Dview(std::cout, y);
93-
94-
// Calculate Givens rotation coefficients to eliminate y(0)
95-
KokkosBlas::rotmg<execution_space, ScalarView, ScalarView, ParamView>(
96-
execution_space(), d1, d2, Kokkos::subview(x, 0), Kokkos::subview(y, 0), param);
97-
98-
auto paramHost = Kokkos::create_mirror_view_and_copy(Kokkos::HostSpace(), param);
99-
100-
std::cout << "\nrotmg output (rotation parameters) to eliminate y(0):\n";
101-
std::cout << "d1 = ";
102-
KokkosKernels::Impl::kk_print_1Dview(std::cout, d1);
103-
std::cout << "d2 = ";
104-
KokkosKernels::Impl::kk_print_1Dview(std::cout, d2);
105-
std::cout << "flag = " << paramHost(0) << '\n';
106-
std::cout << "h components = ";
107-
for (int i = 0; i < 4; i++) std::cout << paramHost(1 + i) << " ";
108-
std::cout << '\n';
109-
110-
// Zero out y(0), which was left unmodified by rotmg.
111-
Kokkos::deep_copy(Kokkos::subview(y, 0), Scalar(0));
112-
113-
// Apply the rotation to the remaining entries of x and y
114-
KokkosBlas::rotm(execution_space(), Kokkos::subview(x, Kokkos::make_pair(1, N)),
115-
Kokkos::subview(y, Kokkos::make_pair(1, N)), param);
116-
117-
// Apply scaling factors: sqrt(d1) and sqrt(d2) to x and y respectively
118-
Kokkos::parallel_for(
119-
Kokkos::RangePolicy<execution_space>(0, N), KOKKOS_LAMBDA(int i) {
120-
x(i) *= Kokkos::sqrt(d1());
121-
y(i) *= Kokkos::sqrt(d2());
122-
});
123-
124-
std::cout << "\nx,y after applying modified Givens rotation and scaling by [sqrt(d1), sqrt(d2)]):\n";
125-
KokkosKernels::Impl::kk_print_1Dview(std::cout, x);
126-
KokkosKernels::Impl::kk_print_1Dview(std::cout, y);
127-
}
128-
Kokkos::finalize();
129-
}
130-
56+
.. literalinclude:: ../../../../example/wiki/blas/KokkosBlas1_wiki_rotmg_rotm.cpp
57+
:language: c++

0 commit comments

Comments
 (0)