synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Mapper/solvers/native/core.py

@@ -0,0 +1,378 @@
+"""Prepared-graph conversion and result records for the shared native core."""
+
+import ctypes as ct
+import json
+import math
+import time
+from collections import Counter
+from numbers import Integral, Real
+from pathlib import Path
+
+import numpy as np
+
+from ..exact.distance_search.records import (
+    DistanceEnumerationResult,
+    ExactEnumerationLimitError,
+    normalize_distance_target,
+)
+from ..slap.lap import _adjacency_and_elements
+from .runtime import (
+    BACKENDS,
+    CALLBACK,
+    INT,
+    LONG,
+    REASONS,
+    Problem,
+    Request,
+    Statistics,
+    load_core,
+    resolve_library_path,
+)
+
+
+def _ids(values, registry):
+    return np.asarray([registry.setdefault(value, len(registry)) for value in values], dtype=np.int32)
+
+
+# Validation, native buffers and callbacks belong to the same solve lifetime.
+def enumerate_core_mappings(  # noqa: C901
+    lgp,
+    *,
+    library_path=None,
+    backend="pabs",
+    CD="minimal",
+    CD_mode="exact",
+    binary=False,
+    symmetry=False,
+    node_properties=(),
+    time_limit_seconds=None,
+    max_states=None,
+    max_mappings=None,
+    max_classes=None,
+    max_frontier=None,
+    memory_limit_bytes=None,
+    collect_mappings=True,
+    mapping_callback=None,
+    compute_minimum_cost=None,
+    max_bijections=None,
+    tolerance=1e-9,
+    proof_only=False,
+    cancel_token=None,
+    initial_mapping=None,
+    allowed_domains=None,
+    _native_classifier=None,
+    _native_class_registry=None,
+):
+    started = time.perf_counter()
+    library_path = resolve_library_path(library_path)
+    target = normalize_distance_target(CD)
+    if backend not in BACKENDS:
+        raise ValueError(f"Unknown native backend: {backend}")
+    if allowed_domains is not None and backend not in {"kbb", "kmilp"}:
+        raise ValueError("allowed_domains requires a kernel backend: kbb or kmilp")
+    if CD_mode not in {"exact", "at_most"} or (CD_mode == "at_most" and target == "minimal"):
+        raise ValueError("at_most requires numeric CD; otherwise use exact")
+    for name, value in (
+        ("binary", binary),
+        ("symmetry", symmetry),
+        ("collect_mappings", collect_mappings),
+        ("proof_only", proof_only),
+    ):
+        if not isinstance(value, bool):
+            raise TypeError(f"{name} must be boolean")
+    if proof_only and target != "minimal":
+        raise ValueError("proof_only requires minimal CD")
+    if initial_mapping is not None:
+        raise ValueError("Shared-core explicit warm starts are not qualified yet")
+    if compute_minimum_cost and target != "minimal":
+        raise ValueError("Numeric core queries do not run a separate minimum proof")
+    if mapping_callback is not None and not callable(mapping_callback):
+        raise TypeError("mapping_callback must be callable")
+    for name, value in (
+        ("max_states", max_states),
+        ("max_mappings", max_mappings),
+        ("max_classes", max_classes),
+        ("max_frontier", max_frontier),
+        ("memory_limit_bytes", memory_limit_bytes),
+        ("max_bijections", max_bijections),
+    ):
+        if value is not None and (isinstance(value, bool) or not isinstance(value, Integral) or not 1 <= value < 2**63):
+            raise ValueError(f"{name} must be a positive integer or None")
+    if time_limit_seconds is not None and (
+        isinstance(time_limit_seconds, bool)
+        or not isinstance(time_limit_seconds, Real)
+        or not math.isfinite(time_limit_seconds)
+        or time_limit_seconds < 0
+    ):
+        raise ValueError("time_limit_seconds must be finite and nonnegative")
+    if (
+        isinstance(tolerance, bool)
+        or not isinstance(tolerance, Real)
+        or not math.isfinite(tolerance)
+        or not 0 <= tolerance < 0.25
+    ):
+        raise ValueError("tolerance must be finite and in [0,0.25)")
+    if len(lgp) != 2:
+        raise ValueError("Expected two endpoint graphs")
+    matrices, elements = zip(*[_adjacency_and_elements(graph, binary) for graph in lgp])
+    n = len(elements[0])
+    if not 1 <= n <= 1024 or any(matrix.shape != (n, n) for matrix in matrices):
+        raise ValueError("Core requires compatible 1..1024 vertex graphs")
+    if Counter(elements[0]) != Counter(elements[1]):
+        raise ValueError("Unequal atom-type inventories")
+    encoded = []
+    for graph, matrix in zip(lgp, matrices):
+        if (
+            any(graph.graph[i].get(i, 0) for i in range(n))
+            or not np.isfinite(matrix).all()
+            or np.any(matrix < 0)
+            or np.any(matrix > 500000)
+            or not np.array_equal(matrix, matrix.T)
+            or not np.allclose(matrix * 2, np.rint(matrix * 2), atol=tolerance, rtol=0)
+        ):
+            raise ValueError("Core requires symmetric loop-free nonnegative half-integer weights")
+        encoded.append(np.ascontiguousarray(np.rint(matrix * 2), dtype=np.int64))
+    total = math.prod(math.factorial(count) for count in Counter(elements[0]).values())
+    if max_bijections is not None and total > max_bijections:
+        raise ExactEnumerationLimitError("Bijections exceed max_bijections")
+    registry = {}
+    types = [_ids(side, registry) for side in elements]
+    colors = {}
+    nodes = []
+    for graph, side in zip(lgp, elements):
+        if set(node_properties) - graph.props.keys():
+            raise ValueError("Missing symmetry node properties")
+        nodes.append(
+            _ids(
+                [(element, *(graph.props[name][i] for name in node_properties)) for i, element in enumerate(side)],
+                colors,
+            )
+        )
+    edges = [np.zeros((n, n), dtype=np.int32) for _ in lgp]
+    # Extra native edge class tokens may be supplied by a frontend; absent
+    # matrices mean no extra edge attributes beyond the weighted objective.
+    for i, graph in enumerate(lgp):
+        if "_native_edge_colors" in graph.props:
+            values = np.asarray(graph.props["_native_edge_colors"])
+            if values.shape != (n, n) or not np.array_equal(values, values.T):
+                raise ValueError("Invalid native edge class attributes")
+            edges[i] = np.ascontiguousarray(values, dtype=np.int32)
+    maximum = float((matrices[0].sum() + matrices[1].sum()) / 2)
+    query = 3 if proof_only else 0 if target == "minimal" else 2 if CD_mode == "at_most" else 1
+    impossible = False
+    if target == "minimal":
+        target2 = 0
+    elif query == 2:
+        target2 = math.floor((min(target, maximum) + tolerance) * 2)
+    elif target > maximum + tolerance:
+        target2 = 0
+        impossible = True
+    else:
+        target2 = round(target * 2)
+        impossible = abs(target - target2 / 2) > tolerance
+    problem = Problem(
+        1,
+        n,
+        *[array.ctypes.data_as(LONG) for array in encoded],
+        *[array.ctypes.data_as(INT) for array in [*types, *nodes, *edges]],
+    )
+    domain_mask = None
+    if allowed_domains is not None:
+        values = np.asarray(allowed_domains)
+        if values.shape != (n, n) or not np.isin(values, [0, 1]).all():
+            raise ValueError("allowed_domains must be an n-by-n zero/one mask")
+        domain_mask = np.ascontiguousarray(values, dtype=np.uint8)
+    request = Request()
+    request.abi_version = 1
+    request.backend = BACKENDS[backend]
+    request.query = query
+    request.symmetry = int(symmetry)
+    request.workers = 1
+    request.target2 = target2
+    request.seconds = -1 if time_limit_seconds is None else max(0, time_limit_seconds - (time.perf_counter() - started))
+    for name, value in (
+        ("max_states", max_states),
+        ("max_candidates", max_mappings),
+        ("max_classes", max_classes),
+        ("max_frontier", max_frontier),
+        ("memory_limit_bytes", memory_limit_bytes),
+    ):
+        setattr(request, name, -1 if value is None else int(value))
+    request.slap_max_fingerprints = 10000
+    stop_flags = np.asarray([int(value == 1) for value in lgp[0].labels], dtype=np.int32)
+    request.slap_stop_flags = stop_flags.ctypes.data_as(INT)
+    request.cancel_token = None if cancel_token is None else cancel_token.pointer
+    mappings = []
+    distances = []
+    observed = set()
+    errors = []
+    classification = None
+
+    def receive(pointer, cost2, _userdata):
+        try:
+            mapping = list(pointer[:n])
+            cost = cost2 / 2
+            if sorted(mapping) != list(range(n)) or any(
+                elements[0][i] != elements[1][j] for i, j in enumerate(mapping)
+            ):
+                raise RuntimeError("Native core returned incompatible bijection")
+            observed.add(cost)
+            if collect_mappings:
+                mappings.append(mapping)
+                distances.append(cost)
+            if mapping_callback is not None:
+                mapping_callback(mapping, cost)
+            return 0
+        except BaseException as error:  # noqa: BLE001
+            errors.append(error)
+            return 1
+
+    callback = CALLBACK(receive)
+    stats = Statistics()
+    library = load_core(str(Path(library_path).resolve()))
+    request.seconds = -1 if time_limit_seconds is None else max(0, time_limit_seconds - (time.perf_counter() - started))
+    if impossible:
+        stats.search_complete = stats.classification_complete = stats.hydrogen_complete = 1
+        stats.minimum2 = stats.incumbent2 = stats.lower_bound2 = -1
+        stats.labeled_count = 0
+    elif _native_classifier is not None:
+        if _native_class_registry is None:
+            raise ValueError("Native class registry is required")
+
+        def receive_class(record):
+            _native_class_registry[record.representative] = record
+            array = (ct.c_int32 * n)(*record.representative)
+            return receive(array, record.cost2, None)
+
+        classification, stats = _native_classifier.solve_prepared(
+            problem,
+            request,
+            class_callback=receive_class,
+            max_canonical_nodes=getattr(_native_classifier, "frontend_max_canonical_nodes", None),
+            allowed_domains=domain_mask,
+            stream=True,
+        )
+        if errors:
+            raise errors[0]
+    else:
+        if domain_mask is not None:
+            if not hasattr(library, "synkit_mapper_solve_domains"):
+                raise RuntimeError("Library lacks the native kernel domain API")
+            result = library.synkit_mapper_solve_domains(
+                ct.byref(problem),
+                ct.byref(request),
+                domain_mask.ctypes.data_as(ct.POINTER(ct.c_uint8)),
+                callback,
+                None,
+                ct.byref(stats),
+            )
+        else:
+            result = library.synkit_mapper_solve(ct.byref(problem), ct.byref(request), callback, None, ct.byref(stats))
+        if errors:
+            raise errors[0]
+        if result:
+            raise RuntimeError(library.synkit_mapper_core_error().decode())
+    detail = {name: getattr(stats, name) for name, _ in stats._fields_}
+    detail.update(
+        core_abi=1,
+        backend=backend,
+        library_path=str(Path(library_path).resolve()),
+        CD_mode=CD_mode,
+        proof_only=proof_only,
+        cost_scale=2,
+        requested_symmetry=symmetry,
+        domain_restricted=domain_mask is not None,
+        enumeration_search_seconds=max(0, stats.enumeration_seconds - stats.callback_seconds),
+    )
+    metadata_function = getattr(library, "synkit_mapper_backend_metadata", None)
+    backend_executed = (
+        not impossible
+        and stats.status != 2
+        and not (stats.reason == 10 and stats.nodes == 0 and stats.model_seconds == 0 and stats.candidate_count == 0)
+    )
+    detail["backend_executed"] = backend_executed
+    if metadata_function and backend_executed:
+        detail["native_metadata"] = json.loads(metadata_function(BACKENDS[backend]).decode())
+    version_function = getattr(library, "synkit_mapper_backend_version", None)
+    detail.update(
+        solver_version=version_function(BACKENDS[backend]).decode() if version_function else None,
+        threads=1,
+        classification_reason=None if classification is None else classification.reason,
+        classification_delivery=(None if classification is None else _native_classifier.delivery_mode),
+        delivered_class_count=(None if classification is None else len(classification.classes)),
+    )
+    if backend == "scip":
+        detail.update(
+            numerical_qualification=(
+                "solver OPTIMAL under floating feasibility tolerances; " "no checked formal certificate"
+            ),
+            relative_gap=0,
+            absolute_gap=0,
+            feasibility_tolerance=1e-9,
+        )
+    if backend in {"cp_sat", "scip", "maxsat"}:
+        detail["implementation"] = "cpp_sparse_full_assignment_linearization"
+    complete = bool(stats.search_complete) and not proof_only and backend != "slap"
+    reason = REASONS.get(stats.reason, "unknown_stop")
+    return DistanceEnumerationResult(
+        target=target,
+        cost=next(iter(observed)) if len(observed) == 1 else None,
+        minimum_cost=stats.minimum2 / 2 if stats.minimum_proven else None,
+        mappings=mappings,
+        distances=distances,
+        total_bijections=total,
+        maximum_cost_upper_bound=maximum,
+        visited_leaves=stats.leaves,
+        pruned_branches=0,
+        visited_nodes=stats.nodes,
+        elapsed_seconds=time.perf_counter() - started,
+        status=(
+            ("complete" if stats.candidate_count else "no_solutions")
+            if complete
+            else "unsupported" if stats.status == 2 else "timeout"
+        ),
+        complete=complete,
+        truncation_reason=reason or ("proof_only" if proof_only else None),
+        selected_mapping_count=stats.candidate_count,
+        selected_labeled_mapping_count=None if stats.labeled_count < 0 else stats.labeled_count,
+        scope=(
+            "restricted_kernel_assignment_space"
+            if backend in {"kbb", "kmilp"}
+            else (
+                "heuristic_candidates"
+                if backend == "slap"
+                else (
+                    "atom_compatible_assignment_space_modulo_verified_symmetry"
+                    if symmetry or backend == "cpabs"
+                    else "complete_atom_compatible_assignment_space"
+                )
+            )
+        ),
+        symmetry_group_order=None if symmetry or backend == "cpabs" else 1,
+        symmetry_search_complete=not symmetry,
+        symmetry_quotient_complete=False,
+        backend=f"{backend}_cpp",
+        backend_statistics=detail,
+    )
+
+
+def map_reaction_core(reaction, *, library_path, backend="pabs", native_classification=None, **options):
+    from ...reaction_search import _map_reaction_with_search
+
+    domains = options.pop("allowed_domains", None)
+    if native_classification is None:
+        native_classification = True
+
+    def search(graphs, **kwargs):
+        kwargs.pop("backend")
+        kwargs["symmetry"] = backend in {"pabs", "cpabs"}
+        return enumerate_core_mappings(graphs, backend=backend, allowed_domains=domains, **kwargs)
+
+    return _map_reaction_with_search(
+        reaction,
+        search_function=search,
+        backend="cpp",
+        library_path=library_path,
+        native_classification_library=library_path if native_classification else None,
+        **options,
+    )

synkit/Chem/Mapper/solvers/native/cpp/CMakeLists.txt

@@ -0,0 +1,120 @@
+cmake_minimum_required(VERSION 3.16)
+project(synkit_mapper VERSION 1.6.5 LANGUAGES C CXX)
+
+add_library(synkit_mapper SHARED
+  src/slap.cpp src/core/dispatch.cpp src/core/pmcd_witness.cpp
+  src/pabs/bridge.cpp src/pabs/sparse_embedding.cpp src/symmetry/edge_deck.cpp
+  src/assignment/abb.cpp
+  src/supporting/dfs.cpp src/supporting/edit_support.cpp src/sepdp/sepdp.cpp
+  src/mces/mces.cpp
+  src/hydrogen/hydrogen.cpp
+  src/astar/astar.cpp src/astar/bound.cpp
+  src/symmetry/classification.cpp src/symmetry/classification_pipeline.cpp src/symmetry/cpabs.cpp)
+target_compile_definitions(synkit_mapper PRIVATE SYNKIT_MAPPER_WITH_ASTAR SYNKIT_MAPPER_WITH_CPABS SYNKIT_MAPPER_WITH_ASSIGNMENT SYNKIT_MAPPER_WITH_SUPPORTING SYNKIT_MAPPER_WITH_MCES)
+target_compile_features(synkit_mapper PUBLIC cxx_std_17)
+target_include_directories(synkit_mapper PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+  $<INSTALL_INTERFACE:include>)
+
+# Only the sparse canonical-labeling engine and its transitive dependencies
+# are vendored. Keep third-party compiler settings separate from our C++ core.
+set(SYNKIT_NAUTY_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src/symmetry/vendor/nauty)
+option(SYNKIT_MAPPER_WITH_NAUTY "Enable optional sparse edge-deck certificates" ${UNIX})
+if(SYNKIT_MAPPER_WITH_NAUTY)
+  add_library(synkit_mapper_nauty STATIC
+    ${SYNKIT_NAUTY_DIR}/nauty.c ${SYNKIT_NAUTY_DIR}/nautil.c
+    ${SYNKIT_NAUTY_DIR}/nausparse.c ${SYNKIT_NAUTY_DIR}/naugraph.c
+    ${SYNKIT_NAUTY_DIR}/schreier.c ${SYNKIT_NAUTY_DIR}/naurng.c)
+  set_target_properties(synkit_mapper_nauty PROPERTIES POSITION_INDEPENDENT_CODE ON)
+  target_include_directories(synkit_mapper PRIVATE ${SYNKIT_NAUTY_DIR})
+  target_link_libraries(synkit_mapper PRIVATE synkit_mapper_nauty)
+  target_compile_definitions(synkit_mapper PRIVATE SYNKIT_MAPPER_WITH_NAUTY)
+endif()
+
+option(SYNKIT_MAPPER_TEST_HOOKS "Build private mathematical-oracle entry points" OFF)
+if(SYNKIT_MAPPER_TEST_HOOKS)
+  target_compile_definitions(synkit_mapper PRIVATE SYNKIT_MAPPER_TEST_HOOKS)
+endif()
+if(MSVC)
+  target_compile_options(synkit_mapper PRIVATE /W4)
+else()
+  target_compile_options(synkit_mapper PRIVATE -Wall -Wextra -Wpedantic)
+endif()
+
+option(SYNKIT_MAPPER_WITH_RDKIT "Build standalone native reaction preparation/rendering" OFF)
+if(SYNKIT_MAPPER_WITH_RDKIT)
+  find_package(rdkit CONFIG REQUIRED)
+  add_library(synkit_mapper_reaction SHARED src/reaction/reaction.cpp)
+  # The optional RDKit 2026 SDK uses constexpr destructors in public headers.
+  # Keep the dependency-free mapper core on C++17.
+  target_compile_features(synkit_mapper_reaction PUBLIC cxx_std_20)
+  target_include_directories(synkit_mapper_reaction PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>)
+  target_link_libraries(synkit_mapper_reaction PRIVATE synkit_mapper
+    RDKit::GraphMol RDKit::SmilesParse RDKit::RDGeneral)
+  add_executable(mapper_reaction examples/map_reaction.cpp)
+  target_link_libraries(mapper_reaction PRIVATE synkit_mapper_reaction)
+endif()
+set_target_properties(synkit_mapper PROPERTIES
+  CXX_EXTENSIONS OFF
+  WINDOWS_EXPORT_ALL_SYMBOLS ON
+  POSITION_INDEPENDENT_CODE ON)
+
+option(SYNKIT_MAPPER_WITH_ORTOOLS "Build CP-SAT, SCIP and certified PABS PDLP bounds" OFF)
+if(SYNKIT_MAPPER_WITH_ORTOOLS)
+  find_package(ortools CONFIG REQUIRED)
+  target_sources(synkit_mapper PRIVATE src/solvers/ortools.cpp)
+  target_link_libraries(synkit_mapper PRIVATE ortools::ortools)
+  target_compile_definitions(synkit_mapper PRIVATE SYNKIT_MAPPER_WITH_ORTOOLS)
+endif()
+set(SYNKIT_MAPPER_OPENWBO_EXECUTABLE "" CACHE FILEPATH "Qualified native Open-WBO executable")
+set(SYNKIT_MAPPER_EVALMAXSAT_EXECUTABLE "" CACHE FILEPATH "Qualified native EvalMaxSAT executable")
+if(SYNKIT_MAPPER_OPENWBO_EXECUTABLE OR SYNKIT_MAPPER_EVALMAXSAT_EXECUTABLE)
+  if(SYNKIT_MAPPER_OPENWBO_EXECUTABLE AND NOT EXISTS "${SYNKIT_MAPPER_OPENWBO_EXECUTABLE}")
+    message(FATAL_ERROR "Open-WBO executable does not exist")
+  endif()
+  target_sources(synkit_mapper PRIVATE src/solvers/maxsat.cpp)
+  target_compile_definitions(synkit_mapper PRIVATE SYNKIT_MAPPER_WITH_MAXSAT)
+  if(SYNKIT_MAPPER_OPENWBO_EXECUTABLE)
+    target_compile_definitions(synkit_mapper PRIVATE
+      SYNKIT_MAPPER_OPENWBO_EXECUTABLE="${SYNKIT_MAPPER_OPENWBO_EXECUTABLE}")
+  endif()
+  if(SYNKIT_MAPPER_EVALMAXSAT_EXECUTABLE)
+    if(NOT EXISTS "${SYNKIT_MAPPER_EVALMAXSAT_EXECUTABLE}")
+      message(FATAL_ERROR "EvalMaxSAT executable does not exist")
+    endif()
+    target_compile_definitions(synkit_mapper PRIVATE
+      SYNKIT_MAPPER_EVALMAXSAT_EXECUTABLE="${SYNKIT_MAPPER_EVALMAXSAT_EXECUTABLE}")
+  endif()
+endif()
+
+option(SYNKIT_MAPPER_BUILD_EXAMPLES "Build standalone C++ mapper examples" OFF)
+if(SYNKIT_MAPPER_BUILD_EXAMPLES)
+  add_executable(slap_graph examples/slap_graph.cpp)
+  target_link_libraries(slap_graph PRIVATE synkit_mapper)
+endif()
+
+include(GNUInstallDirs)
+option(SYNKIT_MAPPER_WHEEL "Install only the runtime library inside the Python wheel" OFF)
+if(SYNKIT_MAPPER_WHEEL)
+  if(MSVC AND NOT SYNKIT_MAPPER_WITH_ORTOOLS)
+    # Standard wheels must not depend on a separately installed MSVC C++ runtime.
+    set_property(TARGET synkit_mapper PROPERTY MSVC_RUNTIME_LIBRARY
+      "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+  endif()
+  install(TARGETS synkit_mapper
+    LIBRARY DESTINATION synkit/Chem/Mapper/solvers/native/lib
+    RUNTIME DESTINATION synkit/Chem/Mapper/solvers/native/lib)
+else()
+  install(TARGETS synkit_mapper
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+  install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+  if(SYNKIT_MAPPER_WITH_RDKIT)
+    install(TARGETS synkit_mapper_reaction mapper_reaction
+      LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+      RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+  endif()
+endif()

synkit/Chem/Mapper/solvers/native/cpp/examples/map_reaction.cpp

@@ -0,0 +1,29 @@
+#include "synkit_mapper/reaction/reaction.h"
+#include <cstdlib>
+#include <iostream>
+
+int main(int argc, char **argv) {
+  if (argc < 2) {
+    std::cerr << "usage: mapper_reaction 'reactants>>products' [backend_id] [seconds]\n";
+    return 2;
+  }
+  SynkitReactionOptions options{1, 1, 1, 0, 0, 0, 0, 100000, 10000};
+  SynkitMapperRequest request{};
+  request.abi_version = 1;
+  request.backend = argc > 2 ? std::atoi(argv[2]) : SYNKIT_PABS;
+  request.query = SYNKIT_MINIMUM_CLASSES;
+  request.workers = 1;
+  request.seconds = argc > 3 ? std::atof(argv[3]) : 10;
+  request.max_states = request.max_classes = request.max_frontier =
+      request.memory_limit_bytes = -1;
+  request.max_candidates = 100000;
+  request.slap_max_fingerprints = 10000;
+  char *json = nullptr;
+  if (synkit_mapper_reaction_solve(argv[1], &options, &request, &json)) {
+    std::cerr << synkit_mapper_reaction_error() << '\n';
+    return 1;
+  }
+  std::cout << json << '\n';
+  synkit_mapper_reaction_free(json);
+  return 0;
+}

synkit/Chem/Mapper/solvers/native/cpp/examples/slap_graph.cpp

@@ -0,0 +1,63 @@
+// Standalone SLAP on a permuted three-node path, with no Python runtime.
+#include "synkit_mapper/slap.h"
+
+#include <array>
+#include <cmath>
+#include <cstdint>
+#include <iostream>
+
+namespace {
+constexpr int N = 3;
+constexpr std::array<int64_t, N * N> A2{0, 2, 0, 2, 0, 2, 0, 2, 0};
+constexpr std::array<int64_t, N * N> B2{0, 2, 2, 2, 0, 0, 2, 0, 0};
+
+struct Output {
+  int count = 0;
+  bool valid = true;
+};
+
+int receive(const int32_t *mapping, int64_t cost2, void *userdata) {
+  auto &output = *static_cast<Output *>(userdata);
+  std::array<bool, N> seen{};
+  for (int i = 0; i < N; ++i) {
+    if (mapping[i] < 0 || mapping[i] >= N || seen[mapping[i]]) {
+      output.valid = false;
+      return 1;
+    }
+    seen[mapping[i]] = true;
+  }
+  int64_t score2 = 0;
+  for (int i = 0; i < N; ++i)
+    for (int j = i + 1; j < N; ++j)
+      score2 += std::abs(A2[i * N + j] - B2[mapping[i] * N + mapping[j]]);
+  if (score2 != cost2 || score2 != 0) {
+    output.valid = false;
+    return 1;
+  }
+  ++output.count;
+  std::cout << "candidate " << output.count << ": CD=" << cost2 / 2.0
+            << ", mapping=";
+  for (int i = 0; i < N; ++i)
+    std::cout << (i ? "," : "") << mapping[i];
+  std::cout << '\n';
+  return 0;
+}
+} // namespace
+
+int main() {
+  const std::array<int32_t, N> labels{6, 6, 6};
+  const std::array<int32_t, N> stop_flags{0, 0, 0};
+  Output output;
+  SlapStatistics statistics{};
+  const int status = synkit_slap_solve(
+      N, A2.data(), B2.data(), labels.data(), labels.data(), stop_flags.data(),
+      10000, -1, -1, -1, receive, &output, &statistics);
+  if (status || !output.valid || !statistics.completed || !output.count) {
+    std::cerr << "SLAP example failed: " << synkit_mapper_error() << '\n';
+    return 1;
+  }
+  std::cout << "Finished heuristic exploration: " << statistics.states
+            << " states, " << statistics.lap_calls << " LAP calls.\n"
+            << "SLAP provides no general optimality or all-class guarantee.\n";
+  return 0;
+}

synkit/Chem/Mapper/solvers/native/cpp/include/synkit_mapper/assignment/assignment.h

@@ -0,0 +1,18 @@
+#pragma once
+#include "synkit_mapper/mapper.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+SYNKIT_MAPPER_API const char *synkit_mapper_assignment_error(void);
+// Construct a restricted uncertainty kernel from supplied heuristic candidates.
+// Consensus rows are fixed, other rows retain observed images. Small uncertain
+// same-type blocks may be closed when their size <= close_block_size. No
+// assertion is made that these domains contain all full-space optima.
+SYNKIT_MAPPER_API int synkit_mapper_kernel_domains(
+    int32_t n, int64_t count, const int32_t *mappings,
+    const int32_t *types_r, const int32_t *types_p, int32_t close_block_size,
+    uint8_t *allowed);
+#ifdef __cplusplus
+}
+#endif

synkit/Chem/Mapper/solvers/native/cpp/include/synkit_mapper/astar/astar.h

@@ -0,0 +1,18 @@
+#ifndef SYNKIT_MAPPER_ASTAR_H
+#define SYNKIT_MAPPER_ASTAR_H
+
+#include "synkit_mapper/mapper.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+// Diagnostic for independent admissibility tests. partial has problem->n
+// entries, -1 for unassigned. Returns 0 on success, -1 on invalid input.
+SYNKIT_MAPPER_API int
+synkit_astar_partial_bound2(const SynkitMapperProblem *problem,
+                            const int32_t *partial, int64_t *bound2);
+#ifdef __cplusplus
+}
+#endif
+
+#endif

synkit/Chem/Mapper/solvers/native/cpp/include/synkit_mapper/astar/bound.h

@@ -0,0 +1,33 @@
+#ifndef SYNKIT_MAPPER_ASTAR_BOUND_H
+#define SYNKIT_MAPPER_ASTAR_BOUND_H
+
+#include <cstdint>
+#include <functional>
+#include <vector>
+
+namespace synkit_mapper {
+namespace astar {
+
+// Total (committed plus residual) doubled-CD lower bound for a compatible
+// partial map. A -1 image denotes an unassigned source. The complete vector is
+// required; a used-target set alone does not define this bound. Throws on an
+// invalid/incompatible partial map or unsupported integer arithmetic range.
+// This C++ diagnostic uses the same bound as search and is independently
+// checked against exhaustive completions in the conformance suite.
+int64_t partial_lower_bound2(int n, const int64_t *a2, const int64_t *b2,
+                             const int32_t *types_r, const int32_t *types_p,
+                             const std::vector<int32_t> &mapping,
+                             const std::function<void()> &poll = {});
+
+// Feasible typed assignment minimizing the same sorted-neighbor profile
+// relaxation used at an empty partial map. This is an input-only incumbent
+// seed, not an optimum certificate for the pairwise mapping objective.
+std::vector<int32_t> profile_assignment_seed(
+    int n, const int64_t *a2, const int64_t *b2,
+    const int32_t *types_r, const int32_t *types_p,
+    const std::function<void()> &poll = {});
+
+} // namespace astar
+} // namespace synkit_mapper
+
+#endif

synkit/Chem/Mapper/solvers/native/cpp/include/synkit_mapper/core/pmcd_witness.h

@@ -0,0 +1,16 @@
+#pragma once
+#include <stdint.h>
+#ifdef __cplusplus
+extern "C" {
+#endif
+// Per-thread witness for the most recent shared-core call. Each solve clears
+// it first; a zero length means that this call retained no PMCD witness.
+// Query with mapping == NULL and capacity == 0 to obtain the required length.
+void synkit_mapper_clear_pmcd_witness(void);
+void synkit_mapper_store_pmcd_witness(int n, const int32_t *mapping,
+                                      int64_t cost2, int proven);
+int synkit_mapper_last_pmcd_witness(int32_t *mapping, int capacity,
+                                    int64_t *cost2, int *proven);
+#ifdef __cplusplus
+}
+#endif