C++ Interface¶
The C++ interface is a header-only C++17 wrapper over the public HYPREDRV_ C
API. It provides RAII ownership for HYPREDRV_t, throwing error handling, a
YAML-driven configuration path, and an idiomatic snake_case method mirror of the
C API.
Build¶
cmake -S . -B build-cpp \
-DHYPREDRV_ENABLE_CPP=ON \
-DHYPREDRV_ENABLE_TESTING=ON \
-DHYPREDRV_ENABLE_EXAMPLES=ON
cmake --build build-cpp --target cpp-test --parallel
Usage¶
#include <hypredrive.hpp>
hypredrive::initialize();
hypredrive::driver drv(MPI_COMM_SELF);
drv.set_library_mode();
drv.parse_yaml(R"yaml(
general:
statistics: 0
solver:
pcg:
max_iter: 100
relative_tol: 1.0e-8
preconditioner:
amg:
print_level: 0
)yaml");
drv.set_matrix_from_csr(row_start, row_end, indptr, cols, values);
drv.set_rhs_from_array(row_start, row_end, rhs);
drv.set_zero_initial_guess();
drv.solve();
hypredrive::finalize();
hypredrive::driver is move-only and destroys its underlying HYPREDRV_t in
its destructor. Methods throw hypredrive::error when the underlying C API
returns a nonzero status. The original status is available through
error::code(). Call hypredrive::describe_error(e.code()) if a caught
exception should also print the C-side diagnostic. Explicit
destroy_linear_solver() calls are only needed to release solver state before
the driver goes out of scope.
Configuration¶
Solver configuration is intentionally YAML-driven. The C++ wrapper does not
mirror the full solver option schema with C++ setters, because the YAML schema is
the project-owned source of truth and supports new HYPREDRV options immediately.
Use parse_yaml() for YAML from a string, string literal, input stream, or
file path; use parse_args(argc, argv) for the same command-line style parsing
exposed by the C API. String-like inputs are treated as file paths when they look
like paths, otherwise as inline YAML text. YAML text is passed to the C parser as
a C string, so embedded NUL bytes are rejected.
Example¶
The laplacian-cpp example assembles a distributed 3D 7-point Laplacian and
solves it through the wrapper:
mpiexec -n 4 ./build-cpp/laplacian-cpp -n 16 16 16 -P 2 2 1 -s 7
Pass a custom YAML file with -i/--input options.yml.
API correspondence¶
The C++ interface is a thin throwing wrapper over the public C API. The table below maps each C++ entry point to the C API it forwards to. C API names link to the generated API reference.
C++ API |
C API |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Installation¶
When HYPREDRV_ENABLE_CPP=ON, CMake installs hypredrive.hpp and
exports the HYPREDRV::CXX target. Downstream projects should link that target
instead of manually adding include directories.