Add Python bindings for PaRSEC (py-parsec)

CMakeLists.txt

@@ -1327,3 +1327,24 @@ foreach( pattern_file ${pattern_files} )
   list( APPEND pattern_files_dest "${pattern_file}" )
 endforeach( pattern_file )
 add_custom_target(build_with_parsec ALL DEPENDS ${pattern_files_dest})
+
+#
+# Optional Python bindings (py-parsec)
+#
+# The python/ subdirectory contains Cython-based Python bindings.
+# They are built via pip/setuptools, not CMake, but we provide a
+# convenience target that runs the pip install after the C library
+# is built and installed.
+#
+option(PARSEC_PYTHON_BINDINGS "Build Python bindings (py-parsec)" OFF)
+if(PARSEC_PYTHON_BINDINGS)
+  find_package(Python3 COMPONENTS Interpreter REQUIRED)
+  add_custom_target(python_bindings ALL
+    COMMAND ${CMAKE_COMMAND} -E env
+      "PARSEC_ROOT=${CMAKE_INSTALL_PREFIX}"
+      ${Python3_EXECUTABLE} -m pip install -e "${CMAKE_CURRENT_SOURCE_DIR}/python"
+      --no-build-isolation -v
+    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/python"
+    COMMENT "Building Python bindings (py-parsec)"
+  )
+endif()

python/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+*.so
+*.pyd
+
+# Cython generated
+src/py_parsec/*.c
+src/py_parsec/*.html
+
+# Virtual environment
+venv/
+
+# Generated env script
+parsec_env.sh
+
+# IDE
+.vscode/
+.idea/
+
+# Coverage
+.coverage
+htmlcov/
+.pytest_cache/

python/Makefile

@@ -0,0 +1,74 @@
+# Makefile for Py_PaRSEC (lives inside parsec/python/)
+
+.PHONY: help install install-dev test test-cov lint format clean build docs
+
+help:  ## Show this help message
+	@echo "Available targets:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Install the package
+	pip install -e .
+
+install-dev:  ## Install the package with development dependencies
+	pip install -e ".[dev,test]"
+
+test:  ## Run tests
+	pytest
+
+test-cov:  ## Run tests with coverage
+	pytest --cov=py_parsec --cov-report=html --cov-report=term-missing
+
+test-mpi:  ## Run MPI tests
+	pytest -m mpi -v
+
+test-integration:  ## Run integration tests
+	pytest -m integration -v
+
+lint:  ## Run linting
+	flake8 src/ tests/
+	mypy src/
+
+format:  ## Format code
+	black src/ tests/
+	isort src/ tests/
+
+clean:  ## Clean build artifacts
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info/
+	rm -rf .pytest_cache/
+	rm -rf .coverage
+	rm -rf htmlcov/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	find . -type f -name "*.so" -delete
+	find . -type f -name "*.pyd" -delete
+
+build:  ## Build the package
+	python -m build
+
+build-ext:  ## Build Cython extensions
+	python setup.py build_ext --inplace
+
+build-parsec:  ## Build PaRSEC from the parent repo
+	python build_parsec4python.py --skip-env
+
+docs:  ## Build documentation
+	cd docs && make html
+
+check:  ## Run all checks (lint, format, test)
+	@echo "Running format check..."
+	black --check src/ tests/
+	isort --check-only src/ tests/
+	@echo "Running linting..."
+	flake8 src/ tests/
+	mypy src/
+	@echo "Running tests..."
+	pytest
+
+setup-dev:  ## Set up development environment
+	pip install -e ".[dev,test]"
+	pre-commit install
+
+dev: install-dev  ## Alias for install-dev
+check-all: check  ## Alias for check

python/README.md

@@ -0,0 +1,103 @@
+# Py_PaRSEC
+
+A Python interface for PaRSEC (Parallel Runtime System for Extreme Scale Computing).
+
+This directory (`python/`) lives inside the PaRSEC source tree and provides
+Cython-based Python bindings for the PaRSEC runtime.
+
+## Quick Start
+
+### Single Command Build and Install
+
+From this directory (`python/`):
+
+```bash
+# CPU-only installation (builds PaRSEC + installs bindings)
+python build_parsec4python.py
+
+# GPU installation with CUDA support
+python build_parsec4python.py --enable-cuda
+
+# GPU installation with HIP/ROCm support
+python build_parsec4python.py --enable-hip
+```
+
+The script automatically:
+1. Sets up a virtual environment in `python/venv/`
+2. Builds PaRSEC via CMake in `../build/` (the repo root)
+3. Installs PaRSEC to `../build/install/`
+4. Installs the `py-parsec` Python package
+5. Generates `parsec_env.sh` for environment setup
+
+### Manual Installation (Alternative)
+
+If you already have PaRSEC built and installed:
+
+```bash
+# 1. Setup environment
+python -m venv venv
+source venv/bin/activate
+
+# 2. Point to your PaRSEC installation
+export PARSEC_ROOT=/path/to/parsec/install
+
+# 3. Install Py_PaRSEC
+pip install -e .
+```
+
+### Common Parameter Parser
+
+Both stencil and DTD examples use a common parameter parsing system (`param_parser.py`) that provides:
+
+- **Verbose control** with four levels:
+  - `--verbose 0` or `--quiet`: Minimal output
+  - `--verbose 1`: Normal output (default)
+  - `--verbose 2`: Detailed output
+  - `--verbose 10`: Very detailed output (task messages)
+- **Unified parameter names** across all examples:
+  - `--M`, `--N`, `--K`: Matrix dimensions
+  - `--mb`, `--nb`, `--kb`: Block/tile sizes
+  - `--device`: Device selection (CPU/GPU)
+  - `--cores`: Number of cores
+
+### Run Examples
+
+```bash
+source venv/bin/activate
+source parsec_env.sh
+
+# Stencil
+python examples/stencil_1D.py --M 100 --mb 10 --K 5 --kb 1 --verbose 0
+
+# DTD GEMM
+python examples/dtd_simple_gemm.py --M 1024 --mb 128 --device CPU --verbose 0
+
+# Merge sort
+python examples/merge_sort.py
+```
+
+### Run Tests
+
+```bash
+source venv/bin/activate
+source parsec_env.sh
+
+pytest
+```
+
+## Requirements
+
+- Python 3.8+
+- NumPy
+- mpi4py
+- Cython 3.0+
+- MPI library (OpenMPI or MPICH)
+- PaRSEC (built from the parent directory)
+
+### GPU Requirements (Optional)
+- **CUDA**: CUDA Toolkit 4.0+
+- **HIP/ROCm**: ROCm 4.0+
+
+## License
+
+See the top-level LICENSE.txt file for details.