PyGinkgo: Python Binding for Ginkgo

PyGinkgo is a Python binding for the Ginkgo framework, providing access to Ginkgo's powerful linear algebra capabilities from Python. Ginkgo is a high-performance numerical linear algebra library for sparse systems, primarily designed for developing efficient iterative solvers on complex HPC architectures.

The tests successfully run on the following Python versions:

• 3.8.20
• 3.9.22
• 3.10.17
• 3.11.12
• 3.12.3
• 3.13.3

Installation

Prerequisites

• Python 3.x
• Ginkgo
• Pybind11
• Ninja # if you want to use cmake presets
• pybind11-stubgen # if you want to use stubs generation

Building the module

1. Clone the repository:

   git clone https://github.com/Helmholtz-AI-Energy/pyGinkgo.git

2. Build using CMake:

   # Make a build directory in the project directory
   mkdir build && cd build
   
   # Run CMake configuration
   cmake ..
   
   # Build the project using the specified number of cores (replace "number of cores" with the desired value)
   # (Here we are still within the build directory)
   cmake --build . -j=number_of_cores

3. Install the module:

   # (Here we are still within the build directory)
   cmake --install .

   • To install in the virtual environment, use -DPython_ROOT_DIR=path_to_venv_bin_folder flag during the project configuration.

Running the tests

You would need to install pytest to be able to run the tests. To run all tests:

ctest

To run a particular test, say 'pyginkgo_import_test':

ctest -R pyginkgo_import_test

Stubs generation

From Python mypy documentation:

A stub file (see PEP 484) contains only type hints for the public interface of a module, with empty function bodies. Mypy can use a stub file instead of the real implementation to provide type information for the module. They are useful for third-party modules whose authors have not yet added type hints (and when no stubs are available in typeshed) and C extension modules (which mypy can’t directly process).

For this project the pybind11-stubgen module was used, being specifically tailored to work with pybind11.

In order to enable the stubs generation:

1. Install pybind11-stubgen on your local Python installation:

   pip install pybind11-stubgen

2. Set ENABLE_PYGINKGOBINDINGS_STUBS=ON when doing CMake configuration:

   cmake .. -DENABLE_PYGINKGOBINDINGS_STUBS=ON

3. Now stubs are generated in the build folder and during the library installation. They would allow to see what's inside of the pyGinkgo.pyGinkgoBindings module and use autocomplete:

   class dense(pyGinkgoBindings.LinOp):
      @typing.overload
      def __init__(self, arg0: typing_extensions.Buffer) -> None:
         ...
      @typing.overload
      def __init__(self, arg0: pyGinkgoBindings.Executor, arg1: typing_extensions.Buffer) -> None:
         ...
      @typing.overload
      def __init__(self, arg0: pyGinkgoBindings.Executor) -> None:
         ...

Development stubs generation

While working on the Python side of the project, it is also useful to have access to the stubs for the C++ code. This can be done by setting ENABLE_PYGINKGOBINDINGS_DEV_STUBS=ON when doing CMake configuration:

cmake .. -DENABLE_PYGINKGOBINDINGS_DEV_STUBS=ON

This will generate the stubs for the C++ code in the pyGinkgoBindings module inside the ./src/pyGinkgo/pyGinkgoBindings folder, allowing for autocomplete and type checking by VSCode or other IDEs.

Usage

Here's a simple example demonstrating how to use PyGinkgo to perform matrix-vector multiplication:

Benchmarking