synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Mapper/solvers/exact/native/frontier.py

@@ -0,0 +1,390 @@
+"""Schedule disjoint resumable native subtrees and merge exact records online."""
+
+import ctypes
+import math
+import multiprocessing as mp
+import os
+import time
+from collections import deque
+from concurrent.futures import FIRST_COMPLETED, ProcessPoolExecutor, wait
+from pathlib import Path
+
+from .candidates import (
+    NativeEnumerationStop,
+    enumerate_native_candidates,
+    prepare_native_candidates,
+)
+from .canonical import compact_code_identifier, transport_canonical_key
+from .orbit_aggregation import OrbitAccumulator
+from .runtime import limit_worker_address_space, pin_worker_cpu, worker_cpus
+
+try:
+    import resource
+except ImportError:  # Windows has no Unix resource module.
+    resource = None
+
+_STATE = None
+_ADDRESS_SPACE_LIMIT = None
+
+
+def _init(
+    lgp,
+    target,
+    config,
+    seed,
+    library,
+    counter,
+    deadline,
+    barrier,
+    cpu_index,
+    cpus,
+    prepared_data,
+):
+    global _STATE, _ADDRESS_SPACE_LIMIT
+    from ....reporting.analysis import _BlindShellObserver, _property_vectors
+    from ...slap.lap import _adjacency_and_elements
+
+    _ADDRESS_SPACE_LIMIT = limit_worker_address_space(resource)
+    with cpu_index.get_lock():
+        index = cpu_index.value
+        cpu_index.value += 1
+    pin_worker_cpu(cpus[index % len(cpus)] if cpus else None)
+    a, labels = _adjacency_and_elements(lgp[0], False)
+    b, _ = _adjacency_and_elements(lgp[1], False)
+    observer = _BlindShellObserver(
+        a, b, labels, _property_vectors(lgp, config.reaction_center_properties), config
+    )
+    # Validated once before spawning; each worker receives private arrays and
+    # attaches its own library handle. Side-group completeness is not re-inferred.
+    prepared = (*prepared_data, ctypes.CDLL(str(Path(library).resolve())))
+    rg, _pg, ro, po = prepared[4:8]
+    accumulator = OrbitAccumulator(
+        observer,
+        rg[1:],
+        ro,
+        po,
+        library_path=library,
+        record_only=True,
+    )
+    _STATE = (
+        lgp,
+        target,
+        config,
+        seed,
+        library,
+        counter,
+        deadline,
+        barrier,
+        accumulator,
+        prepared,
+    )
+
+
+def _ready():
+    barrier = _STATE[7]
+    barrier.wait(timeout=30)
+    barrier.wait(timeout=30)
+    return _ADDRESS_SPACE_LIMIT
+
+
+def _slice(prefixes, slice_nodes):  # noqa: C901
+    from ....reporting.analysis import _mapping_key
+
+    lgp, target, config, _seed, library, counter, deadline, _, accumulator, prepared = (
+        _STATE
+    )
+    records, hashes = {}, set()
+    # The parent fixes this value before releasing the readiness barrier and
+    # never mutates it during search. Snapshot it once per slice: acquiring a
+    # shared process lock at every candidate serializes otherwise independent
+    # callbacks without improving deadline enforcement.
+    slice_deadline = deadline.value
+    counter_value = counter.get_obj()
+    profile = bool(os.environ.get("SYNKIT_NATIVE_PROFILE"))
+    before_timings = dict(accumulator.its_canonicalizer.timings) if profile else {}
+    callback_seconds = identifier_seconds = 0.0
+    pattern_hits_before = accumulator.pattern_hits
+
+    def receive_impl(mapping, cost):
+        nonlocal identifier_seconds
+        if time.perf_counter() >= slice_deadline:
+            raise NativeEnumerationStop("time_limit")
+        hashes.add(_mapping_key(mapping))
+        before = len(accumulator.seen)
+        accumulator.observe(mapping, cost)
+        if len(accumulator.seen) == before:
+            return
+        key = next(reversed(accumulator.seen))
+        with counter.get_lock():
+            if config.max_mappings is not None and counter_value.value >= config.max_mappings:
+                accumulator.seen.pop(key)
+                raise NativeEnumerationStop("mapping_limit")
+            counter_value.value += 1
+        accumulator.its_canonicalizer.remember_pattern()
+        # IDs depend only on exact certificates, so formatting can run while
+        # other workers enumerate. Cached fields never participate in equality.
+        identifier_started = time.perf_counter() if profile else 0
+        object.__setattr__(key, "identifier", compact_code_identifier(key))
+        template_key = accumulator.seen[key][3]
+        if template_key is not None:
+            object.__setattr__(
+                template_key, "identifier", compact_code_identifier(template_key)
+            )
+        if profile:
+            identifier_seconds += time.perf_counter() - identifier_started
+        value = accumulator.seen[key]
+        records[transport_canonical_key(key)] = (
+            *value[:3],
+            transport_canonical_key(template_key),
+            *value[4:],
+        )
+        # Membership alone is sufficient to deduplicate subsequent slices.
+        accumulator.seen[key] = None
+
+    def profiled_receive(mapping, cost):
+        nonlocal callback_seconds
+        started = time.perf_counter()
+        try:
+            return receive_impl(mapping, cost)
+        finally:
+            callback_seconds += time.perf_counter() - started
+
+    receive = profiled_receive if profile else receive_impl
+    remaining = deque(prefixes)
+    frontier = []
+    totals = {
+        "candidate_count": 0,
+        "visited_nodes": 0,
+        "visited_leaves": 0,
+        "pruned": 0,
+        "prefix_replay_nodes": 0,
+        "new_search_nodes": 0,
+    }
+    batch_started = time.perf_counter()
+    reason = None
+    while remaining:
+        batched = hasattr(prepared[-1], "synkit_distance_frontier_batch")
+        options = {}
+        node_budget = slice_nodes
+        if batched:
+            options["prefixes"] = tuple(remaining)
+            node_budget *= min(4, len(remaining))
+            remaining.clear()
+            prefix = ()
+        else:
+            prefix = remaining.popleft()
+        result = enumerate_native_candidates(
+            lgp,
+            target,
+            library_path=library,
+            time_limit_seconds=max(0, slice_deadline - time.perf_counter()),
+            max_mappings=None,
+            callback=receive,
+            prefix=prefix,
+            slice_nodes=node_budget,
+            _prepared=prepared,
+            **options,
+        )
+        for name in totals:
+            totals[name] += result[name] or 0
+        frontier.extend(result["frontier"])
+        if result["reason"] not in (None, "work_slice"):
+            reason = result["reason"]
+            break
+        if time.perf_counter() - batch_started >= 0.25:
+            break
+    frontier.extend(remaining)
+    if reason is None and frontier:
+        reason = "work_slice"
+    totals.update(
+        complete=reason is None,
+        reason=reason,
+        frontier=frontier,
+        retained_classes=len(records),
+        pattern_cache_hits=accumulator.pattern_hits - pattern_hits_before,
+        elapsed_seconds=time.perf_counter() - batch_started,
+    )
+    if profile:
+        totals["profile"] = {
+            key: value - before_timings.get(key, 0)
+            for key, value in accumulator.its_canonicalizer.timings.items()
+        }
+        totals["profile"].update(
+            callback_seconds=callback_seconds,
+            identifier_seconds=identifier_seconds,
+            other_batch_seconds=totals["elapsed_seconds"] - callback_seconds,
+        )
+    return totals, records, hashes
+
+
+def frontier_orbit_search(  # noqa: C901
+    lgp,
+    target,
+    config,
+    seed,
+    observer,
+    *,
+    library_path,
+    workers=8,
+    slice_nodes=8192,
+    absolute_deadline=None,
+):
+    """Consume every emitted subtree before claiming complete coverage.
+
+    The shared cap counts unique records retained within each worker, including
+    duplicate classes held by different workers. Prefix replay is deterministic
+    and preserves the original two-sided pruning state.
+    """
+
+    if (
+        isinstance(workers, bool)
+        or not isinstance(workers, int)
+        or workers < 1
+        or isinstance(slice_nodes, bool)
+        or not isinstance(slice_nodes, int)
+        or not 0 < slice_nodes < (1 << 63)
+    ):
+        raise ValueError("workers and slice_nodes must be positive integers")
+    if (
+        config.binary
+        or set(config.symmetry_node_properties)
+        != set(config.reaction_center_properties)
+        or config.time_limit_seconds is None
+        or not math.isfinite(config.time_limit_seconds)
+    ):
+        raise ValueError(
+            "frontier search requires weighted aligned properties and a finite deadline"
+        )
+    if not hasattr(
+        ctypes.CDLL(str(Path(library_path).resolve())), "synkit_distance_frontier"
+    ):
+        raise ValueError(
+            "native library lacks frontier support; rebuild it or use the static scheduler"
+        )
+    prepared = prepare_native_candidates(
+        lgp,
+        target,
+        library_path=library_path,
+        initial_mapping=seed,
+        node_properties=config.symmetry_node_properties,
+    )
+    rg, _pg, ro, po = prepared[4:8]
+    merged = OrbitAccumulator(
+        observer,
+        rg[1:],
+        ro,
+        po,
+        library_path=library_path,
+        transport_keys=True,
+    )
+    context = mp.get_context("spawn")
+    counter, deadline = context.Value("q", 0), context.Value("d", 0)
+    cpu_index = context.Value("i", 0)
+    barrier = context.Barrier(workers + 1)
+    cpus = worker_cpus(workers)
+    started = time.perf_counter()
+    coordinator_cpu_started = time.process_time()
+    merge_seconds = wait_seconds = 0.0
+    pending, running = deque([()]), set()
+    records, results, reasons = {}, [], set()
+    peak_pending = 1
+    profile_totals = {}
+    with ProcessPoolExecutor(
+        max_workers=workers,
+        mp_context=context,
+        initializer=_init,
+        initargs=(
+            lgp,
+            target,
+            config,
+            seed,
+            str(library_path),
+            counter,
+            deadline,
+            barrier,
+            cpu_index,
+            cpus,
+            prepared[:-1],
+        ),
+    ) as pool:
+        ready = [pool.submit(_ready) for _ in range(workers)]
+        barrier.wait(timeout=30)
+        search_started = time.perf_counter()
+        deadline.value = search_started + config.time_limit_seconds
+        if absolute_deadline is not None:
+            deadline.value = min(deadline.value, absolute_deadline)
+        barrier.wait(timeout=30)
+        for future in ready:
+            future.result()
+        while pending or running:
+            if time.perf_counter() >= deadline.value:
+                reasons.add("time_limit")
+            while pending and len(running) < workers and not reasons:
+                # Share sparse frontiers across idle workers before batching.
+                # Fixed groups of 16 can put all remaining work in one process.
+                idle = workers - len(running)
+                batch_size = min(64, max(1, len(pending) // idle))
+                prefixes = [pending.popleft() for _ in range(batch_size)]
+                running.add(pool.submit(_slice, prefixes, slice_nodes))
+            if not running:
+                break
+            wait_started = time.perf_counter()
+            finished, running = wait(running, timeout=0.25, return_when=FIRST_COMPLETED)
+            merge_started = time.perf_counter()
+            wait_seconds += merge_started - wait_started
+            for future in finished:
+                result, found, hashes = future.result()
+                observer.mapping_hashes.update(hashes)
+                new_tasks = result.pop("frontier")
+                if result["reason"] not in (None, "work_slice"):
+                    reasons.add(result["reason"])
+                else:
+                    pending.extend(new_tasks)
+                    peak_pending = max(peak_pending, len(pending))
+                for key, value in result.pop("profile", {}).items():
+                    profile_totals[key] = profile_totals.get(key, 0) + value
+                results.append(result)
+                for key, value in found.items():
+                    old = records.get(key)
+                    if old is not None and (
+                        old[:2] != value[:2] or old[3:] != value[3:]
+                    ):
+                        raise RuntimeError(
+                            "inconsistent exact records across frontier workers"
+                        )
+                    if old is None:
+                        records[key] = value
+                        merged.merge_record(key, value)
+            merge_seconds += time.perf_counter() - merge_started
+        merged.finish()
+        shutdown_started = time.perf_counter()
+    if time.perf_counter() > deadline.value:
+        reasons.add("time_limit")
+    return {
+        "complete": not reasons and not pending,
+        "profile_totals": profile_totals,
+        "coordinator_cpu_seconds": time.process_time() - coordinator_cpu_started,
+        "coordinator_merge_seconds": merge_seconds,
+        "coordinator_wait_seconds": wait_seconds,
+        "worker_shutdown_seconds": time.perf_counter() - shutdown_started,
+        "worker_startup_seconds": search_started - started,
+        "reasons": sorted(reasons),
+        "timed_phase_seconds": time.perf_counter() - search_started,
+        "retained_worker_records": counter.value,
+        "candidate_count": sum(item["candidate_count"] for item in results),
+        "pattern_cache_hits": sum(item["pattern_cache_hits"] for item in results),
+        "mapping_limit_scope": "retained_worker_double_orbit_representatives",
+        "workers": workers,
+        "scheduler": "resumable_subtree_queue",
+        "slice_nodes": slice_nodes,
+        "completed_batches": len(results),
+        "prefix_replay_nodes": sum(item["prefix_replay_nodes"] for item in results),
+        "new_search_nodes": sum(item["new_search_nodes"] for item in results),
+        "pending_subtrees": len(pending),
+        "peak_pending_subtrees": peak_pending,
+        "shards": results,
+        "unique_classes": len(records),
+        "weighted_product_representatives": observer.count,
+        "labeled_mappings": observer.count * merged.product_order,
+        "elapsed_seconds": time.perf_counter() - started,
+    }, merged

synkit/Chem/Mapper/solvers/exact/native/hydrogen_quotient.py

@@ -0,0 +1,213 @@
+"""Experimental exact terminal-H quotient for minimum Lewis mapping classes.
+
+For a fixed heavy-atom bijection f, neutral monovalent terminal hydrogens have
+minimum bond cost sum_i |h_R[i] - h_P[f(i)]|. This remains true with unequal H
+inventories when isolated zero-state H placeholders form the missing-side
+reservoir. Adding this term before heavy-map optimization gives a global
+explicit-H Lewis minimum, unlike optimizing heavy bonds and lifting afterward.
+
+Only minimum queries use the quotient. Numeric queries, nonordinary H atoms,
+and annotated stereochemistry fall back to the full explicit-H native solver.
+Every optimal integer H transport is lifted, then the common chemical frontend
+performs exact full-ITS classification. This is an experimental reduction, not
+a replacement for the public default or a polynomial all-class enumerator.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+import time
+
+from ....graph.labeled_graph import LabeledGraph
+from ....reaction_search import _map_reaction_with_search
+from ...slap.lap import chemical_distance
+from ..hydrogen import enumerate_minimal_hydrogen_transfers
+from .candidates import NativeEnumerationStop
+from .search import enumerate_cpp_mappings
+
+
+# Each unsupported hydrogen state needs a distinct, stable fallback reason.
+def _quotient_graph(graph):  # noqa: C901
+    """Return a cost-preserving reduced graph and original-index H groups."""
+    hydrogen = [i for i, label in enumerate(graph.labels) if label[0] == 1]
+    if not hydrogen:
+        return None, "no_hydrogen_reduction"
+    if any(graph.labels[i] != (1, 0) for i in hydrogen):
+        return None, "isotopic_hydrogen"
+    if any(graph.props["stereo"]) or any(graph.props["_stereo_anchor"]):
+        return None, "annotated_stereochemistry"
+    hydrogen_set = set(hydrogen)
+    heavy = [i for i in range(len(graph.labels)) if i not in hydrogen_set]
+    positions = {atom: i for i, atom in enumerate(heavy)}
+    groups = [[] for _ in heavy]
+    reservoir = []
+    for atom in hydrogen:
+        if graph.props["dummy"][atom]:
+            if graph.graph[atom]:
+                return None, "bonded_hydrogen_placeholder"
+            reservoir.append(atom)
+            continue
+        if graph.props["charge"][atom] or graph.props["radical"][atom]:
+            return None, "nonneutral_or_radical_hydrogen"
+        neighbors = graph.graph[atom]
+        if len(neighbors) != 1:
+            return None, "nonterminal_hydrogen"
+        parent, weight = next(iter(neighbors.items()))
+        if weight != 1 or parent not in positions or graph.labels[parent][0] == 0:
+            return None, "nonordinary_hydrogen_bond"
+        groups[positions[parent]].append(atom)
+    labels = [graph.labels[i] for i in heavy]
+    h_anchor = len(labels)
+    labels.append((0, -2))
+    adjacency = {
+        positions[i]: {positions[j]: weight for j, weight in graph.graph[i].items()
+                       if j in positions}
+        for i in heavy
+    }
+    adjacency[h_anchor] = {}
+    for i, children in enumerate(groups):
+        if children:
+            adjacency[i][h_anchor] = adjacency[h_anchor][i] = len(children)
+    levels = {0} | {value for neighbors in adjacency.values() for value in neighbors.values()}
+    if len(levels) > 16:
+        return None, "quotient_bond_level_limit"
+    reduced = LabeledGraph(adjacency, labels)
+    for name in ("charge", "radical", "hcount", "stereo", "dummy", "_stereo_anchor"):
+        values = graph.props[name]
+        reduced.props[name] = [values[i] for i in heavy] + [
+            True if name == "dummy" else "" if name == "stereo" else 0
+        ]
+    return (reduced, heavy, groups, reservoir), None
+
+
+# Quotient search and explicit-H fallback must share the remaining deadline.
+def map_reaction_hydrogen_quotient(  # noqa: C901
+    reaction,
+    *,
+    library_path,
+    CD="minimal",
+    CD_mode="exact",
+    balance="strict",
+    time_limit_seconds=10.0,
+    max_mappings=100_000,
+    max_bijections=None,
+    max_hydrogen_plans=10_000,
+    classification_max_search_nodes=100_000,
+):
+    """Map all minimum Lewis classes through a checked H-leaf quotient.
+
+    Full graph electron-anchor weights are retained verbatim, so heavy-atom
+    nonbonding electrons are never re-estimated after hydrogens are removed.
+    Unsupported inputs and numeric CD queries use the full explicit-H engine.
+    Assignment-space cardinality and its optional admission cap concern the
+    reduced problem; full labeled multiplicities remain explicitly unknown.
+    """
+
+    # Some RDKit stereo classes have no CIP label. Preserve the full search
+    # contract by declining reduction for every explicit chiral annotation.
+    raw_stereo = False
+    if isinstance(reaction, str) and ("@" in reaction or "|" in reaction):
+        raw_stereo = True
+
+    def search(graphs, **options):
+        elapsed_start = time.perf_counter()
+        seconds = options["time_limit_seconds"]
+        deadline = None if seconds is None else elapsed_start + seconds
+        options.pop("backend")
+        if options["CD"] != "minimal":
+            result = enumerate_cpp_mappings(graphs, **options)
+            statistics = dict(result.backend_statistics or {})
+            statistics["hydrogen_quotient_fallback"] = "numeric_distance_query"
+            return replace(result, backend_statistics=statistics)
+        prepared = [_quotient_graph(graph) for graph in graphs]
+        failure = next((reason for _, reason in prepared if reason), None)
+        if raw_stereo:
+            failure = "annotated_stereochemistry"
+        if failure:
+            options["time_limit_seconds"] = (
+                None if deadline is None else max(0, deadline - time.perf_counter())
+            )
+            result = enumerate_cpp_mappings(graphs, **options)
+            statistics = dict(result.backend_statistics or {})
+            statistics["hydrogen_quotient_fallback"] = failure
+            return replace(result, backend_statistics=statistics)
+        left, right = [value for value, _ in prepared]
+        reduced = left[0], right[0]
+        callback = options["mapping_callback"]
+        observed = plans_observed = 0
+
+        def remaining():
+            return None if deadline is None else max(0, deadline - time.perf_counter())
+
+        def lift(mapping, cost):
+            nonlocal observed, plans_observed
+            original_mapping = [-1] * len(graphs[0].labels)
+            left_heavy, right_heavy = left[1], right[1]
+            for i, atom in enumerate(left_heavy):
+                original_mapping[atom] = right_heavy[mapping[i]]
+            reactant_groups = [list(group) for group in left[2]] + [list(left[3])]
+            product_groups = [list(right[2][mapping[i]]) for i in range(len(left_heavy))]
+            product_groups.append(list(right[3]))
+            rcounts = [len(group) for group in reactant_groups]
+            pcounts = [len(group) for group in product_groups]
+            plans = enumerate_minimal_hydrogen_transfers(
+                rcounts, pcounts, range(len(rcounts)), max_plans=max_hydrogen_plans,
+                time_limit_seconds=remaining(),
+            )
+            for plan in plans.plans:
+                if deadline is not None and time.perf_counter() >= deadline:
+                    raise NativeEnumerationStop("hydrogen_quotient:time_limit")
+                source = [list(group) for group in reactant_groups]
+                target = [list(group) for group in product_groups]
+                lifted = list(original_mapping)
+
+                def transfer(i, j, count):
+                    for atom, image in zip(source[i][:count], target[j][:count]):
+                        lifted[atom] = image
+                    del source[i][:count]
+                    del target[j][:count]
+
+                for i, count in enumerate(plan.preserved):
+                    transfer(i, i, count)
+                for i, j, count in plan.transfers:
+                    transfer(i, j, count)
+                if sorted(lifted) != list(range(len(lifted))):
+                    raise RuntimeError("H quotient did not lift a compatible bijection")
+                if chemical_distance(graphs, lifted, False) != cost:
+                    raise RuntimeError("H quotient cost differs from full Lewis cost")
+                observed += 1
+                callback(lifted, cost)
+                if options["max_mappings"] is not None and observed >= options["max_mappings"]:
+                    raise NativeEnumerationStop("mapping_limit")
+            plans_observed += plans.observed_plan_count
+            if not plans.complete:
+                raise NativeEnumerationStop("hydrogen_quotient:" + plans.truncation_reason)
+
+        query = dict(options)
+        query.update(
+            mapping_callback=lift, collect_mappings=False, time_limit_seconds=remaining()
+        )
+        result = enumerate_cpp_mappings(reduced, **query)
+        statistics = dict(result.backend_statistics or {})
+        statistics.update(
+            hydrogen_quotient=True, full_nodes=len(graphs[0].labels),
+            quotient_nodes=len(reduced[0].labels), hydrogen_transport_plans=plans_observed,
+            mapping_count_scope="lifted_hydrogen_transport_candidates",
+        )
+        return replace(
+            result, selected_mapping_count=observed,
+            selected_labeled_mapping_count=None,
+            scope="full_lewis_minimum_via_terminal_hydrogen_quotient",
+            backend_statistics=statistics,
+        )
+
+    return _map_reaction_with_search(
+        reaction, search_function=search, backend="cpp", library_path=library_path,
+        CD=CD, CD_mode=CD_mode, objective="lewis", hydrogen="explicit", balance=balance,
+        time_limit_seconds=time_limit_seconds, max_mappings=max_mappings,
+        max_bijections=max_bijections, max_hydrogen_plans=max_hydrogen_plans,
+        classification_max_search_nodes=classification_max_search_nodes,
+    )
+
+
+__all__ = ["map_reaction_hydrogen_quotient"]