HEEL-G RUT

Rolling Uncertainty Traversability — physics-first go / slow / abort gates for wheeled UGVs.

HEEL-G is Fratres X AI’s ground-mobility research line. RUT is the open traversability layer: Bekker–Wong–Janosi Simple Terramechanics, worst-mode gates, soil-parameter uncertainty, and reviewable evidence.

It is a traversability layer, not a planner, navigator, or weapons system.
It is not field-certified and not NRMM-equivalent.

What this is / is not

This is	This is not
Open research software for wheeled ground mobility	A navigation stack or path planner
Challengeable Bekker / Janosi envelopes + GO / SLOW / ABORT / UNKNOWN	A black-box “traversability score” product
Published NASA/Wong soil tables + open residual adapters	Field certification or NRMM equivalence
Pure-Python ROS 2 pickup handler (no ROS install for the science package)	An operational C2 / weapons / C-UAS system
Synthetic scenarios locked in CI for physics honesty	Claimed field logs or invented bevameter campaigns

Why clone it

1. Challengeable soils — heelg-rut-soil/v1 YAML under examples/measured/ (published NASA/Wong path shipped; operator bevameter / plate_shear fits welcome)
2. External residuals — RoBivaL + DROVE-format adapters with quoteable tables (docs/ROBIVAL_RESIDUALS.md, docs/DROVE.md)
3. Pickup path — pure-Python ROS 2 service handler + bagless demo (examples/ros2_traversability/)

Patch + vehicle (+ optional soil YAML) → Bekker / Janosi → gate → evidence / ROS dict

Install

Requires Python 3.10+.

git clone https://github.com/Fratres-X-AI/RUT.git
cd RUT
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e ".[dev]"

Validate (what CI locks)

pytest -q
ruff check src tests
python scripts/validate_literature.py
python scripts/validate_gates.py
python scripts/validate_drove_format.py
python scripts/validate_robival_residuals.py
heelg-demo --all
python examples/ros2_traversability/demo_call.py

Use with ROS 2

No ROS install required for the science package. The handler is pure Python:

python examples/ros2_traversability/demo_call.py

from rut.ros_bridge import handle_traversability_request

out = handle_traversability_request({
    "patch": {"patch_id": "p0", "slope_deg": 8.0, "soil": "unknown"},
    "vehicle": {"name": "ugv", "mass_kg": 900.0, "wheel_radius_m": 0.4},
    "soil_yaml": "examples/measured/published_wong_nasa_dry_sand.yaml",
})
print(out["gate"], out["limiting_mode"], out["costmap"])

Details: examples/ros2_traversability/README.md.

Measured / published soil

from rut import load_soil_yaml, TerrainPatch, VehicleProfile, assess_patch
from rut.models import SoilClass
from rut.measured_soil import provenance_dict

rec = load_soil_yaml("examples/measured/published_wong_nasa_dry_sand.yaml")
vehicle = VehicleProfile(name="patrol-ugv", wheel_radius_m=0.4, mass_kg=900.0)
patch = TerrainPatch(patch_id="creek-bank", slope_deg=14, soil=SoilClass.UNKNOWN)
verdict = assess_patch(patch, vehicle, soil_override=rec.parameters)
print(verdict.gate, verdict.limiting_mode, provenance_dict(rec)["class"])

Copy examples/measured/_TEMPLATE.yaml for a real plate/shear fit.
See docs/FIELD_INGEST.md.

Quick example (demo soil priors)

Demo SOIL_TABLE rows are illustrative. Prefer literature or measured YAML for anything you cite.

from rut import SoilClass, TerrainPatch, VehicleProfile, assess_patch

vehicle = VehicleProfile(name="patrol-ugv", wheel_radius_m=0.25)
patch = TerrainPatch(
    patch_id="creek-bank",
    slope_deg=14,
    cross_slope_deg=9,
    soil=SoilClass.WET_CLAY,
    moisture=0.82,
    perception_confidence=0.71,
)

verdict = assess_patch(patch, vehicle)
print(verdict.gate, verdict.limiting_mode)
print(f"{verdict.max_speed_mps:.2f} m/s · sinkage {verdict.sinkage_m:.3f} m")

Architecture

Module	Role
src/rut/terramechanics.py	Bekker sinkage, Janosi thrust/slip, SSF, RCI prior
src/rut/assess.py	Worst-mode gates + speed-made-good
src/rut/literature.py	NASA/Wong published soils + kernel checks
src/rut/measured_soil.py	heelg-rut-soil/v1 YAML ingest
src/rut/robival.py	RoBivaL-format residual reports
src/rut/drove.py	DROVE-format residual correlation
src/rut/ros_bridge.py	Pure-Python ROS pickup handler
src/rut/uncertainty.py	Soil-parameter Monte Carlo
src/rut/evidence.py	Reviewable evidence packages
src/rut/ml/	Optional slip/drawbar research head (not on assess path)

Phase‑2 DEM / proprioception helpers exist but are not on the assess path — see docs/PHASE2.md.
ML is research-only — ST gates remain authoritative — see docs/ML.md.

Bundled scenarios (synthetic)

Curated YAML for CI physics locks — not field logs. See docs/SCENARIOS.md.

Scenario	Route	Story
patrol_trail	SLOW	Firm trail → loose shoulder
soft_bank_abort	ABORT	Wet clay strength
ridge_unknown	ABORT	Weak perception
desert_wash	ABORT	Sand dune traction
berm_step_abort	ABORT	Step climb limit
ditch_abort	ABORT	Negative obstacle

Documentation

Doc	Contents
docs/README.md	Full doc index
docs/ROBIVAL_RESIDUALS.md	Open-corpus residual campaign (honest limits)
docs/FIELD_INGEST.md	How to land a measured soil YAML
docs/LITERATURE_VALIDATION.md	Published-table kernel locks
docs/DROVE.md	Operator DROVE-format correlation
docs/ML.md	Optional CUDA slip/drawbar head
docs/CAPABILITIES.md	DONE / PARTIAL / SCAFFOLD matrix
docs/REQUIREMENTS.md	Pass bar / locked gates
docs/ARCHITECTURE.md	Pipeline and modules
docs/PHYSICS.md	ST physics notes
docs/ROADMAP.md	Near / later / out of scope

Optional compute host

Any Linux host with a readable cgroup works. Prefer cgroup cpu.max over nproc. Do not commit hostnames, ports, or keys.

export RUT_POD_HOST=<ip> RUT_POD_PORT=<port>
bash scripts/laptop_push_to_pod.sh   # optional sync helper
# on host:
bash scripts/pod_fleet.sh

See docs/POD.md.

Disclaimer

Research software only. Not a navigation product, not operational guidance, not a weapons system.
Demo SOIL_TABLE rows are illustrative. Published NASA/Wong tables are separate (rut.literature).
Replace either with measured heelg-rut-soil/v1 YAML (bevameter / plate_shear) before any field claim.
Synthetic scenarios and residual campaigns are not field certification.

Contributing

See CONTRIBUTING.md. Security: SECURITY.md.

Citation

@software{heelg_rut,
  title  = {HEEL-G RUT: Rolling Uncertainty Traversability for UGVs},
  author = {{Fratres X AI}},
  year   = {2026},
  url    = {https://github.com/Fratres-X-AI/RUT},
  version = {0.7.0}
}

Also CITATION.cff.

License

MIT — © Fratres X AI.