embodichain.learning.rl.policy_evaluation

embodichain.learning.rl.policy_evaluation#

Policy evaluation configuration for embodichain eval-policy.

Classes:

`MotionProfile`	DexSim Policy Spec and report metadata built by one provider.
`MotionProfileRequest`	Checkpoint, configs, and runtime choices supplied to a provider.
`PolicyViewerCameraCfg`	Configure planar tracking in the native policy Viewer.

Functions:

`build_motion_profile`(name, request)	Build one profile with its registered provider.
`register_motion_profile`(name, provider)	Register a Motion Profile provider under its CLI name.

class embodichain.learning.rl.policy_evaluation.MotionProfile[source]#

Bases: object

DexSim Policy Spec and report metadata built by one provider.

Methods:

__init__(profile_id, policy_spec[, ...])

Attributes:

`policy_spec`
`profile_id`
`provenance`
`provider_version`
`warnings`

__init__(profile_id, policy_spec, provider_version=1, provenance=<factory>, warnings=())#

policy_spec: Mapping[str, Any]#

profile_id: str#

provenance: Mapping[str, Any]#

provider_version: int = 1#

warnings: tuple[str, ...] = ()#

class embodichain.learning.rl.policy_evaluation.MotionProfileRequest[source]#

Bases: object

Checkpoint, configs, and runtime choices supplied to a provider.

Methods:

__init__(checkpoint, device[, configs, ...])

Attributes:

`checkpoint`
`configs`
`device`
`renderer`
`resource_root`

__init__(checkpoint, device, configs=<factory>, resource_root=None, renderer='hybrid')#

checkpoint: Path#

configs: Mapping[str, Path]#

device: device#

renderer: str = 'hybrid'#

resource_root: Path | None = None#

class embodichain.learning.rl.policy_evaluation.PolicyViewerCameraCfg[source]#

Bases: object

Configure planar tracking in the native policy Viewer.

A task opts in by exposing policy_viewer_camera_cfg and a callable get_policy_viewer_target_pose() returning a world pose as seven values (x, y, z, qx, qy, qz, qw). Tasks without a preset retain their own view.

On reset, the eye offset is rotated by the target’s initial yaw. Subsequent updates translate the camera only in world X-Y, preserving orbit and zoom adjustments. Target height is fixed in world coordinates for flat scenes.

Methods:

`__init__`([eye_offset, target_height])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

Attributes:

`eye_offset`	Eye position relative to the look-at point, in meters in the target's initial heading frame.
`target_height`	Fixed world Z of the look-at point, in meters.

__init__(eye_offset=<factory>, target_height=<factory>)#

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

eye_offset: tuple[float, float, float]#: Eye position relative to the look-at point, in meters in the target’s initial heading frame. Negative X looks from behind; the horizontal offset must be nonzero.

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

target_height: float#: Fixed world Z of the look-at point, in meters.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

embodichain.learning.rl.policy_evaluation.build_motion_profile(name, request)[source]#

Build one profile with its registered provider.

Parameters:

name (str) – Registered profile name.
request (MotionProfileRequest) – Checkpoint, configs, and runtime choices.

Return type:

MotionProfile

Returns:

Provider-built Motion Profile.

embodichain.learning.rl.policy_evaluation.register_motion_profile(name, provider)[source]#

Register a Motion Profile provider under its CLI name.

Parameters:

name (str) – Stable profile name.
provider (Callable[[MotionProfileRequest], MotionProfile]) – Callable that builds one MotionProfile.

Return type:

None

External Motion Profiles#

External Policy Profile registration and construction.

Classes:

`MotionProfile`	DexSim Policy Spec and report metadata built by one provider.
`MotionProfileRequest`	Checkpoint, configs, and runtime choices supplied to a provider.

Functions:

`build_motion_profile`(name, request)	Build one profile with its registered provider.
`register_motion_profile`(name, provider)	Register a Motion Profile provider under its CLI name.

class embodichain.learning.rl.policy_evaluation.profile.MotionProfile[source]#

Bases: object

DexSim Policy Spec and report metadata built by one provider.

Methods:

__init__(profile_id, policy_spec[, ...])

Attributes:

`policy_spec`
`profile_id`
`provenance`
`provider_version`
`warnings`

__init__(profile_id, policy_spec, provider_version=1, provenance=<factory>, warnings=())#

policy_spec: Mapping[str, Any]#

profile_id: str#

provenance: Mapping[str, Any]#

provider_version: int = 1#

warnings: tuple[str, ...] = ()#

class embodichain.learning.rl.policy_evaluation.profile.MotionProfileRequest[source]#

Bases: object

Checkpoint, configs, and runtime choices supplied to a provider.

Methods:

__init__(checkpoint, device[, configs, ...])

Attributes:

`checkpoint`
`configs`
`device`
`renderer`
`resource_root`

__init__(checkpoint, device, configs=<factory>, resource_root=None, renderer='hybrid')#

checkpoint: Path#

configs: Mapping[str, Path]#

device: device#

renderer: str = 'hybrid'#

resource_root: Path | None = None#

embodichain.learning.rl.policy_evaluation.profile.build_motion_profile(name, request)[source]#

Build one profile with its registered provider.

Parameters:

name (str) – Registered profile name.
request (MotionProfileRequest) – Checkpoint, configs, and runtime choices.

Return type:

MotionProfile

Returns:

Provider-built Motion Profile.

embodichain.learning.rl.policy_evaluation.profile.register_motion_profile(name, provider)[source]#

Register a Motion Profile provider under its CLI name.

Parameters:

name (str) – Stable profile name.
provider (Callable[[MotionProfileRequest], MotionProfile]) – Callable that builds one MotionProfile.

Return type:

None

Run an external Policy Profile through DexSim Motion Policy Kit.

Classes:

MotionEvaluationResult

Normalized inputs and per-episode motion evaluation results.

Functions:

evaluate_motion_profile(profile, *[, ...])

Resolve one Motion Profile and run its visual evaluation.

class embodichain.learning.rl.policy_evaluation.bridge.MotionEvaluationResult[source]#

Bases: object

Normalized inputs and per-episode motion evaluation results.

Methods:

__init__(profile, policy_spec, scene_config, ...)

Attributes:

`episodes`
`policy_spec`
`profile`
`scene_config`
`summary`
`viewer`

__init__(profile, policy_spec, scene_config, episodes, summary, viewer)#

episodes: tuple[Mapping[str, Any], ...]#

policy_spec: Mapping[str, Any]#

profile: MotionProfile#

scene_config: Mapping[str, Any]#

summary: Mapping[str, Any]#

viewer: bool#

embodichain.learning.rl.policy_evaluation.bridge.evaluate_motion_profile(profile, *, episodes=1, viewer=False, control_steps=None, duration=None, command=None, keymap='wasd', scene_config='standard', physics_backend=None, simulation_device='cpu', renderer='hybrid', gpu_id=0, termination_behavior=None, cache_dir=None, offline=False)[source]#

Resolve one Motion Profile and run its visual evaluation.

Parameters:

profile (MotionProfile) – Provider-built profile containing the DexSim Policy Spec.
episodes (int) – Number of independent runs.
viewer (bool) – Open the DexSim Viewer.
control_steps (int | None) – Exact number of applied policy commands per run.
duration (float | None) – Convenience duration converted by DexSim to policy steps.
command (tuple[float, ...] | None) – Optional task command override.
keymap (str) – Viewer command keys, either wasd or arrows.
scene_config (str | Path) – Built-in scene style or custom YAML path.
physics_backend (str | None) – Optional DexSim physics backend override.
simulation_device (str) – cpu or gpu.
renderer (str) – DexSim renderer.
gpu_id (int) – Selected GPU index.
termination_behavior (str | None) – Policy termination handling override.
cache_dir (str | Path | None) – Motion Policy Kit resource cache.
offline (bool) – Use resources already available in the cache.

Return type:

MotionEvaluationResult

Returns:

Normalized inputs, episode results, and aggregate metrics.

EmbodiChain Viewer Bridge#

Tasks opt into planar camera tracking with PolicyViewerCameraCfg and a world-pose provider. The preset controls reset framing; step updates preserve manual orbit and zoom while following the target in X-Y.

Task-owned camera presets for native policy evaluation.

Classes:

PolicyViewerCameraCfg

Configure planar tracking in the native policy Viewer.

class embodichain.learning.rl.policy_evaluation.camera.PolicyViewerCameraCfg[source]#

Bases: object

Configure planar tracking in the native policy Viewer.

A task opts in by exposing policy_viewer_camera_cfg and a callable get_policy_viewer_target_pose() returning a world pose as seven values (x, y, z, qx, qy, qz, qw). Tasks without a preset retain their own view.

On reset, the eye offset is rotated by the target’s initial yaw. Subsequent updates translate the camera only in world X-Y, preserving orbit and zoom adjustments. Target height is fixed in world coordinates for flat scenes.

Methods:

`__init__`([eye_offset, target_height])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

Attributes:

`eye_offset`	Eye position relative to the look-at point, in meters in the target's initial heading frame.
`target_height`	Fixed world Z of the look-at point, in meters.

__init__(eye_offset=<factory>, target_height=<factory>)#

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

eye_offset: tuple[float, float, float]#: Eye position relative to the look-at point, in meters in the target’s initial heading frame. Negative X looks from behind; the horizontal offset must be nonzero.

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

target_height: float#: Fixed world Z of the look-at point, in meters.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

Connect an EmbodiChain task Viewer to Motion Policy Evaluator.

Classes:

`EmbodiChainTaskEnvironment`	Expose one original EmbodiChain RL Environment to the Evaluator.
`EmbodiChainTaskPolicyAdapter`	Run an EmbodiChain Policy from the task observation in each frame.
`NativeViewerResult`	Result of visualizing one Policy in its EmbodiChain task.

Functions:

evaluate_native_viewer(runtime, *, seed, ...)

Visualize an EmbodiChain Policy in the task used for training.

class embodichain.learning.rl.policy_evaluation.viewer.EmbodiChainTaskEnvironment[source]#

Bases: object

Expose one original EmbodiChain RL Environment to the Evaluator.

Methods:

`__init__`(env, *, seed[, command, keymap])
`close`()	Close the original task Environment.
`metrics`()	Return task metrics and completed episode aggregates.
`open_viewer`(title)	Apply the evaluation title to the task Viewer.
`poll`()	Report when the native Viewer is closed or Escape is pressed.
`reset`()	Run the task's original reset and return its observation.
`step`(action)	Apply one raw Policy action through the task's original action path.
`wait_for_reset_or_close`()	Keep a paused Viewer responsive until it is closed.

Attributes:

`current_frame`	Return the latest observation and task state.
`episodes`	Return completed episode summaries.
`physics_backend`	Return the backend selected by the original task Environment.
`policy_context`	Return the timing used by the original task Environment.
`viewer_is_open`	Return whether the original task Viewer remains open.

__init__(env, *, seed, command=None, keymap='wasd')[source]#

close()[source]#

Close the original task Environment.

Return type:: None

property current_frame: EvaluationFrame#: Return the latest observation and task state.

property episodes: tuple[Mapping[str, float | int | bool | str], ...]#: Return completed episode summaries.

metrics()[source]#

Return task metrics and completed episode aggregates.

Return type:: dict[str, float]

open_viewer(title)[source]#

Apply the evaluation title to the task Viewer.

Return type:: None

property physics_backend: str#: Return the backend selected by the original task Environment.

property policy_context: PolicyContext#: Return the timing used by the original task Environment.

poll()[source]#

Report when the native Viewer is closed or Escape is pressed.

Return type:: str | None

reset()[source]#

Run the task’s original reset and return its observation.

Return type:: EvaluationFrame

step(action)[source]#

Apply one raw Policy action through the task’s original action path.

Return type:: EnvironmentStep

property viewer_is_open: bool#: Return whether the original task Viewer remains open.

wait_for_reset_or_close()[source]#

Keep a paused Viewer responsive until it is closed.

MotionPolicyEvaluator calls this method after a task termination when the selected behavior is pause.

Return type:: str

class embodichain.learning.rl.policy_evaluation.viewer.EmbodiChainTaskPolicyAdapter[source]#

Bases: object

Run an EmbodiChain Policy from the task observation in each frame.

Methods:

`__init__`(policy, device)
`close`()	Restore the Policy mode used before evaluation.
`infer`(frame)	Run the same observation and deterministic Policy path as RL evaluation.
`metrics`()	Return Policy-side metrics.
`reset`(frame)	Validate that the Environment supplied the next observation.
`setup`(context)	Select deterministic inference for this evaluation.

__init__(policy, device)[source]#

close()[source]#

Restore the Policy mode used before evaluation.

Return type:: None

infer(frame)[source]#

Run the same observation and deterministic Policy path as RL evaluation.

Return type:: PolicyOutput

metrics()[source]#

Return Policy-side metrics.

Return type:: dict[str, float]

reset(frame)[source]#

Validate that the Environment supplied the next observation.

Return type:: None

setup(context)[source]#

Select deterministic inference for this evaluation.

Return type:: None

class embodichain.learning.rl.policy_evaluation.viewer.NativeViewerResult[source]#

Bases: object

Result of visualizing one Policy in its EmbodiChain task.

Methods:

__init__(task_id, reason, simulation_time, ...)

Attributes:

`control_steps`
`effective_duration`
`episodes`
`metrics`
`reason`
`requested_duration`
`simulation_steps`
`simulation_time`
`task_id`

__init__(task_id, reason, simulation_time, simulation_steps, control_steps, effective_duration, requested_duration, episodes, metrics)#

control_steps: int#

effective_duration: float#

episodes: tuple[Mapping[str, float | int | bool | str], ...]#

metrics: Mapping[str, float]#

reason: str#

requested_duration: float | None#

simulation_steps: int#

simulation_time: float#

task_id: str#

embodichain.learning.rl.policy_evaluation.viewer.evaluate_native_viewer(runtime, *, seed, episodes, control_steps, duration, command=None, keymap='wasd', termination_behavior='auto_reset')[source]#

Visualize an EmbodiChain Policy in the task used for training.

Return type:: NativeViewerResult

Run Discovery and Reports#

Index a training run for standalone policy evaluation.

Classes:

RunManifest

Resolved paths from one EmbodiChain training run.

Functions:

write_run_manifest(run, *, train_config, ...)

Snapshot training configs and write the minimal run manifest.

class embodichain.learning.rl.policy_evaluation.manifest.RunManifest[source]#

Bases: object

Resolved paths from one EmbodiChain training run.

Methods:

`__init__`(root, configs, checkpoints)
`load`(run, *[, check_files])	Load `run-manifest.json` and resolve its referenced files.
`select_checkpoint`([requested])	Select `best` or `latest` and return its resolved path.

Attributes:

`checkpoints`
`configs`
`root`

__init__(root, configs, checkpoints)#

checkpoints: Mapping[str, Path | None]#

configs: Mapping[str, Path]#

classmethod load(run, *, check_files=True)[source]#

Load run-manifest.json and resolve its referenced files.

Parameters:

run (str | Path) – EmbodiChain training run directory.
check_files (bool) – Require every referenced file to exist. Set to False when the caller checks only the files needed for its operation. Manifest structure and path containment are always validated.

Return type:

RunManifest

Returns:

Resolved manifest.

root: Path#

select_checkpoint(requested='latest')[source]#

Select best or latest and return its resolved path.

Parameters:: requested (str) – Checkpoint role.
Return type:: tuple[str, Path]
Returns:: Selected role and checkpoint path. best uses latest when the training run has no best checkpoint.

embodichain.learning.rl.policy_evaluation.manifest.write_run_manifest(run, *, train_config, latest_checkpoint, best_checkpoint=None, gym_config=None)[source]#

Snapshot training configs and write the minimal run manifest.

Parameters:

run (str | Path) – Training run directory containing the checkpoints.
train_config (str | Path) – Training config used for the run.
latest_checkpoint (str | Path) – Final saved checkpoint.
best_checkpoint (str | Path | None) – Best checkpoint when evaluation selected one.
gym_config (str | Path | None) – Referenced task config when the trainer uses one.

Return type:

Path

Returns:

Written manifest path.

Write timestamped policy evaluation reports.

Functions:

write_evaluation_report(parent, payload)

Write evaluation.json under a new timestamped directory.

embodichain.learning.rl.policy_evaluation.report.write_evaluation_report(parent, payload)[source]#

Write evaluation.json under a new timestamped directory.

Parameters:

parent (str | Path) – Output parent directory.
payload (Mapping[str, Any]) – Evaluation inputs and results.

Return type:

Path

Returns:

Written report path.

Command Line#

Unified policy evaluation for EmbodiChain training runs.

Functions:

`cli`([argv])	Run policy evaluation from the unified EmbodiChain CLI.
`parse_args`([argv])	Parse `embodichain eval-policy` arguments.
`run`(args)	Run Headless or Viewer evaluation and write `evaluation.json`.

embodichain.learning.rl.policy_evaluation.cli.cli(argv=None)[source]#

Run policy evaluation from the unified EmbodiChain CLI.

Return type:: None

embodichain.learning.rl.policy_evaluation.cli.parse_args(argv=None)[source]#

Parse embodichain eval-policy arguments.

Return type:: Namespace

embodichain.learning.rl.policy_evaluation.cli.run(args)[source]#

Run Headless or Viewer evaluation and write evaluation.json.

Return type:: Path

embodichain.learning.rl.policy_evaluation

Contents

embodichain.learning.rl.policy_evaluation#

External Motion Profiles#

EmbodiChain Viewer Bridge#

Run Discovery and Reports#

Command Line#