motrix-env-core 0.4.0__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.
- motrix_env_core/__init__.py +52 -0
- motrix_env_core/array/__init__.py +3 -0
- motrix_env_core/array/env.py +360 -0
- motrix_env_core/array_api.py +41 -0
- motrix_env_core/base.py +99 -0
- motrix_env_core/config/__init__.py +8 -0
- motrix_env_core/config/decorate.py +141 -0
- motrix_env_core/config/scene/__init__.py +114 -0
- motrix_env_core/config/scene/_utils.py +24 -0
- motrix_env_core/config/scene/actuator.py +47 -0
- motrix_env_core/config/scene/asset.py +183 -0
- motrix_env_core/config/scene/base.py +338 -0
- motrix_env_core/config/scene/compiler.py +18 -0
- motrix_env_core/config/scene/geometry.py +43 -0
- motrix_env_core/config/scene/light.py +25 -0
- motrix_env_core/config/scene/mjcf.py +10 -0
- motrix_env_core/config/scene/sensor.py +125 -0
- motrix_env_core/config/scene/terrain.py +518 -0
- motrix_env_core/config/scene/urdf.py +84 -0
- motrix_env_core/config/scene/validation.py +73 -0
- motrix_env_core/config/sim.py +30 -0
- motrix_env_core/config/sim_reset.py +42 -0
- motrix_env_core/direct/__init__.py +7 -0
- motrix_env_core/direct/env.py +75 -0
- motrix_env_core/direct/reward.py +71 -0
- motrix_env_core/input/__init__.py +26 -0
- motrix_env_core/input/bindings.py +204 -0
- motrix_env_core/input/command.py +46 -0
- motrix_env_core/input/device.py +57 -0
- motrix_env_core/manager/__init__.py +72 -0
- motrix_env_core/manager/math/__init__.py +8 -0
- motrix_env_core/manager/math/quaternion.py +15 -0
- motrix_env_core/math/__init__.py +6 -0
- motrix_env_core/math/quaternion.py +340 -0
- motrix_env_core/math/utils.py +53 -0
- motrix_env_core/mdp/__init__.py +4 -0
- motrix_env_core/mdp/action.py +215 -0
- motrix_env_core/mdp/action_space.py +143 -0
- motrix_env_core/mdp/noise.py +36 -0
- motrix_env_core/mdp/observations.py +260 -0
- motrix_env_core/mdp/rewards.py +133 -0
- motrix_env_core/mdp/state.py +23 -0
- motrix_env_core/mdp/terminations.py +85 -0
- motrix_env_core/mdp/terrain.py +77 -0
- motrix_env_core/numba/__init__.py +18 -0
- motrix_env_core/numba/fingerprint.py +84 -0
- motrix_env_core/numba/kernel.py +142 -0
- motrix_env_core/numba/kernel_data/__init__.py +64 -0
- motrix_env_core/numba/kernel_data/canonical.py +28 -0
- motrix_env_core/numba/kernel_data/lowering.py +433 -0
- motrix_env_core/numba/kernel_data/map.py +115 -0
- motrix_env_core/numba/kernel_data/methods.py +51 -0
- motrix_env_core/numba/kernel_data/tree.py +324 -0
- motrix_env_core/numba/manager/__init__.py +4 -0
- motrix_env_core/numba/manager/actions.py +113 -0
- motrix_env_core/numba/manager/commands.py +97 -0
- motrix_env_core/numba/manager/compiler/__init__.py +19 -0
- motrix_env_core/numba/manager/compiler/cache.py +106 -0
- motrix_env_core/numba/manager/compiler/codegen.py +202 -0
- motrix_env_core/numba/manager/compiler/compiler.py +1023 -0
- motrix_env_core/numba/manager/compiler/fingerprint.py +18 -0
- motrix_env_core/numba/manager/compiler/plan.py +112 -0
- motrix_env_core/numba/manager/compiler/program.py +51 -0
- motrix_env_core/numba/manager/context.py +80 -0
- motrix_env_core/numba/manager/dispatch.py +27 -0
- motrix_env_core/numba/manager/env.py +952 -0
- motrix_env_core/numba/manager/metrics.py +95 -0
- motrix_env_core/numba/manager/observations.py +146 -0
- motrix_env_core/numba/manager/rand.py +101 -0
- motrix_env_core/numba/manager/rewards.py +66 -0
- motrix_env_core/numba/manager/sim_reset.py +112 -0
- motrix_env_core/numba/manager/terminations.py +107 -0
- motrix_env_core/numba/manager/terms.py +68 -0
- motrix_env_core/numba/math/__init__.py +4 -0
- motrix_env_core/numba/math/quaternion.py +175 -0
- motrix_env_core/numba/program.py +18 -0
- motrix_env_core/numba/threading.py +59 -0
- motrix_env_core/perf.py +292 -0
- motrix_env_core/py.typed +0 -0
- motrix_env_core/registry.py +464 -0
- motrix_env_core/renderer.py +150 -0
- motrix_env_core/sim/__init__.py +122 -0
- motrix_env_core/sim/backend.py +218 -0
- motrix_env_core/sim/body.py +175 -0
- motrix_env_core/sim/config.py +35 -0
- motrix_env_core/sim/model.py +398 -0
- motrix_env_core/sim/read.py +513 -0
- motrix_env_core/sim/registry.py +127 -0
- motrix_env_core/sim/write.py +354 -0
- motrix_env_core/torch/reward.py +59 -0
- motrix_env_core-0.4.0.dist-info/METADATA +92 -0
- motrix_env_core-0.4.0.dist-info/RECORD +94 -0
- motrix_env_core-0.4.0.dist-info/WHEEL +4 -0
- motrix_env_core-0.4.0.dist-info/licenses/LICENSE +204 -0
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Copyright Motphys Technology Co., Ltd. 2025, 2026
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
"""Public API of the environment framework.
|
|
5
|
+
|
|
6
|
+
Importing this package never imports a simulator. Simulator backends live in
|
|
7
|
+
their own distributions (``motrix-env-motrixsim``, ``motrix-env-mujoco``) and
|
|
8
|
+
register through the ``motrix_env.sim_backends`` entry-point group; the
|
|
9
|
+
backend-neutral boundary is :mod:`motrix_env_core.sim` and its registry is
|
|
10
|
+
:mod:`motrix_env_core.sim.registry`. The torch-tensor frontend for MotrixSim
|
|
11
|
+
lives in :mod:`motrix_env_motrixsim.torch_env`, not here.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from motrix_env_core import registry
|
|
15
|
+
from motrix_env_core.base import ABEnv, EnvCfg, ObsSpace, SimCfg
|
|
16
|
+
from motrix_env_core.config import configclass
|
|
17
|
+
from motrix_env_core.config.scene import SceneCfg
|
|
18
|
+
from motrix_env_core.input import (
|
|
19
|
+
BoundedGamePadPlanarVelocityBinding,
|
|
20
|
+
CommandBinding,
|
|
21
|
+
ConstantPlanarVelocityBinding,
|
|
22
|
+
GamePadDevice,
|
|
23
|
+
GamePadPlanarVelocityBinding,
|
|
24
|
+
InputDevice,
|
|
25
|
+
KeyboardDevice,
|
|
26
|
+
KeyboardPlanarVelocityBinding,
|
|
27
|
+
PlanarVelocityCommand,
|
|
28
|
+
)
|
|
29
|
+
from motrix_env_core.perf import Perf, PerfNode, perf_root, perf_scope
|
|
30
|
+
|
|
31
|
+
__all__ = [
|
|
32
|
+
"ABEnv",
|
|
33
|
+
"BoundedGamePadPlanarVelocityBinding",
|
|
34
|
+
"CommandBinding",
|
|
35
|
+
"ConstantPlanarVelocityBinding",
|
|
36
|
+
"EnvCfg",
|
|
37
|
+
"GamePadDevice",
|
|
38
|
+
"GamePadPlanarVelocityBinding",
|
|
39
|
+
"InputDevice",
|
|
40
|
+
"KeyboardDevice",
|
|
41
|
+
"KeyboardPlanarVelocityBinding",
|
|
42
|
+
"ObsSpace",
|
|
43
|
+
"Perf",
|
|
44
|
+
"PerfNode",
|
|
45
|
+
"PlanarVelocityCommand",
|
|
46
|
+
"SceneCfg",
|
|
47
|
+
"SimCfg",
|
|
48
|
+
"configclass",
|
|
49
|
+
"perf_root",
|
|
50
|
+
"perf_scope",
|
|
51
|
+
"registry",
|
|
52
|
+
]
|
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
# Copyright Motphys Technology Co., Ltd. 2025, 2026
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
import abc
|
|
5
|
+
import dataclasses
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from typing import Generic, TypeVar
|
|
8
|
+
|
|
9
|
+
import gymnasium as gym
|
|
10
|
+
import numpy as np
|
|
11
|
+
|
|
12
|
+
from motrix_env_core.base import ABEnv, EnvCfg, ObsSpace
|
|
13
|
+
from motrix_env_core.perf import Perf, perf_root
|
|
14
|
+
from motrix_env_core.sim.backend import (
|
|
15
|
+
RenderConfig,
|
|
16
|
+
SimRenderer,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
# The concrete config type an ArrayEnv subclass consumes. Subclasses parametrize
|
|
20
|
+
# via ``ArrayEnv[MyCfg]`` so ``self.cfg`` is typed as ``MyCfg`` (IDE hint +
|
|
21
|
+
# pyright narrowing). Unparametrized subclasses fall back to ``EnvCfg``
|
|
22
|
+
# (back-compat).
|
|
23
|
+
EnvCfgType = TypeVar("EnvCfgType", bound=EnvCfg)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass
|
|
27
|
+
class NpObs:
|
|
28
|
+
policy: np.ndarray
|
|
29
|
+
value: np.ndarray | None = None
|
|
30
|
+
|
|
31
|
+
@property
|
|
32
|
+
def value_or_policy(self) -> np.ndarray:
|
|
33
|
+
return self.policy if self.value is None else self.value
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@dataclass
|
|
37
|
+
class FinalObs:
|
|
38
|
+
"""Owned pre-reset observations of the current transition's truncated rows.
|
|
39
|
+
|
|
40
|
+
Rows in ``obs`` align with ``env_ids``. Arrays remain valid across steps;
|
|
41
|
+
consumers must treat them as read-only. ``obs.value`` stays optional.
|
|
42
|
+
"""
|
|
43
|
+
|
|
44
|
+
env_ids: np.ndarray
|
|
45
|
+
obs: NpObs
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass
|
|
49
|
+
class ArrayEnvState:
|
|
50
|
+
obs: NpObs
|
|
51
|
+
reward: np.ndarray
|
|
52
|
+
terminated: np.ndarray
|
|
53
|
+
truncated: np.ndarray
|
|
54
|
+
episode_steps: np.ndarray
|
|
55
|
+
# Per-term reward breakdown for the latest transition: term name to a
|
|
56
|
+
# ``(num_envs,)`` array. Freshly written every transition; empty when the
|
|
57
|
+
# environment does not decompose its reward.
|
|
58
|
+
reward_terms: dict[str, np.ndarray] = dataclasses.field(default_factory=dict)
|
|
59
|
+
# Live diagnostics view: per-environment quantities stay unreduced as
|
|
60
|
+
# ``(num_envs,)`` arrays and are views into manager buffers that kernels
|
|
61
|
+
# overwrite every step; batch-level gauges are scalars. Values always
|
|
62
|
+
# reflect the latest step: retain values across steps through
|
|
63
|
+
# :meth:`process_metrics`, which returns a fresh dict of reduced scalars.
|
|
64
|
+
metrics: dict[str, float | np.ndarray] = dataclasses.field(default_factory=dict)
|
|
65
|
+
# None when no row truncated or the implementation does not capture finals.
|
|
66
|
+
final_obs: FinalObs | None = None
|
|
67
|
+
|
|
68
|
+
@property
|
|
69
|
+
def done(self) -> np.ndarray:
|
|
70
|
+
"""
|
|
71
|
+
Check if the environment is done.
|
|
72
|
+
"""
|
|
73
|
+
return np.logical_or(self.terminated, self.truncated)
|
|
74
|
+
|
|
75
|
+
def replace(self, **updates) -> "ArrayEnvState":
|
|
76
|
+
return dataclasses.replace(self, **updates)
|
|
77
|
+
|
|
78
|
+
def process_metrics(self) -> dict[str, float]:
|
|
79
|
+
"""Reduce per-environment metrics into batch-level scalar floats.
|
|
80
|
+
|
|
81
|
+
Per-env arrays are reduced with their mean (bool arrays become trigger
|
|
82
|
+
rates); scalars pass through. The result is a fresh, small dict that is
|
|
83
|
+
safe to retain across steps, unlike the raw ``metrics`` arrays.
|
|
84
|
+
"""
|
|
85
|
+
return {
|
|
86
|
+
name: float(np.mean(value)) if isinstance(value, np.ndarray) else float(value)
|
|
87
|
+
for name, value in self.metrics.items()
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
def validate(self):
|
|
91
|
+
num_envs = self.obs.policy.shape[0]
|
|
92
|
+
assert self.obs.policy.shape[0] == num_envs, self.obs.policy.shape
|
|
93
|
+
if self.obs.value is not None:
|
|
94
|
+
assert self.obs.value.shape[0] == num_envs, self.obs.value.shape
|
|
95
|
+
assert self.reward.shape == (num_envs,), self.reward.shape
|
|
96
|
+
assert self.terminated.shape == (num_envs,), self.terminated.shape
|
|
97
|
+
assert self.truncated.shape == (num_envs,), self.truncated.shape
|
|
98
|
+
assert self.episode_steps.shape == (num_envs,), self.episode_steps.shape
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _as_obs_space(space: gym.Space | ObsSpace) -> ObsSpace:
|
|
102
|
+
if isinstance(space, ObsSpace):
|
|
103
|
+
return space
|
|
104
|
+
assert isinstance(space, gym.spaces.Box)
|
|
105
|
+
return ObsSpace(policy=space)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def _as_obs(obs: NpObs | np.ndarray) -> NpObs:
|
|
109
|
+
if isinstance(obs, NpObs):
|
|
110
|
+
return obs
|
|
111
|
+
assert isinstance(obs, np.ndarray)
|
|
112
|
+
return NpObs(policy=obs)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
class ArrayEnv(ABEnv, Generic[EnvCfgType]):
|
|
116
|
+
"""Simulator-agnostic NumPy frontend environment lifecycle.
|
|
117
|
+
|
|
118
|
+
``ArrayEnv`` owns the step / auto-reset / truncation lifecycle shared by
|
|
119
|
+
NumPy-frontend environments. It is deliberately free of simulator-state
|
|
120
|
+
concepts: subclasses address simulator rows themselves inside the reset
|
|
121
|
+
hooks, so the frontend only ever speaks in environment indices.
|
|
122
|
+
"""
|
|
123
|
+
|
|
124
|
+
_cfg: EnvCfgType
|
|
125
|
+
_state: ArrayEnvState = None
|
|
126
|
+
_render_spacing: float
|
|
127
|
+
|
|
128
|
+
def __init__(self, cfg: EnvCfgType, num_envs: int = 1):
|
|
129
|
+
self._cfg = cfg
|
|
130
|
+
self._num_envs = num_envs
|
|
131
|
+
self.perf = Perf()
|
|
132
|
+
if cfg.scene is None:
|
|
133
|
+
raise ValueError("EnvCfg.scene must be configured")
|
|
134
|
+
self._render_spacing = cfg.render_spacing
|
|
135
|
+
|
|
136
|
+
@property
|
|
137
|
+
def state(self) -> ArrayEnvState:
|
|
138
|
+
"""
|
|
139
|
+
Get the current environment state
|
|
140
|
+
"""
|
|
141
|
+
return self._state
|
|
142
|
+
|
|
143
|
+
@property
|
|
144
|
+
def cfg(self) -> EnvCfgType:
|
|
145
|
+
"""
|
|
146
|
+
Get the environment configuration
|
|
147
|
+
"""
|
|
148
|
+
return self._cfg
|
|
149
|
+
|
|
150
|
+
@property
|
|
151
|
+
def render_spacing(self) -> float:
|
|
152
|
+
"""
|
|
153
|
+
Get the render spacing, with which the multi-envs will be rendered seperately in grid
|
|
154
|
+
"""
|
|
155
|
+
return self._render_spacing
|
|
156
|
+
|
|
157
|
+
@property
|
|
158
|
+
def num_envs(self) -> int:
|
|
159
|
+
return self._num_envs
|
|
160
|
+
|
|
161
|
+
def init_state(self) -> ArrayEnvState:
|
|
162
|
+
"""
|
|
163
|
+
Create a new environment state
|
|
164
|
+
"""
|
|
165
|
+
obs = self._zeros_obs(self.observation_space)
|
|
166
|
+
reward = np.zeros((self._num_envs,), dtype=np.float32)
|
|
167
|
+
terminated = np.ones((self._num_envs,), dtype=bool)
|
|
168
|
+
truncated = np.zeros((self._num_envs,), dtype=bool)
|
|
169
|
+
episode_steps = np.zeros((self._num_envs,), dtype=np.uint64)
|
|
170
|
+
self._state = self._new_state(obs, reward, terminated, truncated, episode_steps)
|
|
171
|
+
self._reset_done_envs()
|
|
172
|
+
with self.perf.scope("observation"):
|
|
173
|
+
self._state = self.compute_observation(self._state)
|
|
174
|
+
self._state = self._state.replace(obs=_as_obs(self._state.obs))
|
|
175
|
+
self._state.validate()
|
|
176
|
+
return self._state
|
|
177
|
+
|
|
178
|
+
def _new_state(
|
|
179
|
+
self,
|
|
180
|
+
obs: NpObs,
|
|
181
|
+
reward: np.ndarray,
|
|
182
|
+
terminated: np.ndarray,
|
|
183
|
+
truncated: np.ndarray,
|
|
184
|
+
episode_steps: np.ndarray,
|
|
185
|
+
) -> ArrayEnvState:
|
|
186
|
+
"""Assemble the environment state; subclasses add simulator-owned fields."""
|
|
187
|
+
return ArrayEnvState(
|
|
188
|
+
obs=obs,
|
|
189
|
+
reward=reward,
|
|
190
|
+
terminated=terminated,
|
|
191
|
+
truncated=truncated,
|
|
192
|
+
episode_steps=episode_steps,
|
|
193
|
+
)
|
|
194
|
+
|
|
195
|
+
@property
|
|
196
|
+
def policy_observation_space(self) -> gym.spaces.Box:
|
|
197
|
+
return _as_obs_space(self.observation_space).policy
|
|
198
|
+
|
|
199
|
+
@property
|
|
200
|
+
def value_observation_space(self) -> gym.spaces.Box:
|
|
201
|
+
return _as_obs_space(self.observation_space).value_or_policy
|
|
202
|
+
|
|
203
|
+
@property
|
|
204
|
+
def has_value_observation(self) -> bool:
|
|
205
|
+
return _as_obs_space(self.observation_space).value is not None
|
|
206
|
+
|
|
207
|
+
def _zeros_box(self, space: gym.spaces.Box) -> np.ndarray:
|
|
208
|
+
return np.zeros((self._num_envs, *space.shape), dtype=space.dtype)
|
|
209
|
+
|
|
210
|
+
def _zeros_obs(self, space: gym.Space | ObsSpace) -> NpObs:
|
|
211
|
+
obs_space = _as_obs_space(space)
|
|
212
|
+
value = None if obs_space.value is None else self._zeros_box(obs_space.value)
|
|
213
|
+
return NpObs(policy=self._zeros_box(obs_space.policy), value=value)
|
|
214
|
+
|
|
215
|
+
def _assign_obs(self, dst: NpObs, mask: np.ndarray, src: NpObs | np.ndarray):
|
|
216
|
+
src = _as_obs(src)
|
|
217
|
+
dst.policy[mask] = src.policy
|
|
218
|
+
if dst.value is not None:
|
|
219
|
+
assert src.value is not None
|
|
220
|
+
dst.value[mask] = src.value
|
|
221
|
+
else:
|
|
222
|
+
assert src.value is None
|
|
223
|
+
|
|
224
|
+
def _reset_done_envs(self) -> None:
|
|
225
|
+
"""
|
|
226
|
+
Reset the environments that are done
|
|
227
|
+
"""
|
|
228
|
+
state = self._state
|
|
229
|
+
with self.perf.scope("done_mask"):
|
|
230
|
+
done = state.done
|
|
231
|
+
assert done.shape == (self._num_envs,)
|
|
232
|
+
has_done = np.any(done)
|
|
233
|
+
if not has_done:
|
|
234
|
+
return
|
|
235
|
+
|
|
236
|
+
with self.perf.scope("select_done"):
|
|
237
|
+
np.putmask(state.episode_steps, done, 0)
|
|
238
|
+
env_ids = np.flatnonzero(done)
|
|
239
|
+
with self.perf.scope("reset_envs"):
|
|
240
|
+
self.reset(env_ids)
|
|
241
|
+
|
|
242
|
+
@abc.abstractmethod
|
|
243
|
+
def reset(self, env_ids: np.ndarray) -> None:
|
|
244
|
+
"""Write reset rows for the selected environments.
|
|
245
|
+
|
|
246
|
+
Subclasses address their simulator's rows themselves. Observation
|
|
247
|
+
generation is deferred until :meth:`compute_observation`, after reset
|
|
248
|
+
writes have completed.
|
|
249
|
+
"""
|
|
250
|
+
|
|
251
|
+
def _capture_final_obs(self, env_ids: np.ndarray) -> FinalObs | None:
|
|
252
|
+
"""Capture truncated rows before reset; default implementation is unsupported.
|
|
253
|
+
|
|
254
|
+
Called after transition and truncation updates, before any reset write.
|
|
255
|
+
Implementations must leave normal observations and task state unchanged
|
|
256
|
+
and return owned row arrays, without advancing observation history.
|
|
257
|
+
"""
|
|
258
|
+
return None
|
|
259
|
+
|
|
260
|
+
def _max_episode_steps(self) -> int | None:
|
|
261
|
+
return self._cfg.max_episode_steps
|
|
262
|
+
|
|
263
|
+
def _update_truncate(self):
|
|
264
|
+
"""
|
|
265
|
+
Truncate the environments that have reached max episode length
|
|
266
|
+
"""
|
|
267
|
+
max_episode_steps = self._max_episode_steps()
|
|
268
|
+
if not max_episode_steps:
|
|
269
|
+
return
|
|
270
|
+
self._state.truncated = self._state.episode_steps >= max_episode_steps
|
|
271
|
+
|
|
272
|
+
@abc.abstractmethod
|
|
273
|
+
def create_renderer(self, config: RenderConfig) -> SimRenderer:
|
|
274
|
+
"""Create the backend-owned renderer bound to this environment."""
|
|
275
|
+
|
|
276
|
+
@abc.abstractmethod
|
|
277
|
+
def apply_action(self, actions: np.ndarray, state: ArrayEnvState) -> ArrayEnvState:
|
|
278
|
+
"""
|
|
279
|
+
Apply the action to the environment
|
|
280
|
+
|
|
281
|
+
Args:
|
|
282
|
+
actions (np.ndarray): The actions to apply
|
|
283
|
+
state (ArrayEnvState): The environment state to apply the actions.
|
|
284
|
+
"""
|
|
285
|
+
|
|
286
|
+
@abc.abstractmethod
|
|
287
|
+
def compute_transition(self, state: ArrayEnvState) -> ArrayEnvState:
|
|
288
|
+
"""
|
|
289
|
+
Update the environment state after physics step
|
|
290
|
+
|
|
291
|
+
This is the only full simulator-data refresh point of a step: concrete
|
|
292
|
+
environments execute their whole read program here before deriving
|
|
293
|
+
reward, termination, and metrics. It must not write ``state.obs`` —
|
|
294
|
+
observations belong to :meth:`compute_observation`.
|
|
295
|
+
|
|
296
|
+
Args:
|
|
297
|
+
state (ArrayEnvState): The environment state to update
|
|
298
|
+
"""
|
|
299
|
+
|
|
300
|
+
@abc.abstractmethod
|
|
301
|
+
def physics_step(self):
|
|
302
|
+
"""Advance the simulator by the configured substeps."""
|
|
303
|
+
|
|
304
|
+
def _prev_physics_step(self):
|
|
305
|
+
if self._state.final_obs is not None:
|
|
306
|
+
self._state = self._state.replace(final_obs=None)
|
|
307
|
+
state = self._state
|
|
308
|
+
state.reward.fill(0.0)
|
|
309
|
+
state.terminated.fill(False)
|
|
310
|
+
state.truncated.fill(False)
|
|
311
|
+
|
|
312
|
+
def compute_observation(self, state: ArrayEnvState) -> ArrayEnvState:
|
|
313
|
+
"""Compute observations for all environments after reset.
|
|
314
|
+
|
|
315
|
+
Called once after the first reset of :meth:`init_state` and once per
|
|
316
|
+
:meth:`step` after episode bookkeeping and auto-reset. Implementations
|
|
317
|
+
must purely construct the observation from the simulator data already
|
|
318
|
+
refreshed by :meth:`compute_transition` (whole batch) and reset
|
|
319
|
+
(selected rows) without executing further reads. The default preserves
|
|
320
|
+
observations already present in ``state``.
|
|
321
|
+
"""
|
|
322
|
+
return state
|
|
323
|
+
|
|
324
|
+
@perf_root("step")
|
|
325
|
+
def step(self, actions: np.ndarray) -> ArrayEnvState:
|
|
326
|
+
"""Advance one control step.
|
|
327
|
+
|
|
328
|
+
Timing: ``apply_action`` -> ``physics_step`` -> ``compute_transition``
|
|
329
|
+
(the only full simulator-data refresh) -> episode bookkeeping ->
|
|
330
|
+
optional pre-reset ``final_obs`` capture for truncated rows ->
|
|
331
|
+
``reset(env_ids)`` for done rows (may refresh selected rows) ->
|
|
332
|
+
``compute_observation`` (whole batch, pure construction).
|
|
333
|
+
"""
|
|
334
|
+
if self._state is None:
|
|
335
|
+
with self.perf.scope("init_state"):
|
|
336
|
+
self.init_state()
|
|
337
|
+
|
|
338
|
+
self._prev_physics_step()
|
|
339
|
+
with self.perf.scope("apply_action"):
|
|
340
|
+
self._state = self.apply_action(actions, self._state)
|
|
341
|
+
assert self._state is not None, "apply_action must return a valid environment state"
|
|
342
|
+
with self.perf.scope("physics"):
|
|
343
|
+
self.physics_step()
|
|
344
|
+
with self.perf.scope("transition"):
|
|
345
|
+
self._state = self.compute_transition(self._state)
|
|
346
|
+
self._state.episode_steps += 1
|
|
347
|
+
self._update_truncate()
|
|
348
|
+
trunc_ids = np.flatnonzero(self._state.truncated)
|
|
349
|
+
if trunc_ids.size:
|
|
350
|
+
with self.perf.scope("final_obs"):
|
|
351
|
+
self._state = self._state.replace(final_obs=self._capture_final_obs(trunc_ids))
|
|
352
|
+
with self.perf.scope("reset"):
|
|
353
|
+
self._reset_done_envs()
|
|
354
|
+
with self.perf.scope("observation"):
|
|
355
|
+
self._state = self.compute_observation(self._state)
|
|
356
|
+
self._state = self._state.replace(obs=_as_obs(self._state.obs))
|
|
357
|
+
return self._state
|
|
358
|
+
|
|
359
|
+
|
|
360
|
+
__all__ = ["ArrayEnv", "ArrayEnvState", "EnvCfgType", "FinalObs", "NpObs"]
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Copyright Motphys Technology Co., Ltd. 2025, 2026
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
"""Backend-neutral array types and operations shared across runtimes."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from types import ModuleType
|
|
9
|
+
from typing import Any, TypeAlias, TypeGuard, Union
|
|
10
|
+
|
|
11
|
+
import numpy as np
|
|
12
|
+
import numpy.typing as npt
|
|
13
|
+
from array_api_compat import array_namespace as _array_namespace
|
|
14
|
+
from array_api_compat import is_numpy_array, is_torch_array
|
|
15
|
+
|
|
16
|
+
Array: TypeAlias = Union[npt.NDArray[Any], "torch.Tensor"] # noqa: F821
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def array_namespace(*arrays: Array) -> ModuleType:
|
|
20
|
+
"""Return the NumPy or Torch Array API namespace shared by ``arrays``."""
|
|
21
|
+
|
|
22
|
+
for array in arrays:
|
|
23
|
+
if not is_array(array):
|
|
24
|
+
raise TypeError(
|
|
25
|
+
f"array_namespace only supports NumPy arrays and Torch tensors, got {type(array).__name__}."
|
|
26
|
+
)
|
|
27
|
+
|
|
28
|
+
return _array_namespace(*arrays)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def is_array(value: object) -> TypeGuard[Array]:
|
|
32
|
+
"""Return whether ``value`` is a supported NumPy array or Torch tensor."""
|
|
33
|
+
|
|
34
|
+
return (is_numpy_array(value) and isinstance(value, np.ndarray)) or is_torch_array(value)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
__all__ = [
|
|
38
|
+
"Array",
|
|
39
|
+
"array_namespace",
|
|
40
|
+
"is_array",
|
|
41
|
+
]
|
motrix_env_core/base.py
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# Copyright Motphys Technology Co., Ltd. 2025, 2026
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
import abc
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
|
|
7
|
+
import gymnasium as gym
|
|
8
|
+
|
|
9
|
+
from motrix_env_core.config import configclass
|
|
10
|
+
from motrix_env_core.config.scene import SceneCfg, validate_scene_cfg
|
|
11
|
+
from motrix_env_core.config.sim import SimCfg
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@dataclass(frozen=True)
|
|
15
|
+
class ObsSpace:
|
|
16
|
+
policy: gym.spaces.Box
|
|
17
|
+
value: gym.spaces.Box | None = None
|
|
18
|
+
|
|
19
|
+
@property
|
|
20
|
+
def value_or_policy(self) -> gym.spaces.Box:
|
|
21
|
+
return self.policy if self.value is None else self.value
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@configclass
|
|
25
|
+
class EnvCfg:
|
|
26
|
+
"""
|
|
27
|
+
Config for the environment
|
|
28
|
+
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
scene: SceneCfg | None = None
|
|
32
|
+
sim: SimCfg = SimCfg()
|
|
33
|
+
max_episode_seconds: float = None
|
|
34
|
+
ctrl_dt: float = 0.01
|
|
35
|
+
render_spacing: float = 1.0
|
|
36
|
+
|
|
37
|
+
@property
|
|
38
|
+
def max_episode_steps(self) -> int | None:
|
|
39
|
+
"""
|
|
40
|
+
return the max episode steps
|
|
41
|
+
"""
|
|
42
|
+
if self.max_episode_seconds is None:
|
|
43
|
+
return None
|
|
44
|
+
return int(self.max_episode_seconds / self.ctrl_dt)
|
|
45
|
+
|
|
46
|
+
@property
|
|
47
|
+
def sim_substeps(self) -> int:
|
|
48
|
+
"""
|
|
49
|
+
return the number of simulation steps per control step
|
|
50
|
+
"""
|
|
51
|
+
return int(round(self.ctrl_dt / self.sim.dt))
|
|
52
|
+
|
|
53
|
+
def validate(self):
|
|
54
|
+
"""
|
|
55
|
+
validate the config
|
|
56
|
+
"""
|
|
57
|
+
self.sim.validate()
|
|
58
|
+
if self.sim.dt > self.ctrl_dt:
|
|
59
|
+
raise ValueError("sim.dt must be less than or equal to ctrl_dt")
|
|
60
|
+
if self.scene is None:
|
|
61
|
+
raise ValueError("EnvCfg.scene must be configured")
|
|
62
|
+
validate_scene_cfg(self.scene)
|
|
63
|
+
|
|
64
|
+
def for_play(self) -> "EnvCfg":
|
|
65
|
+
"""Return the config variant used for play/eval rollouts.
|
|
66
|
+
|
|
67
|
+
The default is mode-agnostic (play behaves exactly like train). Envs
|
|
68
|
+
whose play behavior differs override this to return a modified copy
|
|
69
|
+
(e.g. no episode cap, deterministic start, disabled curriculum/noise).
|
|
70
|
+
Keeping the difference on the config makes it the single source of
|
|
71
|
+
truth and keeps the environment itself unaware of any runtime "mode".
|
|
72
|
+
"""
|
|
73
|
+
return self
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
class ABEnv(abc.ABC):
|
|
77
|
+
@property
|
|
78
|
+
@abc.abstractmethod
|
|
79
|
+
def num_envs(self) -> int:
|
|
80
|
+
"""
|
|
81
|
+
return the size of the env if it is vectorized
|
|
82
|
+
"""
|
|
83
|
+
|
|
84
|
+
@property
|
|
85
|
+
@abc.abstractmethod
|
|
86
|
+
def cfg(self) -> EnvCfg:
|
|
87
|
+
"""
|
|
88
|
+
The configuration of the environment
|
|
89
|
+
"""
|
|
90
|
+
|
|
91
|
+
@property
|
|
92
|
+
@abc.abstractmethod
|
|
93
|
+
def observation_space(self) -> gym.Space | ObsSpace:
|
|
94
|
+
"""Observation space"""
|
|
95
|
+
|
|
96
|
+
@property
|
|
97
|
+
@abc.abstractmethod
|
|
98
|
+
def action_space(self) -> gym.Space:
|
|
99
|
+
"""Action space"""
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Copyright Motphys Technology Co., Ltd. 2025, 2026
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
from motrix_env_core.config.decorate import configclass
|
|
5
|
+
from motrix_env_core.config.sim import SimCfg
|
|
6
|
+
from motrix_env_core.config.sim_reset import ManagerResetCfg, ResetTermCfg
|
|
7
|
+
|
|
8
|
+
__all__ = ["SimCfg", "ManagerResetCfg", "ResetTermCfg", "configclass"]
|