process-geometry 0.0.3__py3-none-any.whl

aeg_shakespeare/discovery/polynomial.py

@@ -0,0 +1,342 @@
+"""Bounded polynomial discovery for process observables, invariants, and quotients.
+
+Mathematical pressure
+---------------------
+The first Shakespeare layers can preserve ordered histories, exact constraints,
+finite grammars, and presentation costs once a useful representation has been
+proposed. A remaining gap appears earlier: classical analysis often hands the
+solver a good observable or first integral before the real calculation begins.
+
+This module provides a deliberately small exact backend for removing part of
+that prior choice. It searches a bounded polynomial observer grammar, discovers
+first integrals as null directions of the represented process modulo declared
+constraints, and eliminates source assignments to expose exact relations among
+chosen process observables.
+
+The polynomial grammar is a search proposal language, not a claim that every
+useful observer is polynomial. Likewise Groebner elimination and exact linear
+algebra are discovery/certificate backends rather than Shakespeare's ontology
+of process equality.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+import sympy as sp
+
+from ..core import homogeneous_monomials
+from ..presentation.constraints import AlgebraicConstraintSet
+from ..process.local import ProcessSystem
+
+
+def _polynomial_dict(
+    expr: sp.Expr,
+    variables: Sequence[sp.Symbol],
+) -> dict[tuple[int, ...], sp.Expr]:
+    try:
+        return sp.Poly(
+            sp.expand(sp.sympify(expr)),
+            *variables,
+            domain="EX",
+        ).as_dict()
+    except sp.PolynomialError as exc:
+        raise ValueError(
+            "discovery expressions must be polynomial in the declared variables"
+        ) from exc
+
+
+def _coefficient_matrix(
+    expressions: Sequence[sp.Expr],
+    variables: Sequence[sp.Symbol],
+) -> sp.Matrix:
+    dictionaries = [_polynomial_dict(expression, variables) for expression in expressions]
+    monomials = sorted(
+        set().union(*(set(dictionary) for dictionary in dictionaries)),
+        reverse=True,
+    )
+    if not monomials:
+        return sp.zeros(0, len(expressions))
+    return sp.Matrix(
+        [
+            [dictionary.get(monomial, sp.S.Zero) for dictionary in dictionaries]
+            for monomial in monomials
+        ]
+    )
+
+
+def _independent_polynomials(
+    expressions: Sequence[sp.Expr],
+    variables: Sequence[sp.Symbol],
+) -> tuple[sp.Expr, ...]:
+    basis: list[sp.Expr] = []
+    rank = 0
+    for expression in expressions:
+        expression = sp.expand(sp.sympify(expression))
+        if expression == 0:
+            continue
+        candidate = basis + [expression]
+        candidate_rank = int(_coefficient_matrix(candidate, variables).rank())
+        if candidate_rank > rank:
+            basis.append(expression)
+            rank = candidate_rank
+    return tuple(basis)
+
+
+@dataclass(frozen=True)
+class PolynomialObserverBasis:
+    expressions: tuple[sp.Expr, ...]
+    max_degree: int
+    raw_candidate_count: int
+    quotient_reduced: bool
+
+    def __post_init__(self) -> None:
+        if self.max_degree < 0:
+            raise ValueError("max_degree must be non-negative")
+        if self.raw_candidate_count < len(self.expressions):
+            raise ValueError(
+                "raw_candidate_count cannot be smaller than the retained basis"
+            )
+
+
+def generate_polynomial_observer_basis(
+    assignments: Sequence[sp.Symbol],
+    *,
+    max_degree: int,
+    constraints: AlgebraicConstraintSet | None = None,
+    include_constant: bool = False,
+) -> PolynomialObserverBasis:
+    if max_degree < 0:
+        raise ValueError("max_degree must be non-negative")
+    assignments = tuple(assignments)
+    if not assignments and max_degree > 0:
+        raise ValueError("at least one assignment is required for positive degree")
+
+    if constraints is not None:
+        unknown = set(assignments) - set(constraints.variables)
+        if unknown:
+            raise ValueError(
+                "assignments missing from constraint variables: "
+                f"{sorted(map(str, unknown))}"
+            )
+        coordinate_variables = constraints.variables
+    else:
+        coordinate_variables = assignments
+
+    raw: list[sp.Expr] = []
+    start_degree = 0 if include_constant else 1
+    for degree in range(start_degree, max_degree + 1):
+        raw.extend(homogeneous_monomials(assignments, degree))
+
+    reduced = [
+        constraints.reduce(expression)
+        if constraints is not None
+        else sp.expand(expression)
+        for expression in raw
+    ]
+    independent = _independent_polynomials(reduced, coordinate_variables)
+    return PolynomialObserverBasis(
+        expressions=independent,
+        max_degree=max_degree,
+        raw_candidate_count=len(raw),
+        quotient_reduced=constraints is not None,
+    )
+
+
+@dataclass(frozen=True)
+class PolynomialInvariant:
+    expression: sp.Expr
+    coordinates: tuple[sp.Expr, ...]
+    derivative_remainder: sp.Expr
+
+    @property
+    def certified(self) -> bool:
+        return sp.expand(self.derivative_remainder) == 0
+
+
+@dataclass(frozen=True)
+class PolynomialInvariantDiscovery:
+    observer_basis: PolynomialObserverBasis
+    invariants: tuple[PolynomialInvariant, ...]
+    derivative_rank: int
+
+    @property
+    def nullity(self) -> int:
+        return len(self.observer_basis.expressions) - self.derivative_rank
+
+
+def discover_polynomial_invariants(
+    system: ProcessSystem,
+    *,
+    constraints: AlgebraicConstraintSet | None = None,
+    max_degree: int,
+    include_constant: bool = True,
+) -> PolynomialInvariantDiscovery:
+    basis = generate_polynomial_observer_basis(
+        system.assignments,
+        max_degree=max_degree,
+        constraints=constraints,
+        include_constant=include_constant,
+    )
+    coordinate_variables = constraints.variables if constraints is not None else system.assignments
+
+    derivatives = tuple(
+        constraints.reduce(system.derive(expression))
+        if constraints is not None
+        else sp.expand(system.derive(expression))
+        for expression in basis.expressions
+    )
+    derivative_matrix = _coefficient_matrix(derivatives, coordinate_variables)
+    assignment_set = set(system.assignments)
+
+    invariants: list[PolynomialInvariant] = []
+    for vector in derivative_matrix.nullspace():
+        coordinates = tuple(sp.simplify(value) for value in vector)
+        expression = sp.expand(
+            sum(
+                coefficient * basis_expression
+                for coefficient, basis_expression in zip(coordinates, basis.expressions)
+            )
+        )
+        reduced_expression = constraints.reduce(expression) if constraints is not None else expression
+        if reduced_expression.free_symbols.isdisjoint(assignment_set):
+            continue
+        derivative_remainder = (
+            constraints.reduce(system.derive(expression))
+            if constraints is not None
+            else sp.expand(system.derive(expression))
+        )
+        invariants.append(
+            PolynomialInvariant(
+                expression=sp.factor(reduced_expression),
+                coordinates=coordinates,
+                derivative_remainder=sp.factor(derivative_remainder),
+            )
+        )
+
+    return PolynomialInvariantDiscovery(
+        observer_basis=basis,
+        invariants=tuple(invariants),
+        derivative_rank=int(derivative_matrix.rank()),
+    )
+
+
+@dataclass(frozen=True)
+class ObservableRelation:
+    relation: sp.Expr
+    pullback_remainder: sp.Expr
+
+    @property
+    def certified(self) -> bool:
+        return sp.expand(self.pullback_remainder) == 0
+
+
+@dataclass(frozen=True)
+class ObservableQuotient:
+    symbols: tuple[sp.Symbol, ...]
+    observables: tuple[sp.Expr, ...]
+    parameters: tuple[sp.Symbol, ...]
+    eliminated_variables: tuple[sp.Symbol, ...]
+    relations: tuple[ObservableRelation, ...]
+
+    @property
+    def complete_certificates(self) -> bool:
+        return all(relation.certified for relation in self.relations)
+
+
+def discover_observable_relations(
+    observables: Sequence[sp.Expr],
+    symbols: Sequence[sp.Symbol],
+    *,
+    constraints: AlgebraicConstraintSet,
+    source_variables: Sequence[sp.Symbol],
+    parameters: Sequence[sp.Symbol] = (),
+) -> ObservableQuotient:
+    observables = tuple(sp.expand(sp.sympify(item)) for item in observables)
+    symbols = tuple(symbols)
+    source_variables = tuple(source_variables)
+    parameters = tuple(parameters)
+
+    if not observables or len(observables) != len(symbols):
+        raise ValueError("observables and symbols must be non-empty and have equal length")
+    if len(set(symbols)) != len(symbols):
+        raise ValueError("observable symbols must be distinct")
+    if len(set(source_variables)) != len(source_variables):
+        raise ValueError("source variables must be distinct")
+    if len(set(parameters)) != len(parameters):
+        raise ValueError("parameters must be distinct")
+
+    constraint_variables = set(constraints.variables)
+    source_set = set(source_variables)
+    parameter_set = set(parameters)
+    symbol_set = set(symbols)
+    if source_set & parameter_set:
+        raise ValueError("source variables and parameters must be disjoint")
+    if symbol_set & constraint_variables:
+        raise ValueError("observable symbols must be fresh relative to constraint variables")
+    if source_set | parameter_set != constraint_variables:
+        missing = constraint_variables - (source_set | parameter_set)
+        extra = (source_set | parameter_set) - constraint_variables
+        raise ValueError(
+            "source_variables + parameters must partition constraint variables; "
+            f"missing={sorted(map(str, missing))}, extra={sorted(map(str, extra))}"
+        )
+
+    generator_order = source_variables + symbols + parameters
+    defining_relations = list(constraints.relations)
+    defining_relations.extend(
+        sp.expand(symbol - observable)
+        for symbol, observable in zip(symbols, observables)
+    )
+    try:
+        elimination_basis = sp.groebner(
+            defining_relations,
+            *generator_order,
+            order="lex",
+        )
+    except sp.PolynomialError as exc:
+        raise ValueError("observable elimination requires polynomial relations") from exc
+
+    substitutions = dict(zip(symbols, observables))
+    relation_certificates: list[ObservableRelation] = []
+    for polynomial in elimination_basis.polys:
+        relation = sp.expand(polynomial.as_expr())
+        if relation.free_symbols & source_set:
+            continue
+        if not relation.free_symbols & symbol_set:
+            continue
+        relation = sp.factor(relation)
+        pullback = sp.expand(relation.subs(substitutions))
+        relation_certificates.append(
+            ObservableRelation(
+                relation=relation,
+                pullback_remainder=sp.factor(constraints.reduce(pullback)),
+            )
+        )
+
+    return ObservableQuotient(
+        symbols=symbols,
+        observables=observables,
+        parameters=parameters,
+        eliminated_variables=source_variables,
+        relations=tuple(relation_certificates),
+    )
+
+
+def discover_first_order_process_quotient(
+    system: ProcessSystem,
+    observable: sp.Expr,
+    *,
+    observable_symbol: sp.Symbol,
+    derivative_symbol: sp.Symbol,
+    constraints: AlgebraicConstraintSet,
+    parameters: Sequence[sp.Symbol] = (),
+) -> ObservableQuotient:
+    return discover_observable_relations(
+        (sp.sympify(observable), system.derive(observable)),
+        (observable_symbol, derivative_symbol),
+        constraints=constraints,
+        source_variables=system.assignments,
+        parameters=parameters,
+    )

aeg_shakespeare/discovery/selection.py

@@ -0,0 +1,146 @@
+"""Costed search over first-order algebraic observer quotients.
+
+This module connects the discovery front-end to Shakespeare's multi-axis
+presentation search. The task here is deliberately narrow: among a
+caller-declared family of observer candidates, find those whose first process
+jet ``(F, D F)`` closes by certified algebraic relations on a declared leaf,
+and compare the resulting presentations without imposing a universal scalar
+objective.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+from typing import Callable, Sequence
+
+import sympy as sp
+
+from ..presentation.constraints import AlgebraicConstraintSet
+from ..presentation.search import (
+    PresentationCandidate,
+    PresentationCost,
+    PresentationSearchResult,
+    pareto_frontier,
+)
+from ..process.local import ProcessSystem
+from .polynomial import ObservableQuotient, discover_first_order_process_quotient
+
+
+@dataclass(frozen=True)
+class FirstOrderObservablePresentation:
+    """One observer together with its discovered first-order algebraic quotient."""
+
+    observable: sp.Expr
+    derivative: sp.Expr
+    quotient: ObservableQuotient
+
+    @property
+    def algebraically_closed(self) -> bool:
+        return bool(self.quotient.relations) and self.quotient.complete_certificates
+
+
+def _expression_complexity(expr: sp.Expr) -> float:
+    expr = sp.expand(sp.sympify(expr))
+    return float(int(sp.count_ops(expr, visual=False)) + 1)
+
+
+def _relation_complexity(
+    relation: sp.Expr,
+    variables: Sequence[sp.Symbol],
+) -> float:
+    """Transparent degree-plus-support proxy for one algebraic relation."""
+    try:
+        polynomial = sp.Poly(sp.expand(relation), *variables, domain="EX")
+    except sp.PolynomialError as exc:
+        raise ValueError("quotient relation must be polynomial") from exc
+    return float(int(polynomial.total_degree()) + len(polynomial.terms()))
+
+
+def structural_first_order_quotient_cost(
+    presentation: FirstOrderObservablePresentation,
+) -> PresentationCost:
+    """Default multi-axis cost for a first-order algebraic observer presentation."""
+    relation_variables = (
+        presentation.quotient.symbols + presentation.quotient.parameters
+    )
+    relation_cost = sum(
+        _relation_complexity(item.relation, relation_variables)
+        for item in presentation.quotient.relations
+    )
+    return PresentationCost(
+        grammar=(
+            _expression_complexity(presentation.observable)
+            + _expression_complexity(presentation.derivative)
+        ),
+        relations=float(relation_cost),
+        history=1.0,
+        decoder=0.0,
+        task_error=0.0 if presentation.algebraically_closed else math.inf,
+    )
+
+
+def _fresh_symbol(base: str, forbidden: set[sp.Symbol]) -> sp.Symbol:
+    candidate = sp.Symbol(base)
+    suffix = 0
+    while candidate in forbidden:
+        suffix += 1
+        candidate = sp.Symbol(f"{base}_{suffix}")
+    forbidden.add(candidate)
+    return candidate
+
+
+def search_first_order_process_quotients(
+    system: ProcessSystem,
+    observer_candidates: Sequence[sp.Expr],
+    *,
+    constraints: AlgebraicConstraintSet,
+    parameters: Sequence[sp.Symbol] = (),
+    cost_model: Callable[
+        [FirstOrderObservablePresentation], PresentationCost
+    ] | None = None,
+) -> PresentationSearchResult[FirstOrderObservablePresentation]:
+    """Compare candidate observers by certified first-order algebraic closure."""
+    observer_candidates = tuple(
+        sp.expand(sp.sympify(candidate)) for candidate in observer_candidates
+    )
+    if not observer_candidates:
+        raise ValueError("at least one observer candidate is required")
+
+    score = cost_model or structural_first_order_quotient_cost
+    forbidden = set(constraints.variables)
+    evaluated: list[PresentationCandidate[FirstOrderObservablePresentation]] = []
+
+    for index, observable in enumerate(observer_candidates):
+        observable_symbol = _fresh_symbol(f"U{index}", forbidden)
+        derivative_symbol = _fresh_symbol(f"Y{index}", forbidden)
+        quotient = discover_first_order_process_quotient(
+            system,
+            observable,
+            observable_symbol=observable_symbol,
+            derivative_symbol=derivative_symbol,
+            constraints=constraints,
+            parameters=parameters,
+        )
+        payload = FirstOrderObservablePresentation(
+            observable=observable,
+            derivative=system.derive(observable),
+            quotient=quotient,
+        )
+        evaluated.append(
+            PresentationCandidate(
+                payload=payload,
+                cost=score(payload),
+                sufficient=payload.algebraically_closed,
+                label=str(observable),
+                certificate=tuple(
+                    relation.relation for relation in quotient.relations
+                ),
+            )
+        )
+
+    evaluated_tuple = tuple(evaluated)
+    return PresentationSearchResult(
+        evaluated=evaluated_tuple,
+        pareto=pareto_frontier(evaluated_tuple),
+    )

aeg_shakespeare/discovery/structured.py

@@ -0,0 +1,201 @@
+"""Minimal structured-observer proposals for process discovery.
+
+This module is deliberately narrower than a general typed mathematical IR.
+The first calibration only needs one fact that bare scalar assignment symbols
+cannot express: several primitive objects may belong to the same pairable sort,
+and a caller-supplied pairing may turn two such objects into a scalar observer.
+
+The abstraction stops there.  It does not assume vector-space addition, scalar
+multiplication, bases, matrices, Fourier analysis, or a universal theory
+protocol.  Those structures should enter only when later mathematical
+vignettes force them.
+
+A proposal retains two layers at once:
+
+* ``construction`` records the structured recipe, e.g. ``pair(q,e)``;
+* ``expression`` is the scalar backend lowering consumed by the existing
+  polynomial discovery layer.
+
+Thus a coordinate expression such as ``qy`` need not become the ontology of
+an observer whose actual construction is ``pair(q,e)``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import combinations_with_replacement, product
+from typing import Callable, Sequence
+
+import sympy as sp
+
+
+@dataclass(frozen=True)
+class PairableAtom:
+    """One named structured atom with a backend component realization.
+
+    ``sort`` is intentionally only an equality tag.  The current layer knows no
+    axioms associated with that tag; it merely prevents a pairing from being
+    applied across incompatible primitive kinds.
+    """
+
+    name: str
+    components: tuple[sp.Expr, ...]
+    sort: str = "pairable"
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("structured atom name must be non-empty")
+        if not self.sort:
+            raise ValueError("structured atom sort must be non-empty")
+        components = tuple(sp.expand(sp.sympify(item)) for item in self.components)
+        if not components:
+            raise ValueError("pairable atom requires at least one component")
+        object.__setattr__(self, "components", components)
+
+
+@dataclass(frozen=True)
+class PairingSpec:
+    """A caller-declared scalar pairing on one structured sort.
+
+    ``lower`` receives the two component tuples and returns the exact scalar
+    backend expression.  Symmetry affects construction enumeration only; no
+    bilinearity, positivity, or other vector-space law is inferred.
+    """
+
+    name: str
+    sort: str
+    lower: Callable[[tuple[sp.Expr, ...], tuple[sp.Expr, ...]], sp.Expr]
+    symmetric: bool = True
+    cost: float = 1.0
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("pairing name must be non-empty")
+        if not self.sort:
+            raise ValueError("pairing sort must be non-empty")
+        if self.cost < 0:
+            raise ValueError("pairing cost must be non-negative")
+
+
+@dataclass(frozen=True)
+class PairingConstruction:
+    """Construction certificate for one scalar observer proposal."""
+
+    pairing_name: str
+    left_name: str
+    right_name: str
+    cost: float
+
+    def recipe(self) -> str:
+        return f"{self.pairing_name}({self.left_name},{self.right_name})"
+
+
+@dataclass(frozen=True)
+class StructuredObserverProposal:
+    """A scalar backend expression together with its structured origin."""
+
+    expression: sp.Expr
+    construction: PairingConstruction
+
+    @property
+    def cost(self) -> float:
+        return self.construction.cost
+
+
+@dataclass(frozen=True)
+class StructuredObserverProposalResult:
+    proposals: tuple[StructuredObserverProposal, ...]
+    rejected: tuple[str, ...] = ()
+
+
+def euclidean_pairing(
+    *,
+    name: str = "pair",
+    sort: str = "euclidean",
+    cost: float = 1.0,
+) -> PairingSpec:
+    """Return the finite-coordinate Euclidean pairing used by calibrations.
+
+    This convenience constructor is a backend realization, not a declaration
+    that every pairable sort is Euclidean.
+    """
+
+    def lower(left: tuple[sp.Expr, ...], right: tuple[sp.Expr, ...]) -> sp.Expr:
+        if len(left) != len(right):
+            raise ValueError("pairing requires equal component dimensions")
+        return sp.expand(sum(a * b for a, b in zip(left, right)))
+
+    return PairingSpec(name=name, sort=sort, lower=lower, symmetric=True, cost=cost)
+
+
+def generate_pairing_observers(
+    atoms: Sequence[PairableAtom],
+    pairing: PairingSpec,
+) -> StructuredObserverProposalResult:
+    """Generate all bounded depth-one scalar observers from one pairing.
+
+    The caller supplies the primitive atoms and the pairing itself.  Shakespeare
+    supplies no vector-space laws beyond the explicitly declared symmetry used
+    to avoid duplicate recipes.
+    """
+
+    atoms = tuple(atoms)
+    if not atoms:
+        raise ValueError("at least one structured atom is required")
+
+    eligible = tuple(atom for atom in atoms if atom.sort == pairing.sort)
+    rejected = tuple(
+        f"{atom.name}: sort {atom.sort!r} is incompatible with pairing sort {pairing.sort!r}"
+        for atom in atoms
+        if atom.sort != pairing.sort
+    )
+    if not eligible:
+        return StructuredObserverProposalResult((), rejected)
+
+    pairs = (
+        combinations_with_replacement(eligible, 2)
+        if pairing.symmetric
+        else product(eligible, repeat=2)
+    )
+    proposals: list[StructuredObserverProposal] = []
+    for left, right in pairs:
+        try:
+            expression = sp.expand(
+                sp.sympify(pairing.lower(left.components, right.components))
+            )
+        except Exception as exc:  # caller pairing boundary
+            rejected += (f"{pairing.name}({left.name},{right.name}): {exc}",)
+            continue
+        proposals.append(
+            StructuredObserverProposal(
+                expression=expression,
+                construction=PairingConstruction(
+                    pairing_name=pairing.name,
+                    left_name=left.name,
+                    right_name=right.name,
+                    cost=float(pairing.cost),
+                ),
+            )
+        )
+
+    return StructuredObserverProposalResult(tuple(proposals), rejected)
+
+
+def nonstationary_observer_proposals(
+    system,
+    proposals: Sequence[StructuredObserverProposal],
+    *,
+    constraints,
+) -> tuple[StructuredObserverProposal, ...]:
+    """Keep proposals whose first process derivative survives the quotient.
+
+    This is a task filter, not an equality rule: stationary constructions remain
+    valid constructions, but they are insufficient for the present task of
+    finding a one-dimensional evolving observer.
+    """
+
+    return tuple(
+        proposal
+        for proposal in proposals
+        if not constraints.contains(system.derive(proposal.expression))
+    )