Support for dynamic system topology discovery

conda/environments/all_cuda-129_arch-aarch64.yaml

@@ -14,6 +14,7 @@ dependencies:
 - cuda-cudart-dev
 - cuda-cupti-dev
 - cuda-nvcc
+- cuda-nvml-dev
 - cuda-nvrtc-dev
 - cuda-nvtx-dev
 - cuda-sanitizer-api

conda/environments/all_cuda-129_arch-x86_64.yaml

@@ -14,6 +14,7 @@ dependencies:
 - cuda-cudart-dev
 - cuda-cupti-dev
 - cuda-nvcc
+- cuda-nvml-dev
 - cuda-nvrtc-dev
 - cuda-nvtx-dev
 - cuda-sanitizer-api

conda/environments/all_cuda-130_arch-aarch64.yaml

@@ -14,6 +14,7 @@ dependencies:
 - cuda-cudart-dev
 - cuda-cupti-dev
 - cuda-nvcc
+- cuda-nvml-dev
 - cuda-nvrtc-dev
 - cuda-nvtx-dev
 - cuda-sanitizer-api

conda/environments/all_cuda-130_arch-x86_64.yaml

@@ -14,6 +14,7 @@ dependencies:
 - cuda-cudart-dev
 - cuda-cupti-dev
 - cuda-nvcc
+- cuda-nvml-dev
 - cuda-nvrtc-dev
 - cuda-nvtx-dev
 - cuda-sanitizer-api

conda/recipes/librapidsmpf/recipe.yaml

@@ -52,6 +52,7 @@ cache:
       - ${{ compiler("cxx") }}
       - ${{ compiler("cuda") }} =${{ cuda_version }}
       - cuda-cupti-dev
+      - cuda-nvml-dev
       - cuda-version =${{ cuda_version }}
       - cmake ${{ cmake_version }}
       - ninja
@@ -60,6 +61,7 @@ cache:
       - cuda-version =${{ cuda_version }}
       - cuda-cudart-dev
       - cuda-cupti-dev
+      - cuda-nvml-dev
       - librmm =${{ minor_version }}
       - libcudf =${{ minor_version }}
       - openmpi >=5.0  # See <https://github.com/rapidsai/rapidsmpf/issues/17>
@@ -85,11 +87,13 @@ outputs:
       build:
         - cmake ${{ cmake_version }}
         - cuda-cupti-dev
+        - cuda-nvml-dev
         - ${{ stdlib("c") }}
       host:
         - cuda-version =${{ cuda_version }}
         - cuda-cudart-dev
         - cuda-cupti-dev
+        - cuda-nvml-dev
         - libcudf =${{ minor_version }}
         - openmpi >=5.0
         - ucxx ${{ ucxx_version }}
@@ -130,10 +134,12 @@ outputs:
       build:
         - cmake ${{ cmake_version }}
         - cuda-cupti-dev
+        - cuda-nvml-dev
         - ${{ stdlib("c") }}
       host:
         - cuda-cudart-dev
         - cuda-cupti-dev
+        - cuda-nvml-dev
         - cuda-version =${{ cuda_version }}
         - libcudf =${{ minor_version }}
         - librmm =${{ minor_version }}

cpp/CMakeLists.txt

@@ -173,6 +173,7 @@ add_library(
   src/shuffler/postbox.cpp
   src/shuffler/shuffler.cpp
   src/statistics.cpp
+  src/topology_discovery.cpp
   src/utils.cpp
 )
 if(RAPIDSMPF_HAVE_STREAMING)
@@ -230,7 +231,7 @@ target_include_directories(
 
 target_link_libraries(
   rapidsmpf
-  PUBLIC rmm::rmm cudf::cudf CCCL::CCCL $<TARGET_NAME_IF_EXISTS:ucxx::ucxx>
+  PUBLIC rmm::rmm cudf::cudf CCCL::CCCL CUDA::nvml $<TARGET_NAME_IF_EXISTS:ucxx::ucxx>
          $<TARGET_NAME_IF_EXISTS:libcoro>
   PRIVATE $<$<BOOL:${RAPIDSMPF_HAVE_NUMA}>:numa>
           $<TARGET_NAME_IF_EXISTS:MPI::MPI_C>
@@ -324,6 +325,11 @@ if(RAPIDSMPF_BUILD_EXAMPLES)
   add_subdirectory(examples)
 endif()
 
+# ##################################################################################################
+# * add tools
+# -------------------------------------------------------------------------------------
+add_subdirectory(tools)
+
 # ##################################################################################################
 # * install targets -------------------------------------------------------------------------------
 rapids_cmake_install_lib_dir(lib_dir)

cpp/include/rapidsmpf/topology_discovery.hpp

@@ -0,0 +1,122 @@
+/**
+ * SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <string>
+#include <vector>
+
+namespace rapidsmpf {
+
+/**
+ * @brief GPU information.
+ */
+struct GpuTopologyInfo {
+    unsigned int id;  ///< GPU device ID.
+    std::string name;  ///< GPU device name.
+    std::string pci_bus_id;  ///< PCI bus ID.
+    std::string uuid;  ///< GPU UUID.
+    int numa_node;  ///< NUMA node ID (-1 if unknown).
+    std::string cpu_affinity_list;  ///< CPU affinity list.
+    std::vector<int> cpu_cores;  ///< List of CPU core IDs.
+    std::vector<int> memory_binding;  ///< NUMA nodes for memory binding.
+    std::vector<std::string>
+        network_devices;  ///< Network devices (NICs) optimal for this GPU.
+};
+
+/**
+ * @brief Network device information.
+ */
+struct NetworkDeviceInfo {
+    std::string name;  ///< Device name (e.g., "mlx5_0").
+    int numa_node;  ///< NUMA node ID (-1 if unknown).
+    std::string pci_bus_id;  ///< PCI bus ID.
+};
+
+/**
+ * @brief System topology information.
+ */
+struct SystemTopologyInfo {
+    std::string hostname;  ///< System hostname.
+    unsigned int num_gpus;  ///< Total number of GPUs.
+    int num_numa_nodes;  ///< Total number of NUMA nodes.
+    int num_network_devices;  ///< Total number of network devices.
+    std::vector<GpuTopologyInfo> gpus;  ///< GPU topology information.
+    std::vector<NetworkDeviceInfo> network_devices;  ///< Network device information.
+};
+
+/**
+ * @brief PCIe topology path types.
+ */
+enum class PciePathType {
+    PIX = 0,  ///< Connection traversing at most a single PCIe bridge (best).
+    PXB = 1,  ///< Connection traversing multiple PCIe bridges.
+    PHB = 2,  ///< Connection traversing PCIe Host Bridge.
+    NODE = 3,  ///< Connection traversing PCIe and interconnect within NUMA node.
+    SYS = 4  ///< Connection traversing NUMA interconnect (worst).
+};
+
+/**
+ * @brief Discover system topology including GPUs, NUMA nodes, and network devices.
+ *
+ * This class provides methods to discover system topology information using NVML
+ * and /sys filesystem queries. It dynamically identifies GPU-to-NUMA-to-NIC mappings
+ * based on PCIe topology.
+ *
+ * Example usage:
+ * @code
+ * rapidsmpf::TopologyDiscovery discovery;
+ * if (discovery.discover()) {
+ *     auto topology = discovery.get_topology();
+ * }
+ * @endcode
+ */
+class TopologyDiscovery {
+  public:
+    /**
+     * @brief Construct a TopologyDiscovery instance.
+     */
+    TopologyDiscovery() = default;
+
+    /**
+     * @brief Destroy the TopologyDiscovery instance.
+     */
+    ~TopologyDiscovery() = default;
+
+    /**
+     * @brief Discover system topology.
+     *
+     * This method performs the actual discovery of GPUs, NUMA nodes, CPU affinity,
+     * and network devices. It must be called before `get_topology()`.
+     *
+     * @return true if discovery was successful, false otherwise.
+     */
+    bool discover();
+
+    /**
+     * @brief Get the discovered topology information.
+     *
+     * @return SystemTopologyInfo structure containing all topology data.
+     * @note `discover()` must be called first.
+     */
+    SystemTopologyInfo const& get_topology() const {
+        return topology_;
+    }
+
+    /**
+     * @brief Check if topology has been discovered.
+     *
+     * @return true if `discover()` has been called successfully.
+     */
+    bool is_discovered() const {
+        return discovered_;
+    }
+
+  private:
+    SystemTopologyInfo topology_;  ///< Discovered topology information.
+    bool discovered_{false};  ///< Flag indicating if topology has been discovered.
+};
+
+}  // namespace rapidsmpf