Add Intel SHMEM Python Bindings

.gitignore

@@ -1,4 +1,8 @@
 .*.sw*
 build
+build-*/
 tags
 ishmem/config.h
+*.pyc
+__pycache__/
+*.egg-info/

CMakeLists.txt

@@ -27,6 +27,8 @@ option(BUILD_UNIT_TESTS "Build unit tests" FALSE)
 option(BUILD_PERF_TESTS "Build performance tests" FALSE)
 option(BUILD_EXAMPLES "Build examples" FALSE)
 option(BUILD_APPS "Build apps" FALSE)
+option(BUILD_PYTHON_BINDINGS "Build Python bindings" FALSE)
+option(ISHMEM4PY_BUILD_TORCH_INTEROP "Build optional Torch/XPU interop for ishmem4py" FALSE)
 option(BUILD_CMAKE_CONFIG "Build CMake config files" TRUE)
 option(ENABLE_ERROR_CHECKING "Validate API inputs" FALSE)
 option(ENABLE_DLMALLOC "Enable dlmalloc for shared heap" TRUE)
@@ -79,6 +81,8 @@ message(STATUS "Build unit tests:            ${BUILD_UNIT_TESTS}")
 message(STATUS "Build performance tests:     ${BUILD_PERF_TESTS}")
 message(STATUS "Build examples:              ${BUILD_EXAMPLES}")
 message(STATUS "Build apps:                  ${BUILD_APPS}")
+message(STATUS "Build Python bindings:       ${BUILD_PYTHON_BINDINGS}")
+message(STATUS "ishmem4py Torch interop:     ${ISHMEM4PY_BUILD_TORCH_INTEROP}")
 message(STATUS "Build CMake configs:         ${BUILD_CMAKE_CONFIG}")
 message(STATUS "Enable input validation:     ${ENABLE_ERROR_CHECKING}")
 message(STATUS "Enable dlmalloc:             ${ENABLE_DLMALLOC}")
@@ -161,6 +165,10 @@ add_subdirectory(src)
 # Build options for tests are handled directly in test/CMakeLists.txt
 add_subdirectory(test)
 
+if (BUILD_PYTHON_BINDINGS)
+    add_subdirectory(ishmem4py)
+endif()
+
 if (BUILD_EXAMPLES)
     add_subdirectory(examples)
 endif()

README.md

@@ -146,8 +146,8 @@ ISHMEM_RUNTIME=<backend> mpiexec.hydra -n 2 -hosts <allocated_node_id> ./scripts
 
 - *Note:* Current supported launchers include: MPI process launchers (i.e. `mpiexec`, `mpiexec.hydra`, `mpirun`, etc.), Slurm (i.e. `srun`, `salloc`, etc.), and PBS (i.e. `qsub`).
 
-- *Note:* Intel® SHMEM execution model requires applications to use a 1:1 mapping between PEs and GPU devices. Attempting to run an application without the `ishmrun` launch script may result in failure if this mapping is not maintained.
-  - For further details on device selection, please see [the ONEAPI_DEVICE_SELECTOR](https://github.com/intel/llvm/blob/sycl/sycl/doc/EnvironmentVariables.md#oneapi_device_selector).
+- *Note:* Intel® SHMEM execution model requires applications to use a 1:1 mapping between PEs and GPU devices. The default `ishmrun` launcher maintains that mapping by restricting each PE to a single visible GPU device. When multiple GPUs remain visible to a PE, set `ishmemx_attr_t.device_id` explicitly before calling `ishmemx_init_attr`.
+  - For further details on launcher-based device selection, please see [the ONEAPI_DEVICE_SELECTOR](https://github.com/intel/llvm/blob/sycl/sycl/doc/EnvironmentVariables.md#oneapi_device_selector).
 
 3. Validate the application ran successfully; example output:
 

docs/source/conf.py

@@ -10,6 +10,8 @@
 # -- Packages ----------------------------------------------------------------
 
 import datetime
+import os
+import sys
 
 # -- Project information -----------------------------------------------------
 
@@ -24,9 +26,16 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+sys.path.insert(0, os.path.abspath('../../ishmem4py/python'))
+
 extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
 ]
 
+autosummary_generate = False
+autodoc_member_order = 'bysource'
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.

docs/source/execution_model.rst

@@ -21,7 +21,9 @@ library<ishmemx_runtime_type_t>`.
    that assigns the environment variable **ZE_AFFINITY_MASK** so that each
    PE is assigned a single SYCL device. Usage of this script is described in
    Section :ref:`Compiling and Running
-   Programs<compiling_and_running_programs>`.
+   Programs<compiling_and_running_programs>`. When multiple GPUs remain
+   visible to a PE, applications must select one explicitly with
+   ``ishmemx_attr_t.device_id`` before calling ``ishmemx_init_attr``.
 
 .. note:: Intel® Data Center GPU Max Series devices utilize a multi-tile
    architecture (as of Intel®  SHMEM v1.0.0 with 1 or 2 tiles).  By default,
@@ -110,4 +112,3 @@ operations, see :ref:`Memory Ordering<memory_ordering>`.
 .. segment.
 .. For example, objects located in the symmetric data segment and objects
 .. located in the symmetric heap can be provided as arguments to the same OpenSHMEM operation.
-

docs/source/index.rst

@@ -45,6 +45,12 @@ Intel® SHMEM
    memory_ordering
    utility
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Python Bindings
+
+   ishmem4py
+
 .. ---------------
 .. Team Management
 .. ---------------