Configuration Classes

All configuration classes live in so101_nexus_core and are plain Python classes with default constructor arguments. They control rendering, robot parameters, reward shaping, observation composition, and environment behavior.

RenderConfig

Controls image resolution for the visualization render camera (not observations).

from so101_nexus_core import RenderConfig

render = RenderConfig(width=640, height=480)

Constructor Parameters

Parameter	Type	Default	Description
`width`	`int`	`640`	Render image width in pixels
`height`	`int`	`480`	Render image height in pixels

Pose

Defines a named robot arm configuration with fixed and free joints. See Initial Poses for a conceptual overview.

from so101_nexus_core import Pose

pose = Pose(
    name="custom",
    shoulder_pan_deg=(-110.0, 110.0),  # free: sampled uniformly
    shoulder_lift_deg=-90.0,            # fixed
    elbow_flex_deg=90.0,                # fixed
    wrist_flex_deg=37.8,                # fixed
    wrist_roll_deg=(-157.0, 163.0),     # free
    gripper_deg=(-10.0, 100.0),         # free
)

Constructor Parameters

Parameter	Type	Description
`name`	`str`	Human-readable identifier
`shoulder_pan_deg`	`float \| tuple[float, float]`	Shoulder pan angle or range (degrees)
`shoulder_lift_deg`	`float \| tuple[float, float]`	Shoulder lift angle or range (degrees)
`elbow_flex_deg`	`float \| tuple[float, float]`	Elbow flex angle or range (degrees)
`wrist_flex_deg`	`float \| tuple[float, float]`	Wrist flex angle or range (degrees)
`wrist_roll_deg`	`float \| tuple[float, float]`	Wrist roll angle or range (degrees)
`gripper_deg`	`float \| tuple[float, float]`	Gripper angle or range (degrees)

Methods

Method	Returns	Description
`sample(rng)`	`tuple[float, ...]`	Sample concrete joint angles in degrees
`sample_rad(rng)`	`tuple[float, ...]`	Sample concrete joint angles in radians

Built-in Poses

Name	Constant	Description
`"rest"`	`REST_POSE`	Arm curled in rest position, free shoulder_pan/wrist_roll/gripper
`"extended"`	`EXTENDED_POSE`	Arm extended forward, free shoulder_pan/wrist_roll/gripper

Access via the POSES dict or by constant:

from so101_nexus_core import POSES, REST_POSE

pose = POSES["rest"]   # same as REST_POSE

RobotConfig

Controls the arm rest pose and grasping thresholds.

from so101_nexus_core import RobotConfig

robot = RobotConfig(rest_qpos_deg=(0.0, -90.0, 90.0, 37.82, 0.0, -63.03))

Constructor Parameters

Parameter	Type	Default	Description
`rest_qpos_deg`	`tuple[float, ...]`	`(0.0, -90.0, 90.0, 37.82, 0.0, -63.03)`	Rest joint positions in degrees, one per joint
`init_pose`	`str \| Pose \| None`	`None`	Initial pose for resets. String looks up from `POSES`, `Pose` instance used directly, `None` uses legacy rest + noise.
`grasp_force_threshold`	`float`	`0.5`	Minimum contact force to count as a grasp
`static_vel_threshold`	`float`	`0.2`	Maximum velocity to consider the arm stationary

Properties

Property	Type	Description
`rest_qpos_rad`	`tuple[float, ...]`	`rest_qpos_deg` converted to radians
`rest_qpos`	`tuple[float, ...]`	Alias for `rest_qpos_rad`
`resolve_pose()`	`Pose \| None`	Returns the resolved `Pose` object, or `None`

RewardConfig

Defines reward component weights and computes the shaped reward.

from so101_nexus_core import RewardConfig

reward = RewardConfig(reaching=0.25, grasping=0.25, task_objective=0.40, completion_bonus=0.10)

Constructor Parameters

Parameter	Type	Default	Description
`reaching`	`float`	`0.25`	Weight for the reaching component
`grasping`	`float`	`0.25`	Weight for the grasping component
`task_objective`	`float`	`0.40`	Weight for the task-specific objective
`completion_bonus`	`float`	`0.10`	Weight for the task completion bonus
`action_delta_penalty`	`float`	`0.0`	Penalty coefficient on L2 norm of consecutive action deltas
`energy_penalty`	`float`	`0.0`	Penalty coefficient on L2 norm of the action vector
`tanh_shaping_scale`	`float`	`5.0`	Scale factor for tanh reward shaping

Validation

The four base weights (reaching + grasping + task_objective + completion_bonus) must sum to 1.0. Construction raises an error if this constraint is violated. The penalty coefficients are separate additive terms and are not included in the sum constraint.

Methods

`compute()`

def compute(
    reach_progress: float,
    is_grasped: bool,
    task_progress: float,
    is_complete: bool,
    action_delta_norm: float = 0.0,
    energy_norm: float = 0.0,
) -> float

Computes the weighted reward from per-component progress values.

Parameter	Type	Default	Description
`reach_progress`	`float`	required	Progress toward the target (0 to 1)
`is_grasped`	`bool`	required	Whether the object is currently grasped
`task_progress`	`float`	required	Progress on the task objective (0 to 1)
`is_complete`	`bool`	required	Whether the task is fully complete
`action_delta_norm`	`float`	`0.0`	Norm of the action delta for penalty
`energy_norm`	`float`	`0.0`	Norm of energy usage for penalty

Returns a single float reward value.

EnvironmentConfig

Base configuration for all environments. Task-specific configs extend this class.

from so101_nexus_core import EnvironmentConfig

config = EnvironmentConfig(max_episode_steps=512, obs_mode="state")

Constructor Parameters

Parameter	Type	Default	Description
`render`	`RenderConfig \| None`	`None`	Render camera resolution settings (visualization only). Uses `RenderConfig()` defaults when `None`.
`reward`	`RewardConfig \| None`	`None`	Reward weights. Uses `RewardConfig()` defaults when `None`.
`robot`	`RobotConfig \| None`	`None`	Robot settings. Uses `RobotConfig()` defaults when `None`.
`ground_colors`	`ColorConfig`	`"gray"`	Ground plane color(s)
`max_episode_steps`	`int`	`1024`	Maximum steps before truncation
`goal_thresh`	`float`	`0.025`	Distance threshold for goal completion (meters)
`spawn_half_size`	`float`	`0.05`	Half-size of object spawn region
`spawn_center`	`tuple[float, float]`	`(0.15, 0.0)`	Center of the spawn region (x, y)
`spawn_min_radius`	`float`	`0.20`	Minimum spawn distance from the robot base
`spawn_max_radius`	`float`	`0.40`	Maximum spawn distance from the robot base
`spawn_angle_half_range_deg`	`float`	`90.0`	Half-range of spawn angle in degrees
`obs_mode`	`ObsMode`	`"state"`	Observation mode: `"state"` or `"visual"`
`robot_colors`	`ColorConfig`	`"yellow"`	Robot body color(s)
`robot_init_qpos_noise`	`float`	`0.02`	Noise added to initial joint positions
`observations`	`list[Observation] \| None`	`None`	Observation components to include. Task-specific configs provide defaults when `None`.

Validation

obs_mode must be "state" or "visual"
When obs_mode="visual", observations must contain at least one camera component (WristCamera or OverheadCamera)
Duplicate camera component types are not allowed

Observation Components

Observation components are lightweight descriptor classes passed via the observations parameter. See Observations for a conceptual overview.

State Components

Class	Size	Description
`JointPositions()`	6	Current joint angles
`EndEffectorPose()`	7	TCP position + quaternion
`TargetOffset()`	3	Vector from gripper to goal
`GazeDirection()`	3	Unit vector toward target
`GraspState()`	1	Binary grasp flag
`ObjectPose()`	7	Object position + quaternion
`ObjectOffset()`	3	Vector from gripper to object
`TargetPosition()`	3	Absolute goal position

Camera Components

`WristCamera`

from so101_nexus_core import WristCamera

cam = WristCamera(width=224, height=224)

Parameter	Type	Default	Description
`width`	`int`	`640`	Image width in pixels
`height`	`int`	`480`	Image height in pixels
`fov_deg_range`	`tuple[float, float]`	`(60.0, 90.0)`	FOV randomization range in degrees
`pitch_deg_range`	`tuple[float, float]`	`(-34.4, 0.0)`	Pitch randomization range in degrees
`pos_x_noise`	`float`	`0.005`	Position noise along x-axis
`pos_y_center`	`float`	`0.04`	Nominal y-offset from the wrist
`pos_y_noise`	`float`	`0.01`	Position noise along y-axis
`pos_z_center`	`float`	`-0.04`	Nominal z-offset from the wrist
`pos_z_noise`	`float`	`0.01`	Position noise along z-axis

Properties: fov_rad_range, pitch_rad_range (converted to radians).

`OverheadCamera`

from so101_nexus_core import OverheadCamera

cam = OverheadCamera(width=320, height=240, fov_deg=45.0)

Parameter	Type	Default	Description
`width`	`int`	`640`	Image width in pixels
`height`	`int`	`480`	Image height in pixels
`fov_deg`	`float`	`45.0`	Vertical field-of-view in degrees

PickConfig

Extends EnvironmentConfig with parameters for pick and lift tasks.

from so101_nexus_core import PickConfig, CubeObject, YCBObject

config = PickConfig(
    objects=[CubeObject(color="blue"), YCBObject("011_banana")],
    n_distractors=2,
)

Additional Parameters

These are in addition to all EnvironmentConfig parameters.

Parameter	Type	Default	Description
`objects`	`list[SceneObject] \| SceneObject \| None`	`None`	Objects to pick. A single object is auto-wrapped. Defaults to `[CubeObject()]` when `None`.
`n_distractors`	`int`	`0`	Number of distractor objects to spawn
`lift_threshold`	`float`	`0.05`	Height above the table to count as lifted (meters)
`max_goal_height`	`float`	`0.08`	Maximum target lift height (meters)
`min_object_separation`	`float`	`0.04`	Minimum distance between spawned objects (meters)

Default Observations

When observations is not specified: [EndEffectorPose(), GraspState(), ObjectPose(), ObjectOffset()] (18 dimensions).

PickAndPlaceConfig

Extends EnvironmentConfig with parameters for pick-and-place tasks.

from so101_nexus_core import PickAndPlaceConfig

config = PickAndPlaceConfig(
    cube_colors="blue",
    target_colors="green",
    min_cube_target_separation=0.05,
)

Additional Parameters

These are in addition to all EnvironmentConfig parameters.

Parameter	Type	Default	Description
`cube_colors`	`ColorConfig`	`"red"`	Color(s) for the cube
`target_colors`	`ColorConfig`	`"blue"`	Color(s) for the target disc
`cube_half_size`	`float`	`0.0125`	Half-size of the cube (meters)
`cube_mass`	`float`	`0.01`	Mass of the cube (kg)
`target_disc_radius`	`float`	`0.05`	Radius of the target disc (meters)
`min_cube_target_separation`	`float`	`0.0375`	Minimum distance between cube and target spawn positions (meters)

Default Observations

When observations is not specified: [EndEffectorPose(), GraspState(), TargetPosition(), ObjectPose(), ObjectOffset(), TargetOffset()] (24 dimensions).

ReachConfig

Extends EnvironmentConfig with parameters for the reach-to-target primitive task.

from so101_nexus_core import ReachConfig

config = ReachConfig(target_radius=0.03, success_threshold=0.02)

Additional Parameters

Parameter	Type	Default	Description
`target_radius`	`float`	`0.02`	Visual radius of the target site sphere (meters)
`target_workspace_half_extent`	`float`	`0.15`	Half-width of the cubic workspace for target sampling (meters)
`success_threshold`	`float`	`0.02`	TCP-to-target distance (m) that counts as success

Defaults max_episode_steps to 512.

Default Observations

When observations is not specified: [JointPositions()] (6 dimensions).

LookAtConfig

Extends EnvironmentConfig with parameters for the look-at primitive task.

from so101_nexus_core import LookAtConfig, CubeObject

config = LookAtConfig(
    objects=CubeObject(color="blue"),
    orientation_success_threshold_deg=5.0,
)

Additional Parameters

Parameter	Type	Default	Description
`objects`	`list[SceneObject] \| SceneObject \| None`	`None`	Target object(s). Only `CubeObject` is supported. Defaults to `[CubeObject()]`.
`orientation_success_threshold_deg`	`float`	`5.73`	Max angular error in degrees for success

Defaults max_episode_steps to 256.

Default Observations

When observations is not specified: [JointPositions()] (6 dimensions).

MoveConfig

Extends EnvironmentConfig with parameters for the directional move primitive task.

from so101_nexus_core import MoveConfig

config = MoveConfig(direction="up", target_distance=0.10)

Additional Parameters

Parameter	Type	Default	Description
`direction`	`MoveDirection`	`"up"`	Cardinal direction: `"up"`, `"down"`, `"left"`, `"right"`, `"forward"`, `"backward"`
`target_distance`	`float`	`0.10`	Distance in metres to travel from the initial TCP position
`success_threshold`	`float`	`0.01`	Max residual distance (m) to count as success

Defaults max_episode_steps to 256.

Default Observations

When observations is not specified: [JointPositions()] (6 dimensions).

Configuration Classes

On this page