aspalchemy 1.0.0__py3-none-any.whl

aspalchemy/__init__.py

@@ -0,0 +1,171 @@
+"""
+ASPAlchemy: A Python library for building clingo ASP (Answer Set Programming) programs
+with a clean, object-oriented interface.
+"""
+
+from .aggregates import (
+    Aggregate,
+    Count,
+    Max,
+    Min,
+    Sum,
+    SumPlus,
+)
+from .choice import CardinalityType, Choice
+from .clingo_handler import ClingoMessage, LogLevel
+from .conditional_literal import ConditionalLiteral
+from .conditioned_element import ConditionedElement, ConditionType
+from .core import (
+    ANY,
+    INF,
+    SUP,
+    BasicTerm,
+    ComparableTerm,
+    Comparison,
+    Compl,
+    ConstantBase,
+    DefaultNegation,
+    DefinedConstant,
+    ExplicitPool,
+    Expression,
+    Infimum,
+    Negatable,
+    Not,
+    Number,
+    Pool,
+    PredicateOccurrence,
+    RangePool,
+    RenderingContext,
+    String,
+    Supremum,
+    Term,
+    V,
+    Value,
+    Variable,
+    Vars,
+    pool,
+)
+from .exceptions import ASPAlchemyError, GroundingError, UnsatisfiableError
+from .operators import ComparisonOperator, Operation
+from .optimization import OptStrategy
+from .predicate import Field, FieldAsTermType, NegatedSignature, Predicate, PredicateField, TupleTermType
+from .program_elements import ProgramElement, RenderedLine
+from .segment import Segment, When
+from .solve_result import (
+    AtomCollection,
+    BraveConsequences,
+    CautiousConsequences,
+    Consequences,
+    CostedModel,
+    Model,
+    OptimizeSteps,
+    Optimum,
+    PredicateTypes,
+    RefinementSteps,
+    Search,
+    SolveResult,
+    convert_predicate_to_symbol,
+    convert_symbol_to_predicate,
+)
+from .solver import ASPProgram, GroundedProgram, SignatureGrounding
+from .source_location import (
+    SourceLocation,
+    attribute_to_caller,
+    capture_location,
+    location_override,
+    register_skip_package,
+)
+from .version import __version__
+
+__all__ = [  # noqa: RUF022 (categorized deliberately, not sorted)
+    # The program and its results
+    "ASPProgram",
+    "Segment",
+    "When",
+    "GroundedProgram",
+    "SignatureGrounding",
+    "SolveResult",
+    "Model",
+    "CostedModel",
+    "AtomCollection",
+    "Consequences",
+    "BraveConsequences",
+    "CautiousConsequences",
+    "RefinementSteps",
+    "OptimizeSteps",
+    "Optimum",
+    "OptStrategy",
+    "Search",
+    "LogLevel",
+    "ClingoMessage",
+    "ASPAlchemyError",
+    "GroundingError",
+    "UnsatisfiableError",
+    "RenderedLine",
+    # Source locations (diagnostics point at the authoring Python line)
+    "SourceLocation",
+    "capture_location",
+    "register_skip_package",
+    "attribute_to_caller",
+    "location_override",
+    # Declaring predicates
+    "Predicate",
+    "NegatedSignature",
+    "Field",
+    "PredicateField",
+    # Rule-building objects
+    "Variable",
+    "ANY",
+    "V",
+    "Vars",
+    "Choice",
+    "ConditionalLiteral",
+    "RangePool",
+    "ExplicitPool",
+    "SUP",
+    "INF",
+    # Aggregates
+    "Count",
+    "Sum",
+    "SumPlus",
+    "Min",
+    "Max",
+    # Rule-building utilities
+    "pool",
+    "Not",
+    "Compl",
+    # Hierarchy types: these appear in public signatures and return types —
+    # annotate with them; you rarely construct them directly
+    "ConditionType",
+    "ConditionedElement",
+    "TupleTermType",
+    "CardinalityType",
+    "PredicateTypes",
+    "FieldAsTermType",
+    "PredicateOccurrence",
+    "Term",
+    "BasicTerm",
+    "Value",
+    "ConstantBase",
+    "ComparableTerm",
+    "Negatable",
+    "ProgramElement",
+    "Expression",
+    "Comparison",
+    "ComparisonOperator",
+    "Operation",
+    "RenderingContext",
+    "DefaultNegation",
+    "DefinedConstant",
+    "Aggregate",
+    "Pool",
+    "Number",
+    "String",
+    "Supremum",
+    "Infimum",
+    # Interop with raw clingo symbols
+    "convert_predicate_to_symbol",
+    "convert_symbol_to_predicate",
+    # Metadata
+    "__version__",
+]

aspalchemy/aggregates.py

@@ -0,0 +1,230 @@
+from abc import ABC
+from enum import StrEnum
+from typing import ClassVar, Self
+
+from aspalchemy.conditioned_element import ConditionedElement, ConditionType, FreezableBuilder
+from aspalchemy.core import (
+    AggregateBase,
+    ExtremeConstant,
+    PredicateOccurrence,
+    RenderingContext,
+    String,
+)
+from aspalchemy.predicate import Predicate, TupleTermType, coerce_tuple_term
+
+
+class AggregateType(StrEnum):
+    """Enum for the different types of aggregate functions available in ASP."""
+
+    COUNT = "#count"
+    SUM = "#sum"
+    SUM_PLUS = "#sum+"
+    MIN = "#min"
+    MAX = "#max"
+
+
+class Aggregate(FreezableBuilder, AggregateBase, ABC):
+    """
+    Abstract base class for aggregates in ASP programs.
+
+    Aggregates calculate values over sets of elements, used in expressions like
+    #count{ X : p(X) } = 3 or #sum{ W,X : p(X,W) } > 10.
+
+    An aggregate is a mutable builder until a rule captures it, which
+    freezes it. A frozen aggregate is a value: build once, use in as many
+    rules as you like (capture may be transitive, through a comparison
+    holding the aggregate). Only mutation is fenced (it would silently
+    rewrite every rule that holds the builder).
+
+    BANDED tests (count between 2 and 4): write two comparisons over the
+    aggregate — Count(...) >= 2, Count(...) <= 4 — which grounds to the
+    same solver input as gringo's two-guard interval literal (verified at
+    the aspif level; the rendered text repeats the elements, the ground
+    representation does not). Do NOT bind-then-compare
+    (N == Count(...), N >= 2, N <= 4) when the band is wide: gringo
+    grounds one aggregate body per feasible N, multiplying the solver
+    input by the band width.
+    """
+
+    # Set by subclasses to specify which aggregate function to use
+    _AGGREGATE_TYPE: ClassVar[AggregateType]
+
+    _RECEIPT_NOUN = "aggregate"
+
+    def __init__(
+        self,
+        element: TupleTermType | tuple[TupleTermType, ...],
+        condition: ConditionType | list[ConditionType] | None = None,
+    ):
+        """
+        Create an aggregate with an initial element; see add() for further elements.
+
+        Args:
+            element: The value, predicate, or tuple to be aggregated
+            condition: Condition(s) determining when the element is included
+                      If None, it's an unconditional element
+        """
+        self._elements: list[ConditionedElement] = []
+        self.add(element, condition)
+
+    def add(
+        self,
+        element: TupleTermType | tuple[TupleTermType, ...],
+        condition: ConditionType | list[ConditionType] | None = None,
+    ) -> Self:
+        """
+        Add an element with optional condition(s); returns self for chaining.
+
+        Args:
+            element: The value, predicate, or tuple to be aggregated
+            condition: Condition(s) determining when the element is included
+                      If None, it's an unconditional element
+
+        Example:
+            >>> from aspalchemy import Variable
+            >>> X, Y, Z, W = (Variable(n) for n in "XYZW")
+            >>> p, q, r = (Predicate.define(name, ["x"]) for name in "pqr")
+            >>> Count(X).add(Y, p(x=Y)).add((Z, W), [q(x=Z), r(x=W)]).render()
+            '#count{ X; Y : p(Y); Z, W : q(Z), r(W) }'
+        """
+        self._require_mutable()
+        raw_tuple = element if isinstance(element, tuple) else (element,)
+        if not raw_tuple:
+            raise ValueError(
+                f"An aggregate element tuple cannot be empty: gringo ignores the element "
+                f"(#min/#max) or counts the bare empty tuple (#count gives 0/1, an existence "
+                f"test) — neither is a {self._AGGREGATE_TYPE.value} over anything. Aggregate "
+                f"over a term, e.g. {self._AGGREGATE_TYPE.value}{{ X : p(X) }}."
+            )
+        element_tuple = tuple(coerce_tuple_term(item, "Aggregate") for item in raw_tuple)
+
+        # Per-class: #sum/#sum+ SUM the first tuple term, so a literal String
+        # (or #sup/#inf) there draws gringo's "tuple ignored" info at ground —
+        # weights are integer-valued. Min/Max/Count order terms and take
+        # strings (and the ordering's end markers) legally.
+        if self._AGGREGATE_TYPE in (AggregateType.SUM, AggregateType.SUM_PLUS):
+            if isinstance(element_tuple[0], String):
+                raise TypeError(
+                    f"{self._AGGREGATE_TYPE.value} weights are integer-valued; the first tuple term "
+                    f"{element_tuple[0].render()} is a String, which gringo silently ignores. For "
+                    f"term-ordered aggregation over strings use Min/Max, or Count for cardinality."
+                )
+            if isinstance(element_tuple[0], ExtremeConstant):
+                raise TypeError(
+                    f"{self._AGGREGATE_TYPE.value} weights are integer-valued, got "
+                    f"{element_tuple[0].render()} as the first tuple term."
+                )
+            if isinstance(element_tuple[0], Predicate):
+                raise TypeError(
+                    f"{self._AGGREGATE_TYPE.value} weights are integer-valued; the first tuple "
+                    f"term {element_tuple[0].render()} is a predicate, which gringo silently "
+                    f"ignores (tuple ignored). Lead the tuple with the weight."
+                )
+        self._elements.append(ConditionedElement(element_tuple, condition, "aggregate"))
+
+        return self
+
+    @property
+    def elements(self) -> list[ConditionedElement]:
+        """The elements of this aggregate (a defensive copy of the list)."""
+        return self._elements.copy()
+
+    @property
+    def is_grounded(self) -> bool:
+        """
+        Grounded means NO variables anywhere, construct-local ones included:
+        #count{ X : p(X) } reports False even though X is local in ASP
+        semantics — the same strict reading every Term uses.
+        """
+        return all(element.is_grounded for element in self._elements)
+
+    def render(self, context: RenderingContext = RenderingContext.DEFAULT) -> str:
+        elements_str = "; ".join(element.render() for element in self._elements)
+
+        return f"{self._AGGREGATE_TYPE.value}{{ {elements_str} }}"
+
+    def __str__(self) -> str:
+        return self.render()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.render()!r})"
+
+    def validate_in_context(self, is_in_head: bool) -> None:
+        """Aggregates are only valid inside comparisons: always raises."""
+        raise ValueError(
+            "Aggregates must be used in comparisons (e.g., #count{ ... } > 0) "
+            "and cannot appear directly in rule heads or bodies"
+        )
+
+    def collect_defined_constants(self) -> set[str]:
+        constants: set[str] = set()
+
+        for element in self._elements:
+            constants.update(element.collect_defined_constants())
+
+        return constants
+
+    def collect_variables(self) -> set[str]:
+        variables: set[str] = set()
+
+        for element in self._elements:
+            variables.update(element.collect_variables())
+
+        return variables
+
+    def collect_predicate_occurrences(self, *, as_argument: bool) -> set[PredicateOccurrence]:
+        # Tuple terms sit in argument positions (data); conditions hold real
+        # atoms in the aggregate's own position
+        occurrences: set[PredicateOccurrence] = set()
+        for element in self._elements:
+            for target in element.targets:
+                occurrences.update(target.collect_predicate_occurrences(as_argument=True))
+            for condition in element.conditions:
+                occurrences.update(condition.collect_predicate_occurrences(as_argument=as_argument))
+        return occurrences
+
+
+class Count(Aggregate):
+    """#count: the number of distinct matching tuples, e.g. #count{ X : p(X) } = 3."""
+
+    _AGGREGATE_TYPE = AggregateType.COUNT
+
+
+class Sum(Aggregate):
+    """
+    #sum: the sum of weights over distinct matching tuples, e.g. #sum{ W,X : p(X,W) } > 10.
+
+    The first element in each tuple is the weight.
+    """
+
+    _AGGREGATE_TYPE = AggregateType.SUM
+
+
+class SumPlus(Aggregate):
+    """
+    #sum+: like Sum, but negative weights are treated as zero.
+
+    The first element in each tuple is the weight.
+    """
+
+    _AGGREGATE_TYPE = AggregateType.SUM_PLUS
+
+
+class Min(Aggregate):
+    """
+    #min: the minimum value over distinct matching tuples, e.g. #min{ W,X : p(X,W) } < 5.
+
+    The first element in each tuple is the value.
+    """
+
+    _AGGREGATE_TYPE = AggregateType.MIN
+
+
+class Max(Aggregate):
+    """
+    #max: the maximum value over distinct matching tuples, e.g. #max{ W,X : p(X,W) } < 100.
+
+    The first element in each tuple is the value.
+    """
+
+    _AGGREGATE_TYPE = AggregateType.MAX

aspalchemy/choice.py

@@ -0,0 +1,281 @@
+from typing import Self
+
+from aspalchemy.conditioned_element import ConditionedElement, ConditionType, FreezableBuilder
+from aspalchemy.core import (
+    Expression,
+    ExtremeConstant,
+    Number,
+    PredicateOccurrence,
+    RenderingContext,
+    String,
+    Term,
+    Value,
+    Variable,
+    negated_literal_value,
+)
+from aspalchemy.predicate import Predicate
+
+type CardinalityType = int | Value | Expression
+
+
+class Choice(FreezableBuilder, Term):
+    """
+    Represents a choice rule in ASP programs.
+
+    Choice rules in ASP allow for specifying sets of atoms from which some
+    subset can be chosen to be true, optionally with cardinality constraints.
+
+    Examples in ASP syntax:
+    - { p(X) : q(X) }
+    - 2 { p(X) : q(X) } 4
+    - { p(X) : q(X) } = 3
+
+    A Choice is a mutable builder until a rule captures it, which freezes
+    it. A frozen Choice is a value: further rules may capture it too — the
+    same choice under different bodies — and it renders identically in
+    each. Only mutation is fenced (it would silently rewrite every rule
+    that holds the builder).
+    """
+
+    _RECEIPT_NOUN = "Choice"
+
+    def __init__(
+        self,
+        element: Predicate,
+        condition: ConditionType | list[ConditionType] | None = None,
+    ):
+        """
+        Create a choice rule with an initial element; see add() for further elements.
+
+        Args:
+            element: The predicate that can be chosen
+            condition: Condition(s) determining when the element is considered
+                      If None, it's an unconditional choice
+        """
+        self._elements: list[ConditionedElement] = []
+        self._min_cardinality: None | Value | Expression = None
+        self._max_cardinality: None | Value | Expression = None
+
+        self.add(element, condition)
+
+    def add(
+        self,
+        element: Predicate,
+        condition: ConditionType | list[ConditionType] | None = None,
+    ) -> Self:
+        """
+        Add another element with optional condition(s); returns self for chaining.
+
+        Args:
+            element: The predicate that can be chosen
+            condition: Condition(s) determining when the element is considered
+                      If None, it's an unconditional choice
+
+        Example:
+            >>> from aspalchemy import Predicate, Variable
+            >>> X = Variable("X")
+            >>> p, q, r, s, t, u = (Predicate.define(name, ["x"]) for name in "pqrstu")
+            >>> Choice(p(x=X)).add(q(x=X), r(x=X)).add(s(x=X), [t(x=X), u(x=X)]).render()
+            '{ p(X); q(X) : r(X); s(X) : t(X), u(X) }'
+        """
+        self._require_mutable()
+        if not isinstance(element, Predicate):
+            raise TypeError(f"Choice element must be a Predicate, got {type(element).__name__}")
+
+        self._elements.append(ConditionedElement((element,), condition, "choice"))
+
+        return self
+
+    @staticmethod
+    def _validate_cardinality(count: int | Value | Expression, description: str) -> Value | Expression:
+        """Validate a cardinality value, coercing ints to Number; raises on bad type or negative int."""
+        if not isinstance(count, (int, Value, Expression)):
+            raise TypeError(f"{description} must be an integer, Value, or Expression, got {type(count).__name__}")
+
+        # Reject string constants which don't make sense for cardinality
+        if isinstance(count, String):
+            raise TypeError(f"{description} cannot be a String")
+        if isinstance(count, Variable) and count.is_anonymous:
+            raise ValueError(
+                f"{description} cannot be '_': an anonymous bound binds nothing, and "
+                f"gringo rejects the rule as unsafe. Use a named Variable bound in the body."
+            )
+        if isinstance(count, ExtremeConstant):
+            raise TypeError(f"{description} must be integer-valued, got {count.render()}")
+
+        count = Number(count) if isinstance(count, int) else count
+        # Checked after coercion so Number(-1) is caught the same as -1;
+        # the literal spelling -Number(1) is caught the same way
+        if isinstance(count, Number) and count.value < 0:
+            raise ValueError(f"{description} must be non-negative, got {count.value}")
+        if (folded := negated_literal_value(count)) is not None and folded < 0:
+            raise ValueError(f"{description} must be non-negative, got {folded}")
+
+        return count
+
+    @staticmethod
+    def _check_cardinality_possible(minimum: Value | Expression | None, maximum: Value | Expression | None) -> None:
+        """Reject statically impossible bounds; renders fine but is silently UNSAT."""
+        if isinstance(minimum, Number) and isinstance(maximum, Number) and minimum.value > maximum.value:
+            raise ValueError(f"Choice cardinality is impossible: at_least({minimum.value}) > at_most({maximum.value})")
+
+    def exactly(self, count: CardinalityType) -> Self:
+        """
+        Set the exact cardinality (min = max = count); returns self for chaining.
+
+        Raises ValueError if cardinality constraints are already set.
+        """
+        self._require_mutable()
+        count = self._validate_cardinality(count, "Exact cardinality")
+
+        if self._min_cardinality is not None or self._max_cardinality is not None:
+            raise ValueError("Cardinality constraints are already set")
+
+        self._min_cardinality = count
+        self._max_cardinality = count
+
+        return self
+
+    def at_least(self, count: CardinalityType) -> Self:
+        """
+        Set the minimum cardinality; returns self for chaining.
+
+        Raises ValueError if minimum cardinality is already set.
+        """
+        self._require_mutable()
+        count = self._validate_cardinality(count, "Minimum cardinality")
+
+        if self._min_cardinality is not None:
+            raise ValueError("Minimum cardinality is already set")
+        self._check_cardinality_possible(minimum=count, maximum=self._max_cardinality)
+
+        self._min_cardinality = count
+
+        return self
+
+    def at_most(self, count: CardinalityType) -> Self:
+        """
+        Set the maximum cardinality; returns self for chaining.
+
+        Raises ValueError if maximum cardinality is already set.
+        """
+        self._require_mutable()
+        count = self._validate_cardinality(count, "Maximum cardinality")
+
+        if self._max_cardinality is not None:
+            raise ValueError("Maximum cardinality is already set")
+        self._check_cardinality_possible(minimum=self._min_cardinality, maximum=count)
+
+        self._max_cardinality = count
+
+        return self
+
+    @property
+    def elements(self) -> list[ConditionedElement]:
+        """The elements of this choice rule (a defensive copy of the list)."""
+        return self._elements.copy()
+
+    @property
+    def min_cardinality(self) -> Value | Expression | None:
+        """The minimum cardinality constraint, or None if not set."""
+        return self._min_cardinality
+
+    @property
+    def max_cardinality(self) -> Value | Expression | None:
+        """The maximum cardinality constraint, or None if not set."""
+        return self._max_cardinality
+
+    @property
+    def is_grounded(self) -> bool:
+        """
+        Grounded means NO variables anywhere, construct-local ones included:
+        {X : p(X)} reports False even though X is local in ASP semantics —
+        the same strict reading every Term uses.
+        """
+        for element in self._elements:
+            if not element.is_grounded:
+                return False
+
+        if self.min_cardinality and not self.min_cardinality.is_grounded:
+            return False
+        if self.max_cardinality and not self.max_cardinality.is_grounded:  # noqa: SIM103
+            return False
+
+        return True
+
+    def render(self, context: RenderingContext = RenderingContext.DEFAULT) -> str:
+        prefix = ""
+        suffix = ""
+
+        if self.min_cardinality and self.max_cardinality:
+            min_str = self.min_cardinality.render()
+            max_str = self.max_cardinality.render()
+
+            if min_str == max_str:
+                # Exact cardinality: { ... } = n
+                suffix = f" = {min_str}"
+            else:
+                # Range cardinality: n { ... } m
+                prefix = f"{min_str} "
+                suffix = f" {max_str}"
+        elif self.min_cardinality:
+            # Only minimum: n { ... }
+            min_str = self.min_cardinality.render()
+            prefix = f"{min_str} "
+        elif self.max_cardinality:
+            # Only maximum: { ... } m
+            max_str = self.max_cardinality.render()
+            suffix = f" {max_str}"
+
+        elements_str = "; ".join(element.render() for element in self._elements)
+
+        return f"{prefix}{{ {elements_str} }}{suffix}"
+
+    def __str__(self) -> str:
+        return self.render()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.render()!r})"
+
+    def validate_in_context(self, is_in_head: bool) -> None:
+        """Choice rules are head-only: raises in bodies, teaching the body spelling."""
+        if not is_in_head:
+            raise ValueError(
+                "A Choice belongs in a rule head, where braces CHOOSE. In a body, "
+                "clingo's braces mean a cardinality TEST — a different construct "
+                "aspalchemy spells as a Count comparison: Count(X, condition=...) >= n."
+            )
+
+    def collect_defined_constants(self) -> set[str]:
+        constants = set()
+
+        for element in self._elements:
+            constants.update(element.collect_defined_constants())
+
+        if self.min_cardinality:
+            constants.update(self.min_cardinality.collect_defined_constants())
+
+        if self.max_cardinality:
+            constants.update(self.max_cardinality.collect_defined_constants())
+
+        return constants
+
+    def collect_variables(self) -> set[str]:
+        variables = set()
+
+        for element in self._elements:
+            variables.update(element.collect_variables())
+
+        if self.min_cardinality is not None:
+            variables.update(self.min_cardinality.collect_variables())
+
+        if self.max_cardinality is not None:
+            variables.update(self.max_cardinality.collect_variables())
+
+        return variables
+
+    def collect_predicate_occurrences(self, *, as_argument: bool) -> set[PredicateOccurrence]:
+        occurrences: set[PredicateOccurrence] = set()
+        for element in self._elements:
+            occurrences.update(element.collect_predicate_occurrences(as_argument=as_argument))
+        return occurrences