The panel shows a motor at 350° with a 0° target, but the controller commands a 350° unwind instead of the 10° forward move. Start here: inspect the angle error used by the objective. The optimizer sees the numbers you supplied, not the physical equivalence of 0° and 360°. That is not an IPOPT fault.
Identify the topology symptom
Record the current angle, target angle, calculated error, and commanded direction. A scalar subtraction produces 0° - 350° = -350°. On a continuous rotation axis, the physical shortest displacement is +10°. If the objective penalizes the scalar error directly, the long move is mathematically cheaper according to the model it received.
| Observed symptom | Likely cause | Next check |
|---|---|---|
| Axis takes the long route across the wrap point | Linear angle subtraction in the cost or reference error | Evaluate the error at 350° and 0° |
| Prediction jumps when angle crosses 360° | State or measurement uses inconsistent angle ranges | Compare estimator, model, and reference conventions |
| Quaternion norm drifts during prediction | Rotation coordinates lack a unit-norm constraint or compatible dynamics | Inspect the state equation and constraint residual |
| Solver fails only after adding rotation constraints | Poor initialization, scaling, or an infeasible manifold constraint | Read constraint residuals and the solver termination result |
| Scenario count becomes unmanageable | Multi-stage uncertainty branches grow exponentially with the control horizon | Inspect the branching depth |
Measure the error at the wrap point
Check the objective before changing solver settings. Evaluate it on both candidate moves: the direct numeric difference and the physically shortest rotation. If the cost favors a 350° move, the fault is in the error representation.
- Read the measured angle immediately below and above the chosen wrap boundary.
- Read the reference and calculate the exact error expression passed into the stage and terminal costs.
- Evaluate that expression for
350° to 0°. - Compare the sign of the resulting error with the commanded direction.
- Move next to state representation only if the objective already treats equivalent orientations identically.
A periodic error can be formed from trigonometric functions. A cost involving sin(angle) can prevent the optimizer from interpreting a full revolution as a distinct position. For a signed shortest-angle error, a common formulation is atan2(sin(e), cos(e)), where e is the reference-minus-state error in one consistent angular unit. Another periodic penalty is 1 - cos(e). Test the full operating range because a trigonometric expression changes the cost landscape and may introduce stationary points that a linear error did not have.
Check the rotation state representation
For planar rotation, an angle state with periodic cost logic is usually the shortest repair. Use one convention throughout the measurement conversion, estimator, dynamic model, bounds, reference, and objective. Normalizing only the displayed value wastes time if the prediction model or reference still uses a different interval.
For 3D rotation, the problem is not just wraparound. Orientation lies on a non-Euclidean state space. The documented approaches are:
- Keep angles as states and perform quaternion operations inside the dynamic state equation.
- Use quaternion components directly as states and add a unit-norm constraint.
The first approach keeps the decision variables familiar but inherits the singularities and coordinate limits of the selected angles. The second avoids an angle-chart singularity, but the optimizer must satisfy the quaternion dynamics and unit-norm constraint. Read the predicted norm at every node, not only at the initial state. A valid initial quaternion does not make later prediction nodes valid automatically.
Do not add a unit-norm constraint and immediately blame the solver when the problem becomes infeasible. First check state initialization, reference normalization, dynamic consistency, scaling, and the residual of the norm constraint.
Separate model formulation from optimizer behavior
do-mpc 4.0.0 uses orthogonal collocation for ODE models. CasADi supplies automatic differentiation for exact first- and second-order derivatives and provides the interface to optimization tools including IPOPT. Those components differentiate and solve the nonlinear program that you formulate; they do not infer that two scalar angle values represent the same physical orientation.
Read three outputs in order:
- Inspect the objective terms. Confirm that equivalent orientations produce equivalent penalties.
- Inspect equality and inequality residuals. Find the first prediction node where the model or rotation constraint fails.
- Inspect the optimizer termination result. Change IPOPT-related settings only after the objective and constraints represent the physical problem correctly.
Increasing iteration limits or changing tolerances cannot repair a cost that requests the long path. Likewise, a different initial guess may hide the symptom for one starting angle while leaving the topology error in place.
Bound multi-stage uncertainty growth
Angle topology and parameter uncertainty are separate decisions. In the documented 4.0.0 architecture, do-mpc handles parametric uncertainty with multi-stage MPC. Parameter selections define scenarios, and different control inputs are calculated for different branches. Every scenario must obey state constraints such as upper and lower bounds.
The number of branches grows exponentially with the control horizon. Stop branching after a selected depth to bound the optimization size. Record the scenario count, solve time, and constraint residuals as you change that depth. Reducing branching may restore execution time, but it does not fix angle unwinding; the periodic state error must be corrected in every scenario.
This architecture is not tube-based MPC. Tube-based MPC was listed as future roadmap work for the documented release. Do not tune a multi-stage scenario tree as though it were a tube controller.
Apply the fix and verify every boundary
- Select a single angular unit and range for measurements, references, model states, and diagnostic displays.
- Replace direct scalar angle subtraction in the objective with the selected periodic error or periodic penalty.
- For angle-state 3D models, verify coordinate validity throughout the expected motion. For quaternion states, normalize the initial and reference orientations and apply the unit-norm constraint.
- Regenerate the prediction from positions on both sides of the wrap boundary.
- Confirm that
350° to 0°commands the 10° route when that route is permitted by actuator and state constraints. - Test the reverse transition, the exact boundary, and positions far from the boundary.
- Trend objective value, constraint residuals, predicted orientation, first control move, and optimizer termination result.
- For multi-stage control, repeat the boundary tests across all configured parameter scenarios and check that every branch respects its bounds.
Accept the repair only when the commanded direction remains continuous through the wrap boundary, predicted orientations remain valid, constraints pass at every prediction node, and repeated solves terminate normally from both sides of the boundary.
FAQ
Why does do-mpc unwind an angle from 350 degrees to zero?
A direct scalar error evaluates the move as -350°. Use a periodic error or penalty so the objective recognizes the equivalent 10° route.
Why does changing IPOPT settings not fix angle unwinding?
IPOPT solves the nonlinear program it receives. Iteration and tolerance changes cannot teach a linear angle state that 0° and 360° are equivalent.
Why does a quaternion state need a unit-norm constraint?
A physical rotation quaternion lies on the unit sphere. Check the norm at every prediction node because valid initialization alone does not constrain the rest of the trajectory.
Why does do-mpc scenario count grow so quickly?
Multi-stage MPC creates branches for parameter scenarios, and branch count grows exponentially with the control horizon. Stop branching at a selected depth and measure scenario count and solve time.
When should I stop troubleshooting and contact official do-mpc support?
Stop when the periodic cost, state conventions, initialization, constraint residuals, and solver result all check out but the predicted move is still wrong or repeatable solver failure remains. Escalate through the official project support channel with a minimal model, do-mpc version, objective definition, initial state, reference, constraint residuals, and complete termination result.