LIRRA  1.0.0
Loading...
Searching...
No Matches
rl_stl.stl.robustness Namespace Reference

Functions

int formula_horizon (STLFormula formula)
 
Iterator[tuple[LinearPredicate, int]] iter_predicates (STLFormula formula, int t=0)
 
float _pred_value (LinearPredicate pred, np.ndarray y_t)
 
Interval _pred_value_range (LinearPredicate pred, np.ndarray y_t)
 
Interval _pred_box_range (LinearPredicate pred, np.ndarray lo, np.ndarray hi)
 
float robustness (STLFormula formula, np.ndarray signal, int t=0, int|None observed_until=None)
 
Interval robustness_interval (STLFormula formula, np.ndarray prefix, np.ndarray signal_lo, np.ndarray signal_hi, int t=0, int|None observed_until=None)
 
float interval_lower_robustness (STLFormula formula, np.ndarray signal, np.ndarray|float radius=0.0, int t=0)
 
dict[str, Interval] top_level_intervals (STLFormula formula, np.ndarray prefix, np.ndarray signal_lo, np.ndarray signal_hi)
 
float stlpy_robustness (STLFormula formula, np.ndarray signal, int t=0)
 
float lipschitz_sup_norm (STLFormula formula)
 

Variables

 Interval = tuple[float, float]
 

Detailed Description

Independent STL robustness evaluation and online (prefix) interval semantics.

Signals in this module are **time-first** arrays of shape ``(T, d)``, the
project convention for trajectories. ``stlpy``'s own ``robustness(y, t)`` uses
``(d, T)``; :func:`stlpy_robustness` performs that conversion.

The evaluator here is written separately from ``stlpy`` (memoised, iterative
over the formula tree) so that robustness of every synthesised trajectory can be
recomputed independently of both the solver and ``stlpy``'s implementation.

Online semantics
----------------
For an observed prefix ``y_0..y_k`` and a formula whose horizon extends past
``k``, ordinary robustness is undefined. :func:`robustness_interval` returns
``[rho_lower, rho_upper]`` enclosing the robustness of **every completion whose
unknown samples lie in the signal box** ``[signal_lo, signal_hi]``:

* ``rho_lower > 0``  every admissible completion satisfies;
* ``rho_upper < 0``  no admissible completion satisfies;
* otherwise           inconclusive.

This is a trace-only (model-free) enclosure: unknown samples are treated
independently at each predicate, so the interval is sound but not tight. It
ignores dynamics, so ``rho_upper >= 0`` does *not* imply that the system can
still satisfy the formula (see the dynamics-constrained oracle in
``rl_stl.evaluation.oracle``).

Future-margin robustness
------------------------
Ordinary robustness of ``y_0:k ++ y_hat`` is capped by the worst *observed*
sample, which can no longer be perturbed. For runtime margins the project uses
the future-margin robustness ``rho_F`` (``observed_until=k``): predicates at
observed times ``<= k`` evaluate to ``+inf`` if satisfied and ``-inf`` if
violated; later predicates keep their quantitative value. Then

* ``rho_F >= 0``  iff  ``rho >= 0`` (same Boolean satisfaction), and
* ``rho_F >= delta`` means every perturbation of the unobserved samples with
  ``L * sup-norm < delta`` preserves satisfaction (``L`` from
  :func:`lipschitz_sup_norm`).

Interval predicates
-------------------
For an :class:`~rl_stl.stl.interval.IntervalPredicate` ``[a]^T y - [b] >= 0`` every evaluator here
uses the I-STL interval of the predicate's value over ``[a]`` and ``[b]``: :func:`robustness` (and
``stlpy``'s own ``robustness``) returns the **lower** robustness (worst case over the predicate
uncertainty, each predicate occurrence independently), :func:`robustness_interval` encloses
``[lower, upper]``, and :func:`interval_lower_robustness` additionally widens each sample to a box
``[y_t - r_t, y_t + r_t]`` (the tube of a predicted sample). Exact predicates keep their values.

Function Documentation

◆ _pred_box_range()

Interval rl_stl.stl.robustness._pred_box_range ( LinearPredicate  pred,
np.ndarray  lo,
np.ndarray  hi 
)
protected

◆ _pred_value()

float rl_stl.stl.robustness._pred_value ( LinearPredicate  pred,
np.ndarray  y_t 
)
protected

◆ _pred_value_range()

Interval rl_stl.stl.robustness._pred_value_range ( LinearPredicate  pred,
np.ndarray  y_t 
)
protected
``[lower, upper]`` of a predicate at a known sample (degenerate for exact predicates).

◆ formula_horizon()

int rl_stl.stl.robustness.formula_horizon ( STLFormula  formula)
Largest time offset referenced by the formula (signal needs horizon+1 samples).

◆ interval_lower_robustness()

float rl_stl.stl.robustness.interval_lower_robustness ( STLFormula  formula,
np.ndarray  signal,
np.ndarray | float   radius = 0.0,
int   t = 0 
)
I-STL lower robustness of the interval signal ``[y_t - r_t, y_t + r_t]`` (``signal``, ``radius``:
``(T, d)``, ``radius`` may broadcast): each predicate occurrence takes the lower endpoint of its value
over the sample box and, for interval predicates, over ``[a]`` and ``[b]``; min/max combine the lower
endpoints (both are monotone). ``radius = 0`` gives :func:`robustness`.

◆ iter_predicates()

Iterator[tuple[LinearPredicate, int]] rl_stl.stl.robustness.iter_predicates ( STLFormula  formula,
int   t = 0 
)
Yield ``(predicate, absolute_time)`` for every leaf occurrence.

◆ lipschitz_sup_norm()

float rl_stl.stl.robustness.lipschitz_sup_norm ( STLFormula  formula)
Constant ``L`` with ``|rho(y) - rho(y')| <= L * max_t ||y_t - y'_t||_inf``.

Min/max are 1-Lipschitz, so ``L = max_predicates ||a||_1`` (``|| max(|a_lo|, |a_hi|) ||_1`` for an
interval predicate's lower endpoint).

◆ robustness()

float rl_stl.stl.robustness.robustness ( STLFormula  formula,
np.ndarray  signal,
int   t = 0,
int | None   observed_until = None 
)
Quantitative robustness ``rho^phi(signal, t)`` for a complete signal ``(T, d)``.

With ``observed_until=k`` returns the future-margin robustness ``rho_F``
(predicates at times ``<= k`` count as ``+/-inf``).

◆ robustness_interval()

Interval rl_stl.stl.robustness.robustness_interval ( STLFormula  formula,
np.ndarray  prefix,
np.ndarray  signal_lo,
np.ndarray  signal_hi,
int   t = 0,
int | None   observed_until = None 
)
Enclosure of robustness over all completions of ``prefix`` inside the signal box.

``prefix`` has shape ``(k+1, d)`` holding the known samples ``y_0..y_k``.
Samples at times ``> k`` are unknown and range over ``[signal_lo, signal_hi]``.
If the prefix already covers the formula horizon the interval is degenerate.
With ``observed_until=j`` (``j <= k``) predicates at times ``<= j`` are
Boolean (future-margin semantics); known samples after ``j`` (e.g. a
prediction) stay quantitative.

◆ stlpy_robustness()

float rl_stl.stl.robustness.stlpy_robustness ( STLFormula  formula,
np.ndarray  signal,
int   t = 0 
)
``stlpy``'s own robustness for a time-first signal (for cross-checking).

◆ top_level_intervals()

dict[str, Interval] rl_stl.stl.robustness.top_level_intervals ( STLFormula  formula,
np.ndarray  prefix,
np.ndarray  signal_lo,
np.ndarray   signal_hi 
)
Interval per top-level conjunct: exposes outstanding vs. discharged obligations.

For ``G safe AND F goal`` a positive lower bound on ``F goal`` means the
eventuality has been discharged by the prefix; an upper bound below zero on
either conjunct means it is already violated.

Variable Documentation

◆ Interval

rl_stl.stl.robustness.Interval = tuple[float, float]