morphata 1.0.0__tar.gz

morphata-1.0.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.3
+Name: morphata
+Version: 1.0.0
+Summary: Flexible automata representations for regular and ω-regular languages.
+Author: Anand Balakrishnan
+Requires-Dist: typing-extensions
+Requires-Dist: lark
+Requires-Dist: logic-asts>=1.4.1
+Requires-Dist: networkx
+Requires-Dist: types-networkx
+Requires-Dist: attrs>=25.4.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Morphata
+
+Morphata is a Python library for constructing, manipulating, and translating
+automata over regular and omega-regular languages.
+It provides flexible graph-based representations for automata without committing
+to any specific model checking or monitoring algorithm.
+
+## Features
+
+- **Graph-based automata implementations**
+  - Nondeterministic Finite Automata (NFA) for finite words
+  - STREL automata for spatio-temporal specifications
+
+- **HOA format parser**
+  - Extended HOA v1 format with finite-word acceptance support
+  - Standard acceptance conditions:
+    Buchi, co-Buchi, Rabin, Streett, Parity, Muller
+  - Extension:
+    `Final(n)` operator for finite-word automata (not in standard HOA v1)
+  - Validation and error reporting
+
+- **Acceptance conditions**
+  - Expression algebra for omega-regular conditions
+  - Classical acceptance types (Buchi, generalized-Buchi, co-Buchi, Rabin,
+    Streett, Muller, Parity)
+  - Finite-word acceptance for regular languages
+
+- **Pure structural interfaces**
+  - Base automaton interfaces without weighted semantics
+  - NetworkX-based graph representations
+  - Clean separation from quantitative monitoring (provided by automatix)
+
+## Architecture
+
+Morphata serves as the foundation for the automatix library:
+
+- **morphata**:
+  Graph-based automata, HOA parsing, acceptance conditions
+- **automatix**:
+  Weighted automata over semirings (depends on morphata)
+- **algebraic**:
+  Pure semiring algebra (independent)
+
+This layered architecture allows morphata to be used independently for
+structural automata operations, or as a foundation for weighted semantics.
+
+## Installation
+
+Morphata is part of the automatix workspace.
+Install using uv:
+
+```bash
+uv pip install -e packages/morphata
+```
+
+## Quick Example
+
+```python
+from morphata.automata import NFA
+from logic_asts import base
+
+# Create an NFA
+nfa = NFA[str]()
+nfa.add_location(0, initial=True)
+nfa.add_location(1, final=True)
+
+# Add transition with guard
+guard_a = base.Variable("a")
+nfa.add_transition(0, 1, guard_a)
+
+# Use the automaton
+accepting, next_state = nfa({"a"}, nfa.initial_state)
+print(f"Accepting: {accepting}, Next state: {next_state}")
+```
+
+## HOA Parser Example
+
+### Standard HOA Format (Omega-Automata)
+
+```python
+from morphata.hoa.parser import parse
+
+hoa_string = """
+HOA: v1
+States: 2
+Start: 0
+acc-name: Buchi
+Acceptance: 1 Inf(0)
+AP: 1 "a"
+--BODY--
+State: 0
+  [0] 1
+State: 1 {0}
+  [t] 1
+--END--
+"""
+
+automaton = parse(hoa_string)
+print(f"Acceptance: {automaton.header.acc}")
+```
+
+### Extended Format: Finite-Word Acceptance
+
+Morphata extends the HOA v1 format with a `Final(n)` operator for finite-word
+automata.
+This is **not part of the standard HOA specification** but provides a natural
+way to express finite-word acceptance in the HOA syntax.
+
+```python
+from morphata.hoa.parser import parse
+
+finite_hoa = """
+HOA: v1
+States: 2
+Start: 0
+acc-name: Finite
+Acceptance: 1 Final(0)
+AP: 1 "a"
+--BODY--
+State: 0
+  [0] 1 {0}
+  [!0] 0
+State: 1
+  [t] 1
+--END--
+"""
+
+automaton = parse(finite_hoa)
+# Accepts finite words ending with 'a'
+```
+
+**Note**:
+The `Final(n)` operator semantics differ from `Fin(n)` and `Inf(n)`:
+- `Inf(n)`:
+  Accept if acceptance set n is visited **infinitely often** (omega-regular)
+- `Fin(n)`:
+  Accept if acceptance set n is visited **finitely often** (omega-regular)
+- `Final(n)`:
+  Accept if the run **ends in** a state marked with acceptance set n (regular)
+
+## Development
+
+Run tests:
+```bash
+python -m pytest packages/morphata/tests/ -v
+```
+
+Type checking:
+```bash
+python -m mypy packages/morphata/src/morphata/ --strict
+```
+
+## License
+
+Part of the automatix project.

morphata-1.0.0/README.md

@@ -0,0 +1,155 @@
+# Morphata
+
+Morphata is a Python library for constructing, manipulating, and translating
+automata over regular and omega-regular languages.
+It provides flexible graph-based representations for automata without committing
+to any specific model checking or monitoring algorithm.
+
+## Features
+
+- **Graph-based automata implementations**
+  - Nondeterministic Finite Automata (NFA) for finite words
+  - STREL automata for spatio-temporal specifications
+
+- **HOA format parser**
+  - Extended HOA v1 format with finite-word acceptance support
+  - Standard acceptance conditions:
+    Buchi, co-Buchi, Rabin, Streett, Parity, Muller
+  - Extension:
+    `Final(n)` operator for finite-word automata (not in standard HOA v1)
+  - Validation and error reporting
+
+- **Acceptance conditions**
+  - Expression algebra for omega-regular conditions
+  - Classical acceptance types (Buchi, generalized-Buchi, co-Buchi, Rabin,
+    Streett, Muller, Parity)
+  - Finite-word acceptance for regular languages
+
+- **Pure structural interfaces**
+  - Base automaton interfaces without weighted semantics
+  - NetworkX-based graph representations
+  - Clean separation from quantitative monitoring (provided by automatix)
+
+## Architecture
+
+Morphata serves as the foundation for the automatix library:
+
+- **morphata**:
+  Graph-based automata, HOA parsing, acceptance conditions
+- **automatix**:
+  Weighted automata over semirings (depends on morphata)
+- **algebraic**:
+  Pure semiring algebra (independent)
+
+This layered architecture allows morphata to be used independently for
+structural automata operations, or as a foundation for weighted semantics.
+
+## Installation
+
+Morphata is part of the automatix workspace.
+Install using uv:
+
+```bash
+uv pip install -e packages/morphata
+```
+
+## Quick Example
+
+```python
+from morphata.automata import NFA
+from logic_asts import base
+
+# Create an NFA
+nfa = NFA[str]()
+nfa.add_location(0, initial=True)
+nfa.add_location(1, final=True)
+
+# Add transition with guard
+guard_a = base.Variable("a")
+nfa.add_transition(0, 1, guard_a)
+
+# Use the automaton
+accepting, next_state = nfa({"a"}, nfa.initial_state)
+print(f"Accepting: {accepting}, Next state: {next_state}")
+```
+
+## HOA Parser Example
+
+### Standard HOA Format (Omega-Automata)
+
+```python
+from morphata.hoa.parser import parse
+
+hoa_string = """
+HOA: v1
+States: 2
+Start: 0
+acc-name: Buchi
+Acceptance: 1 Inf(0)
+AP: 1 "a"
+--BODY--
+State: 0
+  [0] 1
+State: 1 {0}
+  [t] 1
+--END--
+"""
+
+automaton = parse(hoa_string)
+print(f"Acceptance: {automaton.header.acc}")
+```
+
+### Extended Format: Finite-Word Acceptance
+
+Morphata extends the HOA v1 format with a `Final(n)` operator for finite-word
+automata.
+This is **not part of the standard HOA specification** but provides a natural
+way to express finite-word acceptance in the HOA syntax.
+
+```python
+from morphata.hoa.parser import parse
+
+finite_hoa = """
+HOA: v1
+States: 2
+Start: 0
+acc-name: Finite
+Acceptance: 1 Final(0)
+AP: 1 "a"
+--BODY--
+State: 0
+  [0] 1 {0}
+  [!0] 0
+State: 1
+  [t] 1
+--END--
+"""
+
+automaton = parse(finite_hoa)
+# Accepts finite words ending with 'a'
+```
+
+**Note**:
+The `Final(n)` operator semantics differ from `Fin(n)` and `Inf(n)`:
+- `Inf(n)`:
+  Accept if acceptance set n is visited **infinitely often** (omega-regular)
+- `Fin(n)`:
+  Accept if acceptance set n is visited **finitely often** (omega-regular)
+- `Final(n)`:
+  Accept if the run **ends in** a state marked with acceptance set n (regular)
+
+## Development
+
+Run tests:
+```bash
+python -m pytest packages/morphata/tests/ -v
+```
+
+Type checking:
+```bash
+python -m mypy packages/morphata/src/morphata/ --strict
+```
+
+## License
+
+Part of the automatix project.

morphata-1.0.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "morphata"
+version = "1.0.0"
+description = "Flexible automata representations for regular and ω-regular languages."
+authors = [{ name = "Anand Balakrishnan" }]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "typing-extensions",
+  "lark",
+  "logic-asts>=1.4.1",
+  "networkx",
+  "types-networkx",
+  "attrs>=25.4.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.22,<0.10.0"]
+build-backend = "uv_build"

morphata-1.0.0/src/morphata/__init__.py

@@ -0,0 +1,78 @@
+"""Morphata: Flexible automata representations for regular and omega-regular languages.
+
+This package provides:
+- Pure structural automaton interfaces (Automaton, Domain, TransitionRelation)
+- Acceptance condition expressions (morphata.acceptance)
+- HOA format parser (morphata.hoa.parser)
+- Example implementations (morphata.examples)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Mapping
+from collections.abc import Set as AbstractSet
+from dataclasses import dataclass
+
+from typing_extensions import override
+
+from morphata.spec import AcceptanceCondition as AcceptanceCondition
+from morphata.spec import (
+    AlternatingTransitions,
+    BoolExpr,
+    DeterministicTransitions,
+    NonDeterministicTransitions,
+    UniversalTransitions,
+)
+from morphata.spec import Automaton as Automaton
+from morphata.spec import Domain as Domain
+from morphata.spec import InitialState as InitialState
+from morphata.spec import TransitionRelation as TransitionRelation
+
+
+@dataclass
+class DeterministicTransitionRelation[Q: Hashable, S: Hashable](DeterministicTransitions[Q, S]):
+    data: Mapping[Q, Mapping[S, Q]]
+
+    @override
+    def __call__(self, state: Q, symbol: S) -> Q:
+        return self.data[state][symbol]
+
+
+@dataclass
+class NonDeterministicTransitionRelation[Q: Hashable, S: Hashable](NonDeterministicTransitions[Q, S]):
+    data: Mapping[Q, Mapping[S, AbstractSet[Q]]]
+
+    @override
+    def __call__(self, state: Q, symbol: S) -> AbstractSet[Q]:
+        return self.data[state][symbol]
+
+
+@dataclass
+class UniversalTransitionRelation[Q: Hashable, S: Hashable](UniversalTransitions[Q, S]):
+    data: Mapping[Q, Mapping[S, AbstractSet[Q]]]
+
+    @override
+    def __call__(self, state: Q, symbol: S) -> AbstractSet[Q]:
+        return self.data[state][symbol]
+
+
+@dataclass
+class AlternatingTransitionRelation[Q: Hashable, S: Hashable](AlternatingTransitions[Q, S]):
+    data: Mapping[Q, Mapping[S, BoolExpr[Q]]]
+
+    @override
+    def __call__(self, state: Q, symbol: S) -> BoolExpr[Q]:
+        return self.data[state][symbol]
+
+
+__all__ = [
+    "Domain",
+    "InitialState",
+    "AcceptanceCondition",
+    "TransitionRelation",
+    "DeterministicTransitions",
+    "NonDeterministicTransitions",
+    "UniversalTransitions",
+    "AlternatingTransitions",
+    "Automaton",
+]

morphata-1.0.0/src/morphata/acceptance.py

@@ -0,0 +1,222 @@
+"""Concrete classes for acceptance conditions
+
+Provides abstract and concrete acceptance condition classes for omega-automata
+and finite-word automata.
+"""
+
+from __future__ import annotations
+
+import typing as ty
+from collections.abc import Iterable
+
+from attrs import frozen
+from typing_extensions import overload
+
+from morphata.spec import AcceptanceCondition, State
+
+
+@overload
+def acc_from_name(name: ty.Literal["Finite"], arg: Iterable[State], /) -> Finite[State]: ...
+
+
+@overload
+def acc_from_name(name: ty.Literal["Buchi"], arg: Iterable[State], /) -> Buchi[State]: ...
+
+
+@overload
+def acc_from_name(name: ty.Literal["co-Buchi"], arg: Iterable[State], /) -> CoBuchi[State]: ...
+
+
+@overload
+def acc_from_name(name: ty.Literal["generalized-Buchi"], /, *args: Iterable[State]) -> GeneralizedBuchi[State]: ...
+
+
+@overload
+def acc_from_name(name: ty.Literal["generalized-co-Buchi"], /, *args: Iterable[State]) -> GeneralizedCoBuchi[State]: ...
+
+
+@overload
+def acc_from_name(name: ty.Literal["Muller"], /, *args: Iterable[State]) -> Muller[State]: ...
+
+
+@overload
+def acc_from_name(name: ty.Literal["Streett"], /, *args: AccPair[State]) -> Streett[State]: ...
+
+
+@overload
+def acc_from_name(name: ty.Literal["Rabin"], /, *args: AccPair[State]) -> Rabin[State]: ...
+
+
+def acc_from_name(name: str, /, *args) -> AcceptanceCondition[State]:
+    match name:
+        case "Finite":
+            assert len(args) == 1, "Finite acceptance condition requires 1 accepting set"
+            arg = args[0]
+            assert isinstance(arg, Iterable)
+            return Finite(frozenset(arg))
+        case "Buchi":
+            assert len(args) == 1, "Buchi acceptance condition requires 1 accepting set"
+            arg = args[0]
+            assert isinstance(arg, Iterable)
+            return Buchi(frozenset(arg))
+        case "generalized-Buchi":
+            assert len(args) >= 0 and all(isinstance(arg, Iterable) for arg in args), (
+                "Generalized Buchi condition needs a list of accepting sets"
+            )
+            return GeneralizedBuchi(tuple(frozenset(arg) for arg in args))
+        case "co-Buchi":
+            assert len(args) == 1, "CoBuchi acceptance condition requires 1 non-accepting set"
+            arg = args[0]
+            assert isinstance(arg, Iterable)
+            return CoBuchi(frozenset(arg))
+        case "generalized-co-Buchi":
+            assert len(args) >= 0 and all(isinstance(arg, Iterable) for arg in args), (
+                "Generalized CoBuchi condition needs a list of non-accepting sets"
+            )
+            return GeneralizedCoBuchi(tuple(frozenset(arg) for arg in args))
+        case "Streett":
+            assert len(args) >= 0 and all(isinstance(arg, tuple) and len(arg) == 2 for arg in args), (
+                "Streett condition needs a list of 2-tuples of rejecting (Fin) and accepting (Inf) sets"
+            )
+            return Streett(tuple(AccPair(*(frozenset(s) for s in arg)) for arg in args))
+        case "Rabin":
+            assert len(args) >= 0 and all(isinstance(arg, tuple) and len(arg) == 2 for arg in args), (
+                "Rabin condition needs a list of 2-tuples of rejecting (Fin) and accepting (Inf) sets"
+            )
+            return Rabin(tuple(AccPair(*(frozenset(s) for s in arg)) for arg in args))
+
+        case _:
+            raise ValueError(f"Unknown/unsupported named acceptance condition: {name} {args=}")
+
+
+# @frozen
+# class GenericCondition(AcceptanceCondition[State]):
+#     acceptance_sets: tuple[frozenset[State], ...]
+#     expr: AccExpr
+
+#     @override
+#     def __len__(self) -> int:
+#         return self.num_sets
+
+#     @override
+#     def to_expr(self) -> AccExpr:
+#         return self.expr
+
+
+@frozen
+class Finite(AcceptanceCondition[State]):
+    """Finite-word acceptance condition.
+
+    For finite automata, acceptance means reaching a final state. This uses
+    a single acceptance set  to mark final states.
+    """
+
+    accepting: frozenset[State]
+
+    @classmethod
+    def is_omega_regular(cls) -> bool:
+        """Finite-word acceptance is not omega-regular."""
+        return False
+
+
+@frozen
+class Buchi(AcceptanceCondition[State]):
+    """Büchi condition: a run, r, is accepting iff inf(r) intersects with `accepting`"""
+
+    accepting: frozenset[State]
+
+    @classmethod
+    def is_omega_regular(cls) -> bool:
+        """Büchi acceptance is omega-regular."""
+        return True
+
+
+@frozen
+class GeneralizedBuchi(AcceptanceCondition[State]):
+    """Generalized Büchi condition: a run, r, is accepting iff inf(r) intersects with `accepting[i]` for some i"""
+
+    accepting: tuple[frozenset[State], ...]
+
+    @classmethod
+    def is_omega_regular(cls) -> bool:
+        """Generalized Büchi acceptance is omega-regular."""
+        return True
+
+
+@frozen
+class CoBuchi(AcceptanceCondition[State]):
+    """co-Büchi condition: a run, r, is accepting iff inf(r) does not intersect with `rejecting`"""
+
+    rejecting: frozenset[State]
+
+    @classmethod
+    def is_omega_regular(cls) -> bool:
+        """co-Büchi acceptance is omega-regular."""
+        return True
+
+
+@frozen
+class GeneralizedCoBuchi(AcceptanceCondition[State]):
+    """Generalized co-Büchi condition: a run, r, is accepting iff inf(r) does not intersect with `rejecting[i]` for some i"""
+
+    rejecting: tuple[frozenset[State], ...]
+
+    @classmethod
+    def is_omega_regular(cls) -> bool:
+        """Generalized co-Büchi acceptance is omega-regular."""
+        return True
+
+
+class AccPair(ty.NamedTuple, ty.Generic[State]):
+    """Pair of accepting and rejecting state sets for Rabin/Streett conditions."""
+
+    rejecting: frozenset[State]
+    """States that must not appear infinitely often"""
+    accepting: frozenset[State]
+    """States that must appear infinitely often"""
+
+
+@frozen
+class Streett(AcceptanceCondition[State]):
+    """Streett condition: a run, r, is accpting iff _for all_ `i`, we have that inf(r) does not intersect with `pairs[i].rejecting` and does intersect with `pairs[i].accepting`"""
+
+    pairs: tuple[AccPair[State], ...]
+
+    @property
+    def index(self) -> int:
+        """Number of pairs in this condition."""
+        return len(self.pairs)
+
+    @classmethod
+    def is_omega_regular(cls) -> bool:
+        """Streett acceptance is omega-regular."""
+        return True
+
+
+@frozen
+class Rabin(AcceptanceCondition[State]):
+    """Rabin condition: a run, r, is accpting iff _for some_ `i`, we have that inf(r) does not intersect with `pairs[i].rejecting` and does intersect with `pairs[i].accepting`"""
+
+    pairs: tuple[AccPair[State], ...]
+
+    @property
+    def index(self) -> int:
+        """Number of pairs in this condition."""
+        return len(self.pairs)
+
+    @classmethod
+    def is_omega_regular(cls) -> bool:
+        """Rabin acceptance is omega-regular."""
+        return True
+
+
+@frozen
+class Muller(AcceptanceCondition[State]):
+    """Muller condition: a run, r, is accepting iff for some `i`, we have that inf(r) is exactly `sets[i]`"""
+
+    sets: tuple[frozenset[State], ...]
+
+    @classmethod
+    def is_omega_regular(cls) -> bool:
+        """Muller acceptance is omega-regular."""
+        return True