devagent-physical-engine 0.10.0__py3-none-any.whl

devagent_physical_engine/setup_profile.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import json
+import os
+import platform
+import subprocess
+import tempfile
+from typing import Callable, Protocol, Sequence
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+
+UR5E_SIM_PROFILE = "ur5e-sim"
+ROS_DISTRO = "jazzy"
+QUALIFIED_UBUNTU_VERSION = "24.04"
+QUALIFIED_UBUNTU_CODENAME = "noble"
+ROS_SETUP = Path("/opt/ros/jazzy/setup.bash")
+ROS_APT_RELEASE_API = "https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest"
+
+UR5E_SIM_APT_PACKAGES: tuple[str, ...] = (
+    "ros-jazzy-desktop",
+    "ros-jazzy-moveit",
+    "ros-jazzy-ur",
+    "ros-jazzy-ur-simulation-gz",
+    "ros-jazzy-gz-ros2-control",
+    "ros-jazzy-ros2controlcli",
+)
+
+
+class SetupError(RuntimeError):
+    """Stable setup failure that is safe to surface to a user."""
+
+
+@dataclass(frozen=True, slots=True)
+class SystemCommandResult:
+    command: tuple[str, ...]
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+class SystemCommandRunner(Protocol):
+    def run(self, command: Sequence[str], *, timeout_s: float = 120.0) -> SystemCommandResult: ...
+
+
+class SubprocessSystemRunner:
+    """Execute fixed setup commands without a shell.
+
+    Read-only probes are captured for deterministic inspection. When
+    ``stream_mutations`` is enabled, apt/dpkg repository and package mutations inherit
+    the terminal so users see real installation progress instead of an apparently
+    frozen setup command.
+    """
+
+    _STREAMED_PROGRAMS = frozenset({"apt-get", "dpkg", "add-apt-repository"})
+
+    def __init__(self, *, stream_mutations: bool = False) -> None:
+        self.stream_mutations = stream_mutations
+
+    @staticmethod
+    def _program(command: Sequence[str]) -> str:
+        if command and command[0] == "sudo" and len(command) > 1:
+            return command[1]
+        return command[0] if command else ""
+
+    def run(self, command: Sequence[str], *, timeout_s: float = 120.0) -> SystemCommandResult:
+        if not command or any(not isinstance(part, str) or not part for part in command):
+            raise ValueError("setup_command_parts_invalid")
+        if timeout_s <= 0:
+            raise ValueError("setup_timeout_must_be_positive")
+        stream = self.stream_mutations and self._program(command) in self._STREAMED_PROGRAMS
+        try:
+            completed = subprocess.run(
+                list(command),
+                capture_output=not stream,
+                text=True,
+                timeout=timeout_s,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise SetupError(f"setup_command_timeout:{command[0]}") from exc
+        return SystemCommandResult(
+            tuple(command),
+            completed.returncode,
+            completed.stdout or "",
+            completed.stderr or "",
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class SetupCheck:
+    name: str
+    passed: bool
+    detail: str
+
+
+@dataclass(frozen=True, slots=True)
+class SetupPlan:
+    profile: str
+    checks: tuple[SetupCheck, ...]
+    packages: tuple[str, ...]
+    needs_ros_apt_source: bool
+    needs_install: bool
+
+    @property
+    def supported(self) -> bool:
+        required = {"linux", "ubuntu_24_04", "architecture"}
+        by_name = {check.name: check for check in self.checks}
+        return required.issubset(by_name) and all(by_name[name].passed for name in required)
+
+    def to_dict(self) -> dict:
+        return {
+            "profile": self.profile,
+            "supported": self.supported,
+            "needs_ros_apt_source": self.needs_ros_apt_source,
+            "needs_install": self.needs_install,
+            "packages": list(self.packages),
+            "checks": [
+                {"name": check.name, "passed": check.passed, "detail": check.detail}
+                for check in self.checks
+            ],
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class SetupResult:
+    plan: SetupPlan
+    changed_system: bool
+    verified: bool
+    failure_code: str | None = None
+
+    @property
+    def passed(self) -> bool:
+        return self.plan.supported and self.verified and self.failure_code is None
+
+    def to_dict(self) -> dict:
+        return {
+            "profile": self.plan.profile,
+            "passed": self.passed,
+            "changed_system": self.changed_system,
+            "verified": self.verified,
+            "failure_code": self.failure_code,
+            "plan": self.plan.to_dict(),
+        }
+
+
+def _read_os_release(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return values
+    for line in text.splitlines():
+        if "=" not in line or line.lstrip().startswith("#"):
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip().strip('"')
+    return values
+
+
+def _architecture_supported(machine: str) -> bool:
+    return machine.lower() in {"x86_64", "amd64", "aarch64", "arm64"}
+
+
+def _is_package_installed(runner: SystemCommandRunner, package: str) -> bool:
+    result = runner.run(["dpkg-query", "-W", "-f=${Status}", package], timeout_s=10.0)
+    return result.ok and result.stdout.strip() == "install ok installed"
+
+
+def _ros_apt_source_present(runner: SystemCommandRunner) -> bool:
+    return _is_package_installed(runner, "ros2-apt-source") or any(
+        path.exists()
+        for path in (
+            Path("/etc/apt/sources.list.d/ros2.sources"),
+            Path("/etc/apt/sources.list.d/ros2.list"),
+        )
+    )
+
+
+def _safe_ros_apt_asset(payload: dict) -> tuple[str, str]:
+    expected_suffix = f".{QUALIFIED_UBUNTU_CODENAME}_all.deb"
+    matches: list[tuple[str, str]] = []
+    for asset in payload.get("assets", []):
+        name = str(asset.get("name", ""))
+        url = str(asset.get("browser_download_url", ""))
+        if not name.startswith("ros2-apt-source_") or not name.endswith(expected_suffix):
+            continue
+        parsed = urlparse(url)
+        if parsed.scheme != "https" or parsed.hostname not in {"github.com", "objects.githubusercontent.com"}:
+            continue
+        matches.append((name, url))
+    if len(matches) != 1:
+        raise SetupError("ros_apt_source_asset_unavailable")
+    return matches[0]
+
+
+def download_latest_ros_apt_source(*, timeout_s: float = 30.0) -> Path:
+    headers = {"Accept": "application/vnd.github+json", "User-Agent": "devagent-physical-engine"}
+    try:
+        with urlopen(Request(ROS_APT_RELEASE_API, headers=headers), timeout=timeout_s) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+        _name, url = _safe_ros_apt_asset(payload)
+        with urlopen(Request(url, headers={"User-Agent": "devagent-physical-engine"}), timeout=timeout_s) as response:
+            data = response.read()
+    except SetupError:
+        raise
+    except Exception as exc:
+        raise SetupError("ros_apt_source_download_failed") from exc
+    if not data or len(data) > 20 * 1024 * 1024:
+        raise SetupError("ros_apt_source_download_invalid")
+    fd, raw_path = tempfile.mkstemp(prefix="devagent-ros2-apt-source-", suffix=".deb")
+    path = Path(raw_path)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+    except Exception:
+        path.unlink(missing_ok=True)
+        raise
+    return path
+
+
+class UR5eSimulationSetup:
+    def __init__(
+        self,
+        runner: SystemCommandRunner | None = None,
+        *,
+        os_release_path: Path | str = "/etc/os-release",
+        machine: str | None = None,
+        ros_setup: Path | str = ROS_SETUP,
+        downloader: Callable[[], Path] = download_latest_ros_apt_source,
+        verifier: Callable[[], bool] | None = None,
+        progress: Callable[[str], None] | None = None,
+    ) -> None:
+        self.runner = runner or SubprocessSystemRunner()
+        self.os_release_path = Path(os_release_path)
+        self.machine = machine or platform.machine()
+        self.ros_setup = Path(ros_setup)
+        self.downloader = downloader
+        self.verifier = verifier
+        self.progress = progress
+
+    @property
+    def _sudo(self) -> tuple[str, ...]:
+        return () if hasattr(os, "geteuid") and os.geteuid() == 0 else ("sudo",)
+
+    def _emit(self, message: str) -> None:
+        if self.progress is not None:
+            self.progress(message)
+
+    def inspect(self) -> SetupPlan:
+        os_release = _read_os_release(self.os_release_path)
+        checks = [
+            SetupCheck("linux", platform.system() == "Linux", platform.system()),
+            SetupCheck(
+                "ubuntu_24_04",
+                os_release.get("ID") == "ubuntu" and os_release.get("VERSION_ID") == QUALIFIED_UBUNTU_VERSION,
+                f"{os_release.get('ID', 'unknown')} {os_release.get('VERSION_ID', 'unknown')}",
+            ),
+            SetupCheck("architecture", _architecture_supported(self.machine), self.machine or "unknown"),
+        ]
+        if not all(check.passed for check in checks):
+            return SetupPlan(UR5E_SIM_PROFILE, tuple(checks), UR5E_SIM_APT_PACKAGES, False, True)
+
+        ros_ready = self.ros_setup.expanduser().is_file()
+        checks.append(SetupCheck("ros_setup", ros_ready, str(self.ros_setup)))
+        installed: list[str] = []
+        for package in UR5E_SIM_APT_PACKAGES:
+            if _is_package_installed(self.runner, package):
+                installed.append(package)
+        missing = tuple(package for package in UR5E_SIM_APT_PACKAGES if package not in installed)
+        checks.append(
+            SetupCheck(
+                "system_packages",
+                not missing,
+                "all required packages installed" if not missing else "missing:" + ",".join(missing),
+            )
+        )
+        apt_source = _ros_apt_source_present(self.runner)
+        checks.append(SetupCheck("ros_apt_source", apt_source, "configured" if apt_source else "missing"))
+        return SetupPlan(
+            UR5E_SIM_PROFILE,
+            tuple(checks),
+            UR5E_SIM_APT_PACKAGES,
+            needs_ros_apt_source=not apt_source,
+            needs_install=(not ros_ready) or bool(missing),
+        )
+
+    def _run_required(self, command: Sequence[str], *, timeout_s: float = 300.0) -> None:
+        result = self.runner.run(command, timeout_s=timeout_s)
+        if not result.ok:
+            raise SetupError(f"setup_command_failed:{command[-1] if command else 'unknown'}")
+
+    def install(self, plan: SetupPlan) -> SetupResult:
+        if not plan.supported:
+            return SetupResult(plan, changed_system=False, verified=False, failure_code="unsupported_platform")
+        if not plan.needs_install:
+            verified = self.verifier() if self.verifier is not None else True
+            return SetupResult(plan, changed_system=False, verified=verified, failure_code=None if verified else "post_install_verification_failed")
+
+        total_steps = 8 if plan.needs_ros_apt_source else 3
+        current_step = 0
+
+        def step(message: str) -> None:
+            nonlocal current_step
+            current_step += 1
+            self._emit(f"[{current_step}/{total_steps}] {message}")
+
+        downloaded: Path | None = None
+        try:
+            step("Updating apt indexes...")
+            self._run_required((*self._sudo, "apt-get", "update"))
+            if plan.needs_ros_apt_source:
+                step("Installing setup bootstrap packages...")
+                self._run_required((*self._sudo, "apt-get", "install", "-y", "software-properties-common", "curl"))
+                step("Enabling Ubuntu universe repository...")
+                self._run_required((*self._sudo, "add-apt-repository", "-y", "universe"))
+                step("Downloading official ROS 2 apt source...")
+                downloaded = self.downloader()
+                step("Installing official ROS 2 apt source...")
+                self._run_required((*self._sudo, "dpkg", "-i", str(downloaded)), timeout_s=120.0)
+                step("Refreshing ROS 2 apt indexes...")
+                self._run_required((*self._sudo, "apt-get", "update"))
+            step("Installing ROS 2 Jazzy, MoveIt, Gazebo and UR packages...")
+            self._run_required((*self._sudo, "apt-get", "install", "-y", *plan.packages), timeout_s=900.0)
+            step("Running DevAgent ROS verification...")
+            verified = self.verifier() if self.verifier is not None else self.ros_setup.expanduser().is_file()
+            return SetupResult(
+                plan,
+                changed_system=True,
+                verified=verified,
+                failure_code=None if verified else "post_install_verification_failed",
+            )
+        except SetupError as exc:
+            return SetupResult(plan, changed_system=True, verified=False, failure_code=str(exc))
+        finally:
+            if downloaded is not None:
+                downloaded.unlink(missing_ok=True)
+
+
+def format_setup_plan(plan: SetupPlan) -> str:
+    lines = ["DevAgent UR5e Simulation Setup", f"Profile: {plan.profile}", ""]
+    for check in plan.checks:
+        lines.append(f"{'PASS' if check.passed else 'MISSING'}  {check.name}: {check.detail}")
+    lines.extend(["", "Required system packages:"])
+    lines.extend(f"  - {package}" for package in plan.packages)
+    if plan.needs_ros_apt_source:
+        lines.append("  - official ros2-apt-source repository configuration")
+    lines.append("")
+    lines.append("System changes required." if plan.needs_install else "System stack already installed.")
+    return "\n".join(lines)

devagent_physical_engine/simulation.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .models import TaskNode, WorldState
+
+
+@dataclass(frozen=True, slots=True)
+class SimulationStep:
+    task_id: str
+    success: bool
+    satisfied_constraints: frozenset[str]
+    detail: str = ""
+
+
+class SimulationBackend(Protocol):
+    def run_task(self, task: TaskNode, world: WorldState) -> SimulationStep: ...
+
+
+class DeterministicSimulationBackend:
+    """Test backend with injected constraint failures; ROS/Gazebo will implement the same protocol."""
+
+    def __init__(self, fail_constraints_for: set[str] | None = None) -> None:
+        self._fail_constraints_for = fail_constraints_for or set()
+
+    def run_task(self, task: TaskNode, world: WorldState) -> SimulationStep:
+        constraints = set(task.contract.constraints)
+        if task.task_id in self._fail_constraints_for:
+            constraints.discard("collision_free")
+            return SimulationStep(task.task_id, False, frozenset(constraints), "injected_constraint_failure")
+        return SimulationStep(task.task_id, True, frozenset(constraints))

devagent_physical_engine/simulation_platform.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Protocol
+
+from .physical_motion import MotionExecutionMetrics, PhysicalMotionPlan
+from .robot_platform import (
+    QualificationState,
+    RobotProfileRegistry,
+    SimulationTier,
+)
+from .twin import TwinSpec
+
+
+class SimulationPlatformError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class AdapterHealth:
+    ready: bool
+    code: str = "ready"
+    details: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.code.strip():
+            raise ValueError("adapter_health_code_required")
+        if any(not item.strip() for item in self.details):
+            raise ValueError("empty_adapter_health_detail")
+
+
+@dataclass(frozen=True, slots=True)
+class SimulationAdapterDescriptor:
+    adapter_id: str
+    backend: str
+    robot_profile_keys: tuple[str, ...]
+    tier: SimulationTier
+    qualification: QualificationState
+    visual_capable: bool
+    headless_capable: bool
+    replay_capable: bool
+    metric_names: frozenset[str] = frozenset()
+    notes: tuple[str, ...] = ()
+    trajectory_runtime_qualification: QualificationState = QualificationState.NOT_QUALIFIED
+    twin_environment_qualification: QualificationState = QualificationState.NOT_QUALIFIED
+    preexecution_verification_qualification: QualificationState = QualificationState.NOT_QUALIFIED
+    metric_collection_qualification: QualificationState = QualificationState.NOT_QUALIFIED
+
+    def __post_init__(self) -> None:
+        if not self.adapter_id.strip() or not self.backend.strip():
+            raise ValueError("simulation_adapter_identity_required")
+        if not self.robot_profile_keys:
+            raise ValueError("simulation_adapter_robot_profiles_required")
+        if any(not key.strip() for key in self.robot_profile_keys):
+            raise ValueError("empty_simulation_adapter_robot_profile")
+        if len(set(self.robot_profile_keys)) != len(self.robot_profile_keys):
+            raise ValueError("duplicate_simulation_adapter_robot_profile")
+        if any(not metric.strip() for metric in self.metric_names):
+            raise ValueError("empty_simulation_metric_name")
+        if any(not note.strip() for note in self.notes):
+            raise ValueError("empty_simulation_adapter_note")
+
+    @property
+    def commissioning_scope_qualified(self) -> bool:
+        return all(
+            state is QualificationState.QUALIFIED
+            for state in (
+                self.qualification,
+                self.trajectory_runtime_qualification,
+                self.twin_environment_qualification,
+                self.preexecution_verification_qualification,
+                self.metric_collection_qualification,
+            )
+        )
+
+
+class RobotSimulationAdapter(Protocol):
+    """Universal simulation adapter consumed by measured physical campaigns.
+
+    High-level TaskGraph objects are deliberately not executable here. They must
+    first be compiled into a deterministic ``PhysicalMotionPlan``. An adapter is
+    commissioning-qualified only when trajectory execution, Twin materialization,
+    pre-execution verification, and metric collection are all separately qualified.
+    """
+
+    @property
+    def descriptor(self) -> SimulationAdapterDescriptor: ...
+
+    def doctor(self, *, robot_profile_key: str) -> AdapterHealth: ...
+
+    def prepare(self, *, twin: TwinSpec) -> str: ...
+
+    def reset(self, *, case_id: str, state: Mapping[str, Any]) -> None: ...
+
+    def execute_motion(self, *, motion: PhysicalMotionPlan) -> MotionExecutionMetrics: ...
+
+    def collect_metrics(self) -> Mapping[str, float | int | bool | str | None]: ...
+
+    def capture_state(self) -> Mapping[str, Any]: ...
+
+    def replay(self, *, case_id: str) -> Mapping[str, Any]: ...
+
+    def stop(self) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class SimulationSelection:
+    descriptor: SimulationAdapterDescriptor
+    robot_profile_key: str
+    profile_qualification: QualificationState
+
+    @property
+    def fully_qualified(self) -> bool:
+        return (
+            self.descriptor.qualification is QualificationState.QUALIFIED
+            and self.profile_qualification is QualificationState.QUALIFIED
+        )
+
+    @property
+    def commissioning_qualified(self) -> bool:
+        return (
+            self.profile_qualification is QualificationState.QUALIFIED
+            and self.descriptor.commissioning_scope_qualified
+        )
+
+
+class SimulationAdapterRegistry:
+    """Resolve simulator adapters without coupling DevAgent core to a vendor."""
+
+    def __init__(self, robot_profiles: RobotProfileRegistry) -> None:
+        self.robot_profiles = robot_profiles
+        self._adapters: dict[str, RobotSimulationAdapter] = {}
+
+    def register(self, adapter: RobotSimulationAdapter, *, replace: bool = False) -> None:
+        descriptor = adapter.descriptor
+        adapter_id = descriptor.adapter_id.strip().lower()
+        if adapter_id in self._adapters and not replace:
+            raise SimulationPlatformError(f"duplicate_simulation_adapter:{adapter_id}")
+        for key in descriptor.robot_profile_keys:
+            profile = self.robot_profiles.get(key)
+            if profile.key != key:
+                raise SimulationPlatformError(
+                    f"simulation_adapter_requires_canonical_robot_key:{key}"
+                )
+        self._adapters[adapter_id] = adapter
+
+    def get(self, adapter_id: str) -> RobotSimulationAdapter:
+        key = adapter_id.strip().lower()
+        try:
+            return self._adapters[key]
+        except KeyError as exc:
+            raise SimulationPlatformError(f"unknown_simulation_adapter:{key}") from exc
+
+    def descriptors(self) -> tuple[SimulationAdapterDescriptor, ...]:
+        return tuple(
+            self._adapters[key].descriptor for key in sorted(self._adapters)
+        )
+
+    def candidates(
+        self,
+        *,
+        robot_profile_key: str,
+        tier: SimulationTier,
+        require_qualified: bool = True,
+        require_commissioning_qualified: bool = False,
+        require_visual: bool = False,
+        require_replay: bool = False,
+    ) -> tuple[SimulationSelection, ...]:
+        profile = self.robot_profiles.resolve(robot_profile_key)
+        canonical_key = profile.key
+        profile_state = profile.qualification.state_for(tier)
+        selections: list[SimulationSelection] = []
+        for descriptor in self.descriptors():
+            if canonical_key not in descriptor.robot_profile_keys:
+                continue
+            if descriptor.tier is not tier:
+                continue
+            if require_visual and not descriptor.visual_capable:
+                continue
+            if require_replay and not descriptor.replay_capable:
+                continue
+            selection = SimulationSelection(
+                descriptor=descriptor,
+                robot_profile_key=canonical_key,
+                profile_qualification=profile_state,
+            )
+            if require_commissioning_qualified and not selection.commissioning_qualified:
+                continue
+            if require_qualified and not selection.fully_qualified:
+                continue
+            selections.append(selection)
+
+        return tuple(
+            sorted(
+                selections,
+                key=lambda item: (
+                    item.commissioning_qualified,
+                    item.descriptor.qualification is QualificationState.QUALIFIED,
+                    item.descriptor.replay_capable,
+                    item.descriptor.headless_capable,
+                    item.descriptor.adapter_id,
+                ),
+                reverse=True,
+            )
+        )
+
+    def resolve(
+        self,
+        *,
+        robot_profile_key: str,
+        tier: SimulationTier,
+        require_qualified: bool = True,
+        require_commissioning_qualified: bool = False,
+        require_visual: bool = False,
+        require_replay: bool = False,
+    ) -> SimulationSelection:
+        profile = self.robot_profiles.resolve(robot_profile_key)
+        selections = self.candidates(
+            robot_profile_key=profile.key,
+            tier=tier,
+            require_qualified=require_qualified,
+            require_commissioning_qualified=require_commissioning_qualified,
+            require_visual=require_visual,
+            require_replay=require_replay,
+        )
+        if selections:
+            return selections[0]
+        if require_commissioning_qualified:
+            mode = "commissioning_qualified"
+        else:
+            mode = "qualified" if require_qualified else "available"
+        raise SimulationPlatformError(
+            f"no_{mode}_simulation_adapter:{profile.key}:{tier.value}"
+        )
+
+    def capability_matrix(self) -> tuple[dict[str, Any], ...]:
+        rows: list[dict[str, Any]] = []
+        for profile in self.robot_profiles.all():
+            for tier in SimulationTier:
+                adapters = self.candidates(
+                    robot_profile_key=profile.key,
+                    tier=tier,
+                    require_qualified=False,
+                )
+                rows.append(
+                    {
+                        "robot": profile.key,
+                        "tier": tier.value,
+                        "profile_qualification": profile.qualification.state_for(tier).value,
+                        "adapters": [
+                            {
+                                "adapter_id": item.descriptor.adapter_id,
+                                "backend": item.descriptor.backend,
+                                "adapter_qualification": item.descriptor.qualification.value,
+                                "fully_qualified": item.fully_qualified,
+                                "commissioning_qualified": item.commissioning_qualified,
+                                "trajectory_runtime": item.descriptor.trajectory_runtime_qualification.value,
+                                "twin_environment": item.descriptor.twin_environment_qualification.value,
+                                "preexecution_verification": item.descriptor.preexecution_verification_qualification.value,
+                                "metric_collection": item.descriptor.metric_collection_qualification.value,
+                                "visual": item.descriptor.visual_capable,
+                                "headless": item.descriptor.headless_capable,
+                                "replay": item.descriptor.replay_capable,
+                            }
+                            for item in adapters
+                        ],
+                    }
+                )
+        return tuple(rows)