unicode-logic-kit 0.31.0__py3-none-any.whl

unicode_logic_kit/atp/z3_models.py

@@ -0,0 +1,208 @@
+"""Satisfiability / validity checks and model (counterexample) extraction via Z3.
+
+**Many-sorted (MSFOL) soundness.** ``Node.to_z3()`` relativises a sorted
+quantifier/constant/count to plain classical FOL (``fol.nodes.to_fol``,
+auto-run by ``SortedQuantifier.to_z3`` etc.) but that relativisation alone
+does NOT guarantee a sort's universe is non-empty — and MSFOL, by
+convention, never gives a sort an empty one (see the classical-reasoning
+guide's many-sorted section). Left unaddressed, Z3 is free to interpret a
+sort predicate as always-false, which can turn a genuinely valid many-sorted
+formula invalid (or a genuinely unsatisfiable one satisfiable) via a
+spurious empty-sort "model" no legal MSFOL structure would ever be. The
+relativisation likewise reads a sorted constant ``c:S`` as the plain constant
+``c``, so it forgets that ``c`` lies in ``S``: ``∀x:Human Mortal(x)`` would
+not entail ``Mortal(socrates:Human)``, because ``socrates`` could be outside
+``Human``. Every function below closes both gaps the same way: it collects
+``unicode_logic_kit.fol._msfl_nodes.sort_axioms(formula)`` — one ``∃x S(x)`` per
+sort and one ``S(c)`` per sorted constant — and adds them as their own extra,
+UNCONDITIONAL, never-negated assertions on the solver — never folded inside
+``to_z3()`` itself, which is polarity-blind and shared with every OTHER caller
+(see that function's docstring for why). For an unsorted formula the axiom
+list is empty, so the Z3 query — and every one of these functions' return
+values — is unchanged by it.
+"""
+
+from collections import Counter
+from typing import Callable, Dict, List, Optional, Sequence, Tuple
+
+from ..fol._fol_nodes import kit_name_of_z3_symbol, z3_variable_name
+from ..fol._msfl_nodes import sort_axioms
+from ..fol.nodes import Node, Z3Env
+from z3 import Solver, sat, unsat, Not
+
+
+def declaration_keys(entries: Sequence[Tuple[str, int, str]]) -> List[str]:
+    """One key per declaration of a model, ``(name, arity, range)`` each.
+
+    A name that only one declaration carries is its own key, so a model of
+    ``P(a)`` still reads ``{"P": ..., "a": ...}``. When several declarations
+    share a name (``P(a)`` next to ``P(a, b)``, a function ``f`` next to a
+    predicate ``f``, a proposition ``a`` next to a constant ``a``) each is keyed
+    by its name and arity, ``"P/1"`` and ``"P/2"``, and when a name and an arity
+    still do not tell two apart (a predicate and a function of one name and
+    arity) by the sort the declaration returns as well, ``"P/1:Bool"`` and
+    ``"P/1:S"``. The keys are pairwise distinct; a key that would meet another
+    symbol's own name gets a ``#2``, ``#3``, ... suffix.
+
+    Shared by every route that reads a Z3 model back into a dict and by the
+    cvc5 route, so a countermodel names its symbols the same way whichever
+    solver found it.
+    """
+    by_name = Counter(name for name, _, _ in entries)
+    by_arity = Counter((name, arity) for name, arity, _ in entries)
+    keys: List[Optional[str]] = [name if by_name[name] == 1 else None for name, _, _ in entries]
+    taken = {key for key in keys if key is not None}        # a symbol's own name comes first
+    for i, (name, arity, range_text) in enumerate(entries):
+        if keys[i] is not None:
+            continue
+        key = (f"{name}/{arity}" if by_arity[(name, arity)] == 1
+               else f"{name}/{arity}:{range_text}")
+        candidate, n = key, 1
+        while candidate in taken:
+            n += 1
+            candidate = f"{key}#{n}"
+        taken.add(candidate)
+        keys[i] = candidate
+    return keys  # type: ignore[return-value]
+
+
+def separate_variables(entries: Sequence[Tuple[str, int, str]],
+                       is_variable: Sequence[bool]) -> List[Tuple[str, int, str]]:
+    """Give each variable among the ``(name, arity, range)`` entries the name it is reported under.
+
+    A free variable ``x`` is a symbol of the model next to the constants. It is reported
+    under its own name, ``x``, unless a constant of that name is declared too: then the
+    constant keeps ``x`` and the variable is ``x!v``, so that the two are told apart and the
+    constant is always found under its plain name. If ``x!v`` is itself the name of another
+    symbol (a constant spelled ``x!v``, another variable), the variable is ``x!v!v``, and so on:
+    a variable never takes the name of a symbol that is not it, so that no constant loses
+    its plain name to a variable. A constant is a symbol of no arguments whose range is not
+    ``Bool`` (a proposition is a predicate): the sort ``S``, or a numeric sort.
+    """
+    names = {name for name, _, _ in entries}
+    constants = {name for (name, arity, range_text), variable in zip(entries, is_variable)
+                 if not variable and arity == 0 and range_text != "Bool"}
+    reported = []
+    for (name, arity, range_text), variable in zip(entries, is_variable):
+        if variable and name in constants:
+            name = z3_variable_name(name)
+            while name in names:
+                name = z3_variable_name(name)
+            names.add(name)
+        reported.append((name, arity, range_text))
+    return reported
+
+
+def _kit_entry(decl, ranges: Sequence[str] = ("S",)) -> Tuple[Tuple[str, int, str], bool]:
+    """The ``(name, arity, range)`` entry of a declaration of a model, with the kit's name, and
+    whether the declaration is a variable. Only a constant of one of the sorts ``ranges`` (the
+    uninterpreted sort ``S``, or the numeric sort of the arithmetic route) is written with the
+    marks of :func:`~unicode_logic_kit.fol._fol_nodes.kit_name_of_z3_symbol`; every other name is
+    the declaration's own."""
+    name, arity, range_text = str(decl.name()), decl.arity(), str(decl.range())
+    if arity == 0 and range_text in ranges:
+        name, variable = kit_name_of_z3_symbol(name)
+        return (name, arity, range_text), variable
+    return (name, arity, range_text), False
+
+
+def model_assignment(model, skip: Optional[Callable] = None,
+                     ranges: Sequence[str] = ("S",)) -> Dict[str, str]:
+    """Read a satisfying ``z3.ModelRef`` into ``{key: interpretation}``.
+
+    Keys are the kit's names of the symbols, told apart by arity (and result sort) only
+    where one name is declared more than once — see :func:`declaration_keys`. A constant
+    is under its plain name; a free variable (a symbol of its own, see
+    :class:`~unicode_logic_kit.fol.nodes.Z3Env`) is under its name too, and as ``x!v`` when a
+    constant ``x`` is declared as well (:func:`separate_variables`).
+    ``skip(decl)`` leaves out a declaration (the tracking booleans of an
+    ``assert_and_track`` call, say) before the keys are chosen, so a skipped
+    symbol never makes another one's key longer. ``ranges`` are the sorts of the constants
+    and variables of the model: ``("S",)``, or the numeric sort of the arithmetic route.
+    """
+    decls = [d for d in model.decls() if skip is None or not skip(d)]
+    entries = [_kit_entry(d, ranges) for d in decls]
+    keys = declaration_keys(separate_variables([e for e, _ in entries], [v for _, v in entries]))
+    return {key: str(model[d]) for key, d in zip(keys, decls)}
+
+
+def _add_sort_axioms(solver: Solver, *formulas: Node, env: Optional[Z3Env] = None) -> None:
+    """Assert ``sort_axioms(*formulas)`` on ``solver``, unconditionally.
+
+    Shared by every function in this module so they can never drift apart on
+    how the axioms are added (see the module docstring). A no-op — literally
+    zero calls to ``solver.add`` — when none of ``formulas`` is many-sorted.
+    ``env`` is the environment the formulas themselves were translated with.
+    """
+    for axiom in sort_axioms(*formulas):
+        solver.add(axiom.to_z3(env) if env is not None else axiom.to_z3())
+
+
+def is_satisfiable(formula: Node, timeout: int = 10000) -> bool:
+    """Return True if the formula has a model (Z3 reports sat).
+
+    A Z3 ``unknown`` result (e.g. on hard quantified formulas hitting the
+    timeout) is treated as not-known-satisfiable and returns False. A
+    many-sorted ``formula``'s sorts are asserted non-empty, and each of its
+    sorted constants is asserted to lie in its sort, alongside it — see the
+    module docstring.
+    """
+    solver = Solver()
+    solver.set("timeout", timeout)
+    solver.set("random_seed", 42)
+    env = Z3Env()
+    solver.add(formula.to_z3(env))
+    _add_sort_axioms(solver, formula, env=env)
+    return solver.check() == sat
+
+
+def is_valid(formula: Node, timeout: int = 10000) -> bool:
+    """Return True if the formula is valid, i.e. its negation is unsatisfiable.
+
+    A Z3 ``unknown`` result (e.g. on hard quantified formulas hitting the
+    timeout) is treated as not-known-valid and returns False. A many-sorted
+    ``formula``'s sorts are asserted non-empty and its sorted constants are
+    asserted to lie in their sorts, as extra, UNNEGATED premises alongside the
+    negated goal — see the module docstring; this is what makes ``is_valid``
+    agree with ``semantics.modelfinder`` on many-sorted input instead of
+    exploiting an empty-sort or constant-outside-its-sort loophole modelfinder
+    never considers a legal structure. (Asserted outside the negation: were
+    ``S(c)`` negated with the goal it would be one more thing to prove.)
+    """
+    solver = Solver()
+    solver.set("timeout", timeout)
+    solver.set("random_seed", 42)
+    env = Z3Env()
+    goal = Not(formula.to_z3(env))
+    _add_sort_axioms(solver, formula, env=env)
+    solver.add(goal)
+    return solver.check() == unsat
+
+
+def get_model(formula: Node, timeout: int = 10000):
+    """Return a satisfying assignment as a dict, or None if unsat/unknown.
+
+    The dict maps each Z3 declaration name (constants, uninterpreted
+    functions/predicates) to the string form of its interpretation. A name that
+    is declared more than once in the formula (``P(a)`` next to ``P(a, b)``, a
+    function and a predicate of one name) is two symbols, and each is reported
+    under its own key, ``"P/1"`` and ``"P/2"`` (see :func:`declaration_keys`);
+    a name declared once keeps its plain name. For an
+    invalid equivalence or entailment, ``get_model(Not(...))`` yields the
+    concrete counterexample. Returns None when the formula is unsatisfiable or
+    Z3 cannot decide it within the timeout. Every many-sorted node's sort
+    anywhere in ``formula`` — including under a ``Not(...)`` a caller wraps
+    it in — is asserted non-empty, and every sorted constant anywhere in it is
+    asserted to lie in its sort, alongside it, so a returned model is always
+    a legal MSFOL structure (see the module docstring); the returned dict may
+    therefore also carry an interpretation for a sort's own predicate.
+    """
+    solver = Solver()
+    solver.set("timeout", timeout)
+    solver.set("random_seed", 42)
+    env = Z3Env()
+    solver.add(formula.to_z3(env))
+    _add_sort_axioms(solver, formula, env=env)
+    if solver.check() != sat:
+        return None
+    return model_assignment(solver.model())

unicode_logic_kit/chem/__init__.py

@@ -0,0 +1,88 @@
+"""Molecules as finite FOL structures — the model-checking side.
+
+A chemical class definition written in FOL classifies a molecule by MODEL
+CHECKING that formula against the molecule, represented as a finite FOL
+structure (atoms = individuals). The formula side of such a pipeline is
+what usually gets documented in detail; the molecule-to-structure side
+tends to exist only as a single worked prose example (ethanol) — no code.
+This subpackage is that missing translation, in the vocabulary of ChemLog
+(Flügel et al. 2025, MIT licence,
+https://github.com/sfluegel05/chemlog-peptides):
+
+    >>> from unicode_logic_kit.chem import mol_to_structure, CHEMLOG_SIGNATURE
+    >>> ethanol = mol_to_structure("CCO")             # SMILES -> FiniteStructure
+    >>> ethanol.individuals_with("c")                 # the two carbons
+    ('c1', 'c2')
+    >>> from unicode_logic_kit import api
+    >>> api.check("∀x (c(x) → atom(x))", signature=CHEMLOG_SIGNATURE).ok
+    True
+
+Scope
+-----
+* :mod:`.mol` — :func:`mol_to_structure`: SMILES or an ``rdkit.Chem.Mol`` in,
+  a :class:`~unicode_logic_kit.semantics.structures.FiniteStructure` out. RDKit
+  is an OPTIONAL dependency (``pip install rdkit``); importing this
+  subpackage never requires it, only calling :func:`mol_to_structure` does.
+* :mod:`.signature` — :data:`CHEMLOG_SIGNATURE`, the same vocabulary as a
+  first-class kit :class:`~unicode_logic_kit.fol.signature.Signature`
+  (for ``api.check(formula, signature=CHEMLOG_SIGNATURE)``), plus the
+  :data:`CHEMLOG_TO_PAPER` / :data:`PAPER_TO_CHEMLOG` alias tables between
+  ChemLog's own TPTP-file spelling and the prose spelling of the identical
+  vocabulary.
+
+Why this exists (the bottlenecks this pipeline hits)
+----------------------------------------------------------
+Three problems recur in a pipeline of this shape, and this subpackage
+speaks to each directly: model-checking timeouts are the major bottleneck
+(addressed by
+:class:`~unicode_logic_kit.semantics.structures.FiniteStructure`'s
+candidate-set indexing, which this module's structures inherit for free);
+over-general formulas, whose precision cost stays invisible until it is
+measured against a corpus (addressed elsewhere, by tighter translation, not
+by this subpackage); and failures on pure syntax, which dominate the rest
+(addressed by :data:`CHEMLOG_SIGNATURE` catching an unknown predicate or
+wrong arity before a definition ever reaches model checking).
+
+What this subpackage does NOT do
+--------------------------------------
+It does not translate natural-language class definitions to FOL (that is
+the rest of the kit — parsing, ``api.check``, the prover backends), and it
+does not itself run model checking (that is
+:mod:`unicode_logic_kit.semantics.model_eval` / the Tarskian evaluator over
+the :class:`FiniteStructure` this subpackage builds). It is exactly the one
+missing piece: molecule in, structure out, in a vocabulary the rest of the
+kit already knows how to check formulas against.
+"""
+
+from .mol import mol_to_structure
+from .cache import StructureCache, StructureBuildError
+from .signature import (
+    CHEMLOG_SIGNATURE, CHEMLOG_TO_PAPER, PAPER_TO_CHEMLOG,
+    to_paper_naming, to_chemlog_naming,
+)
+
+from ..fol.spans import SpanMap
+from .interop import (
+    parse_chemlog_tptp, to_kit_names, to_chemlog_names,
+    CHEMLOG_TO_KIT, KIT_TO_CHEMLOG,
+    rename_with_spans, to_chemlog_names_with_spans,
+)
+
+__all__ = [
+    "mol_to_structure",
+    "StructureCache", "StructureBuildError",
+    "CHEMLOG_SIGNATURE", "CHEMLOG_TO_PAPER", "PAPER_TO_CHEMLOG",
+    "to_paper_naming", "to_chemlog_naming",
+    # TPTP interop: the kit's importer inverts TPTP's case convention, so a
+    # formula read from ChemLog TPTP needs its chemical vocabulary renamed
+    # back before it lines up with a molecule structure.
+    "parse_chemlog_tptp", "to_kit_names", "to_chemlog_names",
+    "CHEMLOG_TO_KIT", "KIT_TO_CHEMLOG",
+    # Span propagation (opt-in; see unicode_logic_kit.mcp.chem_tools's module
+    # docstring for the consumer): rename_with_spans/to_chemlog_names_with_spans
+    # carry a caller-supplied SpanMap across the rename this module always
+    # performs, since that rename reconstructs every node (see
+    # interop.rename_with_spans's own docstring) and would otherwise sever
+    # the link between a parsed AST node and the source span it came from.
+    "SpanMap", "rename_with_spans", "to_chemlog_names_with_spans",
+]

unicode_logic_kit/chem/_naming.py

@@ -0,0 +1,284 @@
+"""Shared naming-scheme machinery for :mod:`unicode_logic_kit.chem` — PRIVATE.
+
+The ChemLog vocabulary this subpackage targets (Flügel et al. 2025, MIT
+licence, https://github.com/sfluegel05/chemlog-peptides) is spelled two
+different ways by the two kinds of source that describe it:
+
+* **running prose** (as in a worked ethanol example) writes ``has3Hs`` /
+  ``has2Hs`` / ``has1H`` (note the irregular singular at exactly one) and
+  ``singleBond``;
+* the actual **ChemLog TPTP source files** write ``has_1_hs`` / ``has_2_hs``
+  / ``has_3_hs`` and ``bSINGLE``.
+
+:mod:`unicode_logic_kit.chem.mol` has to pick ONE of these as what it actually
+emits (silently supporting "a bit of both" would be exactly the kind of
+unprincipled approximation this kit refuses), and
+:mod:`unicode_logic_kit.chem.signature` has to publish a mapping between the
+two so a caller who needs the other spelling is not stuck. Both modules
+import this one so the naming rules are declared in exactly ONE place: were
+``signature``'s alias table hand-written separately from what ``mol``
+actually produces, the two would be free to drift out of sync with no test
+able to catch it short of re-deriving both by hand. This module has NO
+RDKit dependency (it deals in strings only) — it must stay importable
+without RDKit installed, because :mod:`unicode_logic_kit.chem.signature`
+(which needs it) explicitly must be.
+
+**The default scheme is ``"chemlog"``** (the TPTP-file spelling), because
+that is the vocabulary :mod:`unicode_logic_kit.chem.signature`'s
+``CHEMLOG_SIGNATURE`` is built to validate against and because it is
+internally uniform (one snake_case convention throughout) where the prose
+spelling is not (see ``_hs_name_paper`` below). ``"paper"`` exists
+specifically so a caller can reproduce the literal prose spelling — see
+``mol.py``'s ethanol acceptance test.
+
+Naming decisions spelled out (so a reviewer does not have to reverse-engineer
+them from the code):
+
+* **Hydrogen count.** ChemLog: ``has_{n}_hs`` uniformly. ``"paper"``:
+  ``has{n}H`` at ``n == 1``, ``has{n}Hs`` otherwise — this is a
+  GENERALISATION of the literal ``has3Hs``/``has2Hs``/``has1H`` (the only
+  three values ethanol exhibits) to arbitrary ``n``; the prose spelling
+  never shows ``n == 0`` or ``n > 3``, so extending the same
+  singular-at-one rule to those is the only assumption made here, not a
+  literal quote.
+* **Formal charge.** IDENTICAL under both schemes: ``charge0`` at zero,
+  ``charge_p{n}``/``charge_m{n}`` (``n = abs(charge)``) otherwise. The
+  prose spelling only ever demonstrates ``charge0``; the ChemLog spec gives
+  ``charge0, charge_m1, charge_p1 (bzw. chargeN)`` for the ChemLog side. The
+  parenthetical generic form is read here as "continue the sign-letter
+  pattern established by charge_m1/charge_p1 to any n" rather than as a
+  THIRD, inconsistent bare ``chargeN`` spelling that would collide with the
+  sign-letter convention already fixed at n=1 — the latter reading would
+  leave the sign undetermined for exactly the cases (n>1) it is supposed to
+  cover.
+* **Bond types.** ChemLog: ``bSINGLE``/``bDOUBLE``/``bTRIPLE``/``bAROMATIC``
+  (all four are literal ChemLog spec text). ``"paper"``: only
+  ``singleBond`` is literally attested; ``doubleBond``/``tripleBond``/
+  ``aromaticBond`` are this module's generalisation of that one example by
+  analogy.
+* **Net-charge globals.** ``NetChargePositive``/``NetChargeNegative`` are
+  spelled IDENTICALLY in the ChemLog spec text and in prose (both
+  CamelCase) — no alias needed. Only the neutral flag differs:
+  ``net_charge_neutral`` (ChemLog, snake_case — matching the spec text
+  verbatim, inconsistent as that is with the sibling predicates being
+  CamelCase) vs. ``NetChargeNeutral`` (the ``"paper"`` scheme, CamelCase,
+  matching its siblings and the literal prose spelling).
+* **Element letters, ``atom``, ``ChiralR``/``ChiralS``, the ``bond``
+  super-relation.** Spelled identically by both sources — no alias table
+  entry is needed for these beyond the identity pairing (included below for
+  completeness, so a caller can look ANY known predicate up in one table
+  without having to special-case "well, THIS one doesn't need translating").
+* **``has_bond_to``.** ChemLog-only: the spec text lists it as a second name
+  for the same bond-existence super-relation ``bond`` alongside ``bond``
+  itself (their exact relationship undocumented beyond "binaere: ... bond
+  (Oberrelation), has_bond_to" in the spec text) — both are populated as
+  IDENTICAL extensions under the ``"chemlog"`` scheme. The prose spelling
+  never mentions a second name at all, so the ``"paper"`` scheme simply
+  omits it; it has no alias-table counterpart (deliberately absent, not an
+  oversight — see :mod:`unicode_logic_kit.chem.signature`).
+
+The computed predicates (:mod:`unicode_logic_kit.chem.mol`'s ``in_ring`` /
+``in_ring_of_size_N`` / ``aromatic`` / ``same_fragment`` / ``carbon_
+connected``) are this module's OWN addition beyond either source's literal
+vocabulary, so they are scheme-INVARIANT (same spelling always) and are not
+part of the alias table below — an identity mapping would carry no
+information a lookup failure doesn't already convey by raising.
+"""
+
+from dataclasses import dataclass
+from typing import Callable, Dict, Optional, Tuple
+
+__all__: Tuple[str, ...] = ()   # private module — nothing meant for reuse outside chem/
+
+# -----------------------------------------------------------------------
+# Fixed, scheme-invariant vocabulary
+# -----------------------------------------------------------------------
+
+#: RDKit element symbol -> ChemLog atom-type letter (identical in both
+#: schemes, and in the literal worked ethanol example: M(c), M(o)).
+#:
+#: The first six are ChemLog's own: its published vocabulary is a peptide
+#: one, and peptides are built from C/N/O/S/P/H. The halogens below are this
+#: module's extension, on the same footing as the computed predicates
+#: described at the end of the module docstring -- an addition beyond either
+#: source's literal vocabulary, spelled by the same rule (lower-cased
+#: element symbol) and therefore scheme-invariant.
+#:
+#: They are here because the vocabulary has to cover the molecules it is
+#: pointed at, not just the ones its source paper was about. ChEBI classes
+#: such as ``organohalogenCompound`` are *defined* by a halogen; without
+#: these letters ``mol_to_structure`` refuses the molecule outright, and a
+#: refusal is not a chemical statement -- every such class would be
+#: unanswerable rather than answered. Astatine is included for closure of
+#: the group even though it is vanishingly rare in ChEBI: leaving out one
+#: member would make the vocabulary's boundary an accident of frequency.
+ELEMENT_LETTERS: Dict[str, str] = {
+    "C": "c", "N": "n", "O": "o", "S": "s", "P": "p", "H": "h",
+    "F": "f", "Cl": "cl", "Br": "br", "I": "i", "At": "at",
+}
+
+ATOM_NAME = "atom"
+CHIRAL_R_NAME = "ChiralR"
+CHIRAL_S_NAME = "ChiralS"
+BOND_SUPER_NAME = "bond"
+NET_CHARGE_POSITIVE_NAME = "NetChargePositive"
+NET_CHARGE_NEGATIVE_NAME = "NetChargeNegative"
+
+#: The four RDKit bond-order "kinds" this vocabulary covers, by a
+#: scheme-independent short key (NOT an RDKit ``BondType`` — this module has
+#: no RDKit dependency; ``mol.py`` maps ``rdkit.Chem.BondType`` values onto
+#: these keys itself).
+BOND_KINDS: Tuple[str, ...] = ("SINGLE", "DOUBLE", "TRIPLE", "AROMATIC")
+
+#: The hydrogen-count / formal-charge values every structure ``mol.py``
+#: builds interprets EXPLICITLY (even as an empty extension) regardless of
+#: whether the particular molecule exhibits them — see ``mol.py``'s module
+#: docstring, "always-populated predicates", for why: a formula asking
+#: ``s(x)`` of a sulfur-free molecule must get "false everywhere", not a
+#: ``KeyError`` for an uninterpreted symbol that the ChemLog vocabulary in
+#: fact declares. These two ranges match the ChemLog spec text's OWN
+#: examples verbatim (``has_0_hs``..``has_3_hs``; ``charge0``, ``charge_m1``,
+#: ``charge_p1``) rather than some wider guess — a molecule that genuinely
+#: needs e.g. ``has_4_hs`` (methane's carbon) or ``charge_m2`` still gets
+#: that predicate populated (``mol.py``'s atom loop adds keys on demand), it
+#: is just not PRE-populated as an empty default the way 0..3 / -1/0/1 are.
+CANONICAL_HS_RANGE: Tuple[int, ...] = (0, 1, 2, 3)
+CANONICAL_CHARGES: Tuple[int, ...] = (0, -1, 1)
+
+#: Concrete ring sizes ``mol.py`` exposes as their own unary predicate
+#: (``in_ring_of_size_3`` .. ``in_ring_of_size_8``), alongside the fully
+#: general ``in_ring`` (any size). Range chosen to cover the ring sizes that
+#: actually recur in organic/bio-organic chemistry — cyclopropane through
+#: cyclooctane, which already includes every common aromatic and
+#: heteroaromatic ring (5- and 6-membered). A macrocycle bigger than 8 is
+#: still correctly reported by ``in_ring`` (True) but has no
+#: ``in_ring_of_size_N`` member of its own — a real but narrow limitation,
+#: not a silent one: nothing claims a size-12 ring is a size-8 ring.
+RING_SIZE_FAMILY: Tuple[int, ...] = (3, 4, 5, 6, 7, 8)
+
+
+def _hs_name_chemlog(n: int) -> str:
+    return f"has_{n}_hs"
+
+
+def _hs_name_paper(n: int) -> str:
+    return f"has{n}H" if n == 1 else f"has{n}Hs"
+
+
+def _charge_name(n: int) -> str:
+    if n == 0:
+        return "charge0"
+    return f"charge_{'p' if n > 0 else 'm'}{abs(n)}"
+
+
+@dataclass(frozen=True)
+class NamingScheme:
+    """One consistent spelling of the ChemLog vocabulary.
+
+    ``bond_type_names`` maps each :data:`BOND_KINDS` key to that scheme's
+    predicate name; ``has_bond_to_name`` is ``None`` under the ``"paper"``
+    scheme (see the module docstring's "``has_bond_to``" bullet).
+    """
+
+    key: str
+    hs_name: Callable[[int], str]
+    charge_name: Callable[[int], str]
+    net_charge_neutral_name: str
+    bond_type_names: Dict[str, str]
+    has_bond_to_name: Optional[str]
+
+
+CHEMLOG = NamingScheme(
+    key="chemlog",
+    hs_name=_hs_name_chemlog,
+    charge_name=_charge_name,
+    net_charge_neutral_name="net_charge_neutral",
+    bond_type_names={
+        "SINGLE": "bSINGLE", "DOUBLE": "bDOUBLE",
+        "TRIPLE": "bTRIPLE", "AROMATIC": "bAROMATIC",
+    },
+    has_bond_to_name="has_bond_to",
+)
+
+PAPER = NamingScheme(
+    key="paper",
+    hs_name=_hs_name_paper,
+    charge_name=_charge_name,
+    net_charge_neutral_name="NetChargeNeutral",
+    bond_type_names={
+        "SINGLE": "singleBond", "DOUBLE": "doubleBond",
+        "TRIPLE": "tripleBond", "AROMATIC": "aromaticBond",
+    },
+    has_bond_to_name=None,
+)
+
+#: ``naming=`` argument -> scheme, consulted by ``mol.mol_to_structure``.
+SCHEMES: Dict[str, NamingScheme] = {"chemlog": CHEMLOG, "paper": PAPER}
+
+
+def chemlog_predicate_arities() -> Dict[str, int]:
+    """Every predicate ``mol_to_structure(naming="chemlog")`` may populate,
+    mapped to its arity — the vocabulary
+    :data:`unicode_logic_kit.chem.signature.CHEMLOG_SIGNATURE` declares.
+
+    Includes the computed predicates (present when ``computed=True``, the
+    default) alongside the stored ones, since both are equally part of what
+    a formula checked against ``CHEMLOG_SIGNATURE`` is allowed to mention —
+    :class:`~unicode_logic_kit.fol.signature.Signature` has no notion of
+    "stored vs. computed", only "declared vs. not".
+    """
+    out: Dict[str, int] = {}
+    for letter in ELEMENT_LETTERS.values():
+        out[letter] = 1
+    out[ATOM_NAME] = 1
+    for n in CANONICAL_HS_RANGE:
+        out[CHEMLOG.hs_name(n)] = 1
+    for n in CANONICAL_CHARGES:
+        out[CHEMLOG.charge_name(n)] = 1
+    out[CHIRAL_R_NAME] = 1
+    out[CHIRAL_S_NAME] = 1
+    for kind in BOND_KINDS:
+        out[CHEMLOG.bond_type_names[kind]] = 2
+    out[BOND_SUPER_NAME] = 2
+    assert CHEMLOG.has_bond_to_name is not None
+    out[CHEMLOG.has_bond_to_name] = 2
+    out[CHEMLOG.net_charge_neutral_name] = 0
+    out[NET_CHARGE_POSITIVE_NAME] = 0
+    out[NET_CHARGE_NEGATIVE_NAME] = 0
+    # computed
+    out["in_ring"] = 1
+    for size in RING_SIZE_FAMILY:
+        out[f"in_ring_of_size_{size}"] = 1
+    out["aromatic"] = 1
+    out["same_fragment"] = 2
+    out["carbon_connected"] = 2
+    return out
+
+
+def _build_chemlog_to_paper() -> Dict[str, str]:
+    """The alias table :mod:`unicode_logic_kit.chem.signature` publishes,
+    derived from the two :class:`NamingScheme` objects above rather than
+    hand-duplicated, so it cannot drift from what ``mol.py`` actually emits
+    (see the module docstring's opening paragraph)."""
+    out: Dict[str, str] = {}
+    for letter in ELEMENT_LETTERS.values():
+        out[letter] = letter
+    out[ATOM_NAME] = ATOM_NAME
+    out[CHIRAL_R_NAME] = CHIRAL_R_NAME
+    out[CHIRAL_S_NAME] = CHIRAL_S_NAME
+    out[BOND_SUPER_NAME] = BOND_SUPER_NAME
+    out[NET_CHARGE_POSITIVE_NAME] = NET_CHARGE_POSITIVE_NAME
+    out[NET_CHARGE_NEGATIVE_NAME] = NET_CHARGE_NEGATIVE_NAME
+    out[CHEMLOG.net_charge_neutral_name] = PAPER.net_charge_neutral_name
+    for n in CANONICAL_HS_RANGE:
+        out[CHEMLOG.hs_name(n)] = PAPER.hs_name(n)
+    for n in CANONICAL_CHARGES:
+        out[CHEMLOG.charge_name(n)] = PAPER.charge_name(n)
+    for kind in BOND_KINDS:
+        out[CHEMLOG.bond_type_names[kind]] = PAPER.bond_type_names[kind]
+    # has_bond_to deliberately excluded: no paper-scheme counterpart exists.
+    return out
+
+
+CHEMLOG_TO_PAPER: Dict[str, str] = _build_chemlog_to_paper()
+PAPER_TO_CHEMLOG: Dict[str, str] = {v: k for k, v in CHEMLOG_TO_PAPER.items()}