Add gRPC server and remote execution integrated in cuOpt solver

.gitignore

@@ -68,3 +68,4 @@ docs/cuopt/build
 cpp/include/cuopt/semantic_version.hpp
 !datasets/quadratic_programming
 !datasets/quadratic_programming/**
+dev_scripts/test_c_api

GRPC_ARCHITECTURE.md

@@ -0,0 +1,82 @@
+# gRPC-based Remote Solve Architecture
+
+## Overview
+
+cuOpt remote solve uses gRPC for transport and protobuf-generated stubs for the service API.
+The request/response payloads are serialized with a protobuf-based serializer that maps
+cuOpt data structures to protobuf messages. This preserves existing semantics while
+moving the network layer to a standard, well-supported RPC stack.
+
+## Service Definition
+
+The gRPC service is defined in `cpp/src/linear_programming/utilities/cuopt_remote_service.proto`
+and imports the message schema in `cuopt_remote.proto`. Code is generated by `protoc`
+plus `grpc_cpp_plugin` during the build.
+
+Core RPCs include:
+
+- `SubmitJob` / `UploadAndSubmit`
+- `CheckStatus`
+- `GetResult` / `StreamResult`
+- `StreamLogs`
+- `CancelJob`
+- `DeleteResult`
+- `GetIncumbents`
+
+## Components
+
+### gRPC Server (`cuopt_grpc_server`)
+
+- Source: `cpp/cuopt_grpc_server.cpp`
+- Implements `CuOptRemoteService` and owns the worker process pool.
+- Workers communicate with the main server process via shared memory + pipes.
+- For results, the server calls `to_host()` before serialization.
+- Supports streaming logs and incumbents through gRPC streaming endpoints.
+
+### gRPC Client Path (C++)
+
+- Client logic lives in `cpp/src/linear_programming/utilities/remote_solve_grpc.cpp`
+  and is used by `remote_solve.cu` and `cuopt_cli`.
+- The client serializes problems using the protobuf serializer, submits them
+  via gRPC, and deserializes results back into cuOpt solution objects.
+
+### Serialization Layer
+
+- Default serializer: `cpp/src/linear_programming/utilities/protobuf_serializer.cu`
+- Interface: `cpp/include/cuopt/linear_programming/utilities/remote_serialization.hpp`
+- Optional plugin override: `CUOPT_SERIALIZER_LIB` can load a custom serializer.
+- The serializer uses protobuf message types defined in `cuopt_remote.proto`.
+
+## Data Flow (LP/MIP)
+
+1. Client builds a problem (LP/MIP).
+2. Serializer converts the problem + settings into protobuf bytes.
+3. gRPC `SubmitJob` or `UploadAndSubmit` sends the bytes to the server.
+4. Server deserializes to cuOpt data structures.
+5. Server runs `solve_lp` / `solve_mip` in a worker process.
+6. Server calls `to_host()` and serializes the solution to protobuf bytes.
+7. Client retrieves results via `GetResult` / `StreamResult` and deserializes.
+
+## Generated Code (protoc output)
+
+Generated files are written to the CMake binary directory (not checked into source):
+
+- `cuopt_remote.pb.cc/.h`
+- `cuopt_remote_service.pb.cc/.h`
+- `cuopt_remote_service.grpc.pb.cc/.h`
+
+## Build Integration
+
+`cpp/CMakeLists.txt` drives code generation:
+
+- Locates `protoc` and `grpc_cpp_plugin`
+- Runs `protoc` to generate the `*.pb.cc/.h` sources
+- Adds generated sources to the `cuopt` library
+- Builds `cuopt_grpc_server` only when gRPC is available
+
+## Security Notes
+
+- Service stubs and message parsing are generated by `protoc` and `grpc_cpp_plugin`.
+- Payload serialization uses protobuf message APIs rather than hand-written parsing.
+- gRPC provides HTTP/2 framing, flow control, and standard status codes.
+```

build.sh

@@ -15,7 +15,7 @@ REPODIR=$(cd "$(dirname "$0")"; pwd)
 LIBCUOPT_BUILD_DIR=${LIBCUOPT_BUILD_DIR:=${REPODIR}/cpp/build}
 LIBMPS_PARSER_BUILD_DIR=${LIBMPS_PARSER_BUILD_DIR:=${REPODIR}/cpp/libmps_parser/build}
 
-VALIDARGS="clean libcuopt libmps_parser cuopt_mps_parser cuopt cuopt_server cuopt_sh_client docs deb -a -b -g -fsanitize -tsan -msan -v -l= --verbose-pdlp --build-lp-only  --no-fetch-rapids --skip-c-python-adapters --skip-tests-build --skip-routing-build --skip-fatbin-write --host-lineinfo [--cmake-args=\\\"<args>\\\"] [--cache-tool=<tool>] -n --allgpuarch --ci-only-arch --show_depr_warn -h --help"
+VALIDARGS="clean libcuopt libmps_parser cuopt_mps_parser cuopt cuopt_server cuopt_sh_client cuopt_grpc_server docs deb -a -b -g -fsanitize -tsan -msan -v -l= --verbose-pdlp --build-lp-only  --no-fetch-rapids --skip-c-python-adapters --skip-tests-build --skip-routing-build --skip-fatbin-write --host-lineinfo [--cmake-args=\\\"<args>\\\"] [--cache-tool=<tool>] -n --allgpuarch --ci-only-arch --show_depr_warn -h --help"
 HELP="$0 [<target> ...] [<flag> ...]
  where <target> is:
    clean            - remove all existing build artifacts and configuration (start over)
@@ -25,6 +25,7 @@ HELP="$0 [<target> ...] [<flag> ...]
    cuopt            - build the cuopt Python package
    cuopt_server     - build the cuopt_server Python package
    cuopt_sh_client  - build cuopt self host client
+  cuopt_grpc_server  - build the cuopt gRPC server executable (prototype)
    docs             - build the docs
    deb              - build deb package (requires libcuopt to be built first)
  and <flag> is:
@@ -53,7 +54,7 @@ HELP="$0 [<target> ...] [<flag> ...]
    --show_depr_warn - show cmake deprecation warnings
    -h               - print this text
 
- default action (no args) is to build and install 'libcuopt' then 'cuopt' then 'docs' targets
+ default action (no args) is to build and install 'libcuopt', 'cuopt', 'cuopt_grpc_server', then 'docs'
 
  libcuopt build dir is: ${LIBCUOPT_BUILD_DIR}
 
@@ -171,6 +172,13 @@ function cmakeArgs {
             ARGS=${ARGS//$EXTRA_CMAKE_ARGS/}
             # Filter the full argument down to just the extra string that will be added to cmake call
             EXTRA_CMAKE_ARGS=$(echo "$EXTRA_CMAKE_ARGS" | grep -Eo "\".+\"" | sed -e 's/^"//' -e 's/"$//')
+        else
+            # Support unquoted --cmake-args=VALUE form.
+            EXTRA_CMAKE_ARGS=$(echo "$ARGS" | { grep -Eo "\-\-cmake\-args=[^ ]+" || true; })
+            if [[ -n ${EXTRA_CMAKE_ARGS} ]]; then
+                ARGS=${ARGS//$EXTRA_CMAKE_ARGS/}
+                EXTRA_CMAKE_ARGS=${EXTRA_CMAKE_ARGS#--cmake-args=}
+            fi
         fi
     fi
 
@@ -280,6 +288,52 @@ if ! contains_string "DFIND_MPS_PARSER_CPP" "${EXTRA_CMAKE_ARGS[@]}"; then
     EXTRA_CMAKE_ARGS+=("-DFIND_MPS_PARSER_CPP=ON")
 fi
 
+# Prefer config packages to avoid mixing system and conda find modules.
+if ! contains_string "CMAKE_FIND_PACKAGE_PREFER_CONFIG" "${EXTRA_CMAKE_ARGS[@]}"; then
+    EXTRA_CMAKE_ARGS+=("-DCMAKE_FIND_PACKAGE_PREFER_CONFIG=ON")
+fi
+
+# Default to the active install prefix for dependency lookup unless overridden.
+if ! contains_string "CMAKE_PREFIX_PATH" "${EXTRA_CMAKE_ARGS[@]}"; then
+    EXTRA_CMAKE_ARGS+=("-DCMAKE_PREFIX_PATH=${INSTALL_PREFIX}")
+fi
+
+# If conda-provided protobuf/grpc configs are available, prefer them by default.
+if [ -d "${INSTALL_PREFIX}/lib/cmake/protobuf" ]; then
+    if ! contains_string "Protobuf_DIR" "${EXTRA_CMAKE_ARGS[@]}"; then
+        EXTRA_CMAKE_ARGS+=("-DProtobuf_DIR=${INSTALL_PREFIX}/lib/cmake/protobuf")
+    fi
+fi
+if [ -d "${INSTALL_PREFIX}/lib/cmake/grpc" ]; then
+    if ! contains_string "gRPC_DIR" "${EXTRA_CMAKE_ARGS[@]}"; then
+        EXTRA_CMAKE_ARGS+=("-DgRPC_DIR=${INSTALL_PREFIX}/lib/cmake/grpc")
+    fi
+fi
+
+# Prefer conda's ZLIB config if available to avoid system static zlib references.
+if [ -d "${INSTALL_PREFIX}/lib/cmake/ZLIB" ]; then
+    if ! contains_string "ZLIB_DIR" "${EXTRA_CMAKE_ARGS[@]}"; then
+        EXTRA_CMAKE_ARGS+=("-DZLIB_DIR=${INSTALL_PREFIX}/lib/cmake/ZLIB")
+    fi
+fi
+
+# Avoid pulling system ZLIB config that references missing libz.a.
+if [ -d "/usr/lib64/cmake/ZLIB" ] || [ -d "/lib64/cmake/ZLIB" ]; then
+    if ! contains_string "CMAKE_IGNORE_PATH" "${EXTRA_CMAKE_ARGS[@]}"; then
+        EXTRA_CMAKE_ARGS+=("-DCMAKE_IGNORE_PATH=/usr/lib64/cmake/ZLIB;/lib64/cmake/ZLIB")
+    fi
+fi
+
+# Prefer shared zlib if FindZLIB is used.
+if ! contains_string "ZLIB_USE_STATIC_LIBS" "${EXTRA_CMAKE_ARGS[@]}"; then
+    EXTRA_CMAKE_ARGS+=("-DZLIB_USE_STATIC_LIBS=OFF")
+fi
+
+# Hint FindZLIB to use the active prefix if no config is found.
+if ! contains_string "ZLIB_ROOT" "${EXTRA_CMAKE_ARGS[@]}"; then
+    EXTRA_CMAKE_ARGS+=("-DZLIB_ROOT=${INSTALL_PREFIX}")
+fi
+
 # If clean given, run it prior to any other steps
 if hasArg clean; then
     # If the dirs to clean are mounted dirs in a container, the
@@ -362,6 +416,13 @@ fi
 if buildAll || hasArg libcuopt; then
     mkdir -p "${LIBCUOPT_BUILD_DIR}"
     cd "${LIBCUOPT_BUILD_DIR}"
+    # If the cache points at system ZLIB, clear it so updated hints take effect.
+    if [ -f "${LIBCUOPT_BUILD_DIR}/CMakeCache.txt" ]; then
+        if grep -Eq "/(usr/)?lib64/cmake/ZLIB" "${LIBCUOPT_BUILD_DIR}/CMakeCache.txt"; then
+            rm -f "${LIBCUOPT_BUILD_DIR}/CMakeCache.txt"
+            rm -rf "${LIBCUOPT_BUILD_DIR}/CMakeFiles"
+        fi
+    fi
     cmake -DDEFINE_ASSERT=${DEFINE_ASSERT} \
           -DDEFINE_BENCHMARK="${DEFINE_BENCHMARK}" \
           -DDEFINE_PDLP_VERBOSE_MODE=${DEFINE_PDLP_VERBOSE_MODE} \
@@ -394,6 +455,49 @@ if buildAll || hasArg libcuopt; then
     fi
 fi
 
+################################################################################
+# Build the cuopt gRPC server (prototype)
+if buildAll || hasArg cuopt_grpc_server; then
+    mkdir -p "${LIBCUOPT_BUILD_DIR}"
+    cd "${LIBCUOPT_BUILD_DIR}"
+
+    # Ensure gRPC is enabled and configured in this build directory.
+    cmake -DDEFINE_ASSERT=${DEFINE_ASSERT} \
+          -DDEFINE_BENCHMARK="${DEFINE_BENCHMARK}" \
+          -DDEFINE_PDLP_VERBOSE_MODE=${DEFINE_PDLP_VERBOSE_MODE} \
+          -DLIBCUOPT_LOGGING_LEVEL="${LOGGING_ACTIVE_LEVEL}" \
+          -DCMAKE_INSTALL_PREFIX="${INSTALL_PREFIX}" \
+          -DCMAKE_CUDA_ARCHITECTURES=${CUOPT_CMAKE_CUDA_ARCHITECTURES} \
+          -DDISABLE_DEPRECATION_WARNING=${BUILD_DISABLE_DEPRECATION_WARNING} \
+          -DCMAKE_BUILD_TYPE=${BUILD_TYPE} \
+          -DFETCH_RAPIDS=${FETCH_RAPIDS} \
+          -DBUILD_LP_ONLY=${BUILD_LP_ONLY} \
+          -DBUILD_SANITIZER=${BUILD_SANITIZER} \
+          -DBUILD_TSAN=${BUILD_TSAN} \
+          -DBUILD_MSAN=${BUILD_MSAN} \
+          -DSKIP_C_PYTHON_ADAPTERS=${SKIP_C_PYTHON_ADAPTERS} \
+          -DBUILD_TESTS=$((1 - ${SKIP_TESTS_BUILD})) \
+          -DSKIP_ROUTING_BUILD=${SKIP_ROUTING_BUILD} \
+          -DWRITE_FATBIN=${WRITE_FATBIN} \
+          -DHOST_LINEINFO=${HOST_LINEINFO} \
+          -DINSTALL_TARGET="${INSTALL_TARGET}" \
+          -DCUOPT_ENABLE_GRPC=ON \
+          "${CACHE_ARGS[@]}" \
+          "${EXTRA_CMAKE_ARGS[@]}" \
+          "${REPODIR}"/cpp
+
+    # Build the server target
+    cmake --build "${LIBCUOPT_BUILD_DIR}" --target cuopt_grpc_server ${VERBOSE_FLAG} -j"${PARALLEL_LEVEL}"
+
+    # Install the server executable
+    if [ -z "${INSTALL_TARGET}" ]; then
+        echo "Skipping install of cuopt_grpc_server (-n flag set)"
+    else
+        install -m 755 "${LIBCUOPT_BUILD_DIR}/cuopt_grpc_server" "${INSTALL_PREFIX}/bin/"
+        echo "Installed cuopt_grpc_server to ${INSTALL_PREFIX}/bin/"
+    fi
+fi
+
 ################################################################################
 # Build deb package
 if hasArg deb; then
@@ -414,16 +518,39 @@ fi
 if buildAll || hasArg cuopt; then
     cd "${REPODIR}"/python/cuopt
 
-    # $EXTRA_CMAKE_ARGS gets concatenated into a string with [*] and then we find/replace spaces with semi-colons
-    SKBUILD_CMAKE_ARGS="-DCMAKE_PREFIX_PATH=${INSTALL_PREFIX};-DCMAKE_LIBRARY_PATH=${LIBCUOPT_BUILD_DIR};-DCMAKE_CUDA_ARCHITECTURES=${CUOPT_CMAKE_CUDA_ARCHITECTURES};${EXTRA_CMAKE_ARGS[*]// /;}" \
+    # Convert EXTRA_CMAKE_ARGS into a semicolon-delimited list, escaping
+    # any semicolons in values so scikit-build-core treats each -D as one arg.
+    SKBUILD_EXTRA_ARGS=()
+    for extra_arg in "${EXTRA_CMAKE_ARGS[@]}"; do
+        SKBUILD_EXTRA_ARGS+=("${extra_arg//;/\\;}")
+    done
+    SKBUILD_EXTRA_ARGS_JOINED=""
+    if [ ${#SKBUILD_EXTRA_ARGS[@]} -gt 0 ]; then
+        SKBUILD_EXTRA_ARGS_JOINED="$(IFS=';'; echo "${SKBUILD_EXTRA_ARGS[*]}")"
+    fi
+    SKBUILD_CMAKE_ARGS="-DCMAKE_PREFIX_PATH=${INSTALL_PREFIX};-DCMAKE_LIBRARY_PATH=${LIBCUOPT_BUILD_DIR};-DCMAKE_CUDA_ARCHITECTURES=${CUOPT_CMAKE_CUDA_ARCHITECTURES}"
+    if [ -n "${SKBUILD_EXTRA_ARGS_JOINED}" ]; then
+        SKBUILD_CMAKE_ARGS="${SKBUILD_CMAKE_ARGS};${SKBUILD_EXTRA_ARGS_JOINED}"
+    fi
         python "${PYTHON_ARGS_FOR_INSTALL[@]}" .
 fi
 
 # Build and install the cuopt MPS parser Python package
 if buildAll || hasArg cuopt_mps_parser; then
     cd "${REPODIR}"/python/cuopt/cuopt/linear_programming
 
-    SKBUILD_CMAKE_ARGS="-DCMAKE_PREFIX_PATH=${INSTALL_PREFIX};-DCMAKE_LIBRARY_PATH=${LIBCUOPT_BUILD_DIR};-DCMAKE_CUDA_ARCHITECTURES=${CUOPT_CMAKE_CUDA_ARCHITECTURES};${EXTRA_CMAKE_ARGS[*]// /;}" \
+    SKBUILD_EXTRA_ARGS=()
+    for extra_arg in "${EXTRA_CMAKE_ARGS[@]}"; do
+        SKBUILD_EXTRA_ARGS+=("${extra_arg//;/\\;}")
+    done
+    SKBUILD_EXTRA_ARGS_JOINED=""
+    if [ ${#SKBUILD_EXTRA_ARGS[@]} -gt 0 ]; then
+        SKBUILD_EXTRA_ARGS_JOINED="$(IFS=';'; echo "${SKBUILD_EXTRA_ARGS[*]}")"
+    fi
+    SKBUILD_CMAKE_ARGS="-DCMAKE_PREFIX_PATH=${INSTALL_PREFIX};-DCMAKE_LIBRARY_PATH=${LIBCUOPT_BUILD_DIR};-DCMAKE_CUDA_ARCHITECTURES=${CUOPT_CMAKE_CUDA_ARCHITECTURES}"
+    if [ -n "${SKBUILD_EXTRA_ARGS_JOINED}" ]; then
+        SKBUILD_CMAKE_ARGS="${SKBUILD_CMAKE_ARGS};${SKBUILD_EXTRA_ARGS_JOINED}"
+    fi
         python "${PYTHON_ARGS_FOR_INSTALL[@]}" .
 fi
 

ci/build_wheel_libcuopt.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2023-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
 set -euo pipefail
@@ -17,7 +17,10 @@ fi
 # Install Boost and TBB
 bash ci/utils/install_boost_tbb.sh
 
-export SKBUILD_CMAKE_ARGS="-DCUOPT_BUILD_WHEELS=ON;-DDISABLE_DEPRECATION_WARNING=ON"
+# Install Protobuf + gRPC (protoc + grpc_cpp_plugin)
+bash ci/utils/install_protobuf_grpc.sh
+
+export SKBUILD_CMAKE_ARGS="-DCUOPT_BUILD_WHEELS=ON;-DDISABLE_DEPRECATION_WARNING=ON;-DCUOPT_ENABLE_GRPC=ON"
 
 # For pull requests we are enabling assert mode.
 if [ "$RAPIDS_BUILD_TYPE" = "pull-request" ]; then

ci/utils/install_protobuf_grpc.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+set -euo pipefail
+
+# Install Protobuf and gRPC C++ development libraries
+if [ -f /etc/os-release ]; then
+    . /etc/os-release
+    if [[ "$ID" == "rocky" ]]; then
+        echo "Detected Rocky Linux. Installing Protobuf + gRPC via dnf..."
+        # Enable PowerTools (Rocky 8) or CRB (Rocky 9) repository for protobuf-devel
+        if [[ "${VERSION_ID%%.*}" == "8" ]]; then
+            dnf config-manager --set-enabled powertools || dnf config-manager --set-enabled PowerTools || true
+        elif [[ "${VERSION_ID%%.*}" == "9" ]]; then
+            dnf config-manager --set-enabled crb || true
+        fi
+        # Protobuf (headers + protoc)
+        dnf install -y protobuf-devel protobuf-compiler
+
+        # gRPC C++ (headers/libs + grpc_cpp_plugin for codegen)
+        # Package names can vary by repo; try the common ones first.
+        dnf install -y grpc-devel grpc-plugins || dnf install -y grpc-devel || true
+    elif [[ "$ID" == "ubuntu" ]]; then
+        echo "Detected Ubuntu. Installing Protobuf + gRPC via apt..."
+        apt-get update
+        # Protobuf (headers + protoc)
+        apt-get install -y libprotobuf-dev protobuf-compiler
+
+        # gRPC C++ (headers/libs + grpc_cpp_plugin for codegen)
+        apt-get install -y libgrpc++-dev protobuf-compiler-grpc
+    else
+        echo "Unknown OS: $ID. Please install Protobuf + gRPC development libraries manually."
+        exit 1
+    fi
+else
+    echo "/etc/os-release not found. Cannot determine OS. Please install Protobuf + gRPC development libraries manually."
+    exit 1
+fi

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

@@ -25,13 +25,15 @@ dependencies:
 - doxygen=1.9.1
 - fastapi
 - gcc_linux-aarch64=14.*
+- grpc-cpp
 - ipython
 - jsonref==1.1.0
 - libboost-devel
 - libcudss-dev >=0.7
 - libcurand-dev
 - libcusolver-dev
 - libcusparse-dev
+- libprotobuf
 - libraft-headers==26.2.*,>=0.0.0a0
 - librmm==26.2.*,>=0.0.0a0
 - make

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

@@ -25,13 +25,15 @@ dependencies:
 - doxygen=1.9.1
 - fastapi
 - gcc_linux-64=14.*
+- grpc-cpp
 - ipython
 - jsonref==1.1.0
 - libboost-devel
 - libcudss-dev >=0.7
 - libcurand-dev
 - libcusolver-dev
 - libcusparse-dev
+- libprotobuf
 - libraft-headers==26.2.*,>=0.0.0a0
 - librmm==26.2.*,>=0.0.0a0
 - make

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

@@ -25,13 +25,15 @@ dependencies:
 - doxygen=1.9.1
 - fastapi
 - gcc_linux-aarch64=14.*
+- grpc-cpp
 - ipython
 - jsonref==1.1.0
 - libboost-devel
 - libcudss-dev >=0.7
 - libcurand-dev
 - libcusolver-dev
 - libcusparse-dev
+- libprotobuf
 - libraft-headers==26.2.*,>=0.0.0a0
 - librmm==26.2.*,>=0.0.0a0
 - make