Space Robotics Bench architecture
SRB separates environment contracts, task composition, and adapters for training, data, CLI, and real-system workflows. Supported claims follow the Modelling Envelope.
Subsystems
| Area | Owner | Responsibility |
|---|---|---|
| Contracts and runtime | srb/core/ | Environment lifecycle, actions, specs, spaces, sensors, and capability evidence. |
| Assets and terrain | srb/assets/, srb/terrain/ | Robot and scene assets; terrain resolution, ingestion, fusion, materials, and lighting. |
| Tasks | srb/tasks/ | Scene composition, observations, rewards, and episode outcomes. |
| Wrappers and integrations | srb/wrappers/, srb/integrations/ | Environment wrappers and framework adapters. |
| Data and experiments | srb/datasets/, srb/experiments/ | Dataset formats and validation, model artifacts, and experiment workflows. |
| Sim-to-real | srb/interfaces/sim_to_real/ | Deployment contracts, real-system adapters, and validation. |
| Products and configuration | srb/cli/, crates/srb_gui/, apps/, srb/hydra/ | CLI, GUI, launch configuration, and configuration composition. srb_gui contains the GUI implementation; srb, srb_py, and srb_sys are placeholders. |
Dependency direction
Shared contracts are the base. Core runtime, assets, and terrain build on them; tasks compose them; wrappers and integrations adapt them. CLI, GUI, datasets, experiments, and sim-to-real workflows consume these interfaces. Lower-level packages must not import upward. srb/composition.py binds subsystem contracts; srb/__main__.py delegates to the CLI.
Cross-framework coercion belongs in srb/core/spaces/. Batched torch tensors stay on env.device inside environments; NumPy, CPU, JAX, framework objects, ROS messages, and process arguments belong at adapter boundaries. The Rust GUI communicates through command contracts, not Python implementation details.
Import layers are checked by tests/unit/test_import_layering.py. Standard wrapper composition belongs to srb/wrappers/; task semantics remain with tasks. Dataset formats and GUI command arguments stay distinct, joined by explicit adapters. srb/utils/artifact_identity.py owns canonical artifact identity and hashing.
Environment and task interfaces
An SRB environment uses Isaac Lab DirectEnv and owns its environment count, device, and single and batched spaces. Each step applies actions, advances physics and sensors, then computes observations, rewards, termination, and truncation. Actions and specs belong to srb/core/action/ and srb/core/spec/; introspection and coercion belong to EnvIntrospector and srb/core/spaces/.
Tasks may read physics state for observations, rewards, and outcomes, but must not create physical success by rewriting material state. Privileged simulator state must not silently enter a frozen actor contract or determine acceptance.
Terrain selection and baking belong to srb/terrain/; tasks consume resolved products. The landscaping task and its adapters share the frozen action, observation, map, freshness, and fingerprint contract in srb/terrain/landscaping_contract.py. Physical effects flow through simulator contacts.
CLI, evaluation, and provenance
CLI parser construction stays lightweight and avoids simulator imports. Parser-only help and completion remain host-light; commands needing a live task registry use the shared simulator launch path. The GUI owns command construction and launch behavior; the CLI is its process interface.
The CLI records invocation and system provenance before allocation, then effective task and agent configurations. Arguments after -- remain distinct from Hydra overrides. Unknown values stay absent; simulator metadata reports observed runtime identity.
Evaluation uses a separate directory from training. Bounded evaluation counts completed episodes per environment, reports return and task success separately, and marks missing success evidence or incomplete budgets. Termination alone is not task success; providers must preserve terminal observations and autoreset behavior.
Runtime invariants
- Actions precede physics and sensor updates; observations and rewards describe the resulting state.
- Termination and time-limit truncation remain separate.
- Reset is deterministic where the qualification protocol fixes it and does not preload task success.
- Environment tensors stay batched on
env.device; host conversion occurs at adapter boundaries. - Public action, observation, serialization, CLI, target/reset, and provenance contracts change only with their owners and consumers.
- Asset and terrain provenance remains attached through ingestion, baking, cache, simulator assets, and documentation.
- See the architecture test-backend policy for evidence scope, the capability ledger for readiness, and ADR-0030 for release claims.
Platform boundaries
| Surface | Host Python | Isaac Sim | GUI or GPU | ROS or physical system |
|---|---|---|---|---|
| Pure contracts, catalogs, manifests | Contract checks | Runtime consumer | Not required | Adapter consumer |
| Terrain ingest and fusion | Declared dependencies | Supported | Rendering only when requested | Named data sources |
| Environments and particle physics | Import boundary | Runtime | Required for visual and GPU claims | Simulation evidence only |
| Framework integrations | Unit contracts | Runtime proof when needed | Backend-specific | Not applicable |
| CLI | Parser and routing checks | Full simulator commands | Shared launch seam | Adapter entry point |
| Sim-to-real validation | Contracts and fake probes | Synthetic probes | As sensor requires | Physical evidence only on target |
Unsupported combinations fail closed. See the architecture test-backend policy, installation requirements, and the Modelling Envelope.
Performance and assets
Terrain fusion owns stage budgets in srb/terrain/fusion/budgets.py; terrain baking owns mesh and texture limits. Keep environment hot paths batched on env.device and avoid unnecessary Python loops, host round-trips, and rendering. Keep large generated, cached, rendered, and runtime files outside source control.
Source budgets are not throughput results. Published measurements must identify workload, timed boundary, source and simulator identity, device, and procedure.