Floating-base systems¶

Floating-base state is optional and disabled by default. Enable it when the robot mounting should be integrated as part of the system state:

fixed = PCS.from_links(links, base_pose=fixed_mounting)
floating = PCS.from_links(links, floating_base=True)

base_pose is a construction argument for fixed mounting and is stored as fixed.fixed_base_pose. Floating systems have fixed_base_pose is None and reject a construction-time base_pose; provide the initial pose when packing the runtime configuration instead.

Mounting is not physical parameter data. with_params(...) and update_params(...) therefore leave it unchanged. Use with_fixed_base_pose(...) to create a differently mounted fixed system. Named horizontal, upright, and hanging poses are available from soromox.utils.geometry.poses.

State convention¶

The dimensions are available explicitly as num_internal_dofs, num_base_coordinates, num_base_velocities, num_coordinates, num_velocities, num_auxiliary_states, and state_size. Configuration and velocity dimensions are intentionally separate because a spatial quaternion adds seven stored base coordinates but only six base velocity coordinates.

Spatial floating systems use

q = [qx, qy, qz, qw, px, py, pz, q_internal...]
v = [wx, wy, wz, vx, vy, vz, qd_internal...]

The quaternion is SoRoMoX's scalar-last Hamilton quaternion. Both angular and linear base velocity are expressed in the world frame; linear velocity is at the base-frame origin. Planar systems use

q = [theta, px, py, q_internal...]
v = [omega_z, vx, vy, qd_internal...]

The flat first-order state is always y = [q, v, auxiliary...]. Use pack_configuration, split_configuration, pack_velocity, split_velocity, pack_state, and split_state instead of splitting a state in half. These helpers preserve arbitrary broadcast-compatible leading batch axes.

For spatial systems,

qdot_quaternion = 0.5 [omega_world, 0] * q_quaternion
pdot = v_origin_world

where * is Hamilton multiplication. normalize_configuration preserves the quaternion hemisphere. retract_configuration left-multiplies a world-frame rotation increment and re-normalizes the quaternion.

Dynamics and actuation¶

Kinematics, Jacobians, energies, forces, and dynamics accept total q and v. Actuation and material passive mechanics contribute exactly zero base rows. The base frame itself is massless: the augmented inertia is generated by link, continuum, platform, and payload mass, without artificial base regularization.

JAX supports floating execution for every system. GVS, PCS, and PlanarPCS also expose floating Warp dynamics wherever the corresponding fixed system supports Warp. The fixed and floating paths share local continuum operators but use separate statically specialized root and accumulator kernels, so fixed kernels do not receive floating state or allocate base-sized scratch storage.

Controllers remain internal-coordinate controllers. For a floating robot they evaluate a temporary fixed model at the current runtime base pose, so kinematics and gravity use the current mounting. They intentionally ignore base velocity, acceleration, reaction motion, and floating/internal dynamic coupling, and they never actuate the base.