Add three new anti-windup techniques and a Saturation feature #298

ViktorCVS · 2025-03-11T22:54:46Z

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

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. Some Aspects and Design of Anti-Windup and Conditioned Transfer.
Thesis (Master in Electrical Engineering) — University of Ljubljana, Faculty of
Electrical Engeneering, 1995.
[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.

mergify · 2025-03-12T10:55:24Z

This pull request is in conflict. Could you fix it @ViktorCVS?

ViktorCVS · 2025-03-13T18:42:06Z

@christophfroehlich, it appears that no reviewers have been assigned to this PR. Could you please help with that? If you have time, I'd appreciate it if you could also take a look at the changes.

christophfroehlich

Thx for this thorough PR, but it will need some time to properly review it

src/pid.cpp

control_toolbox.rolling.repos

codecov-commenter · 2025-03-14T22:18:13Z

Codecov Report

Attention: Patch coverage is 91.97708% with 28 lines in your changes missing coverage. Please review.

Project coverage is 79.92%. Comparing base (0936394) to head (e1b7413).

Files with missing lines	Patch %	Lines
control_toolbox/src/pid.cpp	70.83%	9 Missing and 5 partials ⚠️
control_toolbox/src/pid_ros.cpp	77.41%	12 Missing and 2 partials ⚠️

Additional details and impacted files

@@               Coverage Diff               @@
##           ros2-master     #298      +/-   ##
===============================================
+ Coverage        77.24%   79.92%   +2.68%     
===============================================
  Files               29       29              
  Lines             1336     1659     +323     
  Branches            93      100       +7     
===============================================
+ Hits              1032     1326     +294     
- Misses             252      275      +23     
- Partials            52       58       +6

Flag	Coverage Δ
unittests	`79.92% <91.97%> (+2.68%)`	⬆️

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

Files with missing lines	Coverage Δ
control_toolbox/include/control_toolbox/pid.hpp	`95.65% <100.00%> (+17.87%)`	⬆️
...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/src/pid.cpp	`82.81% <70.83%> (-8.20%)`	⬇️
control_toolbox/src/pid_ros.cpp	`73.61% <77.41%> (-0.28%)`	⬇️

🚀 New features to boost your workflow:

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

bmagyar · 2025-04-24T10:57:20Z

@ViktorCVS could you please resolve the current conflicts?

ViktorCVS · 2025-04-24T17:54:59Z

@ViktorCVS could you please resolve the current conflicts?

done

christophfroehlich

Thanks a lot for the nice work including tests etc. Please fix the pre-commit errors, and only some minor comments in the code

control_toolbox/include/control_toolbox/pid_ros.hpp

control_toolbox/src/pid_ros.cpp

control_toolbox/src/pid.cpp

christophfroehlich · 2025-04-26T10:07:19Z

control_toolbox/src/pid.cpp

+  }
+
+  if (gains.antiwindup_strat_ == "back_calculation" && gains.i_gain_ != 0) {
+    if (gains.trk_tc_ == 0.0 && gains.d_gain_ != 0.0) {


better to use something like
std::abs(val) < std::numeric_limits<double>::epsilon() instead of comparing a double to 0.0

applies to every occurrence here, you can create a helper method for that.

template<typename T> bool is_zero(T value, T tolerance = std::numeric_limits<T>::epsilon()) { return std::abs(value) <= tolerance; }

Nice! I added "inline" tag and putted it in pid.hpp. I also created a "is_not_zero(x)" to adress !=0.0 instead of use !is_zero(x). If it isn't ok, I can keep only is_zero. Adressed in commit 4c1fc9b.

Personally I prefer !is_zero, but as you like

I agree. Change it to use only is_zero() in commit 5513ff0.

christophfroehlich · 2025-04-26T10:08:09Z

control_toolbox/src/pid.cpp

+  if (gains.antiwindup_strat_ == "back_calculation" && gains.i_gain_ != 0) {
+    if (gains.trk_tc_ == 0.0 && gains.d_gain_ != 0.0) {
+      // Default value for tracking time constant for back calculation technique
+      gains.trk_tc_ = std::sqrt(gains.d_gain_/gains.i_gain_);


shouldn't this go in the set_gains method, instead of calculating this at every update step?

I agree with @christophfroehlich

Thanks! Fixed in commit 64ce2d6.

control_toolbox/test/pid_tests.cpp

christophfroehlich · 2025-04-26T12:12:31Z

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:

Please add a deprecation notice to the code, as well as a warning on std::cout if "none" is configured, for example "xxx is deprecated. This option will be removed by the ROS 2 Kilted Kaiju release."

christophfroehlich · 2025-04-26T20:32:53Z

control_toolbox/include/control_toolbox/pid.hpp

+   */
+  Pid(double p, double i, double d, double i_max, double i_min,
+    double u_max, double u_min, double trk_tc, bool saturation,
+    bool antiwindup, std::string antiwindup_strat);


thinking once again, maybe we shouldn't use std::string here in the base class, but an enum instead?
the pid_ros can have the string parameter, and maybe do the conversion manually there, or use a pattern like here.

I had some problems on this, but change it in commit e89ac18

control_toolbox/include/control_toolbox/pid.hpp

saikishor · 2025-04-26T21:36:36Z

control_toolbox/src/pid.cpp

+  if (gains.antiwindup_strat_ == "back_calculation" && gains.i_gain_ != 0) {
+    if (gains.trk_tc_ == 0.0 && gains.d_gain_ != 0.0) {
+      // Default value for tracking time constant for back calculation technique
+      gains.trk_tc_ = std::sqrt(gains.d_gain_/gains.i_gain_);


I agree with @christophfroehlich

control_toolbox/include/control_toolbox/pid_ros.hpp

christophfroehlich

For the future: Please don't force push to PRs because it makes it harder for reviewers to check the changes since the last review ;) The history does not have to be linear, because we squash that anyways.

We get closer to the finish line, but some of our comments haven't been addressed yet.

control_toolbox/include/control_toolbox/pid.hpp

control_toolbox/src/pid_ros.cpp

christophfroehlich · 2025-04-28T19:30:07Z

control_toolbox/src/pid.cpp

+  }
+
+  if (gains.antiwindup_strat_ == "back_calculation" && gains.i_gain_ != 0) {
+    if (gains.trk_tc_ == 0.0 && gains.d_gain_ != 0.0) {


Personally I prefer !is_zero, but as you like

control_toolbox/include/control_toolbox/pid.hpp

control_toolbox/include/control_toolbox/pid_ros.hpp

christophfroehlich

The tests are failing now, can you have a look please?

christophfroehlich · 2025-04-30T20:10:50Z

control_toolbox/include/control_toolbox/pid.hpp

+    }
+    else
+    {
+      // Qualquer valor desconhecido agora cai em NONE


Suggested change

// Qualquer valor desconhecido agora cai em NONE

not everyone will understand Portuguese ;)

Oh, this enum caused a lot of trouble, so I added some comments and forgot to delete them. It’s fixed now—I had to reset everything (and force-push), and I’ll try again now.

Commit e89ac18 addresses this.

christophfroehlich · 2025-04-30T20:16:52Z

control_toolbox/include/control_toolbox/pid.hpp

+  };
+
+  constexpr AntiwindupStrategy() : value_(NONE) {}
+  explicit constexpr AntiwindupStrategy(Value v) : value_(v) {}


Suggested change

explicit constexpr AntiwindupStrategy(Value v) : value_(v) {}

constexpr AntiwindupStrategy(Value v) : value_(v) {} // NOLINT(runtime/explicit)

And then the constructor can be omitted and this just works

Pid pid( 0.0, 1.0, 0.0, 0.0, 0.0, 5.0, -5.0, 1.0, true, false, AntiwindupStrategy::BACK_CALCULATION);

What do you think? This can be simplified in the tests then

That helped a lot. I was unsure whether I could use NOLINT—thanks! Commit e89ac18 addresses this.

Colcon tests are ok now

Add 3 unit tests for saturation feature.

Add 7 unit tests for saturation and anti-windup feature.

Add new parameters to the existing unit tests in the package.

The i_bounds and u_bounds conditions were combined using an 'or' operator. I have updated them to use separate if else statements.

Delete comments related to dynamic reconfigure and ROS, and update several other comments.

The i_bounds and u_bounds conditions were combined using an 'or' operator. I have updated them to use separate if else statements.

This commit adds a helper function for comparing values to zero, improving the readability of the code.

Refactor antiwindup strategy variable implementation replacing string usage with a dedicated enum improve type safety.

This was referenced Mar 11, 2025

Add new members for PID controller parameters ros-controls/ros2_controllers#1585

Draft

Remove members to pid state message ros-controls/control_msgs#178

Merged

ViktorCVS changed the title ~~Add three new anti-windup techniques~~ Add three new anti-windup techniques and a Saturation feature Mar 12, 2025

ViktorCVS mentioned this pull request Mar 12, 2025

Understanding the Anti-Windup Action #276

Open

ViktorCVS force-pushed the ros2-master branch 2 times, most recently from d0feb10 to bd7c8f0 Compare March 13, 2025 16:56

ViktorCVS marked this pull request as ready for review March 13, 2025 18:06

ViktorCVS force-pushed the ros2-master branch from 812dab4 to 8931acc Compare March 14, 2025 10:25

christophfroehlich reviewed Mar 14, 2025

View reviewed changes

src/pid.cpp Outdated Show resolved Hide resolved

control_toolbox.rolling.repos Outdated Show resolved Hide resolved

ViktorCVS force-pushed the ros2-master branch from 5b076ea to 2e9e320 Compare March 17, 2025 11:14

ViktorCVS requested a review from christophfroehlich March 20, 2025 12:30

ViktorCVS force-pushed the ros2-master branch from c359b23 to 9021434 Compare March 31, 2025 13:27

ViktorCVS force-pushed the ros2-master branch from 9021434 to 1a3a441 Compare April 24, 2025 17:52

ViktorCVS force-pushed the ros2-master branch from 1a3a441 to fc07bd3 Compare April 25, 2025 18:22

christophfroehlich requested changes Apr 26, 2025

View reviewed changes

christophfroehlich reviewed Apr 26, 2025

View reviewed changes

saikishor reviewed Apr 26, 2025

View reviewed changes

ViktorCVS force-pushed the ros2-master branch from fc07bd3 to 71baea5 Compare April 28, 2025 10:13

christophfroehlich linked an issue Apr 28, 2025 that may be closed by this pull request

Understanding the Anti-Windup Action #276

Open

christophfroehlich requested changes Apr 28, 2025

View reviewed changes

ViktorCVS force-pushed the ros2-master branch from 51b3d0e to 5513ff0 Compare April 29, 2025 12:45

christophfroehlich requested changes Apr 30, 2025

View reviewed changes

ViktorCVS force-pushed the ros2-master branch 2 times, most recently from 5513ff0 to 55f3505 Compare May 5, 2025 10:49

ViktorCVS added 27 commits May 5, 2025 16:43

Add unit tests

9fb4367

Add 3 unit tests for saturation feature.

Resolving conflicts

307b2cf

Add unit tests

c8c7c69

Add 7 unit tests for saturation and anti-windup feature.

Adjust unit tests for new parameters

a374520

Add new parameters to the existing unit tests in the package.

Modify cmd eq. to keep the anti-windup behavior

eab8116

Fix license comments

3d42b91

Separate i_bounds and u_bounds conditions

1fa121d

The i_bounds and u_bounds conditions were combined using an 'or' operator. I have updated them to use separate if else statements.

Fix code style: use consistent brace styles

2850d8c

Remove and update comments

ad95a6b

Delete comments related to dynamic reconfigure and ROS, and update several other comments.

Separate i_bounds and u_bounds conditions

0bd47d8

The i_bounds and u_bounds conditions were combined using an 'or' operator. I have updated them to use separate if else statements.

Move comment closer to corresponding equation

fc218fa

Add helper function for zero comparisons

1a223eb

This commit adds a helper function for comparing values to zero, improving the readability of the code.

Discard unused comments and fix comment formatting

8fc04be

Explicitly initialize variables to 0 in header

7278323

Remove deprecated comment

d8e07d2

add Doxygen trailing comments to Gains members

18f8d1d

add Doxygen trailing comments to Gains members

9c74099

Add comment for gains_buffer_ in pid.hpp

b43e8ea

Add comment for gains_buffer_ in pid.hpp

b459b70

Add comment for gains_buffer_ in pid.hpp

d76cb74

Add comment for gains_buffer_ in pid.hpp

ebdae95

Add default value for trk_tc

0aa356a

remove is_not_zero() function

f7b8ad4

Refactor PID antiwindup strategy variable

47f2f6e

Refactor antiwindup strategy variable implementation replacing string usage with a dedicated enum improve type safety.

Add deprecated message for the old anti-windup

9c14cb8

Add deprecated message for the old anti-windup

db75c83

Calculate tracking time constant in set_gains

3058121

ViktorCVS force-pushed the ros2-master branch from 64ce2d6 to 3058121 Compare May 5, 2025 16:44

ViktorCVS requested review from saikishor and christophfroehlich May 5, 2025 16:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add three new anti-windup techniques and a Saturation feature #298

Add three new anti-windup techniques and a Saturation feature #298

ViktorCVS commented Mar 11, 2025 •

edited

Loading

mergify bot commented Mar 12, 2025

ViktorCVS commented Mar 13, 2025

christophfroehlich left a comment

codecov-commenter commented Mar 14, 2025 •

edited

Loading

bmagyar commented Apr 24, 2025

ViktorCVS commented Apr 24, 2025

christophfroehlich left a comment •

edited

Loading

christophfroehlich Apr 26, 2025

ViktorCVS Apr 28, 2025

christophfroehlich Apr 28, 2025

ViktorCVS Apr 29, 2025

christophfroehlich Apr 26, 2025

saikishor Apr 26, 2025

ViktorCVS May 5, 2025

christophfroehlich commented Apr 26, 2025 •

edited

Loading

christophfroehlich Apr 26, 2025

ViktorCVS Apr 29, 2025 •

edited

Loading

saikishor Apr 26, 2025

christophfroehlich left a comment

christophfroehlich Apr 28, 2025

christophfroehlich left a comment

christophfroehlich Apr 30, 2025

ViktorCVS May 5, 2025

ViktorCVS May 5, 2025

christophfroehlich Apr 30, 2025

ViktorCVS May 5, 2025

ViktorCVS May 5, 2025

	explicit constexpr AntiwindupStrategy(Value v) : value_(v) {}
	constexpr AntiwindupStrategy(Value v) : value_(v) {} // NOLINT(runtime/explicit)

Add three new anti-windup techniques and a Saturation feature #298

Are you sure you want to change the base?

Add three new anti-windup techniques and a Saturation feature #298

Conversation

ViktorCVS commented Mar 11, 2025 • edited Loading

Overview

What was added/changed in this PR

About compatibility

About the older anti-windup technique

About unit tests

Related PR's

Important notes

Graphs

Final notes

References

mergify bot commented Mar 12, 2025

ViktorCVS commented Mar 13, 2025

christophfroehlich left a comment

Choose a reason for hiding this comment

codecov-commenter commented Mar 14, 2025 • edited Loading

Codecov Report

bmagyar commented Apr 24, 2025

ViktorCVS commented Apr 24, 2025

christophfroehlich left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

christophfroehlich commented Apr 26, 2025 • edited Loading

Choose a reason for hiding this comment

ViktorCVS Apr 29, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

christophfroehlich left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

christophfroehlich left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ViktorCVS commented Mar 11, 2025 •

edited

Loading

codecov-commenter commented Mar 14, 2025 •

edited

Loading

christophfroehlich left a comment •

edited

Loading

christophfroehlich commented Apr 26, 2025 •

edited

Loading

ViktorCVS Apr 29, 2025 •

edited

Loading