Skip to content

Acceleration Solver

AccelerationSolver is EmbodiK's native fixed-base acceleration-level eSNS surface. It solves for physical joint acceleration ddq from explicit configuration q, velocity dq, and timestep dt:

J(q) * ddq + Jdot(q, dq) * dq = xdd_ref
lower <= C(q, dq) * ddq + bias(q, dq) <= upper

The solver is intended for controller prototyping and fixed-base constrained motion experiments. It is not a hard real-time controller and does not manage command history, integrate a long-horizon trajectory, or replace a downstream jerk-limited actuator interface.

Supported Scope

KinematicsSolver remains EmbodiK's default velocity-level backend. The acceleration solver is a separate, opt-in API: constructing or running it does not replace, reconfigure, or import tasks from an existing velocity solver.

Area Current acceleration support
Model topology Fixed-base scalar 1-DoF joints
State limits Compatible joint position, velocity, and acceleration box
Tasks Frame, CoM, posture, and joint tasks with explicit velocity and acceleration references
Hard rows Task acceleration bounds, affine acceleration rows, frozen next-velocity rows, and scalar joint locks
Dynamics Fixed-base inverse-dynamics effort limits
Allocation Diagonal generalized acceleration metric and reference
Contact Fixed-base point or rigid contact kinematic acceleration equalities
Geometry Tight point, tight frame pose, relative pose, torso pose bounds, and CoM support polygons
Centroidal stability Momentum-rate objective and bounds, predicted capture point, and physical centroidal-rate ZMP
Collision compatibility Canonical velocity collision rows lifted to next velocity, followed by conservative-or-exact sampled validation
Native collision certification Exact-name sphere-sphere catalogs on fixed-base all-prismatic scalar models

Unsupported scope fails explicitly. This includes floating bases, dynamic contact forces, friction cones, wheel rolling/steering constraints, general native collision geometry, and ROS 2 controller or wheelbase integration.

Prescribed acceleration validation

validate_candidate(q, dq, dt, ddq, options) checks a caller-supplied physical joint acceleration through the same hard-row preparation, integration and nonlinear acceptance used by solve(). It skips command optimization and never polishes, refines or replaces ddq. Success returns that unchanged acceleration, q_solution and joint_velocities_next. A rejected candidate has empty motion outputs; it does not prove that every other command is infeasible. The normalized hard-row certificate and each physical constraint family's acceptance tolerances match those used by solve().

options = embodik.AccelerationSolveOptions()
options.acceleration_limits_override = np.full(robot.nv, 10.0)
result = solver.validate_candidate(q, dq, 0.01, proposed_ddq, options)
if result.status == embodik.SolverStatus.SUCCESS:
    q_next = result.q_solution
    dq_next = result.joint_velocities_next

The result is a command-feasibility check, not an optimum or task-achievement report: task diagnostics, scales and backend problem traces are empty, and final_error and condition_number are NaN. backend_computation_time_ms is zero. Total native timing includes preparation and acceptance. Geometric support checks may still perform numerical feasibility searches. Registered tasks are still prepared when needed by hard task bounds, but their objectives are not optimized.

The initial API rejects nominal-position envelopes, generalized allocation and nonzero stored elastic deltas or capacities. It leaves persistent elasticity unchanged. Optimization preferences do not authorize candidate modification.

validate_candidate_with_velocity_collision(provider, q, dq, dt, ddq, options, lift_options) additionally retains the original velocity-collision rows and sampled checks. Its collision refinement budget must be zero. All existing unsupported-family guards apply. This retains sampled collision validation; it does not establish safety between samples, complete stopping or recovery. To validate a prescribed multi-step rollout, use each original control interval and its actual incoming velocity, then validate its terminal rest command.

For prescribed commands, setting lift_options.candidate_validation = embodik.CollisionCandidateValidation.PHYSICAL_SAMPLES omits only the adapter's internal frozen collision construction rows. This allows a curved, floor-safe interval ending at rest even when its incoming distance Jacobian predicts a floor violation. All caller affine and frozen rows, joint limits, acceleration limits, CoM checks, and the configured collision samples remain active. The default FROZEN_ROWS retains the existing behavior; solve_with_velocity_collision() rejects PHYSICAL_SAMPLES.

This mode requires zero collision repulsion deadband and initially satisfied effective floors at the existing 1e-8 sample tolerance. It validates sampled geometry rather than the legacy recovery controller. It changes neither the number of samples nor their floor tolerance. Complete stopping admission remains the application's responsibility; the result still does not certify the continuous path between samples.

Explicit-state acceleration collision row construction uses isolated precise distance queries for pair ranking and nearest-point Jacobians. These queries do not inherit warm GJK guesses from earlier configurations or debug calls. Ordinary velocity-solver queries retain their existing behavior. Physical clearance checks and numerical acceptance tolerances are unchanged. Sampled acceleration collision validation also uses cold, precise queries, matching explicit pair-distance evaluation rather than inheriting coarse GJK guesses from earlier samples. An invalid numerical distance, including the collision library's finite failure sentinels, receives one fresh query initialized from the shapes' local bounding box centers. Precision settings remain unchanged. The retry computes a signed geometry distance; it does not substitute a bounding-volume distance. An unresolved query failure remains an error and cannot become a collision floor.

Inequality Constraint Parity

The acceleration surface represents velocity inequalities on dq_next = dq + dt * ddq and acceleration inequalities directly. It does not silently import mutable KinematicsSolver configuration, so adapter-owned rows must be supplied explicitly.

Current velocity constraint family Acceleration behavior
Joint position, velocity, and acceleration limits Native combined acceleration state box, with accepted-state recheck
General linear velocity rows Supported through FrozenNextVelocityConstraint
Task-space finite-step bounds Supported through TaskAccelerationBounds; position-step priority-policy rows are not imported automatically
Self-collision include/exclude filters and per-pair floors Supported through solve_with_velocity_collision() using the configured velocity solver
CoM support polygon Native ComSupportPolygonAccelerationConstraint for fixed-base/root-fixed support
Centroidal momentum-rate objective and bounds Native physical Ag * ddq + dAg * dq rows for fixed-base models
Predicted capture point Native CapturePointAccelerationConstraint using the solver's constant-acceleration integration rule
Physical centroidal-rate ZMP Native ZmpAccelerationConstraint with a positive vertical-force gate and accepted-state recheck
Tight point and frame pose bounds Native acceleration constraints
Relative pose bounds Native acceleration constraint
Torso pose bounds Native acceleration constraint with an explicit caller-owned reference pose
Joint locks Zero acceleration, zero next velocity, and fixed current-position lock rows
Fixed-base effort limits Native inverse-dynamics inequalities
Floating-base position/orientation bounds Rejected because the fixed-base solver constructor rejects floating-base topology
Native collision combined with other hard-row families Rejected until the combined predicted-state certificate is implemented

Seed corridors, adaptive timesteps, preferred-lock retries, stall recovery, task-layout selection, and weighted position-step fallback are stateful KinematicsSolver controller policies rather than missing acceleration inequalities. A controller adapter must implement or reject those policies explicitly. Manipulability and joint-limit avoidance are velocity objective families, not hard inequality rows, and are not currently exposed as acceleration tasks.

Scaling and nominal-position elasticity

SCALE preserves the acceleration objective direction through the native SNS backend. MIN_ERROR uses its native constrained error objective. SCALE_ELASTIC uses SNS SCALE plus a persistent nominal-position band. It does not rename a MIN_ERROR solve. Task diagnostics report the effective backend mode and explicit fallback use.

When an authorized fallback has already selected MIN_ERROR, a numerical hard-bound rejection can retry that effective policy from the original problem. This does not authorize fallback for other tasks or soften hard rows; task diagnostics retain the fallback flag. If a higher-priority numerical repair has already completed, a lower-task retry carries its achieved images as exact equality constraints. The verified feasible checkpoint seeds the existing optimizer; it is not returned as a substitute for optimization. Original hard bounds and completed-image tolerances still apply. An almost-zero Cartesian task error does not suppress this retry when the candidate violates hard bounds; tracking accuracy alone is not feasibility.

At nonzero joint velocity, the affine term Jdot * dq can make zero acceleration incompatible with the task ray even when a positive scale is feasible. When directional recovery needs a new seed, the CPU backend searches joint acceleration and scale together, retaining the original hard bounds and the achieved higher-priority task images. It audits that seed before refining the scale; a feasibility witness alone is not an executable command. The normal predicted-state and command-path acceptance checks still apply.

Use MIN_ERROR for a lower-priority posture preference when it should make the best available use of the remaining freedom. A lower-priority SCALE task still requires its exact scaled direction, including any zero components; that direction can conflict with an already achieved higher-priority task at every scale. In that case the solve can return NO_PROGRESS even though the higher-priority task alone has a positive feasible scale. Configuring the posture as MIN_ERROR preserves the higher-priority task image without requiring the posture's exact direction. This is an explicit task policy; the solver does not silently relax a requested SCALE task.

The model position limits are immutable physical bounds. Optional full-nq nominal_position_lower_bounds and nominal_position_upper_bounds define a narrower working envelope inside those bounds for every task mode. Elastic expansion applies only with an active SCALE_ELASTIC registered task or CentroidalMomentumRateObjective, and it is capped by elastic_delta_max and by the physical model bounds. With no separate nominal envelope the expansion capacity is zero. Measured or caller-owned affine rows, velocity and acceleration limits, collision floors, CoM polygons, and effort bounds stay fixed.

Default band parameters are elastic_delta_max=0.05, elastic_expand_rate=0.01, elastic_decay_rate=0.2, and elastic_expand_only_saturated=True. Delta and expansion use each scalar joint's coordinate units. Expansion and multiplicative decay apply per solve. A boundary seed receives a small initial band. Low task scales expand eligible bands, and unconstrained bands decay. Only finite uniform scales in [0, 1] contribute to the low-scale test; MIN_ERROR diagnostics use a -1 sentinel, which does not indicate a stalled scale. Occupied position and outward braking reserve are retained up to the configured capacity. States that need a larger reserve fail closed. Nominal changes reset the band. reset_elastic_band() clears it without replacing caller q or dq. get_elastic_band_deltas() exposes the persistent state. Results expose the band used for the attempt, the effective nominal bounds, and each side's expansion capacity. Post-solve expansion and decay run only after a successful native solve. This band is solver adaptation, not accepted physical history.

Affine State Envelopes

For fixed-base additive scalar joints, AffineStateConstraint expresses y = C @ q + offset. Its position bounds, symmetric rate/acceleration ceilings and declared braking magnitudes use the same envelope builder as geometric constraints. This supports coupled joint facets without projecting a solved command back onto a position bound.

import numpy as np
import embodik

envelope = embodik.AffineStateConstraint()
envelope.source_id = "coupled-joints"
# For a two-coordinate model: -0.5 <= q[0] + q[1] + 0.25 <= 0.5.
envelope.coefficient_matrix = np.array([[1.0, 1.0]])
envelope.offset = np.array([0.25])
envelope.lower_bounds = np.array([-0.5])
envelope.upper_bounds = np.array([0.5])
policy = embodik.GeometricConstraintAccelerationPolicy()
policy.rate_limits = np.array([1.0])
policy.acceleration_limits = np.array([10.0])
policy.lower_braking_accelerations = np.array([2.0])
policy.upper_braking_accelerations = np.array([2.0])
envelope.policy = policy
options = embodik.AccelerationSolveOptions()
options.affine_state_constraints = [envelope]

Every policy vector must match the number of rows. Matrices and offsets are frozen for one call; state-dependent coefficients require a different model. The adapter validates endpoints and every interior quadratic position extremum, then checks next-state viability and joint acceleration support. Outside states are rejected. Braking support is required toward a moving coordinate's active boundary when its remaining margin is within stopping distance plus one control horizon's maximum outward travel. This is re-evaluated at the actual integrated endpoint. A stationary coordinate does not require acceleration further into a limit. Per-axis braking support is not a certificate of a complete jointly feasible stopping trajectory, especially with other hard constraints. Native collision certification and the sampled velocity-collision adapter explicitly reject this family until their stopping integration is qualified.

These are caller-supplied acceleration constraints. Rows configured through KinematicsSolver.set_linear_position_constraints() remain velocity/position-step constraints and are not automatically imported into acceleration solves. The velocity-collision adapter rejects both those provider rows and explicit affine state envelopes while their combined stopping integration remains unsupported.

Compatible Joint Box

Every solve starts from one combined state box. Position, velocity, and acceleration limits are expressed as compatible bounds on the same ddq decision, so an accepted command cannot satisfy one derivative-order limit by contradicting another. Position and velocity limits are enabled by default; callers may supply an acceleration-limit override for models without usable acceleration metadata.

options = embodik.AccelerationSolveOptions()
options.acceleration_limits_override = acceleration_limits
result = solver.solve(q, dq, dt, options)

Set options.refine_partial_scale = True to request one additional bounded refinement when a directional SCALE objective achieves only part of its target. This is disabled by default. Refinement preserves earlier task images and original hard bounds; a larger primary scale can change lower-priority errors and increase computation time. It does not guarantee nonlinear convergence or recovery from an infeasible state.

Set options.prefer_direct_min_error_qp = True to prefer feasible-primal quadratic optimization for an all-MIN_ERROR hierarchy after a complete hard-set feasibility witness is available. Each earlier achieved task image becomes an equality for later objectives. The default is False. This can improve minimum error quality or reduce inverse operations; latency depends on the objective structure and quadratic iterations. An unsuccessful direct attempt returns to the established search. It does not bypass original SCALE/ELASTIC attempts or authorize new fallbacks. For an all-MIN_ERROR hierarchy, this preference also obtains a concrete feasibility witness when the joint box was already prevalidated. This lets state-box-only solves use the requested direct route. Physical and nonlinear acceptance checks still apply.

Zero or subthreshold references are valid for this explicit direct route. They request minimum task error or motion subject to the hard constraints; they do not force a zero command when the hard set requires motion. This also applies when scalable targets and affine biases cancel.

When the combined box requires braking, zero acceleration is outside the hard set. The default allow_state_box_task_fallback = True makes the resulting MIN_ERROR task fallback explicit while preserving the mandatory braking command. Set it to False when strict task semantics should fail closed instead. state_box_task_fallback_applied reports which policy was used.

For optional posture preferences, options.allow_best_effort_lower_tasks = True can retain an already validated higher-priority command when numerical recovery cannot optimize a trailing MIN_ERROR task. The default is False. This does not change a failed primary task into success: at least one earlier objective must have completed, and its achieved image and every hard row are rechecked. An infinite task condition number can reflect a redundant or masked task row; it does not invalidate a finite command that passes those checks. Unfinished lower objectives remain marked as unoptimized, and nonlinear acceptance still applies. Lower-task optimality is not certified; the result reports the recovery in its status message and fallback flags. Physical and nonlinear acceptance checks still apply, so this option cannot guarantee an executable command.

Updating option lists

Python acceleration-option lists return owned snapshots of their records. To update a stored record, edit the snapshot and assign the list back:

saved_rows = options.affine_constraints
options.affine_constraints = []
# saved_rows remains valid after the source list is replaced.
options.affine_constraints = saved_rows

zmp_rows = options.zmp_constraints
zmp_rows[0].fz_min = 10.0  # Assumes a ZMP constraint was already configured.
options.zmp_constraints = zmp_rows

The same snapshot semantics apply to task bounds, centroidal objectives/bounds, contacts, and geometric constraint lists. Editing a snapshot alone does not change the stored options; reassign it to apply the edit.

Only SolverStatus.SUCCESS carries executable acceleration, next-velocity, and configuration outputs. Failures clear those outputs.

Machine-roundoff excursions outside the compatible acceleration box are snapped to the original violated face before coupled checks and integration. This prevents an almost-zero outward acceleration from creating a falsely infeasible predicted boundary state. Larger violations retain their existing validation policy. Joint state-box errors include the joint index, position, velocity and active position bounds to help reproduce a rejected state.

A roundoff-sized boundary or braking-envelope failure can instead select a single braking command certified within the original physical acceleration caps. It first tries a scale-free gentler witness using the same local arithmetic budget, then retains the full-cap witness as a fallback. Each candidate must pass the same endpoint, rate, in-step stopping, declared-braking, and nominal next-box checks. This selects one certified command; it does not expose a full feasible acceleration interval. This preserves the supplied position and velocity. The command must stop outward motion within the control interval, respect position endpoints and rate limits, and satisfy this solve's local next-box check. Stopping vertices are checked against a local position arithmetic budget, including the configured braking policy; this permits tiny numerical excursions, not exact real-number containment. All coupled constraints and nonlinear acceptance checks still apply. Larger outward motion and states without a valid braking command remain rejected.

Per-step success is not a guarantee that the next call admits a continuation or complete stop. Coupled constraints and finite-arithmetic boundary transitions can still reject a later call, including a fail-closed boundary-continuation limitation under investigation. Carry the actual returned state and handle failure explicitly; sustained-saturation and far-target return recovery are not qualified by this release. See the release scope.

For successful solves without generalized acceleration allocation, a small numerical acceleration residual can be projected into the original state box. The corrected command must retain the original hard-row certificate and achieved objective images at their existing tolerances, then pass every physical and nonlinear validator. Already in-box commands are unchanged. This correction does not alter the supplied state or relax its limits.

If a CoM acceleration bound passes the initial linear model but fails along the sampled command path, the solver can perform up to eight corrective solves. Each adds local CoM acceleration rows at violating path samples and re-solves the original objectives with every original hard constraint retained. The local rows differentiate the complete constant-acceleration path, including changes in configuration, velocity, the CoM Jacobian and its acceleration bias. Central differences share evaluations across polygon edges at the same sample time. They add work per correction and can reduce the number of retries; latency depends on the model and command.

Geometric path checks retain fixed quarter-interval samples alongside every point of the adaptive grid. Increasing the grid density therefore cannot drop these fixed checks. Existing adaptive sample times keep their original floating-point calculation. CoM corrective rows use the same combined schedule, and the validation budget covers all samples. This remains sampled validation; it does not certify the continuous path between samples.

The corrected command must pass all existing acceptance checks. These local rows do not establish global nonlinear optimality or continuous collision safety. Accumulated local rows can exclude a feasible nonlinear solution, so failure to complete refinement is not a proof of physical infeasibility.

Joint-limit braking and CoM acceleration bounds can also become jointly infeasible after an accepted step, even while the CoM is well inside its support polygon. Per-joint braking viability and sampled CoM validation do not establish feasibility of their intersection at the next control step. Returning a Cartesian target cannot resolve an infeasible hard set at an unchanged configuration and velocity. Applications that require continuous recovery must retain a stopping policy validated against all active constraints; the current solver does not provide that guarantee. Do not interpret a rejected step as zero physical velocity or reset velocity history to conceal the conflict.

For tight-frame pose constraints, translation and rotation state-bound and endpoint braking violations can also trigger bounded corrective solves. The local model includes both the endpoint configuration and velocity derivatives. Each correction retains the original hard rows and objective policies, adds a local acceleration trust box, and repeats the complete nonlinear acceptance checks. Rotation rows differentiate the SO(3) log coordinates and their rates, including the moving expression frame. Chart and predicted-support failures retain their rejection behavior. Translation, rotation and CoM corrections share the bounded retry budget; enabling a corrective direction does not guarantee faster convergence. At a violating frame sample, the solver groups other violated active scalar faces at that sample and the endpoint into the same local solve. Endpoint braking checks apply only at the endpoint, and the group shares one trust box. These corrections do not establish global recovery or nonlinear optimality. result.nonlinear_refinement_iterations reports the number of corrective solves; zero means the original candidate needed no correction. Reported timings include the retries. Exhausted or unsuccessful corrections return NUMERICAL_ERROR with cleared motion outputs.

For latency-sensitive controller loops, set options.collect_task_diagnostics = False. This skips rich physical per-task records while preserving task scales, task errors, solver status, and all executable outputs. computation_time_ms covers the complete C++ solve; preprocessing_time_ms, backend_computation_time_ms, and postprocessing_time_ms expose its measured phases. For solve_with_velocity_collision(), these phase fields describe the inner acceleration solve; computation_time_ms also includes collision-row lifting and sampled endpoint validation.

Task References

Acceleration tasks use explicit measured-state feedback and feedforward:

reference = embodik.AccelerationTaskReference()
reference.desired_velocity = desired_task_velocity
reference.desired_acceleration = desired_task_acceleration
reference.proportional_gain = kp
reference.derivative_gain = kd
solver.set_task_reference("ee_position", reference)

The proportional term also multiplies task.weight; measured-rate damping does not. For a static posture target with unit joint weights, the requested acceleration is kp * task.weight * (q_target - q) - kd * dq. PostureTask defaults to weight 0.1, so set posture.weight = 1.0 explicitly when the desired law is kp * (q_target - q) - kd * dq. A smaller weight with unchanged damping can produce a slow, overdamped response even when the numerical solve is fast.

Each call takes explicit q and dq. Keep them synchronized with the measured or actually applied state when switching controllers or rejecting a result. A rejected result does not establish zero physical velocity; do not silently replace incoming dq with zero.

Centroidal Stability

Centroidal momentum-rate rows use six-axis order [linear x, y, z; angular x, y, z]. The objective and bounds operate on the physical quantity:

hdot = Ag(q) * ddq + dAg(q, dq) * dq

Predicted capture point uses CoM position, velocity, physical acceleration, a per-solve frozen omega, and the same constant-acceleration integration rule used for q_solution and joint_velocities_next.

Physical centroidal-rate ZMP uses net force after gravity, enforces Fz >= fz_min > 0, and retains CoM-height and horizontal-force terms in every cross-multiplied polygon row. Successful results are postvalidated at the nonlinear predicted state.

These capabilities are fixed-base solver constraints. AccelerationSolver.capabilities().supports_dynamic_balance remains false: the rows do not allocate contact wrenches, enforce friction cones, or prove floating-base contact-force feasibility. See Centroidal Stability for units, frame conventions, velocity-level semantics, formulas, and diagnostics.

Collision Modes

Velocity-row compatibility

solve_with_velocity_collision() consumes an already configured KinematicsSolver. It reuses that solver's collision pair filtering, include/exclude policy, active per-pair floors, row ordering, and row budget. Row construction examines the current pair catalog, bypassing historical candidate-subset and approximate row reuse. Current-state geometry broadphase culling remains available. This avoids missing a newly active pair during explicit-state solves or hypothetical stopping rollouts; a successful solve does not certify that a complete future stopping trajectory exists. If fewer current candidates remain than the row budget, the list stays underfilled. Historical pairs culled by the current query do not supply rows using old distances or nearest points. Mandatory current near-floor rows still remain active even when they exceed the nominal row budget. The lifted rows constrain dq_next = dq + dt * ddq. Every allowed pair at every requested constant-acceleration sample is accounted for in canonical order. A conservative enclosing-sphere lower bound may prove a pair safe; ambiguous geometry falls back to the exact collision backend.

With provider acceleration limits enabled, this explicit-state path constructs its braking proxy for the endpoint of the current constant-acceleration interval. For frozen distance rate r, endpoint rate w, physical-floor slack s and estimated separating acceleration A, it budgets w*w/(2*A) <= s + dt*(r+w)/2 for closing motion. This uses physical-floor slack in the braking proxy. Outside any explicitly configured repulsion deadband, the satisfied-floor row also budgets the integrated interval: w >= -r - 2*s/dt. Positive physical clearance remains usable inside the legacy velocity-command construction reserve. Explicit deadbands and violated-floor recovery rules remain unchanged. Ordinary velocity commands retain their construction reserve and separate command-delay braking policy.

This is a local construction policy, not a nonlinear braking certificate. Changing nearest features, distance curvature and simultaneously available multi-pair acceleration are not established by this frozen model. Original sampled geometry acceptance still applies, and applications requiring complete stopping must independently admit a stopping continuation.

This path is fail-closed but sampled. A successful result reports collision_endpoint_validated = True and collision_step_certified = False; increasing validation substeps does not turn samples into a continuous swept-path proof.

Optional sampled collision correction

VelocityCollisionLiftOptions.max_refinement_iterations defaults to zero. A positive value (at most eight) allows bounded local corrections after a sampled collision rejection on a fixed-base scalar revolute/prismatic model. For example:

import embodik

lift = embodik.VelocityCollisionLiftOptions()
lift.max_refinement_iterations = 2
lift.refinement_trust_radius = 0.5  # Joint acceleration coordinate units / s^2.
lift.refinement_clearance_reserve = 1e-6  # Metres; added to local planning rows.
result = solver.solve_with_velocity_collision(collision_solver, q, dq, dt, options, lift)

Each correction adds a hard linearized distance row at the failed sample and a hard acceleration trust box. Earlier correction rows always remain hard. Its distance and nearest-point derivatives use the same cold, precise query policy as collision floors and sampled acceptance. Original floors and the acceptance tolerance remain unchanged. If a corrective solve fails numerically, makes no progress, or reports infeasibility, the wrapper may remove only its internally appended trust boxes and retry over the original physical domain, provided the original solve succeeded and retry budget remains. Caller rows (including caller trust boxes) are never removed. An unrestricted retry consumes the same budget, adds no distance query, and is not repeated without a new internal trust box. Original tasks, modes, allocation, limits, frozen collision rows, CoM definitions, and incoming state remain unchanged. All existing acceptance checks run again. Separated pairs that start below their floor retain the validator's original non-worsening threshold. Penetrating geometry, unsupported joints, or unavailable finite gradients retain the existing sampled rejection; this facility does not supply global recovery or feasibility proofs. A failed local solve returns NUMERICAL_ERROR with cleared motion outputs, because infeasibility of a local model does not prove physical infeasibility. Budget exhaustion retains COLLISION_VIOLATED with cleared outputs.

collision_refinement_iterations counts extra full solves, including a retry after internal trust removal, and is separate from nonlinear_refinement_iterations, which counts CoM and tight-frame translation corrections across these attempts. With multiple validation samples, refinement selects one materially violating time sample of the first failed pair by its normalized affine-cut violation in acceleration coordinates, including the configured clearance reserve. Passing samples add no cut; exact score ties keep the earlier time. The generated row source identifies the selected sample. All original sampled collision checks still decide acceptance. This selection does not guarantee recovery within the bounded budget.

collision_refinement_exact_queries and its kinematics/geometry counters report extra local-model work, separately from sampled-validation counters. Validation counters accumulate across attempts. Inner phase timings sum the inner solves; total time also includes row lifting, validation, and local model construction. Failed opt-in transactions restore elasticity and report that retained state. The default zero-budget path retains legacy elasticity behavior. No setting provides swept-path certification: collision_step_certified remains false.

Native analytic certification

configure_collision_constraint() enables continuous constant-acceleration certification only for complete exact-name sphere-sphere catalogs on fixed-base all-prismatic scalar models. It proves the current hard row, common reachable braking authority, the integrated path, and predicted-state viability.

While native certification is configured, only joint state boxes, generalized allocation, and soft tasks may be combined with it. Other hard families are rejected until they provide the same predicted-state certificate contract.

Redundant minimum-error objectives

Constrained MIN_ERROR solves preserve the task residual factors for QR steps and gradient evaluation. This avoids squaring their condition number in normal equations, which can cause false numerical stalls in redundant task directions. The scale-relative numerical ridge, priorities, hard constraints and acceptance checks remain unchanged. This improves linear numerical solving; it does not guarantee global nonlinear recovery or stopping feasibility.

When a higher-priority task already fixes an active constraint, projecting that constraint into the remaining motion space can leave only cancellation roundoff. Generalized hierarchical solves use the original constraint-row scale as a floor for the inverse's numerical rank decision, rather than magnifying that residual into a new motion direction. The original hard row and completed task images still require validation. This numerical correction preserves the SCALE ray, fallback permissions and physical tolerances.

Recording a backend problem

Set options.record_linear_problems = True to retain result.linear_problems. Each AccelerationLinearProblemTrace owns the exact backend targets, affine biases, objective matrices/configuration, hard rows and bounds, state, timestep, remaining refinement budget and raw backend result. Constraint row source IDs identify local refinement rows. Snapshots are ordered from the outer call to the deepest nonlinear refinement, including failed calls. Failures before backend assembly produce no snapshot.

options.record_linear_problems = True
result = solver.solve(q, dq, dt, options)
for problem in result.linear_problems:
    replay = embodik.replay_acceleration_linear_problem(problem)
    print(problem.diagnostics.termination_reason, replay.status)

Recording is disabled by default and adds matrix copies when enabled. It changes no solver policy or acceptance tolerance. Phase I status/witness and preferred MIN_ERROR QP attempt/success diagnostics distinguish an unsuccessful preferred attempt from its subsequent ordinary search. A generic helper refusal may not identify an internal active-set exit; it is not a proof of infeasibility.

Replay covers only the linear backend in its recorded coordinates. With allocation enabled, these are allocation coordinates rather than physical joint accelerations. Neither a successful replay nor a recorded intermediate solution certifies integration, collision clearance, CoM acceptance or stopping safety. Never execute a trace as a robot command.

Build And ABI Notes

The acceleration API was introduced in 0.21.0 on top of the 0.20.x velocity-solver integration baseline. The shared Task virtual interface is unchanged. The 0.22.0 centroidal additions extend public solver option and result layouts, so native consumers must rebuild embodik_core and the Nanobind extension together. Pre-1.0 native binaries are not compatible across minor releases. The 0.23.2 robustness update also extends public option and result layouts: native consumers must rebuild against the matching headers, core library, and Python bindings, including when upgrading from an earlier 0.23.x build.

API Reference

Solver

AccelerationSolver

Functions

validate_candidate

validate_candidate(q, dq, dt, ddq, options=...)

Validate an unchanged physical ddq without command optimization. Success reports feasibility and integrated state, not task achievement. Nominal envelopes, allocation and nonzero elastic history are unsupported; elastic history is unchanged. Geometric support may require feasibility searches.

validate_candidate_with_velocity_collision

validate_candidate_with_velocity_collision(
    collision_solver, q, dq, dt, ddq, options=..., lift_options=...
)

Validate an unchanged ddq with sampled checks and, by default, frozen collision rows. PHYSICAL_SAMPLES omits only internal construction rows for initially satisfied floors and zero repulsion deadband. Collision refinement budget must be zero. This does not certify continuous collision safety or complete stopping.

AccelerationSolveOptions

Attributes

allow_best_effort_lower_tasks property writable

allow_best_effort_lower_tasks

Retain a validated higher-priority command if numerical recovery cannot optimize a trailing MIN_ERROR task. Lower-task optimality is not certified; hard and nonlinear checks remain.

allow_state_box_task_fallback property writable

allow_state_box_task_fallback

Allow an explicit MIN_ERROR fallback when the compatible state box requires nonzero braking acceleration.

collect_task_diagnostics property writable

collect_task_diagnostics

Retain rich per-task acceleration diagnostics. Disable in latency-sensitive loops that only require scales and errors.

prefer_direct_min_error_qp property writable

prefer_direct_min_error_qp

Prefer a feasible-primal quadratic solve for an all-MIN_ERROR hierarchy after hard feasibility is established. Scaling and fallback authorization remain unchanged. An unsuccessful direct attempt returns to the established search.

refine_partial_scale property writable

refine_partial_scale

Opt in to bounded refinement of feasible partial SCALE commands, preserving earlier task images and hard bounds. An improved primary scale can change lower task errors.

AccelerationSolverResult

Bases: SolverResult

Attributes

nonlinear_refinement_iterations property

nonlinear_refinement_iterations

Number of bounded nonlinear CoM or tight-frame translation corrective solves.

AccelerationSolverCapabilities

Tasks And Diagnostics

AccelerationTaskReference

AccelerationTaskDiagnostics

AccelerationAllocationDiagnostics

CentroidalMomentumRateObjective

Fixed-base physical hdot objective: Agddq + dAgdq.

CentroidalMomentumRateBounds

Selected-axis hard bounds on physical centroidal momentum rate.

CentroidalMomentumRateDiagnostics

CapturePointAccelerationDiagnostics

ZmpAccelerationDiagnostics

AccelerationAnalyticCollisionPairDiagnostics

State, Effort, And Hard Rows

AffineAccelerationConstraint

FrozenNextVelocityConstraint

TaskAccelerationBounds

GeneralizedAccelerationAllocation

EffortConstraintOptions

ContactAccelerationConstraint

Geometric Constraints

GeometricConstraintAccelerationPolicy

ComSupportPolygonAccelerationPolicy

ComSupportPolygonAccelerationConstraint

CapturePointAccelerationConstraint

Predicted capture-point polygon constraint with per-solve frozen omega.

ZmpAccelerationConstraint

Physical centroidal-rate ZMP polygon rows with a positive Fz gate.

TightPointAccelerationConstraint

TightFramePoseAccelerationConstraint

RelativePoseAccelerationConstraint

TorsoPoseBoundAccelerationConstraint

Collision Compatibility And Certification

VelocityCollisionLiftOptions

CollisionConstraintAccelerationPolicy

AccelerationCollisionRegime

Bases: Enum

CollisionGeometryPair

CollisionPairMinimumDistance

CollisionConstraintDefinition

ComSupportPolygonConstraintDefinition

RelativePoseConstraintDefinition

TightPointConstraintDefinition

TightFramePoseConstraintDefinition

TorsoPoseBoundDefinition

ContactType

Bases: Enum

ComSupportPolygonOutsidePolicy

Bases: Enum

CollisionConstraintOutsidePolicy

Bases: Enum