resolve-core 0.8.1__tar.gz

resolve_core-0.8.1/CMakeLists.txt

@@ -0,0 +1,192 @@
+cmake_minimum_required(VERSION 3.18)
+
+# Check if we're being included as a subdirectory or built standalone
+if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
+    # Standalone build - define project and build resolve_core.
+    # No VERSION here: the wheel's version comes from pyproject.toml, the
+    # engine's from resolve::VERSION, and both are kept in sync with the
+    # repo-root VERSION file by tools/version.py. Nothing consumes
+    # PROJECT_VERSION, and this directory is also the sdist root, which does
+    # not carry the repo-root file.
+    project(resolve_python LANGUAGES CXX)
+
+    # CPU by default: the PyPI wheels link the CPU libtorch the user's `torch`
+    # ships and do not bundle CUDA. Pass -DUSE_CUDA=ON for a local CUDA build.
+    option(USE_CUDA "Enable CUDA support" OFF)
+
+    # libtorch 2.13+ requires C++20 (bit-field default initializers in
+    # c10/core/AutogradState.h). Match the parent src/core/CMakeLists.txt.
+    set(CMAKE_CXX_STANDARD 20)
+    set(CMAKE_CXX_STANDARD_REQUIRED ON)
+    set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+    # Skip Caffe2's CUDA detection entirely when building CPU-only
+    if(NOT USE_CUDA)
+        set(CAFFE2_USE_CUDA OFF CACHE BOOL "" FORCE)
+        set(USE_CUDA OFF CACHE BOOL "" FORCE)
+        set(CAFFE2_USE_CUDNN OFF CACHE BOOL "" FORCE)
+        set(USE_CUDNN OFF CACHE BOOL "" FORCE)
+        # This is the key: tell Torch not to look for CUDA
+        set(TORCH_CUDA_ARCH_LIST "" CACHE STRING "" FORCE)
+        set(CMAKE_CUDA_COMPILER "" CACHE FILEPATH "" FORCE)
+    else()
+        # Local CUDA wheel build: link PyTorch's prebuilt CUDA libs (we do not
+        # compile CUDA ourselves except the custom kernels below). cuDNN off to
+        # match the engine build.
+        set(CAFFE2_USE_CUDA ON)
+        set(CAFFE2_USE_CUDNN OFF)
+        set(USE_CUDNN OFF)
+    endif()
+
+    # Locate libtorch via the installed `torch` package's CMake prefix when no
+    # explicit Torch_DIR / CMAKE_PREFIX_PATH was given. This is how the PyPI
+    # wheel and sdist builds find libtorch: `torch` is a build dependency
+    # (pyproject.toml), so it is present in the build environment, and the
+    # extension links the same libtorch the user's torch ships -- no separate
+    # libtorch is downloaded or bundled.
+    if(NOT Torch_DIR AND NOT CMAKE_PREFIX_PATH)
+        find_package(Python COMPONENTS Interpreter REQUIRED)
+        execute_process(
+            COMMAND "${Python_EXECUTABLE}" -c "import torch.utils; print(torch.utils.cmake_prefix_path)"
+            OUTPUT_VARIABLE TORCH_CMAKE_PREFIX
+            OUTPUT_STRIP_TRAILING_WHITESPACE
+            RESULT_VARIABLE TORCH_PROBE_RC
+        )
+        if(TORCH_PROBE_RC EQUAL 0 AND TORCH_CMAKE_PREFIX)
+            list(APPEND CMAKE_PREFIX_PATH "${TORCH_CMAKE_PREFIX}")
+            message(STATUS "Using libtorch from the torch package: ${TORCH_CMAKE_PREFIX}")
+        endif()
+    endif()
+
+    # Find libtorch (will skip CUDA if the CPU-only vars above are set)
+    find_package(Torch REQUIRED)
+
+    # Core library sources: single source of truth shared with the main engine
+    # build via resolve_core_sources.cmake (no drift -- this is why the wheel
+    # previously failed to link set_vram_fraction / install_crash_handler).
+    set(RESOLVE_CORE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/..)
+    include(${RESOLVE_CORE_DIR}/resolve_warnings.cmake)
+    include(${RESOLVE_CORE_DIR}/resolve_core_sources.cmake)
+
+    add_library(resolve_core STATIC ${RESOLVE_CORE_SOURCES})
+    target_include_directories(resolve_core PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../include>
+    )
+    target_link_libraries(resolve_core PUBLIC ${TORCH_LIBRARIES})
+    target_link_libraries(resolve_core PRIVATE resolve_warnings)
+
+    # Custom CUDA kernels + RESOLVE_HAS_CUDA, shared with the engine build. Under
+    # -DUSE_CUDA=ON this defines RESOLVE_HAS_CUDA so set_vram_fraction and the
+    # hash kernels are actually compiled in; a no-op on the default CPU wheel.
+    include(${RESOLVE_CORE_DIR}/resolve_cuda_kernels.cmake)
+
+    # OpenMP for fuzzy::query_batch (optional).
+    find_package(OpenMP QUIET)
+    if(OpenMP_CXX_FOUND)
+        target_link_libraries(resolve_core PUBLIC OpenMP::OpenMP_CXX)
+        message(STATUS "OpenMP enabled for resolve_core (standalone Python build)")
+    else()
+        message(STATUS "OpenMP not found; fuzzy::query_batch will run serially")
+    endif()
+
+    set_property(TARGET resolve_core PROPERTY CXX_STANDARD 20)
+endif()
+
+# Warning flags for RESOLVE's own targets. Already included by the branch above
+# when this directory configures standalone (the sdist root) and by
+# src/core/CMakeLists.txt when it is a subdirectory; the file guards itself.
+include(${CMAKE_CURRENT_SOURCE_DIR}/../resolve_warnings.cmake)
+
+# Python bindings using nanobind
+find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
+
+# Fetch nanobind
+include(FetchContent)
+FetchContent_Declare(
+    nanobind
+    GIT_REPOSITORY https://github.com/wjakob/nanobind.git
+    GIT_TAG v2.4.0
+)
+FetchContent_MakeAvailable(nanobind)
+
+# Build the extension module
+set(BINDING_SOURCES
+    src/bindings.cpp
+    src/bindings_enums.cpp
+    src/bindings_types.cpp
+    src/bindings_dataset.cpp
+    src/bindings_model.cpp
+    src/bindings_trainer.cpp
+    src/bindings_metrics.cpp
+    src/bindings_pretraining.cpp
+    src/bindings_fuzzy.cpp
+)
+nanobind_add_module(_resolve_core ${BINDING_SOURCES})
+
+# Find torch_python library for Python tensor interop (THPVariable_Wrap, etc.)
+get_filename_component(TORCH_LIB_DIR "${TORCH_INSTALL_PREFIX}/lib" ABSOLUTE)
+find_library(TORCH_PYTHON_LIB torch_python PATHS "${TORCH_LIB_DIR}" NO_DEFAULT_PATH)
+if(TORCH_PYTHON_LIB)
+    message(STATUS "Found torch_python: ${TORCH_PYTHON_LIB}")
+    target_link_libraries(_resolve_core PRIVATE resolve_core ${TORCH_LIBRARIES} ${TORCH_PYTHON_LIB})
+else()
+    message(WARNING "torch_python library not found, some features may not work")
+    target_link_libraries(_resolve_core PRIVATE resolve_core ${TORCH_LIBRARIES})
+endif()
+
+target_link_libraries(_resolve_core PRIVATE resolve_warnings)
+
+# nanobind reaches the binding sources through a FetchContent target, which is
+# not IMPORTED, so CMake does not mark its headers SYSTEM the way it does
+# libtorch's. Promote them, otherwise /W4 and -Wall report nanobind's internals
+# instead of our bindings. Which target carries them depends on the
+# nanobind_add_module mode (static / shared / abi3 variants), so read it off
+# the link line rather than hardcoding a name.
+get_target_property(RESOLVE_NB_LINKED _resolve_core LINK_LIBRARIES)
+foreach(RESOLVE_NB_LIB IN LISTS RESOLVE_NB_LINKED)
+    if(RESOLVE_NB_LIB MATCHES "^nanobind" AND TARGET ${RESOLVE_NB_LIB})
+        get_target_property(RESOLVE_NB_INCS ${RESOLVE_NB_LIB} INTERFACE_INCLUDE_DIRECTORIES)
+        if(RESOLVE_NB_INCS)
+            set_property(TARGET ${RESOLVE_NB_LIB} APPEND PROPERTY
+                INTERFACE_SYSTEM_INCLUDE_DIRECTORIES ${RESOLVE_NB_INCS})
+        endif()
+    endif()
+endforeach()
+
+target_include_directories(_resolve_core PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/../include
+)
+
+# Set output directory for the built module
+set_target_properties(_resolve_core PROPERTIES
+    LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/src/resolve_core
+)
+
+# Runtime libtorch resolution. The wheel deliberately does NOT bundle libtorch
+# -- it links the same libs the user's `torch` ships (a separate copy would be
+# huge and risk an ABI clash). resolve_core/__init__.py imports torch before
+# loading this extension, so torch's libs are already in the process; the RPATH
+# below is a belt-and-braces pointer to the installed torch lib dir
+# (site-packages/torch/lib, one level up from resolve_core/). On Windows, torch
+# adds its lib dir to the DLL search at import, so no RPATH/copy is needed.
+if(UNIX AND NOT APPLE)
+    set_target_properties(_resolve_core PROPERTIES
+        INSTALL_RPATH "$ORIGIN/../torch/lib"
+        BUILD_WITH_INSTALL_RPATH TRUE)
+elseif(APPLE)
+    set_target_properties(_resolve_core PROPERTIES
+        INSTALL_RPATH "@loader_path/../torch/lib"
+        BUILD_WITH_INSTALL_RPATH TRUE)
+    # Linking against libtorch_python pulls libtorch's bundled pybind11 into the
+    # module (via torch/csrc/autograd/python_variable.h in bindings_model.cpp),
+    # which references Python C-API symbols (PyInstanceMethod_*, _PyThreadState_
+    # UncheckedGet) not in nanobind's restricted macOS symbol list. A Python
+    # extension on macOS does not link libpython; those symbols resolve at load
+    # time from the host interpreter, so allow undefined-symbol dynamic lookup
+    # (the canonical macOS Python-extension link flag). Without it the arm64 link
+    # fails with "Undefined symbols for architecture arm64".
+    target_link_options(_resolve_core PRIVATE -Wl,-undefined,dynamic_lookup)
+endif()
+
+# Install target for scikit-build-core
+install(TARGETS _resolve_core LIBRARY DESTINATION resolve_core)

resolve_core-0.8.1/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.2
+Name: resolve-core
+Version: 0.8.1
+Summary: RESOLVE C++ engine: predict sample outcomes from compositional data via learned representations
+Author-Email: Gilles Colling <gilles.colling051@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering
+Project-URL: Homepage, https://github.com/gcol33/resolve
+Project-URL: Repository, https://github.com/gcol33/resolve
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Description-Content-Type: text/markdown
+
+# resolve-core
+
+C++ bindings for the RESOLVE compositional-data prediction engine.
+
+## Installation
+
+```bash
+pip install resolve-core
+```
+
+## Requirements
+
+- Python >= 3.9
+- PyTorch/libtorch
+- CMake >= 3.18
+
+## Usage
+
+```python
+from resolve_core import Trainer, TrainConfig, ModelConfig
+
+# See full package documentation for API details
+```

resolve_core-0.8.1/README.md

@@ -0,0 +1,23 @@
+# resolve-core
+
+C++ bindings for the RESOLVE compositional-data prediction engine.
+
+## Installation
+
+```bash
+pip install resolve-core
+```
+
+## Requirements
+
+- Python >= 3.9
+- PyTorch/libtorch
+- CMake >= 3.18
+
+## Usage
+
+```python
+from resolve_core import Trainer, TrainConfig, ModelConfig
+
+# See full package documentation for API details
+```

resolve_core-0.8.1/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+# torch is a build requirement: the extension links libtorch, located via the
+# installed torch package's CMake prefix (src/core/python/CMakeLists.txt).
+requires = ["scikit-build-core>=0.4.3", "nanobind>=2.0.0", "torch>=2.0"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "resolve-core"
+version = "0.8.1"
+description = "RESOLVE C++ engine: predict sample outcomes from compositional data via learned representations"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Gilles Colling", email = "gilles.colling051@gmail.com"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: C++",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "numpy>=1.20.0",
+    "pandas>=1.3.0",
+    # The extension links libtorch and imports torch before loading; the wheels
+    # do not bundle libtorch, so torch must be installed at runtime.
+    "torch>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/gcol33/resolve"
+Repository = "https://github.com/gcol33/resolve"
+
+[tool.scikit-build]
+# cmake.version, not cmake.minimum-version: scikit-build-core >= 0.8 rejects the
+# old key outright, which fails metadata generation before any build starts.
+cmake.version = ">=3.18"
+cmake.build-type = "Release"
+wheel.packages = ["src/resolve_core"]
+
+[tool.scikit-build.cmake.define]
+BUILD_PYTHON = "ON"
+BUILD_TESTS = "OFF"

resolve_core-0.8.1/src/bindings.cpp

@@ -0,0 +1,118 @@
+// Main binding entry point - delegates to split modules for maintainability
+//
+// The actual binding code is split into:
+// - bindings_enums.cpp: All enum bindings
+// - bindings_types.cpp: Configuration structs and result types
+// - bindings_dataset.cpp: ResolveDataset and species encoding
+// - bindings_model.cpp: ResolveModel
+// - bindings_trainer.cpp: Trainer and Predictor
+// - bindings_metrics.cpp: Metrics classes
+
+#include "bindings_common.hpp"
+
+#include <string>
+
+NB_MODULE(_resolve_core, m) {
+    m.doc() = "RESOLVE C++ core library for species-composition based prediction";
+
+    // libtorch holds global state (type registrations, dispatch keys) via shared_ptr
+    // that outlives nanobind's module cleanup at interpreter shutdown. This causes
+    // false-positive "leaked N types / N functions" warnings. Instance leaks are
+    // fixed by returning config objects by value (not reference) in property bindings.
+    nb::set_leak_warnings(false);
+
+    // Register all bindings from split modules
+    register_enums(m);
+    register_types(m);
+    register_dataset(m);
+    register_model(m);
+    register_trainer(m);
+    register_metrics(m);
+    register_pretraining(m);
+    register_fuzzy(m);
+
+    // Platform-aware PYTORCH_CUDA_ALLOC_CONF setter. The primary surface is
+    // resolve_core.configure_cuda_allocator() in the Python __init__ which
+    // runs at module import (pre-torch). This C++ entry point is the
+    // late-bound fallback for users who imported torch first; in that case
+    // the allocator has already initialized and changing the env var no
+    // longer affects allocator behavior. Returns the resulting config
+    // string for logging.
+    m.def(
+        "_configure_cuda_allocator_native",
+        &resolve::configure_cuda_allocator,
+        nb::arg("force") = false,
+        "Set PYTORCH_CUDA_ALLOC_CONF if unset (or force-set). Linux/macOS\n"
+        "prepend expandable_segments:True; Windows omits it. Returns the\n"
+        "active value. Use resolve_core.configure_cuda_allocator() instead;\n"
+        "this native shim is late-bound and cannot rescue allocators that\n"
+        "have already initialized."
+    );
+
+    // Top-level helper: cap the PyTorch CUDA caching allocator at a fraction
+    // of device VRAM. Standalone counterpart to TrainConfig.vram_fraction for
+    // users running Predictor-only workflows or wanting to apply the cap
+    // before constructing any RESOLVE object.
+    m.def(
+        "set_vram_fraction",
+        [](double fraction, int device_index) {
+            resolve::set_vram_fraction(fraction, device_index);
+        },
+        nb::arg("fraction"),
+        nb::arg("device_index") = -1,
+        "Cap the PyTorch CUDA caching allocator at `fraction` of device VRAM.\n"
+        "fraction must be in (0, 1]; 1.0 disables the cap. device_index = -1\n"
+        "uses the current CUDA device. No-op on CPU-only builds or when no\n"
+        "CUDA device is present."
+    );
+
+    // Pin libtorch's host thread pools. Standalone counterpart used at startup
+    // to avoid worker-thread teardown races on Windows (issue #18); harmless
+    // elsewhere. <=0 keeps libtorch's default for the corresponding pool.
+    m.def(
+        "set_thread_pools",
+        [](int intraop_threads, int interop_threads) {
+            resolve::set_thread_pools(intraop_threads, interop_threads);
+        },
+        nb::arg("intraop_threads"),
+        nb::arg("interop_threads") = -1,
+        "Pin libtorch's intra-op / inter-op thread pools (<=0 keeps the\n"
+        "default). Best-effort; call at startup before the first op."
+    );
+
+    // Windows crash hardening (issue #19): convert an unhandled native fault in
+    // a headless training worker into an immediate TerminateProcess with the
+    // fault's NTSTATUS, instead of an indefinite Windows-Error-Reporting /
+    // JIT-debugger (vsjitdebugger) hang that holds the GPU and stalls the
+    // batch. No-op off Windows. Auto-installed at import below; also exposed so
+    // callers can re-arm or adjust the shutdown exit code explicitly.
+    m.def(
+        "install_crash_handler",
+        [](int shutdown_exit_code) {
+            resolve::install_crash_handler(shutdown_exit_code);
+        },
+        nb::arg("shutdown_exit_code") = 0,
+        "Install the Windows unhandled-exception filter that fails fast via\n"
+        "TerminateProcess instead of hanging on the JIT debugger. No-op off\n"
+        "Windows. Idempotent."
+    );
+
+    // Internal: flip the crash handler to treat a subsequent native fault as a
+    // benign teardown artifact (exit with the shutdown code, not a failure
+    // code). Registered with atexit() in resolve_core/__init__.py so a clean
+    // interpreter shutdown after a successful run is not misreported as a crash.
+    m.def(
+        "_signal_work_complete",
+        []() { resolve::signal_work_complete(); },
+        "Mark all engine work complete (atexit hook; see __init__.py)."
+    );
+
+    // Arm the crash handler as soon as resolve_core is imported, so a training
+    // worker is hardened before Trainer::fit() ever runs (issue #19). Default
+    // shutdown code 0: a clean interpreter shutdown (after _signal_work_complete
+    // via atexit) exits 0; a mid-run native fault exits with its NTSTATUS.
+    resolve::install_crash_handler(0);
+
+    // Version
+    m.attr("__version__") = resolve::VERSION;
+}

resolve_core-0.8.1/src/bindings_common.hpp

@@ -0,0 +1,79 @@
+#pragma once
+
+#include <nanobind/nanobind.h>
+#include <nanobind/stl/string.h>
+#include <nanobind/stl/vector.h>
+#include <nanobind/stl/pair.h>
+#include <nanobind/stl/unordered_map.h>
+#include <nanobind/stl/optional.h>
+#include <torch/torch.h>
+#include <torch/csrc/autograd/python_variable.h>  // For THPVariable_Wrap/Unpack
+
+#include "resolve/resolve.hpp"
+#include "resolve/role_mapping.hpp"
+#include "resolve/dataset.hpp"
+
+namespace nb = nanobind;
+
+// Unpack an optional tensor argument. Returns an undefined tensor for None;
+// THPVariable_Unpack on Py_None reinterprets the None singleton as a
+// THPVariable and reads out of bounds (UB), so callers passing None for an
+// unused input (e.g. genus_ids in hash mode) must be guarded here.
+inline at::Tensor unpack_optional_tensor(const nb::object& obj) {
+    if (!obj.is_valid() || obj.is_none()) return at::Tensor();
+    return THPVariable_Unpack(obj.ptr());
+}
+
+// Unpack a required tensor argument. Raises a clear Python-visible error for
+// None or a non-tensor instead of the UB THPVariable_Unpack would hit.
+inline at::Tensor unpack_required_tensor(const nb::object& obj, const char* name) {
+    PyObject* p = obj.ptr();
+    if (obj.is_none() || !THPVariable_Check(p)) {
+        throw std::invalid_argument(std::string(name) + " must be a tensor");
+    }
+    return THPVariable_Unpack(p);
+}
+
+// Helper to convert Python dict to unordered_map of tensors
+inline std::unordered_map<std::string, torch::Tensor> dict_to_tensor_map(const nb::dict& d) {
+    std::unordered_map<std::string, torch::Tensor> result;
+    for (auto item : d) {
+        // Use THPVariable_Unpack to convert Python tensor to C++ tensor.
+        // Reject a non-tensor value loudly instead of silently dropping it,
+        // which would make a mistyped targets/inputs entry vanish.
+        PyObject* py_tensor = item.second.ptr();
+        auto key = nb::cast<std::string>(item.first);
+        if (!THPVariable_Check(py_tensor)) {
+            throw std::runtime_error(
+                "dict_to_tensor_map: value for key '" + key +
+                "' is not a torch.Tensor");
+        }
+        result[key] = THPVariable_Unpack(py_tensor);
+    }
+    return result;
+}
+
+// Helper to convert unordered_map of tensors to Python dict
+inline nb::object tensor_map_to_dict(const std::unordered_map<std::string, torch::Tensor>& m) {
+    PyObject* py_dict = PyDict_New();
+    for (const auto& [key, value] : m) {
+        if (value.defined()) {
+            // Move tensor to CPU and make contiguous for Python interop
+            auto cpu_tensor = value.detach().cpu().contiguous();
+            PyObject* py_tensor = THPVariable_Wrap(cpu_tensor);
+            PyDict_SetItemString(py_dict, key.c_str(), py_tensor);
+            Py_DECREF(py_tensor);  // PyDict_SetItemString increments refcount
+        }
+    }
+    return nb::steal(py_dict);
+}
+
+// Forward declarations for binding registration functions
+void register_enums(nb::module_& m);
+void register_types(nb::module_& m);
+void register_dataset(nb::module_& m);
+void register_model(nb::module_& m);
+void register_trainer(nb::module_& m);
+void register_metrics(nb::module_& m);
+void register_pretraining(nb::module_& m);
+void register_fuzzy(nb::module_& m);