robotenv 0.2.1__py3-none-any.whl

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 (63) hide show
  1. robotenv/__init__.py +21 -0
  2. robotenv/_canon.py +136 -0
  3. robotenv/config/__init__.py +93 -0
  4. robotenv/config/base_env.py +557 -0
  5. robotenv/config/control.py +161 -0
  6. robotenv/config/defaults.py +29 -0
  7. robotenv/config/env.py +107 -0
  8. robotenv/config/kinematics.py +121 -0
  9. robotenv/config/mount.py +172 -0
  10. robotenv/config/providers.py +171 -0
  11. robotenv/config/robot_providers.py +140 -0
  12. robotenv/config/sim.py +152 -0
  13. robotenv/config/specs.py +111 -0
  14. robotenv/config/sweep.py +100 -0
  15. robotenv/config/task.py +183 -0
  16. robotenv/envs/__init__.py +34 -0
  17. robotenv/envs/spaces.py +38 -0
  18. robotenv/errors.py +35 -0
  19. robotenv/robot/__init__.py +30 -0
  20. robotenv/robot/arm.py +319 -0
  21. robotenv/robot/external.py +234 -0
  22. robotenv/robot/generators.py +138 -0
  23. robotenv/robot/gripper.py +82 -0
  24. robotenv/robot/pose.py +49 -0
  25. robotenv/robot/providers/__init__.py +5 -0
  26. robotenv/robot/providers/menagerie/__init__.py +127 -0
  27. robotenv/robot/providers/menagerie/_describe.py +130 -0
  28. robotenv/robot/providers/menagerie/cards.json +37 -0
  29. robotenv/simulators/__init__.py +51 -0
  30. robotenv/simulators/base.py +70 -0
  31. robotenv/simulators/mujoco/__init__.py +38 -0
  32. robotenv/simulators/mujoco/arm_spec.py +137 -0
  33. robotenv/simulators/mujoco/compile.py +242 -0
  34. robotenv/simulators/mujoco/env.py +257 -0
  35. robotenv/simulators/mujoco/external.py +443 -0
  36. robotenv/simulators/mujoco/mount.py +65 -0
  37. robotenv/simulators/mujoco/render.py +158 -0
  38. robotenv/simulators/mujoco/scenes.py +35 -0
  39. robotenv/simulators/mujoco/sim.py +174 -0
  40. robotenv/simulators/warp/__init__.py +100 -0
  41. robotenv/simulators/warp/env.py +235 -0
  42. robotenv/simulators/warp/sim.py +332 -0
  43. robotenv/tasks/__init__.py +10 -0
  44. robotenv/tasks/base.py +147 -0
  45. robotenv/tasks/empty/__init__.py +42 -0
  46. robotenv/tasks/empty/params.py +33 -0
  47. robotenv/tasks/empty/task.py +27 -0
  48. robotenv/tasks/robosuite/__init__.py +133 -0
  49. robotenv/tasks/robosuite/_compat.py +165 -0
  50. robotenv/tasks/robosuite/_introspect.py +65 -0
  51. robotenv/tasks/robosuite/params.py +152 -0
  52. robotenv/tasks/robosuite/scene.py +140 -0
  53. robotenv/tasks/robosuite/task.py +145 -0
  54. robotenv/viz/__init__.py +22 -0
  55. robotenv/viz/_deps.py +16 -0
  56. robotenv/viz/camera.py +98 -0
  57. robotenv/viz/clip.py +180 -0
  58. robotenv/viz/frames.py +93 -0
  59. robotenv/viz/record.py +141 -0
  60. robotenv-0.2.1.dist-info/METADATA +136 -0
  61. robotenv-0.2.1.dist-info/RECORD +63 -0
  62. robotenv-0.2.1.dist-info/WHEEL +4 -0
  63. robotenv-0.2.1.dist-info/licenses/LICENSE +339 -0
@@ -0,0 +1,171 @@
1
+ """Task providers: who owns which task ids. Imports no simulation engine, torch or robosuite.
2
+
3
+ A task id has the form ``<namespace>/<name>``; it is derived: ``TaskConfig.params`` holds the namespace (the class
4
+ attribute ``provider`` of the params class) and the name (its ``name`` field). The namespace selects a *provider*. A provider
5
+
6
+ - names its tasks and gives the typed ``params`` class of each (the config side, numpy only),
7
+ - checks a config against a simulator (``validate``), and
8
+ - builds the engine side of a task for that simulator (``build``): scene assets, resets, observations, reward.
9
+
10
+ robotenv's own code knows no namespace and no task. Providers are found lazily, from
11
+
12
+ 1. the subpackages of ``robotenv.tasks``: the subpackage name is the namespace and it exposes ``PROVIDER``;
13
+ 2. the entry-point group ``robotenv.task_providers``: the entry-point name is the namespace, the value
14
+ ``"module:attr"`` (this is how another project adds tasks);
15
+ 3. :func:`register_task_provider`, which takes precedence over both.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import importlib
21
+ import importlib.metadata
22
+ import pkgutil
23
+ import re
24
+ from typing import Any, Protocol, runtime_checkable
25
+
26
+ from ..errors import ConfigError, Problem
27
+ from ..robot import Pose
28
+
29
+ __all__ = [
30
+ "ENTRY_POINT_GROUP",
31
+ "TaskProvider",
32
+ "get_task_provider",
33
+ "known_task_ids",
34
+ "list_task_providers",
35
+ "params_class",
36
+ "register_task_provider",
37
+ "split_task_id",
38
+ "unregister_task_provider",
39
+ ]
40
+
41
+ ENTRY_POINT_GROUP = "robotenv.task_providers"
42
+ _NAMESPACE = re.compile(r"[a-z][a-z0-9_]*")
43
+
44
+
45
+ @runtime_checkable
46
+ class TaskProvider(Protocol):
47
+ """What a provider offers. Importing the module that defines it must import no engine."""
48
+
49
+ def task_names(self) -> tuple[str, ...]:
50
+ """Task names, or patterns such as ``"<EnvName>"``; shown when an id is unknown."""
51
+ ...
52
+
53
+ def params_class(self, name: str) -> type | None:
54
+ """The ``params`` class of task ``name`` (``to_dict`` / ``from_dict``), or ``None`` if there is no such task."""
55
+ ...
56
+
57
+ def mount_frame(self, params: Any) -> Pose:
58
+ """The scene's mount frame for this task instance (a world pose); the origin when the scene has no robot slot.
59
+ It depends on the params (a provider's scene options count), not on the task name alone."""
60
+ ...
61
+
62
+ def validate(self, cfg: Any, simulator: str) -> list[Problem]:
63
+ """Every reason ``cfg`` cannot run this task on ``simulator``. May import engines."""
64
+ ...
65
+
66
+ def build(self, cfg: Any, simulator: str) -> Any:
67
+ """The engine side of the task (a ``tasks.base.TaskImpl``) for ``simulator``."""
68
+ ...
69
+
70
+
71
+ # namespace -> provider object, or a lazy "module:attr" string resolved on first use
72
+ _REGISTRY: dict[str, Any] = {}
73
+ _EXPLICIT: set[str] = set()
74
+ _STATE = {"discovered": False}
75
+
76
+
77
+ def register_task_provider(namespace: str, target: Any, *, replace: bool = False) -> None:
78
+ """Register a provider under ``namespace``. ``target`` is a provider, a provider class (instantiated without
79
+ arguments) or a lazy ``"module:attr"`` string. Registering a different target under a taken namespace is an
80
+ error unless ``replace`` is true."""
81
+ if not isinstance(namespace, str) or not _NAMESPACE.fullmatch(namespace):
82
+ raise ConfigError("", f"task namespace must match [a-z][a-z0-9_]*, got {namespace!r}")
83
+ if namespace in _EXPLICIT and _REGISTRY[namespace] is not target and not replace:
84
+ raise ConfigError("", f"task namespace {namespace!r} is already registered; pass replace=True to override it")
85
+ _REGISTRY[namespace] = target
86
+ _EXPLICIT.add(namespace)
87
+
88
+
89
+ def unregister_task_provider(namespace: str) -> None:
90
+ """Forget ``namespace``. Ids of that namespace become unknown until it is registered or discovered again."""
91
+ _REGISTRY.pop(namespace, None)
92
+ _EXPLICIT.discard(namespace)
93
+
94
+
95
+ def _discover() -> None:
96
+ if _STATE["discovered"]:
97
+ return
98
+ _STATE["discovered"] = True
99
+ tasks = importlib.import_module("robotenv.tasks")
100
+ for info in pkgutil.iter_modules(tasks.__path__):
101
+ if info.ispkg and _NAMESPACE.fullmatch(info.name):
102
+ _REGISTRY.setdefault(info.name, f"robotenv.tasks.{info.name}:PROVIDER")
103
+ for ep in importlib.metadata.entry_points(group=ENTRY_POINT_GROUP):
104
+ if _NAMESPACE.fullmatch(ep.name):
105
+ _REGISTRY.setdefault(ep.name, ep.value)
106
+
107
+
108
+ def _load(namespace: str) -> TaskProvider:
109
+ target = _REGISTRY[namespace]
110
+ if isinstance(target, str):
111
+ module, _, attr = target.partition(":")
112
+ try:
113
+ obj = getattr(importlib.import_module(module), attr or "PROVIDER")
114
+ except Exception as e:
115
+ raise ConfigError(
116
+ "task.provider", f"task provider {namespace!r} ({target}) could not be loaded: {type(e).__name__}: {e}"
117
+ ) from e
118
+ target = obj() if isinstance(obj, type) else obj
119
+ _REGISTRY[namespace] = target
120
+ elif isinstance(target, type):
121
+ target = _REGISTRY[namespace] = target()
122
+ if not isinstance(target, TaskProvider):
123
+ raise ConfigError("task.provider", f"task provider {namespace!r} does not implement the TaskProvider protocol")
124
+ return target
125
+
126
+
127
+ def list_task_providers() -> tuple[str, ...]:
128
+ """Namespaces of every registered provider, sorted. Loads none of them."""
129
+ _discover()
130
+ return tuple(sorted(_REGISTRY))
131
+
132
+
133
+ def get_task_provider(namespace: str) -> TaskProvider:
134
+ _discover()
135
+ if namespace not in _REGISTRY:
136
+ raise ConfigError(
137
+ "task.provider", f"unknown task provider {namespace!r}; registered: {list(list_task_providers())}"
138
+ )
139
+ return _load(namespace)
140
+
141
+
142
+ def split_task_id(task_id: Any) -> tuple[str, str] | None:
143
+ """``(namespace, name)`` of ``"<namespace>/<name>"``, or ``None`` when ``task_id`` has no such form."""
144
+ if not isinstance(task_id, str):
145
+ return None
146
+ namespace, sep, name = task_id.partition("/")
147
+ if not sep or not name or not _NAMESPACE.fullmatch(namespace):
148
+ return None
149
+ return namespace, name
150
+
151
+
152
+ def params_class(task_id: Any) -> type | None:
153
+ """The ``params`` class of ``task_id``, or ``None`` when no registered provider has that task."""
154
+ parts = split_task_id(task_id)
155
+ if parts is None:
156
+ return None
157
+ _discover()
158
+ if parts[0] not in _REGISTRY:
159
+ return None
160
+ return _load(parts[0]).params_class(parts[1])
161
+
162
+
163
+ def known_task_ids() -> list[str]:
164
+ """Every id of every registered provider, for error messages. A provider that fails to load is listed as such."""
165
+ out: list[str] = []
166
+ for namespace in list_task_providers():
167
+ try:
168
+ out += [f"{namespace}/{name}" for name in _load(namespace).task_names()]
169
+ except ConfigError:
170
+ out.append(f"{namespace}/? (provider could not be loaded)")
171
+ return out
@@ -0,0 +1,140 @@
1
+ """Robot providers: who owns which robot namespace. Imports no simulation engine and no torch.
2
+
3
+ An :class:`~robotenv.robot.ExternalRobot` refers to a model that lives elsewhere. Its ``provider`` field is a
4
+ namespace, and the namespace selects a *provider*, which
5
+
6
+ - lists its robots (``names``),
7
+ - reads a model and returns the numbers a config needs (``describe``, engine side),
8
+ - opens the model as an editable ``mujoco.MjSpec`` after checking it against ``robot.source`` (``spec``, engine side),
9
+ - checks a robot against a simulator (``validate``), and
10
+ - gives a numpy oracle of the robot's kinematics (``kinematics``, engine side).
11
+
12
+ This mirrors task providers (``config/providers.py``). The core knows no namespace. Providers are found lazily, from
13
+
14
+ 1. the subpackages of ``robotenv.robot.providers``: the subpackage name is the namespace and it exposes ``PROVIDER``;
15
+ 2. the entry-point group ``robotenv.robot.providers``: the entry-point name is the namespace, the value ``"module:attr"``;
16
+ 3. :func:`register_robot_provider`, which takes precedence over both.
17
+
18
+ Answering ``list_robot_providers`` loads nothing; a provider module is imported when the provider is first used.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import importlib
24
+ import importlib.metadata
25
+ import pkgutil
26
+ import re
27
+ from typing import Any, Protocol, runtime_checkable
28
+
29
+ from ..errors import ConfigError, Problem
30
+
31
+ __all__ = [
32
+ "ENTRY_POINT_GROUP",
33
+ "RobotProvider",
34
+ "get_robot_provider",
35
+ "list_robot_providers",
36
+ "register_robot_provider",
37
+ "unregister_robot_provider",
38
+ ]
39
+
40
+ ENTRY_POINT_GROUP = "robotenv.robot.providers"
41
+ _NAMESPACE = re.compile(r"[a-z][a-z0-9_]*")
42
+
43
+
44
+ @runtime_checkable
45
+ class RobotProvider(Protocol):
46
+ """What a robot provider offers. Importing the module that defines it must import no engine."""
47
+
48
+ def names(self) -> tuple[str, ...]:
49
+ """Robot names, or patterns; shown when a name is unknown."""
50
+ ...
51
+
52
+ def describe(self, name: str, **options: Any) -> Any:
53
+ """Read the model of robot ``name`` and return an ``ExternalRobot``. Engine side."""
54
+ ...
55
+
56
+ def spec(self, robot: Any) -> Any:
57
+ """An editable ``mujoco.MjSpec`` of ``robot``, checked against ``robot.source``. Engine side."""
58
+ ...
59
+
60
+ def validate(self, robot: Any, simulator: str) -> list[Problem]:
61
+ """Every reason ``robot`` cannot run on ``simulator``. May import engines."""
62
+ ...
63
+
64
+ def kinematics(self, robot: Any) -> Any:
65
+ """An object with ``forward_ee_batch(q, base)`` and ``sample_joint_positions(num, rng)``. Engine side."""
66
+ ...
67
+
68
+
69
+ # namespace -> provider object, or a lazy "module:attr" string resolved on first use
70
+ _REGISTRY: dict[str, Any] = {}
71
+ _EXPLICIT: set[str] = set()
72
+ _STATE = {"discovered": False}
73
+
74
+
75
+ def register_robot_provider(namespace: str, target: Any, *, replace: bool = False) -> None:
76
+ """Register a provider under ``namespace``. ``target`` is a provider, a provider class (instantiated without
77
+ arguments) or a lazy ``"module:attr"`` string. Registering a different target under a taken namespace is an
78
+ error unless ``replace`` is true."""
79
+ if not isinstance(namespace, str) or not _NAMESPACE.fullmatch(namespace):
80
+ raise ConfigError("", f"robot namespace must match [a-z][a-z0-9_]*, got {namespace!r}")
81
+ if namespace in _EXPLICIT and _REGISTRY[namespace] is not target and not replace:
82
+ raise ConfigError("", f"robot namespace {namespace!r} is already registered; pass replace=True to override it")
83
+ _REGISTRY[namespace] = target
84
+ _EXPLICIT.add(namespace)
85
+
86
+
87
+ def unregister_robot_provider(namespace: str) -> None:
88
+ """Forget ``namespace``. Robots of that namespace become unknown until it is registered or discovered again."""
89
+ _REGISTRY.pop(namespace, None)
90
+ _EXPLICIT.discard(namespace)
91
+
92
+
93
+ def _discover() -> None:
94
+ if _STATE["discovered"]:
95
+ return
96
+ _STATE["discovered"] = True
97
+ package = importlib.import_module("robotenv.robot.providers")
98
+ for info in pkgutil.iter_modules(package.__path__):
99
+ if info.ispkg and _NAMESPACE.fullmatch(info.name):
100
+ _REGISTRY.setdefault(info.name, f"robotenv.robot.providers.{info.name}:PROVIDER")
101
+ for ep in importlib.metadata.entry_points(group=ENTRY_POINT_GROUP):
102
+ if _NAMESPACE.fullmatch(ep.name):
103
+ _REGISTRY.setdefault(ep.name, ep.value)
104
+
105
+
106
+ def _load(namespace: str) -> RobotProvider:
107
+ target = _REGISTRY[namespace]
108
+ if isinstance(target, str):
109
+ module, _, attr = target.partition(":")
110
+ try:
111
+ obj = getattr(importlib.import_module(module), attr or "PROVIDER")
112
+ except Exception as e:
113
+ raise ConfigError(
114
+ "robot.provider",
115
+ f"robot provider {namespace!r} ({target}) could not be loaded: {type(e).__name__}: {e}",
116
+ ) from e
117
+ target = obj() if isinstance(obj, type) else obj
118
+ _REGISTRY[namespace] = target
119
+ elif isinstance(target, type):
120
+ target = _REGISTRY[namespace] = target()
121
+ if not isinstance(target, RobotProvider):
122
+ raise ConfigError(
123
+ "robot.provider", f"robot provider {namespace!r} does not implement the RobotProvider protocol"
124
+ )
125
+ return target
126
+
127
+
128
+ def list_robot_providers() -> tuple[str, ...]:
129
+ """Namespaces of every registered robot provider, sorted. Loads none of them."""
130
+ _discover()
131
+ return tuple(sorted(_REGISTRY))
132
+
133
+
134
+ def get_robot_provider(namespace: str) -> RobotProvider:
135
+ _discover()
136
+ if namespace not in _REGISTRY:
137
+ raise ConfigError(
138
+ "robot.provider", f"unknown robot provider {namespace!r}; registered: {list(list_robot_providers())}"
139
+ )
140
+ return _load(namespace)
robotenv/config/sim.py ADDED
@@ -0,0 +1,152 @@
1
+ """Simulation settings, including the options of the chosen simulator. Nothing here has a default value.
2
+
3
+ ``SimConfig.simulator`` names the simulator (a physics engine, for example ``"mujoco"``), never a source of tasks;
4
+ tasks come from task providers (``config.providers``). ``SimConfig.options`` holds the settings that exist for that
5
+ simulator only, as an instance of the options class registered for its name.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+ from dataclasses import dataclass, fields
12
+ from typing import Any, Mapping
13
+
14
+ from .._canon import as_bool, as_float, as_int, as_str, check_keys, within
15
+ from ..errors import ConfigError
16
+
17
+ INTEGRATORS = ("euler", "implicit", "implicitfast", "rk4")
18
+ _DEVICE = re.compile(r"cpu|cuda:\d+")
19
+
20
+
21
+ @dataclass(frozen=True, slots=True)
22
+ class MujocoOptions:
23
+ self_collision: bool
24
+
25
+ def __post_init__(self):
26
+ as_bool(self.self_collision, "self_collision")
27
+
28
+ @classmethod
29
+ def default(cls) -> "MujocoOptions":
30
+ """The options ``BaseEnvConfig`` uses (an optional hook of every options class)."""
31
+ return cls(self_collision=False)
32
+
33
+ def to_dict(self) -> dict[str, Any]:
34
+ return {f.name: getattr(self, f.name) for f in fields(self)}
35
+
36
+ @classmethod
37
+ def from_dict(cls, d: Mapping[str, Any]) -> "MujocoOptions":
38
+ check_keys(d, {f.name for f in fields(cls)}, "")
39
+ return cls(**d)
40
+
41
+
42
+ @dataclass(frozen=True, slots=True)
43
+ class WarpOptions:
44
+ """Settings of the MuJoCo Warp (GPU) simulator. Capacities are per world, so ``num_envs`` can change freely."""
45
+
46
+ njmax: int # constraint rows allocated per world; no world may exceed it
47
+ nconmax: int # contacts allocated per world; the simulation allocates nconmax * num_envs
48
+ cuda_graph: bool # capture the physics sub-steps of one policy step in a CUDA graph
49
+
50
+ def __post_init__(self):
51
+ for name in ("njmax", "nconmax"):
52
+ value = as_int(getattr(self, name), name)
53
+ if value < 1:
54
+ raise ConfigError(name, "must be >= 1")
55
+ object.__setattr__(self, name, value)
56
+ as_bool(self.cuda_graph, "cuda_graph")
57
+
58
+ @classmethod
59
+ def default(cls) -> "WarpOptions":
60
+ # Plain choices from benchmarks/bench_warp.py (the task counts are in docs/configs/sim.md): the largest counts per world
61
+ # over a random-policy rollout of a table-top scene with one or two objects were 32 to 52 constraint rows and 8 to 13
62
+ # contacts, so 128 / 32 leaves about 2.5x headroom; scenes with many contacts need larger options. Counts do not
63
+ # depend on the device. The CUDA graph is on: it replays the physics sub-steps of a step as one launch, which was 12 to 13 times
64
+ # faster per step than stepping kernel by kernel in the Lift sweep of benchmarks/bench_warp.py (CUDA only; resets are not captured).
65
+ return cls(njmax=128, nconmax=32, cuda_graph=True)
66
+
67
+ def to_dict(self) -> dict[str, Any]:
68
+ return {f.name: getattr(self, f.name) for f in fields(self)}
69
+
70
+ @classmethod
71
+ def from_dict(cls, d: Mapping[str, Any]) -> "WarpOptions":
72
+ check_keys(d, {f.name for f in fields(cls)}, "")
73
+ return cls(**d)
74
+
75
+
76
+ # One typed options class per simulator name. Simulators outside this package may register theirs.
77
+ SIMULATOR_OPTIONS: dict[str, type] = {"mujoco": MujocoOptions, "warp": WarpOptions}
78
+
79
+
80
+ def register_simulator_options(simulator: str, cls: type) -> None:
81
+ """Declare the options class of a simulator. It needs ``to_dict`` and ``from_dict``, and may have a ``default()``
82
+ classmethod: ``BaseEnvConfig.sim(simulator=...)`` uses it to reset the options when the simulator changes."""
83
+ SIMULATOR_OPTIONS[simulator] = cls
84
+
85
+
86
+ def _options_class(simulator: str) -> type:
87
+ cls = SIMULATOR_OPTIONS.get(simulator)
88
+ if cls is None:
89
+ raise ConfigError(
90
+ "simulator", f"no options registered for simulator {simulator!r}; known: {sorted(SIMULATOR_OPTIONS)}"
91
+ )
92
+ return cls
93
+
94
+
95
+ @dataclass(frozen=True, slots=True)
96
+ class SimConfig:
97
+ simulator: str
98
+ num_envs: int
99
+ device: str
100
+ dt: float
101
+ integrator: str
102
+ control_freq: float
103
+ seed: int
104
+ scene: str
105
+ options: Any
106
+
107
+ def __post_init__(self):
108
+ as_str(self.simulator, "simulator")
109
+ as_str(self.scene, "scene")
110
+ n = as_int(self.num_envs, "num_envs")
111
+ if n < 1:
112
+ raise ConfigError("num_envs", "must be >= 1")
113
+ object.__setattr__(self, "num_envs", n)
114
+ if not isinstance(self.device, str) or not _DEVICE.fullmatch(self.device):
115
+ raise ConfigError("device", f"must be 'cpu' or 'cuda:N', got {self.device!r}")
116
+ if self.integrator not in INTEGRATORS:
117
+ raise ConfigError("integrator", f"unknown {self.integrator!r}; expected one of {list(INTEGRATORS)}")
118
+ dt = as_float(self.dt, "dt")
119
+ if dt <= 0.0:
120
+ raise ConfigError("dt", "must be > 0")
121
+ object.__setattr__(self, "dt", dt)
122
+ freq = as_float(self.control_freq, "control_freq")
123
+ if freq <= 0.0:
124
+ raise ConfigError("control_freq", "must be > 0")
125
+ object.__setattr__(self, "control_freq", freq)
126
+ substeps = 1.0 / (freq * dt)
127
+ if substeps < 1.0 - 1e-9 or abs(substeps - round(substeps)) > 1e-9:
128
+ raise ConfigError(
129
+ "control_freq",
130
+ f"1 / (control_freq * dt) must be a positive integer, got {substeps:.9g} "
131
+ f"(control_freq={freq}, dt={dt})",
132
+ )
133
+ object.__setattr__(self, "seed", as_int(self.seed, "seed"))
134
+ options_cls = _options_class(self.simulator)
135
+ if not isinstance(self.options, options_cls):
136
+ raise ConfigError("options", f"simulator {self.simulator!r} requires {options_cls.__name__}")
137
+
138
+ @property
139
+ def n_substeps(self) -> int:
140
+ return round(1.0 / (self.control_freq * self.dt))
141
+
142
+ def to_dict(self) -> dict[str, Any]:
143
+ d = {f.name: getattr(self, f.name) for f in fields(self) if f.name != "options"}
144
+ d["options"] = self.options.to_dict()
145
+ return d
146
+
147
+ @classmethod
148
+ def from_dict(cls, d: Mapping[str, Any]) -> "SimConfig":
149
+ check_keys(d, {f.name for f in fields(cls)}, "")
150
+ options_cls = _options_class(as_str(d["simulator"], "simulator"))
151
+ rest = {k: v for k, v in d.items() if k != "options"}
152
+ return cls(**rest, options=within("options", options_cls.from_dict, d["options"]))
@@ -0,0 +1,111 @@
1
+ """Partial specs for the builder layer: ``NOT_SET`` and ``Chain``. numpy only.
2
+
3
+ A spec says only what the caller wrote. ``BaseEnvConfig`` merges specs into a complete description; the frozen configs
4
+ (``ParametricArm``, ``SimConfig``, ...) never see a missing value.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from dataclasses import dataclass, fields, replace
10
+ from typing import Any
11
+
12
+ from ..errors import ConfigError
13
+ from ..robot import ParametricArm, chain
14
+
15
+ __all__ = ["NOT_SET", "Chain"]
16
+
17
+
18
+ class _NotSet:
19
+ """The marker of "argument not passed". ``None`` is a meaningful value in some configs, so it cannot be used."""
20
+
21
+ _instance: "_NotSet | None" = None
22
+
23
+ def __new__(cls):
24
+ if cls._instance is None:
25
+ cls._instance = super().__new__(cls)
26
+ return cls._instance
27
+
28
+ def __repr__(self) -> str:
29
+ return "NOT_SET"
30
+
31
+ def __bool__(self) -> bool:
32
+ return False
33
+
34
+ def __copy__(self):
35
+ return self
36
+
37
+ def __deepcopy__(self, memo):
38
+ return self
39
+
40
+ def __reduce__(self):
41
+ return (_NotSet, ())
42
+
43
+
44
+ NOT_SET: Any = _NotSet()
45
+
46
+ _PAIRS = (("link_length", "total_length"), ("mass", "total_mass"))
47
+ _REQUIRED = ("n", "axes", "radius", "damping", "armature", "frictionloss", "effort_limit")
48
+
49
+
50
+ @dataclass(frozen=True, slots=True)
51
+ class Chain:
52
+ """The arguments of :func:`chain` (without a base pose: the mount belongs to the task), each optional.
53
+
54
+ Used as a partial description, ``BaseEnvConfig().robot(Chain(n=5, axes="zyyyy"))`` changes what is written and
55
+ keeps the rest. Writing one of ``link_length`` / ``total_length`` (or ``mass`` / ``total_mass``) clears the other.
56
+ ``arm()`` returns the :class:`ParametricArm`, and needs every required value to be set.
57
+ """
58
+
59
+ n: Any = NOT_SET
60
+ axes: Any = NOT_SET
61
+ link_length: Any = NOT_SET
62
+ total_length: Any = NOT_SET
63
+ mass: Any = NOT_SET
64
+ total_mass: Any = NOT_SET
65
+ radius: Any = NOT_SET
66
+ damping: Any = NOT_SET
67
+ armature: Any = NOT_SET
68
+ frictionloss: Any = NOT_SET
69
+ effort_limit: Any = NOT_SET
70
+ range: Any = NOT_SET
71
+ home_qpos: Any = NOT_SET
72
+ end_effector: Any = NOT_SET
73
+ tool: Any = NOT_SET
74
+ gripper: Any = NOT_SET
75
+ label: Any = NOT_SET
76
+
77
+ def written(self) -> tuple[str, ...]:
78
+ """The names of the fields that were given."""
79
+ return tuple(f.name for f in fields(self) if getattr(self, f.name) is not NOT_SET)
80
+
81
+ def merge(self, other: "Chain") -> "Chain":
82
+ """``self`` with the fields written in ``other`` on top; the partner of an exclusive pair is cleared."""
83
+ if not isinstance(other, Chain):
84
+ raise ConfigError("robot", f"expected a Chain, got {type(other).__name__}")
85
+ changes = {name: getattr(other, name) for name in other.written()}
86
+ for a, b in _PAIRS:
87
+ if a in changes and b not in changes:
88
+ changes[b] = NOT_SET
89
+ elif b in changes and a not in changes:
90
+ changes[a] = NOT_SET
91
+ return replace(self, **changes)
92
+
93
+ def arm(self) -> ParametricArm:
94
+ """Build the arm. Raises ``ConfigError`` (path: the argument of ``chain``) when it cannot be built."""
95
+ for name in _REQUIRED:
96
+ if getattr(self, name) is NOT_SET:
97
+ raise ConfigError(name, "not set")
98
+
99
+ def get(name, fallback=None):
100
+ v = getattr(self, name)
101
+ return fallback if v is NOT_SET else v
102
+
103
+ return chain(
104
+ self.n, self.axes,
105
+ link_length=get("link_length"), total_length=get("total_length"),
106
+ mass=get("mass"), total_mass=get("total_mass"),
107
+ radius=self.radius, damping=self.damping, armature=self.armature,
108
+ frictionloss=self.frictionloss, effort_limit=self.effort_limit,
109
+ range=get("range"), home_qpos=get("home_qpos"), end_effector=get("end_effector"),
110
+ tool=get("tool"), gripper=get("gripper"), label=get("label", ""),
111
+ )
@@ -0,0 +1,100 @@
1
+ """``BaseEnvConfig.sweep``: a family of environment configs, one per combination of overrides. numpy only.
2
+
3
+ A plain expansion: launching the jobs (Slurm or other) is left to the project that uses it. Give each job the resolved dict
4
+ (``config.resolve().to_dict()``) and rebuild with ``EnvConfig.from_dict`` in the worker: the task and robot registries are
5
+ process-global, so a worker must not rely on state of the launching process.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import itertools
11
+ import warnings
12
+ from typing import TYPE_CHECKING, Any, Iterator, Mapping
13
+
14
+ from .env import EnvConfig
15
+ from ..errors import ConfigError
16
+
17
+ if TYPE_CHECKING:
18
+ from .base_env import BaseEnvConfig
19
+
20
+ __all__ = ["Family"]
21
+
22
+
23
+ def _axes(kind: str, spec: Mapping[str, Any] | None) -> dict[str, list]:
24
+ out: dict[str, list] = {}
25
+ for key, values in (spec or {}).items():
26
+ if isinstance(values, (str, bytes)) or not hasattr(values, "__iter__"):
27
+ raise ConfigError(f"sweep.{kind}.{key}", f"expected a sequence of values, got {type(values).__name__}")
28
+ values = list(values)
29
+ if not values:
30
+ raise ConfigError(f"sweep.{kind}.{key}", "has no values")
31
+ out[key] = values
32
+ return out
33
+
34
+
35
+ class Family:
36
+ """The configs of a sweep, in order: ``len``, iteration and indexing give ``BaseEnvConfig`` items. ``notes`` lists
37
+ the items dropped because their resolved ``env_hash`` repeated."""
38
+
39
+ def __init__(self, items: list[tuple[dict[str, Any], "BaseEnvConfig", EnvConfig]], notes: list[str]):
40
+ self._items = items
41
+ self.notes = notes
42
+
43
+ def __len__(self) -> int:
44
+ return len(self._items)
45
+
46
+ def __iter__(self) -> Iterator["BaseEnvConfig"]:
47
+ return (cfg for _, cfg, _ in self._items)
48
+
49
+ def __getitem__(self, i: int) -> "BaseEnvConfig":
50
+ return self._items[i][1]
51
+
52
+ def configs(self) -> list[EnvConfig]:
53
+ """The resolved ``EnvConfig`` of every item."""
54
+ return [env for _, _, env in self._items]
55
+
56
+ def overrides(self) -> list[dict[str, Any]]:
57
+ """The overrides that produced every item."""
58
+ return [dict(o) for o, _, _ in self._items]
59
+
60
+ def table(self) -> list[dict[str, Any]]:
61
+ """One row per item: ``index``, the override values by dotted path, and ``env_hash``."""
62
+ return [{"index": i, **o, "env_hash": env.env_hash} for i, (o, _, env) in enumerate(self._items)]
63
+
64
+ def __repr__(self) -> str:
65
+ return f"Family({len(self)} configs)"
66
+
67
+
68
+ def expand(base: "BaseEnvConfig", paired: Mapping[str, Any] | None, grid: Mapping[str, Any] | None) -> Family:
69
+ paired_axes, grid_axes = _axes("paired", paired), _axes("grid", grid)
70
+ both = sorted(set(paired_axes) & set(grid_axes))
71
+ if both:
72
+ raise ConfigError(f"sweep.{both[0]}", "is in both paired and grid")
73
+ lengths = {k: len(v) for k, v in paired_axes.items()}
74
+ if len(set(lengths.values())) > 1:
75
+ raise ConfigError("sweep.paired", f"axes must have equal lengths, got {lengths}")
76
+ groups = ([dict(zip(paired_axes, vals)) for vals in zip(*paired_axes.values())] if paired_axes else [{}])
77
+ combos = [dict(zip(grid_axes, vals)) for vals in itertools.product(*grid_axes.values())]
78
+ items: list[tuple[dict[str, Any], "BaseEnvConfig", EnvConfig]] = []
79
+ seen: dict[str, int] = {}
80
+ notes: list[str] = []
81
+ index = -1
82
+ for group in groups:
83
+ for combo in combos:
84
+ index += 1
85
+ overrides = {**group, **combo}
86
+ try:
87
+ cfg = base.with_overrides(overrides)
88
+ env = cfg.resolve()
89
+ except ConfigError as e:
90
+ err = ConfigError(e.path, f"{e.reason} (sweep item {index}: {overrides})")
91
+ err.problems = getattr(e, "problems", ())
92
+ raise err from None
93
+ if env.env_hash in seen:
94
+ notes.append(f"item {index} {overrides} repeats item {seen[env.env_hash]} (env_hash {env.env_hash}); dropped")
95
+ continue
96
+ seen[env.env_hash] = index
97
+ items.append((overrides, cfg, env))
98
+ if notes:
99
+ warnings.warn("; ".join(notes), stacklevel=3)
100
+ return Family(items, notes)