process-geometry 0.0.3__py3-none-any.whl

aeg_shakespeare/constraints.py

@@ -0,0 +1,121 @@
+"""Exact algebraic constraints and quotient reduction.
+
+Mathematical lineage
+--------------------
+Classical mechanics is often presented *after* coordinates have already solved
+part of the geometry: a pendulum becomes an angle, a rigid body becomes a chart,
+and the remaining equations are written on that chosen coordinate space.  The
+Shakespeare reconstruction reverses that order.  It keeps the primitive
+assignments and their relations visible, then asks which dynamics preserve the
+relations and what quotient those relations force.
+
+This is why constraints are not treated as side conditions.  A relation such as
+``q.q - 1 = 0`` is part of the process presentation.  Requiring its successive
+process images to vanish can determine otherwise unresolved process terms; only
+later may a familiar coordinate description appear as a classical shadow.
+
+Implementation
+--------------
+``AlgebraicConstraintSet`` represents the polynomial quotient exactly through a
+Groebner backend. ``constraint_prolongation`` records the successive history
+``r, D r, D^2 r, ...`` without assuming a named mechanical model.
+
+Boundary
+--------
+This module does not claim that every useful constraint is polynomial, nor that
+Groebner reduction is the ontology of equality.  It is one exact backend for a
+relation layer whose meaning is supplied by the process presentation.
+
+See ``docs/07-classical-calibration-program.md`` and
+``docs/09-literate-programming-and-mathematical-lineage.md``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cached_property
+from typing import Sequence
+
+import sympy as sp
+
+
+@dataclass(frozen=True)
+class AlgebraicConstraintSet:
+    """A polynomial quotient specified by generators of an algebraic ideal."""
+
+    variables: tuple[sp.Symbol, ...]
+    relations: tuple[sp.Expr, ...]
+    order: str = "grevlex"
+
+    def __post_init__(self) -> None:
+        if not self.variables:
+            raise ValueError("constraint set requires at least one variable")
+        variables = tuple(self.variables)
+        if len(set(variables)) != len(variables):
+            raise ValueError("constraint variables must be distinct")
+        relations = tuple(sp.expand(sp.sympify(relation)) for relation in self.relations)
+        if any(relation == 0 for relation in relations):
+            relations = tuple(relation for relation in relations if relation != 0)
+        object.__setattr__(self, "variables", variables)
+        object.__setattr__(self, "relations", relations)
+
+    @cached_property
+    def groebner_basis(self) -> sp.GroebnerBasis | None:
+        if not self.relations:
+            return None
+        try:
+            return sp.groebner(self.relations, *self.variables, order=self.order)
+        except sp.PolynomialError as exc:
+            raise ValueError("constraints must be polynomial in the declared variables") from exc
+
+    def reduce(self, expr: sp.Expr) -> sp.Expr:
+        """Return the exact normal remainder modulo the constraint ideal."""
+
+        expr = sp.expand(sp.sympify(expr))
+        if self.groebner_basis is None:
+            return expr
+        try:
+            _quotients, remainder = self.groebner_basis.reduce(expr)
+        except sp.PolynomialError as exc:
+            raise ValueError("expression must be polynomial in the declared variables") from exc
+        return sp.expand(remainder)
+
+    def contains(self, expr: sp.Expr) -> bool:
+        """Whether ``expr = 0`` follows from the declared algebraic relations."""
+
+        return self.reduce(expr) == 0
+
+    def equivalent(self, left: sp.Expr, right: sp.Expr) -> bool:
+        """Whether two expressions agree in the quotient algebra."""
+
+        return self.contains(sp.expand(sp.sympify(left) - sp.sympify(right)))
+
+    def adjoin(self, *relations: sp.Expr) -> "AlgebraicConstraintSet":
+        """Return the quotient obtained by adding more exact relations."""
+
+        return AlgebraicConstraintSet(
+            variables=self.variables,
+            relations=self.relations + tuple(relations),
+            order=self.order,
+        )
+
+
+def constraint_prolongation(
+    derive,
+    relation: sp.Expr,
+    *,
+    order: int,
+) -> tuple[sp.Expr, ...]:
+    """Return ``relation, D relation, ..., D^order relation``.
+
+    ``derive`` is caller-supplied so this utility can be used with
+    ``ProcessSystem``, ``ProcessFrame`` generators, or future process backends.
+    No dynamics-specific multiplier model is assumed here.
+    """
+
+    if order < 0:
+        raise ValueError("order must be non-negative")
+    values = [sp.expand(sp.sympify(relation))]
+    for _ in range(order):
+        values.append(sp.expand(sp.sympify(derive(values[-1]))))
+    return tuple(values)

aeg_shakespeare/construction.py

@@ -0,0 +1,303 @@
+"""Construction-history-preserving primitive proposals.
+
+Candidate primitives should not be identified merely because their final SymPy
+expressions are equal. This module provides a small symbolic proposal IR that
+keeps an explicit construction tree, operation costs, and bounded generation.
+It is intentionally separate from presentation evaluation/Pareto search.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from itertools import product
+import math
+from typing import Callable, Sequence
+
+import sympy as sp
+
+
+@dataclass(frozen=True)
+class SymbolicOperation:
+    """Caller-declared symbolic operation available to proposal generation.
+
+    Parameters
+    ----------
+    name:
+        Stable display name used in construction certificates.
+    arity:
+        Number of input expressions.
+    apply:
+        Callable implementing the operation's symbolic semantics. Callable
+        identity remains part of construction identity, so two operations with
+        the same display name are not silently equated.
+    cost:
+        Non-negative construction cost of one use.
+    commutative:
+        If true, argument permutations are considered the same construction for
+        this operation. Associativity is *not* assumed automatically.
+    """
+
+    name: str
+    arity: int
+    apply: Callable[..., sp.Expr] = field(repr=False)
+    cost: float = 1.0
+    commutative: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("operation name must be non-empty")
+        if self.arity < 1:
+            raise ValueError("operation arity must be positive")
+        if not math.isfinite(float(self.cost)) or self.cost < 0:
+            raise ValueError("operation cost must be finite and non-negative")
+
+
+@dataclass(frozen=True)
+class PrimitiveConstruction:
+    """A tree certificate for how one candidate primitive was built."""
+
+    atom: sp.Expr | None = None
+    operation: SymbolicOperation | None = None
+    children: tuple["PrimitiveConstruction", ...] = ()
+
+    def __post_init__(self) -> None:
+        has_atom = self.atom is not None
+        has_operation = self.operation is not None
+        if has_atom == has_operation:
+            raise ValueError("construction must contain exactly one atom or operation")
+        if has_atom:
+            if self.children:
+                raise ValueError("atomic construction cannot have children")
+            object.__setattr__(self, "atom", sp.expand(sp.sympify(self.atom)))
+            return
+        assert self.operation is not None
+        if len(self.children) != self.operation.arity:
+            raise ValueError("construction child count must match operation arity")
+
+    @classmethod
+    def atomic(cls, expr: sp.Expr) -> "PrimitiveConstruction":
+        return cls(atom=sp.expand(sp.sympify(expr)))
+
+    @property
+    def depth(self) -> int:
+        if self.atom is not None:
+            return 0
+        return 1 + max((child.depth for child in self.children), default=0)
+
+    @property
+    def operation_count(self) -> int:
+        if self.atom is not None:
+            return 0
+        return 1 + sum(child.operation_count for child in self.children)
+
+    @property
+    def cost(self) -> float:
+        if self.atom is not None:
+            return 0.0
+        assert self.operation is not None
+        return float(self.operation.cost) + sum(child.cost for child in self.children)
+
+    def recipe(self) -> str:
+        if self.atom is not None:
+            return str(self.atom)
+        assert self.operation is not None
+        arguments = ", ".join(child.recipe() for child in self.children)
+        return f"{self.operation.name}({arguments})"
+
+
+@dataclass(frozen=True)
+class PrimitiveProposal:
+    """A candidate expression together with its non-erased construction tree."""
+
+    expression: sp.Expr
+    construction: PrimitiveConstruction
+
+    @property
+    def cost(self) -> float:
+        return self.construction.cost
+
+
+@dataclass(frozen=True)
+class RejectedPrimitiveProposal:
+    construction: PrimitiveConstruction
+    reason: str
+
+
+@dataclass(frozen=True)
+class PrimitiveProposalResult:
+    proposals: tuple[PrimitiveProposal, ...]
+    rejected: tuple[RejectedPrimitiveProposal, ...]
+    truncated: bool = False
+
+    @property
+    def semantic_expression_count(self) -> int:
+        """Count distinct final expressions without erasing proposal histories."""
+
+        return len({sp.srepr(proposal.expression) for proposal in self.proposals})
+
+
+def _polynomial_degree(expr: sp.Expr, variables: Sequence[sp.Symbol]) -> int:
+    try:
+        degree = sp.Poly(sp.expand(expr), *variables).total_degree()
+    except sp.PolynomialError as exc:
+        raise ValueError("proposal is not polynomial in the declared variables") from exc
+    if degree is sp.S.NegativeInfinity:
+        return 0
+    return int(degree)
+
+
+def _construction_key(construction: PrimitiveConstruction) -> str:
+    return construction.recipe()
+
+
+def generate_primitive_proposals(
+    atoms: Sequence[sp.Expr],
+    operations: Sequence[SymbolicOperation],
+    *,
+    variables: Sequence[sp.Symbol],
+    max_depth: int,
+    max_degree: int,
+    max_candidates: int = 256,
+    include_atoms: bool = True,
+) -> PrimitiveProposalResult:
+    """Generate bounded symbolic primitive proposals without erasing recipes.
+
+    Generation proceeds by construction depth. Semantic duplicates are kept if
+    they have different construction trees. The only automatic construction
+    quotient is argument permutation for operations explicitly declared
+    commutative by the caller.
+
+    ``max_candidates`` bounds generated non-atomic proposals; atoms are caller
+    inputs and are not charged against that bound.
+    """
+
+    if max_depth < 0:
+        raise ValueError("max_depth must be non-negative")
+    if max_degree < 0:
+        raise ValueError("max_degree must be non-negative")
+    if max_candidates < 0:
+        raise ValueError("max_candidates must be non-negative")
+
+    variables = tuple(variables)
+    constructions: list[PrimitiveConstruction] = []
+    seen_constructions: set[PrimitiveConstruction] = set()
+    proposals: list[PrimitiveProposal] = []
+    rejected: list[RejectedPrimitiveProposal] = []
+
+    for atom in atoms:
+        construction = PrimitiveConstruction.atomic(atom)
+        if construction in seen_constructions:
+            continue
+        seen_constructions.add(construction)
+        expression = construction.atom
+        assert expression is not None
+        try:
+            degree = _polynomial_degree(expression, variables)
+        except ValueError as exc:
+            rejected.append(RejectedPrimitiveProposal(construction, str(exc)))
+            continue
+        if degree > max_degree:
+            rejected.append(
+                RejectedPrimitiveProposal(
+                    construction,
+                    f"polynomial degree {degree} exceeds bound {max_degree}",
+                )
+            )
+            continue
+        constructions.append(construction)
+        if include_atoms:
+            proposals.append(PrimitiveProposal(expression, construction))
+
+    if max_candidates == 0:
+        return PrimitiveProposalResult(
+            proposals=tuple(proposals),
+            rejected=tuple(rejected),
+            truncated=max_depth > 0 and bool(operations) and bool(constructions),
+        )
+
+    generated_nonatoms = 0
+
+    for depth in range(1, max_depth + 1):
+        pool = tuple(constructions)
+        if not pool:
+            break
+
+        for operation in operations:
+            for children in product(pool, repeat=operation.arity):
+                if max(child.depth for child in children) != depth - 1:
+                    continue
+                if operation.commutative:
+                    keys = tuple(_construction_key(child) for child in children)
+                    if keys != tuple(sorted(keys)):
+                        continue
+
+                construction = PrimitiveConstruction(
+                    operation=operation,
+                    children=tuple(children),
+                )
+                if construction in seen_constructions:
+                    continue
+                seen_constructions.add(construction)
+
+                try:
+                    expression = _evaluate_construction(construction)
+                except Exception as exc:  # caller operation boundary
+                    rejected.append(
+                        RejectedPrimitiveProposal(
+                            construction,
+                            f"operation evaluation failed: {exc}",
+                        )
+                    )
+                    continue
+
+                if expression == 0:
+                    rejected.append(
+                        RejectedPrimitiveProposal(
+                            construction,
+                            "zero is not a primitive proposal",
+                        )
+                    )
+                    continue
+
+                try:
+                    degree = _polynomial_degree(expression, variables)
+                except ValueError as exc:
+                    rejected.append(RejectedPrimitiveProposal(construction, str(exc)))
+                    continue
+                if degree > max_degree:
+                    rejected.append(
+                        RejectedPrimitiveProposal(
+                            construction,
+                            f"polynomial degree {degree} exceeds bound {max_degree}",
+                        )
+                    )
+                    continue
+
+                proposals.append(PrimitiveProposal(expression, construction))
+                constructions.append(construction)
+                generated_nonatoms += 1
+                if generated_nonatoms >= max_candidates:
+                    return PrimitiveProposalResult(
+                        proposals=tuple(proposals),
+                        rejected=tuple(rejected),
+                        truncated=True,
+                    )
+
+    return PrimitiveProposalResult(
+        proposals=tuple(proposals),
+        rejected=tuple(rejected),
+        truncated=False,
+    )
+
+
+def _evaluate_construction(construction: PrimitiveConstruction) -> sp.Expr:
+    if construction.atom is not None:
+        return construction.atom
+    assert construction.operation is not None
+    return sp.expand(
+        sp.sympify(
+            construction.operation.apply(
+                *[_evaluate_construction(child) for child in construction.children]
+            )
+        )
+    )

aeg_shakespeare/core.py

@@ -0,0 +1,59 @@
+"""Compatibility/backend module after semantic core decomposition.
+
+Canonical semantic ownership is now:
+
+- ``ProcessWord`` and ``interpret_history`` -> ``process.history``;
+- ``ProcessSystem`` -> ``process.local``;
+- ``SearchBudget`` -> ``presentation.budget``.
+
+This module retains those identity-preserving imports for pre-refactor internal
+paths and keeps ``homogeneous_monomials`` as a small SymPy backend helper. It is
+no longer the architectural center of the public API.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+import sympy as sp
+
+from .presentation.budget import SearchBudget
+from .process.history import ProcessWord, interpret_history
+from .process.local import ProcessSystem
+
+
+def homogeneous_monomials(assignments: Sequence[sp.Symbol], degree: int) -> list[sp.Expr]:
+    """Enumerate commutative monomials of fixed total degree.
+
+    This is a SymPy-backend utility, not a restriction on the process ontology.
+    """
+    if degree < 0:
+        raise ValueError("degree must be non-negative")
+    assignments = tuple(assignments)
+    if not assignments:
+        return [sp.S.One] if degree == 0 else []
+
+    def compositions(total: int, n: int):
+        if n == 1:
+            yield (total,)
+            return
+        for i in range(total, -1, -1):
+            for rest in compositions(total - i, n - 1):
+                yield (i,) + rest
+
+    result: list[sp.Expr] = []
+    for exponents in compositions(degree, len(assignments)):
+        monomial = sp.S.One
+        for symbol, exponent in zip(assignments, exponents):
+            monomial *= symbol**exponent
+        result.append(sp.expand(monomial))
+    return result
+
+
+__all__ = [
+    "ProcessWord",
+    "interpret_history",
+    "ProcessSystem",
+    "SearchBudget",
+    "homogeneous_monomials",
+]

aeg_shakespeare/cost.py

@@ -0,0 +1,51 @@
+"""Cost objects for process-representation search.
+
+Costs stay multi-axis by default.  A caller may scalarize them later, but the
+library does not hide trade-offs between grammar size, relation complexity,
+history depth, decoder complexity, and task error.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping
+
+
+@dataclass(frozen=True)
+class PresentationCost:
+    """Multi-axis cost of a process presentation."""
+
+    grammar: float = 0.0
+    relations: float = 0.0
+    history: float = 0.0
+    decoder: float = 0.0
+    task_error: float = 0.0
+
+    def components(self) -> Mapping[str, float]:
+        return {
+            "grammar": self.grammar,
+            "relations": self.relations,
+            "history": self.history,
+            "decoder": self.decoder,
+            "task_error": self.task_error,
+        }
+
+    def scalarize(self, weights: Mapping[str, float] | None = None) -> float:
+        """Return a caller-controlled weighted sum.
+
+        Missing weights default to ``1``.  Shakespeare does not prescribe one
+        universal scalar objective because different tasks may value grammar,
+        history, and decoding differently.
+        """
+
+        weights = weights or {}
+        return sum(weights.get(name, 1.0) * value for name, value in self.components().items())
+
+    def dominates(self, other: "PresentationCost") -> bool:
+        """Whether this cost Pareto-dominates ``other``."""
+
+        mine = tuple(self.components().values())
+        theirs = tuple(other.components().values())
+        return all(a <= b for a, b in zip(mine, theirs)) and any(
+            a < b for a, b in zip(mine, theirs)
+        )

aeg_shakespeare/discovery/__init__.py

@@ -0,0 +1,53 @@
+"""Process-first representation discovery backends."""
+
+from .coefficient_extension import factor_process_relation_over_extension
+from .polynomial import (
+    ObservableQuotient,
+    ObservableRelation,
+    PolynomialInvariant,
+    PolynomialInvariantDiscovery,
+    PolynomialObserverBasis,
+    discover_first_order_process_quotient,
+    discover_observable_relations,
+    discover_polynomial_invariants,
+    generate_polynomial_observer_basis,
+)
+from .selection import (
+    FirstOrderObservablePresentation,
+    search_first_order_process_quotients,
+    structural_first_order_quotient_cost,
+)
+from .structured import (
+    PairableAtom,
+    PairingConstruction,
+    PairingSpec,
+    StructuredObserverProposal,
+    StructuredObserverProposalResult,
+    euclidean_pairing,
+    generate_pairing_observers,
+    nonstationary_observer_proposals,
+)
+
+__all__ = [
+    "factor_process_relation_over_extension",
+    "ObservableQuotient",
+    "ObservableRelation",
+    "PolynomialInvariant",
+    "PolynomialInvariantDiscovery",
+    "PolynomialObserverBasis",
+    "discover_first_order_process_quotient",
+    "discover_observable_relations",
+    "discover_polynomial_invariants",
+    "generate_polynomial_observer_basis",
+    "FirstOrderObservablePresentation",
+    "search_first_order_process_quotients",
+    "structural_first_order_quotient_cost",
+    "PairableAtom",
+    "PairingConstruction",
+    "PairingSpec",
+    "StructuredObserverProposal",
+    "StructuredObserverProposalResult",
+    "euclidean_pairing",
+    "generate_pairing_observers",
+    "nonstationary_observer_proposals",
+]

aeg_shakespeare/discovery/coefficient_extension.py

@@ -0,0 +1,75 @@
+"""Explicit coefficient-language extensions for process-relation factorization.
+
+A discovered process relation is always meaningful before any root or spectral
+interpretation.  Sometimes a caller may nevertheless ask whether the same
+relation admits a finer factorization after enlarging the coefficient language.
+This module provides exactly that experiment and nothing more.
+
+It deliberately does not define eigenvalues, eigenspaces, a spectral theorem,
+or an automatic policy for choosing coefficient fields.  The extension is an
+explicit representation proposal supplied by the caller.
+"""
+
+from __future__ import annotations
+
+import sympy as sp
+
+from ..relations import ProcessPolynomialRelation
+
+
+def factor_process_relation_over_extension(
+    relation: ProcessPolynomialRelation,
+    extension,
+) -> tuple[ProcessPolynomialRelation, ...]:
+    """Factor ``relation`` after an explicit algebraic coefficient extension.
+
+    Parameters
+    ----------
+    relation:
+        The already-discovered constant-coefficient process relation.
+    extension:
+        A SymPy algebraic extension accepted by ``factor_list``; for example
+        ``sp.I`` for adjoining a square root of ``-1``.
+
+    Notes
+    -----
+    Multiplicity is retained inside each primary factor, matching the ordinary
+    Shakespeare relation-factor convention.  Returned factors are normalized
+    to monic process polynomials.  No semantic meaning is attached to their
+    roots by this routine.
+    """
+
+    if extension is None:
+        raise ValueError("an explicit coefficient extension is required")
+
+    symbol = sp.Symbol("_D")
+    expression = relation.as_expr(symbol)
+    _unit, factors = sp.factor_list(
+        expression,
+        symbol,
+        extension=extension,
+    )
+    if not factors:
+        return (relation,)
+
+    result: list[ProcessPolynomialRelation] = []
+    for factor, multiplicity in factors:
+        primary = sp.Poly(
+            sp.expand(factor**multiplicity),
+            symbol,
+            extension=extension,
+        ).monic()
+        coefficients = tuple(
+            sp.simplify(value)
+            for value in reversed(primary.all_coeffs())
+        )
+        result.append(ProcessPolynomialRelation(coefficients))
+
+    original = sp.Poly(expression, symbol, extension=extension).monic().as_expr()
+    rebuilt = sp.expand(
+        sp.prod(factor.as_expr(symbol) for factor in result)
+    )
+    if sp.simplify(sp.expand(original - rebuilt)) != 0:
+        raise AssertionError("coefficient-extension factorization certificate failed")
+
+    return tuple(result)