synkit 1.6.5__py3-none-win_amd64.whl

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

@@ -0,0 +1,328 @@
+"""Exact weighted accumulation of reactant/product double orbits."""
+
+from collections import Counter
+
+import numpy as np
+
+from ....reporting.spectrum import (
+    ExactStructureSpectrumAccumulator,
+    _attributed_its_graph,
+    _changed_atoms_and_bonds,
+    _template_context,
+)
+from .canonical import (
+    PackedCanonicalKey,
+    compact_code_identifier,
+    native_canonical_code,
+    transport_canonical_key,
+)
+from .its import NativeITSCanonicalizer
+
+
+def coordinate_orbits(n, generators, pairs=False):
+    coordinates = (
+        [(i, j) for i in range(n) for j in range(i + 1, n)] if pairs else list(range(n))
+    )
+    position = {value: i for i, value in enumerate(coordinates)}
+    parent = list(range(len(coordinates)))
+
+    def find(i):
+        while parent[i] != i:
+            parent[i] = parent[parent[i]]
+            i = parent[i]
+        return i
+
+    for generator in generators:
+        for i, value in enumerate(coordinates):
+            image = (
+                tuple(sorted((generator[value[0]], generator[value[1]])))
+                if pairs
+                else generator[value]
+            )
+            left, right = find(i), find(position[image])
+            if left != right:
+                parent[right] = left
+    groups = {}
+    for i, value in enumerate(coordinates):
+        groups.setdefault(find(i), []).append(value)
+    groups = list(groups.values())
+    lookup = {value: i for i, group in enumerate(groups) for value in group}
+    return groups, lookup
+
+
+class _NativeReferenceCache:
+    def __init__(self, accumulator):
+        # Keep only canonicalization inputs. Retaining the accumulator here
+        # creates observer -> cache -> accumulator -> observer cycles containing
+        # the entire completed spectrum.
+        self.transport_keys = accumulator.transport_keys
+        self.library_path = accumulator.library_path
+        self.generators = accumulator.generators
+        self.color_cache = accumulator.color_cache
+        self.calls = 0
+
+    def code(self, graph, *, timeout_seconds, max_search_nodes):
+        self.calls += 1
+        try:
+            value, _ = native_canonical_code(
+                graph,
+                library_path=self.library_path,
+                generators=self.generators,
+                timeout_seconds=timeout_seconds,
+                max_search_nodes=max_search_nodes,
+                _its_color_cache=self.color_cache,
+                compact=True,
+            )
+            key = PackedCanonicalKey(value)
+            return (transport_canonical_key(key) if self.transport_keys else key), None
+        except RuntimeError as error:
+            return None, str(error)
+
+    def statistics(self):
+        return {"native_reference_calls": self.calls}
+
+
+class NativeCompactStructureAccumulator(ExactStructureSpectrumAccumulator):
+    """Keep exact sparse keys in memory and preserve public class identifiers."""
+
+    @staticmethod
+    def _reported_counts(counts):
+        return tuple(
+            sorted(
+                (compact_code_identifier(key), int(count))
+                for key, count in counts.items()
+            )
+        )
+
+
+class OrbitAccumulator:
+    """Weights are |Aut(A)| / |Aut(A) intersect transported Aut(B)|.
+
+    Each ITS canonical key identifies one complete two-sided mapping orbit.
+    Coordinate counts average its indicator over reactant coordinate orbits.
+    All divisions must be integral; a failed group or canonical proof aborts.
+    """
+
+    def __init__(
+        self,
+        observer,
+        generators,
+        reactant_order,
+        product_order,
+        *,
+        library_path,
+        record_only=False,
+        transport_keys=False,
+    ):
+        self.record_only = record_only
+        self.transport_keys = transport_keys
+        self.observer = observer
+        old = observer.structure
+        if not isinstance(old, NativeCompactStructureAccumulator):
+            observer.structure = NativeCompactStructureAccumulator(
+                old.reactant,
+                old.product,
+                old.elements,
+                old.properties,
+                enabled=old.enabled,
+                template_radius=old.template_radius,
+                tolerance=old.tolerance,
+                timeout_seconds=old.timeout_seconds,
+                max_search_nodes=old.max_search_nodes,
+            )
+        self.atom_frequencies = Counter()
+        self.bond_frequencies = Counter()
+        self.generators = generators
+        self.reactant_order = reactant_order
+        self.product_order = product_order
+        self.library_path = library_path
+        self.color_cache = {}
+        self.its_canonicalizer = NativeITSCanonicalizer(
+            observer, generators, library_path
+        )
+        observer.structure._code_cache = _NativeReferenceCache(self)
+        self.seen = {}
+        n = len(observer.reactant)
+        self.atom_orbits, self.atom_lookup = coordinate_orbits(n, generators)
+        self.bond_orbits, self.bond_lookup = coordinate_orbits(
+            n, generators, pairs=True
+        )
+        self.candidates = 0
+        self.duplicates = 0
+        self.pattern_hits = 0
+
+    def canonical(self, graph):
+        return native_canonical_code(
+            graph,
+            library_path=self.library_path,
+            generators=self.generators,
+            timeout_seconds=self.observer.structure.timeout_seconds,
+            max_search_nodes=self.observer.structure.max_search_nodes,
+            compact=True,
+            _its_color_cache=self.color_cache,
+        )
+
+    def observe(self, mapping, cost):
+        self.candidates += 1
+        observer = self.observer
+        transported = (
+            observer.product[np.ix_(mapping, mapping)]
+            if self.its_canonicalizer.changes_function is None
+            else None
+        )
+        paired = self.its_canonicalizer.paired_matrix(mapping)
+        if self.its_canonicalizer.known_pattern(mapping, paired):
+            self.duplicates += 1
+            self.pattern_hits += 1
+            return
+        key, stabilizer = self.its_canonicalizer.canonical(
+            mapping, transported, paired=paired, packed=True
+        )
+        if not isinstance(key, PackedCanonicalKey):
+            key = PackedCanonicalKey(key)
+        if key in self.seen:
+            self.duplicates += 1
+            self.its_canonicalizer.remember_pattern()
+            return
+        self.commit(key, stabilizer, mapping, transported=transported, paired=paired)
+        if not self.record_only:
+            self.its_canonicalizer.remember_pattern()
+
+    def commit(
+        self,
+        key,
+        stabilizer,
+        mapping,
+        template_key=None,
+        *,
+        transported=None,
+        paired=None,
+    ):
+        if key in self.seen:
+            return
+        observer = self.observer
+        if transported is None and self.its_canonicalizer.changes_function is None:
+            transported = observer.product[np.ix_(mapping, mapping)]
+        if (
+            not stabilizer
+            or self.reactant_order % stabilizer
+            or self.product_order % stabilizer
+        ):
+            raise RuntimeError("unproved double-orbit multiplicity")
+        weight = self.reactant_order // stabilizer
+        if paired is None:
+            paired = self.its_canonicalizer.paired_matrix(mapping)
+        changes = self.its_canonicalizer.changes(mapping, paired)
+        if changes is None:
+            changed_atoms, changed_bonds = _changed_atoms_and_bonds(
+                observer.reactant,
+                transported,
+                observer.properties,
+                mapping,
+                observer.tolerance,
+            )
+            context = _template_context(
+                observer.reactant,
+                transported,
+                changed_atoms,
+                observer.structure.template_radius,
+            )
+            atom_changes = [
+                i
+                for i in range(len(mapping))
+                if any(
+                    left[i] != right[mapping[i]]
+                    for left, right in observer.properties.values()
+                )
+            ]
+        else:
+            atom_changes, changed_bonds, context = changes
+        if template_key is None and observer.structure.enabled:
+            template_key, _ = self.its_canonicalizer.canonical(
+                mapping,
+                transported,
+                context,
+                paired=paired,
+                require_group=False,
+                packed=True,
+            )
+            if not isinstance(template_key, PackedCanonicalKey):
+                template_key = PackedCanonicalKey(template_key)
+        atom_totals = Counter(self.atom_lookup[i] for i in atom_changes)
+        bond_totals = Counter(self.bond_lookup[pair] for pair in changed_bonds)
+        atom_updates, bond_updates = {}, {}
+        for totals, orbits, updates in (
+            (atom_totals, self.atom_orbits, atom_updates),
+            (bond_totals, self.bond_orbits, bond_updates),
+        ):
+            for orbit, count in totals.items():
+                increment, remainder = divmod(weight * count, len(orbits[orbit]))
+                if remainder:
+                    raise RuntimeError("nonintegral orbit frequency")
+                updates[orbit] = increment
+        from ....reporting.analysis import _mapping_sha256
+
+        record = (
+            weight,
+            stabilizer,
+            _mapping_sha256(mapping),
+            template_key,
+            tuple(sorted(atom_updates.items())),
+            tuple(sorted(bond_updates.items())),
+        )
+        if self.record_only:
+            self.seen[key] = record
+        else:
+            self.merge_record(key, record)
+
+    def merge_record(self, key, record):
+        """Merge a proved class using precomputed coordinate-orbit totals."""
+        if key in self.seen:
+            return
+        weight, stabilizer, mapping_digest, template_key, atoms, bonds = record
+        if (
+            not stabilizer
+            or self.reactant_order % stabilizer
+            or self.product_order % stabilizer
+            or weight != self.reactant_order // stabilizer
+        ):
+            raise RuntimeError("unproved double-orbit merge weight")
+        self.seen[key] = (weight, stabilizer)
+        observer = self.observer
+        observer.count += weight
+        self.atom_frequencies.update(dict(atoms))
+        self.bond_frequencies.update(dict(bonds))
+        payload = str(weight).encode() + b":" + mapping_digest
+        observer.stream_digest.update(len(payload).to_bytes(8, "little"))
+        observer.stream_digest.update(payload)
+        if observer.structure.enabled:
+            observer.structure.its_counts[key] += weight
+            observer.structure.template_counts[template_key] += weight
+
+    def finish(self):
+        """Expand coordinate-orbit totals once, after exact class deduplication."""
+        self.observer.atom_counts.clear()
+        self.observer.bond_counts.clear()
+        for frequencies, orbits, counts in (
+            (self.atom_frequencies, self.atom_orbits, self.observer.atom_counts),
+            (self.bond_frequencies, self.bond_orbits, self.observer.bond_counts),
+        ):
+            for orbit, value in frequencies.items():
+                for coordinate in orbits[orbit]:
+                    counts[coordinate] = value
+
+    def contains_reference(self, mapping):
+        observer = self.observer
+        transported = observer.product[np.ix_(mapping, mapping)]
+        graph = _attributed_its_graph(
+            observer.reactant,
+            transported,
+            observer.structure.elements,
+            observer.properties,
+            mapping,
+        )
+        key, _ = self.canonical(graph)
+        key = PackedCanonicalKey(key)
+        if self.transport_keys:
+            key = transport_canonical_key(key)
+        return key in self.seen

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

@@ -0,0 +1,205 @@
+"""Bounded parallel enumeration with an exact double-orbit merge."""
+
+import math
+import multiprocessing as mp
+import time
+from concurrent.futures import ProcessPoolExecutor
+
+from .candidates import NativeEnumerationStop, enumerate_native_candidates
+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
+_READY = False
+
+
+class NativeSharedBudget(NativeEnumerationStop):
+    pass
+
+
+def _init_worker(counter, deadline, barrier, cap):
+    global _STATE, _READY
+    _READY = False
+    _STATE = counter, deadline, barrier, cap
+    limit_worker_address_space(resource)
+
+
+def _worker(lgp, target, config, seed, library_path, index, workers, cpu):
+    global _READY
+    from ....reporting.analysis import _BlindShellObserver, _mapping_key, _property_vectors
+    from ....graph.automorphism import bounded_automorphism_permutations
+    from ...slap.lap import _adjacency_and_elements
+    from ..symmetry import permutation_group_order
+
+    pin_worker_cpu(cpu)
+    a, labels = _adjacency_and_elements(lgp[0], config.binary)
+    b, _ = _adjacency_and_elements(lgp[1], config.binary)
+    properties = _property_vectors(lgp, config.reaction_center_properties)
+    observer = _BlindShellObserver(a, b, labels, properties, config)
+    rg, rc = bounded_automorphism_permutations(
+        lgp[0], binary=False, node_properties=config.symmetry_node_properties
+    )
+    pg, pc = bounded_automorphism_permutations(
+        lgp[1], binary=False, node_properties=config.symmetry_node_properties
+    )
+    if not rc or not pc:
+        raise ValueError("parallel orbit search requires complete side groups")
+    accumulator = OrbitAccumulator(
+        observer,
+        rg[1:],
+        permutation_group_order(rg[1:]),
+        permutation_group_order(pg[1:]),
+        library_path=library_path,
+        record_only=True,
+    )
+    counter, deadline, barrier, cap = _STATE
+    if not _READY:
+        barrier.wait(timeout=30)
+        barrier.wait(timeout=30)
+        _READY = True
+
+    def receive(mapping, cost):
+        if time.perf_counter() >= deadline.value:
+            raise NativeSharedBudget("time_limit")
+        observer.mapping_hashes.add(_mapping_key(mapping))
+        before = len(accumulator.seen)
+        accumulator.observe(mapping, cost)
+        if len(accumulator.seen) > before:
+            with counter.get_lock():
+                if cap is not None and counter.value >= cap:
+                    accumulator.seen.popitem()
+                    raise NativeSharedBudget("mapping_limit")
+                counter.value += 1
+
+    result = enumerate_native_candidates(
+        lgp,
+        target,
+        library_path=library_path,
+        time_limit_seconds=max(0, deadline.value - time.perf_counter()),
+        max_mappings=None,
+        initial_mapping=seed,
+        node_properties=config.symmetry_node_properties,
+        callback=receive,
+        shard_index=index,
+        shards=workers,
+    )
+    result = {
+        key: value
+        for key, value in result.items()
+        if key not in {"mappings", "reactant_generators"}
+    }
+    result["retained_classes"] = len(accumulator.seen)
+    return result, accumulator.seen, observer.mapping_hashes
+
+
+def parallel_orbit_search(
+    lgp, target, config, seed, observer, *, library_path, workers=8, shard_count=None
+):
+    from ....graph.automorphism import bounded_automorphism_permutations
+    from ..symmetry import permutation_group_order
+
+    if config.binary or set(config.symmetry_node_properties) != set(
+        config.reaction_center_properties
+    ):
+        raise ValueError(
+            "parallel orbit analysis requires weighted matrices and aligned property sets"
+        )
+    if isinstance(workers, bool) or not isinstance(workers, int) or workers < 1:
+        raise ValueError("workers must be a positive integer")
+    shard_count = workers if shard_count is None else shard_count
+    if not isinstance(shard_count, int) or shard_count < workers:
+        raise ValueError("shard_count must be at least workers")
+    if (
+        config.time_limit_seconds is None
+        or not math.isfinite(config.time_limit_seconds)
+        or config.time_limit_seconds < 0
+    ):
+        raise ValueError("parallel orbit analysis requires a finite time budget")
+    rg, rc = bounded_automorphism_permutations(
+        lgp[0], binary=False, node_properties=config.symmetry_node_properties
+    )
+    pg, pc = bounded_automorphism_permutations(
+        lgp[1], binary=False, node_properties=config.symmetry_node_properties
+    )
+    if not rc or not pc:
+        raise ValueError("parallel orbit search requires complete side groups")
+    merged = OrbitAccumulator(
+        observer,
+        rg[1:],
+        permutation_group_order(rg[1:]),
+        permutation_group_order(pg[1:]),
+        library_path=library_path,
+    )
+    context = mp.get_context("spawn")
+    counter = context.Value("q", 0)
+    deadline = context.Value("d", 0)
+    barrier = context.Barrier(workers + 1)
+    cpus = worker_cpus(workers)
+    started = time.perf_counter()
+    results = []
+    # One complete representative per class survives the exact-key union.
+    records = {}
+    with ProcessPoolExecutor(
+        max_workers=workers,
+        mp_context=context,
+        initializer=_init_worker,
+        initargs=(counter, deadline, barrier, config.max_mappings),
+    ) as pool:
+        futures = [
+            pool.submit(
+                _worker,
+                lgp,
+                target,
+                config,
+                seed,
+                str(library_path),
+                i,
+                shard_count,
+                cpus[i % len(cpus)] if cpus else None,
+            )
+            for i in range(shard_count)
+        ]
+        barrier.wait(timeout=30)
+        deadline.value = time.perf_counter() + config.time_limit_seconds
+        search_started = time.perf_counter()
+        barrier.wait(timeout=30)
+        for future in futures:
+            result, found, hashes = future.result()
+            observer.mapping_hashes.update(hashes)
+            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 double-orbit records across shards"
+                    )
+                records.setdefault(key, value)
+    search_and_transfer_seconds = time.perf_counter() - search_started
+    for key, record in records.items():
+        merged.merge_record(key, record)
+    merged.finish()
+    within_deadline = time.perf_counter() <= deadline.value
+    reasons = {result["reason"] for result in results if result.get("reason")}
+    if not within_deadline:
+        reasons.add("time_limit")
+    return {
+        "complete": all(result["complete"] for result in results) and within_deadline,
+        "reasons": sorted(reasons),
+        "timed_phase_seconds": time.perf_counter() - search_started,
+        "retained_worker_records": counter.value,
+        "candidate_count": sum(result["candidate_count"] for result in results),
+        "mapping_limit_scope": "retained_worker_double_orbit_representatives",
+        "workers": workers,
+        "shard_count": shard_count,
+        "shards": results,
+        "unique_classes": len(records),
+        "weighted_product_representatives": observer.count,
+        "labeled_mappings": observer.count * merged.product_order,
+        "elapsed_seconds": time.perf_counter() - started,
+        "search_and_transfer_seconds": search_and_transfer_seconds,
+    }, merged