simulo-interfaces 0.26.0__tar.gz → 0.27.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.
Files changed (72) hide show
  1. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/PKG-INFO +1 -1
  2. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/pyproject.toml +1 -1
  3. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/__init__.py +2 -0
  4. simulo_interfaces-0.27.0/src/simulo/interfaces/authoring/named_actuators.py +29 -0
  5. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/physics.py +60 -4
  6. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/policy_inputs.py +63 -23
  7. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/prop.py +0 -4
  8. simulo_interfaces-0.27.0/src/simulo/interfaces/authoring/variants.py +65 -0
  9. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/__init__.py +8 -0
  10. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/asset_catalog.py +7 -0
  11. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/evaluation.py +37 -3
  12. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/manifest.py +8 -4
  13. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/onnx_bundle.py +4 -0
  14. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/preview.py +15 -1
  15. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/submit.py +4 -4
  16. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/runtime/task.py +4 -0
  17. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo_interfaces.egg-info/PKG-INFO +1 -1
  18. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo_interfaces.egg-info/SOURCES.txt +1 -0
  19. simulo_interfaces-0.26.0/src/simulo/interfaces/authoring/variants.py +0 -48
  20. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/MANIFEST.in +0 -0
  21. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/PYPI.md +0 -0
  22. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/setup.cfg +0 -0
  23. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/__init__.py +0 -0
  24. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/action_channel.py +0 -0
  25. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/actuator.py +0 -0
  26. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/asset.py +0 -0
  27. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/checkpoint.py +0 -0
  28. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/entity.py +0 -0
  29. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/light.py +0 -0
  30. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/materials.py +0 -0
  31. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/pose.py +0 -0
  32. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/primitives.py +0 -0
  33. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/properties.py +0 -0
  34. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/record.py +0 -0
  35. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/robot.py +0 -0
  36. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/robot_config.py +0 -0
  37. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/scene.py +0 -0
  38. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/sensor.py +0 -0
  39. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/terrain.py +0 -0
  40. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/visual.py +0 -0
  41. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/authoring/world.py +0 -0
  42. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/exceptions.py +0 -0
  43. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/ids.py +0 -0
  44. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/_payload.py +0 -0
  45. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/app.py +0 -0
  46. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/asset.py +0 -0
  47. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/callbacks.py +0 -0
  48. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/debug.py +0 -0
  49. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/domain.py +0 -0
  50. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/enums.py +0 -0
  51. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/job_events.py +0 -0
  52. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/outputs.py +0 -0
  53. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/policy_checkpoint.py +0 -0
  54. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/runs.py +0 -0
  55. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/runtime.py +0 -0
  56. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/runtimes.py +0 -0
  57. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/system_tiers.py +0 -0
  58. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/systems.py +0 -0
  59. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/platform/volume.py +0 -0
  60. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/py.typed +0 -0
  61. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/runtime/__init__.py +0 -0
  62. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/runtime/anomaly.py +0 -0
  63. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/runtime/components.py +0 -0
  64. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/runtime/env.py +0 -0
  65. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/runtime/player.py +0 -0
  66. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/runtime/policy.py +0 -0
  67. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/runtime/policy_frames.py +0 -0
  68. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/runtime/tensors.py +0 -0
  69. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo/interfaces/runtime/trainer.py +0 -0
  70. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo_interfaces.egg-info/dependency_links.txt +0 -0
  71. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo_interfaces.egg-info/requires.txt +0 -0
  72. {simulo_interfaces-0.26.0 → simulo_interfaces-0.27.0}/src/simulo_interfaces.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: simulo-interfaces
3
- Version: 0.26.0
3
+ Version: 0.27.0
4
4
  Summary: Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime.
5
5
  Author-email: Simulo Team <team@simulo.ai>
6
6
  License: BSD-3-Clause
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "simulo-interfaces"
7
- version = "0.26.0"
7
+ version = "0.27.0"
8
8
  description = "Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime."
9
9
  readme = "PYPI.md"
10
10
  requires-python = ">=3.11"
@@ -96,6 +96,7 @@ from simulo.interfaces.authoring.light import (
96
96
  LightConfig,
97
97
  )
98
98
  from simulo.interfaces.authoring.materials import Material, SurfaceMaterial
99
+ from simulo.interfaces.authoring.named_actuators import NamedActuatorControlsProtocol
99
100
  from simulo.interfaces.authoring.physics import (
100
101
  Collision,
101
102
  DeformableMaterial,
@@ -214,6 +215,7 @@ __all__ = [
214
215
  # the backend package and explicitly inherit these Protocols)
215
216
  "ExternalForceProtocol",
216
217
  "RobotPropertiesProtocol",
218
+ "NamedActuatorControlsProtocol",
217
219
  "PropPropertiesProtocol",
218
220
  "RobotProtocol",
219
221
  "RobotStateProtocol",
@@ -0,0 +1,29 @@
1
+ """Optional named-actuator commands, independent of the legacy robot contract."""
2
+
3
+ from typing import List, Optional, Protocol, Sequence, runtime_checkable
4
+
5
+ from simulo.interfaces.runtime.tensors import TensorLike
6
+
7
+
8
+ @runtime_checkable
9
+ class NamedActuatorControlsProtocol(Protocol):
10
+ """Control file-authored tendon and site actuators in their own units."""
11
+
12
+ def get_named_actuator_names(self) -> List[str]:
13
+ """Return item-local tendon and site actuator names after scene build."""
14
+ ...
15
+
16
+ def set_actuator_controls(
17
+ self,
18
+ values: TensorLike,
19
+ actuator_names: Optional[Sequence[str]] = None,
20
+ env_ids: Optional[TensorLike] = None,
21
+ ) -> None:
22
+ """Set persistent controls (K, A), or broadcast (A,), in file units.
23
+
24
+ None selects all names or copies. Unselected controls persist.
25
+ Authored bounds and action delay apply. Reset clears controls and
26
+ snapshots restore them. Raises RuntimeError before attach; call from
27
+ on_start onward. This capability requires the engine backend.
28
+ """
29
+ ...
@@ -6,6 +6,7 @@ definitions shared by the torch-free thin client (authoring at submit) and the
6
6
  backend runtime (execution on the worker).
7
7
  """
8
8
 
9
+ import math
9
10
  from dataclasses import dataclass
10
11
  from typing import Optional
11
12
 
@@ -61,16 +62,58 @@ class RigidPhysics:
61
62
  """Rigid body physics properties.
62
63
 
63
64
  Attributes:
64
- mass: Mass in kg
65
+ mass: Mass in kg. Defaults to 1.0. Set to ``None`` when using density.
66
+ Mutually exclusive with density.
67
+ density: Density in kg/m^3. Mutually exclusive with mass. For file
68
+ assets, derives mass and inertia from imported collision geometry.
69
+ friction: Optional Coulomb friction coefficient. ``None`` preserves
70
+ the shape's authored material.
71
+ restitution: Optional contact restitution coefficient. ``None``
72
+ preserves the shape's authored material.
65
73
  collision: Collision properties
66
74
  kinematic: If True, body is fixed in place (doesn't respond to forces)
67
75
  activate_contact_sensors: If True, enables contact reporting for sensors
68
76
  """
69
77
 
70
- mass: float = 1.0
78
+ mass: float | None = 1.0
71
79
  collision: Optional[Collision] = None
72
80
  kinematic: bool = False
73
81
  activate_contact_sensors: bool = False
82
+ density: float | None = None
83
+ friction: float | None = None
84
+ restitution: float | None = None
85
+
86
+ def __post_init__(self) -> None:
87
+ if self.mass is not None and self.density is not None:
88
+ raise ValueError("RigidPhysics.mass and RigidPhysics.density are mutually exclusive")
89
+ if self.mass is not None and (
90
+ isinstance(self.mass, bool)
91
+ or not isinstance(self.mass, (int, float))
92
+ or not math.isfinite(self.mass)
93
+ or self.mass <= 0
94
+ ):
95
+ raise ValueError("RigidPhysics.mass must be a finite positive number")
96
+ if self.density is not None and (
97
+ isinstance(self.density, bool)
98
+ or not isinstance(self.density, (int, float))
99
+ or not math.isfinite(self.density)
100
+ or self.density <= 0
101
+ ):
102
+ raise ValueError("RigidPhysics.density must be a finite positive number")
103
+ if self.friction is not None and (
104
+ isinstance(self.friction, bool)
105
+ or not isinstance(self.friction, (int, float))
106
+ or not math.isfinite(self.friction)
107
+ or self.friction < 0
108
+ ):
109
+ raise ValueError("RigidPhysics.friction must be a finite non-negative number")
110
+ if self.restitution is not None and (
111
+ isinstance(self.restitution, bool)
112
+ or not isinstance(self.restitution, (int, float))
113
+ or not math.isfinite(self.restitution)
114
+ or not 0 <= self.restitution <= 1
115
+ ):
116
+ raise ValueError("RigidPhysics.restitution must be a finite number in [0, 1]")
74
117
 
75
118
 
76
119
  @dataclass
@@ -107,15 +150,25 @@ class Physics:
107
150
 
108
151
  @staticmethod
109
152
  def rigid(
110
- mass: float = 1.0,
153
+ mass: float | None = 1.0,
111
154
  collision: Optional[Collision] = None,
112
155
  kinematic: bool = False,
113
156
  activate_contact_sensors: bool = False,
157
+ density: float | None = None,
158
+ friction: float | None = None,
159
+ restitution: float | None = None,
114
160
  ) -> RigidPhysics:
115
161
  """Create rigid body physics.
116
162
 
117
163
  Args:
118
- mass: Mass in kg
164
+ mass: Mass in kg. Defaults to 1.0. Set to ``None`` when using
165
+ density. Mutually exclusive with density.
166
+ density: Density in kg/m^3. Mutually exclusive with mass. For file
167
+ assets, derives mass and inertia from imported collision geometry.
168
+ friction: Optional Coulomb friction coefficient. ``None`` keeps
169
+ the shape's authored material.
170
+ restitution: Optional contact restitution coefficient. ``None``
171
+ keeps the shape's authored material.
119
172
  collision: Collision properties
120
173
  kinematic: If True, body is fixed in place (doesn't respond to forces).
121
174
  Useful for static obstacles, walls, etc.
@@ -127,6 +180,9 @@ class Physics:
127
180
  """
128
181
  return RigidPhysics(
129
182
  mass=mass,
183
+ density=density,
184
+ friction=friction,
185
+ restitution=restitution,
130
186
  collision=collision,
131
187
  kinematic=kinematic,
132
188
  activate_contact_sensors=activate_contact_sensors,
@@ -27,7 +27,9 @@ class PolicyInput:
27
27
  inputs require uint8, shape ``(H, W, 3)`` and a nonblank camera scene name:
28
28
  the last segment of ``scene.add(camera, at="/World/<name>")``. Full paths
29
29
  are rejected. LearningEnv setup requires that camera's purpose to be
30
- ``"policy"``. Two policy cameras cannot share a scene name.
30
+ ``"policy"``. Two policy cameras cannot share a scene name. Numeric
31
+ inputs may optionally name every flattened value with ``element_labels``;
32
+ those labels do not affect the tensor layout.
31
33
  """
32
34
 
33
35
  name: str
@@ -36,11 +38,14 @@ class PolicyInput:
36
38
  kind: Literal["numeric", "image"] = "numeric"
37
39
  camera: str | None = None
38
40
  preprocessing: Literal["none", "center"] = "none"
41
+ element_labels: tuple[str, ...] = ()
39
42
 
40
43
  def __post_init__(self) -> None:
41
44
  label = f"Input {self.name!r}"
42
45
  if isinstance(self.shape, list):
43
46
  object.__setattr__(self, "shape", tuple(self.shape))
47
+ if isinstance(self.element_labels, list):
48
+ object.__setattr__(self, "element_labels", tuple(self.element_labels))
44
49
  if not isinstance(self.name, str) or not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", self.name):
45
50
  raise ValueError(f"{label}: name must start with a letter and contain only letters, digits or underscores.")
46
51
  if (
@@ -54,33 +59,70 @@ class PolicyInput:
54
59
  if self.preprocessing not in ("none", "center"):
55
60
  raise ValueError(f"{label}: preprocessing must be 'none' or 'center'.")
56
61
  if self.kind == "image":
57
- if self.dtype != "uint8":
58
- raise ValueError(f"{label}: image dtype must be uint8 RGB NHWC, got {self.dtype!r}.")
59
- if len(self.shape) != 3 or self.shape[-1] != 3:
60
- raise ValueError(f"{label}: image shape must be (H, W, 3) RGB NHWC, excluding batch, got {self.shape}.")
61
- if not isinstance(self.camera, str) or not self.camera.strip():
62
- raise ValueError(f"{label}: image inputs require a camera identity.")
63
- if "/" in self.camera or self.camera != self.camera.strip():
64
- raise ValueError(f"{label}: camera must be a scene name, the last segment of scene.add(..., at=...).")
62
+ _validate_image_input(self, label)
65
63
  elif self.dtype != "float32" or self.camera is not None or self.preprocessing != "none":
66
64
  raise ValueError(f"{label}: numeric inputs require float32, no camera, and preprocessing='none'.")
65
+ _validate_element_labels(self, label)
67
66
 
68
67
  def to_dict(self) -> dict[str, Any]:
69
- """Return JSON metadata, converting the stored tuple shape to a list."""
70
- return {**asdict(self), "shape": list(self.shape)}
68
+ """Return JSON metadata, converting stored tuples to lists."""
69
+ metadata = {**asdict(self), "shape": list(self.shape)}
70
+ if self.element_labels:
71
+ metadata["element_labels"] = list(self.element_labels)
72
+ else:
73
+ del metadata["element_labels"]
74
+ return metadata
71
75
 
72
76
  @classmethod
73
77
  def from_dict(cls, value: Mapping[str, Any]) -> PolicyInput:
74
78
  """Parse JSON, converting list shapes to tuples; reject unknown fields."""
75
79
  if not isinstance(value, Mapping):
76
80
  raise ValueError("Input declaration must be an object.")
77
- allowed = {"name", "shape", "dtype", "kind", "camera", "preprocessing"}
81
+ allowed = {"name", "shape", "dtype", "kind", "camera", "preprocessing", "element_labels"}
78
82
  if set(value) - allowed or not {"name", "shape"} <= set(value):
79
83
  raise ValueError(f"Input {value.get('name')!r}: declaration has missing or unknown fields.")
80
84
  shape = value["shape"]
81
85
  if not isinstance(shape, (list, tuple)):
82
86
  raise ValueError(f"Input {value['name']!r}: shape must be an array of positive dimensions.")
83
- return cls(**{**value, "shape": tuple(shape)})
87
+ element_labels = value.get("element_labels", ())
88
+ if not isinstance(element_labels, (list, tuple)):
89
+ raise ValueError(f"Input {value['name']!r}: element labels must be an array of strings.")
90
+ return cls(**{**value, "shape": tuple(shape), "element_labels": tuple(element_labels)})
91
+
92
+
93
+ def _validate_image_input(spec: PolicyInput, label: str) -> None:
94
+ if spec.dtype != "uint8":
95
+ raise ValueError(f"{label}: image dtype must be uint8 RGB NHWC, got {spec.dtype!r}.")
96
+ if len(spec.shape) != 3 or spec.shape[-1] != 3:
97
+ raise ValueError(f"{label}: image shape must be (H, W, 3) RGB NHWC, excluding batch, got {spec.shape}.")
98
+ if not isinstance(spec.camera, str) or not spec.camera.strip():
99
+ raise ValueError(f"{label}: image inputs require a camera identity.")
100
+ if "/" in spec.camera or spec.camera != spec.camera.strip():
101
+ raise ValueError(f"{label}: camera must be a scene name, the last segment of scene.add(..., at=...).")
102
+ if spec.element_labels:
103
+ raise ValueError(f"{label}: image inputs cannot name individual elements.")
104
+
105
+
106
+ def _validate_element_labels(spec: PolicyInput, label: str) -> None:
107
+ if not isinstance(spec.element_labels, tuple) or any(
108
+ not isinstance(element_label, str) or not element_label.strip() for element_label in spec.element_labels
109
+ ):
110
+ raise ValueError(f"{label}: element labels must be nonblank strings.")
111
+ if spec.element_labels and len(spec.element_labels) != _value_count(spec.shape):
112
+ raise ValueError(f"{label}: element labels must name each of {_value_count(spec.shape)} values.")
113
+
114
+
115
+ def _layout_metadata(spec: PolicyInput) -> dict[str, Any]:
116
+ """Return the fields that determine a policy tensor's layout."""
117
+ return {name: getattr(spec, name) for name in ("name", "shape", "dtype", "kind", "camera", "preprocessing")}
118
+
119
+
120
+ def _value_count(shape: tuple[int, ...]) -> int:
121
+ """Return the flattened element count without a tensor dependency."""
122
+ count = 1
123
+ for dimension in shape:
124
+ count *= dimension
125
+ return count
84
126
 
85
127
 
86
128
  @dataclass(frozen=True, slots=True, kw_only=True)
@@ -89,9 +131,10 @@ class PolicyInputSchema:
89
131
 
90
132
  ``critic=None`` means the critic uses exactly the actor declarations.
91
133
  Future export and playback consumers must use only ``actor``. A critic
92
- declaration sharing an actor name must be identical. Actor inputs omitted
93
- from an explicit critic are not supplied to that critic. Order is part of
94
- checkpoint compatibility, including numeric concatenation order.
134
+ declaration sharing an actor name must have the same tensor layout. Actor
135
+ inputs omitted from an explicit critic are not supplied to that critic.
136
+ Order is part of checkpoint compatibility, including numeric concatenation
137
+ order. Element labels are display metadata, so they may differ by role.
95
138
  """
96
139
 
97
140
  actor: tuple[PolicyInput, ...]
@@ -110,7 +153,7 @@ class PolicyInputSchema:
110
153
  seen.add(spec.name)
111
154
  actor = {spec.name: spec for spec in self.actor}
112
155
  for spec in self.critic_inputs:
113
- if spec.name in actor and spec != actor[spec.name]:
156
+ if spec.name in actor and _layout_metadata(spec) != _layout_metadata(actor[spec.name]):
114
157
  raise ValueError(
115
158
  f"critic input {spec.name!r}: declaration contradicts the actor input of the same name."
116
159
  )
@@ -148,14 +191,11 @@ class PolicyInputSchema:
148
191
  Batch size is absent, so a checkpoint can change parallelism.
149
192
  """
150
193
 
151
- def canonical(spec: PolicyInput) -> dict[str, Any]:
152
- # Pin v1's subset: future defaulted fields do not invalidate hashes.
153
- return {name: getattr(spec, name) for name in ("name", "shape", "dtype", "kind", "camera", "preprocessing")}
154
-
155
194
  metadata = {
156
195
  "version": "simulo.policy-input-fingerprint.v1",
157
- "actor": [canonical(spec) for spec in self.actor],
158
- "critic": [canonical(spec) for spec in self.critic_inputs],
196
+ # Pin v1's subset: future defaulted fields do not invalidate hashes.
197
+ "actor": [_layout_metadata(spec) for spec in self.actor],
198
+ "critic": [_layout_metadata(spec) for spec in self.critic_inputs],
159
199
  }
160
200
  return hashlib.sha256(json.dumps(metadata, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
161
201
 
@@ -228,7 +228,3 @@ class VariantPropProtocol(PropProtocol, Protocol):
228
228
  def variant_index(self) -> TensorLike:
229
229
  """Active option index for every environment copy, shape ``(num_envs,)``."""
230
230
  ...
231
-
232
- def set_variant(self, index: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
233
- """Switch selected copies to an option index. Supported for pool variants."""
234
- ...
@@ -0,0 +1,65 @@
1
+ """Dependency-free authoring data for opt-in per-copy scene variants."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+ from numbers import Integral
7
+ from typing import Literal, Sequence, cast
8
+
9
+ from simulo.interfaces.authoring.asset import AssetSource
10
+ from simulo.interfaces.authoring.primitives import PrimitiveShape
11
+
12
+
13
+ @dataclass(frozen=True, init=False)
14
+ class ObjectVariants:
15
+ """The objects one authored prop can represent across environment copies.
16
+
17
+ ``assign="blocks"`` assigns each option to contiguous copies. ``"cycle"``
18
+ repeats options in order. A sequence selects the option for each copy; the
19
+ engine validates that its length matches the scene's environment count.
20
+ """
21
+
22
+ options: Sequence[PrimitiveShape | AssetSource]
23
+ assign: Literal["blocks", "cycle"] | Sequence[int] = "blocks"
24
+
25
+ def __init__(
26
+ self,
27
+ options: Sequence[PrimitiveShape | AssetSource],
28
+ assign: Literal["blocks", "cycle"] | Sequence[int] = "blocks",
29
+ **kwargs: object,
30
+ ) -> None:
31
+ if "mode" in kwargs:
32
+ raise TypeError(
33
+ "ObjectVariants.mode was removed. Use assign=... and rebuild the scene to change variant assignments."
34
+ )
35
+ if kwargs:
36
+ unexpected = next(iter(kwargs))
37
+ raise TypeError(f"ObjectVariants.__init__() got an unexpected keyword argument {unexpected!r}")
38
+ object.__setattr__(self, "options", options)
39
+ object.__setattr__(self, "assign", assign)
40
+ self.__post_init__()
41
+
42
+ def __post_init__(self) -> None:
43
+ options = tuple(self.options)
44
+ if len(options) < 2:
45
+ raise ValueError("ObjectVariants.options must contain at least 2 options")
46
+ if not all(isinstance(option, (PrimitiveShape, AssetSource)) for option in options):
47
+ raise TypeError("ObjectVariants.options must contain PrimitiveShape or AssetSource values")
48
+ assign = self.assign
49
+ if isinstance(assign, str):
50
+ if assign not in {"blocks", "cycle"}:
51
+ raise ValueError("ObjectVariants.assign must be 'blocks', 'cycle', or a sequence of option indices")
52
+ else:
53
+ if not isinstance(assign, Sequence):
54
+ raise TypeError("ObjectVariants.assign must be 'blocks', 'cycle', or a sequence of option indices")
55
+ indices = tuple(cast(Sequence[object], assign))
56
+ if any(isinstance(index, bool) or not isinstance(index, Integral) for index in indices):
57
+ raise TypeError("ObjectVariants.assign indices must be integers")
58
+ assign = tuple(int(cast(Integral, index)) for index in indices)
59
+ if any(index < 0 or index >= len(options) for index in assign):
60
+ raise ValueError("ObjectVariants.assign indices must select an option")
61
+ object.__setattr__(self, "options", options)
62
+ object.__setattr__(self, "assign", assign)
63
+
64
+
65
+ __all__ = ["ObjectVariants"]
@@ -19,6 +19,7 @@ from simulo.interfaces.platform.asset_catalog import (
19
19
  ASSET_MISSING_CODE,
20
20
  ASSET_NOT_EXPORTABLE_CODE,
21
21
  ASSET_NOT_FOUND_CODE,
22
+ ASSET_NOT_IN_CATALOG_CODE,
22
23
  ASSET_ORIGIN_TYPES,
23
24
  ASSET_PUBLISH_ROLES,
24
25
  ASSET_RECONVERT_ROUTE_TEMPLATE,
@@ -98,6 +99,7 @@ from simulo.interfaces.platform.evaluation import (
98
99
  EPISODES_CSV_COLUMNS_BEFORE_CHECKS,
99
100
  EPISODES_CSV_FIRST_FAILURE_AT_S_PREFIX,
100
101
  EPISODES_CSV_FIRST_FAILURE_STEP_PREFIX,
102
+ EPISODES_CSV_REPLAY_COLUMNS,
101
103
  EVALUATION_ACTIONS,
102
104
  EVALUATION_REPORT_SCHEMA_VERSION,
103
105
  MAX_CHECK_NAME_CHARS,
@@ -111,6 +113,7 @@ from simulo.interfaces.platform.evaluation import (
111
113
  MAX_NEXT_LINES,
112
114
  MAX_RECORDED_EPISODES,
113
115
  MAX_RECORDING_PROBLEM_CHARS,
116
+ MAX_REPLAYED_FAILURES,
114
117
  CheckCount,
115
118
  ComparisonVerdict,
116
119
  EndingCount,
@@ -127,6 +130,7 @@ from simulo.interfaces.platform.evaluation import (
127
130
  ListedEpisode,
128
131
  NextLine,
129
132
  NextRule,
133
+ Recording3D,
130
134
  ReplayFrame,
131
135
  ReplayPose,
132
136
  ReplayTrace,
@@ -579,6 +583,7 @@ __all__ = [
579
583
  "ASSET_DIGEST_MISMATCH_CODE",
580
584
  "ASSET_CORRUPT_CODE",
581
585
  "ASSET_NOT_FOUND_CODE",
586
+ "ASSET_NOT_IN_CATALOG_CODE",
582
587
  # asset catalog — wire dataclasses
583
588
  "FileManifestEntry",
584
589
  "AssetRecord",
@@ -689,6 +694,7 @@ __all__ = [
689
694
  "MAX_CHECK_NAME_CHARS",
690
695
  "MAX_FAILURE_GROUPS",
691
696
  "MAX_RECORDED_EPISODES",
697
+ "MAX_REPLAYED_FAILURES",
692
698
  "MAX_RECORDING_PROBLEM_CHARS",
693
699
  "MAX_LISTED_EPISODES",
694
700
  "MAX_LISTED_SIMULATION_PROBLEMS",
@@ -699,6 +705,7 @@ __all__ = [
699
705
  "EvaluationActions",
700
706
  "ComparisonVerdict",
701
707
  "NextRule",
708
+ "Recording3D",
702
709
  "SimulationProblem",
703
710
  "EvaluationCheckpoint",
704
711
  "EvaluationTask",
@@ -720,6 +727,7 @@ __all__ = [
720
727
  "EPISODES_CSV_COLUMNS_BEFORE_CHECKS",
721
728
  "EPISODES_CSV_CHECK_PREFIX",
722
729
  "EPISODES_CSV_COLUMNS_AFTER_CHECKS",
730
+ "EPISODES_CSV_REPLAY_COLUMNS",
723
731
  "EPISODES_CSV_FIRST_FAILURE_STEP_PREFIX",
724
732
  "EPISODES_CSV_FIRST_FAILURE_AT_S_PREFIX",
725
733
  "episodes_csv_columns",
@@ -673,6 +673,13 @@ ASSET_DIGEST_MISMATCH_CODE = "asset_digest_mismatch"
673
673
  #: from both :data:`ASSET_MISSING_CODE` (bytes never arrived) and
674
674
  #: :data:`ASSET_DIGEST_MISMATCH_CODE` (bytes don't match what was promised).
675
675
  ASSET_CORRUPT_CODE = "asset_corrupt"
676
+ #: Error code the worker uses to **fail a job in place** when a claimed
677
+ #: Simulo Engine catalog asset names a version the catalog does not hold, or a
678
+ #: version for another asset kind. The claim is checked against the catalog
679
+ #: index with no download, so the answer cannot change on a retry. A download or
680
+ #: cache fault keeps :data:`ASSET_MISSING_CODE` or :data:`ASSET_DIGEST_MISMATCH_CODE`;
681
+ #: the control plane retries those and fails a validation only on this code.
682
+ ASSET_NOT_IN_CATALOG_CODE = "asset_not_in_catalog"
676
683
  #: The uniform per-ref miss code the batch resolver (:data:`ASSETS_RESOLVE_ROUTE`)
677
684
  #: and the job-submit pin re-verify both answer for a ref that does not resolve —
678
685
  #: unknown, cross-org, deleted, or malformed, **all reported identically**
@@ -67,6 +67,9 @@ MAX_FAILURE_GROUPS: Final = 3
67
67
  MAX_RECORDED_EPISODES: Final = 10
68
68
  """Episodes an evaluation records."""
69
69
 
70
+ MAX_REPLAYED_FAILURES: Final = 20
71
+ """Failed episodes an evaluation replays into its 3D recording. The rest are listed as not recorded."""
72
+
70
73
  MAX_LISTED_EPISODES: Final = 13
71
74
  """Episodes WENT WRONG lists: the recorded ones, then up to three more."""
72
75
 
@@ -334,6 +337,10 @@ class ListedEpisode(TypedDict):
334
337
  recording: str | None
335
338
  """The recording name for ``simulo recordings JOB <name>``, such as ``episode-64``;
336
339
  ``None`` when the episode was not recorded."""
340
+ copy_index: NotRequired[int | None]
341
+ """The environment copy that ran the episode. The 3D recording names the episode by
342
+ ``episode`` and shows it on this copy. Omitted by reports written before this additive
343
+ v1 field existed."""
337
344
 
338
345
 
339
346
  class SimulationProblemEpisode(TypedDict):
@@ -344,6 +351,20 @@ class SimulationProblemEpisode(TypedDict):
344
351
  at_s: float
345
352
 
346
353
 
354
+ class Recording3D(TypedDict):
355
+ """Which failed episodes the evaluation's 3D recording holds."""
356
+
357
+ episodes: list[int]
358
+ """Failed episodes replayed into the recording, ascending; at most :data:`MAX_REPLAYED_FAILURES`."""
359
+ not_recorded: int
360
+ """Failed episodes over that limit, or all of them when the replay was dropped."""
361
+ not_exact: NotRequired[list[int]]
362
+ """Failed episodes whose replay differed from their first run, ascending. They are never
363
+ recorded and are counted in ``not_recorded``."""
364
+ problem: NotRequired[str]
365
+ """Why no failed episode was recorded, when none was."""
366
+
367
+
347
368
  class NextLine(TypedDict):
348
369
  """One NEXT line: what to do, and the command that does it."""
349
370
 
@@ -386,6 +407,9 @@ class EvaluationReport(TypedDict):
386
407
  simulation problem, in episode order."""
387
408
  next: list[NextLine]
388
409
  """At most :data:`MAX_NEXT_LINES`."""
410
+ recording_3d: NotRequired[Recording3D | None]
411
+ """Set only when episodes failed: which of them the 3D recording holds. Omitted by
412
+ reports written before this additive v1 field existed."""
389
413
  recording_problem: NotRequired[str]
390
414
  """Why requested filming did not complete, at most
391
415
  :data:`MAX_RECORDING_PROBLEM_CHARS` characters. Omitted when filming succeeds
@@ -448,7 +472,11 @@ class ReplayTrace(TypedDict):
448
472
  # One row per episode. Booleans are ``true``/``false``. ``sim_problem`` holds a
449
473
  # ``SimulationProblem`` value and ``recording`` a recording name, each empty when
450
474
  # there is none. ``first_observation`` is the policy's observation on the
451
- # episode's first step, as a JSON list.
475
+ # episode's first step, as a JSON list. A runtime that replays failed episodes into a 3D recording
476
+ # adds two columns after ``recording`` (``episodes_csv_columns(..., include_replay=True)``):
477
+ # ``copy_index`` is the environment copy that ran the episode and ``recorded_3d`` is ``true`` when
478
+ # the 3D recording holds the episode and ``not_exact`` when its replay differed from its first run,
479
+ # so it is not recorded. A runtime that does not replay writes neither column.
452
480
 
453
481
  EPISODES_CSV_COLUMNS_BEFORE_CHECKS: Final = (
454
482
  "episode",
@@ -464,10 +492,15 @@ EPISODES_CSV_CHECK_PREFIX: Final = "check:"
464
492
  EPISODES_CSV_FIRST_FAILURE_STEP_PREFIX: Final = "first_failure_step:"
465
493
  EPISODES_CSV_FIRST_FAILURE_AT_S_PREFIX: Final = "first_failure_at_s:"
466
494
  EPISODES_CSV_COLUMNS_AFTER_CHECKS: Final = ("first_observation", "recording")
495
+ EPISODES_CSV_REPLAY_COLUMNS: Final = ("copy_index", "recorded_3d")
496
+
467
497
 
498
+ def episodes_csv_columns(
499
+ check_names: Sequence[str], *, include_first_failures: bool = False, include_replay: bool = False
500
+ ) -> tuple[str, ...]:
501
+ """The ``episodes.csv`` header for a rule with these checks, in rule order.
468
502
 
469
- def episodes_csv_columns(check_names: Sequence[str], *, include_first_failures: bool = False) -> tuple[str, ...]:
470
- """The ``episodes.csv`` header for a rule with these checks, in rule order."""
503
+ ``include_replay`` adds the two columns a runtime that replays failed episodes writes at the end."""
471
504
 
472
505
  return (
473
506
  *EPISODES_CSV_COLUMNS_BEFORE_CHECKS,
@@ -478,4 +511,5 @@ def episodes_csv_columns(check_names: Sequence[str], *, include_first_failures:
478
511
  for column in ([prefix + name for name in check_names] if include_first_failures else [])
479
512
  ),
480
513
  *EPISODES_CSV_COLUMNS_AFTER_CHECKS,
514
+ *(EPISODES_CSV_REPLAY_COLUMNS if include_replay else ()),
481
515
  )
@@ -97,9 +97,11 @@ class Manifest:
97
97
  reproducibility / source caching.
98
98
  * ``package_id`` — the *submission* identity: a ``sha256`` over
99
99
  ``source_digest + entrypoint.file + job_name + canonical_json(args) + canonical_json(resources)``,
100
- where ``resources`` is the canonical asset list.
100
+ where ``resources`` is the canonical asset list. Runtimes other than the
101
+ legacy runtime append their runtime ID before hashing. Legacy and absent
102
+ runtimes preserve the hash input used by published clients.
101
103
  It is also the package directory name. Two submits of the same source
102
- with a different entry file, job, args, or asset list get a different ``package_id``
104
+ with a different entry file, job, args, asset list, or effective runtime get a different ``package_id``
103
105
  (a distinct package dir), so one submission never clobbers another's
104
106
  recorded entrypoint or ``args``.
105
107
 
@@ -110,8 +112,10 @@ class Manifest:
110
112
 
111
113
  ⚠️ **Wire stability:** :meth:`to_json` bytes feed the package archive,
112
114
  whose sha256 the control plane pins per ``package_id`` — while
113
- ``package_id`` itself hashes only
114
- ``(source_digest, entrypoint.file, job_name, args, canonical asset list)``.
115
+ ``package_id`` hashes
116
+ ``(source_digest, entrypoint.file, job_name, args, canonical asset list)``
117
+ with the runtime ID appended to those inputs before hashing for
118
+ nonlegacy runtimes.
115
119
  Changes to fields outside those inputs or to their wire serialisation can shift
116
120
  ``archive_sha256`` under an unchanged ``package_id``, which is exactly
117
121
  the server's ``package_conflict`` 409 for every user resubmitting an
@@ -1592,6 +1592,10 @@ class PolicyObservationSchema:
1592
1592
  # Version 1 readers reject unknown keys. Omitting the additive
1593
1593
  # field also preserves its historical bytes exactly.
1594
1594
  del payload["inputs"]
1595
+ else:
1596
+ # PolicyInput owns optional display metadata. Its serializer omits
1597
+ # default labels, retaining the established version-2 wire shape.
1598
+ payload["inputs"] = [input_spec.to_dict() for input_spec in self.inputs]
1595
1599
  return json.dumps(payload, indent=2, sort_keys=True, default=_json_default)
1596
1600
 
1597
1601
  @classmethod
@@ -169,7 +169,11 @@ class LimitsReportComparisonRating(TypedDict):
169
169
 
170
170
 
171
171
  class LimitsReportJoint(TypedDict):
172
- """The applied bounds and measured peaks for one joint at evaluation end."""
172
+ """The applied bounds and measured peaks for one joint at evaluation end.
173
+
174
+ Applied effort is the solved drive force, including implicit damping.
175
+ Breach counts and samples cover the measured step range only.
176
+ """
173
177
 
174
178
  joint: str
175
179
  configured_speed_cap: float | None
@@ -179,6 +183,16 @@ class LimitsReportJoint(TypedDict):
179
183
  speed_peak: float
180
184
  requested_effort_peak: float | Literal["unavailable"]
181
185
  applied_effort_peak: float
186
+ clamped_effort_peak: NotRequired[float | Literal["unavailable"]]
187
+ """The clamped motor-force peak before implicit damping, or ``\"unavailable\"``."""
188
+ drive_effort_peak: NotRequired[float | Literal["unavailable"]]
189
+ """The damper-inclusive drive-force peak, or ``\"unavailable\"``."""
190
+ applied_effort_exceeds_limit: NotRequired[bool]
191
+ """True when the measured step range includes a drive-effort breach."""
192
+ applied_effort_exceedance_count: NotRequired[int]
193
+ """Drive-effort breaches across all copies in the measured step range."""
194
+ applied_effort_exceedance_ranges: NotRequired[list[dict[str, int]]]
195
+ """Inclusive per-copy drive-effort breach ranges for this joint."""
182
196
  speed_breaches: int
183
197
  effort_breaches: int
184
198
  samples: int
@@ -93,10 +93,10 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
93
93
 
94
94
  ``runtime_id`` is an optional top-level execution
95
95
  field. It names the submitted manifest's supported runtime. When it is
96
- missing, the control plane inspects the bounded, uncompressed package
97
- manifest before selecting the legacy Isaac runtime. An Engine manifest
98
- without this field returns ``422 client_runtime_required`` with an
99
- instruction to run ``pip install -U simulo``. Explicit runtime values
96
+ missing, the control plane reads the supported runtime from the bounded,
97
+ uncompressed package manifest. A manifest that also omits the runtime uses
98
+ Simulo Engine. Explicit legacy choices retain their runtime. Invalid runtime
99
+ values return ``422 client_runtime_required``. Explicit request values
100
100
  avoid archive inspection. The selected value is stored and returned inside
101
101
  the worker-only ``job`` record below; the worker compares it with the
102
102
  downloaded package manifest before launch.
@@ -21,6 +21,10 @@ class EngineSetupOverride(TypedDict, total=False):
21
21
  motor_spec: Literal["reference", "real"]
22
22
  catalog_version: str
23
23
  motors: Mapping[str, Mapping[str, float | str]]
24
+ actuators: Mapping[str, Mapping[str, float]]
25
+ """Raw robot file only: actuator name -> ``{"force_limit": largest actuator force}`` for an
26
+ actuator whose transmission is not a joint (tendon, site, slider-crank). The limit lowers the
27
+ file's ``forcerange`` and sets one when the file has none."""
24
28
  action_delay_steps: int
25
29
  solver_substeps: int
26
30
  """Positive solver steps per physics tick; defaults to one on Engine."""
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: simulo-interfaces
3
- Version: 0.26.0
3
+ Version: 0.27.0
4
4
  Summary: Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime.
5
5
  Author-email: Simulo Team <team@simulo.ai>
6
6
  License: BSD-3-Clause
@@ -13,6 +13,7 @@ src/simulo/interfaces/authoring/checkpoint.py
13
13
  src/simulo/interfaces/authoring/entity.py
14
14
  src/simulo/interfaces/authoring/light.py
15
15
  src/simulo/interfaces/authoring/materials.py
16
+ src/simulo/interfaces/authoring/named_actuators.py
16
17
  src/simulo/interfaces/authoring/physics.py
17
18
  src/simulo/interfaces/authoring/policy_inputs.py
18
19
  src/simulo/interfaces/authoring/pose.py
@@ -1,48 +0,0 @@
1
- """Dependency-free authoring data for opt-in per-copy scene variants."""
2
-
3
- from __future__ import annotations
4
-
5
- import math
6
- from dataclasses import dataclass
7
- from typing import Literal, Sequence
8
-
9
- from simulo.interfaces.authoring.asset import AssetSource
10
- from simulo.interfaces.authoring.pose import Pose
11
- from simulo.interfaces.authoring.primitives import PrimitiveShape
12
-
13
-
14
- @dataclass(frozen=True)
15
- class ObjectVariants:
16
- """The objects one authored prop can represent across environment copies.
17
-
18
- ``groups`` assigns each option to a contiguous group of copies. ``pool``
19
- builds every option in each copy so a task can switch the active object at
20
- reset. The engine validates geometry-dependent parking distances at build.
21
- """
22
-
23
- options: Sequence[PrimitiveShape | AssetSource]
24
- mode: Literal["groups", "pool"] = "groups"
25
- parking_origin: Pose | None = None
26
- parking_spacing: float | None = None
27
-
28
- def __post_init__(self) -> None:
29
- options = tuple(self.options)
30
- if not 2 <= len(options) <= 8:
31
- raise ValueError("ObjectVariants.options must contain between 2 and 8 options")
32
- if not all(isinstance(option, (PrimitiveShape, AssetSource)) for option in options):
33
- raise TypeError("ObjectVariants.options must contain PrimitiveShape or AssetSource values")
34
- if self.mode not in {"groups", "pool"}:
35
- raise ValueError("ObjectVariants.mode must be 'groups' or 'pool'")
36
- if self.mode != "pool" and (self.parking_origin is not None or self.parking_spacing is not None):
37
- raise ValueError("parking_origin and parking_spacing are supported only for pool variants")
38
- if self.parking_spacing is not None:
39
- if (
40
- isinstance(self.parking_spacing, bool)
41
- or not math.isfinite(self.parking_spacing)
42
- or self.parking_spacing <= 0
43
- ):
44
- raise ValueError("parking_spacing must be a finite positive number")
45
- object.__setattr__(self, "options", options)
46
-
47
-
48
- __all__ = ["ObjectVariants"]