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.

SimSOFollowerConfig.seed controls the seed for the simulator reset during connection. The default is None, which lets Gymnasium select the random state. Teleoperation sets this field from its effective episode seed.

PhysicsConfigCopy Anchor Link

Pass physics=PhysicsConfig(...) to any task configuration to select physics timing, solver behavior, and optional jaw contact impedance. Omit physics to retain each backend's historical defaults.

from so101_nexus import PhysicsConfig, PickConfig

config = PickConfig(physics=PhysicsConfig(timestep_s=0.0025))

This configuration uses eight physics substeps per 20 ms command, including reset settling and Warp CUDA graphs. The default control frequency remains 50 Hz when only the physics timestep changes. An explicit control_period_s changes the command frequency and the duration of episodes with a fixed step count.

PhysicsConfig is immutable. A different configuration requires a new environment. Warp rejects unsupported NoSlip and solver tolerance values before device conversion. See Physics divergence for backend limits.

gripper_solimp affects only active condim=6 collision geoms directly attached to gripper and moving_jaw_so101_v1. It preserves material friction, solref, geometry, collision masks, mass, actuator limits, and task thresholds. The tuple requires 1e-4 <= dmin <= dmax <= 0.9999, positive width, midpoint strictly between zero and one, and power at least one. Width uses meters. An omitted tuple preserves the native contact impedance.

Grasp retention profileCopy Anchor Link

The following explicit profile adjusts numerical accuracy and jaw compliance together:

config = PickConfig(
    physics=PhysicsConfig(
        timestep_s=0.0025,
        control_period_s=0.02,
        integrator="implicit",
        solver="Newton",
        cone="elliptic",
        impratio=1000,
        iterations=100,
        ls_iterations=100,
        tolerance=9.999999974752427e-7,
        noslip_iterations=0,
        gripper_solimp=(0.99, 0.999, 0.001, 0.5, 2.0),
    )
)

The tolerance matches the float32 representation of 1e-6 on both backends. The report's run_hold_final_profile_v2.py validated this profile on a saved grasp with 20 mm and 19.05 mm cubes. Those tests assumed 10 g cubes and used the separate Warp collision patch. The configuration alone does not change Warp's box collision algorithm. This profile is a simulation assumption, not a measured stock-pad material model or evidence of general task success. Contact impedance affects tangential regularization as well as penetration. Validate the profile on the intended task.

RenderConfigCopy Anchor Link

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. Both backends support these views. See Render modes for backend output formats.

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",
    side_azimuth_range_deg=(120.0, 200.0),
    side_elevation_range_deg=(-50.0, -20.0),
    side_distance_range=(0.8, 1.2),
)

Constructor ParametersCopy Anchor Link

Ranges apply to every task's side view on both backends, including RGB and depth, and the MuJoCo human viewer. Each reset samples the configured ranges using the environment's seeded RNG. Warp samples independently per world and only resamples worlds that reset, including same-step autoresets. The sampled pose stays fixed during the episode; the human viewer still allows manual orbiting. An open viewer adopts the newly sampled pose on reset.

Automatic side framing fits the spawn region and arm working volume at the selected angles and image aspect ratio. The region follows the configured arc, or the square spawn_half_size region for LookAt. The camera fits the projected workspace and arm bounds within the image, choosing the shortest distance that leaves padding around them. It shifts the aim point only as much as needed to fit those bounds. The default angles favor objects in front of the arm. For custom spawn regions that extend behind the robot, the arm can obscure objects even when they fit in the frame. Adjust the angles for that layout or use the overhead view. With randomized angles, each reset computes both the aim point and distance for the sampled view. An explicit side_distance_range overrides the automatic distance.

Endpoints must be finite and ordered. Equal endpoints select a fixed value. Omitted angle ranges retain the corresponding fixed angles, and camera="overhead" ignores all side ranges. With no ranges, the camera uses fixed angles and automatic distance. Explicit distance bounds can crop the workspace or place the camera inside geometry, so choose bounds that suit your scene. These settings do not change camera observations.

PoseCopy Anchor Link

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 ParametersCopy Anchor Link

MethodsCopy Anchor Link

Built-in PosesCopy Anchor Link

Access via the POSES dict or by constant:

from so101_nexus import POSES, REST_POSE

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

RobotConfigCopy Anchor Link

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 ParametersCopy Anchor Link

Properties and methodsCopy Anchor Link

RobotCameraPresetCopy Anchor Link

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.

RewardConfigCopy Anchor Link

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 ParametersCopy Anchor Link

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.

ValidationCopy Anchor Link

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.

MethodsCopy Anchor Link

compute()Copy Anchor Link

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.

EnvironmentConfigCopy Anchor Link

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

from so101_nexus import EnvironmentConfig

config = EnvironmentConfig(obs_mode="state")

Constructor ParametersCopy Anchor Link

ValidationCopy Anchor Link

• 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 LengthCopy Anchor Link

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 ComponentsCopy Anchor Link

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

State ComponentsCopy Anchor Link

Camera ComponentsCopy Anchor Link

Both camera classes accept the keyword-only modalities parameter. Use ("rgb",) for RGB, ("depth",) for depth, or ("rgb", "depth") for both. The default is ("rgb",). Empty, duplicate, and unknown modalities raise ValueError. See Depth observations for output keys, units, shapes, and clipping behavior.

WristCameraCopy Anchor Link

from so101_nexus import WristCamera

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

Properties: fov_rad_range, pitch_rad_range (converted to radians).

OverheadCameraCopy Anchor Link

from so101_nexus import OverheadCamera

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

PickConfigCopy Anchor Link

Extends EnvironmentConfig with parameters for pick and lift tasks.

from so101_nexus import PickConfig, CubeObject, YCBObject

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

Additional ParametersCopy Anchor Link

These are in addition to all EnvironmentConfig parameters.

Default ObservationsCopy Anchor Link

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

PickReturnConfigCopy Anchor Link

Extends PickConfig for the pick-and-return task.

from so101_nexus import CubeObject, PickReturnConfig, RobotConfig

config = PickReturnConfig(
    objects=[CubeObject(color="blue"), CubeObject(color="red")],
    return_threshold_deg=5.0,
    robot=RobotConfig(rest_qpos_deg=(0.0, -90.0, 90.0, 37.8, 0.0, 0.0)),
)

return_threshold_deg, lift_threshold, and max_goal_height must be finite and positive. The rest target uses the first five angles in robot.rest_qpos_deg. robot.static_vel_threshold controls final arm staticness. reward.velocity_shaping_scale shapes the final slowdown and is active for this task. The default reward weights are reaching=0.15, grasping=0.15, task_objective=0.3, and completion_bonus=0.4. Passing a RewardConfig replaces these weights with your configuration. max_goal_height controls the curvature of lift shaping in meters. Lift credit is normalized to one at lift_threshold and saturates there. See task details for reward stages and default observations. An explicit observations list is preserved, including an empty list.

PickAndPlaceConfigCopy Anchor Link

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")

# Default cubes with a float millimeter side length:
millimeter_config = PickAndPlaceConfig(cube_side_length_mm=25.4)

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

Additional ParametersCopy Anchor Link

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 ObservationsCopy Anchor Link

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

PickAndPlaceV2ConfigCopy Anchor Link

This config extends PickAndPlaceConfig for the v2 center-placement contract. Use it with the v2 environment IDs. V1 and v2 reject the other version's config.

from so101_nexus import PickAndPlaceV2Config, YCBObject

config = PickAndPlaceV2Config(
    objects=[YCBObject("011_banana")],
    target_disc_radius=0.05,
)

The resolved contact-force tolerance is the larger of the absolute and relative values. All numerical thresholds must be finite. The radius, dwell time, and minimum weight fraction must be positive. The minimum weight fraction must not exceed one. The relative force tolerance must be less than one. The scanline count must be a positive integer. placement_contract returns JSON-safe evaluator metadata without simulator state.

StackCubeConfigCopy Anchor Link

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 ParametersCopy Anchor Link

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 ObservationsCopy Anchor Link

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

TouchConfigCopy Anchor Link

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 ParametersCopy Anchor Link

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

Default ObservationsCopy Anchor Link

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

LookAtConfigCopy Anchor Link

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 ParametersCopy Anchor Link

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 ObservationsCopy Anchor Link

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

MoveConfigCopy Anchor Link

Extends EnvironmentConfig with parameters for the directional move primitive task.

from so101_nexus import MoveConfig

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

Additional ParametersCopy Anchor Link

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 ObservationsCopy Anchor Link

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