Update anti-windup techniques (backport #298)

[mergify]

Overview

This PR adds three new anti-windup techniques: back‑calculation, the conditioning technique, and conditional integration. It also adds a saturation feature for the PID output. New parameters have been introduced, and additional overloads have been implemented to ensure compatibility.

What was added/changed in this PR

• Added three new anti-windup techniques
  • back-calculation
  • conditioning technique
  • conditional integration
• Added saturation feature to PID output

About compatibility

The packages compile correctly and have passed the pre‑commit and colcon tests (packages with dependencies continue to show the same number of failures before and after my modifications). If the new parameters are not used, the package retains its old behavior.

About the older anti-windup technique

My plan, either by the end of this PR or in a subsequent one, is to completely remove the older anti‑windup technique that has been used so far. This method, which is a form of conditional integration, has several disadvantages:

• If set incorrectly, it may cause a steady‑state error.
• If set incorrectly, it may not affect the system at all.
• Even if it is set between the steady‑state error limit and the value beyond which it has no effect, it is still difficult to find a configuration that improves the system as effectively as the other techniques.

Additionally, regardless of whether the 'antiwindup' parameter is set to true or false, the anti-windup technique is applied (using the same method with a different approach), so the user does not have the option to disable it.

About unit tests

I've added 10 new unit tests for the new features and updated the existing ones to accommodate the new parameters.

Related PR's

• Add new members for PID controller parameters ros2_controllers#1585
• Remove members to pid state message control_msgs#178

Important notes

These three techniques are common anti‑windup strategies used to mitigate the windup effect and are widely employed in control applications: back‑calculation [1], the conditioning technique [1,2], and conditional integration [1,3].

The default values for the tracking time constant are defined in [3,4] for back‑calculation and in [1] for the conditioning technique.

Both back‑calculation and the conditioning technique use forward Euler discretization; this may change before merging this PR.

Graphs

I tested it on ros2_control_demos to better illustrate this feature and test it on simulation to valide the equations. The tests were conducted using a modified version of Example 1: RRBot, which uses a PID controller instead of the default forward position controller. It was tested on Docker, Ubuntu Noble, and Jazzy.

PID values: p = 4.0, i = 25.0, d = 0.5; u_max = 13, u_min = -13; and the tracking time constant was left at its default value.

The standard response with a settling time (ts) of 5.2 seconds, the response affected by saturation, resulting in a settling time (ts_sat) of 8.6 seconds (+65.4% increase) and the response using the back-calculation technique, which improves performance with a settling time (ts_back) of 4.1 seconds (–21.2% decrease), even lower than the standard response.

Those figures compares three anti-windup methods applied to the step response, a zoomed-in view of the step response is provided here to clearly distinguish between the three anti-windup strategies. They are all very similar due to the system and PID values, but they may vary significantly between applications.

The standard control output, the control output affected by saturation, with a recovery time from saturation of 6.8s and the control output using the back-calculation technique, with a recovery time from saturation of 2s (-70.6%).

Those figures compares three control outputs using anti-windup methods, a zoomed-in view of the control output is provided here to clearly distinguish between the three anti-windup strategies. They are all very similar due to the system and PID values, but they may vary significantly between applications.

All the equations have been validated with these simulations, providing a feature with three techniques to address windup.

Final notes

I'm very open to any recommendations to improve this code.

References

[1] VISIOLI, A. Pratical PID Control. London: Springer-Verlag London Limited, 2006. 476 p.
[2] VRANCIC, D et al. Antiwindup, Bumpless, and Conditioned Transfer Techniques for PID Controllers. IEEE Control Systems Magazine, 1996. 16(4):48 - 57.
[3] BOHN, C.; ATHERTON, D. An analysis package comparing pid anti-windup strategies.
IEEE Control Systems Magazine, p. 34–40, 1995.
[4] ASTRöM, K.; HäGGLUND, T. PID Controllers: Theory, Design and Tuning. ISA Press.
Research Triangle Park, USA: Springer-Verlag London Limited, 1995. 343 p.

---

This is an automatic backport of pull request #298 done by [Mergify](https://mergify.com).

[mergify]

Cherry-pick of f652c3d has failed:

On branch mergify/bp/jazzy/pr-298
Your branch is up to date with 'origin/jazzy'.

You are currently cherry-picking commit f652c3d.
  (fix conflicts and run "git cherry-pick --continue")
  (use "git cherry-pick --skip" to skip this patch)
  (use "git cherry-pick --abort" to cancel the cherry-pick operation)

Changes to be committed:
	modified:   control_toolbox/test/pid_ros_parameters_tests.cpp
	modified:   control_toolbox/test/pid_ros_publisher_tests.cpp

Unmerged paths:
  (use "git add/rm <file>..." as appropriate to mark resolution)
	both modified:   control_toolbox/include/control_toolbox/pid.hpp
	both modified:   control_toolbox/include/control_toolbox/pid_ros.hpp
	both modified:   control_toolbox/src/pid.cpp
	both modified:   control_toolbox/src/pid_ros.cpp
	both modified:   control_toolbox/test/pid_tests.cpp
	deleted by us:   doc/release_notes.rst

To fix up this pull request, you can check it out locally. See documentation: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally

[mergify]

This pull request is in conflict. Could you fix it @bmagyar @destogl @christophfroehlich @saikishor?

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 77.88945% with 88 lines in your changes missing coverage. Please review.

Project coverage is 74.95%. Comparing base (f9881af) to head (b15d94f).

Files with missing lines	Patch %	Lines
control_toolbox/src/pid_ros.cpp	55.76%	41 Missing and 5 partials ⚠️
control_toolbox/src/pid.cpp	57.31%	32 Missing and 3 partials ⚠️
control_toolbox/include/control_toolbox/pid.hpp	84.44%	6 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##            jazzy     #386      +/-   ##
==========================================
- Coverage   74.98%   74.95%   -0.03%     
==========================================
  Files          29       29              
  Lines        1387     1749     +362     
  Branches       85      101      +16     
==========================================
+ Hits         1040     1311     +271     
- Misses        298      380      +82     
- Partials       49       58       +9     

Flag	Coverage Δ
unittests	74.95% <77.88%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ontrol_toolbox/include/control_toolbox/pid_ros.hpp	100.00% <ø> (ø)
control_toolbox/test/pid_ros_parameters_tests.cpp	100.00% <100.00%> (ø)
control_toolbox/test/pid_ros_publisher_tests.cpp	95.00% <100.00%> (ø)
control_toolbox/test/pid_tests.cpp	100.00% <100.00%> (ø)
control_toolbox/include/control_toolbox/pid.hpp	82.35% <84.44%> (+4.57%)	⬆️
control_toolbox/src/pid.cpp	66.07% <57.31%> (-14.93%)	⬇️
control_toolbox/src/pid_ros.cpp	59.16% <55.76%> (-3.69%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.