synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Mapper/solvers/native/cpp/include/synkit_mapper/symmetry/classification.h

@@ -0,0 +1,140 @@
+#ifndef SYNKIT_MAPPER_SYMMETRY_CLASSIFICATION_H
+#define SYNKIT_MAPPER_SYMMETRY_CLASSIFICATION_H
+
+#include <stdint.h>
+#include "synkit_mapper/slap.h"
+#include "synkit_mapper/mapper.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Exact palette ranks are ordered by Python's _encode_color tokens. Node
+ * colors are ranks, edge colors rank+1 (zero is absent). Endpoint edge states
+ * are independent dense indices; edge_pair_colors pairs their full attributes,
+ * including optional E/Z. Thus no chemistry attribute is discarded natively.
+ * Palette entries are canonical ASCII JSON tokens, without surrounding list.
+ * Only complete canonical searches publish keys. Equality uses full SKC1 bytes,
+ * never their SHA256 identifiers. The identifiers preserve the legacy dense
+ * certificate SHA256 encoding. This additive interface has version 1.
+ */
+typedef struct SynkitClassProblem {
+  int32_t n;
+  const int32_t *node_pair_colors; /* n*n */
+  const int32_t *edges_r;         /* n*n endpoint state IDs */
+  const int32_t *edges_p;
+  int32_t edge_states_r;
+  int32_t edge_states_p;
+  const int32_t *edge_pair_colors;
+  int32_t palette_size;
+  const char *const *palette_json;
+} SynkitClassProblem;
+
+typedef struct SynkitClassStatistics {
+  int64_t candidates;
+  int64_t classes;
+  int64_t canonical_nodes;
+  int32_t complete;
+  /* 0 complete, 1 deadline, 2 canonical node cap, 3 class cap, 4 callback,
+   * 5 cancellation requested. */
+  int32_t reason;
+  double elapsed_seconds;
+} SynkitClassStatistics;
+
+typedef int (*SynkitClassCallback)(const int32_t *representative,
+                                  int64_t cost2, int64_t observed_count,
+                                  const unsigned char *packed_key,
+                                  int64_t packed_size,
+                                  const char *legacy_identifier,
+                                  void *userdata);
+
+SYNKIT_MAPPER_API int synkit_mapper_classification_abi(void);
+/* Additive capacity discovery; libraries without this export support256. */
+SYNKIT_MAPPER_API int synkit_mapper_classification_max_vertices(void);
+SYNKIT_MAPPER_API const char *synkit_mapper_classification_error(void);
+/* mappings is count*n, costs2 is count. seconds=-1 means unlimited. A shared
+ * remaining deadline should be passed by the pipeline. All caps are -1 or
+ * positive; max_nodes applies across the entire batch. No exceptions cross
+ * callbacks. Return 0 for complete/interrupted, -1 for invalid input/error. */
+SYNKIT_MAPPER_API int synkit_mapper_classify_batch(
+    const SynkitClassProblem *problem, int64_t count,
+    const int32_t *mappings, const int64_t *costs2,
+    double seconds, int64_t max_nodes, int64_t max_classes,
+    SynkitClassCallback callback, void *userdata,
+    SynkitClassStatistics *statistics);
+SYNKIT_MAPPER_API int synkit_mapper_classify_batch_with_cancel(
+    const SynkitClassProblem *problem, int64_t count,
+    const int32_t *mappings, const int64_t *costs2,
+    double seconds, int64_t max_nodes, int64_t max_classes, void *cancel_token,
+    SynkitClassCallback callback, void *userdata,
+    SynkitClassStatistics *statistics);
+
+/* Additive delivery mode: first discovery publishes a complete exact key
+ * immediately, then a final cumulative observed-count update when needed.
+ * Merge callbacks by the FULL packed key; updates are not new mappings or
+ * additional classes. Complete output has final counts. Interrupted output
+ * counts are nondecreasing lower bounds and incomplete flags stay explicit.
+ * The legacy batch entry points and their one-callback contract are unchanged.
+ * Publication and canonical work share the supplied deadline. */
+SYNKIT_MAPPER_API int synkit_mapper_classify_batch_updates_with_cancel(
+    const SynkitClassProblem *problem, int64_t count,
+    const int32_t *mappings, const int64_t *costs2,
+    double seconds, int64_t max_nodes, int64_t max_classes, void *cancel_token,
+    SynkitClassCallback callback, void *userdata,
+    SynkitClassStatistics *statistics);
+
+/* Additive explicit options; both flags must be 0 or 1. updates uses the
+ * cumulative-count contract above. packed_identifier=1 returns SHA256 of the
+ * exact SKC1 bytes as the presentation identifier; 0 preserves legacy IDs.
+ * Keys, canonicalization, deduplication, budgets and statistics are unchanged.
+ * No process-global mode is set; existing entry points always use legacy IDs. */
+SYNKIT_MAPPER_API int synkit_mapper_classify_batch_ex(
+    const SynkitClassProblem *problem, int64_t count,
+    const int32_t *mappings, const int64_t *costs2,
+    double seconds, int64_t max_nodes, int64_t max_classes, void *cancel_token,
+    SynkitClassCallback callback, void *userdata,
+    SynkitClassStatistics *statistics, int32_t updates, int32_t packed_identifier);
+
+/* Entire prepared search -> class pipeline. Intermediate mapping callbacks
+ * stay in C++; only class records cross the output callback. Search and class
+ * processing share the request deadline and core cancellation token. The
+ * supplied request must have classify=1; class cap applies to distinct keys.
+ * Classification node budget is separate and explicit. Search candidate cap
+ * retains its candidate units; exact class equality is never a hash test.
+ * Results distinguish search completion from classification completion. */
+SYNKIT_MAPPER_API int synkit_mapper_solve_classified(
+    const SynkitMapperProblem *, const SynkitMapperRequest *,
+    const SynkitClassProblem *, int64_t max_canonical_nodes,
+    SynkitClassCallback, void *, SynkitMapperStatistics *, SynkitClassStatistics *);
+/* Restricted-domain variant. The row-major n*n zero/one mask is passed intact
+ * to synkit_mapper_solve_domains; neither classification nor batching expands
+ * it. Minimum proof/completeness scope remains exactly the supplied domains. */
+SYNKIT_MAPPER_API int synkit_mapper_solve_domains_classified(
+    const SynkitMapperProblem *, const SynkitMapperRequest *, const uint8_t *allowed,
+    const SynkitClassProblem *, int64_t max_canonical_nodes,
+    SynkitClassCallback, void *, SynkitMapperStatistics *, SynkitClassStatistics *);
+
+/* Search followed by incremental class delivery, with cumulative-count
+ * callbacks as documented above. Existing classified entry points remain
+ * batch interfaces. Raw search and classification still share one deadline. */
+SYNKIT_MAPPER_API int synkit_mapper_solve_classified_updates(
+    const SynkitMapperProblem *, const SynkitMapperRequest *,
+    const SynkitClassProblem *, int64_t max_canonical_nodes,
+    SynkitClassCallback, void *, SynkitMapperStatistics *, SynkitClassStatistics *);
+SYNKIT_MAPPER_API int synkit_mapper_solve_domains_classified_updates(
+    const SynkitMapperProblem *, const SynkitMapperRequest *, const uint8_t *allowed,
+    const SynkitClassProblem *, int64_t max_canonical_nodes,
+    SynkitClassCallback, void *, SynkitMapperStatistics *, SynkitClassStatistics *);
+
+/* Explicit options as above; allowed may be NULL for unrestricted search or
+ * the unchanged n*n zero/one kernel mask. ABI1 structs are not extended. */
+SYNKIT_MAPPER_API int synkit_mapper_solve_classified_ex(
+    const SynkitMapperProblem *, const SynkitMapperRequest *, const uint8_t *allowed,
+    const SynkitClassProblem *, int64_t max_canonical_nodes,
+    SynkitClassCallback, void *, SynkitMapperStatistics *, SynkitClassStatistics *,
+    int32_t updates, int32_t packed_identifier);
+
+#ifdef __cplusplus
+}
+#endif
+#endif

synkit/Chem/Mapper/solvers/native/cpp/include/synkit_mapper/symmetry/cpabs.h

@@ -0,0 +1,33 @@
+#ifndef SYNKIT_MAPPER_SYMMETRY_CPABS_H
+#define SYNKIT_MAPPER_SYMMETRY_CPABS_H
+#include "synkit_mapper/mapper.h"
+#ifdef __cplusplus
+extern "C" {
+#endif
+typedef struct SynkitCPABSProfile {
+  int64_t discovery_nodes;
+  int64_t subgroup_order;
+  int64_t canonical_calls;
+  int64_t augmentations;
+  int64_t canonical_rejections;
+  int64_t bound_rejections;
+  int32_t identity_fallback_r;
+  int32_t identity_fallback_p;
+  double discovery_seconds;
+  double canonical_seconds;
+} SynkitCPABSProfile;
+/* Read the current thread's most recent run. Profile is diagnostic, never a
+ * claim of complete endpoint symmetry discovery. Legacy fallback flags now
+ * indicate an incomplete quotient group; verified twin factors remain active. */
+SYNKIT_MAPPER_API void synkit_mapper_cpabs_profile(SynkitCPABSProfile *);
+typedef struct SynkitCPABSProfileV2 {
+  SynkitCPABSProfile base;
+  int64_t twin_blocks_r,twin_blocks_p,quotient_order_r,quotient_order_p;
+  int64_t bound_calls,seed_cost2;
+  double bound_seconds,seed_seconds;
+} SynkitCPABSProfileV2;
+SYNKIT_MAPPER_API void synkit_mapper_cpabs_profile_v2(SynkitCPABSProfileV2 *);
+#ifdef __cplusplus
+}
+#endif
+#endif

synkit/Chem/Mapper/solvers/native/cpp/src/assignment/abb.cpp

@@ -0,0 +1,302 @@
+#include "synkit_mapper/core/runtime.h"
+#include <limits>
+#include <numeric>
+#include <set>
+#include <string>
+
+namespace synkit_mapper {
+namespace {
+constexpr int64_t INF = std::numeric_limits<int64_t>::max() / 8;
+
+// Integral Hungarian assignment. Forbidden domain entries have cost INF.
+int64_t lap(const std::vector<std::vector<int64_t>> &cost,
+            const Budget &budget, std::vector<int> *assignment = nullptr) {
+  const int n = static_cast<int>(cost.size());
+  std::vector<int64_t> u(n + 1), v(n + 1);
+  std::vector<int> p(n + 1), way(n + 1);
+  for (int i = 1; i <= n; ++i) {
+    budget.check();
+    p[0] = i;
+    int j0 = 0;
+    std::vector<int64_t> slack(n + 1, INF);
+    std::vector<bool> used(n + 1, false);
+    do {
+      budget.check();
+      used[j0] = true;
+      int i0 = p[j0], j1 = 0;
+      int64_t delta = INF;
+      for (int j = 1; j <= n; ++j)
+        if (!used[j]) {
+          int64_t cur = cost[i0 - 1][j - 1] >= INF
+                            ? INF
+                            : cost[i0 - 1][j - 1] - u[i0] - v[j];
+          if (cur < slack[j]) {
+            slack[j] = cur;
+            way[j] = j0;
+          }
+          if (slack[j] < delta) {
+            delta = slack[j];
+            j1 = j;
+          }
+        }
+      if (delta >= INF)
+        return INF;
+      for (int j = 0; j <= n; ++j)
+        if (used[j]) {
+          u[p[j]] += delta;
+          v[j] -= delta;
+        } else if (slack[j] < INF)
+          slack[j] -= delta;
+      j0 = j1;
+    } while (p[j0] != 0);
+    do {
+      int j1 = way[j0];
+      p[j0] = p[j1];
+      j0 = j1;
+    } while (j0);
+  }
+  if (assignment) {
+    assignment->assign(n, -1);
+    for (int j = 1; j <= n; ++j)
+      (*assignment)[p[j] - 1] = j - 1;
+  }
+  return -v[0];
+}
+
+class AssignmentSearch {
+  const Problem &p;
+  const Request &r;
+  const uint8_t *allowed;
+  Callback callback;
+  void *userdata;
+  Statistics &s;
+  Budget budget;
+  std::vector<int> order;
+  std::vector<int32_t> mapping;
+  std::vector<bool> used;
+  int64_t best = INF;
+  int64_t threshold = 0;
+  bool optimize = false;
+
+  bool compatible(int i, int j) const {
+    return p.types_r[i] == p.types_p[j] &&
+           (!allowed || allowed[i * p.n + j]);
+  }
+  void poll() {
+    budget.check();
+    if (r.max_states >= 0 && s.nodes >= r.max_states)
+      throw Stop{SYNKIT_STOP_STATES};
+    ++s.nodes;
+  }
+  int64_t cross(int i, int j, int depth) const {
+    int64_t value = 0;
+    for (int k = 0; k < depth; ++k) {
+      const int a = order[k];
+      value += std::abs(p.a2[i * p.n + a] - p.b2[j * p.n + mapping[a]]);
+    }
+    return value;
+  }
+  // Every unresolved-to-committed pair is counted exactly once. Ignoring
+  // unresolved-to-unresolved pairs can only decrease the nonnegative cost.
+  int64_t bound(int depth, int64_t committed) {
+    int count = p.n - depth;
+    std::vector<int> products;
+    for (int j = 0; j < p.n; ++j)
+      if (!used[j])
+        products.push_back(j);
+    std::vector<std::vector<int64_t>> costs(
+        count, std::vector<int64_t>(count, INF));
+    for (int a = 0; a < count; ++a) {
+      budget.check();
+      const int i = order[depth + a];
+      for (int b = 0; b < count; ++b)
+        if (compatible(i, products[b]))
+          costs[a][b] = cross(i, products[b], depth);
+    }
+    int64_t rest = lap(costs, budget);
+    return rest >= INF ? INF : committed + rest;
+  }
+  void emit(int64_t cost) {
+    ++s.candidate_count;
+    s.labeled_count = s.candidate_count;
+    const auto start = Clock::now();
+    const int stop = callback ? callback(mapping.data(), cost, userdata) : 0;
+    s.callback_seconds += elapsed(start);
+    if (stop)
+      throw Stop{SYNKIT_STOP_CALLBACK};
+    budget.check();
+    if (r.max_candidates >= 0 && s.candidate_count >= r.max_candidates)
+      throw Stop{SYNKIT_STOP_CANDIDATES};
+  }
+  void visit(int depth, int64_t committed) {
+    poll();
+    const int64_t cutoff = optimize ? best : threshold;
+    if ((optimize && committed >= cutoff) || (!optimize && committed > cutoff))
+      return;
+    if (depth == p.n) {
+      ++s.leaves;
+      if (optimize) {
+        best = committed;
+        s.incumbent2 = best;
+      } else if (r.query != SYNKIT_EXACT_DISTANCE || committed == threshold)
+        emit(committed);
+      return;
+    }
+    int64_t lower = bound(depth, committed);
+    if ((optimize && lower >= cutoff) || (!optimize && lower > cutoff))
+      return;
+    const int i = order[depth];
+    std::vector<std::pair<int64_t, int>> choices;
+    for (int j = 0; j < p.n; ++j)
+      if (!used[j] && compatible(i, j))
+        choices.emplace_back(cross(i, j, depth), j);
+    std::sort(choices.begin(), choices.end());
+    for (auto [delta, j] : choices) {
+      mapping[i] = j;
+      used[j] = true;
+      visit(depth + 1, committed + delta);
+      used[j] = false;
+      mapping[i] = -1;
+    }
+  }
+
+public:
+  AssignmentSearch(const Problem &problem, const Request &request,
+                   const uint8_t *domains, Callback cb, void *data,
+                   Statistics &statistics)
+      : p(problem), r(request), allowed(domains), callback(cb), userdata(data),
+        s(statistics), budget(r), order(p.n), mapping(p.n, -1),
+        used(p.n, false) {}
+  int run() {
+    if (r.classify || r.max_classes != -1 || r.max_frontier != -1 ||
+        r.memory_limit_bytes != -1 || r.symmetry)
+      return unsupported(s);
+    double phase = 0;
+    try {
+      budget.check();
+      std::iota(order.begin(), order.end(), 0);
+      std::vector<int> sizes(p.n), degrees(p.n);
+      for (int i = 0; i < p.n; ++i)
+        for (int j = 0; j < p.n; ++j) {
+          sizes[i] += compatible(i, j);
+          degrees[i] += p.a2[i * p.n + j] != 0;
+        }
+      std::stable_sort(order.begin(), order.end(), [&](int a, int b) {
+        return sizes[a] == sizes[b] ? degrees[a] > degrees[b]
+                                    : sizes[a] < sizes[b];
+      });
+      std::vector<std::vector<int64_t>> seed_cost(
+          p.n, std::vector<int64_t>(p.n, INF));
+      for (int i = 0; i < p.n; ++i) {
+        budget.check();
+        for (int j = 0; j < p.n; ++j)
+          if (compatible(i, j))
+            seed_cost[i][j] = 0;
+      }
+      std::vector<int> seed;
+      if (lap(seed_cost, budget, &seed) < INF) {
+        std::vector<int32_t> candidate(seed.begin(), seed.end());
+        best = mapping_cost2(p, candidate);
+        s.incumbent2 = best;
+      }
+      s.model_seconds = budget.seconds();
+      phase = budget.seconds();
+      if (r.query == SYNKIT_MINIMUM_CLASSES || r.query == SYNKIT_MINIMUM_PROOF) {
+        optimize = true;
+        if (best > 0 && best < INF)
+          visit(0, 0);
+        budget.check();
+        s.optimization_seconds = budget.seconds() - phase;
+        if (best < INF) {
+          s.minimum_proven = 1;
+          s.minimum2 = s.lower_bound2 = best;
+        }
+        if (r.query == SYNKIT_MINIMUM_PROOF || best == INF) {
+          s.search_complete = 1;
+          s.elapsed_seconds = budget.seconds();
+          return 0;
+        }
+        threshold = best;
+      } else
+        threshold = r.target2;
+      optimize = false;
+      phase = budget.seconds();
+      visit(0, 0);
+      budget.check();
+      s.enumeration_seconds = budget.seconds() - phase;
+      s.search_complete = 1;
+      if (s.labeled_count < 0)
+        s.labeled_count = 0;
+    } catch (const Stop &stop) {
+      if (optimize)
+        s.optimization_seconds = budget.seconds() - phase;
+      else
+        s.enumeration_seconds = budget.seconds() - phase;
+      stopped(s, stop.reason);
+    }
+    s.elapsed_seconds = budget.seconds();
+    return 0;
+  }
+};
+} // namespace
+
+int solve_abb(const Problem &p, const Request &r, const uint8_t *domains,
+              Callback cb, void *data, Statistics &s) {
+  return AssignmentSearch(p, r, domains, cb, data, s).run();
+}
+} // namespace synkit_mapper
+
+namespace {
+thread_local std::string assignment_error;
+}
+extern "C" const char *synkit_mapper_assignment_error(void) {
+  return assignment_error.c_str();
+}
+extern "C" 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) {
+  assignment_error.clear();
+  try {
+    if (n < 1 || n > 1024 || count < 1 || count > 1000000 || !mappings ||
+        !types_r || !types_p || !allowed || close_block_size < 0)
+      throw std::invalid_argument("Invalid native uncertainty-kernel arguments");
+    std::fill(allowed, allowed + n * n, uint8_t{0});
+    for (int64_t k = 0; k < count; ++k) {
+      std::vector<bool> seen(n, false);
+      for (int i = 0; i < n; ++i) {
+        const int j = mappings[k * n + i];
+        if (j < 0 || j >= n || seen[j] || types_r[i] != types_p[j])
+          throw std::invalid_argument("Kernel candidate is not a compatible bijection");
+        seen[j] = true;
+        allowed[i * n + j] = 1;
+      }
+    }
+    std::map<int32_t, std::vector<int>> rows;
+    for (int i = 0; i < n; ++i) {
+      int size = 0;
+      for (int j = 0; j < n; ++j)
+        size += allowed[i * n + j];
+      if (size > 1)
+        rows[types_r[i]].push_back(i);
+    }
+    for (const auto &[type, block] : rows) {
+      (void)type;
+      if (static_cast<int>(block.size()) > close_block_size)
+        continue;
+      std::set<int> products;
+      for (int i : block)
+        for (int j = 0; j < n; ++j)
+          if (allowed[i * n + j])
+            products.insert(j);
+      if (products.size() == block.size())
+        for (int i : block)
+          for (int j : products)
+            allowed[i * n + j] = 1;
+    }
+    return 0;
+  } catch (const std::exception &e) {
+    assignment_error = e.what();
+    return -1;
+  }
+}

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

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.16)
+project(synkit_astar_standalone LANGUAGES CXX)
+
+add_executable(astar_graph astar_graph.cpp astar.cpp bound.cpp)
+target_compile_features(astar_graph PRIVATE cxx_std_17)
+target_include_directories(astar_graph PRIVATE ../../include)
+set_target_properties(astar_graph PROPERTIES CXX_EXTENSIONS OFF)
+if(MSVC)
+  target_compile_options(astar_graph PRIVATE /W4)
+else()
+  target_compile_options(astar_graph PRIVATE -Wall -Wextra -Wpedantic)
+endif()

synkit/Chem/Mapper/solvers/native/cpp/src/astar/README.md

@@ -0,0 +1,47 @@
+# Weighted best-first atom assignment
+
+The module searches compatible bijections with a priority queue ordered by an
+admissible bound in integer doubled-CD units. “Weighted” describes the Lewis
+edge costs. The heuristic multiplier is exactly one; this is not the
+suboptimal, inflated-heuristic variant sometimes called weighted A*.
+
+For a partial map `p:S -> T`, let `U,V` be its residual vertices. Its committed
+cost `g` contains exactly the pairs wholly in `S`. For a compatible `i -> j`,
+let `c(i,j)` sum the discrepancies from `i,j` to all committed pairs. For each
+hard atom type, sort the residual incident edge weights at `i` and `j`,
+including zero weights and excluding the vertex itself. Let `q(i,j)` be the
+sum of absolute differences between these sorted lists over all types.
+
+Any compatible completion pairs those lists by a permutation. Sorted pairing
+minimizes one-dimensional absolute discrepancy, so `q(i,j)` is no larger
+than that completion's residual incident discrepancy. Summing over a complete
+residual assignment counts every residual-residual edge twice. Consequently
+
+    h = ceil(min_compatible_assignment sum(2*c(i,j) + q(i,j)) / 2)
+
+is no greater than the integral residual cost. The bound `g+h` has no double
+counting: committed pairs are in `g`, committed/residual pairs are in `c`,
+and residual pairs are covered by the half incident bound. Nonbonding-electron
+anchors, if present in the common encoding, are ordinary forced typed vertices;
+the module adds no second unary electron term.
+
+Each state stores the entire partial image vector. A deterministic fixed
+source order gives every labeled bijection one path; there is no symmetry
+pruning and no closed set keyed by a used-target set or hash. In particular,
+this implementation enumerates labeled mappings and requires the shared
+classification stage for all-class output.
+
+The first complete state removed from the queue proves the minimum, because
+every unexpanded completion is bounded below by a queued state's bound.
+Continuing until the least queue bound exceeds that optimum enumerates every
+minimum labeled mapping. Numeric exact and at-most queries retain their
+original threshold even after finding a cheaper mapping. Exact queries filter
+only full-state costs; their threshold is never an incumbent.
+
+An empty exhausted frontier proves the selected shell/interval complete (and
+can prove no compatible completion). Time, cancellation, candidate, state and
+frontier-memory stops preserve incomplete enumeration; a minimum already
+proved remains a separate fact. Frontier bytes describe allocated state and
+queue storage accounted by this implementation, not whole-process RSS or an
+enforced operating-system memory limit. Tests compare partial bounds against
+independently scored exhaustive completions and complete tiny mapping sets.