wip: python support

Author: OmarDuran

.gitignore

@@ -71,3 +71,8 @@ Testing/
 # spack environment artifacts (spack.yaml is tracked; these are generated)
 .spack-env/
 spack.lock
+
+# python binding artifacts
+python/graphos/_core*.so
+python/graphos/__pycache__/
+python/tests/__pycache__/

CMakeLists.txt

@@ -75,6 +75,11 @@ if(GRAPHOS_BUILD_BENCH AND PROJECT_IS_TOP_LEVEL)
   add_subdirectory(bench)
 endif()
 
+option(GRAPHOS_BUILD_PYTHON "Build the Python bindings (graphos._core)" OFF)
+if(GRAPHOS_BUILD_PYTHON AND PROJECT_IS_TOP_LEVEL)
+  add_subdirectory(python)
+endif()
+
 # ---- installation ----------------------------------------------------------
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)

README.md

@@ -127,6 +127,20 @@ Two disciplines follow:
 `freeze(c, halo_depth)` records the ghost-ring depth (default 1) that Local
 queries are guaranteed correct within.
 
+## Python bindings
+
+`-DGRAPHOS_BUILD_PYTHON=ON` builds `graphos._core` (pybind11, fetched
+automatically) into `python/graphos/`; run with `PYTHONPATH=python`. The
+whole calculus and query surface is exposed with the same names; markers
+take Python callables as predicates (`marker.mark_where(1, lambda e: ...)`),
+identifications and glue are lists of `(from, to[, sign])` tuples, and
+chain maps come back as NumPy arrays. Lifetime follows the builder/frozen
+split: accessors on `Complex` and on operation results return array
+copies; `FrozenComplex.boundary/coboundary` return zero-copy views whose
+base keeps the frozen complex alive. `python/tests/test_graphos.py`
+re-asserts the mathematical certificates through the bindings and runs as
+the `python.test_graphos` ctest entry.
+
 ## Build, test, install
 
 ```bash

include/graphos/core/frozen.hpp

@@ -69,6 +69,13 @@ class FrozenComplex {
     }
   }
 
+  // frozen storage is move-only (exec::Array owns device-capable memory);
+  // stating it explicitly keeps type traits honest for bindings
+  FrozenComplex(const FrozenComplex&) = delete;
+  FrozenComplex& operator=(const FrozenComplex&) = delete;
+  FrozenComplex(FrozenComplex&&) = default;
+  FrozenComplex& operator=(FrozenComplex&&) = default;
+
   int dim() const { return dim_; }
 
   int halo_depth() const { return halo_depth_; }

python/CMakeLists.txt

@@ -0,0 +1,17 @@
+include(FetchContent)
+FetchContent_Declare(pybind11
+  GIT_REPOSITORY https://github.com/pybind/pybind11.git
+  GIT_TAG stable)
+FetchContent_MakeAvailable(pybind11)
+
+pybind11_add_module(_core bindings.cpp)
+target_link_libraries(_core PRIVATE graphos::graphos)
+set_target_properties(_core PROPERTIES
+  LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/graphos)
+
+if(BUILD_TESTING)
+  add_test(NAME python.test_graphos
+           COMMAND ${Python_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_graphos.py)
+  set_tests_properties(python.test_graphos PROPERTIES
+    ENVIRONMENT "PYTHONPATH=${CMAKE_CURRENT_SOURCE_DIR}")
+endif()