Skip to content

Cost Function as a DFA

API Reference

masa.common.ltl.DFACostFn

DFACostFn(dfa: DFA)

Bases: DFA, CostFn

DFA-backed MASA cost function.

This wrapper interprets accepting automaton states as constraint violations (or terminal "bad" states): a transition that lands in an accepting state yields cost 1.0 and otherwise 0.0.

Important
  • The internal DFA state is advanced by calling __call__.
  • Use cost for counterfactual evaluation from an explicit DFA state without mutating internal state.
  • DFA.step is intentionally disabled to avoid ambiguous state updates via the inherited DFA interface.

Attributes:

Name Type Description
dfa

The wrapped DFA instance whose internal state is advanced when the cost function is called.

Creates a DFA cost function wrapper.

Parameters:

Name Type Description Default
dfa DFA

The DFA to wrap. The wrapper keeps a reference to this DFA and uses its internal state for sequential evaluation.

required
Source code in masa/common/ltl.py
def __init__(self, dfa: DFA):
    """Creates a DFA cost function wrapper.

    Args:
      dfa: The DFA to wrap. The wrapper keeps a reference to this DFA and
        uses its internal state for sequential evaluation.
    """
    self.dfa = dfa
    self.states = self.dfa.states
    self.initial = self.dfa.initial
    self.accepting = self.dfa.accepting
    self.edges = self.dfa.edges

dfa instance-attribute

dfa = dfa

states instance-attribute

states = self.dfa.states

initial instance-attribute

initial = self.dfa.initial

accepting instance-attribute

accepting = self.dfa.accepting

edges instance-attribute

edges = self.dfa.edges

automaton_state property

automaton_state

Returns the current state of the wrapped DFA.

Returns:

Type Description

The wrapped DFA's current automaton state (DFA.state).

add_edge

add_edge(parent: int, child: int, condition: Formula)

Disables edge modification after wrapping.

Raises:

Type Description
RuntimeError

Always raised. Build the DFA fully before wrapping it as a cost function to avoid unintended side effects.

Source code in masa/common/ltl.py
def add_edge(self, parent: int, child: int, condition: Formula):
    """Disables edge modification after wrapping.

    Raises:
      RuntimeError: Always raised. Build the DFA fully before wrapping it as
        a cost function to avoid unintended side effects.
    """
    raise RuntimeError(
        "Please build the DFA before wrapping it as a cost function to avoid unintended side effects"
    )

reset

reset()

Resets the internal DFA state.

Notes

This delegates to the wrapped DFA's DFA.reset.

Source code in masa/common/ltl.py
def reset(self):
    """Resets the internal DFA state.

    Notes:
      This delegates to the wrapped DFA's :meth:`DFA.reset`.
    """
    self.dfa.reset()

step

step(labels: Iterable[str]) -> Tuple[bool, int]

Disables stepping via the DFA interface.

Raises:

Type Description
RuntimeError

Always raised. Use __call__ to advance the internal DFA and return the cost signal.

Source code in masa/common/ltl.py
def step(self, labels: Iterable[str]) -> Tuple[bool, int]:
    """Disables stepping via the DFA interface.

    Raises:
      RuntimeError: Always raised. Use :meth:`__call__` to advance the
        internal DFA and return the cost signal.
    """
    raise RuntimeError(
        "Please do not modify the the internal dfa state here, use DFACostFn.__call__ instead for correct functionality"
    )

cost

cost(state: int, labels: Iterable[str]) -> float

Computes the one-step cost from an explicit DFA state without mutation.

Parameters:

Name Type Description Default
state int

The DFA state to evaluate from (does not need to equal the internal automaton state).

required
labels Iterable[str]

Iterable of atomic proposition names for the current step.

required

Returns:

Type Description
float

1.0 iff the next state reached from state under labels is

float

accepting; otherwise 0.0.

Notes

This is intended for counterfactual evaluation and does not change the wrapped DFA's internal state.

Source code in masa/common/ltl.py
def cost(self, state: int, labels: Iterable[str]) -> float:
    """Computes the one-step cost from an explicit DFA state without mutation.

    Args:
      state: The DFA state to evaluate from (does not need to equal the
        internal automaton state).
      labels: Iterable of atomic proposition names for the current step.

    Returns:
      ``1.0`` iff the next state reached from ``state`` under ``labels`` is
      accepting; otherwise ``0.0``.

    Notes:
      This is intended for counterfactual evaluation and does not change the
      wrapped DFA's internal state.
    """
    return float(self.dfa.transition(state, labels) in self.dfa.accepting)

__call__

__call__(labels: Iterable[str])

Advances the internal DFA by one step and returns the cost.

Parameters:

Name Type Description Default
labels Iterable[str]

Iterable of atomic proposition names for the current step.

required

Returns:

Type Description

1.0 if the internal DFA transitions into an accepting state on

this step, else 0.0.

Source code in masa/common/ltl.py
def __call__(self, labels: Iterable[str]):
    """Advances the internal DFA by one step and returns the cost.

    Args:
      labels: Iterable of atomic proposition names for the current step.

    Returns:
      ``1.0`` if the internal DFA transitions into an accepting state on
      this step, else ``0.0``.
    """
    accepting, _ = self.dfa.step(labels)
    return float(accepting)

masa.common.ltl.dfa_to_costfn

dfa_to_costfn(dfa: DFA)

Wraps a DFA as a DFACostFn via a deep copy.

Parameters:

Name Type Description Default
dfa DFA

The DFA to wrap.

required

Returns:

Type Description

A DFACostFn wrapper around a deep-copied DFA.

Notes

The deep copy prevents unexpected side effects if the caller later mutates the original DFA (e.g., by adding edges).

Source code in masa/common/ltl.py
def dfa_to_costfn(dfa: DFA):
    """Wraps a DFA as a :class:`DFACostFn` via a deep copy.

    Args:
      dfa: The DFA to wrap.

    Returns:
      A :class:`DFACostFn` wrapper around a deep-copied DFA.

    Notes:
      The deep copy prevents unexpected side effects if the caller later mutates
      the original DFA (e.g., by adding edges).
    """
    return DFACostFn(deepcopy(dfa))