build: add the CUDA-free cuopt_client library

With the host code now separable, this adds the target that makes use of it.

cuopt_client holds the host-side problem representation (parsers,
data_model_view, mps_data_model, writers), the gRPC wire protocol (generated
protos + mappers) and the gRPC clients for both LP/MIP and routing. libcuopt and
cuopt_grpc_server both link it, so there is one mapper implementation rather than
a client-side fork.

Both gRPC arms qualify: the routing mappers added in #1597 reference no
raft/rmm/thrust either. solve_remote.cpp stays in libcuopt -- it is the
local-vs-remote dispatcher and calls into the GPU solver.

Built as an OBJECT library plus a SHARED library, mirroring cuopt_objs/cuopt.
cuopt_static embeds the objects directly rather than linking the shared library,
because the internal test binaries reach parser internals such as
mps_phase_registry_t.

Two build details worth knowing:

* cuopt_client uses default visibility, deliberately unlike cuopt_objs. libcuopt
  depends on roughly 214 of its symbols -- essentially the whole host-side API --
  because this library was carved out of the internals rather than designed as a
  curated CUOPT_EXPORT surface. Hiding them makes libcuopt.so fail to load with
  "undefined symbol: grpc_client_t::solve_mip".

* logger.cpp moves into the client sources: both the parsers and the gRPC code
  include <utilities/logger.hpp>, so without it the library has an unresolved
  reference to the logger.

Result:

    libcuopt_client.so NEEDED: libgrpc++, libprotobuf, libabseil,
                               librapids_logger, libc, libstdc++, libgomp, libdl
                               -- no libcudart, no rmm, no raft, no cudss
    ldd -r over libcuopt.so + libcuopt_client.so: 0 unresolved symbols

Note that raft/rmm headers are still needed at *build* time (the CPU headers
transitively include them), which costs nothing at runtime because the device
getters throw. Separating the headers is follow-up work, and is what a standalone
client package would additionally require.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>

Author: ramakrishnap-nv

cpp/CMakeLists.txt

@@ -550,11 +550,12 @@ if (BUILD_TESTS)
 endif ()
 
 set(CUOPT_SRC_FILES)
+set(CUOPT_CLIENT_SRC_FILES)
 set(MPS_FAST_SRC_FILES)
 add_subdirectory(src)
 
 if (HOST_LINEINFO)
-    set_source_files_properties(${CUOPT_SRC_FILES} DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTIES COMPILE_OPTIONS "-g1")
+    set_source_files_properties(${CUOPT_SRC_FILES} ${CUOPT_CLIENT_SRC_FILES} DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTIES COMPILE_OPTIONS "-g1")
 endif ()
 
 # Needed for the fast MPS parser, available on all x86-64-v3 compliant x86 CPUs (essentially since Haswell ~2013)
@@ -567,11 +568,11 @@ endif ()
 # TODO: figure out a set of flags for ARM that fits the range of CPUs we wish to support (neoverse?)
 # NEON should be universal on aarch64 and enough for our purposes (parsing) though
 
-# Apply -UNDEBUG only to solver source files (not gRPC infrastructure).
-# Must happen before gRPC files are appended to CUOPT_SRC_FILES.
+# Apply -UNDEBUG only to solver and parser source files (not gRPC infrastructure).
+# Must happen before gRPC files are appended to CUOPT_CLIENT_SRC_FILES.
 # Uses APPEND to preserve any existing per-file options (e.g. -g1 from HOST_LINEINFO).
 if (DEFINE_ASSERT)
-    set_property(SOURCE ${CUOPT_SRC_FILES} DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    set_property(SOURCE ${CUOPT_SRC_FILES} ${CUOPT_CLIENT_SRC_FILES} DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
             APPEND PROPERTY COMPILE_OPTIONS "-UNDEBUG")
 endif ()
 
@@ -598,9 +599,7 @@ if (NOT SKIP_GRPC_BUILD)
             src/grpc/client/grpc_client.cpp
             src/grpc/client/grpc_client_env.cpp
             src/grpc/client/cython_grpc_client.cpp
-            src/grpc/client/solve_remote.cpp
     )
-
     # Routing (VRP) arm: everything that depends on the routing engine. Kept as
     # its own list so a routing-only gRPC client can be split out of the
     # cuopt_grpc component without moving code around again.
@@ -616,7 +615,17 @@ if (NOT SKIP_GRPC_BUILD)
     if (CUOPT_ENABLE_GRPC_ROUTING)
         list(APPEND GRPC_INFRA_FILES ${GRPC_ROUTING_FILES})
     endif ()
-    list(APPEND CUOPT_SRC_FILES ${GRPC_INFRA_FILES})
+
+    # Both arms are CUDA-free -- the routing mappers reference no raft/rmm/thrust
+    # either -- so the wire protocol and clients build into cuopt_client, shared by
+    # libcuopt, cuopt_grpc_server and the Python client extensions. One mapper
+    # implementation, not a client-side fork of it.
+    list(APPEND CUOPT_CLIENT_SRC_FILES ${GRPC_INFRA_FILES})
+
+    # solve_remote.cpp is the local-vs-remote dispatcher: it calls into the GPU
+    # solver, so it stays in cuopt_objs rather than moving down to cuopt_client.
+    list(APPEND CUOPT_SRC_FILES src/grpc/client/solve_remote.cpp)
+    list(APPEND GRPC_INFRA_FILES src/grpc/client/solve_remote.cpp)
 
     # Always keep NDEBUG defined for gRPC infrastructure files so that abseil
     # headers inline Mutex::Dtor() instead of emitting an external call.
@@ -631,6 +640,120 @@ if (NOT SKIP_GRPC_BUILD)
             APPEND PROPERTY COMPILE_OPTIONS "$<$<COMPILE_LANGUAGE:CXX>:-fvisibility=default>")
 endif (NOT SKIP_GRPC_BUILD)
 
+# ##################################################################################################
+# - cuopt_client - CPU-only support library ----------------------------------------------------------
+#
+# Holds the host-side problem representation (parsers, data_model_view, mps_data_model,
+# writers), the gRPC wire protocol (generated protos + mappers), and the gRPC client.
+# None of it touches CUDA, so this library links no CUDA runtime.
+#
+# It exists so the Python extension modules that never call into the GPU -- data_model,
+# solver_settings, io, and the gRPC client -- can link something other than libcuopt.so,
+# which is what makes a GPU-free client install possible. libcuopt and cuopt_grpc_server
+# both link it, so there is exactly one implementation of the mappers, not a client fork.
+#
+# LANGUAGES is deliberately not CUDA here: adding a .cu file to CUOPT_CLIENT_SRC_FILES
+# should fail loudly rather than quietly reintroduce a CUDA dependency.
+# Built as an OBJECT library first, mirroring cuopt_objs/cuopt. The shared library below
+# keeps hidden visibility and exports only the curated CUOPT_EXPORT surface, while
+# cuopt_static (for internal tests) links the objects directly -- internal symbols such as
+# the fast MPS parser's mps_phase_registry_t are not exported, and the internal test
+# binaries need them.
+add_library(cuopt_client_objs OBJECT ${CUOPT_CLIENT_SRC_FILES})
+# NOTE: default visibility, deliberately unlike cuopt_objs.
+#
+# cuopt_objs can hide everything not marked CUOPT_EXPORT because libcuopt has a curated
+# public C++ API. cuopt_client is different: it was carved out of the *internals*, so
+# libcuopt itself depends on ~214 of its symbols (the whole cpu_optimization_problem_t /
+# data_model_view_t / mps_data_model_t / grpc_client_t surface). Those are internal
+# cross-library references, not a public API, and hiding them makes libcuopt.so fail to
+# load with e.g. "undefined symbol: grpc_client_t::solve_mip".
+#
+# Curating them behind CUOPT_EXPORT would mean annotating essentially every host-side
+# method, so default visibility is the right trade here.
+set_target_properties(cuopt_client_objs
+        PROPERTIES POSITION_INDEPENDENT_CODE ON
+        CXX_SCAN_FOR_MODULES OFF
+)
+
+add_library(cuopt_client SHARED $<TARGET_OBJECTS:cuopt_client_objs>)
+add_library(cuopt::cuopt_client ALIAS cuopt_client)
+
+target_include_directories(cuopt_client
+        PUBLIC
+        "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
+        "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>"
+        INTERFACE
+        "$<INSTALL_INTERFACE:include>"
+)
+
+target_compile_definitions(cuopt_client
+        PUBLIC "CUOPT_LOG_ACTIVE_LEVEL=RAPIDS_LOGGER_LOG_LEVEL_${LIBCUOPT_LOGGING_LEVEL}"
+)
+
+set_target_properties(cuopt_client
+        PROPERTIES POSITION_INDEPENDENT_CODE ON
+        CXX_SCAN_FOR_MODULES OFF
+        BUILD_RPATH "\$ORIGIN"
+        INSTALL_RPATH "\$ORIGIN"
+        LINKER_LANGUAGE CXX
+)
+
+target_compile_definitions(cuopt_client_objs
+        PUBLIC "CUOPT_LOG_ACTIVE_LEVEL=RAPIDS_LOGGER_LOG_LEVEL_${LIBCUOPT_LOGGING_LEVEL}"
+)
+
+target_compile_options(cuopt_client_objs
+        PRIVATE "$<$<COMPILE_LANGUAGE:CXX>:${CUOPT_CXX_FLAGS}>"
+)
+
+target_include_directories(cuopt_client_objs
+        PRIVATE
+        "${CMAKE_CURRENT_SOURCE_DIR}/../thirdparty"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src/io"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src/grpc"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src/grpc/client"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src/grpc/codegen/generated"
+        "${CMAKE_CURRENT_BINARY_DIR}"
+        "${CMAKE_CURRENT_BINARY_DIR}/include"
+        $<$<BOOL:${CUOPT_PARSER_WITH_BZIP2}>:${BZIP2_INCLUDE_DIRS}>
+        $<$<BOOL:${CUOPT_PARSER_WITH_ZLIB}>:${ZLIB_INCLUDE_DIRS}>
+        PUBLIC
+        "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
+        "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>"
+        INTERFACE
+        "$<INSTALL_INTERFACE:include>"
+)
+
+# CCCL is a compile-time (header-only) dependency here: the fast MPS parser uses
+# host helpers from <cuda/cmath> (ceil_div, round_up). It pulls in no CUDA runtime.
+# bzip2 / zlib / lz4 are dlopen'd at runtime by file_to_string.cpp, so they are
+# header-only here too and deliberately absent from the link line.
+# The OBJECT library needs these for their INTERFACE include dirs / defines at compile time.
+target_link_libraries(cuopt_client_objs
+        PUBLIC
+        rapids_logger::rapids_logger
+        CCCL::CCCL
+        PRIVATE
+        simde::simde
+        OpenMP::OpenMP_CXX
+        $<$<BOOL:${CUOPT_ENABLE_GRPC}>:protobuf::libprotobuf>
+        $<$<BOOL:${CUOPT_ENABLE_GRPC}>:gRPC::grpc++>
+)
+
+target_link_libraries(cuopt_client
+        PUBLIC
+        rapids_logger::rapids_logger
+        CCCL::CCCL
+        PRIVATE
+        simde::simde
+        OpenMP::OpenMP_CXX
+        ${CMAKE_DL_LIBS}
+        $<$<BOOL:${CUOPT_ENABLE_GRPC}>:protobuf::libprotobuf>
+        $<$<BOOL:${CUOPT_ENABLE_GRPC}>:gRPC::grpc++>
+)
+
 add_library(cuopt_objs OBJECT
         ${CUOPT_SRC_FILES}
 )
@@ -757,6 +880,7 @@ target_compile_definitions(cuopt_objs PUBLIC
 
 target_link_libraries(cuopt_objs
         PUBLIC
+        cuopt::cuopt_client
         CUDA::cublas
         CUDA::cusparse
         rmm::rmm
@@ -777,7 +901,10 @@ target_link_libraries(cuopt_objs
 # - generate tests --------------------------------------------------------------------------------
 if (BUILD_TESTS)
     include(CTest)
-    add_library(cuopt_static STATIC $<TARGET_OBJECTS:cuopt_objs>)
+    # Embeds cuopt_client_objs directly rather than linking libcuopt_client.so: the internal
+    # test binaries reach parser internals that the shared library deliberately does not
+    # export. Do not also link cuopt::cuopt_client here -- that would duplicate every symbol.
+    add_library(cuopt_static STATIC $<TARGET_OBJECTS:cuopt_objs> $<TARGET_OBJECTS:cuopt_client_objs>)
     target_link_libraries(cuopt_static
             PUBLIC
             CUDA::cublas
@@ -839,6 +966,7 @@ target_include_directories(cuopt
 )
 target_link_libraries(cuopt
         PUBLIC
+        cuopt::cuopt_client
         CUDA::cublas
         CUDA::cusparse
         rmm::rmm
@@ -904,14 +1032,14 @@ else ()
 endif ()
 
 # adds the .so files to the runtime deb package
-install(TARGETS cuopt
+install(TARGETS cuopt cuopt_client
         DESTINATION ${_LIB_DEST}
         COMPONENT runtime
         EXPORT cuopt-exports
 )
 
 # adds the .so files to the development deb package
-install(TARGETS cuopt
+install(TARGETS cuopt cuopt_client
         DESTINATION ${_LIB_DEST}
         COMPONENT dev
 )
@@ -939,7 +1067,7 @@ cuOpt library is a collection of GPU accelerated combinatorial optimization algo
 
 rapids_export(INSTALL cuopt
         EXPORT_SET cuopt-exports
-        GLOBAL_TARGETS cuopt
+        GLOBAL_TARGETS cuopt cuopt_client
         NAMESPACE cuopt::
         DOCUMENTATION doc_string
 )
@@ -948,7 +1076,7 @@ rapids_export(INSTALL cuopt
 # - build export -------------------------------------------------------------------------------
 rapids_export(BUILD cuopt
         EXPORT_SET cuopt-exports
-        GLOBAL_TARGETS cuopt
+        GLOBAL_TARGETS cuopt cuopt_client
         NAMESPACE cuopt::
         DOCUMENTATION doc_string
 )

cpp/src/CMakeLists.txt

@@ -4,11 +4,15 @@
 # cmake-format: on
 
 set(UTIL_SRC_FILES ${CMAKE_CURRENT_SOURCE_DIR}/utilities/seed_generator.cu
-                   ${CMAKE_CURRENT_SOURCE_DIR}/utilities/logger.cpp
                    ${CMAKE_CURRENT_SOURCE_DIR}/utilities/version_info.cpp
                    ${CMAKE_CURRENT_SOURCE_DIR}/utilities/timestamp_utils.cpp
                    ${CMAKE_CURRENT_SOURCE_DIR}/utilities/work_unit_scheduler.cpp)
 
+# logger.cpp backs <utilities/logger.hpp>, which both the parsers and the gRPC
+# sources include, so it belongs to the CPU library. Without this, cuopt_client would
+# have an undefined reference to the logger.
+set(UTIL_CLIENT_SRC_FILES ${CMAKE_CURRENT_SOURCE_DIR}/utilities/logger.cpp)
+
 add_subdirectory(linear_algebra)
 add_subdirectory(pdlp)
 add_subdirectory(math_optimization)
@@ -26,4 +30,5 @@ add_subdirectory(branch_and_bound)
 add_subdirectory(cuts)
 
 set(CUOPT_SRC_FILES ${CUOPT_SRC_FILES} ${UTIL_SRC_FILES} PARENT_SCOPE)
+set(CUOPT_CLIENT_SRC_FILES ${CUOPT_CLIENT_SRC_FILES} ${UTIL_CLIENT_SRC_FILES} PARENT_SCOPE)
 set(MPS_FAST_SRC_FILES ${MPS_FAST_SRC_FILES} PARENT_SCOPE)

cpp/src/io/CMakeLists.txt

@@ -23,5 +23,10 @@ set(PARSERS_SRC_FILES
   ${MPS_FAST_SRC_FILES}
 )
 
-set(CUOPT_SRC_FILES ${CUOPT_SRC_FILES} ${PARSERS_SRC_FILES} PARENT_SCOPE)
+# The parsers and the host-side problem representation are CUDA-free (the only
+# `cuda::` uses are host integer helpers from header-only libcu++), so they build
+# into the CPU-only cuopt_client library rather than into cuopt_objs. That is what
+# lets the Python data_model / solver_settings / io extension modules link a
+# library with no CUDA runtime dependency.
+set(CUOPT_CLIENT_SRC_FILES ${CUOPT_CLIENT_SRC_FILES} ${PARSERS_SRC_FILES} PARENT_SCOPE)
 set(MPS_FAST_SRC_FILES ${MPS_FAST_SRC_FILES} PARENT_SCOPE)

cpp/src/math_optimization/CMakeLists.txt

@@ -5,12 +5,20 @@
 
 list(PREPEND
   MATH_OPT_SRC_FILES
-  ${CMAKE_CURRENT_SOURCE_DIR}/solver_settings.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/solver_settings_gpu.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/solution_reader.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/solution_writer.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/tic_toc.cpp
   )
 
+# solver_settings_t is host-only apart from the device members in solver_settings_gpu.cu,
+# so the bulk of it builds into cuopt_client. The gRPC client takes a solver_settings_t
+# in its public API, so this is required for the client library to resolve standalone.
+set(MATH_OPT_CLIENT_SRC_FILES
+  ${CMAKE_CURRENT_SOURCE_DIR}/solver_settings.cpp
+  )
+
 set(CUOPT_SRC_FILES ${CUOPT_SRC_FILES}
   ${MATH_OPT_SRC_FILES} PARENT_SCOPE)
+set(CUOPT_CLIENT_SRC_FILES ${CUOPT_CLIENT_SRC_FILES}
+  ${MATH_OPT_CLIENT_SRC_FILES} PARENT_SCOPE)

cpp/src/mip_heuristics/CMakeLists.txt

@@ -9,7 +9,6 @@ set(MIP_LP_NECESSARY_FILES
   ${CMAKE_CURRENT_SOURCE_DIR}/problem/problem.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/problem/presolve_data.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/solver_settings.cu
-  ${CMAKE_CURRENT_SOURCE_DIR}/solver_settings.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/solver_solution.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/local_search/rounding/simple_rounding.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/presolve/third_party_presolve.cpp
@@ -55,5 +54,13 @@ else()
   set(MIP_SRC_FILES ${MIP_LP_NECESSARY_FILES} ${MIP_NON_LP_FILES})
 endif()
 
+# Host-only members of mip_solver_settings_t (callbacks, tolerances). The gRPC client
+# needs them, so they build into cuopt_client; add_initial_solution stays in the .cu.
+set(MIP_CLIENT_SRC_FILES
+  ${CMAKE_CURRENT_SOURCE_DIR}/solver_settings.cpp
+)
+
 set(CUOPT_SRC_FILES ${CUOPT_SRC_FILES}
   ${MIP_SRC_FILES} PARENT_SCOPE)
+set(CUOPT_CLIENT_SRC_FILES ${CUOPT_CLIENT_SRC_FILES}
+  ${MIP_CLIENT_SRC_FILES} PARENT_SCOPE)

cpp/src/pdlp/CMakeLists.txt

@@ -6,9 +6,7 @@
 # Core LP files always included
 set(LP_CORE_FILES
   ${CMAKE_CURRENT_SOURCE_DIR}/solver_settings.cu
-  ${CMAKE_CURRENT_SOURCE_DIR}/solver_settings_accessors.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/optimization_problem.cu
-  ${CMAKE_CURRENT_SOURCE_DIR}/cpu_optimization_problem.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/cpu_optimization_problem_to_gpu.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/backend_selection.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/utilities/problem_checking.cu
@@ -17,7 +15,6 @@ set(LP_CORE_FILES
   ${CMAKE_CURRENT_SOURCE_DIR}/pdhg.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/solver_solution.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/solution_conversion.cu
-  ${CMAKE_CURRENT_SOURCE_DIR}/solution_conversion_cpu.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/saddle_point.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/cusparse_view.cu
   ${CMAKE_CURRENT_SOURCE_DIR}/pdlp_warm_start_data.cu
@@ -52,4 +49,14 @@ else()
   set(LP_SRC_FILES ${LP_CORE_FILES} ${LP_ADAPTER_FILES})
 endif()
 
+# Host-only LP sources that the gRPC client needs. These build into cuopt_client so the
+# client library resolves standalone, without libcuopt.so. Their GPU-facing members were
+# split into separate CUDA translation units above (e.g. cpu_optimization_problem_to_gpu.cpp).
+set(LP_CLIENT_FILES
+  ${CMAKE_CURRENT_SOURCE_DIR}/cpu_optimization_problem.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/solution_conversion_cpu.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/solver_settings_accessors.cpp
+)
+
 set(CUOPT_SRC_FILES ${CUOPT_SRC_FILES} ${LP_SRC_FILES} PARENT_SCOPE)
+set(CUOPT_CLIENT_SRC_FILES ${CUOPT_CLIENT_SRC_FILES} ${LP_CLIENT_FILES} PARENT_SCOPE)