synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Mapper/validation/annotations.py

@@ -0,0 +1,274 @@
+"""Secondary label metrics, structural classes and shared annotation policies.
+
+Inputs must retain complete joint labels, not merely one representative per
+changed-bond set. Reference annotations are revealed only to this evaluation
+stage; they are never used to generate predictions or candidate sets.
+"""
+
+import json
+from numbers import Integral
+
+from .bonds import IncompleteSymmetry, ScoreWitness, bond_f1
+from .identifiability import extract_label
+from .orbits import SupportOrbitEvaluator
+from ..solvers.slap.lap import _adjacency_and_elements
+from ..reporting.spectrum import exact_its_and_template_codes
+
+
+def features(label, kind):
+    if kind == "bond":
+        return frozenset(("bond", i, j) for i, j in label.changed_bonds)
+    if kind == "atom":
+        return frozenset(("atom", i) for i in label.centre_atoms)
+    if kind == "typed":
+        return frozenset(("bond", *edit) for edit in label.typed_bond_edits)
+    if kind == "joint":
+        return features(label, "typed") | frozenset(
+            ("unary", *edit) for edit in label.unary_changes
+        )
+    raise ValueError("Unknown label kind")
+
+
+class FeatureOrbitEvaluator(SupportOrbitEvaluator):
+    """The same exact support action on typed bonds, unary edits or atom sets."""
+
+    def __init__(self, reactant, *, exact_match=False, **limits):
+        super().__init__(reactant, **limits)
+        self.exact_match = exact_match
+
+    def _validate(self, label):
+        label = frozenset(tuple(item) for item in label)
+        for item in label:
+            if not item or item[0] not in {"atom", "bond", "unary"}:
+                raise ValueError("Unknown feature token")
+            if item[0] == "atom" and len(item) == 2:
+                indices = item[1:2]
+            elif item[0] == "bond" and len(item) in (3, 5):
+                indices = item[1:3]
+                if not item[1] < item[2]:
+                    raise ValueError("Bond coordinates must be ordered")
+                if len(item) == 5 and (
+                    any(not isinstance(x, Integral) for x in item[3:])
+                    or item[3] == item[4]
+                ):
+                    raise ValueError(
+                        "Typed edits need distinct integer before/after orders"
+                    )
+            elif item[0] == "unary" and len(item) == 5:
+                indices = item[1:2]
+                if item[2] not in {"charges", "hcounts"} or any(
+                    not isinstance(x, Integral) for x in item[3:]
+                ):
+                    raise ValueError("Unsupported unary edit")
+            else:
+                raise ValueError("Invalid feature shape")
+            if any(not isinstance(i, Integral) or not 0 <= i < self.n for i in indices):
+                raise ValueError("Out-of-range feature coordinate")
+        return label
+
+    def _support(self, label):
+        return tuple(
+            sorted({i for x in label for i in (x[1:3] if x[0] == "bond" else x[1:2])})
+        )
+
+    def _transport(self, label, permutation):
+        result = []
+        for item in label:
+            if item[0] == "bond":
+                i, j = sorted((permutation[item[1]], permutation[item[2]]))
+                result.append(("bond", i, j, *item[3:]))
+            else:
+                result.append((item[0], permutation[item[1]], *item[2:]))
+        return frozenset(result)
+
+    def score(self, prediction, label):
+        prediction = self._validate(prediction)
+        best = None
+        for image, witness in self.orbit(label).items():
+            self._check()
+            value = (
+                int(prediction == image)
+                if self.exact_match
+                else bond_f1(prediction, image)
+            )
+            if best is None or value > best.score:
+                best = ScoreWitness(value, witness)
+        return best
+
+
+def _witness(value):
+    return {
+        "difference": str(value.difference),
+        "label": sorted(value.label),
+        "a_score": str(value.a.score),
+        "b_score": str(value.b.score),
+        "a_transporter": value.a.transporter,
+        "b_transporter": value.b.transporter,
+    }
+
+
+def analyze_annotations(  # noqa: C901
+    reactant,
+    product,
+    candidate_mappings,
+    prediction_a,
+    prediction_b,
+    *,
+    joint_labels_complete,
+    minimum,
+    reference_mapping=None,
+    metric_seconds=10,
+    canonical_seconds=0.25,
+    template_radius=1,
+):
+    """Evaluate complete joint witnesses with independently reported stages.
+
+    Canonical full ITS codes choose a deterministic class convention. Policies
+    nearest to A/B use primary bond F1 with that canonical code as tie-break;
+    every method is evaluated against the resulting *shared* label. These
+    conventions are diagnostics, not chemical ground truth.
+    """
+    if not joint_labels_complete:
+        raise ValueError("Secondary evaluation requires complete joint labels")
+    mappings = [tuple(m) for m in candidate_mappings]
+    if not mappings:
+        raise ValueError("A nonempty candidate set is required")
+    labels = [extract_label(reactant, product, m) for m in mappings]
+    if any(x.weighted_distance != minimum for x in labels):
+        raise ValueError(
+            "Candidate objective does not match the declared weighted minimum"
+        )
+    pa = extract_label(reactant, product, prediction_a)
+    pb = extract_label(reactant, product, prediction_b)
+    reference = (
+        None
+        if reference_mapping is None
+        else extract_label(reactant, product, reference_mapping)
+    )
+    output = {"status": "evaluated", "metrics": {}, "reference": {}, "policies": {}}
+    if reference is not None:
+        output["reference"] = {
+            "weighted_distance": str(reference.weighted_distance),
+            "mapping_in_minimum": reference.weighted_distance == minimum,
+        }
+    primary_scores, primary_keys = None, None
+    for name, kind, exact in (
+        ("bond_f1", "bond", False),
+        ("atom_f1", "atom", False),
+        ("typed_f1", "typed", False),
+        ("bond_exact", "bond", True),
+        ("joint_exact", "joint", True),
+    ):
+        try:
+            scorer = FeatureOrbitEvaluator(
+                reactant, exact_match=exact, time_limit_seconds=metric_seconds
+            )
+            candidates = [features(x, kind) for x in labels]
+            a, b = features(pa, kind), features(pb, kind)
+            lo, hi = scorer.paired_envelope(a, b, candidates, labels_complete=True)
+            keys = [scorer.orbit_key(x) for x in candidates]
+            values = [
+                (scorer.score(a, x).score, scorer.score(b, x).score) for x in candidates
+            ]
+            record = {
+                "status": "complete",
+                "lower": _witness(lo),
+                "upper": _witness(hi),
+                "width": str(hi.difference - lo.difference),
+                "fixed_labels": len(set(candidates)),
+                "label_orbits": len(set(keys)),
+            }
+            output["metrics"][name] = record
+            if name == "bond_f1":
+                primary_scores, primary_keys = values, keys
+            if reference is not None:
+                try:
+                    ref = features(reference, kind)
+                    membership = scorer.orbit_key(ref) in set(keys)
+                    ref_scores = {
+                        "a": str(scorer.score(a, ref).score),
+                        "b": str(scorer.score(b, ref).score),
+                    }
+                    record.update(
+                        reference_status="complete",
+                        reference_orbit_in_minimum=membership,
+                        reference_scores=ref_scores,
+                    )
+                except IncompleteSymmetry as exc:
+                    record.update(
+                        reference_status="unresolved", reference_reason=str(exc)
+                    )
+        except IncompleteSymmetry as exc:
+            output["metrics"][name] = {"status": "unresolved", "reason": str(exc)}
+    rmatrix, elements = _adjacency_and_elements(reactant.graph(), False)
+    pmatrix, _ = _adjacency_and_elements(product.graph(), False)
+    properties = {
+        name: (getattr(reactant, name), getattr(product, name))
+        for name in ("charges", "hcounts")
+    }
+    codes = []
+    for mapping in mappings:
+        full, template, reason = exact_its_and_template_codes(
+            rmatrix,
+            pmatrix,
+            elements,
+            properties,
+            mapping,
+            template_radius=template_radius,
+            timeout_seconds=canonical_seconds,
+        )
+        if reason is not None:
+            output["structure"] = {"status": "unresolved", "reason": reason}
+            break
+        codes.append(
+            (
+                json.dumps(full, separators=(",", ":")),
+                json.dumps(template, separators=(",", ":")),
+            )
+        )
+    else:
+        output["structure"] = {
+            "status": "complete",
+            "its_classes": len({x[0] for x in codes}),
+            "template_classes": len({x[1] for x in codes}),
+            "template_radius": template_radius,
+            "codes": [
+                {"mapping": m, "its_code": code[0], "template_code": code[1]}
+                for m, code in zip(mappings, codes)
+            ],
+        }
+        joint = output["metrics"]["joint_exact"]
+        if (
+            joint["status"] == "complete"
+            and joint["label_orbits"] != output["structure"]["its_classes"]
+        ):
+            raise ValueError("Full ITS and joint-label orbit counts disagree")
+        if primary_scores is not None:
+            code_labels = {}
+            for code, key in zip(codes, primary_keys):
+                if code[0] in code_labels and code_labels[code[0]] != key:
+                    raise ValueError(
+                        "One ITS class induced multiple primary bond orbits"
+                    )
+                code_labels[code[0]] = key
+            choices = {
+                "canonical_its": min(range(len(codes)), key=lambda i: codes[i][0]),
+                "nearest_a": min(
+                    range(len(codes)),
+                    key=lambda i: (-primary_scores[i][0], codes[i][0]),
+                ),
+                "nearest_b": min(
+                    range(len(codes)),
+                    key=lambda i: (-primary_scores[i][1], codes[i][0]),
+                ),
+            }
+            for name, index in choices.items():
+                a, b = primary_scores[index]
+                output["policies"][name] = {
+                    "mapping": mappings[index],
+                    "its_code": codes[index][0],
+                    "a_score": str(a),
+                    "b_score": str(b),
+                    "difference": str(a - b),
+                }
+    return output

synkit/Chem/Mapper/validation/bonds.py

@@ -0,0 +1,124 @@
+"""Exact, shared-label changed-bond evaluation on fully resolved inputs.
+
+The exhaustive full-reactant symmetry route is a bounded development oracle.
+It raises on incomplete symmetry rather than silently reporting exact scores.
+Production callers must also establish minimum and label-enumeration closure.
+"""
+
+from dataclasses import dataclass
+from fractions import Fraction
+from time import monotonic
+
+import networkx as nx
+
+from .identifiability import Endpoint
+
+
+class IncompleteSymmetry(RuntimeError):
+    """The full attributed automorphism group was not established."""
+
+
+def _graph(endpoint):
+    graph = nx.Graph()
+    for i, z in enumerate(endpoint.atomic_numbers):
+        graph.add_node(i, color=(z, endpoint.charges[i], endpoint.hcounts[i]))
+    for i, j, order in endpoint.bonds:
+        graph.add_edge(i, j, order=order)
+    return graph
+
+
+def full_automorphisms(endpoint: Endpoint, *, max_automorphisms=100000,
+                       time_limit_seconds=30):
+    """Enumerate all symmetries, preserving elements, charges, H and orders.
+
+    The time check is cooperative between matcher yields; a campaign runner
+    still needs an external process deadline. Component roles are not supported
+    by this contract and must not be claimed as preserved attributes.
+    """
+    if max_automorphisms < 1 or time_limit_seconds <= 0:
+        raise ValueError("Symmetry limits must be positive")
+    graph = _graph(endpoint)
+    matcher = nx.algorithms.isomorphism.GraphMatcher(
+        graph, graph,
+        node_match=nx.algorithms.isomorphism.categorical_node_match("color", None),
+        edge_match=nx.algorithms.isomorphism.categorical_edge_match("order", None),
+    )
+    start = monotonic()
+    permutations = []
+    for mapping in matcher.isomorphisms_iter():
+        if monotonic() - start > time_limit_seconds:
+            raise IncompleteSymmetry("Automorphism deadline exceeded")
+        if len(permutations) >= max_automorphisms:
+            raise IncompleteSymmetry("Automorphism output cap exceeded")
+        permutations.append(tuple(mapping[i] for i in range(len(graph))))
+    if monotonic() - start > time_limit_seconds:
+        raise IncompleteSymmetry("Automorphism deadline exceeded")
+    return tuple(sorted(permutations))
+
+
+def bond_f1(prediction, label):
+    prediction, label = frozenset(prediction), frozenset(label)
+    denominator = len(prediction) + len(label)
+    return Fraction(2 * len(prediction & label), denominator) if denominator else Fraction(1)
+
+
+def transport_bonds(label, permutation):
+    return frozenset(tuple(sorted((permutation[i], permutation[j]))) for i, j in label)
+
+
+@dataclass(frozen=True)
+class ScoreWitness:
+    score: Fraction
+    transporter: tuple[int, ...]
+
+
+class ExactBondEvaluator:
+    """Scorer bound to one endpoint and its completely enumerated symmetry."""
+
+    def __init__(self, reactant: Endpoint, **symmetry_limits):
+        self.n = len(reactant.atomic_numbers)
+        self.automorphisms = full_automorphisms(reactant, **symmetry_limits)
+
+    def _validate(self, bonds):
+        bonds = frozenset(bonds)
+        if any(len(pair) != 2 or not 0 <= pair[0] < pair[1] < self.n for pair in bonds):
+            raise ValueError("Bond labels require canonical in-range unordered pairs")
+        return bonds
+
+    def score(self, prediction, label):
+        prediction, label = self._validate(prediction), self._validate(label)
+        best = None
+        for permutation in self.automorphisms:
+            score = bond_f1(prediction, transport_bonds(label, permutation))
+            if best is None or score > best.score:
+                best = ScoreWitness(score, permutation)
+        return best
+
+    def orbit_key(self, label):
+        label = self._validate(label)
+        return min(tuple(sorted(transport_bonds(label, p))) for p in self.automorphisms)
+
+    def paired_envelope(self, prediction_a, prediction_b, labels, *, labels_complete):
+        """Return attained min/max differences with shared candidate witnesses.
+
+        ``labels_complete`` is an explicit caller obligation, not a proof
+        generated by the scorer. An incomplete set is refused by this API.
+        """
+        if not labels_complete:
+            raise ValueError("Exact envelopes require complete admitted labels")
+        values = []
+        for label in labels:
+            label = self._validate(label)
+            a, b = self.score(prediction_a, label), self.score(prediction_b, label)
+            values.append(PairedWitness(a.score - b.score, label, a, b))
+        if not values:
+            raise ValueError("At least one admitted label is required")
+        return min(values, key=lambda x: x.difference), max(values, key=lambda x: x.difference)
+
+
+@dataclass(frozen=True)
+class PairedWitness:
+    difference: Fraction
+    label: frozenset[tuple[int, int]]
+    a: ScoreWitness
+    b: ScoreWitness

synkit/Chem/Mapper/validation/cohorts.py

@@ -0,0 +1,72 @@
+"""Separate intrinsic label sensitivity from unresolved computation.
+
+Each case's paired F1 difference is in [-1,1]. Weights and scores are exact
+rationals; these are identification bounds, not sampling confidence intervals.
+"""
+
+from dataclasses import dataclass
+from fractions import Fraction
+
+
+def rational(value):
+    if isinstance(value, bool) or not isinstance(value, (int, str, Fraction)):
+        raise TypeError("Use an integer, Fraction or rational string, not a float")
+    return Fraction(value)
+
+
+@dataclass(frozen=True)
+class CohortBounds:
+    unresolved_weight: Fraction
+    outer_lower: Fraction
+    outer_upper: Fraction
+    width_lower: Fraction
+    width_upper: Fraction
+    conditional_lower: Fraction | None
+    conditional_upper: Fraction | None
+    lower_witness_assignment_upper: Fraction
+    upper_witness_assignment_lower: Fraction
+    robust_a: bool
+    robust_b: bool
+    guaranteed_substantive_reversal: bool
+    exact: bool
+
+
+def paired_cohort_bounds(intervals, *, weights=None, margin=Fraction(1, 50)):
+    """Bound a fixed common-valid cohort; ``None`` means unresolved.
+
+    Resolved intervals must be attained shared-label extrema. For a global
+    coupled annotation policy these sums need not be attainable; the function
+    assumes casewise label choices are independent. Invalid predictions must
+    be handled before calling, by an explicit cohort or operational policy.
+    """
+    intervals = list(intervals)
+    if not intervals:
+        raise ValueError("A nonempty comparison cohort is required")
+    weights = ([Fraction(1, len(intervals))] * len(intervals) if weights is None
+               else [rational(x) for x in weights])
+    if len(weights) != len(intervals) or any(w < 0 for w in weights) or sum(weights) != 1:
+        raise ValueError("Weights must be nonnegative, aligned and sum to one")
+    margin = rational(margin)
+    if not 0 <= margin <= 1:
+        raise ValueError("Margin must lie in [0,1]")
+    lower, upper, unknown = Fraction(), Fraction(), Fraction()
+    for interval, weight in zip(intervals, weights):
+        if interval is None:
+            unknown += weight
+        else:
+            lo, hi = map(rational, interval)
+            if not -1 <= lo <= hi <= 1:
+                raise ValueError("Invalid paired score interval")
+            lower += weight * lo
+            upper += weight * hi
+    resolved_weight = 1-unknown
+    outer_lo, outer_hi = lower-unknown, upper+unknown
+    return CohortBounds(
+        unknown, outer_lo, outer_hi, upper-lower, upper-lower+2*unknown,
+        lower/resolved_weight if resolved_weight else None,
+        upper/resolved_weight if resolved_weight else None,
+        lower+unknown, upper-unknown,
+        outer_lo > margin, outer_hi < -margin,
+        lower+unknown < -margin and upper-unknown > margin,
+        unknown == 0,
+    )

synkit/Chem/Mapper/validation/identifiability.py

@@ -0,0 +1,150 @@
+"""Strict heavy-atom endpoints and joint reaction labels for evaluation.
+
+This study interface deliberately does not balance, repair, or discard atoms.
+Stereochemistry is outside its connectivity-only contract; isotope inputs and
+hydrogens that cannot be folded into heavy atoms are rejected.
+"""
+
+from collections import Counter
+from dataclasses import dataclass
+from fractions import Fraction
+from itertools import combinations
+from numbers import Integral
+
+from rdkit import Chem
+
+from ..graph.labeled_graph import LabeledGraph
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    atomic_numbers: tuple[int, ...]
+    charges: tuple[int, ...]
+    hcounts: tuple[int, ...]
+    # Bond orders are represented as exact twice-order integers.
+    bonds: tuple[tuple[int, int, int], ...]
+
+    def __post_init__(self):
+        n = len(self.atomic_numbers)
+        if len(self.charges) != n or len(self.hcounts) != n:
+            raise ValueError("Endpoint property lengths differ")
+        if not n or any(z <= 1 for z in self.atomic_numbers):
+            raise ValueError("A nonempty heavy-atom inventory is required")
+        if any(not isinstance(x, Integral) for values in
+               (self.atomic_numbers, self.charges, self.hcounts) for x in values):
+            raise ValueError("Atom properties must be integers")
+        if any(h < 0 for h in self.hcounts):
+            raise ValueError("Hydrogen counts must be nonnegative")
+        pairs = set()
+        for i, j, order in self.bonds:
+            if not all(isinstance(x, Integral) for x in (i, j, order)):
+                raise ValueError("Bond records must use integers")
+            if not 0 <= i < j < n or order not in (2, 3, 4, 6):
+                raise ValueError("Unsupported bond coordinate or order")
+            if (i, j) in pairs:
+                raise ValueError("Duplicate bond")
+            pairs.add((i, j))
+
+    def graph(self):
+        adjacency = {i: {} for i in range(len(self.atomic_numbers))}
+        for i, j, order in self.bonds:
+            adjacency[i][j] = adjacency[j][i] = order / 2
+        result = LabeledGraph(adjacency, self.atomic_numbers)
+        for name, values in (("atomic numbers", self.atomic_numbers),
+                             ("charges", self.charges), ("hcounts", self.hcounts)):
+            result.set_prop(name, list(values))
+        return result
+
+
+def parse_endpoint(smiles: str) -> Endpoint:
+    """Parse every component, discard map labels, fold ordinary explicit H.
+
+    Coordinates follow RDKit's retained heavy-atom order, not atom-map numbers.
+    The caller must save the exact input string with exported labels.
+    """
+    params = Chem.SmilesParserParams()
+    params.removeHs = False
+    mol = Chem.MolFromSmiles(smiles, params)
+    if mol is None:
+        raise ValueError("Invalid endpoint SMILES")
+    for atom in mol.GetAtoms():
+        if atom.GetIsotope():
+            raise ValueError("Isotope-specific endpoints are unsupported")
+        if atom.GetNumRadicalElectrons():
+            raise ValueError("Radical endpoints are unsupported")
+        atom.SetAtomMapNum(0)
+    mol = Chem.RemoveHs(mol)
+    bonds = []
+    for bond in mol.GetBonds():
+        order = 2 * bond.GetBondTypeAsDouble()
+        if order not in (2, 3, 4, 6):
+            raise ValueError("Unsupported bond type")
+        i, j = sorted((bond.GetBeginAtomIdx(), bond.GetEndAtomIdx()))
+        bonds.append((i, j, int(order)))
+    return Endpoint(
+        tuple(a.GetAtomicNum() for a in mol.GetAtoms()),
+        tuple(a.GetFormalCharge() for a in mol.GetAtoms()),
+        tuple(a.GetTotalNumHs() for a in mol.GetAtoms()),
+        tuple(sorted(bonds)),
+    )
+
+
+def parse_reaction(reaction: str) -> tuple[Endpoint, Endpoint]:
+    """Accept balanced ``reactants>>products`` without a hidden agent policy."""
+    fields = reaction.split(">")
+    if len(fields) != 3 or fields[1]:
+        raise ValueError("Expected reactants>>products with no agent field")
+    reactant, product = map(parse_endpoint, (fields[0], fields[2]))
+    if Counter(reactant.atomic_numbers) != Counter(product.atomic_numbers):
+        raise ValueError("Heavy-atom inventories are not element balanced")
+    return reactant, product
+
+
+@dataclass(frozen=True)
+class JointLabel:
+    typed_bond_edits: tuple[tuple[int, int, int, int], ...]
+    unary_changes: tuple[tuple[int, str, int, int], ...]
+
+    @property
+    def changed_bonds(self):
+        return frozenset((i, j) for i, j, _, _ in self.typed_bond_edits)
+
+    @property
+    def centre_atoms(self):
+        return frozenset(
+            [i for pair in self.changed_bonds for i in pair]
+            + [i for i, _, _, _ in self.unary_changes]
+        )
+
+    @property
+    def weighted_distance(self):
+        return Fraction(sum(abs(after - before)
+                            for _, _, before, after in self.typed_bond_edits), 2)
+
+
+def extract_label(reactant: Endpoint, product: Endpoint, mapping) -> JointLabel:
+    """Derive one *joint* label from a complete element-compatible bijection."""
+    mapping = tuple(mapping)
+    n = len(reactant.atomic_numbers)
+    if (len(product.atomic_numbers) != n or len(mapping) != n
+            or any(not isinstance(p, Integral) for p in mapping)
+            or set(mapping) != set(range(n))):
+        raise ValueError("Mapping must be a complete bijection")
+    if any(z != product.atomic_numbers[mapping[i]]
+           for i, z in enumerate(reactant.atomic_numbers)):
+        raise ValueError("Mapping changes an element")
+    rb = {(i, j): order for i, j, order in reactant.bonds}
+    pb = {(i, j): order for i, j, order in product.bonds}
+    edits = []
+    for i, j in combinations(range(n), 2):
+        before = rb.get((i, j), 0)
+        after = pb.get(tuple(sorted((mapping[i], mapping[j]))), 0)
+        if before != after:
+            edits.append((i, j, before, after))
+    unary = []
+    for name in ("charges", "hcounts"):
+        before_values, after_values = getattr(reactant, name), getattr(product, name)
+        for i, p in enumerate(mapping):
+            if before_values[i] != after_values[p]:
+                unary.append((i, name, before_values[i], after_values[p]))
+    return JointLabel(tuple(edits), tuple(sorted(unary)))

synkit/Chem/Mapper/validation/numerical_scope.py

@@ -0,0 +1,36 @@
+"""Declared finite chemical-lattice domain for the identifiability study.
+
+This guard is not a repair of the generic floating-point solver API. The study
+uses undirected loop-free endpoints with doubled orders in {2,3,4,6}, at most
+512 atoms, and exact integer independent witness rescoring. The current Python
+assignment route verifies bounded lattice LAP answers using integer primal--dual
+certificates; its operation-level argument is in the assignment-proof supplement.
+This input guard alone does not certify another execution route or an archived source
+version, and does not broaden the generic floating-point API guarantee.
+"""
+
+MAX_STUDY_ATOMS = 512
+
+
+def validate_study_domain(reactant, product):
+    from collections import Counter
+
+    n = len(reactant.atomic_numbers)
+    if not 1 <= n <= MAX_STUDY_ATOMS or len(product.atomic_numbers) != n:
+        raise ValueError("Study arithmetic domain requires 1–512 balanced heavy atoms")
+    if Counter(reactant.atomic_numbers) != Counter(product.atomic_numbers):
+        raise ValueError("Study endpoints must be element balanced")
+    for endpoint in (reactant, product):
+        endpoint.__post_init__()
+    # 4*value must fit exactly in binary64. This deliberately loose polynomial
+    # envelope is far above the O(n^2) matrix/DFS/profile quantities actually
+    # used; it also leaves headroom for LAP potential/shortest-path updates.
+    scaled_working_envelope = 4 * 64 * n**4
+    if scaled_working_envelope >= 2**53:
+        raise ValueError("Study arithmetic envelope exceeds binary64 integer range")
+    return {"domain": "bounded-half-integer-chemical-v1", "heavy_atoms": n,
+            "max_heavy_atoms": MAX_STUDY_ATOMS,
+            "doubled_orders": [2, 3, 4, 6],
+            "scaled_working_envelope": scaled_working_envelope,
+            "binary64_exact_integer_limit": 2**53,
+            "generic_float_api_certified": False}