Ginkgo

https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop
Admin
Ginkgo is a numerical linear algebra library designed for many-core architectures, providing...
Tokens:1,789,450
Snippets:15,484
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Build External Library Example

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/install_ginkgo.html

Build the interfacing example with deal.II by setting `-DGINKGO_BUILD_EXTLIB_EXAMPLE=ON`.

```bash
cmake -DGINKGO_BUILD_EXTLIB_EXAMPLE=ON ..
cmake --build .
```

--------------------------------

### Build Ginkgo Examples

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/install_ginkgo.html

Include Ginkgo's examples in the build by setting `-DGINKGO_BUILD_EXAMPLES=ON`.

```bash
cmake -DGINKGO_BUILD_EXAMPLES=ON ..
cmake --build .
```

--------------------------------

### Generate Documentation Examples

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/install_ginkgo.html

Generate documentation for examples within Ginkgo by setting `-DGINKGO_DOC_GENERATE_EXAMPLES=ON`.

```bash
cmake -DGINKGO_DOC_GENERATE_EXAMPLES=ON ..
cmake --build .
```

--------------------------------

### Print Usage Help

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/simple_solver.html

Prints usage instructions to standard error and exits if the program is called with the '--help' argument. This guides users on how to run the example.

```cpp
if (argc == 2 && (std::string(argv[1]) == "--help")) {
std::cerr << "Usage: " << argv[0] << " [executor] " << std::endl;
std::exit(-1);
}
```

--------------------------------

### polymorphic_object_move_started_mask

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/classgko_1_1log_1_1Convergence-members.html

Static method to get the mask for polymorphic object move started events. Used for event filtering in the logger.

```APIDOC
## polymorphic_object_move_started_mask

### Description
Static method to get the mask for polymorphic object move started events. Used for event filtering in the logger.

### Signature
```cpp
static uint32 polymorphic_object_move_started_mask()
```
```

--------------------------------

### polymorphic_object_create_started_mask

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/classgko_1_1log_1_1Convergence-members.html

Static method to get the mask for polymorphic object create started events. Used for event filtering in the logger.

```APIDOC
## polymorphic_object_create_started_mask

### Description
Static method to get the mask for polymorphic object create started events. Used for event filtering in the logger.

### Signature
```cpp
static uint32 polymorphic_object_create_started_mask()
```
```

--------------------------------

### Main Function Setup

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/custom_matrix_format.html

Sets up the main execution environment, including argument parsing for executor and discretization points, and initializes the executor map.

```cpp
int main(int argc, char* argv[])
{
using ValueType = double;
using RealValueType = gko::remove_complex<ValueType>;
using IndexType = int;
using vec = gko::matrix::Dense<ValueType>;
using mtx = gko::matrix::Csr<ValueType, IndexType>;
using cg = gko::solver::Cg<ValueType>;

if (argc == 2 && (std::string(argv[1]) == "--help")) {
std::cerr << "Usage: " << argv[0] << " [executor]" << std::endl;
std::exit(-1);
}

const auto executor_string = argc >= 2 ? argv[1] : "reference";
const unsigned int discretization_points =
argc >= 3 ? std::atoi(argv[2]) : 100u;

std::map<std::string, std::function<std::shared_ptr<gko::Executor>()>>
exec_map{
{"omp", [] { return gko::OmpExecutor::create(); }},
{"cuda",
[] {
return gko::CudaExecutor::create(0,
gko::OmpExecutor::create());
}},
{"hip",
[] {
return gko::HipExecutor::create(0, gko::OmpExecutor::create());
}},
{"dpcpp",
[] {
return gko::DpcppExecutor::create(0,
gko::OmpExecutor::create());
}},
{"reference", [] { return gko::ReferenceExecutor::create(); }}
};


```

--------------------------------

### polymorphic_object_copy_started_mask

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/classgko_1_1log_1_1Convergence-members.html

Static method to get the mask for polymorphic object copy started events. Used for event filtering in the logger.

```APIDOC
## polymorphic_object_copy_started_mask

### Description
Static method to get the mask for polymorphic object copy started events. Used for event filtering in the logger.

### Signature
```cpp
static uint32 polymorphic_object_copy_started_mask()
```
```

--------------------------------

### Main function setup and execution

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/custom_matrix_format.html

Sets up the Ginkgo environment, including executor selection, problem definition, and solver configuration. Handles command-line arguments for executor and discretization points.

```cpp
int main(int argc, char* argv[])
{
Some shortcuts
using ValueType = double;
using RealValueType = gko::remove_complex<ValueType>;
using IndexType = int;
using vec = gko::matrix::Dense<ValueType>;
using mtx = gko::matrix::Csr<ValueType, IndexType>;
using cg = gko::solver::Cg<ValueType>;
Figure out where to run the code
if (argc == 2 && (std::string(argv[1]) == "--help")) {
std::cerr << "Usage: " << argv[0] << " [executor]" << std::endl;
std::exit(-1);
}
const auto executor_string = argc >= 2 ? argv[1] : "reference";
const unsigned int discretization_points =
argc >= 3 ? std::atoi(argv[2]) : 100u;
std::map<std::string, std::function<std::shared_ptr<gko::Executor>()>>
exec_map{
{"omp", [] { return gko::OmpExecutor::create(); }},
{"cuda",
[] {
return gko::CudaExecutor::create(0,
gko::OmpExecutor::create());
}},
{"hip",
[] {
return gko::HipExecutor::create(0, gko::OmpExecutor::create());
}},
{"dpcpp",
[] {
return gko::DpcppExecutor::create(0,
gko::OmpExecutor::create());
}},
{"reference", [] { return gko::ReferenceExecutor::create(); }}
};
executor where Ginkgo will perform the computation
const auto exec = exec_map.at(executor_string); // throws if not valid
executor used by the application
const auto app_exec = exec->get_master();
problem:
auto correct_u = [](ValueType x) { return x * x * x; };
auto f = [](ValueType x) { return ValueType{6} * x; };
auto u0 = correct_u(0);
auto u1 = correct_u(1);
initialize vectors
auto rhs = vec::create(app_exec, gko::dim<2>(discretization_points, 1));
generate_rhs(f, u0, u1, rhs.get());
auto u = vec::create(app_exec, gko::dim<2>(discretization_points, 1));
for (int i = 0; i < u->get_size()[0]; ++i) {
u->get_values()[i] = 0.0;
}
const RealValueType reduction_factor{1e-7};
Generate solver and solve the system
cg::build()
.with_criteria(
gko::stop::Iteration::build().with_max_iters(discretization_points),
gko::stop::ResidualNorm<ValueType>::build().with_reduction_factor(
reduction_factor))
.on(exec)
notice how our custom StencilMatrix can be used in the same way as any built-in type
->generate(StencilMatrix<ValueType>::create(exec, discretization_points,
-1, 2, -1))
->apply(rhs, u);
std::cout << "\nSolve complete." << "\nThe average relative error is "
<< calculate_error(discretization_points, u.get(), correct_u) /
discretization_points
<< std::endl;
}
```

--------------------------------

### min_iters

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/namespacegko_1_1stop.html

Creates a stopping criterion factory that wraps another criterion, which only starts getting checked after a specified number of initial iterations.

```APIDOC
## min_iters()

Creates the precursor to a MinimumIteration stopping criterion factory, to be used in conjunction with `.with_criteria(...)` function calls when building a solver factory. 
This stopping criterion wraps another stopping criterion inside, which only starts getting checked after the first `count` iterations finished.

### Parameters
- **count** (size_type) - The number of iterations after which to start checking the inner criterion.
- **criterion** (deferred_factory_parameter< const CriterionFactory >) - The inner criterion, which will not be checked until `count` iterations finished, afterwards the min_iters stopping criterion behaves like the inner criterion.

### Returns
- A deferred_factory_parameter that can be passed to the `with_criteria` function when building a solver.
```

--------------------------------

### Main Function: Heat Equation Solver Setup

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/heat_equation.html

Sets up problem and simulation parameters, initializes Ginkgo executors, loads initial state and source vectors, and creates the output vector. Requires 'data/gko_logo_2d.mtx' and 'data/gko_text_2d.mtx'.

```C++
#include <chrono>
#include <fstream>
#include <iostream>
#include <opencv2/core.hpp>
#include <opencv2/videoio.hpp>
#include <ginkgo/ginkgo.hpp>
int main(int argc, char* argv[])
{
using mtx = gko::matrix::Csr<>;
using vec = gko::matrix::Dense<>;
Problem parameters: simulation length
auto t0 = 5.0;
diffusion factor
auto diffusion = 0.0005;
scaling factor for heat source
auto source_scale = 2.5;
Simulation parameters: inner grid points per discretization direction
auto n = 256;
number of simulation steps per second
auto steps_per_sec = 500;
number of video frames per second
auto fps = 25;
number of grid points
auto n2 = n * n;
grid point distance (ignoring boundary points)
auto h = 1.0 / (n + 1);
auto h2 = h * h;
time step size for the simulation
auto tau = 1.0 / steps_per_sec;
create a CUDA executor with an associated OpenMP host executor
auto exec = gko::CudaExecutor::create(0, gko::OmpExecutor::create());
load heat source and initial state vectors
std::ifstream initial_stream("data/gko_logo_2d.mtx");
std::ifstream source_stream("data/gko_text_2d.mtx");
auto source = gko::read<vec>(source_stream, exec);
auto in_vector = gko::read<vec>(initial_stream, exec);
create output vector with initial guess for
auto out_vector = in_vector->clone();
create scalar for source update
auto tau_source_scalar = gko::initialize<vec>({source_scale * tau}, exec);
create stencil matrix as shared_ptr for solver
auto stencil_matrix = gko::share(mtx::create(exec));
assemble matrix
gko::matrix_data<> mtx_data{gko::dim<2>(n2, n2)};
for (int i = 0; i < n; i++) {
for (int j = 0; j < n; j++) {
auto c = i * n + j;
auto c_val = diffusion * tau * 4.0 / h2 + 1.0;
auto off_val = -diffusion * tau / h2;
for each grid point: insert 5 stencil points with Dirichlet boundary conditions, i.e. with zero boundary value
if (i > 0) {
mtx_data.nonzeros.emplace_back(c, c - n, off_val);
}
if (j > 0) {
mtx_data.nonzeros.emplace_back(c, c - 1, off_val);
}
mtx_data.nonzeros.emplace_back(c, c, c_val);
if (j < n - 1) {
mtx_data.nonzeros.emplace_back(c, c + 1, off_val);
}
if (i < n - 1) {
mtx_data.nonzeros.emplace_back(c, c + n, off_val);
}
}
}
stencil_matrix->read(mtx_data);
prepare video output
auto output = build_output(n, fps);
build CG solver on stencil with incomplete Cholesky preconditioner stopping at 1e-10 relative accuracy
auto solver =
gko::solver::Cg<>::build()
.with_preconditioner(gko::preconditioner::Ic<>::build())
.with_criteria(gko::stop::ResidualNorm<>::build()
.with_baseline(gko::stop::mode::rhs_norm)
.with_reduction_factor(1e-10))
.on(exec)
->generate(stencil_matrix);
time stamp of the last output frame (initialized to a sentinel value)
double last_t = -t0;
execute implicit Euler method: for each timestep, solve stencil system
for (double t = 0; t < t0; t += tau) {
if enough time has passed, output the next video frame
if (t - last_t > 1.0 / fps) {
last_t = t;
std::cout << t << std::endl;
output_timestep(
output, n,
gko::make_temporary_clone(exec->get_master(), in_vector)
->get_const_values());
}
add heat source contribution
in_vector->add_scaled(tau_source_scalar, source);
execute Euler step
solver->apply(in_vector, out_vector);
swap input and output
}
```

--------------------------------

### Ginkgo Main Function Setup

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/performance_debugging.html

Sets up Ginkgo execution environment, including selecting an executor, reading matrices, and configuring a solver with a preconditioner and stopping criteria.

```C++
int main(int argc, char* argv[])
{
Parametrize the benchmark here Pick a value type
using ValueType = double;
using IndexType = int;

Pick a matrix format
using mtx = gko::matrix::Csr<ValueType, IndexType>;

Pick a solver
using solver = gko::solver::Cg<ValueType>;

Pick a preconditioner type
using preconditioner = gko::matrix::IdentityFactory<ValueType>;

Pick a residual norm reduction value
const gko::remove_complex<ValueType> reduction_factor = 1e-12;

Pick an output file name
const auto of_name = "log.txt";

Simple shortcut
using vec = gko::matrix::Dense<ValueType>;

Print version information
std::cout << gko::version_info::get() << std::endl;

Figure out where to run the code
if (argc == 2 && (std::string(argv[1]) == "--help")) {
std::cerr << "Usage: " << argv[0] << " [executor]" << std::endl;
std::exit(-1);
}

Figure out where to run the code
const auto executor_string = argc >= 2 ? argv[1] : "reference";
std::map<std::string, std::function<std::shared_ptr<gko::Executor>()>>
exec_map{
{"omp", [] { return gko::OmpExecutor::create(); }},
{"cuda",
[] { return gko::CudaExecutor::create(0,
gko::OmpExecutor::create());
}},
{"hip",
[] { return gko::HipExecutor::create(0, gko::OmpExecutor::create());
}},
{"dpcpp",
[] { return gko::DpcppExecutor::create(0,
gko::OmpExecutor::create());
}},
{"reference", [] { return gko::ReferenceExecutor::create(); }}
};
const auto exec = exec_map.at(executor_string); // throws if not valid

Read the input matrix file directory
std::string input_mtx = "data/A.mtx";
if (argc == 3) {
input_mtx = std::string(argv[2]);
}

Read data: A is read from disk Create a StorageLogger to track the size of A
auto storage_logger = std::make_shared<loggers::StorageLogger>();

Add the logger to the executor
exec->add_logger(storage_logger);

Read the matrix A from file
auto A = gko::share(gko::read<mtx>(std::ifstream(input_mtx), exec));

Remove the storage logger
exec->remove_logger(storage_logger);

Pick a maximum iteration count
const auto max_iters = A->get_size()[0];

Generate b and x vectors
auto b = utils::create_vector<ValueType>(exec, A->get_size()[0], 1.0);
auto x = utils::create_vector<ValueType>(exec, A->get_size()[0], 0.0);

Declare the solver factory. The preconditioner's arguments should be adapted if needed.
auto solver_factory =
solver::build()
.with_criteria(
gko::stop::ResidualNorm<ValueType>::build()
.with_reduction_factor(reduction_factor),
gko::stop::Iteration::build().with_max_iters(max_iters))
.with_preconditioner(preconditioner::create(exec))
.on(exec);

Declare the output file for all our loggers
std::ofstream output_file(of_name);

Do a warmup run
{
Clone x to not overwrite the original one
auto x_clone = gko::clone(x);
Generate and call apply on a solver

```

--------------------------------

### Get Superior Power

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/math_8hpp_source.html

Recursively calculates the smallest power of `base` that is greater than or equal to `limit`, starting from a `hint` value. Useful for finding appropriate sizes or capacities.

```cpp
template <typename T>
constexpr T get_superior_power(const T& base, const T& limit,
const T& hint = T{1}) noexcept
{
return hint >= limit ? hint : get_superior_power(base, limit, hint * base);
}
```

--------------------------------

### Main Function Setup and Solver Configuration

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/custom_logger.html

This C++ code sets up Ginkgo executors, reads sparse matrix A and vectors b, x0 from files, and configures a Conjugate Gradient (CG) solver with specific stopping criteria. It demonstrates how to initialize Ginkgo components and prepare for a linear solve. The executor selection is based on command-line arguments.

```cpp
int main(int argc, char* argv[])
{
    using ValueType = double;
    using RealValueType = gko::remove_complex<ValueType>;
    using IndexType = int;
    using vec = gko::matrix::Dense<ValueType>;
    using real_vec = gko::matrix::Dense<RealValueType>;
    using mtx = gko::matrix::Csr<ValueType, IndexType>;
    using cg = gko::solver::Cg<ValueType>;

    std::cout << gko::version_info::get() << std::endl;

    if (argc == 2 && (std::string(argv[1]) == "--help")) {
        std::cerr << "Usage: " << argv[0] << " [executor]" << std::endl;
        std::exit(-1);
    }

    const auto executor_string = argc >= 2 ? argv[1] : "reference";

    std::map<std::string, std::function<std::shared_ptr<gko::Executor>()>>
        exec_map{
            {"omp", [] { return gko::OmpExecutor::create(); }},
            {"cuda",
             [] {
                 return gko::CudaExecutor::create(0,
                                                    gko::OmpExecutor::create());
             }},
            {"hip",
             [] {
                 return gko::HipExecutor::create(0, gko::OmpExecutor::create());
             }},
            {"dpcpp",
             [] {
                 return gko::DpcppExecutor::create(0,
                                                    gko::OmpExecutor::create());
             }},
            {"reference", [] { return gko::ReferenceExecutor::create(); }}
        };

    const auto exec = exec_map.at(executor_string); // throws if not valid

    auto A = 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);

    const RealValueType reduction_factor = 1e-7;

    auto solver_gen = 
        cg::build()
            .with_criteria(gko::stop::Iteration::build().with_max_iters(20u),
                             gko::stop::ResidualNorm<ValueType>::build()
                                 .with_reduction_factor(reduction_factor))
            .on(exec);

    // The rest of the main function would typically involve creating the logger,
    // attaching it to the solver, and running the solve.
    // Example:
    // auto logger = ResidualLogger<ValueType>();
    // auto solver = solver_gen->generate(A);
    // solver->add_logger(&logger);
    // solver->apply(b, x);
    // logger.write();

    return 0;
}

```

--------------------------------

### Get Significant Bit

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/math_8hpp_source.html

Recursively finds the most significant bit of a number `n`, starting the search from a given `hint`. Useful for bit manipulation and determining number ranges.

```cpp
template <typename T>
constexpr uint32 get_significant_bit(const T& n, uint32 hint = 0u) noexcept
{
return (T{1} << (hint + 1)) > n ? hint : get_significant_bit(n, hint + 1u);
}
```

--------------------------------

### Measure Ginkgo Solver Overhead

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/ginkgo_overhead.html

This C++ code measures the time taken by the Ginkgo library to perform a specified number of CG solver iterations. It includes setup for the executor, solver factory, and matrix/vector initialization. Ensure Ginkgo is installed and configured.

```cpp
#include <chrono>
#include <cmath>
#include <iostream>
#include <ginkgo/ginkgo.hpp>
[[noreturn]] void print_usage_and_exit(const char* name)
{
std::cerr << "Usage: " << name << " [NUM_ITERS]" << std::endl;
std::exit(-1);
}
int main(int argc, char* argv[])
{
using ValueType = double;
using IndexType = int;
using vec = gko::matrix::Dense<ValueType>;
using mtx = gko::matrix::Csr<ValueType, IndexType>;
using cg = gko::solver::Cg<ValueType>;
long unsigned num_iters = 1000000;
if (argc > 2) {
print_usage_and_exit(argv[0]);
}
if (argc == 2) {
num_iters = std::atol(argv[1]);
if (num_iters == 0) {
print_usage_and_exit(argv[0]);
}
}
std::cout << gko::version_info::get() << std::endl;
auto exec = gko::ReferenceExecutor::create();
auto cg_factory =
cg::build()
.with_criteria(
gko::stop::Iteration::build().with_max_iters(num_iters))
.on(exec);
auto A = gko::initialize<mtx>({1.0}, exec);
auto b = gko::initialize<vec>({std::nan("")}, exec);
auto x = gko::initialize<vec>({0.0}, exec);
auto tic = std::chrono::steady_clock::now();
auto solver = cg_factory->generate(gko::give(A));
solver->apply(x, b);
exec->synchronize();
auto tac = std::chrono::steady_clock::now();
auto time = std::chrono::duration_cast<std::chrono::nanoseconds>(tac - tic);
std::cout << "Running " << num_iters
<< " iterations of the CG solver took a total of "
<< static_cast<double>(time.count()) /
static_cast<double>(std::nano::den)
<< " seconds." << std::endl
<< "\tAverage library overhead: "
<< static_cast<double>(time.count()) /
static_cast<double>(num_iters)
<< " [nanoseconds / iteration]" << std::endl;
}
```

--------------------------------

### get() - Get Underlying MPI_Status

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/structgko_1_1experimental_1_1mpi_1_1status.html

Get a pointer to the underlying MPI_Status object. This is useful for interacting directly with MPI functions.

```APIDOC
## get()

### Description
Get a pointer to the underlying MPI_Status object.

### Method
MPI_Status* get()

### Returns
a pointer to MPI_Status object
```

--------------------------------

### Run Solver Benchmarks with Help

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/benchmarking_ginkgo.html

To see all available options for solver benchmarks, run the solver executable with the --help flag. This provides a comprehensive list of configurable parameters.

```bash
${ginkgo_build_dir}/benchmark/solver/solver --help
```

--------------------------------

### AdvectionProblem setup_system

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/external_lib_interfacing.html

Sets up the linear system by distributing degrees of freedom, creating hanging node constraints, and initializing the sparsity pattern, system matrix, solution vector, and right-hand side vector.

```C++
template <int dim>
void AdvectionProblem<dim>::setup_system()
{
    dof_handler.distribute_dofs(fe);
    hanging_node_constraints.clear();
    DoFTools::make_hanging_node_constraints(dof_handler,
hanging_node_constraints);
    hanging_node_constraints.close();
    DynamicSparsityPattern dsp(dof_handler.n_dofs(), dof_handler.n_dofs());
    DoFTools::make_sparsity_pattern(dof_handler, dsp, hanging_node_constraints,
                                     / *keep_constrained_dofs = * / true);
    sparsity_pattern.copy_from(dsp);
    system_matrix.reinit(sparsity_pattern);
    solution.reinit(dof_handler.n_dofs());
    system_rhs.reinit(dof_handler.n_dofs());
}
```

--------------------------------

### Get Krylov Dimension

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/classgko_1_1solver_1_1Gmres.html

Gets the Krylov dimension of the solver.

```APIDOC
## get_krylov_dim

### Description
Gets the Krylov dimension of the solver.

### Method
`size_type get_krylov_dim () const`
```

--------------------------------

### Main Function for Poisson Solver Example

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/poisson_solver.html

Sets up and solves the Poisson equation. It configures the executor, defines the problem (exact solution, RHS, boundary conditions), initializes the matrix and vectors, generates the solver, and applies it to solve the system. Finally, it prints the solution and calculates the error.

```cpp
int main(int argc, char* argv[])
{
    // Some shortcuts
    using ValueType = double;
    using IndexType = int;
    using vec = gko::matrix::Dense<ValueType>;
    using mtx = gko::matrix::Csr<ValueType, IndexType>;
    using cg = gko::solver::Cg<ValueType>;
    using bj = gko::preconditioner::Jacobi<ValueType, IndexType>;

    // Print version information
    std::cout << gko::version_info::get() << std::endl;

    if (argc == 2 && (std::string(argv[1]) == "--help")) {
        std::cerr << "Usage: " << argv[0]
                  << " [executor] [DISCRETIZATION_POINTS]" << std::endl;
        std::exit(-1);
    }

    // Get number of discretization points
    const unsigned int discretization_points = 
        argc >= 3 ? std::atoi(argv[2]) : 100;

    // Get the executor string
    const auto executor_string = argc >= 2 ? argv[1] : "reference";

    // Figure out where to run the code
    std::map<std::string, std::function<std::shared_ptr<gko::Executor>()>>
        exec_map{
            {"omp", [] { return gko::OmpExecutor::create(); }},
            {"cuda",
             [] {
                 return gko::CudaExecutor::create(0,
                                                    gko::OmpExecutor::create());
             }},
            {"hip",
             [] {
                 return gko::HipExecutor::create(0, gko::OmpExecutor::create());
             }},
            {"dpcpp",
             [] {
                 return gko::DpcppExecutor::create(0,
                                                    gko::OmpExecutor::create());
             }},
            {"reference", [] { return gko::ReferenceExecutor::create(); }}
        };
    // executor where Ginkgo will perform the computation
    const auto exec = exec_map.at(executor_string); // throws if not valid
    // executor used by the application
    const auto app_exec = exec()->get_master();

    // Set up the problem: define the exact solution, the right hand side and the Dirichlet boundary condition.
    auto correct_u = [](ValueType x) { return x * x * x; };
    auto f = [](ValueType x) { return ValueType(6) * x; };
    auto u0 = correct_u(0);
    auto u1 = correct_u(1);

    // initialize matrix and vectors
    auto matrix = mtx::create(app_exec, gko::dim<2>(discretization_points),
                             3 * discretization_points - 2);
    // generate_stencil_matrix(matrix.get());
    auto rhs = vec::create(app_exec, gko::dim<2>(discretization_points, 1));
    generate_rhs(f, u0, u1, rhs.get());
    auto u = vec::create(app_exec, gko::dim<2>(discretization_points, 1));
    for (int i = 0; i < u->get_size()[0]; ++i) {
        u->get_values()[i] = 0.0;
    }

    const gko::remove_complex<ValueType> reduction_factor = 1e-7;

    // Generate solver and solve the system
    cg::build()
        .with_criteria(
            gko::stop::Iteration::build().with_max_iters(discretization_points),
            gko::stop::ResidualNorm<ValueType>::build().with_reduction_factor(
                reduction_factor))
        .with_preconditioner(bj::build())
        .on(exec())
        ->generate(clone(exec(), matrix)) // copy the matrix to the executor
        ->apply(rhs, u);

    // Uncomment to print the solution
    // print_solution<ValueType>(u0, u1, u.get());

    std::cout << "Solve complete.\nThe average relative error is "
              << calculate_error(discretization_points, u.get(), correct_u) /
                 static_cast<gko::remove_complex<ValueType>>(
                     discretization_points) << std::endl;
}
```

--------------------------------

### Main Program Execution

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/par_ilu_convergence.html

Sets up and runs the parallel ILU factorization experiment. It parses command-line arguments for executor, matrix file, preconditioner type, and performance tuning parameters.

```cpp
int main(int argc, char* argv[])
{
using ValueType = double;
using IndexType = int;
if (argc < 2 || executors.find(argv[1]) == executors.end()) {
std::cerr << "Usage: executable"
<< " <reference|omp|cuda|hip|dpcpp> [<matrix-file>] "
<< " [<parilu|parilut|paric|parict] [<max-iterations>] "
<< " [<num-repetitions>] [<fill-in-limit>]\n";
return -1;
}
auto exec = try_generate([&] { return executors.at(argv[1])(); });
std::string matrix = argc < 3 ? "data/A.mtx" : argv[2];
std::string precond = argc < 4 ? "parilu" : argv[3];
int max_iterations = argc < 5 ? 10 : std::stoi(argv[4]);
int num_repetitions = argc < 6 ? 10 : std::stoi(argv[5]);
double limit = argc < 7 ? 2 : std::stod(argv[6]);
auto mtx = gko::share(try_generate([&] {
std::ifstream mtx_stream{matrix};
if (!mtx_stream) {
throw GKO_STREAM_ERROR("Unable to open matrix file");
}
std::cerr << "Reading " << matrix << std::endl;
return gko::read<gko::matrix::Csr<ValueType, IndexType>>(mtx_stream,
exec);
}));
auto factory_generator =
[&](gko::size_type iteration) -> std::shared_ptr<gko::LinOpFactory> {
if (precond == "parilu") {
return gko::factorization::ParIlu<ValueType, IndexType>::build()
.with_iterations(iteration)
.on(exec);
} else if (precond == "paric") {
return gko::factorization::ParIc<ValueType, IndexType>::build()
.with_iterations(iteration)
.on(exec);
} else if (precond == "parilut") {
return gko::factorization::ParIlut<ValueType, IndexType>::build()
.with_fill_in_limit(limit)
.with_iterations(iteration)
.on(exec);
} else if (precond == "parict") {
return gko::factorization::ParIct<ValueType, IndexType>::build()
.with_fill_in_limit(limit)
.with_iterations(iteration)
.on(exec);
} else {
GKO_NOT_IMPLEMENTED;
}
};
auto one = gko::initialize<gko::matrix::Dense<ValueType>>({1.0}, exec);
auto minus_one =
gko::initialize<gko::matrix::Dense<ValueType>>({-1.0}, exec);
for (int it = 1; it <= max_iterations; ++it) {
auto factory = factory_generator(it);
std::cout << it << ';';
std::vector<long> times;
std::vector<double> residuals;
for (int rep = 0; rep < num_repetitions; ++rep) {
auto tic = std::chrono::high_resolution_clock::now();
auto result =
gko::as<gko::Composition<ValueType>>(factory->generate(mtx));
exec->synchronize();
auto toc = std::chrono::high_resolution_clock::now();
auto residual = gko::clone(exec, mtx);
result->get_operators()[0]->apply(one, result->get_operators()[1],
minus_one, residual);
times.push_back(
std::chrono::duration_cast<std::chrono::nanoseconds>(toc - tic)
.count());
residuals.push_back(
compute_ilu_residual_norm(residual.get(), mtx.get()));
}
for (auto el : times) {
std::cout << el << ';';
}
for (auto el : residuals) {
std::cout << el << ';';
}
std::cout << '\n';
}
}
```

--------------------------------

### Main Program Execution (C++)

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/poisson_solver.html

Sets up the Ginkgo executor, defines the problem parameters, generates the matrix and RHS, solves the linear system using CG with Jacobi preconditioning, and prints the error.

```cpp
int main(int argc, char* argv[])
{
using ValueType = double;
using IndexType = int;
using vec = gko::matrix::Dense<ValueType>;
using mtx = gko::matrix::Csr<ValueType, IndexType>;
using cg = gko::solver::Cg<ValueType>;
using bj = gko::preconditioner::Jacobi<ValueType, IndexType>;
std::cout << gko::version_info::get() << std::endl;
if (argc == 2 && (std::string(argv[1]) == "--help")) {
std::cerr << "Usage: " << argv[0]
<< " [executor] [DISCRETIZATION_POINTS]" << std::endl;
std::exit(-1);
}
const unsigned int discretization_points =
argc >= 3 ? std::atoi(argv[2]) : 100;
const auto executor_string = argc >= 2 ? argv[1] : "reference";
std::map<std::string, std::function<std::shared_ptr<gko::Executor>()>>
exec_map{
{"omp", [] { return gko::OmpExecutor::create(); }},
{"cuda",
[] {
return gko::CudaExecutor::create(0,
gko::OmpExecutor::create());
}},
{"hip",
[] {
return gko::HipExecutor::create(0, gko::OmpExecutor::create());
}},
{"dpcpp",
[] {
return gko::DpcppExecutor::create(0,
gko::OmpExecutor::create());
}},
{"reference", [] { return gko::ReferenceExecutor::create(); }}
};
const auto exec = exec_map.at(executor_string); // throws if not valid
const auto app_exec = exec->get_master();
auto correct_u = [](ValueType x) { return x * x * x; };
auto f = [](ValueType x) { return ValueType(6) * x; };
auto u0 = correct_u(0);
auto u1 = correct_u(1);
auto matrix = mtx::create(app_exec, gko::dim<2>(discretization_points),
3 * discretization_points - 2);
generate_stencil_matrix(matrix.get());
auto rhs = vec::create(app_exec, gko::dim<2>(discretization_points, 1));
generate_rhs(f, u0, u1, rhs.get());
auto u = vec::create(app_exec, gko::dim<2>(discretization_points, 1));
for (int i = 0; i < u->get_size()[0]; ++i) {
u->get_values()[i] = 0.0;
}
const gko::remove_complex<ValueType> reduction_factor = 1e-7;
cg::build()
.with_criteria(
gko::stop::Iteration::build().with_max_iters(discretization_points),
	gko::stop::ResidualNorm<ValueType>::build().with_reduction_factor(
reduction_factor))
.with_preconditioner(bj::build())
.on(exec)
->generate(clone(exec, matrix)) // copy the matrix to the executor
->apply(rhs, u);
std::cout << "Solve complete.\nThe average relative error is "
<< calculate_error(discretization_points, u.get(), correct_u) /
static_cast<gko::remove_complex<ValueType>>(
discretization_points)
<< std::endl;
}
```

--------------------------------

### get_stride

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/classgko_1_1matrix_1_1Dense-members.html

Retrieves the stride of the dense matrix, which is the number of elements between the start of one row and the start of the next.

```APIDOC
## get_stride

### Description
Returns the stride of the dense matrix.

### Signature
get_stride() const noexcept

### Returns
The stride of the matrix.
```

--------------------------------

### Main Program Execution

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/simple_solver_logging.html

The main function sets up the Ginkgo environment, including executor selection, matrix loading, solver configuration, and logger setup. It then applies the solver and prints the results.

```cpp
int main(int argc, char* argv[])
{
using ValueType = double;
using RealValueType = gko::remove_complex<ValueType>;
using IndexType = int;
using vec = gko::matrix::Dense<ValueType>;
using real_vec = gko::matrix::Dense<RealValueType>;
using mtx = gko::matrix::Csr<ValueType, IndexType>;
using cg = gko::solver::Cg<ValueType>;
std::cout << gko::version_info::get() << std::endl;
if (argc == 2 && (std::string(argv[1]) == "--help")) {
std::cerr << "Usage: " << argv[0] << " [executor]" << std::endl;
std::exit(-1);
}
const auto executor_string = argc >= 2 ? argv[1] : "reference";
std::map<std::string, std::function<std::shared_ptr<gko::Executor>()>>
exec_map{
{"omp", [] { return gko::OmpExecutor::create(); }},
{"cuda",
[] {
return gko::CudaExecutor::create(0,
gko::OmpExecutor::create());
}},
{"hip",
[] {
return gko::HipExecutor::create(0, gko::OmpExecutor::create());
}},
{"dpcpp",
[] {
return gko::DpcppExecutor::create(0,
gko::OmpExecutor::create());
}},
{"reference", [] { return gko::ReferenceExecutor::create(); }}
};
const auto exec = exec_map.at(executor_string); // throws if not valid
auto A = 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);
std::shared_ptr<gko::log::Stream<ValueType>> stream_logger = 
gko::log::Stream<ValueType>::create(
gko::log::Logger::all_events_mask ^
gko::log::Logger::linop_factory_events_mask ^
gko::log::Logger::polymorphic_object_events_mask,
std::cout);
exec->add_logger(stream_logger);
const RealValueType reduction_factor{1e-7};
using ResidualCriterionFactory = 
gko::stop::ResidualNorm<ValueType>::Factory;
std::shared_ptr<ResidualCriterionFactory> residual_criterion = 
ResidualCriterionFactory::create()
.with_reduction_factor(reduction_factor)
.on(exec);
residual_criterion->add_logger(stream_logger);
auto solver_gen =
cg::build()
.with_criteria(residual_criterion,
gko::stop::Iteration::build().with_max_iters(20u))
.on(exec);
auto solver = solver_gen->generate(A);
std::ofstream filestream("my_file.txt");
solver->add_logger(gko::log::Stream<ValueType>::create(
gko::log::Logger::all_events_mask, filestream));
solver->add_logger(stream_logger);
std::shared_ptr<gko::log::Convergence<ValueType>> convergence_logger = 
gko::log::Convergence<ValueType>::create();
solver->add_logger(convergence_logger);
std::shared_ptr<gko::log::Record> record_logger = 
gko::log::Record::create(gko::log::Logger::executor_events_mask |
gko::log::Logger::iteration_complete_mask);
exec->add_logger(record_logger);
solver->add_logger(record_logger);
solver->apply(b, x);
auto residual = 
record_logger->get().iteration_completed.back()->residual.get();
auto residual_d = gko::as<vec>(residual);
print_vector("Residual", residual_d);
std::cout << "Solution (x):\n";
write(std::cout, x);
std::cout << "Residual norm sqrt(r^T r):\n";
write(std::cout, gko::as<vec>(convergence_logger->get_residual_norm()));
std::cout << "Number of iterations "
<< convergence_logger->get_num_iterations() << std::endl;
std::cout << "Convergence status " << std::boolalpha
<< convergence_logger->has_converged() << std::endl;
}
```

--------------------------------

### Instantiate and use MyLinOp

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/group__LinOp.html

Demonstrates creating a factory with default parameters and generating an operator. Also shows creating a factory with a custom parameter value and generating an operator.

```c++
auto exec = gko::ReferenceExecutor::create();
// create a factory with default `my_value` parameter
auto fact = MyLinOp::build().on(exec);
// create a operator using the factory:
auto my_op = fact->generate(gko::matrix::Identity::create(exec, 2));
std::cout << my_op->get_my_parameters().my_value; // prints 5

```

```c++
// create a factory with custom `my_value` parameter
auto fact = MyLinOp::build().with_my_value(0).on(exec);
// create a operator using the factory:
auto my_op = fact->generate(gko::matrix::Identity::create(exec, 2));
std::cout << my_op->get_my_parameters().my_value; // prints 0

```

--------------------------------

### stride Member

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/structgko_1_1matrix_1_1view_1_1dense-members.html

The stride of the dense matrix view, which is the number of elements between the start of one row and the start of the next.

```APIDOC
## stride

### Description
Represents the stride of the dense matrix view.
```

--------------------------------

### Solve System Setup (C++)

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/nine_pt_stencil_solver.html

Sets up the necessary types and variables for solving a linear system using Ginkgo. This includes defining dense vectors, CSR matrices, CG solvers, and Jacobi preconditioners.

```cpp
template <typename ValueType, typename IndexType>
void solve_system(const std::string& executor_string,
unsigned int discretization_points, IndexType* row_ptrs,
IndexType* col_idxs, ValueType* values, ValueType* rhs,
ValueType* u, gko::remove_complex<ValueType> reduction_factor)
{
Some shortcuts
using vec = gko::matrix::Dense<ValueType>;
using mtx = gko::matrix::Csr<ValueType, IndexType>;
using cg = gko::solver::Cg<ValueType>;
using bj = gko::preconditioner::Jacobi<ValueType, IndexType>;
using val_array = gko::array<ValueType>;

```

--------------------------------

### get_srow()

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/classgko_1_1matrix_1_1Csr.html

Retrieves the starting rows of the CSR matrix. This method returns a pointer to the underlying array of starting rows.

```APIDOC
## get_srow()

### Description
Returns the starting rows.

### Returns
`index_type*`: A pointer to the starting rows.

### Template Parameters
* `ValueType`: The type of the matrix values (default is `default_precision`).
* `IndexType`: The type of the matrix indices (default is `int32`).
```

--------------------------------

### Preconditioned Iterative Solver Setup

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/classgko_1_1solver_1_1CbGmres.html

Constructors and assignment operators for setting up a preconditioned iterative solver.

```APIDOC
## EnablePreconditionedIterativeSolver (system_matrix, stop_factory, preconditioner)

### Description
Constructor for a preconditioned iterative solver.

### Method
`EnablePreconditionedIterativeSolver(std::shared_ptr< const LinOp > system_matrix, std::shared_ptr< const stop::CriterionFactory > stop_factory, std::shared_ptr< const LinOp > preconditioner)`
```

```APIDOC
## EnablePreconditionedIterativeSolver (system_matrix, params)

### Description
Constructor for a preconditioned iterative solver using factory parameters.

### Method
`EnablePreconditionedIterativeSolver(std::shared_ptr< const LinOp > system_matrix, const FactoryParameters &params)`
```

--------------------------------

### General Get Functions

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/functions_g.html

A collection of 'get' functions for various Ginkgo components, including configuration, executors, MPI, logging, and parameters.

```APIDOC
## get()

### Description
Retrieves various objects and information from Ginkgo components.

### Method
Not specified (likely a C++ function call)

### Endpoint
Not applicable

### Parameters
None explicitly defined in source.

### Request Example
None provided.

### Response
- **gko::config::pnode**: Configuration node.
- **gko::cuda_stream**: CUDA stream object.
- **gko::experimental::mpi::communicator**: MPI communicator.
- **gko::experimental::mpi::contiguous_type**: MPI contiguous type.
- **gko::experimental::mpi::request**: MPI request.
- **gko::experimental::mpi::status**: MPI status.
- **gko::experimental::mpi::window< ValueType >**: MPI window.
- **gko::hip_stream**: HIP stream object.
- **gko::log::Record**: Log record.
- **gko::ptr_param< T >**: Pointer parameter.
- **gko::version_info**: Ginkgo version information.

### Response Example
None provided.
```

--------------------------------

### Run Spmv Benchmarks with Help

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/benchmarking_ginkgo.html

To see all available options for sparse matrix-vector product (spmv) benchmarks, run the spmv executable with the --help flag. This lists all supported matrix formats and optimization parameters.

```bash
${ginkgo_build_dir}/benchmark/spmv/spmv --help
```

--------------------------------

### Register Polymorphic Object Create Started Event

Source: https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/logger_8hpp_source.html

Registers an event for the start of polymorphic object creation. Requires an Executor and a PolymorphicObject.

```cpp
GKO_LOGGER_REGISTER_EVENT(8, polymorphic_object_create_started,
const Executor* exec, const PolymorphicObject* po)
```
Tokens:
Raw