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.
- robotenv/__init__.py +21 -0
- robotenv/_canon.py +136 -0
- robotenv/config/__init__.py +93 -0
- robotenv/config/base_env.py +557 -0
- robotenv/config/control.py +161 -0
- robotenv/config/defaults.py +29 -0
- robotenv/config/env.py +107 -0
- robotenv/config/kinematics.py +121 -0
- robotenv/config/mount.py +172 -0
- robotenv/config/providers.py +171 -0
- robotenv/config/robot_providers.py +140 -0
- robotenv/config/sim.py +152 -0
- robotenv/config/specs.py +111 -0
- robotenv/config/sweep.py +100 -0
- robotenv/config/task.py +183 -0
- robotenv/envs/__init__.py +34 -0
- robotenv/envs/spaces.py +38 -0
- robotenv/errors.py +35 -0
- robotenv/robot/__init__.py +30 -0
- robotenv/robot/arm.py +319 -0
- robotenv/robot/external.py +234 -0
- robotenv/robot/generators.py +138 -0
- robotenv/robot/gripper.py +82 -0
- robotenv/robot/pose.py +49 -0
- robotenv/robot/providers/__init__.py +5 -0
- robotenv/robot/providers/menagerie/__init__.py +127 -0
- robotenv/robot/providers/menagerie/_describe.py +130 -0
- robotenv/robot/providers/menagerie/cards.json +37 -0
- robotenv/simulators/__init__.py +51 -0
- robotenv/simulators/base.py +70 -0
- robotenv/simulators/mujoco/__init__.py +38 -0
- robotenv/simulators/mujoco/arm_spec.py +137 -0
- robotenv/simulators/mujoco/compile.py +242 -0
- robotenv/simulators/mujoco/env.py +257 -0
- robotenv/simulators/mujoco/external.py +443 -0
- robotenv/simulators/mujoco/mount.py +65 -0
- robotenv/simulators/mujoco/render.py +158 -0
- robotenv/simulators/mujoco/scenes.py +35 -0
- robotenv/simulators/mujoco/sim.py +174 -0
- robotenv/simulators/warp/__init__.py +100 -0
- robotenv/simulators/warp/env.py +235 -0
- robotenv/simulators/warp/sim.py +332 -0
- robotenv/tasks/__init__.py +10 -0
- robotenv/tasks/base.py +147 -0
- robotenv/tasks/empty/__init__.py +42 -0
- robotenv/tasks/empty/params.py +33 -0
- robotenv/tasks/empty/task.py +27 -0
- robotenv/tasks/robosuite/__init__.py +133 -0
- robotenv/tasks/robosuite/_compat.py +165 -0
- robotenv/tasks/robosuite/_introspect.py +65 -0
- robotenv/tasks/robosuite/params.py +152 -0
- robotenv/tasks/robosuite/scene.py +140 -0
- robotenv/tasks/robosuite/task.py +145 -0
- robotenv/viz/__init__.py +22 -0
- robotenv/viz/_deps.py +16 -0
- robotenv/viz/camera.py +98 -0
- robotenv/viz/clip.py +180 -0
- robotenv/viz/frames.py +93 -0
- robotenv/viz/record.py +141 -0
- robotenv-0.2.1.dist-info/METADATA +136 -0
- robotenv-0.2.1.dist-info/RECORD +63 -0
- robotenv-0.2.1.dist-info/WHEEL +4 -0
- 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})"
|