hypredrive is a flexible framework for high-performance sparse linear algebra through hypre. It can be used as:

• Library: C API via include/HYPREDRV.h and other interfaces/ (C++, Fortran, Python, MATLAB/Octave, and Julia) with solver options configured via YAML input (file or in-memory)
• Driver: hypredrive-cli command-line tool for solving linear systems read from files, with solver options given by YAML input

Build

git clone --depth 1 https://github.com/hypre-space/hypredrive.git && cd hypredrive
cmake -DHYPREDRV_ENABLE_DATA=ON -B build && cmake --build build -j -t check

• hypre is fetched automatically if not found. Pass -DHYPRE_ROOT=<path> to use an existing install.
• Enable accelerator support via HYPREDRV_ENABLE_CUDA/HIP/SYCL.
• Check installation instructions for details, including the available library options.

Examples

Driver -- solve a system from a YAML file (see examples files in the docs).

mpirun -np 1 ./build/hypredrive-cli examples/ex2.yml

Library -- call the API from your own code (see example drivers in the docs).

   #include <mpi.h>
   #include "HYPREDRV.h"

   // 1. Setup hypredrive options from YAML input
   MPI_Init(NULL, NULL);
   HYPREDRV_t hdrv = NULL;
   HYPREDRV_Initialize();
   HYPREDRV_Create(MPI_COMM_WORLD, &hdrv);
   HYPREDRV_SetLibraryMode(hdrv);
   const char *yaml_text = "solver: pcg\n"
                           "preconditioner: amg\n";
   char *yaml_argv[] = {(char *)yaml_text};
   HYPREDRV_InputArgsParse(1, yaml_argv, hdrv); // Solver options are parsed here

   // 2. Setup linear system ("A" and "b" are built previously)
   // The application retains ownership of these objects in library mode.
   HYPREDRV_LinearSystemSetMatrix(hdrv, (HYPRE_Matrix) A);
   HYPREDRV_LinearSystemSetRHS(hdrv, (HYPRE_Vector) b);

   // 3. Solve lifecycle (Solve for "x" in "A x = b")
   HYPREDRV_LinearSolverCreate(hdrv);
   HYPREDRV_LinearSolverSetup(hdrv);
   HYPREDRV_LinearSolverApply(hdrv);
   HYPREDRV_LinearSolverDestroy(hdrv);

   // 4. Cleanup
   HYPREDRV_Destroy(&hdrv);
   HYPREDRV_Finalize();
   MPI_Finalize();

Documentation is available at hypredrive.readthedocs.io. For contribution instructions, see CONTRIBUTING.md.

Citation

Magri, V. A. P. (2024). Hypredrive: High-level interface for solving linear systems with hypre. JOSS, 9(98), 6654. https://doi.org/10.21105/joss.06654

See also CITATION.cff.

License

This project is licensed under the MIT License - see the LICENSE file for details. All new contributions must be made under this license.

SPDX-License-Identifier: MIT

LLNL-CODE-861860