Configuration Classes

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

RenderConfig

Controls the visualization render camera (not observations): image resolution and which view render_mode shows. camera="side" selects an angled tabletop bystander view, useful for watching rollouts and recording presentation-quality videos of trained policies; it never enters the observation space. The camera selection applies to the MuJoCo backend only, since the Warp backend does not implement render().

from so101_nexus import RenderConfig

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

# Angled side view for render_mode="rgb_array" videos and the human viewer
render = RenderConfig(camera="side")

Constructor Parameters

Pose

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

from so101_nexus 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

Methods

Built-in Poses

Access via the POSES dict or by constant:

from so101_nexus import POSES, REST_POSE

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

RobotConfig

Controls the arm rest pose, grasping thresholds, and the end-effector solver.

from so101_nexus import RobotConfig

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

Constructor Parameters

Properties and methods

RobotCameraPreset

Robot-specific camera and mounting parameters for SO-100 and SO-101. All fields are required (no defaults); wrist_cam_euler_center_rad and wrist_cam_euler_noise_rad expose the Euler angles in radians.

RewardConfig

Defines reward component weights and computes the shaped reward.

from so101_nexus import RewardConfig

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

Constructor Parameters

A "potential-shaped delta" pays the change in progress since the previous step rather than the raw value, so dwelling at a fixed state (e.g. holding an object without lifting it) earns no further reward. The implementation is so101_nexus.rewards.potential_shaping; see Rewards for which tasks use it.

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.

Returns a single float reward value.

EnvironmentConfig

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

from so101_nexus import EnvironmentConfig

config = EnvironmentConfig(obs_mode="state")

Constructor Parameters

Validation

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

Episode Length

max_episode_steps is owned by the Gymnasium registration, not the config. Set it per env at construction, the same way for every task:

import gymnasium as gym

# MuJoCo (single env): applied via the TimeLimit wrapper
env = gym.make("MuJoCoTouch-v1", config=config, max_episode_steps=256)

# Warp (batched): forwarded to the vector env, which truncates internally
envs = gym.make_vec("WarpTouch-v1", num_envs=4, device="cuda", config=config, max_episode_steps=256)

Registered defaults: PickLift, PickAndPlace, and StackCube 1024, Touch 512, LookAt and Move 256. They apply to both the MuJoCo*-v1 and Warp*-v1 ids.

Observation Components

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

State Components

Camera Components

WristCamera

from so101_nexus import WristCamera

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

Properties: fov_rad_range, pitch_rad_range (converted to radians).

OverheadCamera

from so101_nexus import OverheadCamera

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

PickConfig

Extends EnvironmentConfig with parameters for pick and lift tasks.

from so101_nexus 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.

Default Observations

When observations is not specified: [JointPositions(), JointVelocities(), EndEffectorPose(), GraspState(), GazeState(), ObjectPose(), ObjectOffset()] (31 dimensions).

PickAndPlaceConfig

Extends EnvironmentConfig with parameters for pick-and-place tasks. The carried object is chosen per episode from an object pool: by default one cube per color in cube_colors, or pass objects to carry YCBObject / MeshObject instead.

from so101_nexus import PickAndPlaceConfig, YCBObject

# Default cube path (carries a colored cube onto the disc):
config = PickAndPlaceConfig(cube_colors="blue", target_colors="green")

# Object-pool path (carries a YCB object):
config = PickAndPlaceConfig(objects=[YCBObject("011_banana")], target_colors="green")

Additional Parameters

These are in addition to all EnvironmentConfig parameters.

Distractor slots are only compiled when n_distractors > 0, so the default scene holds exactly one object. Distractors keep min_object_target_separation from the disc, so clutter never spawns on the goal. A distractor cube whose color is also a carried cube color warns, because the task description names the carried object by color alone.

Default Observations

When observations is not specified: [JointPositions(), JointVelocities(), EndEffectorPose(), GraspState(), GazeState(), TargetPosition(), ObjectPose(), ObjectVelocity(), ObjectOffset(), TargetOffset()] (43 dimensions).

StackCubeConfig

Extends EnvironmentConfig with parameters for the stack-cube task. Two cubes are spawned every episode: cube A (picked up and stacked) and cube B (the stationary base). Colors default to disjoint values so the two cubes are never the same color out of the box.

from so101_nexus import StackCubeConfig

config = StackCubeConfig(cube_a_colors="green", cube_b_colors="purple")

Additional Parameters

These are in addition to all EnvironmentConfig parameters.

Passing overlapping cube_a_colors/cube_b_colors pools warns (the two cubes may be the same color in some episodes).

Distractor slots are only compiled when n_distractors > 0, so the default scene holds exactly two cubes. A distractor cube whose color is also a cube A/B color warns, because the task description names cubes by color alone.

Default Observations

When observations is not specified: [JointPositions(), JointVelocities(), EndEffectorPose(), GraspState(), GazeState(), ObjectPose(), ObjectVelocity(), ObjectOffset(), TargetPosition(), TargetOffset()] (43 dimensions).

TouchConfig

Extends PickConfig with the touch task. The touch target can be any cube, YCB object, or mesh from the object pool.

from so101_nexus import TouchConfig

config = TouchConfig(touch_margin=0.03)

Additional Parameters

This is in addition to all PickConfig object-pool parameters (objects, n_distractors, min_object_separation) and the inherited EnvironmentConfig parameters.

Default Observations

When observations is not specified: [JointPositions(), JointVelocities(), EndEffectorPose(), GraspState(), GazeState(), ObjectPose(), ObjectOffset()] (31 dimensions).

LookAtConfig

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

from so101_nexus import LookAtConfig, CubeObject

config = LookAtConfig(
    objects=CubeObject(color="blue"),
    fov_deg=60.0,
)

Additional Parameters

The MuJoCoLookAt-v1 and WarpLookAt-v1 registrations default max_episode_steps to 256; override it at construction via gym.make(..., max_episode_steps=N) (MuJoCo) or gym.make_vec(..., max_episode_steps=N) (Warp).

Default Observations

When observations is not specified: [JointPositions(), JointVelocities(), EndEffectorPose(), GazeDirection(), GazeState()] (23 dimensions).

MoveConfig

Extends EnvironmentConfig with parameters for the directional move primitive task.

from so101_nexus import MoveConfig

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

Additional Parameters

The MuJoCoMove-v1 and WarpMove-v1 registrations default max_episode_steps to 256; override it at construction via gym.make(..., max_episode_steps=N) (MuJoCo) or gym.make_vec(..., max_episode_steps=N) (Warp).

Default Observations

When observations is not specified: [JointPositions(), JointVelocities(), EndEffectorPose(), TargetOffset()] (22 dimensions).