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

christophfroehlich · 2025-03-14T22:08:34Z

src/pid.cpp

+  if (gains.antiwindup_ && gains.antiwindup_strat_ == "none") {
    // Prevent i_term_ from climbing higher than permitted by i_max_/i_min_
    i_term_ = std::clamp(i_term_ + gains.i_gain_ * dt_s * p_error_,
      gains.i_min_, gains.i_max_);
-  } else {
+  } else if (!gains.antiwindup_ && gains.antiwindup_strat_ == "none") {
    i_term_ += gains.i_gain_ * dt_s * p_error_;
+    i_term_ = std::clamp(i_term_, gains.i_min_, gains.i_max_);
  }


isn't this the same?

No, with just the else clause, if gains.antiwindup_strat_ isn’t "none", it will fall through to the i_term_ equation. However, in my approach, i_term_ should be zero during the first iteration, and then obtain a value after the output is calculated (due to the anti-causal nature of anti-windup techniques, which require both the saturated and unsaturated cmd values to compute i_term_), effectively influencing the cmd on the next iteration.

but isn't the content of if and else branch the same code in the end? And could just be simplified to if (gains.antiwindup_strat_ == "none")

I see now, you are right. It is interesting that this code passes the unit tests for the old anti-windup behavior, even though we can simplify the two old conditions into just one.

However, I'm now considering the readability of the code. If I use only 'gains.antiwindup_strat_ == "none"' as the condition in this if statement, we would visually suppress the anti-windup variable/parameter, and people might not understand where this variable is being used, since it exists and is referenced throughout the code. At the same time, it's odd to have such redundancy in the ros2_control code.

I'd rather keep it this way until I remove the feature, so the variable remains visible. What do you think? I could remove the entire old behavior and address this issue in this PR or the next one.

as you implemented it here, this is different from the current behavior?
on the master branch: if antiwindup is false, then the i_term will windup and only the integral action for cmd_ will be clamped. This is a total different dynamic behavior. Only if antiwindup is true, then also i_term will be limited.
To keep the current behavior, here only
if (gains.antiwindup_ && gains.antiwindup_strat_ == "none")
is necessary?

as I implemented it here, is the same as the current behavior. All tests for this anti-windup feature have been passed (70 tests, all of them passed), so I believe that I don't change anything about it. I tried what you said, to simplify to just one condition, removing the else condition and all tests also have been passed:

// Calculate integral contribution to command if (gains.antiwindup_strat_ == "none") { // Prevent i_term_ from climbing higher than permitted by i_max_/i_min_ i_term_ = std::clamp(i_term_ + gains.i_gain_ * dt_s * p_error_, gains.i_min_, gains.i_max_); }

For now I guess is worth questioning that if the current tests for this feature really are enough to show any difference. Besides this, even I can simplify, if I do this, I would suppress the anti-windup variable/parameter from the function, and people may not understand why this variable exists. What do you think?

I don't think that the current tests are good enough here (as you have proven). But I suggested
if (gains.antiwindup_ && gains.antiwindup_strat_ == "none")
where I think that this has the same behavior than the current rolling version.

Nice! I see where I should make edits to maintain the same behavior as the rolling branch. I'll commit these changes tomorrow morning.

I didn't want to create i_error_ again, so I decided to put cmd_ on a conditional.

Hi @christophfroehlich, I've pushed some updates to the PR. When you have a moment, could you please take another look and continue the review? Thanks a lot for your time and help.

christophfroehlich · 2025-03-14T22:13:20Z

control_toolbox.rolling.repos

@@ -1,7 +1,7 @@
 repositories:
  control_msgs:
    type: git
-    url: https://github.com/ros-controls/control_msgs.git
+    url: https://github.com/ViktorCVS/control_msgs.git


Suggested change

url: https://github.com/ViktorCVS/control_msgs.git

url: https://github.com/ros-controls/control_msgs.git

I added this just to run the CI successfully in the meantime

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

Codecov Report

Attention: Patch coverage is 89.06250% with 35 lines in your changes missing coverage. Please review.

Project coverage is 77.96%. Comparing base (6c9a959) to head (5b076ea).

Files with missing lines	Patch %	Lines
src/pid_ros.cpp	70.58%	11 Missing and 9 partials ⚠️
src/pid.cpp	65.90%	9 Missing and 6 partials ⚠️

Additional details and impacted files

@@               Coverage Diff               @@
##           ros2-master     #298      +/-   ##
===============================================
+ Coverage        75.58%   77.96%   +2.37%     
===============================================
  Files               24       24              
  Lines             1155     1443     +288     
  Branches            86      100      +14     
===============================================
+ Hits               873     1125     +252     
- Misses             236      258      +22     
- Partials            46       60      +14

Flag	Coverage Δ
unittests	`77.96% <89.06%> (+2.37%)`	⬆️

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

Files with missing lines	Coverage Δ
include/control_toolbox/pid.hpp	`86.66% <100.00%> (+8.88%)`	⬆️
include/control_toolbox/pid_ros.hpp	`100.00% <ø> (ø)`
test/pid_ros_parameters_tests.cpp	`100.00% <100.00%> (ø)`
test/pid_ros_publisher_tests.cpp	`95.23% <100.00%> (ø)`
test/pid_tests.cpp	`100.00% <100.00%> (ø)`
src/pid.cpp	`82.30% <65.90%> (-12.64%)`	⬇️
src/pid_ros.cpp	`69.19% <70.58%> (-1.52%)`	⬇️

🚀 New features to boost your workflow:

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

This commit adds three new anti-windup techniques: back-calculation, the conditioning technique, and conditional integration. New parameters have been introduced and additional overloads have been implemented to ensure compatibility.

Add 3 unit tests for saturation feature.

Pulled upstream changes and merged my previous modifications.

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

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

This commit removes references to the fields that were deleted from the PidState.msg in the publish function, ensuring consistency between the message definition and its usage.

Remove references to the fields that were deleted from the PidState.msg in the publish function, ensuring consistency between the message definition and its usage.

This was referenced Mar 11, 2025

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

Draft

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

Open

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

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 added 8 commits March 31, 2025 13:27

Add three new anti-windup techniques

6fe1daa

This commit adds three new anti-windup techniques: back-calculation, the conditioning technique, and conditional integration. New parameters have been introduced and additional overloads have been implemented to ensure compatibility.

Add unit tests

8b03fdb

Add 3 unit tests for saturation feature.

Merge upstream and add local modifications

274eed8

Pulled upstream changes and merged my previous modifications.

Add unit tests

083c11f

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

Adjust unit tests for new parameters

a3db0aa

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

Removed access to deleted PidState fields in pub

6a61e19

This commit removes references to the fields that were deleted from the PidState.msg in the publish function, ensuring consistency between the message definition and its usage.

Modify cmd eq. to keep the anti-windup behavior

ba7fddb

Removed access to deleted PidState fields in pub

9021434

Remove references to the fields that were deleted from the PidState.msg in the publish function, ensuring consistency between the message definition and its usage.

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

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

christophfroehlich Mar 14, 2025

ViktorCVS Mar 14, 2025

christophfroehlich Mar 15, 2025

ViktorCVS Mar 16, 2025

christophfroehlich Mar 16, 2025

ViktorCVS Mar 17, 2025

christophfroehlich Mar 17, 2025

ViktorCVS Mar 17, 2025

ViktorCVS Mar 18, 2025

ViktorCVS Mar 31, 2025

christophfroehlich Mar 14, 2025

codecov-commenter commented Mar 14, 2025

	url: https://github.com/ViktorCVS/control_msgs.git
	url: https://github.com/ros-controls/control_msgs.git

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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov-commenter commented Mar 14, 2025

Codecov Report

ViktorCVS commented Mar 11, 2025 •

edited

Loading