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

Classes

class  PatrolTask
 

Functions

int spec_dim (str spec)
 
str spec_base (str spec)
 
bool spec_uncertain (str spec)
 
int seconds_to_steps (float seconds, float dt)
 
STLFormula outside_box (float half_width, int d=2, tuple[int,...]|None axes=None)
 
STLFormula interval_outside_box (float half_width, int d=2, tuple[int,...]|None axes=None, float offset_bound=0.05, float rotation_bound=0.05)
 
STLFormula rotated_outside_box (float half_width, np.ndarray R, int|None d=None, tuple[int,...]|None axes=None)
 
np.ndarray rotation_matrix (np.ndarray axis, float angle)
 
STLFormula outside_square (float half_width, int d=2, int ix=0, int iy=1)
 
STLFormula window_spec (STLFormula psi, int n_plan, int first_window=0)
 
int first_enforced_window (int t, int h)
 

Variables

 SpecName = Literal["theta", "phi", "theta_plus", "phi_plus", "theta_u", "phi_u", "theta_plus_u", "phi_plus_u"]
 
tuple EXACT_SPECS = ("theta", "phi", "theta_plus", "phi_plus")
 
tuple UNCERTAIN_SPECS = ("theta_u", "phi_u", "theta_plus_u", "phi_plus_u")
 
tuple SPECS = EXACT_SPECS + UNCERTAIN_SPECS
 

Detailed Description

NAHS patrol task: keep-out square, formulas (24)/(25), receding window specification.

Baird, Morales-Cuadrado and Coogan (NAHS 2026 submission, Sec. 11):

    theta = (x in S) => F_[0,4] (x notin S)                 (24)
    phi   = (x in S) => F_[0,3] G_[0,1] (x notin S)         (25)

with time bounds in seconds and ``S = {|px| < 1.41, |py| < 1.41}`` (2 m taped square
inflated by the 0.38 m blimp radius and the 0.03 m tape). The reference code
(`rta_fixed.py:395-397`) converts seconds to steps as ``F_[0, round(4/dt) - 1]`` and
``F_[0, round(3/dt) - 1] G_[0, round(1/dt)]``; :func:`seconds_to_steps` follows that
convention so that ``dt = 0.5`` reproduces their 7-step formulas exactly.

``(x in S) => F_[0,a] notS`` equals ``notS OR F_[0,a] notS = F_[0,a] notS`` (the
eventually includes offset 0), so theta is built as the eventually alone. phi keeps
the disjunction (``notS`` now does not imply ``F G notS``).

The signal is the planar position ``y = (px, py)``; every predicate is
``+-px - 1.41 >= 0`` or ``+-py - 1.41 >= 0`` (unit normals, robustness in metres).

3-D cube variants (theta^+, phi^+)
---------------------------------
``theta_plus`` and ``phi_plus`` keep the temporal structure of (24)/(25) and replace the square by
the cube ``S+ = {|px|, |py|, |pz| < 1.41}`` (signal ``y = (px, py, pz)``, z relative to the cube
centre). The patrol waypoints are the six face centres moved outward by the 2-D offset
(``waypoint_radius - half_width``), visited in the order ``+y, +x, +z, -y, -x, -z``: consecutive
faces are adjacent, so each straight leg cuts an edge region of ``S+`` as the 2-D legs cut the
corners of ``S``. Restricted to the plane the cycle is the 2-D order ``+y, +x, -y, -x``.

Uncertain predicates (theta_u, phi_u, theta_plus_u, phi_plus_u)
---------------------------------------------------------------
The ``_u`` specs keep the temporal structure and the signal of their exact counterpart and replace
every face predicate by an interval predicate ``[a]^T y - [b] >= 0``
(:class:`~rl_stl.stl.interval.IntervalPredicate`). The true keep-out region is the nominal square
(cube) rotated by an unknown angle of at most ``pred_rotation`` (0.05 rad, any axis in 3-D) about its
centre, with an unknown half-width ``b in [half_width - pred_offset, half_width + pred_offset]``
(0.05 m). ``[b]`` is that interval; ``[a]`` is the interval hull of the face's rotated unit normal:
for the ``+x`` face ``a_x in [cos(pred_rotation), 1]`` and every tangential component in
``[-sin(pred_rotation), sin(pred_rotation)]`` (signs flipped for the ``-`` faces). Every true region
is therefore inside the predicates' uncertainty set, and the I-STL lower bound
(:mod:`rl_stl.stl.interval`) is a worst case over all of them.

``PatrolTask.nominal_predicates`` is an ablation: the loop plans and checks with the exact nominal
predicates while the episode is scored against a true region drawn inside the uncertainty set
(:meth:`PatrolTask.sample_true_region`, :meth:`PatrolTask.true_formula`).

Receding window
---------------
At planning step ``t`` the synthesis signal is ``y_{t-h+1} .. y_t`` (measured) followed
by ``y_{t+1} .. y_{t+N}`` (planned), ``L = h + N`` samples, where ``h`` is the formula
horizon. The formula is enforced on every window ``[s, s+h]`` that contains a planned
sample: local starts ``s = 0 .. N-1`` (NAHS (16): ``k = t-h+1 .. t+N-h``). Windows that
would start before the episode start are not enforced (:func:`window_spec`).

Function Documentation

◆ first_enforced_window()

int rl_stl.stl.nahs.first_enforced_window ( int  t,
int  h 
)
Local start of the first window that begins at absolute time ``>= 0``.

◆ interval_outside_box()

STLFormula rl_stl.stl.nahs.interval_outside_box ( float  half_width,
int   d = 2,
tuple[int, ...] | None   axes = None,
float   offset_bound = 0.05,
float   rotation_bound = 0.05 
)
``x notin S`` for an uncertain box: interval predicates ``[a]^T y - [b] >= 0`` per face.

``[b] = [half_width - offset_bound, half_width + offset_bound]``; ``[a]`` is the box hull of the
face's outward unit normal rotated (within the subspace of ``axes``) by at most ``rotation_bound``:
normal component ``sign * [cos(rotation_bound), 1]``, other box axes ``[-sin, sin]``, signal
components outside ``axes`` 0. The nominal ``a``, ``b`` are those of :func:`outside_box`.

◆ outside_box()

STLFormula rl_stl.stl.nahs.outside_box ( float  half_width,
int   d = 2,
tuple[int, ...] | None   axes = None 
)
``x notin S``: disjunction of the ``2 len(axes)`` half-spaces outside ``|y_i| < half_width``.

``axes`` (default ``0..d-1``) are the signal components that bound ``S``; two axes give the NAHS
square, three the cube ``S+``.

◆ outside_square()

STLFormula rl_stl.stl.nahs.outside_square ( float  half_width,
int   d = 2,
int   ix = 0,
int   iy = 1 
)
``x notin S``: disjunction of the four half-planes outside ``|px|, |py| < half_width``.

◆ rotated_outside_box()

STLFormula rl_stl.stl.nahs.rotated_outside_box ( float  half_width,
np.ndarray  R,
int | None   d = None,
tuple[int, ...] | None   axes = None 
)
``x notin R S_b``: exact predicates of the box ``|y_k| < half_width`` rotated by ``R``.

``R`` is a rotation of the subspace of ``axes`` (``len(axes) x len(axes)``); face ``(k, sign)`` has
the outward normal ``sign * R e_k`` (embedded in the signal space) and offset ``half_width``.

◆ rotation_matrix()

np.ndarray rl_stl.stl.nahs.rotation_matrix ( np.ndarray  axis,
float  angle 
)
Rodrigues rotation about the unit ``axis`` (3-D), or the planar rotation (``axis`` ignored, 2-D).

◆ seconds_to_steps()

int rl_stl.stl.nahs.seconds_to_steps ( float  seconds,
float  dt 
)
NAHS convention for the upper bound of ``F_[0, seconds]``: ``round(s/dt) - 1``.

◆ spec_base()

str rl_stl.stl.nahs.spec_base ( str  spec)
Temporal structure ``theta`` (24) or ``phi`` (25).

◆ spec_dim()

int rl_stl.stl.nahs.spec_dim ( str  spec)
Signal dimension: 3 for the cube specs (``*_plus``, ``*_plus_u``), else 2.

◆ spec_uncertain()

bool rl_stl.stl.nahs.spec_uncertain ( str  spec)
Interval (uncertain) predicates: the ``_u`` specs.

◆ window_spec()

STLFormula rl_stl.stl.nahs.window_spec ( STLFormula  psi,
int  n_plan,
int   first_window = 0 
)
Conjunction of ``psi`` at local window starts ``first_window .. n_plan - 1``.

The signal has ``h + n_plan`` samples (``h = horizon(psi)``). ``first_window > 0``
drops windows that would start before the episode start (fewer than ``h - 1``
measured samples exist).

Variable Documentation

◆ EXACT_SPECS

tuple rl_stl.stl.nahs.EXACT_SPECS = ("theta", "phi", "theta_plus", "phi_plus")

◆ SpecName

rl_stl.stl.nahs.SpecName = Literal["theta", "phi", "theta_plus", "phi_plus", "theta_u", "phi_u", "theta_plus_u", "phi_plus_u"]

◆ SPECS

tuple rl_stl.stl.nahs.SPECS = EXACT_SPECS + UNCERTAIN_SPECS

◆ UNCERTAIN_SPECS

tuple rl_stl.stl.nahs.UNCERTAIN_SPECS = ("theta_u", "phi_u", "theta_plus_u", "phi_plus_u")