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,557 @@
1
+ """``BaseEnvConfig``: a complete, runnable environment description refined with accumulating section calls.
2
+
3
+ The builder layer, like RLlib's ``AlgorithmConfig`` in ergonomics only: no ``ray``, no trainer. ``BaseEnvConfig()`` is a
4
+ one-link arm in the ``empty`` scene doing the ``empty/idle`` task (the table in ``defaults.py``); ``.robot()``,
5
+ ``.control()``, ``.task()`` and ``.sim()`` each return a new config that changes what the call writes and keeps the rest;
6
+ ``resolve()`` returns the frozen, validated :class:`EnvConfig` with its ``env_hash``. Defaults live here and nowhere
7
+ else: ``EnvConfig`` and the configs under it keep requiring every field. numpy only; the engine is imported by ``build()``.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+ import warnings
14
+ from dataclasses import fields
15
+ from pathlib import Path
16
+ from typing import Any, Mapping, Sequence
17
+
18
+ from .._canon import check_keys, within
19
+ from .control import CONTROL_MODES, NATIVE_MODES, ControlConfig, FixedGains, NativeGains
20
+ from .defaults import DEFAULTS, DEFAULTS_VERSION
21
+ from .env import EnvConfig
22
+ from ..errors import ConfigError, Problem
23
+ from .providers import get_task_provider
24
+ from .robot_providers import get_robot_provider
25
+ from ..robot import ExternalRobot, ParametricArm, Pose, ToolSpec, TwoFingerGripper, robot_from_dict
26
+ from .sim import SIMULATOR_OPTIONS, SimConfig
27
+ from .specs import NOT_SET, Chain
28
+ from .mount import Mount, snapped
29
+ from .task import TaskConfig, migrate_task_dict
30
+
31
+ __all__ = ["BaseEnvConfig"]
32
+
33
+ _CONTROL_FIELDS = ("mode", "gains", "action_scale")
34
+ _TASK_FIELDS = ("max_episode_steps", "success_tolerance", "target_region", "mount")
35
+ _SIM_FIELDS = tuple(f.name for f in fields(SimConfig))
36
+ _GOAL_FIELDS = ("success_tolerance", "target_region")
37
+
38
+
39
+ def _unknown(section: str, key: str, allowed) -> ConfigError:
40
+ hint = " ('horizon' was renamed to 'max_episode_steps')" if (section, key) == ("task", "horizon") else ""
41
+ return ConfigError(f"{section}.{key}", f"unknown field{hint}; expected one of {sorted(allowed)}")
42
+
43
+
44
+ def _check_keys(section: str, given: dict, allowed) -> None:
45
+ for key in given:
46
+ if key not in allowed:
47
+ raise _unknown(section, key, allowed)
48
+
49
+
50
+ def _norm(v: Any) -> Any:
51
+ """Lists and tuples compare equal, for ``diff``."""
52
+ return tuple(_norm(x) for x in v) if isinstance(v, (list, tuple)) else v
53
+
54
+
55
+ def _default_options(simulator: str) -> Any:
56
+ cls = SIMULATOR_OPTIONS.get(simulator)
57
+ if cls is None:
58
+ raise ConfigError("sim.simulator", f"no options registered for simulator {simulator!r}; known: {sorted(SIMULATOR_OPTIONS)}")
59
+ default = getattr(cls, "default", None)
60
+ return NOT_SET if default is None else default()
61
+
62
+
63
+ _SECTIONS = ("robot", "control", "task", "sim")
64
+ _READY = (ParametricArm, ExternalRobot) # a ready robot: it replaces the section, no Chain fields apply to it
65
+ _CHAIN_FIELDS = tuple(f.name for f in fields(Chain))
66
+ _PAIRS = (("link_length", "total_length"), ("mass", "total_mass"))
67
+
68
+
69
+ def _jsonable(v: Any) -> Any:
70
+ """A plain JSON-able value: objects with ``to_dict`` are converted, tuples become lists."""
71
+ if hasattr(v, "to_dict"):
72
+ return v.to_dict()
73
+ if isinstance(v, (list, tuple)):
74
+ return [_jsonable(x) for x in v]
75
+ if isinstance(v, Mapping):
76
+ return {k: _jsonable(x) for k, x in v.items()}
77
+ return v
78
+
79
+
80
+ def _tuplify(v: Any) -> Any:
81
+ return tuple(_tuplify(x) for x in v) if isinstance(v, (list, tuple)) else v
82
+
83
+
84
+ def _parse_override(item: str) -> tuple[str, Any]:
85
+ """``"path=value"``: the value is a JSON literal, or a string if it is not one."""
86
+ path, sep, raw = item.partition("=")
87
+ if not sep or not path.strip():
88
+ raise ConfigError("", f"override {item!r} is not of the form path=value")
89
+ try:
90
+ return path.strip(), json.loads(raw)
91
+ except ValueError:
92
+ return path.strip(), raw
93
+
94
+
95
+ def _yaml():
96
+ try:
97
+ import yaml
98
+ except ImportError as e:
99
+ raise ImportError("YAML configs need the optional extra: pip install 'robotenv[yaml]'") from e
100
+ return yaml
101
+
102
+
103
+ class BaseEnvConfig:
104
+ """See the module docstring. Immutable by convention: every call returns a new object, the receiver is unchanged."""
105
+
106
+ __slots__ = ("_robot", "_control", "_task", "_sim", "_written")
107
+
108
+ def __init__(self):
109
+ d = DEFAULTS
110
+ provider, name = d["task"]["provider"], d["task"]["name"]
111
+ params_cls = get_task_provider(provider).params_class(name)
112
+ self._robot: Chain | ParametricArm | ExternalRobot = Chain(**d["robot"])
113
+ self._control = {"mode": d["control"]["mode"], "gains": FixedGains(d["control"]["kp"], d["control"]["kd"]),
114
+ "action_scale": d["control"]["action_scale"]}
115
+ self._task = {"params": params_cls(name=name), "max_episode_steps": d["task"]["max_episode_steps"], "success_tolerance": None,
116
+ "target_region": None, "mount": Mount()}
117
+ self._sim = {k: d["sim"][k] for k in _SIM_FIELDS if k != "options"}
118
+ self._sim["options"] = _default_options(d["sim"]["simulator"])
119
+ self._written: frozenset[str] = frozenset()
120
+
121
+ # --- copying ---------------------------------------------------------------------
122
+
123
+ def _copy(self, *, robot=None, control=None, task=None, sim=None, written=None) -> "BaseEnvConfig":
124
+ new = object.__new__(BaseEnvConfig)
125
+ new._robot = self._robot if robot is None else robot
126
+ new._control = self._control if control is None else control
127
+ new._task = self._task if task is None else task
128
+ new._sim = self._sim if sim is None else sim
129
+ new._written = self._written if written is None else written
130
+ return new
131
+
132
+ # --- section calls ---------------------------------------------------------------
133
+
134
+ def robot(self, robot: Any = NOT_SET, **fields_: Any) -> "BaseEnvConfig":
135
+ """Refine the robot. ``robot`` is a :class:`Chain` (written fields change, the rest carries), a ready
136
+ ``ParametricArm`` or ``ExternalRobot`` (a fixed robot: it replaces the section) or omitted; keywords are fields
137
+ of ``Chain``."""
138
+ allowed = [f.name for f in fields(Chain)]
139
+ _check_keys("robot", fields_, allowed)
140
+ written = set(self._written)
141
+ if isinstance(robot, _READY):
142
+ if fields_:
143
+ raise ConfigError("robot", f"a ready {type(robot).__name__} cannot be combined with Chain fields")
144
+ written = {w for w in written if not w.startswith("robot")} | {"robot"}
145
+ return self._copy(robot=robot, written=frozenset(written))
146
+ if robot is not NOT_SET and not isinstance(robot, Chain):
147
+ raise ConfigError("robot", f"expected a Chain, a ParametricArm or an ExternalRobot, got {type(robot).__name__}")
148
+ if isinstance(self._robot, Chain):
149
+ base = self._robot
150
+ else: # a fixed robot is replaced by the default chain with the written fields on top
151
+ base = Chain(**DEFAULTS["robot"])
152
+ written = {w for w in written if not w.startswith("robot")}
153
+ merged, new = base, set()
154
+ for spec in (robot, Chain(**fields_)):
155
+ if spec is not NOT_SET:
156
+ merged = merged.merge(spec)
157
+ new |= {f"robot.{n}" for n in spec.written()}
158
+ written = {w for w in written if w[6:] in merged.written() or not w.startswith("robot.")} | new
159
+ return self._copy(robot=merged, written=frozenset(written))
160
+
161
+ def control(self, control: Any = NOT_SET, **fields_: Any) -> "BaseEnvConfig":
162
+ """Refine the control: keywords ``mode``, ``gains``, ``action_scale``, or a whole ``ControlConfig``."""
163
+ _check_keys("control", fields_, _CONTROL_FIELDS)
164
+ values = dict(self._control)
165
+ changed = dict(fields_)
166
+ if control is not NOT_SET:
167
+ if not isinstance(control, ControlConfig):
168
+ raise ConfigError("control", f"expected a ControlConfig, got {type(control).__name__}")
169
+ changed = {**{k: getattr(control, k) for k in _CONTROL_FIELDS}, **changed}
170
+ values.update(changed)
171
+ return self._copy(control=values, written=self._written | {f"control.{k}" for k in changed})
172
+
173
+ def task(self, params: Any = NOT_SET, **fields_: Any) -> "BaseEnvConfig":
174
+ """Refine the task: a provider's params object (it is the task), keywords ``max_episode_steps``, ``success_tolerance``,
175
+ ``target_region``, ``mount``, or a whole ``TaskConfig``. A new params class resets ``success_tolerance`` and
176
+ ``target_region`` (they belong to goal tasks) unless the call writes them. A written ``mount`` is pinned."""
177
+ _check_keys("task", fields_, _TASK_FIELDS)
178
+ values = dict(self._task)
179
+ changed = dict(fields_)
180
+ if isinstance(params, TaskConfig):
181
+ changed = {**{k: getattr(params, k) for k in _TASK_FIELDS}, **changed}
182
+ params = params.params
183
+ if params is not NOT_SET:
184
+ if type(params) is not type(values["params"]):
185
+ for k in _GOAL_FIELDS:
186
+ changed.setdefault(k, None)
187
+ changed["params"] = params
188
+ values.update(changed)
189
+ return self._copy(task=values, written=self._written | {f"task.{k}" for k in changed})
190
+
191
+ def sim(self, sim: Any = NOT_SET, **fields_: Any) -> "BaseEnvConfig":
192
+ """Refine the simulation: keywords are the fields of ``SimConfig``, or give a whole ``SimConfig``. Changing
193
+ ``simulator`` resets ``options`` to that simulator's ``default()`` unless ``options=`` is given."""
194
+ _check_keys("sim", fields_, _SIM_FIELDS)
195
+ values = dict(self._sim)
196
+ changed = dict(fields_)
197
+ if sim is not NOT_SET:
198
+ if not isinstance(sim, SimConfig):
199
+ raise ConfigError("sim", f"expected a SimConfig, got {type(sim).__name__}")
200
+ changed = {**{k: getattr(sim, k) for k in _SIM_FIELDS}, **changed}
201
+ if "simulator" in changed and changed["simulator"] != values["simulator"] and "options" not in changed:
202
+ changed["options"] = _default_options(changed["simulator"])
203
+ values.update(changed)
204
+ return self._copy(sim=values, written=self._written | {f"sim.{k}" for k in changed})
205
+
206
+ # --- resolution ------------------------------------------------------------------
207
+
208
+ def _mount(self):
209
+ """The mount: the one written, else the one that snaps the robot onto the scene's frame (``Mount()`` for a
210
+ fixed-base robot, ``MobileMount()`` for a floating-base one)."""
211
+ return self._task["mount"] if "task.mount" in self._written else snapped(self._robot)
212
+
213
+ def _resolved_control(self) -> tuple[dict[str, Any], dict[str, str]]:
214
+ """The control values and, for those the robot decided, the source ``default (robot)``. An external robot whose
215
+ gains were not written is driven by its own actuators (``NativeGains``), and an unwritten mode is the default
216
+ mode when it fits the actuators, else the first mode that does."""
217
+ values, sources = dict(self._control), {}
218
+ if not isinstance(self._robot, ExternalRobot):
219
+ return values, sources
220
+ if "control.gains" not in self._written:
221
+ values["gains"], sources["gains"] = NativeGains(), "default (robot)"
222
+ fits = NATIVE_MODES[self._robot.actuator_kind]
223
+ if "control.mode" not in self._written and fits and values["mode"] not in fits:
224
+ values["mode"], sources["mode"] = next(m for m in CONTROL_MODES if m in fits), "default (robot)"
225
+ return values, sources
226
+
227
+ def _build(self) -> tuple[list[Problem], EnvConfig | None]:
228
+ problems: list[Problem] = []
229
+ parts: dict[str, Any] = {}
230
+
231
+ def attempt(section: str, make) -> None:
232
+ try:
233
+ parts[section] = make()
234
+ except ConfigError as e:
235
+ p = e.prefixed(section)
236
+ problems.append(Problem(p.path, p.reason))
237
+ except (TypeError, ValueError, AttributeError) as e:
238
+ problems.append(Problem(section, f"{type(e).__name__}: {e}"))
239
+
240
+ attempt("robot", lambda: self._robot if isinstance(self._robot, _READY) else self._robot.arm())
241
+ attempt("control", lambda: ControlConfig(**self._resolved_control()[0]))
242
+
243
+ def task():
244
+ return TaskConfig(**{**self._task, "mount": self._mount()})
245
+
246
+ def sim():
247
+ s = dict(self._sim)
248
+ if s["options"] is NOT_SET:
249
+ raise ConfigError("options", f"simulator {s['simulator']!r} has no default options; pass options=")
250
+ return SimConfig(**s)
251
+
252
+ attempt("task", task)
253
+ attempt("sim", sim)
254
+ if problems:
255
+ return problems, None
256
+ try:
257
+ return [], EnvConfig(robot=parts["robot"], control=parts["control"], task=parts["task"], sim=parts["sim"])
258
+ except ConfigError as e:
259
+ return [Problem(e.path, e.reason)], None
260
+
261
+ def validate(self) -> list[Problem]:
262
+ """Every problem of the config as ``Problem(path, message)``, without raising. Checks the config only; what a
263
+ simulator or a task provider cannot run is reported by ``make_env``."""
264
+ return self._build()[0]
265
+
266
+ def resolve(self) -> EnvConfig:
267
+ """The frozen :class:`EnvConfig`, every value explicit. Raises one
268
+ ``ConfigError`` that lists every problem with its dotted path (``.problems`` holds them)."""
269
+ problems, cfg = self._build()
270
+ if cfg is not None:
271
+ return cfg
272
+ if len(problems) == 1:
273
+ err = ConfigError(problems[0].path, problems[0].message)
274
+ else:
275
+ lines = "\n".join(f" - {p}" for p in problems)
276
+ err = ConfigError("", f"{len(problems)} problems in the config:\n{lines}")
277
+ err.problems = tuple(problems)
278
+ raise err
279
+
280
+ def build(self) -> Any:
281
+ """``make_env(self.resolve())``: the one construction path. Imports the engine here."""
282
+ from ..envs import make_env
283
+
284
+ return make_env(self.resolve())
285
+
286
+ # --- serialization -----------------------------------------------------------------
287
+
288
+ def to_dict(self) -> dict[str, Any]:
289
+ """Every builder field as plain data, with ``defaults_version``. The record to keep with a run is ``resolve().to_dict()``."""
290
+ robot = (self._robot.to_dict() if isinstance(self._robot, _READY)
291
+ else {"kind": "chain", **{n: _jsonable(getattr(self._robot, n)) for n in self._robot.written()}})
292
+ t = self._task
293
+ task = {"provider": t["params"].provider, "params": t["params"].to_dict(), "max_episode_steps": t["max_episode_steps"],
294
+ "success_tolerance": t["success_tolerance"], "target_region": _jsonable(t["target_region"])}
295
+ task["mount"] = _jsonable(self._mount())
296
+ sim = {k: self._sim[k] for k in _SIM_FIELDS if k != "options"}
297
+ if self._sim["options"] is not NOT_SET:
298
+ sim["options"] = self._sim["options"].to_dict()
299
+ control = {"mode": self._control["mode"], "gains": _jsonable(self._control["gains"]),
300
+ "action_scale": self._control["action_scale"]}
301
+ return {"defaults_version": DEFAULTS_VERSION, "robot": robot, "control": control, "task": task, "sim": sim}
302
+
303
+ @classmethod
304
+ def from_dict(cls, d: Mapping[str, Any]) -> "BaseEnvConfig":
305
+ """Inverse of ``to_dict``. Sections and keys left out take the base's value, so a hand-written file can be short.
306
+ Warns when ``defaults_version`` differs from this package's."""
307
+ check_keys(d, set(), "", optional={"defaults_version", *_SECTIONS})
308
+ version = d.get("defaults_version", DEFAULTS_VERSION)
309
+ if version != DEFAULTS_VERSION:
310
+ warnings.warn(
311
+ f"config written with defaults version {version}, this is version {DEFAULTS_VERSION}: values it left "
312
+ "out take the new defaults", stacklevel=2,
313
+ )
314
+ cfg = cls()
315
+ pristine = cfg.to_dict()
316
+ for section in _SECTIONS:
317
+ if section in d:
318
+ given = d[section]
319
+ if not isinstance(given, Mapping):
320
+ raise ConfigError(section, f"expected a mapping, got {type(given).__name__}")
321
+ if section == "task":
322
+ given = within("task", migrate_task_dict, given)
323
+ base = dict(pristine[section])
324
+ if section == "sim":
325
+ base.pop("options") # the options of the simulator written, or its defaults
326
+ if section == "robot":
327
+ base = {} # a chain is merged onto the default chain, an arm stands alone
328
+ cfg = cfg._with_section(section, {**base, **given}, merge_chain=True)
329
+ return cfg._with_written(cfg._diff_paths())
330
+
331
+ def _diff_paths(self) -> frozenset[str]:
332
+ return frozenset(self.diff())
333
+
334
+ def _with_written(self, paths) -> "BaseEnvConfig":
335
+ keep = {w for w in paths if not w.startswith("robot.") or w[6:] in getattr(self._robot, "written", lambda: ())()}
336
+ return self._copy(written=frozenset(keep))
337
+
338
+ def _with_section(self, section: str, d: Mapping[str, Any], merge_chain: bool = False) -> "BaseEnvConfig":
339
+ """The config with ``section`` replaced by what the dict ``d`` says (validated by the section's own classes)."""
340
+ if section == "robot":
341
+ if d.get("kind", "chain") in ("parametric_arm", "external_robot"):
342
+ return self._copy(robot=within("robot", robot_from_dict, d))
343
+ check_keys(d, set(), "robot", optional={"kind", *_CHAIN_FIELDS})
344
+ if d.get("kind", "chain") != "chain":
345
+ raise ConfigError(
346
+ "robot.kind", f"unknown kind {d['kind']!r}; expected 'chain', 'parametric_arm' or 'external_robot'"
347
+ )
348
+ given = {}
349
+ for k, v in d.items():
350
+ if k == "kind":
351
+ continue
352
+ if k == "end_effector" and isinstance(v, Mapping):
353
+ v = within(f"robot.{k}", Pose.from_dict, v)
354
+ elif k == "tool" and isinstance(v, Mapping):
355
+ v = within(f"robot.{k}", ToolSpec.from_dict, v)
356
+ elif k == "gripper" and isinstance(v, Mapping):
357
+ v = within(f"robot.{k}", TwoFingerGripper.from_dict, v)
358
+ given[k] = _tuplify(v) if isinstance(v, (list, tuple)) else v
359
+ spec = Chain(**given)
360
+ return self._copy(robot=Chain(**DEFAULTS["robot"]).merge(spec) if merge_chain else spec)
361
+ if section == "control":
362
+ c = within("control", ControlConfig.from_dict, d)
363
+ return self._copy(control={k: getattr(c, k) for k in _CONTROL_FIELDS})
364
+ if section == "task":
365
+ check_keys(d, {"provider", "params", "max_episode_steps", "success_tolerance", "target_region"}, "task", {"mount"})
366
+ probe = within("task", TaskConfig.from_dict, {**d, "mount": d.get("mount", Mount().to_dict())})
367
+ task = {"params": probe.params, "max_episode_steps": probe.max_episode_steps, "success_tolerance": probe.success_tolerance,
368
+ "target_region": probe.target_region,
369
+ "mount": probe.mount}
370
+ return self._copy(task=task)
371
+ d = dict(d)
372
+ check_keys(d, set(), "sim", optional=set(_SIM_FIELDS))
373
+ full = {k: v for k, v in d.items() if k != "options"}
374
+ sim = {k: self._sim[k] for k in _SIM_FIELDS if k != "options"} | full
375
+ options = d.get("options")
376
+ if options is None:
377
+ options = _default_options(sim["simulator"])
378
+ if options is NOT_SET:
379
+ raise ConfigError("sim.options", f"simulator {sim['simulator']!r} has no default options; give options")
380
+ options = options.to_dict()
381
+ probe = within("sim", SimConfig.from_dict, {**sim, "options": options})
382
+ return self._copy(sim={k: getattr(probe, k) for k in _SIM_FIELDS})
383
+
384
+ # --- overrides ---------------------------------------------------------------------
385
+
386
+ def with_overrides(self, overrides: Mapping[str, Any] | Sequence[str]) -> "BaseEnvConfig":
387
+ """A new config with dotted-path overrides applied, with the semantics of the section calls (they accumulate).
388
+
389
+ ``overrides`` is a mapping ``{"sim.num_envs": 64, "sim.options.self_collision": True, "robot.total_length": 1.2}``
390
+ or a list of CLI strings ``["sim.num_envs=64", "robot.axes=zyy"]`` (the value is a JSON literal, or a string if
391
+ it is not one). Paths reach nested fields (``sim.options.*``, ``task.params.*``, ``control.gains.*``). Unknown
392
+ keys and sections raise ``ConfigError`` with the dotted path; writing one of ``link_length`` / ``total_length``
393
+ (or ``mass`` / ``total_mass``) clears the other; changing ``sim.simulator`` resets ``sim.options`` to that
394
+ simulator's defaults unless ``sim.options.*`` is given too. Each touched section is rebuilt and validated by
395
+ its own classes."""
396
+ if isinstance(overrides, Mapping):
397
+ items = list(overrides.items())
398
+ elif isinstance(overrides, str) or not hasattr(overrides, "__iter__"):
399
+ raise ConfigError("", "overrides must be a mapping or a list of 'path=value' strings")
400
+ else:
401
+ items = []
402
+ for o in overrides:
403
+ if not isinstance(o, str):
404
+ raise ConfigError("", f"override {o!r} is not a 'path=value' string")
405
+ items.append(_parse_override(o))
406
+ state = self.to_dict()
407
+ touched: dict[str, set[str]] = {}
408
+ # a simulator change first, so that options edits apply to the options of the new simulator
409
+ items.sort(key=lambda kv: kv[0] != "sim.simulator")
410
+ written_now: set[str] = set()
411
+ for path, value in items:
412
+ parts = str(path).split(".")
413
+ if parts[0] not in _SECTIONS:
414
+ raise ConfigError(parts[0], f"unknown section; expected one of {list(_SECTIONS)}")
415
+ if len(parts) == 1:
416
+ raise ConfigError(path, "give a field of the section (for example sim.num_envs)")
417
+ section = state[parts[0]]
418
+ if path == "sim.simulator" and value != section["simulator"]:
419
+ new = _default_options(value)
420
+ if new is NOT_SET:
421
+ if not any(p.startswith("sim.options") for p, _ in items):
422
+ raise ConfigError("sim.options", f"simulator {value!r} has no default options; give sim.options.*")
423
+ section.pop("options", None)
424
+ else:
425
+ section["options"] = new.to_dict()
426
+ self._set_path(state, parts, _jsonable(value), written_now)
427
+ touched.setdefault(parts[0], set()).add(".".join(parts[:2]))
428
+ cfg = self
429
+ for section in _SECTIONS:
430
+ if section in touched:
431
+ cfg = cfg._with_section(section, state[section])
432
+ written = set(self._written) | {w for ws in touched.values() for w in ws}
433
+ if isinstance(cfg._robot, Chain):
434
+ written = {w for w in written if not w.startswith("robot.") or w[6:] in cfg._robot.written()}
435
+ return cfg._copy(written=frozenset(written))
436
+
437
+ @staticmethod
438
+ def _set_path(state: dict, parts: list[str], value: Any, written_now: set[str]) -> None:
439
+ node, walked = state, []
440
+ for i, key in enumerate(parts[:-1]):
441
+ walked.append(key)
442
+ nxt = node.get(key) if isinstance(node, dict) else None
443
+ if not isinstance(nxt, dict):
444
+ raise ConfigError(".".join(parts[: i + 1]), "has no fields to reach into" if key in node else
445
+ f"unknown field; expected one of {sorted(node)}")
446
+ node = nxt
447
+ key, section = parts[-1], parts[0]
448
+ path = ".".join(parts)
449
+ chain_level = section == "robot" and len(parts) == 2 and node.get("kind", "chain") == "chain"
450
+ allowed = set(node) | ({*_CHAIN_FIELDS} if chain_level else set())
451
+ if key not in allowed:
452
+ raise ConfigError(path, f"unknown field; expected one of {sorted(allowed)}")
453
+ node[key] = value
454
+ if chain_level:
455
+ written_now.add(key)
456
+ for a, b in _PAIRS:
457
+ for x, y in ((a, b), (b, a)):
458
+ if key == x and y not in written_now:
459
+ node.pop(y, None)
460
+
461
+ # --- sweeps ------------------------------------------------------------------------
462
+
463
+ def sweep(self, *, paired: Mapping[str, Any] | None = None, grid: Mapping[str, Any] | None = None):
464
+ """A :class:`Family` of configs: ``paired`` axes are zipped (equal lengths), ``grid`` axes form a Cartesian
465
+ product, and the paired group multiplies with the grid. Keys are dotted paths with the semantics of
466
+ ``with_overrides``. Order: the paired group first, then the grid axes in the order given, the last one fastest.
467
+ Items whose resolved ``env_hash`` repeats are dropped (see ``Family.notes``); an invalid item raises at
468
+ expansion, naming its index and overrides."""
469
+ from .sweep import expand
470
+
471
+ return expand(self, paired, grid)
472
+
473
+ # --- files -------------------------------------------------------------------------
474
+
475
+ def dump(self, path: str | Path, format: str | None = None) -> None:
476
+ """Write ``to_dict()`` as JSON, or as YAML for ``.yaml`` / ``.yml`` (needs the ``yaml`` extra)."""
477
+ path = Path(path)
478
+ fmt = format or ("yaml" if path.suffix.lower() in (".yaml", ".yml") else "json")
479
+ if fmt == "yaml":
480
+ path.write_text(_yaml().safe_dump(self.to_dict(), sort_keys=False))
481
+ elif fmt == "json":
482
+ path.write_text(json.dumps(self.to_dict(), indent=2) + "\n")
483
+ else:
484
+ raise ConfigError("format", f"expected 'json' or 'yaml', got {fmt!r}")
485
+
486
+ @classmethod
487
+ def load(cls, path: str | Path, format: str | None = None) -> "BaseEnvConfig":
488
+ """Read what ``dump`` wrote."""
489
+ path = Path(path)
490
+ fmt = format or ("yaml" if path.suffix.lower() in (".yaml", ".yml") else "json")
491
+ if fmt == "yaml":
492
+ return cls.from_dict(_yaml().safe_load(path.read_text()))
493
+ if fmt == "json":
494
+ return cls.from_dict(json.loads(path.read_text()))
495
+ raise ConfigError("format", f"expected 'json' or 'yaml', got {fmt!r}")
496
+
497
+ # --- inspection ------------------------------------------------------------------
498
+
499
+ def _fields(self, *, resolved: bool) -> list[tuple[str, Any, str]]:
500
+ w = self._written
501
+ src = lambda path: "set" if path in w else "default" # noqa: E731
502
+ out: list[tuple[str, Any, str]] = []
503
+ if isinstance(self._robot, _READY):
504
+ out.append(("robot", self._robot, "set"))
505
+ else:
506
+ out += [(f"robot.{n}", getattr(self._robot, n), src(f"robot.{n}")) for n in self._robot.written()]
507
+ control, by_robot = self._resolved_control() if resolved else (self._control, {})
508
+ out += [(f"control.{k}", control[k], by_robot.get(k) or src(f"control.{k}")) for k in _CONTROL_FIELDS]
509
+ out.append(("task.params", self._task["params"], src("task.params")))
510
+ for k in _TASK_FIELDS:
511
+ value = self._mount() if k == "mount" and resolved else self._task[k]
512
+ out.append((f"task.{k}", value, src(f"task.{k}")))
513
+ out += [(f"sim.{k}", self._sim[k], src(f"sim.{k}")) for k in _SIM_FIELDS]
514
+ return out
515
+
516
+ def _robot_license(self) -> str | None:
517
+ """The licence of an external robot's model, if its provider reports one (``license(name)``)."""
518
+ if not isinstance(self._robot, ExternalRobot):
519
+ return None
520
+ try:
521
+ return getattr(get_robot_provider(self._robot.provider), "license")(self._robot.name) # noqa: B009
522
+ except Exception: # no such method, library missing, unknown robot: nothing to show
523
+ return None
524
+
525
+ def explain(self) -> str:
526
+ """Every field with its value and where it comes from: ``set``, ``default``, or, for an
527
+ external robot, ``default (robot)``."""
528
+ rows = self._fields(resolved=True)
529
+ license_ = self._robot_license()
530
+ if license_ is not None:
531
+ rows.insert(1, ("robot.license", license_, "provider"))
532
+ width = max(len(p) for p, _, _ in rows)
533
+ head = f"BaseEnvConfig (defaults version {DEFAULTS_VERSION})"
534
+ return "\n".join([head] + [f" {p:<{width}} {v!r} [{s}]" for p, v, s in rows])
535
+
536
+ def diff(self) -> dict[str, tuple[Any, Any]]:
537
+ """``{path: (default, value)}`` against the pristine ``BaseEnvConfig()`` of this defaults version. A field
538
+ that only one side has is ``NOT_SET`` on the other;"""
539
+ mine = {p: v for p, v, _ in self._fields(resolved=False)}
540
+ base = {p: v for p, v, _ in BaseEnvConfig()._fields(resolved=False)}
541
+ out = {}
542
+ for path in [*base, *(p for p in mine if p not in base)]:
543
+ a, b = base.get(path, NOT_SET), mine.get(path, NOT_SET)
544
+ if _norm(a) != _norm(b):
545
+ out[path] = (a, b)
546
+ return out
547
+
548
+ def __eq__(self, other: object) -> bool:
549
+ if not isinstance(other, BaseEnvConfig):
550
+ return NotImplemented
551
+ return (self._robot, self._control, self._task, self._sim) == (other._robot, other._control, other._task, other._sim)
552
+
553
+ __hash__ = None # type: ignore[assignment]
554
+
555
+ def __repr__(self) -> str:
556
+ changed = ", ".join(sorted(self._written)) or "nothing"
557
+ return f"BaseEnvConfig(defaults v{DEFAULTS_VERSION}; set: {changed})"