urml-chrono-runtime 0.4.0__py3-none-any.whl

urml_chrono_runtime/__init__.py

@@ -0,0 +1,27 @@
+"""urml_chrono_runtime — high-fidelity validation runtime for URML.
+
+  ChronoAdapter (+ ChronoConfig, load_chrono_config)
+    Project Chrono multibody / multi-physics via PyChrono. **No ROS 2
+    dependency.** Chrono is the high-fidelity *validation* target: a
+    URML program is checked statically against the capability manifest
+    and safety envelope first, then the same validated intent is driven
+    through a short Chrono simulation segment and the dynamics (system
+    time, contacts, the commanded driver inputs) come back as evidence.
+    ``pychrono`` is imported lazily (it ships via conda-forge), so this
+    module loads on every host without it.
+"""
+
+from __future__ import annotations
+
+from urml_chrono_runtime._version import __version__
+from urml_chrono_runtime.adapter import ChronoAdapter, ChronoConfig, load_chrono_config
+from urml_chrono_runtime.terramechanics import TerramechanicsParams, TerramechanicsScene
+
+__all__ = [
+    "ChronoAdapter",
+    "ChronoConfig",
+    "TerramechanicsParams",
+    "TerramechanicsScene",
+    "__version__",
+    "load_chrono_config",
+]

urml_chrono_runtime/_version.py

@@ -0,0 +1,3 @@
+"""Package version. Bumped per release."""
+
+__version__ = "0.4.0"

urml_chrono_runtime/adapter.py

@@ -0,0 +1,352 @@
+"""ChronoAdapter — Project Chrono multibody physics, via ``pychrono``.
+
+Project Chrono is a high-fidelity open multibody and multi-physics
+engine (Chrono::Vehicle ground dynamics, terramechanics for deformable
+terrain, Chrono::Sensor) from the University of Wisconsin-Madison and
+the University of Parma. This adapter mirrors :class:`MujocoAdapter`:
+lazy ``pychrono``, **no ROS 2 dependency**, a lazily-built cached
+``ChSystem``, failures returned not raised.
+
+Chrono's distinctive role for URML is **high-fidelity pre-deployment
+validation** (RFC-0328): URML checks a program statically against the
+declared capability and safety envelope first, then drives the same
+validated intent through a short Chrono simulation segment so the
+dynamics come back as evidence the claim holds. URML composes *above*
+Chrono; it does not embed it.
+
+## v0.1 method coverage
+
+Supported (mapped onto a ``ChSystem`` advanced by driver inputs):
+
+- ``move_to`` / ``hover`` → apply the configured driver segment and
+  advance the engine ``steps_per_command`` steps (location → driver
+  inputs via :class:`ChronoConfig`); ``hover`` is a zero-input hold
+  (step in place).
+- ``wait`` → step the engine for the dwell.
+- ``measure`` → return the accumulated dynamics evidence (system time,
+  contact count, the last commanded driver inputs).
+- ``wait_for`` → step-then-check (a sim has no external event bus; the
+  step advances state and the predicate is evaluated once).
+- ``report`` → structured record to a local sink (no cloud — manifesto).
+- ``scan`` → documented **stub success**, mirroring PX4Adapter.run_scan.
+
+The primitive → driver-input altitude follows Project Chrono lead Dan
+Negrut's feedback on issue #746.
+
+Not supported by a bare vehicle / terramechanics model (returned, not
+raised): ``grasp`` / ``release``, ``dock``, ``detect``, ``capture``,
+``speak``, ``listen``. Perception primitives want a Chrono::Sensor
+companion (camera / lidar / GPS / IMU); manipulation wants an
+articulated-model companion. The drone trio ``take_off`` / ``land`` /
+``return_to_home`` are ``not_applicable_sim``.
+
+The committed unit suite exercises every path against a fake
+``pychrono`` injected into ``sys.modules`` (the technique px4-runtime /
+mujoco-runtime use); a Chrono::Vehicle terramechanics scene driven by a
+real engine is the documented calibration step in
+``chrono-integration.yml``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from urml_ros2_runtime.substrate.base import (
+    CaptureResult,
+    DetectionResult,
+    ListenResult,
+    ManipulationResult,
+    MeasurementResult,
+    NavigationResult,
+    ProgramCallResult,
+    ScanResult,
+    SubstrateResult,
+    WaitResult,
+    unsupported_program_call,
+)
+
+from urml_chrono_runtime._version import __version__
+from urml_chrono_runtime.config import ChronoConfig, DriverSegment, load_chrono_config
+
+__all__ = [
+    "ChronoAdapter",
+    "ChronoConfig",
+    "DriverSegment",
+    "__version__",
+    "load_chrono_config",
+]
+
+_NOT_SUPPORTED = (
+    "not_supported_in_base_sim: a bare Chrono::Vehicle / terramechanics model has no {capability}. "
+    "Pair it with a Chrono::Sensor or articulated-model companion; the URML "
+    "program, manifest, and validator are unchanged."
+)
+_NOT_APPLICABLE = "not_applicable_sim: {capability} has no meaning for a ground-vehicle physics model."
+
+
+def _require_pychrono() -> Any:
+    """Lazy-import pychrono with a clear, actionable error when missing."""
+    try:
+        import pychrono  # type: ignore[import-not-found,unused-ignore]
+    except ImportError as exc:
+        raise RuntimeError(
+            "pychrono is not installed. ChronoAdapter requires PyChrono.\n"
+            "  PyChrono ships via conda-forge, not as a PyPI wheel:\n"
+            "    conda install -c conda-forge pychrono\n"
+            "  (the [chrono] extra documents the boundary; pychrono is imported lazily)."
+        ) from exc
+    return pychrono
+
+
+class ChronoAdapter:
+    """Project Chrono adapter implementing the URML ROSAdapter Protocol."""
+
+    BRAND = "chrono"
+
+    def __init__(self, config: ChronoConfig | None = None) -> None:
+        self._chrono = _require_pychrono()
+        self._config = config or ChronoConfig()
+        self._system: Any = None
+        self._scene: Any = None  # set when config.scene == "terramechanics"
+        self._reports: list[dict[str, Any]] = []
+        self._last_evidence: dict[str, Any] | None = None
+        self._closed = False
+
+    def _sim(self) -> Any:
+        """Lazily build and cache the ``ChSystem`` (bare or terramechanics scene)."""
+        if self._system is not None:
+            return self._system
+        if self._config.scene == "terramechanics":
+            from urml_chrono_runtime.terramechanics import (
+                TerramechanicsParams,
+                TerramechanicsScene,
+            )
+
+            self._scene = TerramechanicsScene(
+                self._chrono, self._config.terramechanics or TerramechanicsParams()
+            )
+            self._system = self._scene.system
+        else:
+            ctor = self._chrono.ChSystemSMC if self._config.system_type == "SMC" else self._chrono.ChSystemNSC
+            self._system = ctor()
+        return self._system
+
+    def _advance(self, steps: int, driver: list[float] | None = None) -> None:
+        system = self._sim()
+        if self._scene is not None:
+            self._scene.advance(self._config.step_size, steps, driver)
+            return
+        for _ in range(max(1, steps)):
+            system.DoStepDynamics(self._config.step_size)
+
+    def _evidence(self, driver: list[float], steps: int) -> dict[str, Any]:
+        """Read the current ``ChSystem`` dynamics as a validation-evidence dict."""
+        system = self._sim()
+        ev: dict[str, Any] = {
+            "sim_time": float(system.GetChTime()),
+            "n_contacts": int(system.GetNcontacts()),
+            "steps": int(steps),
+            "driver": [float(v) for v in driver],
+            "terrain_class": self._config.terrain_fidelity,  # RFC-0381 hint, mirrored from the manifest
+            "backend": "pychrono",
+        }
+        if self._scene is not None:
+            # Richer terramechanics evidence (sinkage, contact force, tip margin).
+            ev.update(self._scene.evidence())
+        self._last_evidence = ev
+        return ev
+
+    def close(self) -> None:
+        self._closed = True
+
+    def __enter__(self) -> ChronoAdapter:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Supported
+    # ------------------------------------------------------------------
+
+    def send_navigation_goal(
+        self,
+        *,
+        location: str | None = None,
+        pose: dict[str, float] | None = None,
+        frame: str | None = None,
+        carrying: dict[str, Any] | None = None,
+        speed: float | None = None,
+    ) -> NavigationResult:
+        if location is None and pose is None:
+            return NavigationResult(success=False, reason="send_navigation_goal called without location or pose")
+        if location is not None:
+            seg = self._config.resolve_location(location)
+            if seg is None:
+                return NavigationResult(
+                    success=False,
+                    reason=f"location_not_configured: {location!r} is declared in the "
+                    "manifest but not mapped to a driver segment in chrono_adapter.yaml.",
+                )
+            driver = list(seg.driver)
+            steps = seg.steps or self._config.steps_per_command
+        else:
+            driver = [float(v) for v in (pose or {}).values()]
+            steps = self._config.steps_per_command
+        self._advance(steps, driver)
+        ev = self._evidence(driver, steps)
+        # final_pose is a flat dict[str, float]: the commanded driver vector as
+        # indexed scalars, plus the headline dynamics evidence the run produced.
+        final: dict[str, float] = {f"driver{i}": float(v) for i, v in enumerate(driver)}
+        final["sim_time"] = float(ev["sim_time"])
+        final["n_contacts"] = float(ev["n_contacts"])
+        return NavigationResult(success=True, final_pose=final, frame=frame or "vehicle")
+
+    def wait_passively(self, *, duration_seconds: float) -> SubstrateResult:
+        self._advance(self._config.steps_per_command)
+        return SubstrateResult(success=True)
+
+    def take_measurement(self, *, what: str, target: str | None, sensor: str | None) -> MeasurementResult:
+        system = self._sim()
+        ev = self._last_evidence or {
+            "sim_time": float(system.GetChTime()),
+            "n_contacts": int(system.GetNcontacts()),
+            "steps": 0,
+            "driver": [],
+            "backend": "pychrono",
+        }
+        payload: dict[str, Any] = {
+            "value": ev["n_contacts"],
+            "unit": "contacts",
+            "timestamp": ev["sim_time"],
+            "what": what,
+            **ev,
+        }
+        return MeasurementResult(success=True, payload=payload)
+
+    def wait_for_condition(
+        self,
+        *,
+        kind: Literal["event", "signal", "input", "sensor_threshold"],
+        name: str | None,
+        input_mode: str | None,
+        threshold: dict[str, Any] | None,
+        timeout_seconds: float | None,
+    ) -> WaitResult:
+        self._advance(self._config.steps_per_command)
+        return WaitResult(success=True, timed_out=False, payload=None)
+
+    def emit_report(
+        self,
+        *,
+        to: str,
+        facts: dict[str, Any],
+        attachments: list[str] | None,
+        status: Literal["success", "partial", "failure"],
+        severity: Literal["info", "notice", "warning", "error"],
+    ) -> SubstrateResult:
+        self._reports.append({"to": to, "status": status, "severity": severity, "facts": facts})
+        return SubstrateResult(success=True)
+
+    def run_scan(
+        self,
+        *,
+        area: dict[str, Any],
+        pattern: Literal["serpentine", "spiral", "grid", "adaptive"],
+        overlap: float,
+        altitude: float | None,
+        media: Literal["photo", "video", "sensor_only"],
+        sensor: str | None,
+    ) -> ScanResult:
+        return ScanResult(
+            success=True,
+            payload={"samples": [], "coverage": 0.0, "anomalies": [], "_note": "v0.1 ChronoAdapter scan: stub."},
+        )
+
+    # ------------------------------------------------------------------
+    # Not supported by a bare vehicle / terramechanics model
+    # ------------------------------------------------------------------
+
+    def send_manipulation_goal(
+        self,
+        *,
+        action: Literal["grasp", "release"],
+        target: dict[str, Any] | None = None,
+        force_n: float | None = None,
+        approach: Literal["top", "side", "front", "auto"] = "auto",
+        release_mode: Literal["drop", "place", "hand_to_user"] | None = None,
+        release_at: dict[str, Any] | str | None = None,
+    ) -> ManipulationResult:
+        return ManipulationResult(success=False, reason=_NOT_SUPPORTED.format(capability="manipulator controller"))
+
+    def send_docking_goal(self, *, station: str, service: str, until: str | None = None) -> NavigationResult:
+        return NavigationResult(success=False, reason=_NOT_SUPPORTED.format(capability="docking station"))
+
+    def query_detection(
+        self,
+        *,
+        object_class: str,
+        attributes: dict[str, Any] | None = None,
+        where_near: str | None = None,
+        where_within: float | None = None,
+    ) -> DetectionResult:
+        return DetectionResult(success=False, reason=_NOT_SUPPORTED.format(capability="Chrono::Sensor perception"))
+
+    def capture_media(
+        self,
+        *,
+        media: Literal["photo", "video"],
+        target: str | None,
+        duration_seconds: float | None,
+        attributes: dict[str, Any] | None,
+    ) -> CaptureResult:
+        return CaptureResult(success=False, reason=_NOT_SUPPORTED.format(capability="Chrono::Sensor camera"))
+
+    def emit_speech(
+        self,
+        *,
+        utterance: str,
+        locale: str | None,
+        style: Literal["notice", "warning", "conversational"],
+        interrupt: bool,
+    ) -> SubstrateResult:
+        return SubstrateResult(success=False, reason=_NOT_SUPPORTED.format(capability="speaker"))
+
+    def acquire_speech(
+        self,
+        *,
+        prompt: str | None,
+        locale: str | None,
+        timeout_seconds: float | None,
+        expected: Literal["free_form", "confirmation", "choice"],
+        choices: list[str] | None,
+    ) -> ListenResult:
+        return ListenResult(success=False, reason=_NOT_SUPPORTED.format(capability="microphone"))
+
+    def send_takeoff_goal(self, *, altitude: float, climb_rate: float | None = None) -> NavigationResult:
+        return NavigationResult(success=False, reason=_NOT_APPLICABLE.format(capability="take_off"))
+
+    def send_land_goal(
+        self,
+        *,
+        at: str | None = None,
+        precision: Literal["standard", "precise"] = "standard",
+    ) -> NavigationResult:
+        return NavigationResult(success=False, reason=_NOT_APPLICABLE.format(capability="land"))
+
+    def send_return_to_home_goal(
+        self,
+        *,
+        speed: float | None = None,
+        altitude: float | None = None,
+    ) -> NavigationResult:
+        return NavigationResult(success=False, reason=_NOT_APPLICABLE.format(capability="return_to_home"))
+
+    def call_named_program(
+        self,
+        *,
+        name: str,
+        args: dict[str, Any] | None = None,
+    ) -> ProgramCallResult:
+        """``call_program``: this substrate exposes no named programs (RFC-0015)."""
+        return unsupported_program_call("chrono_sim")

urml_chrono_runtime/config.py

@@ -0,0 +1,116 @@
+"""Deployment-side configuration for ``ChronoAdapter``.
+
+A Chrono validation run needs to know:
+
+- Which contact method the system uses (``system_type``: ``NSC``
+  non-smooth complementarity, or ``SMC`` smooth penalty).
+- The integration step size and how many steps to advance per command.
+- A mapping from manifest-declared location names to a **driver
+  segment**: the driver inputs (throttle / steering / braking, model
+  ordering) that drive the vehicle toward that named pose for one
+  command, mirroring the ROS 2 runtime's ``location_to_pose`` and the
+  MuJoCo runtime's ``location_to_target``.
+
+This altitude follows Project Chrono lead Dan Negrut's feedback on
+issue #746: align at Chrono's **motion primitives and driver inputs**,
+each manifest entry mapping to a concrete ``ChSystem`` configuration.
+These facts are model- and deployment-specific, so they do NOT belong
+in the URML program, manifest, or envelope. They live in a
+``chrono_adapter.yaml`` alongside the URML artifacts.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+from urml_chrono_runtime.terramechanics import TerramechanicsParams
+
+
+class DriverSegment(BaseModel):
+    """A named driver segment: the driver-input vector for one command.
+
+    The adapter applies ``driver`` (model-specific ordering, e.g.
+    ``[throttle, steering, braking]``) and advances the Chrono system;
+    ``driver`` is model-specific, which is exactly why it is deployment
+    config and not a URML-level concept.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    driver: list[float] = Field(
+        default_factory=list,
+        description="Driver-input vector applied for this command (model ordering).",
+    )
+    steps: int | None = Field(
+        default=None,
+        ge=1,
+        description="Physics steps for this segment; overrides steps_per_command when set.",
+    )
+
+
+class ChronoConfig(BaseModel):
+    """Chrono system + driver config."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    system_type: Literal["NSC", "SMC"] = Field(
+        default="NSC",
+        description="Contact method: NSC (complementarity) or SMC (penalty).",
+    )
+    step_size: float = Field(
+        default=1e-3,
+        gt=0.0,
+        description="Integration step size in seconds passed to DoStepDynamics.",
+    )
+    steps_per_command: int = Field(
+        default=200,
+        ge=1,
+        description="Physics steps advanced per navigation/wait command.",
+    )
+    location_to_segment: dict[str, DriverSegment] = Field(
+        default_factory=dict,
+        description="Map manifest-declared location names to a driver segment.",
+    )
+    terrain_fidelity: Literal["rigid", "deformable", "granular", "unmodeled"] | None = Field(
+        default=None,
+        description=(
+            "RFC-0381 terrain class this deployment runs over, mirrored from the "
+            "manifest's validation.terrain_fidelity. Recorded in the evidence; the "
+            "terramechanics scene reads it as the cue for deformable terrain."
+        ),
+    )
+    scene: Literal["bare", "terramechanics"] = Field(
+        default="bare",
+        description=(
+            "Which Chrono scene the adapter builds. 'bare' is a plain ChSystem "
+            "advanced by driver inputs (v0.1). 'terramechanics' builds a rig on "
+            "SCM deformable terrain and returns richer evidence (sinkage, contact "
+            "force, tip margin); pair it with terrain_fidelity: deformable."
+        ),
+    )
+    terramechanics: TerramechanicsParams | None = Field(
+        default=None,
+        description="Soil + rig parameters for the terramechanics scene; defaults used when omitted.",
+    )
+
+    def resolve_location(self, name: str) -> DriverSegment | None:
+        """Return the driver segment for a named location, or None if unmapped.
+
+        Unmapped names produce a ``NavigationResult(success=False)`` with a
+        ``location_not_configured`` reason; they do not raise.
+        """
+        return self.location_to_segment.get(name)
+
+
+def load_chrono_config(path: str | Path) -> ChronoConfig:
+    """Parse a ``chrono_adapter.yaml`` file into a ``ChronoConfig``."""
+    p = Path(path)
+    with p.open(encoding="utf-8") as fh:
+        data = yaml.safe_load(fh) or {}
+    if not isinstance(data, dict):
+        raise ValueError(f"chrono-config file {p} did not contain a YAML mapping at the top level.")
+    return ChronoConfig.model_validate(data)

urml_chrono_runtime/terramechanics.py

@@ -0,0 +1,223 @@
+"""TerramechanicsScene — a rig on Chrono SCM deformable terrain.
+
+The bundled Chrono::Vehicle terramechanics scene the runtime's status note
+flagged as a follow-up, and the richer evidence Project Chrono lead Dan Negrut
+pointed at on `projectchrono/chrono` issue #746: contact forces, sinkage, and a
+tip-stability margin, exercised over a *deformable* terrain model rather than a
+bare rigid `ChSystem`.
+
+The role is unchanged from the rest of the runtime (RFC-0328): URML validates a
+program statically against the capability manifest and the safety envelope
+*first*, then drives the same validated intent through this scene so the
+high-fidelity dynamics come back as evidence. The scene is selected by the
+manifest's `validation.terrain_fidelity: deformable` hint (RFC-0381), mirrored
+into `ChronoConfig.terrain_fidelity`; URML never models the soil itself, it only
+declares the fidelity it expects and reads back what Chrono computed.
+
+## What is verified where
+
+The URML-side wiring — selecting the deformable scene from the config, driving
+the rig with the resolved driver segment, and shaping sinkage / contact force /
+tip margin into the validation-evidence payload — is exercised hermetically by
+the committed unit suite against a fake `pychrono` (the technique the rest of the
+runtime uses). The live SCM construction against a real PyChrono build is the
+documented **calibration step** (the px4 / mujoco / opcua convention): the exact
+SCM getter surface is version-sensitive, so each physics read is wrapped and
+degrades to an honest ``unavailable`` note rather than crashing, and the pinned
+scene is verified in ``chrono-integration.yml``'s ``chrono-sitl-e2e`` job.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TerramechanicsParams(BaseModel):
+    """Soil + rig parameters for the SCM deformable-terrain scene.
+
+    Bekker-Wong pressure-sinkage plus Janosi-Hanamoto shear, the standard SCM
+    (Soil Contact Model) parameter set. Defaults approximate a soft sandy loam.
+    These are model- and deployment-specific, so they live in adapter config
+    (``chrono_adapter.yaml``), never in the URML program, manifest, or envelope.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    terrain_length_m: float = Field(default=4.0, gt=0.0)
+    terrain_width_m: float = Field(default=2.0, gt=0.0)
+    mesh_resolution_m: float = Field(default=0.04, gt=0.0)
+    rig_mass_kg: float = Field(default=250.0, gt=0.0)
+    tip_threshold_deg: float = Field(
+        default=35.0,
+        gt=0.0,
+        description="Roll/pitch angle past which the rig is treated as unstable (tip margin = threshold - |tilt|).",
+    )
+    drawbar_gain_n: float = Field(
+        default=1500.0,
+        ge=0.0,
+        description="Forward force per unit of driver[0] (throttle) applied to the rig, N.",
+    )
+    # Bekker-Wong / Janosi soil parameters (SCM).
+    bekker_kphi: float = Field(default=0.2e6, description="Bekker frictional modulus k_phi, Pa/m^n.")
+    bekker_kc: float = Field(default=0.0, description="Bekker cohesive modulus k_c, Pa/m^(n-1).")
+    bekker_n: float = Field(default=1.1, gt=0.0, description="Bekker sinkage exponent n.")
+    mohr_cohesion_pa: float = Field(default=0.0, ge=0.0, description="Mohr-Coulomb cohesion, Pa.")
+    mohr_friction_deg: float = Field(default=30.0, description="Mohr-Coulomb internal friction angle, deg.")
+    janosi_shear_m: float = Field(default=0.01, gt=0.0, description="Janosi-Hanamoto shear deformation modulus, m.")
+
+
+def _unavailable(reason: str) -> dict[str, Any]:
+    return {"value": None, "note": f"unavailable: {reason}"}
+
+
+class TerramechanicsScene:
+    """A rigid rig resting on an SCM deformable-terrain patch, via ``pychrono``.
+
+    Holds a cached ``ChSystemSMC`` (SCM contact requires the smooth/penalty
+    method), an SCM terrain patch, and a rigid rig body. ``advance`` applies the
+    driver and steps both; ``evidence`` reads sinkage, the peak contact force,
+    and the tip-stability margin. The scene is built lazily by the adapter only
+    when ``ChronoConfig.scene == "terramechanics"``.
+    """
+
+    TERRAIN_MODEL = "scm_deformable"
+
+    def __init__(self, chrono: Any, params: TerramechanicsParams) -> None:
+        self._ch = chrono
+        self._p = params
+        self._veh = self._import_vehicle()
+        self.system: Any = chrono.ChSystemSMC()
+        self._terrain: Any = None
+        self._rig: Any = None
+        self._rig_z0: float = 0.0
+        self._notes: list[str] = []
+        self._build()
+
+    def _import_vehicle(self) -> Any:
+        """Resolve the ``pychrono.vehicle`` module (attribute first, then import)."""
+        veh = getattr(self._ch, "vehicle", None)
+        if veh is not None:
+            return veh
+        try:
+            import pychrono.vehicle as veh  # type: ignore[import-not-found,unused-ignore]
+        except ImportError as exc:  # pragma: no cover - calibration-only path
+            raise RuntimeError(
+                "pychrono.vehicle is required for the terramechanics scene.\n"
+                "  It ships with PyChrono from conda-forge: conda install -c conda-forge pychrono"
+            ) from exc
+        return veh
+
+    # ------------------------------------------------------------------
+    # Construction (calibration-gated against a real PyChrono build)
+    # ------------------------------------------------------------------
+
+    def _build(self) -> None:
+        p = self._p
+        terrain = self._veh.SCMTerrain(self.system)
+        terrain.SetSoilParameters(
+            p.bekker_kphi,
+            p.bekker_kc,
+            p.bekker_n,
+            p.mohr_cohesion_pa,
+            p.mohr_friction_deg,
+            p.janosi_shear_m,
+        )
+        terrain.Initialize(p.terrain_length_m, p.terrain_width_m, p.mesh_resolution_m)
+        self._terrain = terrain
+
+        rig = self._ch.ChBody()
+        rig.SetMass(p.rig_mass_kg)
+        self.system.AddBody(rig)
+        self._rig = rig
+        self._rig_z0 = self._body_z(rig)
+
+    # ------------------------------------------------------------------
+    # Stepping
+    # ------------------------------------------------------------------
+
+    def advance(self, step_size: float, steps: int, driver: list[float] | None = None) -> None:
+        if driver:
+            self._apply_driver(driver)
+        for _ in range(max(1, steps)):
+            self._advance_terrain(step_size)
+            self.system.DoStepDynamics(step_size)
+
+    def _apply_driver(self, driver: list[float]) -> None:
+        """Apply driver[0] (throttle) as a forward drawbar force on the rig."""
+        force = float(driver[0]) * self._p.drawbar_gain_n
+        try:
+            self._rig.EmptyAccumulators()
+            self._rig.AccumulateForce(
+                self._ch.ChVector3d(force, 0.0, 0.0), self._rig.GetPos(), False
+            )
+        except Exception as exc:  # pragma: no cover - calibration-only path
+            self._note(f"driver_force {type(exc).__name__}")
+
+    def _advance_terrain(self, step_size: float) -> None:
+        try:
+            self._terrain.Advance(step_size)
+        except Exception as exc:  # pragma: no cover - calibration-only path
+            self._note(f"terrain_advance {type(exc).__name__}")
+
+    # ------------------------------------------------------------------
+    # Evidence
+    # ------------------------------------------------------------------
+
+    def evidence(self) -> dict[str, Any]:
+        """Richer terramechanics evidence for the validation payload."""
+        ev: dict[str, Any] = {
+            "terrain_model": self.TERRAIN_MODEL,
+            "sinkage_m": self._sinkage_m(),
+            "max_contact_force_n": self._max_contact_force_n(),
+            "tip_margin_deg": self._tip_margin_deg(),
+        }
+        if self._notes:
+            ev["terramechanics_notes"] = list(self._notes)
+        return ev
+
+    def _sinkage_m(self) -> float | None:
+        try:
+            return max(0.0, self._rig_z0 - self._body_z(self._rig))
+        except Exception as exc:  # pragma: no cover - calibration-only path
+            self._note(f"sinkage {type(exc).__name__}")
+            return None
+
+    def _max_contact_force_n(self) -> float | None:
+        try:
+            f = self._terrain.GetContactForceBody(self._rig)
+            return float(f.Length())
+        except Exception as exc:  # pragma: no cover - calibration-only path
+            self._note(f"contact_force {type(exc).__name__}")
+            return None
+
+    def _tip_margin_deg(self) -> float | None:
+        try:
+            roll, pitch = self._rig_roll_pitch_deg()
+            return self._p.tip_threshold_deg - max(abs(roll), abs(pitch))
+        except Exception as exc:  # pragma: no cover - calibration-only path
+            self._note(f"tip_margin {type(exc).__name__}")
+            return None
+
+    # ------------------------------------------------------------------
+    # Small physics reads
+    # ------------------------------------------------------------------
+
+    def _body_z(self, body: Any) -> float:
+        return float(body.GetPos().z)
+
+    def _rig_roll_pitch_deg(self) -> tuple[float, float]:
+        """Roll and pitch of the rig from its orientation quaternion, in degrees."""
+        q = self._rig.GetRot()
+        w, x, y, z = float(q.e0), float(q.e1), float(q.e2), float(q.e3)
+        # Standard quaternion -> roll (x) / pitch (y), ZYX convention.
+        roll = math.atan2(2.0 * (w * x + y * z), 1.0 - 2.0 * (x * x + y * y))
+        sin_pitch = max(-1.0, min(1.0, 2.0 * (w * y - z * x)))
+        pitch = math.asin(sin_pitch)
+        return math.degrees(roll), math.degrees(pitch)
+
+    def _note(self, msg: str) -> None:
+        if msg not in self._notes:
+            self._notes.append(msg)

urml_chrono_runtime-0.4.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: urml-chrono-runtime
+Version: 0.4.0
+Summary: High-fidelity validation runtime for URML — Project Chrono multibody physics, zero ROS.
+Project-URL: Homepage, https://github.com/URML-MARS/URML
+Project-URL: Repository, https://github.com/URML-MARS/URML
+Project-URL: Issues, https://github.com/URML-MARS/URML/issues
+Author: URML Maintainers
+License: Apache-2.0
+Keywords: chrono,pychrono,robotics,runtime,simulation,terramechanics,urml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: urml-ros2-runtime>=0.4.0
+Requires-Dist: urml-validator>=0.4.0
+Provides-Extra: chrono
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
+</p>
+
+<p align="center">
+  A small, opinionated, human-readable language for describing robot intent.
+</p>
+
+<p align="center">
+  <a href="https://urml.dev"><b>urml.dev</b></a>
+</p>
+
+---
+
+# urml-chrono-runtime
+
+**High-fidelity validation reference runtime for URML** — `ChronoAdapter` for **Project Chrono** multibody / multi-physics, via `pychrono`.
+
+Project Chrono is an open high-fidelity multibody engine (Chrono::Vehicle ground dynamics, terramechanics for deformable terrain, Chrono::Sensor) from the University of Wisconsin-Madison and the University of Parma. This adapter mirrors `MujocoAdapter` / `PX4Adapter`: lazy `pychrono`, **no ROS 2 dependency**, a lazily-built cached `ChSystem`, failures returned not raised. Built against the frozen substrate Protocol per [RFC-0014](../../docs/rfcs/0014-substrate-conformance.md).
+
+Chrono's distinctive role for URML is **high-fidelity pre-deployment validation** ([RFC-0328](../../docs/rfcs/0328-project-chrono-outreach.md)): URML checks a program statically against the declared capability manifest and active safety envelope first, then drives the same validated intent through a short Chrono simulation segment so the dynamics come back as evidence. URML composes **above** Chrono; it never embeds it. The differentiator is the static capability-and-envelope check *before* the expensive multibody solver ever spins, so the high-fidelity run only ever exercises admissible programs.
+
+The primitive → driver-input altitude follows Project Chrono lead Dan Negrut's feedback on [issue #746](https://github.com/projectchrono/chrono/issues/746): align each manifest entry to a concrete `ChSystem` configuration at the level of Chrono's motion primitives and driver inputs.
+
+## Method coverage
+
+| URML primitive | v0.1 |
+|---|---|
+| `move_to` / `hover` | apply the configured driver segment, advance the `ChSystem` `steps_per_command` steps, return the dynamics evidence (sim time, contacts, commanded driver inputs) |
+| `wait` | step the engine |
+| `measure` | return the accumulated dynamics evidence (`value`=contacts, `sim_time`, `driver`, `backend`) |
+| `wait_for` | step-then-check (a sim has no external event bus) |
+| `report` | structured record to a local sink (no cloud) |
+| `scan` | documented **stub success** (mirrors `PX4Adapter.run_scan`) |
+
+`grasp`/`release`, `dock`, `detect`, `capture`, `speak`, `listen` return `not_supported_in_base_sim` (a Chrono::Sensor or articulated-model companion supplies them under the unchanged program, manifest, and validator). The drone trio returns `not_applicable_sim`.
+
+## Install / use
+
+PyChrono ships via **conda-forge**, not as a PyPI wheel. The `[chrono]` extra is intentionally empty (it documents the boundary); `pychrono` is imported lazily, so this module loads on every host without it.
+
+```bash
+conda install -c conda-forge pychrono            # the engine
+pip install -e reference/chrono-runtime[chrono]   # the adapter
+```
+
+```python
+from urml_chrono_runtime import ChronoAdapter, ChronoConfig
+from urml_chrono_runtime.adapter import DriverSegment
+cfg = ChronoConfig(steps_per_command=200,
+                   location_to_segment={"ridge_waypoint": DriverSegment(driver=[0.8, 0.1, 0.0])})
+with ChronoAdapter(cfg) as sim:
+    r = sim.send_navigation_goal(location="ridge_waypoint")
+    assert r.success and r.final_pose["sim_time"] > 0.0
+```
+
+Without `pychrono` installed, `ChronoAdapter()` raises a clear error pointing at conda-forge.
+
+## Status
+
+**v0.1 (this release):**
+- `ChronoAdapter` + `ChronoConfig` (PyChrono, no ROS). `chrono_vehicle_cell` manifest + `conformance/fixtures/home/21_chrono_vehicle_terrain_positive.yaml` verified through the runner (hermetic against `MockROSAdapter`; adapter-agnostic against `ChronoAdapter`).
+- **Terramechanics scene** (`scene: terramechanics`): a rig on Chrono SCM deformable terrain, selected by the manifest's `validation.terrain_fidelity: deformable` hint (RFC-0381). The validation-evidence payload gains **sinkage, peak contact force, and a tip-stability margin** alongside the base dynamics — the richer evidence Project Chrono lead Dan Negrut pointed at on [#746](https://github.com/projectchrono/chrono/issues/746). See [`terramechanics.py`](src/urml_chrono_runtime/terramechanics.py) and [`chrono_adapter.terramechanics.yaml`](chrono_adapter.terramechanics.yaml).
+- Hermetic unit tests: navigation (configured + unmapped), the NSC/SMC system-type switch, measure (validation-evidence payload), scan-stub, lifecycle, the not-supported / not-applicable-sim sentinels, the missing-`pychrono` (conda-pointing) error, the conformance hook, and the **terramechanics scene** (sinkage / contact-force / tip-margin evidence, driver-force application, bare-path regression) — no pychrono install required (a fake `pychrono`, with a `vehicle`/SCM surface, is injected into `sys.modules`).
+- Gated `.github/workflows/chrono-integration.yml`: `chrono-smoke` (real pychrono from conda-forge + the hermetic suite + the live smoke) and `chrono-sitl-e2e` against a real Chrono::Vehicle scene (first run is a calibration run by design — the established px4 / mujoco / opcua convention). The live SCM scene is that calibration target: its physics reads are version-sensitive, so each degrades to an honest `unavailable` note rather than crashing.
+- [`SPEC-GAPS.md`](SPEC-GAPS.md): the two manifest gaps the mapping surfaced (terrain-fidelity + simulator-target-class hints) shipped as RFC-0381; the terramechanics scene now reads the terrain-fidelity hint.
+
+**Follow-ups (not yet):** a true sentence→motion validation video; a Chrono::Sensor companion for `detect` / `capture`; a full Chrono::Vehicle (HMMWV-class) model under the rig, pinned in CI.
+
+## Core Commitment
+
+This runtime is Apache 2.0. It is outside the [Core Commitment](../../CORE_COMMITMENT.md) boundary (only ROS 2 + PX4 reference runtimes are named there) but carries the same no-vendor-coupling, no-cloud, no-enterprise-edition posture. PyChrono / Project Chrono is BSD-3-Clause (confirmed by the maintainers on #746); a validated-intent mapping carries no license entanglement.
+
+## Related documents
+
+- [`/reference/mujoco-runtime/`](../mujoco-runtime/) — the zero-ROS simulator sibling whose structure this mirrors.
+- [`/docs/rfcs/0328-project-chrono-outreach.md`](../../docs/rfcs/0328-project-chrono-outreach.md) — the engagement and mapping this implements.
+- [`/docs/rfcs/0014-substrate-conformance.md`](../../docs/rfcs/0014-substrate-conformance.md) — the conformance contract this is built against.
+- [`/conformance/`](../../conformance/) — the test suite that decides conformance.

urml_chrono_runtime-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+urml_chrono_runtime/__init__.py,sha256=gNgCyvZ8gL86nbEQChXnWVJWPtrv_d0KzZyUCTqQb8E,1091
+urml_chrono_runtime/_version.py,sha256=E5rRAxDRNIsA89ZzGERJeca0a74MUnpI6Avs1JFLuv0,66
+urml_chrono_runtime/adapter.py,sha256=mZwxTF0K2qACFMFP6KBJSvw87v9HnsJLDfHIKLcBRIc,13779
+urml_chrono_runtime/config.py,sha256=QeHwWEGOHxmTQq_LgRYJXiLcnO4Eg4aKi1vt9yICGN0,4510
+urml_chrono_runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+urml_chrono_runtime/terramechanics.py,sha256=3_d_W87XGJm-y8zdsSq5FMj8-LHc_ZYUKf_tCtR9ExM,9783
+urml_chrono_runtime-0.4.0.dist-info/METADATA,sha256=TZAXCzbj3xXjsP3TJ2Ho6xfLjcJ4ELicOC_BKP3boSo,8029
+urml_chrono_runtime-0.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+urml_chrono_runtime-0.4.0.dist-info/RECORD,,

urml_chrono_runtime-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any