Changelog
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
[0.24.0] - 2026-11-20
Reusable CPU optimization interfaces, constrained IK reliability fixes, and diagnostics that distinguish solver status from actual robot behavior. Standalone optimization and opt-in acceleration/GPU paths retain their documented experimental status. Backend discovery currently exposes native math only; sustained saturation recovery and complete stopping are not guaranteed by this release.
Compatibility
- Native C++ interfaces and public structure layouts have changed. Rebuild the core library, Python bindings, and native applications together against matching headers; do not mix binaries from earlier releases.
Added
-
Lazy
embodik.backendsdiscovery and native numerical handles expose runtime capabilities without changing existing math dispatch, defaults or results. Handle solve attributes are the existing native functions, without an extra solve wrapper. No optional numerical or robot engine is registered implicitly. -
KinematicsSolver.get_collision_pair_floors()reads live collision clearance metadata without forward kinematics or distance queries. It preserves the distance observer's pair ordering and floor semantics; it is not a collision safety check. -
CPU
initialize_collision_recovery_floors(q_start)initializes unseeded recovery floors from startup signed distances capped by active pair margins, preserving nominal margins and acceleration settings. Existing native numerical tolerances remain unchanged. -
CPU acceleration
validate_candidate()andvalidate_candidate_with_velocity_collision()check a prescribed physical acceleration through existing hard-row and nonlinear admission without command optimization or candidate modification. Results report feasibility, not task achievement or complete stopping. Nominal envelopes, allocation, nonzero elastic history and collision-refinement budgets remain unsupported. -
Prescribed acceleration collision validation can explicitly select
CollisionCandidateValidation.PHYSICAL_SAMPLESto omit internal frozen construction rows while retaining caller constraints and sampled physical floors. The default remainsFROZEN_ROWS; optimization rejects the new mode. Physical sampling requires initially satisfied floors and zero repulsion deadband, and does not certify continuous clearance or complete stopping. -
Native CPU
AffineStateConstraintacceleration envelopes for fixed-base additive scalar coordinatesy=Cq+b, sharing state shaping, exact quadratic extrema checks and per-axis next-state viability. Complete stopping and collision integration remain explicitly unsupported. -
Experimental robot-independent CPU
solve_lsandsolve_qpinterfaces, with explicit result statuses, hard linear bounds and factor-preserving least squares.solve_lsalso accepts weighted soft affine intervals throughS,sl,suandweights, keeping hard constraints and original-variable ridge separate. The initial soft-bound implementation uses exact auxiliary projection variables. The initial QP interface requires positive definite objectives; GPU dispatch and general semidefinite programs remain unsupported. -
Default-off acceleration backend problem traces and replay, preserving affine objectives, hard-row sources, nonlinear refinement history and raw failures. Optional diagnostics identify Phase I outcomes and preferred MIN_ERROR QP attempts without changing execution or acceptance policy.
-
Opt-in fixed-base GPU
warp_polytopebackend for exact-ray primary SCALE velocity IK with native coupled linear configuration bounds. Native reduced coordinates have a checked full-space fallback; invalid lanes cannot publish unchecked commands. Collision, centroidal/CoM, torso, secondary, contact and acceleration constraints remain explicitly unsupported by this backend. -
Default-off
PositionStepOptions.allow_best_effort_posture_retrypermits a transactional retry of stalled or rejected unchanged velocity steps with strictly lower posture-only bands in MIN_ERROR, preserving primary targets and hard guards. -
Native CPU coupled configuration bounds for fixed-base additive scalar joints. Position-step inner states and retry horizons rebuild the velocity rows; outside seeds can move inward without projection. Automatic transfer of these velocity-solver rows into acceleration execution, including collision adapters, and contact execution, remain unsupported. The separate explicit
AffineStateConstraintacceleration API does not certify complete coupled stopping. -
Explicit original collision-floor anchors for velocity-only CPU position steps, with named-pair retention across commands, bounded candidate checks and final fresh all-pair validation. Legacy recovery remains the default.
-
Opt-in individual position/orientation merit budgets for CPU multi-target position steps, with physical velocity rows and finite-candidate validation. The default same-priority aggregate policy is preserved.
-
Opt-in CPU velocity/position-step problem snapshots and nominal hierarchical backend replay, including objective policies, variable mapping and per-target priority-candidate merits, constraint row families and continuity guard decisions. Recording is disabled by default.
Changed
- CPU position-step continuity uses one stationary-progress requirement for automatic target identity and explicit command revisions. Automatic low-progress holds remain reversible; explicit revisions retain their identity and latching behavior. This replaces the automatic mode's separate productivity criterion without changing constraints, constraint or satisfaction tolerances, or recovery budgets.
Fixed
-
The opt-in CPU direct MIN_ERROR acceleration route now accepts zero and subthreshold references when hard constraints require nonzero motion. Previously these references incorrectly skipped the requested quadratic optimization. Default and legacy routes retain their existing dispatch.
-
Opt-in CPU acceleration collision refinement selects a strongest normalized violating time sample for the first failed pair instead of always using its earliest failure. It retains one cut per refinement, the existing retry budget and complete sampled collision validation.
-
CPU velocity and acceleration collision-row selection no longer refills an underfilled candidate list with historical pairs culled at the current state. This prevents stale distances and nearest points from creating spurious constraints. Current near-floor rows and physical validation remain intact.
-
Collision distance queries reject finite results that contradict a sound separation bound for disjoint geometry. The existing cold-query retry recovers full distance and closest-point evidence without relaxing floors.
-
Generalized hierarchical solves calibrate projected active-constraint rank against the original row scale. A constraint already fixed by a higher task can otherwise turn cancellation roundoff into a spurious correction, changing the completed task image or rejecting a feasible lower-task solve. Original hard bounds and task-image checks remain unchanged; the legacy velocity route retains its existing inverse policy.
-
Authorized lower-task MIN_ERROR retries preserve repaired higher-priority images as exact constraints and reuse a verified full hard-set witness. This avoids numerical rejection caused by recomputing an already completed image; hard bounds, fallback permissions and prefix tolerances are unchanged.
-
A primary MIN_ERROR repair in a mixed hierarchy can use the certified Phase-I feasible point to initialize its existing optimizer when zero violates mandatory hard rows. The returned command must still pass optimization and feasibility checks; SCALE fallback authorization and higher-priority task protection are unchanged.
-
Bimanual viewer "Hold non-dragged arm" keeps the held hand at higher task priority while the commanded motion is unfinished, including after dragging stops. New input, mode changes and resets clear that ownership; shared torso control stays below active hand tasks. This is a task-priority policy, not a hard pose constraint or a guarantee of target acquisition.
-
Native builds require Eigen 3.4, matching the development baseline. Isolated Linux source builds and Linux wheel builds install pinned Eigen 3.4.0 headers. macOS wheels use Homebrew
eigen@3throughEigen3_DIR. -
Acceleration collision refinement uses the same cold, precise distance and nearest-point policy as floor and sample queries, preventing optimistic local correction rows. Physical floors and acceptance tolerances remain unchanged.
-
Acceleration collision sample validation uses the same cold, precise distance query as floor initialization and explicit-state constraint construction. Caller query tuning no longer permits accepting a sampled floor violation; physical floors, acceptance tolerances and sampling counts are unchanged.
-
Acceleration frame refinements can release their own local trust box when it prevents a certified feasible solve. Geometric correction cuts, caller constraints, nonlinear acceptance and the existing refinement budget remain enforced; caller rows are never selected for removal by their names.
-
Explicit-state CPU acceleration collision rows now budget current-interval displacement before their subsequent braking proxy, using physical-floor clearance. Satisfied-floor acceleration rows likewise budget integrated displacement, permitting use of positive clearance inside the legacy command reserve. Explicit deadbands, recovery rules, sampled geometry checks and legacy velocity-command behavior remain unchanged. This does not guarantee nonlinear stopping viability; applications still need complete-stop admission.
-
CPU acceleration and generalized linear solves now honor the opt-in direct
MIN_ERRORpreference when hard constraints were already prevalidated. A concrete feasibility witness is obtained before attempting the existing direct backend; physical checks and the default backend remain unchanged. -
Unallocated acceleration solves polish exact coordinate hard equalities using the existing hard-row and task-image certificates, preventing numerical residual commands on zero-rate locked axes without modifying input states.
-
Non-worsening collision floors tolerate arithmetic-sized distance differences when constructing no-approach rows, avoiding artificial separation demands at a satisfied structural floor. Raw distances and physical acceptance tolerances remain unchanged; larger violations still require recovery.
-
Nonlinear acceleration refinement permits one additional bounded correction near converging constraint boundaries without tightening the feasible set or changing the final physical checks.
-
CPU CoM support-polygon acceleration solves can use bounded nonlinear refinement to correct predicted outward boundary rates, including supported seeds within the configured boundary epsilon band. Outside-state policy and the original hard-row and nonlinear admission checks remain unchanged.
-
Collision velocity dampers permit stationary commands at satisfied recovery floors. The numerical reserve remains a no-approach band; recovery below the floor and approach bounds beyond that band are unchanged.
-
Collision trajectory validation reuses conservative clearance bounds at the seed when tracked geometry and initialized pair floors permit certification. Mutable geometry and unsupported cases retain exact distance checks.
-
The CPU affine solver can reject a coupled row inconsistent with signed-unit variable bounds before Phase I. Conservative numerical guards leave uncertain or unsupported arithmetic cases on the existing solver path.
-
Collision distance queries reject missing and failure sentinels before updating floors or caches. Invalid numerical results receive one deterministic cold retry with unchanged precision; unresolved failures remain errors.
-
Prescribed acceleration validation retains the optimizer's normalized row certificate and existing physical constraint tolerances across row units.
-
Explicit-state acceleration collision rows use isolated precise distance queries for both pair ranking and selected nearest points. Warm GJK history no longer perturbs their distance and nearest-point data at a fixed state. Legacy velocity queries retain their existing warm-start behavior.
-
Mixed hierarchies repair hard-invalid intermediate MIN_ERROR stages before lower tasks run, preserving original bounds, completed task images and fallback permissions. Existing all-MIN_ERROR and trailing-suffix optimizers retain ownership of their problems. Valid damped stages keep their existing construction.
-
Standalone CPU LS and positive-definite QP solves preserve the minimizing active face when the entire objective changes units, including explicit ridge weights and warm starts. Unrepresentable normalization returns
NO_PROGRESS. -
Shared constrained MIN_ERROR numerical solves retain least-squares factors for stable residual gradients and QR steps, avoiding false iteration stalls in redundant task directions without weakening hard rows or tolerances.
-
Undamped legacy hierarchical solves use a rank-aware inverse for projected tasks and optimize a trailing MIN_ERROR suffix with the existing constrained quadratic solver, preserving completed task images and hard bounds.
-
Single-step finite-zone MIN_ERROR recovery checks bounded native proposal fractions near earlier satisfied pose boundaries. Original hard rows, mandatory velocity bounds, nonlinear collision floors and finite pose zones remain required; this does not guarantee sustained recovery.
-
Explicitly enabled CPU MIN_ERROR position-step recovery can serve the first unsatisfied Cartesian priority while earlier tasks remain inside their finite pose zones. A zero-motion backend success no longer prevents this bounded trial. Earlier pose budgets, physical bounds and original collision-floor publication checks remain mandatory; sustained recovery is not guaranteed.
-
Finite MIN_ERROR recovery distinguishes priority-validation rejection from intentional continuity holds. A permitted weighted trial may lead to a fully validated nominal correction; that command is retained without incorrectly requiring the final backend to report weighted fallback.
-
CPU multi-target Cartesian MIN_ERROR steps can use an enabled constrained weighted fallback after finite command rejection, even when the nominal linear solve succeeded. The bounded retry retains original hard guards and requires actual commanded primary-error reduction.
-
Opt-in best-effort posture recovery retries rejected finite candidates from the incoming configuration even when their diagnostic output is nonzero. An unaccepted candidate no longer suppresses recovery as apparent motion.
-
Finite pose-budget correction uses analytic physical norm gradients, including fractional masks and soft-task joint exclusions, avoiding repeated disposable FK probes away from the orientation log-map branch.
-
Individual finite pose-budget corrections reserve a bounded part of observed nonlinear overshoot inside the original tolerance, avoiding repeated near-boundary rejections that can stall feasible redundant motion.
-
Opt-in CPU velocity refinement recovers numerically invalid trailing MIN_ERROR objectives using constrained least squares, preserving achieved higher-task images, task modes, and original hard bounds without skipping suffix tasks.
-
Native hierarchical solves reject zero-row objective matrices explicitly instead of entering an invalid numerical decomposition.
-
Opt-in CPU SCALE refinement protects achieved weak higher-priority directions using numerical rank independently of task acceptance tolerance. Redundant prefix rows retain an orthogonal nullspace for lower objectives.
-
Original-floor collision execution preserves a feasible Cartesian objective through redundant joint motion before tangent projection. Multi-target pose-budget retries also correct finite collision curvature and retain bounded budget refinement, preventing avoidable holds with coupled guards.
-
Collision row and recovery checks use an enclosing-sphere certificate before box/SAT refinement when it already proves the required clearance threshold. Ambiguous pairs retain stronger bounds and precise distance validation.
-
Opt-in SCALE ray certification preserves legacy lower-task projected preferences and skips incompatible lower raw-ray construction, retaining primary protection while avoiding unnecessary feasibility searches.
-
Position-step
computation_time_mscovers the complete native call, including inner iterations, recovery and final guards, instead of the last velocity solve. Rebaseline historical timing comparisons across this correction. -
Explicitly authorized primary MIN_ERROR retries also cover final collision rejections and held commands whose backend already reported MIN_ERROR. The complete adapter is retried once from the unchanged state; original targets and physical guards remain active, and acceleration commands are excluded.
-
CPU and Warp SCALE bound-release searches retain strictly verified positive checkpoints when numerical direction and blocking-row thresholds disagree near a vertex, preserving ray, hard bounds and prior task values without claiming optimality.
-
Explicitly authorized CPU position-step MIN_ERROR fallback can retry a nominal positive-scale command rejected by final endpoint validation. The bounded retry retains targets, physical guards and protected pose budgets.
-
Anchored CPU position steps can correct finite collision curvature with bounded local row retries, allowing redundant joints to support motion tangent to a clearance boundary without relaxing the original floors.
-
Physical SCALE-ray recovery honors explicit per-target pose budgets instead of unnecessarily contracting a valid ray through a hidden strict merit check. Unbudgeted recovery retains its existing acceptance policy.
-
The acceleration velocity-collision adapter explicitly rejects original-floor anchors until stopping feasibility is supported, rather than treating its sampled endpoint checks as an acceleration safety contract.
-
Explicit CPU individual-budget position steps use bounded finite-curvature correction rows and partial-scale redistribution, allowing redundant joints to support motion inside tight pose budgets while retaining final checks.
-
Opt-in partial SCALE refinement can rebuild an off-ray damped legacy seed from a verified feasible task-entry witness, preserving earlier task images and accepting only a certified larger scale under the original hard rows.
-
Fresh collision-pair distance queries use isolated cold GJK state and tighter distance precision. Unrelated collision-query history no longer changes the reported clearance at an identical configuration or falsely rejects an unchanged seed under an original-floor policy.
-
Explicit original-floor mode uses matching precise cold distance queries in constraint construction, candidate backoffs and final checks, avoiding repeated admission of proposals that its final clearance check rejects.
-
Constrained position-step merit retries now reduce the interval or terminal fraction by at least half after rejection. Near-one backtracking fractions no longer consume every retry on essentially the same rejected nonlinear step; the retry cap and final constraint checks are unchanged.
[0.23.3] - 2026-11-18
This patch adds official Rainbow RB-Y1 fixed-base adapters and keeps Linux
wheels building on Eigen 3.3. The unqualified rby1 preset follows official
M v1.3. The previous robot_descriptions bimanual profile remains available
as rby1-legacy.
Added
- Official Rainbow RB-Y1 A v1.2 and M v1.3 model adapters, pinned to SDK v0.10.1,
with cached assets, ready configurations and basic/collision/bimanual example
presets.
rby1aliases official M v1.3;rby1aselects A v1.2. The old bimanual profile is explicitly namedrby1-legacy. Fixed-base IK retains 20 torso/arm DOFs; wheel, head and finger joints are locked. SDK capsules are preserved as equivalent standard URDF primitives. RobotVisualizeraccepts an expliciturdf_pathfor its ViserUrdf backend so custom or adapted models can use the same description for solving and display.
Fixed
- SVD factor checks no longer call
info()on Eigen 3.3. The manylinux wheel image ships that version, which exposes singular values but notSVD::info(). - The bimanual example opens official and legacy RB-Y1 descriptions on visual geometry. Collision and both-geometry views stay available in the dropdown.
- Whole-body posture sliders no longer duplicate joints that already have a manual joint slider, and manual joint control wins for those joints.
- Checking or unchecking Auto IK Solve copies the current end-effector pose into the arm targets.
[0.23.2] - 2026-10-16
This release improves constrained velocity and acceleration IK robustness and reduces repeated numerical and collision work. Recovery remains local and bounded: it does not guarantee escape from every stalled configuration, a collision-free swept path, or a fixed response-time deadline. Experimental corridor recovery and optional refinement routes require explicit opt-in. GPU acceleration support remains a subset of the CPU constraint API; see GPU solver capabilities before selecting a backend.
Added
-
AccelerationSolveOptions.refine_partial_scaleexposes opt-in bounded refinement of feasible directional acceleration commands. -
Acceleration collision lifting supports opt-in bounded sampled-distance corrections for fixed-base scalar revolute/prismatic models, retaining original limits and validation and exposing separate retry diagnostics.
VelocityCollisionLiftOptions.max_refinement_iterationsstays0.refinement_trust_radiusandrefinement_clearance_reservebound each local correction. -
AccelerationSolveOptions.allow_best_effort_lower_tasksopts in to retaining a validated priority prefix when numerical recovery cannot optimize optional lower MIN_ERROR tasks. The default remains disabled. -
Fixed-base GPU solvers expose opt-in partial SCALE refinement through
refine_partial_scale, with advanced origin and seed-admission controls for the native Warp and cuSOLVER backends. -
Experimental
CartesianCorridorRecoverygenerates hypothetical free-hand endpoints and validates bounded native velocity rollouts before activation. Executed steps retain explicit pose, joint, collision and support checks; acceleration/contact recovery and swept collision certification are unsupported. Optional measured-state revalidation, pose-zone reentry and remembered gain backoff order remain disabled by default. -
SolverRuntimeConfig.refine_partial_scaleexposes opt-in CPU refinement of feasible partial directional SCALE solutions. Explicit CPU refinement also repairs off-ray damped results, including reported full-scale commands, using a verified feasible witness while preserving earlier task images and hard rows. The default remains disabled. -
Constrained weighted velocity IK accepts an optional validated feasible seed for primal optimization when a preceding solve already provides one.
-
Native acceleration options expose default-off
prefer_direct_min_error_qpto prefer a feasible-primal quadratic route for all-MIN_ERROR hierarchies, preserving hard bounds, earlier task images and fallback authorization. -
Opt-in position-step velocity candidate records expose each native velocity, integration interval, and nominal manifold motion before acceptance guards.
-
Opt-in
PositionStepOptions.record_collision_candidatesrecords nominal collision checks and backoff configurations with effective recovery margins and acceptance decisions. Records usePositionStepCollisionCandidate. Recording is disabled by default. -
examples/harnesses/joint_limit_recovery_harness.pyreproduces CPU velocity joint-limit redistribution on a generated two-slider robot. It is a measurement harness, not an acceleration-solver example. KinematicsSolver.evaluate_collision_pair_distances(q)returns a fresh distance and the configured minimum for every active collision pair. The query does not use the constraint-row budget or a cached closest pair, and it leaves the robot state unchanged.
Changed
-
Native rebuild: solver option and result layouts changed. Rebuild native consumers, the core library, and Python bindings together for this release.
-
Python migration: acceleration-option constraint and objective lists now return owned record snapshots. To change a stored record, edit the returned list and assign it back to the option. In-place edits to a fetched record alone no longer update the option. This prevents references from dangling when the original list is replaced; see the update example.
-
AccelerationSolveracceptsSCALE_ELASTICas SNSSCALEplus a nominal-position band inside the model limits. The band expands only for that mode, and only up toelastic_delta_maxand the physical joint limits.reset_elastic_band()clears the persistent band, andget_elastic_band_deltas()reports it. Velocity, acceleration, collision, and other hard rows stay fixed.
Fixed
-
Acceleration nominal-position elasticity ignores
MIN_ERRORscale sentinels in registered-task and centroidal diagnostics. A fully achieved elastic task no longer expands unsaturated joint bands merely because another objective uses minimum-error optimization. -
Acceleration collision linearizations refresh the current pair catalog, avoiding stale candidate subsets in explicit-state and stopping rollouts.
-
Objective fallback reuses hard-feasibility witnesses only after validating them against the current original constraints. Collision sample validation skips stronger bounds when enclosing spheres already certify clearance.
-
Nonlinear geometric endpoint state and braking checks use the same entry tolerance as the next state-box construction, allowing existing refinement to repair small violations before a successful command is returned.
-
Hard-constraint feasibility search recognizes a fully pinned active set without following spurious numerical directions, while retaining multiplier release, residual checks, and existing infeasibility certificates.
-
Geometric path validation retains quarter-interval checks when the adaptive grid changes, and CoM refinement uses the same sample locations. Existing sample times retain their original arithmetic to avoid roundoff changes in nonlinear corrections.
-
Python acceleration-option constraint and objective lists return owned record snapshots, preventing dangling references, corrupted data and crashes when saving, replacing and restoring lists.
-
Generalized numerical recovery can preserve a feasible mixed SCALE/MIN_ERROR prefix while repairing a trailing MIN_ERROR task, without changing earlier achieved images, directional scales, hard limits, or fallback authorization.
-
Unresolved hard-feasibility searches can retry objective-null trial-bound release; promoted witnesses must pass every original row at its existing tolerance. Previously feasible and proven-infeasible results are retained.
-
Position stepping can refine finite primary MIN_ERROR pose endpoints while preserving the original requested pose and integration limits.
-
Tight-frame acceleration recovery handles SO(3) state and braking violations and groups violated scalar faces into bounded corrective solves, retaining task policies and full nonlinear acceptance.
-
Generalized affine SCALE recovery retries unusable Phase-I ray seeds at a tighter precision, avoiding lost directional motion while preserving valid seed searches, hard bounds and task checks. An independently revalidated auxiliary-scale projection can avoid that retry without changing the physical command or acceptance tolerances.
-
Authorized best-effort recovery retains validated finite commands even when a rank-deficient task reports infinite conditioning. Unoptimized lower tasks remain flagged; original hard rows and higher task images stay protected. Quadratic recovery also reports attempted iterations when a search fails.
-
Enabled partial-SCALE refinement gets its own bounded attempt even when an earlier zero-scale recovery already ran for the same objective.
-
Recovery of a MIN_ERROR suffix after a SCALE prefix can reuse a certified feasible quadratic solution immediately when roundoff in weak task-null directions prevents convergence, retaining hard bounds and protected task images. Other minimum-error recovery paths retain their stopping rules.
-
Bounded acceleration collision recovery can retry outside an exhausted internal trust box while retaining caller constraints and physical limits.
-
CoM position and velocity getters share a consistent cache regardless of access order, including tiny nonzero velocities.
-
Successful unallocated acceleration solves can correct small state-box residuals after rechecking hard constraints and achieved task images at the existing numerical tolerances.
-
Nonlinear CoM acceleration corrections account for configuration and velocity changes along the commanded path when constructing local refinement rows.
-
Roundoff-sized position-boundary failures can recover with a physically capped braking command when its endpoint and next state remain valid.
- An almost-zero task error no longer suppresses an already authorized minimum-error recovery retry after a hard-bound rejection.
- Minimum-error recovery can release a negative-dual trial bound before rejecting an ill-conditioned working set; success retains its existing stationarity and hard-bound checks.
- Converging nonlinear CoM curvature corrections have a bounded eight-retry budget, avoiding premature rejection after four corrections.
- Numerical retries retain an already authorized minimum-error fallback after an internal hard-bound rejection, without demoting strict SCALE objectives.
-
Collision row caches refresh when joint acceleration limits are enabled, disabled, or changed.
-
Directional CPU recovery can initialize a feasible affine task ray when zero acceleration does not satisfy the moving-state task equation.
-
Phase I no longer initializes strictly interior inequalities as active equalities with their initial slack attached.
-
Invalid singular-vector output from the fast SVD triggers a Jacobi SVD retry with the same rank threshold and damping policy.
- Numerical recovery of a trailing
MIN_ERRORobjective retains feasible higher-prioritySCALEtask images and all original hard constraints. -
CoM acceleration violations caused by changing command-path geometry can trigger bounded corrective solves, followed by full acceptance validation.
AccelerationSolverResult.nonlinear_refinement_iterationsreports retries. -
Hard-constrained minimum-error numerical recovery now considers moving lower-priority objectives when the primary objective is a satisfied hold. Recovery preserves the achieved higher-priority task images.
-
AccelerationSolvercanonicalizes machine-roundoff excursions onto the original physical acceleration bounds before coupled validation and state integration. Joint state-box failures identify the joint and physical state. -
Acceleration-limited position stepping reconciles roundoff at a scalar braking face using its existing floating-point comparison allowance. Genuine conflicts still fail without advancing velocity history.
-
Acceleration-limited position solves account for true scalar joint limits before integration, including when elastic task policies are enabled. Rejected priority candidates cannot commit an acceleration-infeasible zero hold as accepted velocity history.
-
Coupled outer CoM projections use tighter numerical accuracy, snap scalar joint bounds, and recheck coupled rows before accepting or restoring a command.
-
Failed explicit CPU
MIN_ERRORhierarchies can release incompatible trial bounds through feasible active-set recovery while preserving earlier task images and the original hard constraints. -
Acceleration-limited position steps preserve CoM velocity rows during outer realization and validate emitted commands using the outer control interval.
-
Opt-in GPU refinement can recover a rounded float32 seed from a feasible zero origin while retaining final equality, box and improvement checks.
-
A stationary
NO_PROGRESSpreferred-lock attempt now permits the normal position solve, even when it lies inside the coarse lock-error tolerance. Settled successful holds and moving candidates retain the existing policy. -
With joint acceleration limits enabled, position-step objectives containing only frame tasks retain the physical full-pose Jacobian near scalar joint limits, so lower-priority motion preserves the actual primary task image. Configured joint bounds continue to constrain allowed motion.
-
Acceleration-limited position commands and braking rollouts honor configured per-pair collision floors instead of reimposing nominal clearance after the task solve. Per-pair validation and the independent penetration guard remain.
-
Joint acceleration constraints and position-step braking predictions use the configured maximum without the former one-percent expansion. Direct velocity and outer position commands share the exact step with collision stopping certificates; existing hard-safety precedence is preserved.
-
Legacy velocity IK reports
INFEASIBLEfor an exactly zero hard constraint row whose interval excludes zero beyond the existing bound tolerance, instead of exhausting iterations. Nonzero rows and permitted softening are unchanged. -
Position-step continuity no longer discards a validated step that brings previously unsatisfied tasks into tolerance at a stationary monitoring boundary. Already-satisfied holds and hard-constraint checks are preserved, with regression coverage for both position-step overloads.
-
Direct legacy linear/velocity primary SCALE results no longer report success for structurally inconsistent task rays. Explicit primary MIN_ERROR fallback remains eligible; position-step projection, lower-priority preferences and supported regularization are preserved.
-
Opt-in position-step seed corridors bound scalar joint displacement across adaptive and multiple inner iterations using the outer command interval and effective velocity caps. Corridor bounds enter the velocity hierarchy without component clipping; failed strict primary vectors retain earlier accepted motion.
-
GPU undamped inverse mode shares identical accumulations for its two output buffers and checks matrix finiteness once per factor. Rank, convergence, overflow and output-clearing checks are retained.
-
Position-step collision escapes and joint-limit desaturation preserve the matching velocity solve's physical hard rows, locked coordinates and endpoint safety checks. Permitted per-pair overlap no longer triggers an escape by itself. A held escape rejected for worsening protected tasks reports
NO_PROGRESSwithout counting it as accepted recovery motion. -
Elastic full-pose position steps prefer a checked true-limit SCALE ray when integration clipping would change the requested Cartesian direction. Original hard rows and lower-task modes remain enforced.
-
Bounded-ray retries re-solve the hierarchy with smaller primary requests when nonlinear integration worsens pose error. Accepted candidates retain their checked lower-task motion and diagnostics through subsequent repair.
-
GPU bound-release refinement reuses fixed equality QR rows within each active-set phase, retaining rank, finite-input, task-ray and bound checks.
-
GPU bounded task completion reuses the immediately preceding primary undamped factor when its matrix and numerical settings match. Failed or non-finite cached factors retain independent factorization and status checks.
-
GPU bounded task completion skips an unused blocker-factor inverse after accepting the preceding violator solution, retaining bound and non-finite input checks.
-
Coupled collision recovery removes every mandatory separating direction from a task once it requires tangent projection, preventing an infeasible task ray without enabling minimum-error fallback.
-
Zero and near-zero CPU
MIN_ERRORtargets retain hard-row feasibility when bounds require nonzero motion, instead of taking the stationary shortcut. -
Satisfied zero CPU task objectives preserve their achieved values against lower-priority motion. Zero targets with residuals from earlier tasks are solved inside the remaining nullspace instead of silently skipped.
-
Unconfigured velocity frame tasks and stationary manipulability gradients leave secondary motion available. Explicit zero velocity references still preserve their achieved values; physical Jacobian queries are unchanged.
-
Stationary collision recovery retains its hold state while correcting back toward an earlier best pose, preventing repeated unproductive reopen cycles.
-
The Spot command helper balances small arm reaches, larger base-assisted reaches and conditioning recovery at its default locomotion sensitivity. Separate forward, lateral and yaw restoration gains retain arm participation in lateral and yaw commands after physics settling while preserving forward base assistance. Changing sensitivity affects x/y/yaw assistance while retaining height and roll/pitch restoration.
-
Native GPU inverses avoid spectral work for exactly zero matrices and finite unused bounded-completion factors while retaining replay output clearing and non-finite input/status checks.
-
Independent Newton CoM/centroidal evaluators preserve Warp stream restoration under concurrent worker calls, avoiding an obsolete default stream after interleaved scopes. Each evaluator still requires exclusive buffer ownership.
-
Generalized affine SCALE results recover the realized intermediate scale when active hard rows eliminate the remaining task direction, retaining original hard bounds and exact task-ray validation.
-
Legacy native SCALE results no longer report positive-scale success when an unactuated primary task row has a nonzero target. Explicitly authorized primary
MIN_ERRORfallback remains available. -
Task-layout diagnostics reflect active frame tasks rather than an automatic policy state. Raw pose tasks and fixed-layout groups no longer trigger ineffective split retries when no automatic group can switch.
-
Explicit Cartesian orientation tasks preserve their physical Jacobians near joint limits, retaining legal inward rotations and split-pose recovery while joint velocity constraints enforce the permitted motion.
-
Elastic position steps can repair a joint realization before integration clipping removes achieved primary motion, while retaining the primary image, existing constraints and endpoint safety checks.
-
GPU bound release can compensate mandatory inward joint motion while retaining the homogeneous primary task. It also retains feasible task-null motion when the task ray collapses to zero scale, and can recover a positive task ray when no feasible zero-task starting velocity exists. Invalid moving realizations can also be repaired while preserving their achieved primary velocity; valid moving realizations bypass the search.
-
Native hard-bound validation no longer depends on summed task scales, including mixed
SCALE/MIN_ERRORresults. Bound recovery can preserve achieved primary motion before selecting weighted fallback. Stationary commands can recover compensating task-null motion, explicitly enabledMIN_ERRORretries remain available, and proven contradictory hard intervals report infeasibility. -
Native task scaling preserves productive motion when task-independent joints require a nonzero velocity to satisfy a scalar box. A verified feasible starting velocity prevents those bounds from collapsing the task scale.
-
Constrained continuity holds can reopen for productive coupled motion while already satisfied task blocks remain within the existing satisfaction tolerance.
-
Position integration no longer adds inset-restoration motion to an exactly zero locked or globally excluded joint command at a valid limit.
-
Cartesian position tasks retain legal inward motion near joint limits, independently of Cartesian axis signs, in velocity and position-step solves. Physical position Jacobians preserve task/nullspace combinations during singularity recovery, while velocity constraints enforce permitted directions.
-
Held fixed-base
SCALEpose steps can recover with bounded physical-task retries and radius refinement, preserving sampled constraints and bounded pose errors through layout retries and resetting recovery when commands change. -
Stationary minimum-error position steps reject worsening of the worst target promptly when no hard-constraint tradeoff requires motion, and resume when targets change. Scaled-step productivity retains its existing dwell policy.
-
Position-step collision rejection respects effective per-pair recovery floors and overrides instead of imposing global nominal clearance again. The independent penetration guard remains active. Iterative position IK also checks the candidate distance before rejecting motion from a safe seed.
- Constrained stationary position-step holds can reopen when a validated candidate makes sufficient progress on every unsatisfied task-error block without worsening another block in the current priority group. Earlier oscillation no longer permanently vetoes fresh recovery progress.
- A zero-scale CPU velocity task can recover by releasing an unnecessary
saturated constraint. Recovery preserves the task ray, achieved prior task
values and original hard intervals, and requires a feasible zero-scale
witness. Native
warp_srinvandcusolver_srinvcombined tasks use a graph-compatible bound-release kernel for zero velocity in boxes containing zero. Existing positive-scale behavior is retained. - Native GPU bounded-completion rank checks use reusable native inverse buffers during graph capture. Singleton matrices use an exact tensor inverse, avoiding a host-synchronizing Torch SVD in that case. Spectral failures continue to veto publication.
- A consistent explicit zero row, repeated row, or linear combination of earlier rows is no longer a rank failure. The same saturation applies to a consistent full-rank row whose uniform scale is zero, so a reachable task still finishes past the default 20-iteration cap. The ESNS loop saturates every bound violated by the full-scale step when that set still reaches the target. When it does not, only the joints that force scale 0 are saturated. When that full-scale velocity exceeds a free bound and the pinned joints are at the origin, the reported scale is the largest value that stays inside the box. A positive uniform scale is left unchanged. A structurally singular Jacobian or an inconsistent extra row keeps the original row-count stop. An all-zero Jacobian reports scale 0 for a nonzero target. Inconsistent targets still scale, and hard bounds stay in force.
- The GPU native velocity solve, FI-PeSNS, and PPH-SNS use that same completion for one consistent task, including a full-rank row blocked at scale 0, a pinned zero-width bound, and the same partial scale. A step that does not move a nonzero target reports scale 0. Other GPU tasks keep uniform bound scaling.
- Tall task matrices no longer combine the full left singular vectors with the shorter per-singular-value damping diagonal. That size mismatch could produce non-finite state in release builds.
- Velocity clamping keeps sparse position-limit rows and coupled velocity rows in their own layout. Position bounds no longer clamp those extra rows as if they were joint velocities.
FrameTask.get_jacobian()refreshes the cached task error when the cache is stale, so reading the Jacobian first still sees the updated task.- Priority acceptance no longer adds numerical slack on top of an already exceeded baseline, so a protected merit cannot ratchet upward across control ticks. Every nonzero position step is checked against that budget.
[0.23.1] - 2026-09-25
Fixed
- Linux wheels build on the
manylinux_2_28image dated 2026-09-05. The image selected by the previous cibuildwheel pin could not refresh AlmaLinux 8 package metadata, so the 0.23.0 Linux wheels were not published.
Changed
- The README now leads with the PyPI quick start, and the experimental GPU
section uses
pixi run setup-gpu-wbc.
[0.23.0] - 2026-09-24
Added
- Added an experimental model-derived Newton/Warp whole-body GPU API with fixed- and floating-base adapters, device-resident batching, collision and CoM constraints, torso bounds/staging, posture, secondary priorities, adaptive time steps, and acceleration-history limits.
- Added explicit GPU capability discovery and CPU/GPU selectors across the public Panda, IIWA, bimanual, Unitree G1, and Spot examples.
- Added per-world
reset_mask/valid_maskinputs, categoricalworld_statuscodes, and in-placereset_state(mask)for the velocity GPU WBC batch path so one invalid or finished environment no longer rejects or clears the whole batch. - Added
measure_device_batch()for solver-path host-dispatch, synchronization, and CUDA allocator snapshots. Full-workload RL profiles remain application-owned.
Fixed
- Aligned the experimental CasADi FI-PeSNS and PPH-SNS SRINV defaults with
KinematicsSolver: singular-value tolerance0.1and damping0.1. The generated GPU path continues to reproduce the CPU extended-SRINV formula, including its global and per-singular-direction damping terms. - Kept FI-PeSNS feasibility refinement from reapplying damped task corrections, so multiple fixed penalty iterations preserve the CPU extended-SRINV result instead of progressively weakening singular-direction damping.
- Stopped reducing GPU WBC input validation with a host
.tolist()on every solve. Value checks stay on device per world, and only layout/dtype mismatches raise. Runtime posture weights now bind Torch through the solver instance instead of a missing global name. from_robot()rejects a missing or wrong-baserobotbefore CUDA setup. The GPU guide now states quaternion layouts, active-configuration shapes, and the per-worldworld_statuscodes.- Added
pixi run setup-gpu-wbc, which installs the CUDA environment, a compatible Torch wheel, and Newton in one step. - Finite GPU WBC joint positions outside their URDF limits are projected onto
those limits before the solve. Infinities, NaNs, and degenerate quaternions
still return
WORLD_STATUS_INVALID_INPUTand keep the caller's configuration, as do worlds excluded byvalid_mask.
[0.22.0] - 2026-07-29
Added
- Added validated RobotModel centroidal quantities for total mass, centroidal
momentum matrix and momentum, matrix derivative, and physical
dAg(q, dq) * dqbias for fixed- and floating-base models. - Added an absolute centroidal momentum task, selected-axis hard momentum bounds, commanded-velocity capture point, and finite-difference ZMP to the velocity solver.
- Added fixed-base centroidal momentum-rate objectives and bounds, predicted capture-point constraints, physical centroidal-rate ZMP constraints, positive vertical-force gates, and accepted-state diagnostics to the acceleration solver.
- Added visual centroidal momentum, capture-point, and velocity-ZMP controls to the Panda CoM and bimanual whole-body IK examples, with non-visual velocity and acceleration composition checks retained as tests.
Changed
- Made velocity ZMP require explicit current velocity through
solve_velocity_with_state()instead of relying on a previous solver command or other hidden history. - Extended
solve_position_step()with caller-ownedPositionStepOptions.current_joint_velocity, allowing its main interactive path to enforce velocity ZMP alongside momentum and capture-point controls. - Reused one support-polygon geometry implementation across CoM, capture-point, and ZMP constraints, including margin, half-plane, inradius, and root-fixed-frame validation.
- Rejected moving support frames for velocity CoM polygons because their frame motion is not part of the fixed-frame Jacobian contract.
- Made native analytic collision certification reject centroidal momentum-rate bounds, capture-point constraints, and ZMP constraints until those combined hard families provide a shared predicted-state certificate.
- Documented centroidal row ordering, units, gravity and support-plane conventions, and the fixed-base capability boundary. Fixed-base ZMP does not claim floating-base contact-force feasibility or dynamic balance.
- Extended native solver option and result layouts; C++ consumers must rebuild
embodik_coreand the Nanobind extension together for0.22.0.
[0.21.1] - 2026-07-28
Changed
- Modularized the velocity, position-step, and fixed-base acceleration solver implementations into responsibility-focused translation units without changing their public APIs, supported capabilities, numerical results, or exported symbol surfaces.
- Replaced broad acceleration access to velocity-solver collision internals with a source-private provider that preserves collision-row ordering, validation, and exact-query accounting.
- Preserved the public solver declaration and exported-symbol surfaces while keeping modular velocity, position-step, and acceleration dispatch within their established latency budgets.
[0.21.0] - 2026-07-23
Added
- Added a fixed-base acceleration-level eSNS API with Python bindings for compatible joint state boxes, task and affine rows, effort limits, fixed-contact kinematics, geometric constraints, and explicit diagnostics.
- Added sampled velocity-collision row compatibility and continuously certified native sphere-sphere collision support with distinct result flags.
- Added velocity/acceleration solver-level selection to the basic and collision-aware examples, gated by the active model and safety contract.
Changed
- Kept velocity collision pair filtering authoritative for the sampled acceleration compatibility path, including include/exclude pairs, active per-pair floors, row ordering, and exact validation accounting.
- Documented the acceleration solver as fixed-base, scalar-joint, and non-hard-real-time; floating-base dynamics, wheel constraints, and dynamic contact forces remain outside the stable surface.
- Kept the shared task virtual interface and object layout unchanged; source consumers must still rebuild the core library and Nanobind extension together.
- Defined the pre-1.0 versioning contract so new public solver capabilities use minor releases while compatible fixes and internal improvements use patches.
- Documented acceleration compatibility for every runnable example; velocity remains the default and acceleration selection stays limited to examples that explicitly own compatible state and constraint policies.
[0.20.18] - 2026-07-22
Changed
- Made finite position-step hierarchy validation aggregate task blocks at the same priority, preserving lexicographic priority without freezing productive bimanual and whole-body tradeoffs.
- Reused validated backtracked directions for unconstrained velocity-level steps and skipped redundant shorter-timestep retries when no admissible fraction exists.
Fixed
- Restored continuous G1 single-target oscillation, whole-body torso-bias recovery, and split/Auto bimanual progress while retaining hold-last-target behavior at genuinely exhausted joint limits.
- Kept stationary-target regression holds responsive to each commanded task while limiting continuity decisions to the highest unsatisfied priority.
[0.20.17] - 2026-07-22
Added
- Added manipulability and joint-limit avoidance tasks, including C++ and Python APIs, for lower-priority conditioning without overriding commanded Cartesian motion.
- Added an opt-in active joint-limit non-worsening policy that preserves inward and tangent motion near finite scalar limits, including sampled braking when acceleration limits are enabled.
- Added position-step controls for whole-step configuration caps, caller-owned continuity identity, continuity reference frames, preferred-lock candidates, and protected-task position/orientation tolerances.
- Added explicit position-step hold and preferred-lock diagnostics, APIs to synchronize the applied acceleration reference, and post-step collision query counters for controllers that hold or post-process solver output.
- Added
PostureTask.set_reference_configuration()so applications can move a regularization anchor without declaring a new posture command every tick.
Changed
- Kept finite position steps inside velocity, acceleration, active joint-limit, collision, and protected-task constraints while preserving useful progress through nonlinear refinement.
- Made preferred-lock arbitration evaluate the locked candidate and fallback from the same entry state, preserving one physical integration step while allowing useful arms-first progress before shared-body fallback.
- Improved collision-row retention, tangent-space task projection, conservative post-step validation, and broadphase certification so constrained motion can slide along a contact boundary without sacrificing the configured recovery floor.
- Treated
max_constraintsas a nominal collision-row budget: penetrating and floor-critical pairs remain represented when safety requires additional rows. - Used the configured structural floor as the recovery and retention target for pairs first observed inside the global collision margin, instead of pinning every positive-clearance pair at its first observed distance.
- Kept task-local joint exclusions local to their tasks so collision recovery can still use globally available joints.
- Updated the public bimanual example to cap Auto-mode torso contribution, accept measurable arms-only progress before fallback, and use a lower default adaptive-dt scale for smoother large target transitions.
- Updated GitHub checkout, Python setup, Pages, and artifact actions used by CI, documentation, wheel, and release workflows.
- Automated version-bump releases after merge to
main: synchronized package metadata and the dated changelog entry are validated before the version tag is created and the wheel/sdist/PyPI workflow is dispatched.
Fixed
- Prevented infeasible or stationary targets from producing residual self-motion after useful progress is exhausted; intentional holds are now reported explicitly to callers.
- Prevented stationary workspace-boundary targets from accumulating regressive velocity-level steps after marker motion stops, while retaining productive convergence through smaller position/orientation error trades.
- Improved recovery from fully extended, singular, and active joint-limit configurations without requiring a joint-space reset.
- Prevented conditioning, acceleration projection, and lower-priority tasks from spending active joint-limit slack or returning finite steps outside the configured hard limits.
- Preserved primary task and grasp continuity across preferred-lock handoffs, acceleration projection, target changes, and collision-pair switches.
- Preserved collision recovery floors across cache refreshes, active-row switches, target changes, and diagnostic probes; non-finite collision evidence now fails closed without replacing warm solver state.
- Distinguished recoverable finite numerical stalls from invalid non-finite input so valid constrained commands can retry without hiding malformed data.
[0.20.16] - 2026-06-08
Added
- Added soft per-joint joint metric controls (
set_joint_metric_weights,clear_joint_metric_weights) with Python bindings so applications can bias torso-vs-arm contribution without hard-excluding fallback DOFs. - Added per-joint velocity-limit overrides (
set_joint_velocity_limit,clear_joint_velocity_limit_overrides) for safety and hard-lock use cases. - Added bimanual teleop controls for torso contribution, optional torso marker
control, task-space speed caps, and a
Torso Policydropdown withFree,Locked, andDecoupledmodes. - Added regression coverage for joint metrics, velocity-limit overrides, arm-joint classifiers, torso/arm ownership, and far-target damping in the shared bimanual teleop app.
Changed
- Made production
pixi run upload-pypirefuse sdist-only uploads unless an explicit recovery override is set, so releases do not reach PyPI without the repaired wheel artifacts. - Updated the shared bimanual solver fixture to use the same arm-joint classifiers as the interactive helper.
Fixed
- Kept decoupled torso-marker ownership asymmetric: end-effector tasks exclude torso-chain DOFs, while the torso task keeps arm DOFs available so tools can be held in place during torso motion.
- Kept marker-off bimanual control in
Freewhole-body mode by default so torso DOFs can support end-effector target motion when no explicit torso marker is active.
[0.20.15] - 2026-06-02
Added
- Public docs — collision and robustness guides:
docs/collision_constraints.md(Speed / Balanced / Precise tuning, pairwise bounds, post-step guards, batch IK notes) anddocs/solver_robustness.md(adaptive dt, elastic band, auto task layout, weighted fallback, stall handler, diagnostics), plus adocs/guides/index.mdreading-path hub and tuning-mode demo video. - Non-worsening floor regression coverage: expanded
test/test_collision_non_worsening_floor.pyfor margin-floor recovery and initially penetrating pairs.
Changed
- C++ position-step penetration guard: tightened post-step rejection when a pair is already materially penetrating so accepted steps cannot keep drifting deeper; added margin-floor-aware worsen tolerances and recovery seeding for pairs first seen in penetration toward the configured structural floor (capped by the active collision margin).
- MkDocs layout: reordered Guides and Examples navigation, grouped the home-page doc index by intent (Learn / Configure / Reference), and expanded cross-links from API and example pages.
Fixed
- Incremental penetration on
SUCCESS: C++ position-step integration no longer accepts small deepenings when an actionable pair is already inside the material penetration band.
[0.20.14] - 2026-05-31
Fixed
- Preserve registered
solve_position_step()task solve modes and min-error fallback settings unless the caller supplies an explicit non-default step override. - Apply the shared solver runtime policy in the adaptive gain harness.
[0.20.13] - 2026-05-31
Added
- Added an opt-in per-pair non-worsening collision recovery floor
(
set_non_worsening_collision_floor_enabled,set_collision_structural_floor; off by default). When enabled, link pairs first seen closer thanmin_distanceby construction (e.g. an upper arm near the torso) are maintained at a small penetration-prevention clearance instead of triggering an infeasible recovery to the fullmin_distance— which otherwise over-constrains the QP (arm coupling, jamming, or a frozen solve). Off by default because it changes recovery semantics for pairs that start in violation; the shared bimanual whole-body teleop app enables it. - Added shared bimanual Seer/xvisio teleop support for
examples/06_bimanual_whole_body_ik.py. The browser transform controls remain available when no controller is connected. - Added adaptive position/orientation gain tuning controls and headless regression coverage for the shared bimanual teleop app.
- Added
PositionStepOptions.primary_solve_modeandprimary_allow_min_error_fallbacksosolve_position_step()callers can keep their primary task mode explicit and opt into one constrained MIN_ERROR retry when a SCALE/SCALE_ELASTIC step stalls under active constraints.
Changed
- A freshly constructed
KinematicsSolvernow defaults to the BALANCED collision tuning preset (proximity-gated activation with a 5x band, sphere broadphase, and the balanced pair-cache cadence) instead of an unconfigured speed-labelled state. Collision checking still only runs onceconfigure_collision_constraint()is called, so solvers without a collision constraint are unaffected. Callers that want a different preset can still callset_collision_tuning_mode(...).
Fixed
- Kept source-only robot fixtures and validation helpers out of installed/copied public examples while preserving them in the repository for validation.
[0.20.12] - 2026-05-28
Added
- Added paired-SE3
TaskTarget.from_se3_pair(...)bindings so multi-targetsolve_position_step()can drive anAbsoluteFrameTaskfrom the two commanded arm targets while preserving calibrated grasp offsets.
Changed
- Refreshed the docs landing page and README positioning around solver-owned robustness behavior, and added theme-aware EmbodiK logo assets.
Fixed
- Added the
pypiGitHub Actions environment to the wheel publish job so PyPI trusted publishing receives the expected OIDC environment claim. - Kept elastic-band joint-limit expansion internal by projecting returned position-step configurations back to the robot's true scalar joint limits after integration.
- Made multi-target position stepping apply paired arm targets to
AbsoluteFrameTaskinstead of treating the absolute task as a single-frame pose target.
[0.20.11] - 2026-05-23
Added
- Added solver runtime diagnostics and
SolverRuntimeConfigcontrols for solver-owned pose-task layout auto-switching and constrained weighted fallback recovery. - Added
PoseTaskGroupsupport for switching between merged and split same-priority pose task layouts while preserving existing task ownership.
Changed
- Enabled constrained weighted fallback recovery by default for
solve_position_step()runtime policy when a prioritized candidate fails but a weighted same-priority candidate satisfies solver-owned hard constraints. - Kept PyPI
pinbuild dependencies on the tested Pinocchio 3.x line, pinned the matching cmeel urdfdom/tinyxml native dependencies, and made release repair scripts locate the cmeel prefix without importing Pinocchio first. - Included the mesh loader used by generated RB-Y1 collision fixtures in the examples extra and made CI check out LFS-backed robot assets for collision regression tests.
- Made the RB-Y1 auto-layout regression accept platforms where the merged pose layout already succeeds while still requiring split/auto to stay productive.
- Kept optional RB-Y1
robot_descriptionsregressions from failing CI when the external model repository cannot be fetched by the runner. - Renumbered the highlighted public examples to keep the recommended demos
first, moved narrower examples out of the numbered path, and standardized
Viser examples on the shared
http://localhost:8080default endpoint. - Simplified public examples to call the C++ solver runtime policy directly instead of maintaining Python-side constraint clipping, retry, or last-safe guard helpers.
Removed
- Removed the public
TaskLayout.WEIGHTED_FALLBACKenum value before release; weighted fallback is reported throughSolverRecoveryStage.WEIGHTED_FALLBACKwhileTaskLayoutremains limited to merged vs. split pose-task layout. - Removed internal harness files from the installed/copied public examples surface while keeping them available in the source tree for release validation.
[0.20.10] - 2026-05-21
Changed
- Updated the bundled Spot full-body IK collision asset to match the reference collision geometry while preserving the previous visual meshes.
- Added a Viser control for switching the Spot full-body IK example between visual geometry, collision geometry, and combined inspection.
Fixed
- Pointed public one-shot installer commands back to the public gist-backed scripts so users without repository access can download them.
- Removed the temporary Spot collision workaround now that the packaged asset reproduces the intended recovery behavior directly.
- Expanded the curated Spot self-collision set to include auxiliary body-box checks against the distal arm, wrist, gripper fingers, and jaw.
[0.20.9] - 2026-05-18
Added
- Bundled public Spot-with-arm URDF assets for the Viser Spot full-body IK example.
- Bundled the MuJoCo Menagerie Spot-with-arm MJCF scene and meshes for the Spot locomanipulation mjviser example.
Changed
- Made the Spot URDF and MJCF resolvers prefer explicit user overrides, then bundled public assets, before falling back to optional cache/download paths.
- Expanded README and installation docs with copy-paste venv, one-shot installer, and mjviser example run paths for pip users.
Fixed
- Fixed copied pip examples requiring private Spot model paths or first-run
robot_descriptionsdownloads for the default Spot URDF/MJCF runs.
[0.20.8] - 2026-05-17
Added
- Added Spot full-body IK and Spot loco-manipulation mjviser examples with preview media, docs, and optional Seer teleop support.
- Added reusable Spot policy runtime, mjviser adapter, Seer teleop, and whole-body IK helpers for future policy examples.
- Added bundled Spot locomanipulation ONNX policy assets tracked through Git LFS.
Changed
- Decoupled policy inference, rendering, and IK scheduling so the Spot loco-manipulation example can keep policy updates at 50 Hz while IK runs asynchronously.
- Tuned the Spot loco-manipulation IK defaults for balanced collision handling, three active collision rows by default, operator-readable controls, and motion-triggered condition protection.
- Updated docs and README example tables to surface the new Spot
mjviserandmjviser-teleopworkflows.
[0.20.7] - 2026-05-13
Added
- Added Linux and macOS one-shot installer scripts for source-build fallback paths.
- Added native dependency notices for repaired wheels that bundle Pinocchio, Coal/HPP-FCL, and related libraries.
Changed
- Simplified installation, quickstart, contributing, and example setup docs around a single wheel-first install path.
- Restored Python 3.11 as a supported install and wheel target alongside Python 3.10 and 3.12.
- Updated example docs to describe the current registered-task APIs instead of stale velocity-IK snippets.
Fixed
- Fixed repaired-wheel loading after upgrades by making Python bindings prefer packaged native libraries before package-root libraries.
- Pointed public source-build installer commands at repository-owned scripts instead of stale external gist copies.
[0.20.6] - 2026-05-11
Added
- Added
SolverResult.condition_numberreporting for singularity/conditioning diagnostics without changing the SRINV damping law. - Added opt-in joint acceleration limits (
enable_acceleration_limits()/set_acceleration_limits()) with Python bindings, tests, and example controls. - Added the unified
examples/06_bimanual_whole_body_ik.pyentrypoint, defaulting to AI Worker and optionally supporting RB-Y1 with generated bounded primitive collision geometry.
Changed
- Renamed shared bimanual example helpers and docs away from AI-worker-specific filenames.
- Reduced AI Worker interactive solve-time spikes during fast gizmo motion by avoiding secondary-objective retries after a productive solve step and reusing cached collision debug distances in the live loop.
- Removed the older AI Worker-specific bimanual entrypoints in favor of the common bimanual example.
[0.20.5] - 2026-05-09
Added
- Added
examples/07_unitree_g1_retargeting_ik.py, a Unitree G1 whole-body retargeting IK example with palm, pelvis, and foot target controls. - Added G1 CoM visualization, optional self-collision handling, collision-geometry inspection, and headless smoke checks for the new example.
- Bundled the generated G1 collision URDF asset so copied and pip-installed examples can run without source-tree asset paths.
Changed
- Updated the examples documentation and copied-example coverage for the Unitree G1 workflow.
[0.20.4] - 2026-05-04
Added
- Added research metric helpers and regression coverage for fluidity, smoothness, sign-flip, and metric-writer outputs.
- Added internal robustness verification tooling and elastic-band investigation notes.
Changed
- Improved
SCALE_ELASTICrecovery fluidity and position-step recovery semantics around constrained teleop stalls. - Avoided full collision scans on ordinary position-step success paths to reduce unnecessary collision-check overhead.
Fixed
- Fixed the public AI Worker teleop entrypoint so visual URDF resolution can require the public visual mesh while continuing to use bundled reduced collision geometry.
- Aligned AI Worker recovery tests with current solver intervention semantics.
[0.20.3] - 2026-04-29
Fixed
- Made copied/pip-installed AI Worker examples resolve bundled SG2 generated URDF assets before attempting network downloads.
- Added copied-example regression coverage so
embodik-examples --copyimports AI Worker helpers from the copied examples directory, not the source tree. - Updated AI Worker example docs and installer guidance around copied example usage.
[0.20.2] - 2026-04-28
Added
- Public ROBOTIS AI Worker constrained dual-arm teleop example (
examples/06_bimanual_whole_body_ik.py) with cached public URDF resolution and reduced collision assets. - Shared
embodik.interactive_ikruntime helpers for robust interactive IK stepping, constrained last-safe restoration, and boundary stall classification. - AI Worker robustness harness and headless regression coverage for collision/CoM boundary behavior.
Changed
- Merged the simplified public example defaults from
mainand kept adaptive dt, nullspace bias, and balanced collision tuning as the default interactive behavior. - Simplified public-facing example/runtime code by moving detailed constrained-step handling out of the example layer.
- Updated Pixi test/build tasks to use
python -m pytestandpython -m pipso release workflow commands run reliably in the Pixi environment.
Fixed
- Hardened collision and CoM boundary handling around constrained teleop stalls, including target resync and safe-pose restoration.
- Preserved AI Worker visual meshes while using generated reduced collision geometry for IK collision checks.
- Cleaned up stale/order-dependent regression tests and documented the removed expectations in public test history.
[0.20.0] - 2026-04-19
Added
SolverStatus.COLLISION_VIOLATED(= 9): returned bysolve_position_stepwhen the input q was collision-safe but no integration step could maintainmin_distance.q_solutionis set to the last safe configuration. Hardware startup recovery (violated seed) never returns this status.- Per-link-pair collision distance overrides:
solver.set_collision_pair_min_distance(link_a, link_b, dist, activate_when_clear=True)sets a custom minimum clearance for specific link pairs. Uses deferred-latch activation by default — the override activates the first time the pair achieves the desired clearance, preventing immediate stalls when called from inside the threshold. PositionStepOptions.adaptive_dt: scales the integration timestep proportional to current position error for faster large-jump convergence without tuning gains. Configurable viaadaptive_dt_max_scaleandadaptive_dt_reference_distance. Includes proximity-aware cap to prevent overshoot stalls near collision boundaries.- Collision boundary tuning API:
set_collision_repulsion_deadband(),set_collision_recovery_scale(),set_collision_max_separation_speed_nonpenetrating()for runtime sweep/autoresearch without recompiling. evaluate_per_pair_override_violations(q): returns the worst margin across active per-pair override pairs; used internally in post-step rejection.- Example
collision_hardening_demo.py(Franka Panda interactive demo with collision status, per-pair sliders, nearest-point visualization). - Benchmarks:
benchmark_position_step_responsiveness.py,benchmark_boundary_oscillation.py. - Test suite:
test/test_collision_hardening.py(7 tests covering all new collision guarantees).
Changed
collision_repulsion_deadbanddefault changed from 3 mm to 0: the 3 mm no-braking zone created a 0.145 m/s velocity discontinuity that drove boundary-bounce oscillation. With 0, the lb formula provides a smooth deceleration ramp all the way tomin_distancewith no bounce.- Sparse position-limit constraint rows:
solve_velocitynow only adds QP rows for joints where position limits actually tighten beyond the velocity limit. Reduces constraint matrix size significantly for high-DOF floating-base robots (e.g. nv=47 → ~15 active rows at mid-range configuration). - Adaptive dt full-scan for large steps: when
adaptive_dtscales the integration step by > 1.01×, the post-step collision check uses a sphere-broadphase-expanded scan to catch pairs that were outside the active set before the jump. set_collision_pair_min_distancedefault changed toactivate_when_clear=True; useactivate_when_clear=Falsefor the previous immediate-activation behaviour.examples/02_collision_aware_IK.pyupdated with adaptive_dt controls (max_scale=10, ref_dist=0.02 defaults) andCOLLISION_VIOLATEDhold handling.
Fixed
- Critical: post-step rejection in both
solve_position_stepoverloads previously checkedkCollisionPenetrationDistanceThreshold(−1e-5) instead ofmin_distance. Solutions violating min_distance were silently returned asSUCCESS, requiring client-side collision checks. - Critical: multi-target
solve_position_steprejection was never updated from the original −1e-5 threshold (onlysolve_positionand single-target were fixed initially). - Critical: collision constraint permanently silenced in SPEED/BALANCED mode — the proximity-gated fast-path had no refresh-interval guard, causing
last_constraint_min_distance_to stay stale indefinitely. Fixed with refresh-interval check and delta-q guard (~0.1 rad motion invalidates stale cache immediately). - Critical: per-pair distance overrides not enforced in post-step rejection. Global
min_distancewas used, allowing custom pairs to penetrate undetected. Nowevaluate_per_pair_override_violations()is checked at all three rejection sites. - Desaturation nudge used
kCollisionPenetrationDistanceThresholdas safe_candidate threshold; could silently place robot insidemin_distancewithin the 0.5 mmnot_worsetolerance window. - Stall escape (Jacobian/normal) did not account for per-pair override thresholds.
- Removed
kCollisionViolationDeadband(1 mm dead zone with zero recovery force insidemin_distance); recovery ramp now activates immediately at the boundary.
[0.19.0] - 2026-04-04
Added
- Sphere broadphase collision culling: native AABB-derived bounding spheres skip expensive GJK/EPA distance queries for far-apart collision pairs. Achieves 30x collision speedup in isolation, 5790x combined with lazy reuse. New API:
solver.enable_sphere_broadphase(True),result.collision_sphere_culled_pairs. Enabled by default inkSpeedandkBalancedtuning modes. - Lazy constraint reuse: skip collision recomputation when joint velocity is near-zero and previous distance is safe. Eliminates 99%+ of collision steps in smooth trajectories.
- Post-step collision rejection: targeted safety check after integration prevents penetration without full-scan overhead.
- Elastic band joint limit expansion: temporary joint limit widening for overconstrained solver stalls. New
SCALE_ELASTICtask solve mode auto-enables elastic band. evaluate_min_collision_distance()Python binding: public API for querying collision distance at arbitrary configurations.- Release workflow command: helper workflow for version bump, changelog, and PyPI publishing.
Changed
- Default solve mode: examples 01-09 now default to
SCALE_ELASTICinstead ofSCALE. - Collision tuning presets:
kSpeedandkBalancedmodes now enable sphere broadphase automatically. - Example 02 defaults: self-collision and collision debug visualization enabled by default.
- Collision constraint reuse: coalesced nearest-points queries and added lazy constraint reuse — when joint velocity is near-zero and cached distance is safe, the entire collision constraint computation is skipped. Reuse is bounded by the cache refresh interval to guarantee periodic full scans.
- Position-step collision hot path: eliminated redundant full-scan collision overhead in position-step recovery paths; targeted pair evaluation replaces global distance scans during stall-escape and post-step rejection.
- Collision debug state preservation: lazy constraint reuse now preserves collision debug info (closest pair, nearest points) from the previous full computation, ensuring debug visualization remains available during reuse steps.
Removed
- Collision warm-start: removed unused
warm_start_collision_marginfeature from elastic band config (stall handler's reactive relaxation is preferred).
[0.18.9] - 2026-03-29
Added
- Focused solver perf gates: added targeted benchmark scripts for velocity and position-step collision workloads plus a hardened median-of-medians aggregator to make refactor acceptance decisions robust against run-to-run noise.
Changed
- Collision-heavy IK loop efficiency: reduced per-step overhead by removing avoidable allocations in stall/candidate handling, reserving hot-path containers, and simplifying collision debug evaluation in repeated checks.
- Position-step recovery hot path: skip redundant post-step collision rejection when integration does not move configuration, and cache collision-object-to-frame lookups during stall normal-escape attempts.
- Constraint bound readability: replaced unbounded torso-row magic literals with the shared
kUnboundedConstraintLimitconstant.
[0.18.8] - 2026-03-30
Added
- Position IK collision diagnostics counters:
PositionIKResultnow exposescollision_rejection_countandstall_escape_count(C++ + Python bindings) so callers can quantify rejected penetration steps and successful stall-escape nudges.
Changed
- Collision candidate-set safety fallback: collision row selection now forces a full scan when cached/top-K candidate subsets are underfilled or empty, and guarantees any currently penetrating pair is included in the active set before truncation.
- Collision debug semantics for top-K mode:
evaluate_collision_debug()now reports the globally closest pair rather than only the closest active constraint row, improving observability when the nearest pair is outside the current top-K active rows. - Penetration/stall constants normalized: newly introduced penetration-rejection and stall-escape thresholds in position-step paths are now defined as shared file-level constants instead of repeated inline literals.
- Stall-escape activation widened for clearance violations: stalled recovery now treats configured clearance violations (
distance < min_distance) as escape-eligible even when still non-penetrating, reducing prolonged zero-motion plateaus. - Debug instrumentation cleanup: removed session-specific C++ runtime log sinks used during incident debugging while preserving solver behavior changes validated by runtime evidence.
Fixed
- Position-step penetration regression guard:
solve_positionand bothsolve_position_stepoverloads now reject integration steps that newly create or significantly deepen collision penetration, reverting to the pre-step configuration when unsafe. - Stalled penetration escape robustness: when stalled in penetration, position-step IK now invalidates stale collision-pair caches and applies Jacobian-based escape nudges (active-row first, then global-pair fallback) to recover from deep contact states more reliably.
- Hard jump protection in step integration: sudden deep penetration transitions are now rejected via additional hard-jump thresholds in position-step rejection logic.
- Recovery gating when stall margin goes non-positive: collision rejection/escape paths now remain active when collision constraints are enabled, even if the temporary stall-adjusted
min_distancebecomes non-positive.
[0.18.7] - 2026-03-26
Changed
- Stall recovery bottleneck classification: stall handling now evaluates active collision-row distances from
get_last_collision_debug_list()(with backward-compatible fallback) instead of relying on a single scalar debug pair. - Position-step stall path parity:
solve_position/solve_position_stepnow propagate saturated-joint information into stall handling, matchingsolve_velocity-path bottleneck context.
Fixed
- Limit-dominated deep-collision pull-in: when joints are saturated near limits, stall recovery no longer relaxes collision margin as if collision were the primary bottleneck, avoiding false-positive margin ratcheting into penetration.
- Regression coverage for K>1 collision rows: added stall-handler tests for multi-constraint collision regimes (
max_constraints > 1) and parity checks for CoM-constrainedsolve_position_stepdirectional behavior.
[0.18.6] - 2026-03-26
Changed
- Stall-handler bottleneck gating tightened: stall recovery now relaxes collision
min_distanceonly when collision constraints are actually binding (distance <= current min_distance), preventing false-positive relaxation when joint-limit clamping is the real bottleneck. - Stall-handler docs clarified: API documentation now explicitly describes collision-only relaxation behavior and why joint-limit-driven stalls do not trigger collision-margin relaxation.
Fixed
- Deep-collision pull-in regression near joint limits: resolved a regression where repeated stall-threshold triggers could ratchet down collision margin while Jacobian clamping constrained motion, allowing tasks to pull the arm further into body collision.
- Regression test coverage for clamping-stall interaction: added/validated targeted tests ensuring stall recovery does not keep relaxing collision margins once joint limits become the bottleneck.
[0.18.5] - 2026-03-26
Changed
- Joint-limit handling simplification: removed the optional joint-limit barrier task API from C++/Python solver surfaces and internal solve path, keeping the near-limit Jacobian clamping strategy as the primary behavior near active limits.
- Examples/docs cleanup: removed barrier-specific controls and references from examples and recovery documentation to align with current default solver behavior.
Fixed
- Two-joint limit trap behavior: improved near-limit escape behavior by clamping task Jacobian entries that would push joints further into active limits, reducing apparent teleop stalls when one joint must move away while another remains near a bound.
- Regression stability around recovery fixtures: updated hardware-seed recovery checks to deterministic non-regression assertions so tests remain robust across environment-sensitive collision fixtures.
[0.18.4] - 2026-03-26
Added
- Explicit proximity-gating toggle API: added
set_proximity_gated_collision_activation_enabled(...)/get_proximity_gated_collision_activation_enabled()in C++ and Python so gating can be enabled/disabled without mutating threshold multipliers. - Regression coverage for gating toggle semantics: added tests verifying enable/disable behavior flips row activation while preserving configured activation multiplier and effective margin.
Changed
- Proximity-gated collision activation controls: added optional, min-distance-scaled activation threshold controls (
constraint_activation_multiplier, effectiveconstraint_activation_margin) and wired automatic margin updates whenmin_distancechanges. - Collision tuning preset behavior: restored
PRECISEto conservative legacy-equivalent behavior (cache disabled, no budget, gating off), whileBALANCEDandSPEEDenable proximity gating with distinct activation multipliers. - Collision row assembly path: collision QP rows are now emitted conditionally based on proximity threshold when gating is enabled, reducing far-from-collision overhead.
[0.18.3] - 2026-03-25
Changed
- Constraint assembly internals unified across APIs: extracted shared helper paths in the solver implementation for excluded-joint Jacobian masking, inequality-row appending, and torso pose-bound row construction so
solve_velocityandsolve_positionfollow one consistent constraint assembly pattern.
Fixed
- Reduced drift risk between
solve_velocityandsolve_position: replaced manual row-offset recomputation in position IK with the same append-editor pattern used in velocity IK, reducing error-prone index math during future constraint additions. - Safety-net parity across solve APIs:
solve_positionnow runssanitize_solver_inputs(...)before backend solve, matchingsolve_velocityhandling for non-finite goal/Jacobian/constraint inputs. - Regression coverage for API consistency: added CoM-constraint parity coverage in
test/test_com_constraint.pyvalidating that both solve APIs improve or match unconstrained support-polygon violation behavior.
[0.18.2] - 2026-03-25
Fixed
solve_positionCoM constraint gap: position IK now includes configured CoM support-polygon inequality rows in its constraint stack (including excluded-joint handling), matching expected CoM-limit behavior already present in velocity IK.- Regression coverage for CoM-constrained position IK: added a targeted test in
test/test_com_constraint.pyto verify CoM-constraint configuration reduces or matches unconstrained support-polygon violation insolve_position.
[0.18.1] - 2026-03-23
Added
- Shared velocity-box headroom policy type: added
VelocityBoxHeadroomPolicy(enabled,fraction,activation_margin) and exposed it underTorsoPoseConstraintOptions.velocity_box_headroomin C++ and Python bindings. - Velocity-box helper API extension:
KinematicsSolver.calculate_velocity_box_constraint(...)now accepts optionalmin_velocity_headroomandheadroom_activation_marginarguments for explicit per-call headroom policy testing. PositionStepOptions.torso_constraint: optional torso orientation task and torso pose bounds on position-step IK; exposed in C++ and Python bindings (including.pyistubs).
Changed
- Torso pose-bound headroom path generalized: torso pose-bound rows now use the same shared
calculate_velocity_box_constraint(...)headroom path as other velocity-box constraints, replacing torso-specific post-processing. - Docs: Example 10 teleop docs now describe
velocity_box_headroomas the preferred API and markpose_bound_softening_*as legacy aliases.
Fixed
torso_constraintenforced insolve_position_step:PositionStepOptions.torso_constraintis now applied insolve_position_step(including the multi-target path) via inequality rows consistent withsolve_position, so teleop-style position stepping respects torso pose limits.- Bindings/stubs:
PositionStepOptionsin Python bindings and type stubs includestorso_constraintalongside other position-step fields. - Regression tests: expanded
test_position_step_joint_options.pycoverage for torso-constrained position stepping. - Validation coverage for headroom policy: regression tests for invalid
torso_constraint.velocity_box_headroom.fractionand preserved softening/backward-compat tests.
[0.18.0] - 2026-03-24
Added
TorsoPoseConstraintOptions.pose_bounds_reference_pose: optional 4x4 homogeneous anchor so torso pose box limits stay fixed relative to a chosen world pose across repeatedsolve_positioncalls (e.g. teleop ticks), while remaining fixed across inner IK iterations as before.- Torso pose-bound softening controls: added
TorsoPoseConstraintOptions.pose_bound_softening_enabledandpose_bound_softening_fraction(C++ + Python) as an opt-in way to preserve minimum torso-row velocity headroom near active pose-box limits. - Example 10 benchmark diagnostics:
scripts/benchmark_example10_torso_modes.pynow reports per-status timing/error buckets,iterations_useddistributions/histograms, and a jump-vs-no-jump plus max-iterations matrix sweep for deeper responsiveness analysis. scripts/install_embodik_macos.sh: one-shot macOS setup (Homebreweigen@3/ URDF packages, venv,SDKROOT+ SDK libc++ include workaround,CMAKE_PREFIX_PATHfor PyPIpin+ Homebrew, PyPI or editablepip install). Shipped in sdist viaMANIFEST.in.scripts/install_embodik_linux.sh: one-shot Linux setup (Debian/Ubuntuaptdeps for Eigen/URDF + toolchain, venv,CMAKE_PREFIX_PATHfrom PyPIpin, and PyPI or editablepip install). Shipped in sdist viaMANIFEST.in.
Changed
- Torso pose-box rotation error:
solve_positiontorso 6D bounds now usepinocchio::log3for the relative rotation (R_\mathrm{ref}^\top R) instead of a localacos/vee implementation, matching Pythonembodik.log3and improving numerical behavior near (\pi). - Example 10 interactive tuning workflow: added bounded-mode behavior presets (
Responsive,Stable,StrictBounds), torso bound softening controls, and aConstraint pressureindicator to make high-constraint stall risk visible during teleop-style target motion. - Docs (Pixi): Developer setup documents optional
pixi install, macOS Xcode CLT expectation, and that CMake adds the SDKlibc++include path on Apple platforms. - Docs / README: expanded pip/sdist guidance with one-shot installer coverage for both macOS and Linux, including optional
curlflows and distro-specific dependency notes. - CI (
test-macos-arm64): installeigen@3and URDF Homebrew packages; setSDKROOT, SDK libc++CXXFLAGS, andCMAKE_PREFIX_PATH="${PIN_PREFIX}:$(brew --prefix)". cibuildwheel(macOS):brew install eigen@3plus URDF packages;Eigen3_DIRunderopt/eigen@3;CMAKE_PREFIX_PATH=/opt/homebrewto complement CMake’s PyPIpinprefix prepended inCMakeLists.txt.
Fixed
- macOS Python module load after
pip install:INSTALL_RPATHfor_embodik_implnow uses separate Mach-O entries (@loader_path;@loader_path/lib) instead of one invalid$ORIGIN:$ORIGIN/libstring. - macOS builds with Xcode CLT:
CMakeLists.txtadds the active macOS SDK’susr/include/c++/v1onAPPLEsopixi run installand in-tree Ninja builds find<cmath>when CLT libc++ is incomplete; manual pip-only installs still use the documentedCXXFLAGSworkaround where needed.
[0.17.0] - 2026-03-23
Added
- Solver status/options API expansion for position stepping: introduced no-progress-oriented status and option surface in C++ and Python bindings so position-step callers can control and interpret bounded-step convergence behavior explicitly.
- Reference corridor support for position-step IK bounds: added reference-corridor-aware bound handling to improve guidance around prior solutions and reduce drift during repeated teleop-like updates.
- High-level collision tuning presets: added
CollisionTuningMode(PRECISE,BALANCED,SPEED) andKinematicsSolver.set_collision_tuning_mode(...)/get_collision_tuning_mode()so users can select collision behavior by intent instead of low-level cache/budget knobs. - Python enum exposure for collision tuning modes:
CollisionTuningModeis available in Python bindings and wired into solver bindings for direct use in scripts and applications.
Changed
- Unified IK bound evaluation path: consolidated position-step bound and stop-condition checks so joint/task limits, corridor checks, and termination semantics run through one consistent status-classification flow.
- Default no-progress behavior now classifies early exits explicitly: when incremental motion fails to make meaningful progress, the solver reports a no-progress outcome by default instead of collapsing into less specific statuses.
- Interactive example controls for live collision tuning: examples
02_collision_aware_IK.pyand03_teleop_ik.pynow expose aspeed/balanced/preciseselector with runtime updates while keeping low-level cache/budget knobs hidden. - Preset rationale documented in solver implementation: clarified why
PRECISEandBALANCEDdisable time-budget truncation (budget_us=0) and why onlySPEEDuses a positive refinement budget for bounded latency.
Fixed
- No-progress exit semantics consistency: aligned default no-progress classification across solver internals and bindings so callers observe stable, deterministic status reporting for stalled incremental updates.
[0.16.0] - 2026-03-21
Added
- Collision-query instrumentation in solver results:
VelocitySolverResultnow reportscollision_pairs_considered,collision_exact_distance_queries,collision_bound_culled_pairs, andcollision_budget_exhaustedfor per-step profiling. - Collision performance controls in public API: added
enable_collision_pair_cache(...),set_collision_refinement_time_budget_us(...), andget_collision_refinement_time_budget_us()onKinematicsSolverwith Python bindings. - Benchmark and equivalence tools: added
scripts/benchmark_teleop_workloads.pyandscripts/validate_collision_cache_equivalence.pyfor teleop-focused performance measurement and cache-vs-baseline correctness checks.
Changed
- Default collision path is optimized: collision pair caching and conservative budgeted refinement are now enabled with tuned defaults to reduce collision overhead in teleop-style loops while preserving conservative behavior.
- Dual-iiwa URDF utility flexibility:
build_dual_iiwa_urdf()now supports optional mesh-collision replacement viareplace_mesh_collision. - Local perf artifact hygiene:
.editor/reports/perf_runs/*is now ignored to keep generated profiling outputs out of git tracking by default.
[0.15.6] - 2026-03-21
Added
- Panda joint-limit regression tests:
test_panda_position_limit_seed.py(at-limit seed vs incremental teleop-style nudge undersolve_position_step) andtest_panda_joint_limit_barrier_position_step.py(barrier overhead / incremental teleop-like stepping). scripts/benchmark_joint_limit_barrier_overhead.py: optional local timing comparison for barrier ON vs OFF under repeatedsolve_position_stepcalls.
Changed
- Joint-limit barrier performance: cache the velocity→configuration index map across
solve_velocitycalls (rebuild when robot model ornvchanges); inject barrier objectives in one pass without allocating a fullnv-dimensional gradient vector. - Named barrier/limit constants:
KinematicsSolverusesstatic constexprvalues for barrier clamps, deadband math, numerical guards, and map sentinels instead of scattered literals. - Docs:
docs/joint_limit_saturation_exit_findings.mdtable updated to match the barrier implementation.
[0.15.5] - 2026-03-20
Changed
- Simplified stall recovery strategy: removed MIN_ERROR fallback toggling and iteration-cap coupling from the stall handler so recovery behavior is driven solely by collision-margin relaxation and restoration.
- Stall-handler API cleanup: reduced
configure_stall_handler()to core parameters (stall_threshold,restore_rate,floor_fraction) and removed fallback-specific state/config paths.
Fixed
- Collision margin consistency during recovery: unified restoration into a single ceiling-limited ramp that keeps effective
min_distancebelow live collision clearance, preventing abrupt re-entry into infeasible regions. - Regression coverage alignment with simplified behavior: updated stall-handler tests and docs/stubs to validate stable pull-away recovery and no-regression behavior without fallback-dependent assertions.
[0.15.4] - 2026-03-20
Added
pull-awaystall regression test: added dual-EE body-stall coverage that reproduces a stall-then-reverse-target sequence and asserts quick motion recovery when end-effector goals move away from collision.
Changed
- Stall detection now treats
kNumericalError+ near-zerodqas stuck: extends handler triggering beyondkInfeasibleso sustained capped-iteration failures still progress through recovery logic. - Iteration-cap probing under fallback: during fallback cycles, the solver now allows uncapped probe steps at cycle boundaries to detect newly feasible motion sooner when constraints are being relieved.
Fixed
- Collision margin clamp removed for runtime tuning:
set_collision_min_distance()now accepts negative values, enabling deep-penetration escape strategies that require temporary sub-zero margins. - Deep-penetration stall escape path: on repeated stalls while interpenetrating, the handler drops effective collision margin below current penetration and exits fallback so motion can resume instead of remaining locked with high compute cost.
- Margin restoration stability after escape: restoration is bounded by live collision-distance ceilings to avoid immediately reintroducing infeasible collision rows during recovery.
[0.15.3] - 2026-03-20
Changed
- Stall handler tuning is now parameterized: replaced inline magic constants in fallback logic with explicit config fields (
relax_drop_fraction,healthy_motion_multiplier,fallback_iteration_limit,task_active_weight_eps) to make behavior easier to reason about and tune. - Stall-handler defaults aligned with current behavior:
healthy_steps_to_cleardefault is now 10 inStallHandlerConfig, matching the sustained-motion requirement used by the active fallback implementation.
Fixed
- Removed ad-hoc floating-point guards in stall cleanup paths: stall margin restore/relaxed-state checks now use named tolerance constants rather than repeated hardcoded epsilons.
- Stall regression test robustness: threshold-reach assertion in dual-EE body-stall coverage now reflects observed counter accumulation under the updated sustained-motion fallback behavior.
[0.15.2] - 2026-03-20
Fixed
- Broadened stall detection under MIN_ERROR fallback: stall handler now detects stuck states when
dq ≈ 0under active MIN_ERROR fallback (returnskSuccesswith near-zero motion). Uses a wider velocity threshold (100×dq_stall_eps) when fallback is already active. - Progressive margin relaxation: fallback deactivation now requires collision margin to be fully restored to nominal before clearing, preventing rapid on/off cycling that re-triggered immediate stalls.
- Jump prevention on task disable: when all priority-0 tasks have near-zero weight (e.g., user disabling one EE during stall), the handler immediately restores collision margin to nominal and deactivates fallback, preventing configuration jumps into deep penetration.
- Computation time bounded during deep stalls: when the stall handler is in active fallback with sustained infeasibility, the inner SNS solver iteration limit is capped to 5, preventing per-step computation spikes from MIN_ERROR constraint-by-constraint saturation.
- Healthy-step gating: fallback deactivation requires sustained meaningful motion (above 10× the effective stall threshold), not just any non-zero
dq.
Added
TestDualEEBodyStalltest class: 5 new tests covering progressive margin relaxation, repeated threshold hits, computation time budget, no-penetration-jump on task disable, and velocity-loop stall reduction — all using the multi-targetsolve_position_steppattern typical of dual-arm teleop loops.
[0.15.1] - 2026-03-20
Changed
solve_position_step(..., stall_recovery=True)lifecycle: stall-handler state now persists across successive single-step calls so stall counters accumulate correctly in outer loops (e.g., teleop ticks withmax_steps=1).- Stall handler enabling semantics:
enable_stall_handler()is now idempotent and preserves accumulated recovery state when called repeatedly.
Fixed
- Persistent dual-EE stall handling: fixed a reset path that prevented
consecutive_stall_stepsfrom reaching threshold in per-tick stepping IK loops, which blocked stall recovery from activating. - Regression coverage: added/updated stall-handler tests for persistent
solve_position_stepbehavior and counter accumulation across repeated single-step calls.
Removed
- Solver recovery state machine: the internal velocity-solver recovery state machine has been removed entirely. It caused oscillation and aggressive velocity spikes without measurable benefit.
set_solver_recovery_enabled()/solver_recovery_enabled()are retained as no-ops for backward compatibility.
[0.15.0] - 2026-03-20
Added
- Stall recovery opt-in for
solve_velocity:KinematicsSolver::solve_velocity(..., stall_recovery=False)andsolve_velocity_dq(..., stall_recovery=False)now support one-flag activation of the C++ stall handler in user velocity loops. - Stall recovery opt-in for position IK:
PositionIKOptions.stall_recoveryenables the same C++ stall handling path forsolve_position(...)with sensible defaults. - Tests: expanded stall-handler coverage for
solve_velocity/solve_velocity_dqandsolve_positionflag behavior (default-off, opt-in behavior, and externally-enabled handler semantics).
Changed
solve_positionstall handling integration: stall detection now classifies low-level velocity outcomes consistently withsolve_velocity(including zero-scale primary-task infeasibility) before feeding the stall handler.
Fixed
- Stall-handler consistency across call paths: aligned status classification and option semantics so
stall_recoverybehaves consistently acrosssolve_velocity,solve_position_step, andsolve_position.
[0.14.4] - 2026-03-20
Fixed
solve_position_step(..., PositionStepOptions.excluded_joint_indices=...): restored consistent behavior with the existingsolve_positionintent by avoiding temporary mutation of registered task exclusion lists during stepping IK.- 0.14.3 regression note:
excluded_joint_indicesin stepping IK could cause undesirable behavior by patching registered task exclusions at runtime; this release removes that side effect.
Changed
- Stepping IK exclusions implementation:
excluded_joint_indicesnow uses a non-mutating per-step lock path (no scoped merge/restore of registered tasks).
Changed
clear_collision_constraint(): also resets active collision pair indices, stuck-detection counters, per-pair last-distance caches, and recovery homotopy state (collision_effective_min_distance_) so disabling collision does not leave stale internal state.- Recovery mode exit (collision health): when
max_constraints > 1, recovery now requires every active collision QP row (same entries asget_last_collision_debug_list()) to be at or abovemin_distance, not inference from the closest pair alone.
Removed
- Dead locals in
solve_velocityrecovery bookkeeping (collision_unhealthy/joint_unhealthy/unhealthy) that were never read.
Docs
- Header comments for internal recovery behavior (trigger,
goals[0]/ first merged priority-0 block, diagnostics viastatus_message) and expandedclear_collision_constraint()documentation. PositionStepOptions: clarify thatlocked_joint_indiceschanges the QP (not the same as post-QP masking); recommendintegration_zero_velocity_indicesalone for typical interactivesolve_position_steploops unless diagnostics require QP-consistent velocities.
[0.14.3] - 2026-03-19
Added
PositionStepOptions(aligned withPositionIKOptionsnaming where applicable):excluded_joint_indices: same meaning asPositionIKOptions::excluded_joint_indices— merged into exclusions on the driven pose task(s) and everyPostureTaskfor each innersolve_velocity, then restored (parity with howsolve_positionapplies exclusions to its frame + nullspace tasks).locked_joint_indices:nv-indices constrained to v = 0 in the velocity QP (tight bounds on the identity rows + Jacobian column zeroing on objectives and inequality constraints). Cleared automatically at the end of eachsolve_velocity.integration_zero_velocity_indices: after each innersolve_velocity, listednvcomponents are zeroed on the joint velocity beforepinocchio::integrate(legacy post-QP mask; QP may still have assigned non-zero velocity there).- Tests:
test/test_position_step_joint_options.py.
[0.14.2] - 2026-03-19
Added
- macOS Apple Silicon (Pixi):
osx-arm64inpixi.tomlworkspace platforms; lockfile regenerated for multi-platform solve. - CI:
macos-14job builds with venv + pip (pin+CMAKE_PREFIX_PATH) and runspytest. - Wheels workflow:
cibuildwheelonubuntu-latest(manylinux x86_64/aarch64) andmacos-14(arm64) withauditwheel/delocate-wheelrepair; sdist artifact; on version tags, publish combined artifacts to PyPI and create a GitHub release (generate_release_notes).
Changed
- Nanobind stubgen (CMake): use
DYLD_LIBRARY_PATHon Apple when running stub generation; includeDYLD_LIBRARY_PATHsegments in library search paths. embodik-sanitize-env: on macOS, sanitizeDYLD_LIBRARY_PATHinstead ofLD_LIBRARY_PATH.- Docs: README and
docs/installation.md— Apple Silicon notes,DYLD_LIBRARY_PATH/@rpathtroubleshooting, unset both loader vars in “existing Pinocchio” flow. - Release automation: tag-based PyPI upload moved to the wheels workflow;
release.ymlis manual (workflow_dispatch) for GitHub release only. scripts/upload_pypi.sh: comments updated for sdist-only script vs cibuildwheel artifacts.
Fixed
- CI / wheels:
find_package(Eigen3)failures — macOS job installs Eigen via Homebrew and setsEigen3_DIR;cibuildwheelLinux runsdnf install -y eigen3-devel; macOS wheel builds setEigen3_DIRfor Apple Silicon Homebrew. Docs updated for local macOS pip installs.
[0.14.1] - 2026-03-19
Added
PositionStepOptions: optional task-space speed capsmax_linear_speedandmax_angular_speed(≤0 = unlimited); applied insidesolve_position_stepafter gain × pose error.KinematicsSolver::clear_all_target_velocities()— clears directtarget_velocityon every registered task; exposed in Python bindings.- Tests:
test/test_position_step_speed_limits.py— stale-velocity cleanup after stepping IK and linear speed-cap behavior.
Changed
solve_position_step: after each call, clear direct velocities on all registered tasks (single-task path uses the same global cleanup as multi-task). Prevents stalesetTargetVelocity/ stepping leftovers from affecting the nextsolve_velocityor frame.
Docs
Task::getVelocity()— note that direct-velocity magnitude is not scaled byweight_; useweight = 0,active = false, orclearTargetVelocity()to drop contribution.
[0.14.0] - 2026-03-19
Added
- Stepping position IK —
KinematicsSolver::solve_position_step(...): interactive / per-frame position IK that does not swap or create temporary tasks. It sets the target on a registered pose task, computes pose error internally, maps it to a task-space velocity using separate linear/angular gains (PositionStepOptions, independent of task weight), runssolve_velocity()up tomax_stepswith optional per-step integration (dt≤ 0 usessolver.dt). Because it goes throughsolve_velocity(), the same collision and limit machinery applies each sub-step. - Multi-task stepping IK — overload
solve_position_step(current_q, std::vector<TaskTarget>, options)for one coordinated velocity solve per sub-step across multiple targets. Supports registeredFrameTask,AbsoluteFrameTask, andRelativeFrameTask(by task name); eachTaskTargetcarries its own 4×4 pose and gains. PositionStepOptions:position_gain,orientation_gain,max_steps,dt.TaskTarget:task_name,target_pose,position_gain,orientation_gain.- Python bindings:
TaskTargetandPositionStepOptions;TaskTarget.from_se3(...);solve_position_stepoverload acceptingembodik.Rt/ Pinocchio SE3 for the single-task path (in addition to 4×4ndarray). FrameTask::getFrameName()— public accessor for the controlled frame id.- Solver recovery state machine (velocity / stepping paths): ring buffer of recent solve snapshots; stuck trigger on sustained
NUMERICAL_ERRORwith near-zero||dq||; rollback toward the best recent feasible configuration; recovery mode that softens primary EE-style objectives and biases toward collision clearance and limit margin; per-pair collision margin homotopy (collision_effective_min_distance_) to ease out of persistent margin violations; healthy exit counters before returning to normal. - Examples:
examples/utils/pose_utils.py(PoseUtils.make_pose_matrix); Viser examples 01, 02, 03, 08, 09 updated to usesolve_position_step, aligned default sliders (task weight / gains / iterations), and shared EE solve mode + allow SCALE→MIN_ERROR fallback controls where applicable. - Tests:
pytest-benchmarkforsolve_position_stepvs a low-level reference loop; stepping API +Rt/SE3 overload coverage (test_adaptive_task_relaxation.py); defaultallow_min_error_fallbackround-trip (test_tasks.py); collision recovery / cold-start / deadlock rollouts (test_embodik.py).
Changed
- Default task behavior:
Task::allow_min_error_fallbacknow defaults tofalse. Code that depended on automatic SCALE → MIN_ERROR fallback without setting the flag must opt in withallow_min_error_fallback = True(matches interactive examples and coordinated IK expectations). solve_position_stepperformance: O(1) task lookup viatask_map_, singlesetTargetPoseinstead of split setters (one cache invalidate), fixed-size 6D velocity buffer in hot loops,std::movemerge ofVelocitySolverResultintoPositionIKResult, multi-task path resolves dynamic task types once per call (not every sub-step).- Examples / scripts: reuse a single
PositionStepOptionsinstance in tight loops where practical;visualization_example.pyusesPoseUtils.
Fixed
- Clearer invalid-input messages for stepping IK (unknown task name, non-
FrameTaskname in single-task API, unsupported task type in multi-task list).
Docs
docs/api/tasks.md— document defaultallow_min_error_fallbackfor user-created tasks.
Note (test suite)
- Full
pixi run teston this date: 247 passed, 7 skipped, 3 failed (known debt, not introduced by the stepping-IK API itself): test_joint6_drift_bug:test_x_positive_drive_causes_j6_drift,test_y_positive_drive_causes_j6_drift— joint-6 drift exceeds the current tight threshold for pure ±X/±Y EE drives.test_panda_narrowed_limits:TestStrategyComparison.test_strategy_a_vs_baseline[X]— strategy A reverse-path stall count vs baseline.
[0.13.2] - 2026-03-12
Added
- Collision-boundary jitter guardrails for adaptive relaxation: new regression tests compare
SCALEvsMIN_ERRORnear active collision-distance limits using both distance-stddev and sign-flip metrics.
Changed
- Near-boundary collision handling now applies a small violation dead-zone just below
min_distanceto reduce numerical chatter while preserving recovery behavior for real violations.
[0.13.1] - 2026-03-12
Added
- Regression coverage for adaptive task relaxation on Panda, including
MIN_ERRORprogress checks with and without nullspace posture bias. - Adaptive relaxation is now enabled by default for
SCALEtasks via automatic fallback toMIN_ERRORwhen scale collapses.
Changed
- Refined clamped
MIN_ERRORactive-set behavior to preserve hierarchical projector updates and improve constrained progress when saturation evolves. - Kept the release focused by dropping temporary scripted trace/debug tooling from examples.
Fixed
- Resolved a
MIN_ERRORloop-control path that could skip objective projector updates and degrade lower-priority task behavior. - Resolved
MIN_ERRORtermination fallback handling to avoid pathological stagnation/oscillation in constrained scenarios.
[0.13.0] - 2026-03-10
Added
- New public solver outcome
INFEASIBLEacross C++/Python status enums and stubs to distinguish clean infeasibility from numerical failures. - Explicit high-level status-message coverage for infeasible outcomes in velocity and position solving, including position-IK non-convergence classification.
- Regression tests for status exposure, infeasibility hinting, and high-level infeasible/non-convergence behavior.
Changed
- High-level
KinematicsSolvernow classifies numerically stable but unachievable outcomes asINFEASIBLEinstead of overloadingNUMERICAL_ERROR. solve_velocity()now preserves and surfaces backendstatus_messagedetails to downstream callers.- CoM rollout tests now accept
INFEASIBLEas a valid constrained-solve outcome while preserving behavioral assertions.
[0.12.6] - 2026-03-10
Added
- Guided solver debugging helper:
embodik.get_solver_status_hint(status, status_message=None)returns actionable troubleshooting guidance per solver status and appends backend details when available. SolverResult.status_messageis now exposed to Python bindings for explicit failure diagnostics.- Explicit solver status coverage in Python: new enum values exported (
SHAPE_MISMATCH,EMPTY_PROBLEM,CONSTRAINT_BOUNDS_MISMATCH,NON_FINITE_INPUT) for clearer handling in downstream code. - New regression test for status hint helper and updated invalid-input tests to validate explicit status categories.
Changed
- Constraint robustness logic is streamlined via shared internal helpers for half-space bound shaping and violated-row task projection, and applied consistently across collision, CoM, and relative-pose constraints.
- Solver pre-processing now sanitizes non-finite values and inconsistent per-row bounds before backend solve, reducing NaN-driven ambiguous failures.
- Input-validation failures in the backend now return explicit status categories with descriptive messages instead of lumping all failures into generic
INVALID_INPUT.
[0.12.5] - 2026-03-10
Changed
- CoM support-polygon constraints now apply collision-style violation handling: when outside a half-plane, task Jacobians are projected to remove outward motion components while preserving tangential/inward directions.
- CoM constraint bounds now include active outside recovery behavior with minimum inward recovery speed and proportional scaling, improving escape behavior when starting in violation.
- CoM half-plane construction now includes a centroid-side orientation guard so feasibility is robust to polygon winding/orientation.
Added
- New CoM regression tests covering outside-violation behavior:
- single-step suppression of further outward motion while outside, and
- multi-step constrained-vs-unconstrained rollout comparison.
[0.12.4] - 2026-03-06
Changed
- Saturation exit behavior disabled by default: Velocity-box softening near joint limits (kMinBoundFraction) is now opt-in. Use
enable_saturation_exit_behavior(True)to restore previous behavior; requires more testing before enabling broadly.
Added
enable_saturation_exit_behavior(bool)/saturation_exit_behavior_enabled(): Python API to toggle velocity-box softening near limits.
[0.12.3] - 2026-03-06
Added
- Native Rotation helper (
embodik.Rotation/SO3): Lightweight SO(3) class replacingscipy.spatial.transform.Rotation. Constructors:from_matrix,from_quat,from_rotvec,from_euler,identity. Spatialmath-style shorthands:Rx,Ry,Rz,RPY,AngVec,EulerVec. - SE3 property aliases:
R,t,A(spatialmath-style).SE3.Rt(R, t)classmethod. - Transform benchmarks (
pixi run benchmark-transforms): Latency and throughput benchmarks; native r2q/q2r ~24×/2× faster than SciPy.
Changed
- r2q / q2r: Now use native Pinocchio conversion (no SciPy dependency).
- API documentation: Added
docs/api/transforms.mdfor Rotation, SO3, SE3. Updateddocs/api/utils.mdwith r2q, q2r, Rt, compute_pose_error.
[0.12.2] - 2026-03-06
Added
- SE3 Python API: Composition operator (
T1 * T2), equality (==,!=), and point transforms (act(p),actInv(p)). Enablesgoal_pose = torso_emb * target_se3andp_world = T.act(p_local)without manual matrix math.
[0.12.1] - 2026-03-06
Fixed
- Decoupled velocity-solver tolerances to avoid unintended over-regularization:
set_tolerance()now maps to regularized pseudoinverse damping threshold (regularization_config.epsilon), preserving historical behavior.- Added
set_constraint_tolerance()to control constraint violation deadband (VelocitySolverConfig::epsilon) independently. - Updated Python bindings/docstrings to reflect the separated semantics.
[0.12.0] - 2026-03-05
Added
- Top-K simultaneous collision constraints (
max_constraintsparameter onconfigure_collision_constraint()): instead of protecting only the single globally closest pair, the solver now emits up to K independent QP constraint rows — one per closest pair. Each row has its own Jacobian, velocity-damper bounds, and stuck-detection counter, so multiple tight-clearance regions (e.g. base/leg and arm/torso on a wheeled humanoid) are protected simultaneously. get_last_collision_debug_list(): returns alist[CollisionDebugInfo]with one entry per active constraint row (up tomax_constraints). The existing single-pairget_last_collision_debug()remains unchanged for backward compatibility.- Per-pair hysteresis and stuck detection: previous active pair indices are tracked as a vector; each pair has its own stuck counter in a map. Pairs that fall out of the top-K are cleaned up automatically each step.
Changed
- Continuous recovery ramp (collision escape improvement): removed the discrete "slightly-inside deadband" special case that used a
gentle_scale = 0.01multiplier (producing ~0.005 m/s — too weak to overcome EE task pulls). All non-penetrating violations now use a uniformkCollisionRecoveryScale = 0.2, producing a proportional recovery push at all violation depths. - Task normal projection (collision escape improvement): when a collision pair is violated (
lower_bound > 0), the collision normal is projected out of all EE task Jacobians before the SNS solve. Only the approach component (proj < 0) is removed; tangential and escape directions remain fully available. This eliminates the "frozen in all directions" symptom where the entire task velocity was scaled to zero by the SNS solver. kCollisionStuckRecoverySpeed = 0.10 m/sadded: stuck condition now boosts recovery to at least 0.10 m/s (previously 0.05 m/s, shared with penetration floor).
[0.11.0] - 2026-03-04
Added
- RobotModel constructor with actuated joint names:
RobotModel(urdf_path, actuated_joint_names=[...], floating_base=False)builds a reduced model by locking all joints not in the list at their neutral configuration. The resulting model'snq/nvmatch the actuated joint count, eliminating index mapping when integrating with external systems that use reduced configurations. Visual and collision geometry are reduced in sync with the model.
Changed
- For floating-base robots, the root freeflyer joint is never locked when using the actuated_joint_names constructor.
[0.10.0] - 2026-03-03
Added
- ECTS (Extended Cooperative Task Space): Dual-arm coordination tasks (reference: H. A. Park, IROS 2016, doi:10.1109/IROS.2016.7759161).
add_absolute_frame_task(): Alpha-blended midpoint frame (Serial L/R, Parallel, Blended).add_relative_frame_task(): Grasp configuration (right EE relative to left EE).add_frame_task(): Single-frame pose task for Orthogonal mode.embodik.map_ects_mode(),map_ects_mode_blended(): ECTS config mapping.- Relative pose constraint:
configure_relative_pose_constraint(),clear_relative_pose_constraint()for bounds on stored relative target. - Interactive example (
05_dual_arm_ects.py): Dual LBR iiwa ECTS demo with Viser. - Six coordination modes (Orthogonal, Serial L/R, Blended, Parallel).
- Orthogonal mode: two independent EE pose controls (blue marker → left EE, green → right EE).
- Mode-change snap keeps arms at current config; markers snap to effective frames.
- Collision avoidance with primitive collision shapes; collision debug visualization.
- Dual iiwa URDF builder (
utils/dual_iiwa_urdf.py): Composes two iiwa14 arms with shared base. - Strips Drake namespace attributes (
drake:acceleration) for parser compatibility. - Replaces high-poly mesh collision (links 6 & 7) with spheres for ~100× faster collision queries.
Changed
- Renamed
ects.hpp/ects.cpptodual_arm_ects.hpp/dual_arm_ects.cppfor clarity. Added IROS 2016 paper citation in headers.
Fixed
- Drake iiwa mesh-based collision geometry (links 6 & 7) caused ~100× slowdown; now replaced with sphere primitives in dual_iiwa_urdf.
[0.9.0] - 2026-03-03
Added
- Joint-limit barrier gradient task:
set_joint_limit_barrier_task(margin, gain)andclear_joint_limit_barrier_task()to proactively drive joints away from limits via an analytical barrier gradient in nullspace. Reduces EE return error and stalls when joints saturate during round-trip motion. - Pose metrics module (
embodik.pose_metrics): C++ implementations with Python bindings forjoint_limit_distance,joint_limit_distance_gradient,velocity_manipulability, andsingularity_joint_limit_metricfor diagnostics and monitoring. - Interactive example (
01_basic_ik_simple.py): Joint limit scaling slider, barrier task toggle, and real-time pose metrics display.
Fixed
- Joint-6 spurious drift bug:
kMinBoundFractionin velocity box constraints no longer injects headroom toward a limit when a joint is already at that limit. AddedkMarginThreshold(0.01 rad) so softening applies only in the direction away from limits. - Limit scaling in example: When narrowing joint limits via the slider, the current configuration is now clipped to the new limits to avoid spurious recovery behavior.
Changed
- Moved
kMinBoundFraction,kMarginThreshold, and pose_metrics constants to file-level for clarity.
[0.8.1] - 2026-02-27
Changed
- CoM margin definition: The fractional margin for polygon shrink now uses
the mean distance from centroid to vertices (
char_size) instead of the minimum distance (min_radius), producing more consistent shrink behavior across polygon shapes.
[0.8.0] - 2026-02-27
Added
- CoM support-polygon inequality constraint API: Enforce the 2D projection of the center of mass to remain inside a convex polygon via per-half-plane QP constraints.
KinematicsSolver.configure_com_constraint(): Configure constraint with polygon vertices, fractional margin shrink, velocity/acceleration limits, and proximity-based activation.KinematicsSolver.clear_com_constraint(): Disable CoM constraint.KinematicsSolver.get_com_proximity_threshold(): Read back the auto-computed activation distance (proximity_fraction × polygon inradius).- Convex hull computation, half-plane extraction, and polygon inradius are handled internally in C++ — callers only provide raw vertices.
- Three-layer velocity bound per half-plane (matching Spot Flex IK pattern):
com_vel_max— always active, caps CoM speed in every direction.sqrt(2 * com_acc_max * slack)— always active, smoothly tapers approach speed well before the boundary (bounded tipping energy).slack / dt— active only near the boundary (when slack < proximity threshold), prevents overshooting in a single time step.- Anti-chattering at boundary: Slack clamped to non-negative for position
and acceleration terms; epsilon dead-zone (0.1 mm) prevents sign-flip
oscillation from numerical noise. Matches the
kMarginEpsilonpattern used in joint position-limit constraints. - Interactive Viser example (
examples/04_com_constraint_example.py): CoM sphere, floor projection disk, vertical drop line, inner/outer polygon boundaries, and color-coded status (green/orange/red). GUI sliders for all constraint parameters. - Unit tests (
test/test_com_constraint.py): API usage, invalid input rejection, Jacobian shape, CoM containment, velocity/acceleration limits, and frame transforms (123 total tests pass).
[0.7.2] - 2026-02-09
Fixed
- Improved position-limit robustness near joint bounds: Increased the
position-limit margin used for position-based velocity constraints from
1e-4to1e-3radians to better absorb solver tolerance and numerical drift during integration. - Post-solve velocity bound enforcement for limited solves:
KinematicsSolver.solve_velocity(..., apply_limits=True)now clamps the returned velocity vector to the effective per-joint bounds (including the intersection of velocity and position-based bounds when both are active).
[0.7.1] - 2026-02-09
Fixed
- Joint position limit enforcement with mixed joint representations:
KinematicsSolver.solve_velocity(..., apply_limits=True)now maps velocity-space indices (v) to the correct configuration-space indices (q) when building position-based velocity constraints. This fixes cases where models include continuous joints (nq=2, nv=1) ahead of bounded revolute joints and the bounded joint could be constrained using the wrongqindex. - Added regression coverage in
test_joint_limit_recovery.pyfor a chain containing a continuous joint followed by a bounded revolute joint to ensure integrated solutions remain within revolute position limits.
[0.7.0] - 2026-02-06
Added
- Joint index access API on
RobotModel: Expose per-joint configuration-space and velocity-space indexing, matching Pinocchio'smodel.idx_qs/nqs/idx_vs/nvsarrays through a clean name-based Python API. RobotModel.has_joint(joint_name): Check if a joint existsRobotModel.get_joint_id(joint_name): Get the internal joint indexRobotModel.get_joint_config_index(joint_name): Starting index in q (idx_q)RobotModel.get_joint_config_size(joint_name): Number of config variables (nq)RobotModel.get_joint_velocity_index(joint_name): Starting index in v (idx_v)RobotModel.get_joint_velocity_size(joint_name): Number of velocity variables (nv)
Notes
These APIs let users build per-joint q/v mappings without importing Pinocchio directly, enabling cleaner joint-to-motor mapping code. For revolute joints, nq=nv=1. For continuous joints, nq=2 (cos/sin) and nv=1. For floating-base, nq=7 (xyz + quaternion) and nv=6 (linear + angular velocity).
Migration Guide
Replace direct Pinocchio joint index access:
# Old - required pip pinocchio
import pinocchio as pin
model = pin.buildModelFromUrdf("robot.urdf")
joint_id = model.getJointId("joint1")
idx_q = model.idx_qs[joint_id]
nq = model.nqs[joint_id]
idx_v = model.idx_vs[joint_id]
nv = model.nvs[joint_id]
# New (v0.7.0) - no pip pinocchio needed
import embodik
robot = embodik.RobotModel("robot.urdf")
idx_q = robot.get_joint_config_index("joint1")
nq = robot.get_joint_config_size("joint1")
idx_v = robot.get_joint_velocity_index("joint1")
nv = robot.get_joint_velocity_size("joint1")
[0.6.0] - 2026-02-06
Added
- Inverse dynamics API on
RobotModel: Full dynamics computations via Pinocchio's RNEA and CRBA algorithms, exposed through native C++ bindings. RobotModel.compute_generalized_gravity(q): Compute gravity torque vector g(q)RobotModel.rnea(q, v, a): Full inverse dynamics via Recursive Newton-Euler Algorithm (returns tau = M(q)a + C(q,v)v + g(q))RobotModel.compute_mass_matrix(q): Joint-space mass/inertia matrix M(q) via CRBARobotModel.compute_coriolis(q, v): Coriolis + centrifugal torque vector C(q,v)*vRobotModel.set_gravity(gravity)/get_gravity(): Configure gravity vector- Boolean collision checking on
RobotModel: RobotModel.check_collision(min_distance=0.0): Returns True if any collision pair has distance below threshold. Simpler API thancompute_min_collision_distance()for pass/fail collision queries.
Notes
These APIs unify robot model functionality that was previously scattered across
separate Pinocchio imports (e.g. pin.computeGeneralizedGravity, pin.rnea,
downstream packages collision checks) into EmbodiK's single RobotModel class,
eliminating the need for a separate pin runtime dependency for dynamics.
Migration Guide
Replace direct Pinocchio dynamics calls:
# Old - required pip pinocchio
import pinocchio as pin
model = pin.buildModelFromUrdf("robot.urdf")
data = model.createData()
tau_gravity = pin.computeGeneralizedGravity(model, data, q)
tau_total = pin.rnea(model, data, q, v, a)
# New (v0.6.0) - no pip pinocchio needed
import embodik
robot = embodik.RobotModel("robot.urdf")
tau_gravity = robot.compute_generalized_gravity(q)
tau_total = robot.rnea(q, v, a)
Replace separate collision checking libraries:
# Old - required direct pinocchio
robot_state.check_collision()
# New (v0.6.0) - built into EmbodiK
robot.update_configuration(q)
in_collision = robot.check_collision() # contact check
too_close = robot.check_collision(min_distance=0.02) # proximity check
[0.5.0] - 2026-02-06
Added
- Lie-group-aware
integrate()method onRobotModel: Properly integrates joint velocities into configurations using Pinocchio's manifold-aware integration. For standard revolute/prismatic joints this is equivalent toq + v*dt, but for floating-base (SE3), spherical (quaternion), and other non-Euclidean joint types it performs the correct exponential-map integration (e.g. quaternion update viaexp). This replaces naiveq += dt * dqaddition which breaks quaternion unit-norm constraints and gives wrong results for continuous and floating-base joints. RobotModel.integrate(q, v, dt=1.0): Manifold integrationRobotModel.difference(q0, q1): Inverse of integrate; returns tangent vectorRobotModel.neutral_configuration(): Returns the home/zero configuration (valid quaternion for floating-base)RobotModel.random_configuration(): Random valid configuration within joint limitsRobotModel.normalize(q): Re-normalize quaternion components of configuration
Fixed
- Position IK
solve_position()now usespinocchio::integrate()instead of naiveq += dt * dqfor velocity integration. This fixes incorrect behavior for floating-base robots where quaternion components were being updated via simple addition, breaking the unit-norm constraint and producing invalid configurations.
Migration Guide
Users who were manually integrating velocities from solve_velocity() using q += dt * dq
should switch to RobotModel.integrate():
# Old (v0.4.x) - broken for floating-base / quaternion joints
result = solver.solve_velocity(q)
q = q + dt * np.array(result.solution) # WRONG for floating-base!
# New (v0.5.0) - correct for all joint types
result = solver.solve_velocity(q)
q = robot.integrate(q, np.array(result.solution), dt) # Always correct
For computing configuration differences:
# Old - broken for floating-base
delta = q1 - q0 # WRONG for floating-base
# New - correct for all joint types
delta = robot.difference(q0, q1) # Returns tangent vector (size nv)
[0.4.0] - 2026-02-05
Breaking Changes
- Removed Python
pinpackage from runtime dependencies: EmbodiK now uses native C++ bindings exclusively for all Pinocchio functionality. Thepip pinocchio(pin) package is no longer required at runtime, only at build time. - This resolves numpy dependency conflicts when using EmbodiK with other packages that have different numpy version requirements
- All rotation utilities (log3, exp3, quaternion conversions) now use native bindings
- Collision distance computation now uses native
RobotModel.compute_min_collision_distance() - Visualization defaults to direct Viser (no Pinocchio ViserVisualizer dependency)
Added
- Native math utilities via nanobind: New C++ bindings for rotation/pose math
embodik.log3(R): Compute axis-angle from rotation matrix (replacespin.log3)embodik.exp3(omega): Compute rotation matrix from axis-angle (replacespin.exp3)embodik.matrix_to_quaternion_wxyz(R): Convert rotation matrix to (w,x,y,z) quaternionembodik.quaternion_wxyz_to_matrix(w,x,y,z): Convert quaternion to rotation matrix- Native collision distance API: RobotModel now exposes collision distance methods
RobotModel.compute_min_collision_distance(): Get minimum distance across all collision pairsRobotModel.compute_collision_distances(): Get distances for all collision pairs- Optional Pinocchio visualization:
pip install embodik[visualization-pinocchio]for Pinocchio's ViserVisualizer (requirespin>=3.8.0)
Changed
- Visualization now defaults to direct Viser implementation (no
pinneeded) utils.pyfunctions (get_pose_error_vector,compute_pose_error,Rt) use native bindingsvisualization.pyquaternion functions use native bindings- GPU collision fallback uses native
RobotModel.compute_min_collision_distance() - Removed
_runtime_deps.py(lazy Pinocchio import no longer needed)
Migration Guide
If you were using Pinocchio Python bindings directly through EmbodiK:
# Old (v0.3.x) - required pip pinocchio
import pinocchio as pin
R_error = pose_goal.rotation @ pose_current.rotation.T
error = pin.log3(R_error)
q = pin.Quaternion(R)
# New (v0.4.0) - no pip pinocchio needed
import embodik as eik
R_error = pose_goal.rotation @ pose_current.rotation.T
error = eik.log3(R_error)
w, x, y, z = eik.matrix_to_quaternion_wxyz(R)
For collision distance computation:
# Old (v0.3.x) - required pip pinocchio
import pinocchio as pin
pin.updateGeometryPlacements(model, data, collision_model, collision_data)
for i in range(len(collision_model.collisionPairs)):
pin.computeDistance(collision_model, collision_data, i)
dist = collision_data.distanceResults[i].min_distance
# New (v0.4.0) - native API
robot_model.update_configuration(q)
dist = robot_model.compute_min_collision_distance()
[0.3.0] - 2026-02-03
Added
- PPH-SNS Solver: Alternative GPU-optimized solver (Parallel Penalized Hierarchical SNS)
- Soft top-k violation selection using softmax weights
- Limited rank-1 projector updates (1–2 violators per iteration)
- Achieves ~632,000 IK solves/second at batch size 10,000
- Benchmark comparison scripts:
benchmark-solver-comparison,benchmark-solver-batched - GPU Acceleration: Batched velocity IK solving with massive parallelism (100-500x speedup)
- Achieves ~670,000 IK solves/second at batch size 10,000
- Ideal for RL training (4096+ parallel environments), motion planning, and dataset generation
- GPU batched solver via CusADi-compiled CUDA kernels
- FI-PeSNS Solver: Fixed-Iteration Penalized eSNS algorithm optimized for GPU
- Singularity-Robust Inverse (SRINV) for numerical stability
- Analytical scaling for feasible task scales without iterative saturation
- Penalty gradient approach for constraint enforcement
- Fixed iterations for predictable compute time (ideal for real-time RL)
- GPU Collision Detection: GPU-accelerated collision detection via NVIDIA Warp
- Batched collision queries for parallel processing
- Experimental support for GPU-accelerated self-collision avoidance
- Parallel Trajectory Tracking Demo: Visualize 100 robot instances simultaneously tracking different trajectories
- Interactive demo with Viser visualization
- Demonstrates GPU parallelization capabilities
- Achieves ~50,000+ IK solves/second with GPU acceleration
- Teleoperation IK Example: Interactive IK control using Seer wireless controller (Xvisio SDK)
- GPU Benchmarks and Demos: Comprehensive benchmarking tools for GPU performance
- Batch IK performance benchmarks
- FI-PeSNS vs CPU accuracy benchmarks
- Collision detection benchmarks
- GPU solver demonstration panels
- CasADi Integration: Export and compile velocity IK functions to CUDA kernels
- Symbolic function export for GPU compilation
- CusADi integration for CUDA kernel generation
- GPU Environment Support: CUDA feature in pixi.toml with GPU-specific tasks
check-cuda,check-gpu,install-cusaditasks- GPU demos and benchmarks via pixi tasks
- CUDA environment configuration
Changed
- Enhanced examples with GPU acceleration support
- Updated dependencies to include xvisio SDK support for teleoperation examples
- Improved GPU documentation and setup instructions
Dependencies
- Added
casadi>=3.6.0andtorch>=2.0.0to[gpu]optional dependencies - Added
warp-lang>=1.0.0to[gpu-collision]optional dependencies - Added
xvisio>=0.3.1to pixi dependencies for teleoperation examples
[0.2.0] - 2026-01-30
Added
- Position IK now supports
excluded_joint_indicesto lock joints during solves - Position IK can enforce collision constraints during iterative solves (when configured)
Changed
- Velocity solver now groups same-priority tasks to make ordering within a priority level symmetric
- Collision constraint computation now uses cached allow-masks to skip excluded pairs efficiently
- Collision recovery near
min_distanceuses deadband + adaptive push to reduce jitter and stalling - Collision constraint default
nearest_points_all_pairsset to true - Collision debug evaluation is side-effect free (no solver state mutation)
Fixed
- Position IK now applies collision constraints and excluded joint indices consistently with velocity IK
- Collision constraint pair selection now uses hysteresis across frames for stability
[0.1.1] - 2025-01-09
Added
- PyPI Publishing: Full wheel building and publishing workflow for TestPyPI and PyPI
embodik-sanitize-envCLI: Helper to sanitizeLD_LIBRARY_PATHfor clean pip installsembodik-examplesCLI: Tool to list and copy examples for pip-installed users- Built-in robot presets:
pandaandiiwapresets work withoutrobot_presets.yaml - sdist build support: Source distribution builds now auto-detect PyPI
pinwheel's Pinocchio
Changed
- Simplified
_runtime_deps.py- removed complex preloading logic, now just providesimport_pinocchio()helper - Documentation updated to recommend
venv + pip + unset LD_LIBRARY_PATHas primary user flow - ViserVisualizer now uses empty GeometryModel instead of None when collisions disabled
Fixed
- Fixed
KeyError: 'pinocchio/frames/universe'in ViserVisualizer whenload_collisions=False - Fixed RPATH for
_embodik_impl.soto correctly findlibembodik_core.so - Fixed sdist builds failing to find Pinocchio by auto-detecting
pinwheel's CMake config - Examples now work correctly for pip-installed users via
embodik-examples --copy
Dependencies
- Added
pin>=3.8.0to build-system requirements for sdist builds - Added
pyyaml,robot_descriptions,viser,yourdfpyto[examples]optional dependencies
[0.1.0] - 2025-12-12
Added
- Initial release of embodiK
- High-performance inverse kinematics solver with hierarchical task resolution
- Python bindings using nanobind
- Support for multiple task types (FrameTask, PostureTask, COMTask, JointTask, MultiJointTask)
- Position and velocity IK solving
- Optional visualization tools using Viser
- Comprehensive test suite
- Example scripts demonstrating various use cases
Technical Details
- C++17 core library built on Pinocchio and Eigen3
- Python 3.8+ support
- Linux x86_64 support
- CMake-based build system
- scikit-build-core for Python packaging