flakepl 0.3.1__py3-none-any.whl

flake/__init__.py

@@ -0,0 +1,102 @@
+from .actions import Action, Receive, Send, Tau
+from .agent import Agent
+from .dynamic import (
+    ActionEvent,
+    ActionModel,
+    DynamicEvent,
+    PublicAnnouncement,
+    action_event,
+    announce,
+    event,
+    product_update,
+    public_announcement,
+)
+from .epistemic import (
+    CommonKnowledge,
+    DistributedKnowledge,
+    EpistemicModel,
+    EveryoneKnows,
+    Knowledge,
+    ProductWorld,
+    World,
+    C,
+    D,
+    E,
+    K,
+)
+from .explorer import StateSpace, explore, explore_many, explore_many_with, explore_with
+from .execution import (
+    ActionObservation,
+    BlindActionObservation,
+    ProcessExecutionEvent,
+    TransitionObservation,
+    blind_action,
+    execute,
+    execute_transition,
+    observe_action,
+    step,
+)
+from .formula import And, Atom, Formula, Not, Or, iff, implies
+from .observation import (
+    GlobalObservation,
+    LocalObservation,
+    ObservationBuilder,
+    global_,
+    local,
+    observe_global,
+    observe_local_process,
+    observe_local_state,
+    public,
+    same_observation,
+)
+from .process import Choice, Nil, Parallel, Prefix, Process, choice, parallel, recv, send, stop, tau
+from .propositions import Proposition
+from .runtime import Configuration, GlobalState, SystemTransition
+from .semantics import synchronous_system_transitions
+from .sos import Transition, transitions
+from .temporal import Always, Eventually, Next, Until, F, G, U, X
+from .verify import (
+    Trace,
+    VerificationResult,
+    find_always_counterexample,
+    find_eventually_counterexample,
+    find_next_counterexample,
+    find_path_to,
+    find_state_counterexample,
+    format_trace,
+    format_verification,
+    verify,
+    verify_always,
+    verify_eventually,
+)
+
+# Backward-compatible system-level name.
+system_transitions = synchronous_system_transitions
+
+__all__ = [
+    "Action", "Tau", "Send", "Receive",
+    "Agent",
+    "Process", "Nil", "Prefix", "Choice", "Parallel",
+    "stop", "send", "recv", "tau", "choice", "parallel",
+    "GlobalState", "Configuration", "SystemTransition",
+    "Proposition",
+    "Transition", "transitions",
+    "StateSpace", "explore", "explore_many", "explore_with", "explore_many_with",
+    "system_transitions", "synchronous_system_transitions",
+    "LocalObservation", "GlobalObservation", "ObservationBuilder",
+    "local", "global_", "public", "observe_global", "observe_local_state",
+    "observe_local_process", "same_observation",
+    "Formula", "Atom", "Not", "And", "Or", "implies", "iff",
+    "World", "ProductWorld", "EpistemicModel",
+    "Knowledge", "EveryoneKnows", "DistributedKnowledge", "CommonKnowledge",
+    "K", "E", "D", "C",
+    "Next", "Eventually", "Always", "Until", "X", "F", "G", "U",
+    "DynamicEvent", "PublicAnnouncement", "ActionEvent", "ActionModel",
+    "announce", "public_announcement", "event", "action_event", "product_update",
+    "TransitionObservation", "ActionObservation", "BlindActionObservation",
+    "ProcessExecutionEvent", "observe_action", "blind_action", "execute_transition",
+    "execute", "step",
+    "Trace", "VerificationResult", "find_path_to", "find_state_counterexample",
+    "find_next_counterexample", "find_always_counterexample", "find_eventually_counterexample",
+    "verify_always", "verify_eventually", "verify", "format_trace", "format_verification",
+]

flake/actions.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Tau:
+    """
+    Internal action.
+
+    Represents:
+        τ
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class Send:
+    """
+    Output action:
+
+        channel!value
+    """
+
+    channel: str
+    value: Any
+
+
+@dataclass(frozen=True, slots=True)
+class Receive:
+    """
+    Input action:
+
+        channel?variable
+    """
+
+    channel: str
+    variable: str
+
+
+Action = Tau | Send | Receive

flake/agent.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .process import Process
+
+
+@dataclass(frozen=True, slots=True)
+class Agent:
+    """
+    Runtime agent.
+
+    Agent identity is its logical name.
+
+    Runtime state consists of:
+
+        process
+        local state
+    """
+
+    name: str
+    process: Process
+    state: tuple[tuple[str, Any], ...] = ()
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        process: Process,
+        state: dict[str, Any] | None = None,
+    ) -> Agent:
+
+        if not name:
+            raise ValueError(
+                "Agent name cannot be empty"
+            )
+
+        if state is None:
+            state = {}
+
+        return cls(
+            name=name,
+            process=process,
+            state=tuple(
+                sorted(
+                    state.items(),
+                    key=lambda item: item[0],
+                )
+            ),
+        )
+
+    def get_state(
+        self,
+        key: str,
+        default: Any = None,
+    ) -> Any:
+        """
+        Read one local state variable.
+        """
+
+        return dict(
+            self.state
+        ).get(
+            key,
+            default,
+        )
+
+    def with_state(
+        self,
+        key: str,
+        value: Any,
+    ) -> Agent:
+        """
+        Return a new agent with updated local state.
+        """
+
+        state = dict(
+            self.state
+        )
+
+        state[key] = value
+
+        return Agent(
+            name=self.name,
+            process=self.process,
+            state=tuple(
+                sorted(
+                    state.items(),
+                    key=lambda item: item[0],
+                )
+            ),
+        )
+
+    def with_process(
+        self,
+        process: Process,
+    ) -> Agent:
+        """
+        Return a new agent with updated process.
+        """
+
+        return Agent(
+            name=self.name,
+            process=process,
+            state=self.state,
+        )

flake/dynamic.py

@@ -0,0 +1,449 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    Iterable,
+    Mapping,
+    Protocol,
+    TYPE_CHECKING,
+)
+
+from .formula import Formula
+
+if TYPE_CHECKING:
+    from .epistemic import EpistemicModel
+
+
+class DynamicEvent(Protocol):
+    """
+    Dynamic epistemic event.
+
+    Applying an event creates a new epistemic model.
+    """
+
+    def apply(
+        self,
+        model: "EpistemicModel",
+    ) -> "EpistemicModel":
+        ...
+
+
+# ============================================================================
+# Public announcement
+# ============================================================================
+
+
+@dataclass(frozen=True, slots=True)
+class PublicAnnouncement:
+    """
+    Public Announcement Logic event.
+
+    Every world where the formula is false is removed.
+
+    The original model is never mutated.
+    """
+
+    formula: Formula
+
+    def apply(
+        self,
+        model: "EpistemicModel",
+    ) -> "EpistemicModel":
+        return model._apply_public_announcement(
+            self.formula
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"PublicAnnouncement({self.formula!r})"
+        )
+
+
+def announce(
+    formula: Formula,
+) -> PublicAnnouncement:
+    """
+    Construct a public announcement.
+
+    Example:
+
+        model2 = model.update(
+            announce(p)
+        )
+    """
+
+    return PublicAnnouncement(
+        formula
+    )
+
+
+def public_announcement(
+    formula: Formula,
+) -> PublicAnnouncement:
+    """
+    Explicit alias for announce().
+    """
+
+    return announce(formula)
+
+
+# ============================================================================
+# Action events
+# ============================================================================
+
+
+@dataclass(frozen=True, slots=True)
+class ActionEvent:
+    """
+    One event point of an epistemic action model.
+
+    name:
+        Event identifier.
+
+    precondition:
+        Formula that must hold for the event to be executable.
+
+        None means that the event is executable in every world.
+    """
+
+    name: str
+    precondition: Formula | None = None
+
+    def __post_init__(self) -> None:
+        if not self.name.strip():
+            raise ValueError(
+                "ActionEvent name must not be empty"
+            )
+
+    def enabled(
+        self,
+        model: "EpistemicModel",
+        world,
+    ) -> bool:
+        """
+        Check whether this event is executable at a world.
+        """
+
+        if self.precondition is None:
+            return True
+
+        return model.check(
+            self.precondition,
+            at=world,
+        )
+
+    def __repr__(self) -> str:
+        if self.precondition is None:
+            return (
+                f"ActionEvent({self.name!r})"
+            )
+
+        return (
+            f"ActionEvent("
+            f"{self.name!r}, "
+            f"precondition={self.precondition!r}"
+            f")"
+        )
+
+
+def event(
+    name: str,
+    precondition: Formula | None = None,
+) -> ActionEvent:
+    """
+    Construct an action-model event.
+
+    Examples:
+
+        event("learn", K("alice", p))
+
+        event("noop")
+    """
+
+    return ActionEvent(
+        name=name,
+        precondition=precondition,
+    )
+
+
+def action_event(
+    name: str,
+    precondition: Formula | None = None,
+) -> ActionEvent:
+    """
+    Explicit alias for event().
+    """
+
+    return event(
+        name,
+        precondition,
+    )
+
+
+# ============================================================================
+# Action model
+# ============================================================================
+
+
+@dataclass(slots=True)
+class ActionModel:
+    """
+    Finite epistemic action model.
+
+    An ActionModel contains:
+
+        events
+        preconditions
+        actual event
+        event indistinguishability relations
+
+    relations:
+
+        relations[agent][event] = events that agent
+        considers possible after observing that event.
+
+    If no relation is supplied for an agent, all events are
+    considered indistinguishable for that agent.
+
+    Example:
+
+        action_model = ActionModel(
+            events=(
+                event("learn", p),
+                event("noop", ~p),
+            ),
+            actual="learn",
+            relations={
+                "alice": {
+                    "learn": {"learn"},
+                    "noop": {"noop"},
+                },
+                "bob": {
+                    "learn": {"learn", "noop"},
+                    "noop": {"learn", "noop"},
+                },
+            },
+        )
+    """
+
+    events: tuple[ActionEvent, ...]
+    actual: str
+    relations: (
+        Mapping[
+            str,
+            Mapping[
+                str,
+                Iterable[str],
+            ],
+        ]
+        | None
+    ) = None
+
+    def __post_init__(self) -> None:
+        self.events = tuple(
+            self.events
+        )
+
+        if not self.events:
+            raise ValueError(
+                "ActionModel requires at least one event"
+            )
+
+        names = [
+            item.name
+            for item in self.events
+        ]
+
+        if len(names) != len(set(names)):
+            raise ValueError(
+                "ActionEvent names must be unique"
+            )
+
+        if self.actual not in names:
+            raise ValueError(
+                f"Unknown actual event {self.actual!r}"
+            )
+
+        event_names = set(names)
+
+        normalized: dict[
+            str,
+            dict[
+                str,
+                frozenset[str],
+            ],
+        ] = {}
+
+        if self.relations is not None:
+            for agent, relation in self.relations.items():
+                if not isinstance(agent, str):
+                    raise TypeError(
+                        "ActionModel agent names must be strings"
+                    )
+
+                agent_name = agent.strip()
+
+                if not agent_name:
+                    raise ValueError(
+                        "ActionModel agent name must not be empty"
+                    )
+
+                if agent_name in normalized:
+                    raise ValueError(
+                        f"Duplicate action relation for "
+                        f"{agent_name!r}"
+                    )
+
+                source_map: dict[
+                    str,
+                    frozenset[str],
+                ] = {}
+
+                for source, targets in relation.items():
+                    if source not in event_names:
+                        raise ValueError(
+                            f"Unknown event {source!r} "
+                            f"in relation for {agent_name!r}"
+                        )
+
+                    target_set = frozenset(
+                        targets
+                    )
+
+                    unknown_targets = (
+                        target_set - event_names
+                    )
+
+                    if unknown_targets:
+                        unknown_text = ", ".join(
+                            sorted(unknown_targets)
+                        )
+
+                        raise ValueError(
+                            f"Unknown target event(s) "
+                            f"{unknown_text!r} "
+                            f"in relation for {agent_name!r}"
+                        )
+
+                    source_map[source] = (
+                        target_set
+                    )
+
+                missing_sources = (
+                    event_names - set(source_map)
+                )
+
+                if missing_sources:
+                    missing_text = ", ".join(
+                        sorted(missing_sources)
+                    )
+
+                    raise ValueError(
+                        f"Missing action relation(s) "
+                        f"for {agent_name!r}: "
+                        f"{missing_text}"
+                    )
+
+                normalized[agent_name] = (
+                    source_map
+                )
+
+        self.relations = normalized
+
+    # ---------------------------------------------------------------------
+    # Event API
+    # ---------------------------------------------------------------------
+
+    @property
+    def event_names(
+        self,
+    ) -> tuple[str, ...]:
+        return tuple(
+            item.name
+            for item in self.events
+        )
+
+    def event(
+        self,
+        name: str,
+    ) -> ActionEvent:
+        for item in self.events:
+            if item.name == name:
+                return item
+
+        raise ValueError(
+            f"Unknown action event {name!r}"
+        )
+
+    # ---------------------------------------------------------------------
+    # Event epistemic relation
+    # ---------------------------------------------------------------------
+
+    def accessible(
+        self,
+        agent: str,
+        event_name: str,
+    ) -> tuple[str, ...]:
+        """
+        Return events that the agent considers possible
+        after observing event_name.
+
+        If no relation is defined for this agent, all events
+        are considered indistinguishable.
+        """
+
+        self.event(event_name)
+
+        relation = self.relations.get(
+            agent
+        )
+
+        if relation is None:
+            return self.event_names
+
+        return tuple(
+            target
+            for target in self.event_names
+            if target in relation[event_name]
+        )
+
+    # ---------------------------------------------------------------------
+    # DynamicEvent protocol
+    # ---------------------------------------------------------------------
+
+    def apply(
+        self,
+        model: "EpistemicModel",
+    ) -> "EpistemicModel":
+        return model._apply_action_model(
+            self
+        )
+
+    def __repr__(self) -> str:
+        names = ", ".join(
+            self.event_names
+        )
+
+        return (
+            f"ActionModel("
+            f"events=[{names}], "
+            f"actual={self.actual!r}"
+            f")"
+        )
+
+
+def product_update(
+    model: "EpistemicModel",
+    action_model: ActionModel,
+) -> "EpistemicModel":
+    """
+    Functional helper for product update.
+
+    Equivalent to:
+
+        model.product_update(action_model)
+    """
+
+    return model.product_update(
+        action_model
+    )