Shaped Cost Function

API Reference

class masa.common.ltl.ShapedCostFn(dfa: DFA, potential_fn: Callable[[int], float], gamma: float = 0.99)[source]

Bases: DFACostFn

Potential-based shaped DFA cost for counterfactual experience.

This class implements a potential-based shaping term on top of the base DFA cost, intended for counterfactual computations where you explicitly pass a DFA state to DFACostFn.cost().

The shaped cost is:

\[c'(q, \ell) = c(q, \ell) + \gamma \Phi(q') - \Phi(q),\]

where \(q'\) is the next automaton state after reading labels \(\ell\), \(c(q, \ell)\) is the base DFA cost, and \(\Phi\) is a user-provided potential function.

Important

  • This cost function is not intended to be used statefully.

  • reset() and __call__() are disabled by design.

Creates a shaped DFA cost function.

Parameters:

  • dfa – DFA whose accepting states define the base cost.

  • potential_fn – Potential function \(\Phi(q)\) over DFA states.

  • gamma – Discount factor \(\gamma\) used in potential-based shaping.

reset()[source]

Disables resetting for shaped counterfactual cost.

Raises:

RuntimeError – Always raised. This object is intended for counterfactual calls to DFACostFn.cost() only.

cost(state: int, labels: Iterable[str]) → float[source]

Computes shaped cost from an explicit DFA state without mutation.

The shaped cost is:

\[c(q,\ell) + \gamma \Phi(q') - \Phi(q),\]

where \(q' = \delta(q, \ell)\) is the DFA transition result.

Parameters:

  • state – DFA state \(q\) to evaluate from.

  • labels – Iterable of atomic proposition names \(\ell\) for the current step.

Returns:

Potential-based shaped cost.

Notes

This method does not change the wrapped DFA’s internal state.

Warning

The implementation calls self.potential(state) for the final term, which assumes a method/attribute named potential exists. If you intended to use the provided callable, replace that with self.potential_fn(state).