urml-chrono-runtime 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- urml_chrono_runtime-0.5.0/.gitignore +114 -0
- urml_chrono_runtime-0.5.0/PKG-INFO +110 -0
- urml_chrono_runtime-0.5.0/README.md +79 -0
- urml_chrono_runtime-0.5.0/SPEC-GAPS.md +64 -0
- urml_chrono_runtime-0.5.0/chrono_adapter.terramechanics.yaml +41 -0
- urml_chrono_runtime-0.5.0/pyproject.toml +77 -0
- urml_chrono_runtime-0.5.0/src/urml_chrono_runtime/__init__.py +27 -0
- urml_chrono_runtime-0.5.0/src/urml_chrono_runtime/_version.py +3 -0
- urml_chrono_runtime-0.5.0/src/urml_chrono_runtime/adapter.py +357 -0
- urml_chrono_runtime-0.5.0/src/urml_chrono_runtime/config.py +116 -0
- urml_chrono_runtime-0.5.0/src/urml_chrono_runtime/py.typed +0 -0
- urml_chrono_runtime-0.5.0/src/urml_chrono_runtime/terramechanics.py +223 -0
- urml_chrono_runtime-0.5.0/tests/__init__.py +0 -0
- urml_chrono_runtime-0.5.0/tests/integration/__init__.py +0 -0
- urml_chrono_runtime-0.5.0/tests/integration/test_chrono_adapter_live.py +62 -0
- urml_chrono_runtime-0.5.0/tests/test_chrono_adapter.py +167 -0
- urml_chrono_runtime-0.5.0/tests/test_terramechanics.py +201 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# --- Python ---
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
build/
|
|
8
|
+
dist/
|
|
9
|
+
develop-eggs/
|
|
10
|
+
downloads/
|
|
11
|
+
eggs/
|
|
12
|
+
.eggs/
|
|
13
|
+
lib/
|
|
14
|
+
lib64/
|
|
15
|
+
parts/
|
|
16
|
+
sdist/
|
|
17
|
+
var/
|
|
18
|
+
wheels/
|
|
19
|
+
*.egg-info/
|
|
20
|
+
.installed.cfg
|
|
21
|
+
*.egg
|
|
22
|
+
MANIFEST
|
|
23
|
+
|
|
24
|
+
# Virtual envs
|
|
25
|
+
.venv/
|
|
26
|
+
venv/
|
|
27
|
+
env/
|
|
28
|
+
ENV/
|
|
29
|
+
.python-version
|
|
30
|
+
|
|
31
|
+
# Test / coverage / mypy / pyright
|
|
32
|
+
.coverage
|
|
33
|
+
.coverage.*
|
|
34
|
+
.cache
|
|
35
|
+
.pytest_cache/
|
|
36
|
+
.mypy_cache/
|
|
37
|
+
.dmypy.json
|
|
38
|
+
.pyre/
|
|
39
|
+
.pyright/
|
|
40
|
+
htmlcov/
|
|
41
|
+
nosetests.xml
|
|
42
|
+
coverage.xml
|
|
43
|
+
*.cover
|
|
44
|
+
.hypothesis/
|
|
45
|
+
.tox/
|
|
46
|
+
|
|
47
|
+
# --- Node / web tooling (kept out of core repo; here for safety) ---
|
|
48
|
+
node_modules/
|
|
49
|
+
.pnp.*
|
|
50
|
+
.yarn/cache/
|
|
51
|
+
.yarn/unplugged/
|
|
52
|
+
.yarn/build-state.yml
|
|
53
|
+
.yarn/install-state.gz
|
|
54
|
+
npm-debug.log*
|
|
55
|
+
yarn-debug.log*
|
|
56
|
+
yarn-error.log*
|
|
57
|
+
|
|
58
|
+
# --- C++ / Rust build artifacts (in case reference runtimes land here in early Phase 1) ---
|
|
59
|
+
target/
|
|
60
|
+
*.o
|
|
61
|
+
*.obj
|
|
62
|
+
*.a
|
|
63
|
+
*.lib
|
|
64
|
+
*.dll
|
|
65
|
+
*.dylib
|
|
66
|
+
*.exe
|
|
67
|
+
*.pdb
|
|
68
|
+
cmake-build-*/
|
|
69
|
+
CMakeCache.txt
|
|
70
|
+
CMakeFiles/
|
|
71
|
+
CMakeScripts/
|
|
72
|
+
Testing/
|
|
73
|
+
cmake_install.cmake
|
|
74
|
+
install_manifest.txt
|
|
75
|
+
compile_commands.json
|
|
76
|
+
|
|
77
|
+
# --- ROS 2 build dirs ---
|
|
78
|
+
build/
|
|
79
|
+
install/
|
|
80
|
+
log/
|
|
81
|
+
|
|
82
|
+
# --- Editor and OS junk ---
|
|
83
|
+
.vscode/
|
|
84
|
+
.idea/
|
|
85
|
+
*.swp
|
|
86
|
+
*.swo
|
|
87
|
+
*~
|
|
88
|
+
.DS_Store
|
|
89
|
+
Thumbs.db
|
|
90
|
+
desktop.ini
|
|
91
|
+
|
|
92
|
+
# --- Local-only artifacts ---
|
|
93
|
+
.env
|
|
94
|
+
.env.*
|
|
95
|
+
*.log
|
|
96
|
+
*.tmp
|
|
97
|
+
.local/
|
|
98
|
+
.scratch/
|
|
99
|
+
|
|
100
|
+
# --- Outreach campaign artifacts (operational, not part of the open standard) ---
|
|
101
|
+
# Target lists, message drafts, tracking data, and the launch-approval record
|
|
102
|
+
# stay local. They are private to the maintainer; committing them would
|
|
103
|
+
# telegraph the campaign before launch and could embarrass listed projects.
|
|
104
|
+
outreach/
|
|
105
|
+
|
|
106
|
+
# Outreach dashboard SQLite mirror (RFC-0275). Derived from
|
|
107
|
+
# examples/lighthouses/outreach*.yaml via tools/scripts/refresh_outreach_db.py.
|
|
108
|
+
# Regenerated on demand by `make outreach-refresh`.
|
|
109
|
+
tools/outreach.db
|
|
110
|
+
tools/.outreach.db
|
|
111
|
+
|
|
112
|
+
# Local Claude Code settings (per-machine; permission rules, etc.). Not committed.
|
|
113
|
+
.claude/settings.json
|
|
114
|
+
.claude/settings.local.json
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: urml-chrono-runtime
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: High-fidelity validation runtime for URML — Project Chrono multibody physics, zero ROS.
|
|
5
|
+
Project-URL: Homepage, https://github.com/urml-dev/URML
|
|
6
|
+
Project-URL: Repository, https://github.com/urml-dev/URML
|
|
7
|
+
Project-URL: Issues, https://github.com/urml-dev/URML/issues
|
|
8
|
+
Author: URML Maintainers
|
|
9
|
+
License: BUSL-1.1
|
|
10
|
+
Keywords: chrono,pychrono,robotics,runtime,simulation,terramechanics,urml
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: Other/Proprietary License
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Requires-Dist: pydantic<3,>=2.6
|
|
21
|
+
Requires-Dist: pyyaml<7,>=6.0
|
|
22
|
+
Requires-Dist: urml-ros2-runtime>=0.5.0
|
|
23
|
+
Requires-Dist: urml-validator>=0.5.0
|
|
24
|
+
Provides-Extra: chrono
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: mypy>=1.10; extra == 'dev'
|
|
27
|
+
Requires-Dist: pytest-cov>=5; extra == 'dev'
|
|
28
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
29
|
+
Requires-Dist: ruff>=0.5; extra == 'dev'
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
<p align="center">
|
|
33
|
+
<a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
|
|
34
|
+
</p>
|
|
35
|
+
|
|
36
|
+
<p align="center">
|
|
37
|
+
A small, opinionated, human-readable language for describing robot intent.
|
|
38
|
+
</p>
|
|
39
|
+
|
|
40
|
+
<p align="center">
|
|
41
|
+
<a href="https://urml.dev"><b>urml.dev</b></a>
|
|
42
|
+
</p>
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
# urml-chrono-runtime
|
|
47
|
+
|
|
48
|
+
**High-fidelity validation reference runtime for URML** — `ChronoAdapter` for **Project Chrono** multibody / multi-physics, via `pychrono`.
|
|
49
|
+
|
|
50
|
+
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).
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
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.
|
|
55
|
+
|
|
56
|
+
## Method coverage
|
|
57
|
+
|
|
58
|
+
| URML primitive | v0.1 |
|
|
59
|
+
|---|---|
|
|
60
|
+
| `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) |
|
|
61
|
+
| `wait` | step the engine |
|
|
62
|
+
| `measure` | return the accumulated dynamics evidence (`value`=contacts, `sim_time`, `driver`, `backend`) |
|
|
63
|
+
| `wait_for` | step-then-check (a sim has no external event bus) |
|
|
64
|
+
| `report` | structured record to a local sink (no cloud) |
|
|
65
|
+
| `scan` | documented not-supported result: no area-scan controller (a scan is waypoints plus a capture at each one) |
|
|
66
|
+
|
|
67
|
+
`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`.
|
|
68
|
+
|
|
69
|
+
## Install / use
|
|
70
|
+
|
|
71
|
+
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.
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
conda install -c conda-forge pychrono # the engine
|
|
75
|
+
pip install -e reference/chrono-runtime[chrono] # the adapter
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
from urml_chrono_runtime import ChronoAdapter, ChronoConfig
|
|
80
|
+
from urml_chrono_runtime.adapter import DriverSegment
|
|
81
|
+
cfg = ChronoConfig(steps_per_command=200,
|
|
82
|
+
location_to_segment={"ridge_waypoint": DriverSegment(driver=[0.8, 0.1, 0.0])})
|
|
83
|
+
with ChronoAdapter(cfg) as sim:
|
|
84
|
+
r = sim.send_navigation_goal(location="ridge_waypoint")
|
|
85
|
+
assert r.success and r.final_pose["sim_time"] > 0.0
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Without `pychrono` installed, `ChronoAdapter()` raises a clear error pointing at conda-forge.
|
|
89
|
+
|
|
90
|
+
## Status
|
|
91
|
+
|
|
92
|
+
**v0.1 (this release):**
|
|
93
|
+
- `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`).
|
|
94
|
+
- **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).
|
|
95
|
+
- Hermetic unit tests: navigation (configured + unmapped), the NSC/SMC system-type switch, measure (validation-evidence payload), scan (not supported), 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`).
|
|
96
|
+
- 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.
|
|
97
|
+
- [`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.
|
|
98
|
+
|
|
99
|
+
**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.
|
|
100
|
+
|
|
101
|
+
## Core Commitment
|
|
102
|
+
|
|
103
|
+
Business Source License 1.1: free for non-production use, commercial license for production (see [`LICENSING.md`](../../LICENSING.md)). No vendor coupling, no cloud dependency. PyChrono / Project Chrono is BSD-3-Clause (confirmed by the maintainers on #746); a validated-intent mapping carries no license entanglement.
|
|
104
|
+
|
|
105
|
+
## Related documents
|
|
106
|
+
|
|
107
|
+
- [`/reference/mujoco-runtime/`](../mujoco-runtime/) — the zero-ROS simulator sibling whose structure this mirrors.
|
|
108
|
+
- [`/docs/rfcs/0328-project-chrono-outreach.md`](../../docs/rfcs/0328-project-chrono-outreach.md) — the engagement and mapping this implements.
|
|
109
|
+
- [`/docs/rfcs/0014-substrate-conformance.md`](../../docs/rfcs/0014-substrate-conformance.md) — the conformance contract this is built against.
|
|
110
|
+
- [`/conformance/`](../../conformance/) — the test suite that decides conformance.
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
A small, opinionated, human-readable language for describing robot intent.
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://urml.dev"><b>urml.dev</b></a>
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# urml-chrono-runtime
|
|
16
|
+
|
|
17
|
+
**High-fidelity validation reference runtime for URML** — `ChronoAdapter` for **Project Chrono** multibody / multi-physics, via `pychrono`.
|
|
18
|
+
|
|
19
|
+
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).
|
|
20
|
+
|
|
21
|
+
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.
|
|
22
|
+
|
|
23
|
+
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.
|
|
24
|
+
|
|
25
|
+
## Method coverage
|
|
26
|
+
|
|
27
|
+
| URML primitive | v0.1 |
|
|
28
|
+
|---|---|
|
|
29
|
+
| `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) |
|
|
30
|
+
| `wait` | step the engine |
|
|
31
|
+
| `measure` | return the accumulated dynamics evidence (`value`=contacts, `sim_time`, `driver`, `backend`) |
|
|
32
|
+
| `wait_for` | step-then-check (a sim has no external event bus) |
|
|
33
|
+
| `report` | structured record to a local sink (no cloud) |
|
|
34
|
+
| `scan` | documented not-supported result: no area-scan controller (a scan is waypoints plus a capture at each one) |
|
|
35
|
+
|
|
36
|
+
`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`.
|
|
37
|
+
|
|
38
|
+
## Install / use
|
|
39
|
+
|
|
40
|
+
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.
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
conda install -c conda-forge pychrono # the engine
|
|
44
|
+
pip install -e reference/chrono-runtime[chrono] # the adapter
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from urml_chrono_runtime import ChronoAdapter, ChronoConfig
|
|
49
|
+
from urml_chrono_runtime.adapter import DriverSegment
|
|
50
|
+
cfg = ChronoConfig(steps_per_command=200,
|
|
51
|
+
location_to_segment={"ridge_waypoint": DriverSegment(driver=[0.8, 0.1, 0.0])})
|
|
52
|
+
with ChronoAdapter(cfg) as sim:
|
|
53
|
+
r = sim.send_navigation_goal(location="ridge_waypoint")
|
|
54
|
+
assert r.success and r.final_pose["sim_time"] > 0.0
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Without `pychrono` installed, `ChronoAdapter()` raises a clear error pointing at conda-forge.
|
|
58
|
+
|
|
59
|
+
## Status
|
|
60
|
+
|
|
61
|
+
**v0.1 (this release):**
|
|
62
|
+
- `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`).
|
|
63
|
+
- **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).
|
|
64
|
+
- Hermetic unit tests: navigation (configured + unmapped), the NSC/SMC system-type switch, measure (validation-evidence payload), scan (not supported), 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`).
|
|
65
|
+
- 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.
|
|
66
|
+
- [`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.
|
|
67
|
+
|
|
68
|
+
**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.
|
|
69
|
+
|
|
70
|
+
## Core Commitment
|
|
71
|
+
|
|
72
|
+
Business Source License 1.1: free for non-production use, commercial license for production (see [`LICENSING.md`](../../LICENSING.md)). No vendor coupling, no cloud dependency. PyChrono / Project Chrono is BSD-3-Clause (confirmed by the maintainers on #746); a validated-intent mapping carries no license entanglement.
|
|
73
|
+
|
|
74
|
+
## Related documents
|
|
75
|
+
|
|
76
|
+
- [`/reference/mujoco-runtime/`](../mujoco-runtime/) — the zero-ROS simulator sibling whose structure this mirrors.
|
|
77
|
+
- [`/docs/rfcs/0328-project-chrono-outreach.md`](../../docs/rfcs/0328-project-chrono-outreach.md) — the engagement and mapping this implements.
|
|
78
|
+
- [`/docs/rfcs/0014-substrate-conformance.md`](../../docs/rfcs/0014-substrate-conformance.md) — the conformance contract this is built against.
|
|
79
|
+
- [`/conformance/`](../../conformance/) — the test suite that decides conformance.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
A small, opinionated, human-readable language for describing robot intent.
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://urml.dev"><b>urml.dev</b></a>
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# SPEC-GAPS — urml-chrono-runtime
|
|
16
|
+
|
|
17
|
+
Per the spec-gap protocol (RFC-0014): each runtime is built strictly
|
|
18
|
+
against the frozen substrate Protocol; anything a substrate needs that
|
|
19
|
+
URML cannot express is recorded here and, if genuinely inexpressible,
|
|
20
|
+
promoted to a numbered RFC Draft for maintainer decision, never a
|
|
21
|
+
silent primitive/schema change.
|
|
22
|
+
|
|
23
|
+
## Gaps
|
|
24
|
+
|
|
25
|
+
The substrate Protocol itself is **fully implemented with zero new
|
|
26
|
+
vocabulary**: `move_to`/`hover`/`wait`/`measure`/`wait_for`/`report`
|
|
27
|
+
map onto a `ChSystem` advanced by driver inputs, and `scan` is the
|
|
28
|
+
documented stub. Capabilities a *bare* vehicle / terramechanics model
|
|
29
|
+
lacks (`grasp`/`release`, `dock`, `detect`, `capture`, `speak`,
|
|
30
|
+
`listen`) are returned as honest unsuccessful `SubstrateResult`s, not
|
|
31
|
+
gaps in URML; a Chrono::Sensor or articulated-model companion supplies
|
|
32
|
+
them under the unchanged program, manifest, and validator.
|
|
33
|
+
|
|
34
|
+
The Chrono **mapping** surfaced two *manifest* gaps. Neither is bolted
|
|
35
|
+
on here; both are queued as Spec RFCs for maintainer decision, exactly
|
|
36
|
+
as flagged in [RFC-0328](../../docs/rfcs/0328-project-chrono-outreach.md):
|
|
37
|
+
|
|
38
|
+
1. **Terrain / terramechanics fidelity hint.** URML's manifest declares
|
|
39
|
+
capability, not the terrain a deployment runs over. An optional
|
|
40
|
+
terrain-fidelity hint (rigid / deformable / granular) would let the
|
|
41
|
+
envelope reason about a margin Chrono will exercise, without
|
|
42
|
+
modelling the terrain itself (that stays substrate configuration in
|
|
43
|
+
`chrono_adapter.yaml`).
|
|
44
|
+
|
|
45
|
+
2. **Simulator-target class hint.** URML does not declare whether a
|
|
46
|
+
deployment targets a high-fidelity multibody simulator, a game-grade
|
|
47
|
+
engine, or real hardware. An optional simulator-target-class hint
|
|
48
|
+
would let a fixture state the fidelity it was validated against.
|
|
49
|
+
Shared with the sibling Move #24 simulation RFCs.
|
|
50
|
+
|
|
51
|
+
Both hints shipped as [RFC-0381](../../docs/rfcs/0381-simulation-fidelity-manifest-hints.md)
|
|
52
|
+
(the optional `validation` block: `terrain_fidelity` +
|
|
53
|
+
`simulator_target_class`). The terramechanics scene
|
|
54
|
+
(`scene: terramechanics`) now reads the `terrain_fidelity: deformable`
|
|
55
|
+
hint and returns richer evidence (sinkage, peak contact force,
|
|
56
|
+
tip-stability margin) over a Chrono SCM deformable-terrain model; the
|
|
57
|
+
bare `ChSystem` evidence (system time, contact count, commanded driver
|
|
58
|
+
inputs) remains the default. The live SCM construction is the documented
|
|
59
|
+
calibration step in `chrono-integration.yml`: its physics getter surface
|
|
60
|
+
is version-sensitive, so each read degrades to an honest `unavailable`
|
|
61
|
+
note rather than crashing, and the pinned version is verified there.
|
|
62
|
+
|
|
63
|
+
No primitive, manifest field, or behavior-semantic change is made by
|
|
64
|
+
this runtime.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Example chrono_adapter.yaml for the terramechanics scene.
|
|
2
|
+
#
|
|
3
|
+
# Deployment-side configuration for ChronoAdapter (NOT a URML artifact: these
|
|
4
|
+
# facts are model- and deployment-specific, so they live here, never in the
|
|
5
|
+
# URML program, manifest, or envelope). Pairs with a manifest that declares
|
|
6
|
+
# `validation.terrain_fidelity: deformable` (RFC-0381); the adapter mirrors that
|
|
7
|
+
# into `terrain_fidelity` below and builds the SCM deformable-terrain scene.
|
|
8
|
+
#
|
|
9
|
+
# from urml_chrono_runtime import ChronoAdapter, load_chrono_config
|
|
10
|
+
# cfg = load_chrono_config("chrono_adapter.terramechanics.yaml")
|
|
11
|
+
# with ChronoAdapter(cfg) as sim:
|
|
12
|
+
# r = sim.send_navigation_goal(location="ridge_waypoint")
|
|
13
|
+
# # r.final_pose + a measure() now carry sinkage_m, max_contact_force_n,
|
|
14
|
+
# # tip_margin_deg over the SCM deformable terrain.
|
|
15
|
+
|
|
16
|
+
system_type: SMC # SCM deformable terrain requires the smooth/penalty method
|
|
17
|
+
step_size: 0.001
|
|
18
|
+
steps_per_command: 200
|
|
19
|
+
terrain_fidelity: deformable
|
|
20
|
+
scene: terramechanics
|
|
21
|
+
|
|
22
|
+
terramechanics:
|
|
23
|
+
terrain_length_m: 4.0
|
|
24
|
+
terrain_width_m: 2.0
|
|
25
|
+
mesh_resolution_m: 0.04
|
|
26
|
+
rig_mass_kg: 250.0
|
|
27
|
+
tip_threshold_deg: 35.0 # roll/pitch past which the rig is unstable
|
|
28
|
+
drawbar_gain_n: 1500.0 # forward force per unit throttle (driver[0])
|
|
29
|
+
# SCM soil parameters (Bekker-Wong pressure-sinkage + Janosi-Hanamoto shear);
|
|
30
|
+
# defaults approximate a soft sandy loam.
|
|
31
|
+
bekker_kphi: 200000.0
|
|
32
|
+
bekker_kc: 0.0
|
|
33
|
+
bekker_n: 1.1
|
|
34
|
+
mohr_cohesion_pa: 0.0
|
|
35
|
+
mohr_friction_deg: 30.0
|
|
36
|
+
janosi_shear_m: 0.01
|
|
37
|
+
|
|
38
|
+
location_to_segment:
|
|
39
|
+
ridge_waypoint:
|
|
40
|
+
driver: [0.8] # throttle; drives the rig forward across the patch
|
|
41
|
+
steps: 300
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "urml-chrono-runtime"
|
|
7
|
+
version = "0.5.0"
|
|
8
|
+
description = "High-fidelity validation runtime for URML — Project Chrono multibody physics, zero ROS."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "BUSL-1.1" }
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
authors = [{ name = "URML Maintainers" }]
|
|
13
|
+
keywords = ["robotics", "simulation", "chrono", "pychrono", "terramechanics", "urml", "runtime"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"License :: Other/Proprietary License",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Topic :: Scientific/Engineering",
|
|
23
|
+
]
|
|
24
|
+
dependencies = [
|
|
25
|
+
"pydantic>=2.6,<3",
|
|
26
|
+
"PyYAML>=6.0,<7",
|
|
27
|
+
"urml-validator>=0.5.0",
|
|
28
|
+
"urml-ros2-runtime>=0.5.0",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[project.optional-dependencies]
|
|
32
|
+
# PyChrono ships via conda-forge (conda install -c conda-forge pychrono),
|
|
33
|
+
# not as an official PyPI wheel, so this extra is intentionally empty: it
|
|
34
|
+
# documents the dependency boundary without pinning a package pip cannot
|
|
35
|
+
# resolve. pychrono is imported lazily, so this module loads on every host
|
|
36
|
+
# (Windows included) without it; ChronoAdapter raises a clear, actionable
|
|
37
|
+
# error pointing at conda-forge on first use when pychrono is absent. The
|
|
38
|
+
# gated chrono-integration.yml installs pychrono from conda-forge.
|
|
39
|
+
chrono = []
|
|
40
|
+
dev = [
|
|
41
|
+
"pytest>=8",
|
|
42
|
+
"pytest-cov>=5",
|
|
43
|
+
"ruff>=0.5",
|
|
44
|
+
"mypy>=1.10",
|
|
45
|
+
]
|
|
46
|
+
|
|
47
|
+
[project.urls]
|
|
48
|
+
Homepage = "https://github.com/urml-dev/URML"
|
|
49
|
+
Repository = "https://github.com/urml-dev/URML"
|
|
50
|
+
Issues = "https://github.com/urml-dev/URML/issues"
|
|
51
|
+
|
|
52
|
+
[tool.hatch.build.targets.wheel]
|
|
53
|
+
packages = ["src/urml_chrono_runtime"]
|
|
54
|
+
|
|
55
|
+
[tool.ruff]
|
|
56
|
+
line-length = 120
|
|
57
|
+
target-version = "py311"
|
|
58
|
+
src = ["src", "tests"]
|
|
59
|
+
|
|
60
|
+
[tool.ruff.lint]
|
|
61
|
+
select = ["E", "F", "W", "I", "B", "UP", "N", "ANN", "RUF"]
|
|
62
|
+
ignore = ["ANN401"]
|
|
63
|
+
|
|
64
|
+
[tool.ruff.lint.per-file-ignores]
|
|
65
|
+
"tests/*" = ["ANN"]
|
|
66
|
+
|
|
67
|
+
[tool.mypy]
|
|
68
|
+
strict = true
|
|
69
|
+
python_version = "3.11"
|
|
70
|
+
plugins = ["pydantic.mypy"]
|
|
71
|
+
mypy_path = "src"
|
|
72
|
+
packages = ["urml_chrono_runtime"]
|
|
73
|
+
|
|
74
|
+
[tool.pytest.ini_options]
|
|
75
|
+
minversion = "8.0"
|
|
76
|
+
testpaths = ["tests"]
|
|
77
|
+
addopts = ["-q", "--strict-markers"]
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""urml_chrono_runtime — high-fidelity validation runtime for URML.
|
|
2
|
+
|
|
3
|
+
ChronoAdapter (+ ChronoConfig, load_chrono_config)
|
|
4
|
+
Project Chrono multibody / multi-physics via PyChrono. **No ROS 2
|
|
5
|
+
dependency.** Chrono is the high-fidelity *validation* target: a
|
|
6
|
+
URML program is checked statically against the capability manifest
|
|
7
|
+
and safety envelope first, then the same validated intent is driven
|
|
8
|
+
through a short Chrono simulation segment and the dynamics (system
|
|
9
|
+
time, contacts, the commanded driver inputs) come back as evidence.
|
|
10
|
+
``pychrono`` is imported lazily (it ships via conda-forge), so this
|
|
11
|
+
module loads on every host without it.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
from urml_chrono_runtime._version import __version__
|
|
17
|
+
from urml_chrono_runtime.adapter import ChronoAdapter, ChronoConfig, load_chrono_config
|
|
18
|
+
from urml_chrono_runtime.terramechanics import TerramechanicsParams, TerramechanicsScene
|
|
19
|
+
|
|
20
|
+
__all__ = [
|
|
21
|
+
"ChronoAdapter",
|
|
22
|
+
"ChronoConfig",
|
|
23
|
+
"TerramechanicsParams",
|
|
24
|
+
"TerramechanicsScene",
|
|
25
|
+
"__version__",
|
|
26
|
+
"load_chrono_config",
|
|
27
|
+
]
|