1 //
2 //
3 // Copyright 2016 gRPC authors.
4 //
5 // Licensed under the Apache License, Version 2.0 (the "License");
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
8 //
9 //     http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 //
17 //
18 
19 #ifndef GRPC_SRC_CORE_LIB_TRANSPORT_PID_CONTROLLER_H
20 #define GRPC_SRC_CORE_LIB_TRANSPORT_PID_CONTROLLER_H
21 
22 #include <grpc/support/port_platform.h>
23 
24 #include <limits>
25 
26 // \file Simple PID controller.
27 // Implements a proportional-integral-derivative controller.
28 // Used when we want to iteratively control a variable to converge some other
29 // observed value to a 'set-point'.
30 // Gains can be set to adjust sensitivity to current error (p), the integral
31 // of error (i), and the derivative of error (d).
32 
33 namespace grpc_core {
34 
35 class PidController {
36  public:
37   class Args {
38    public:
gain_p()39     double gain_p() const { return gain_p_; }
gain_i()40     double gain_i() const { return gain_i_; }
gain_d()41     double gain_d() const { return gain_d_; }
initial_control_value()42     double initial_control_value() const { return initial_control_value_; }
min_control_value()43     double min_control_value() const { return min_control_value_; }
max_control_value()44     double max_control_value() const { return max_control_value_; }
integral_range()45     double integral_range() const { return integral_range_; }
46 
set_gain_p(double gain_p)47     Args& set_gain_p(double gain_p) {
48       gain_p_ = gain_p;
49       return *this;
50     }
set_gain_i(double gain_i)51     Args& set_gain_i(double gain_i) {
52       gain_i_ = gain_i;
53       return *this;
54     }
set_gain_d(double gain_d)55     Args& set_gain_d(double gain_d) {
56       gain_d_ = gain_d;
57       return *this;
58     }
set_initial_control_value(double initial_control_value)59     Args& set_initial_control_value(double initial_control_value) {
60       initial_control_value_ = initial_control_value;
61       return *this;
62     }
set_min_control_value(double min_control_value)63     Args& set_min_control_value(double min_control_value) {
64       min_control_value_ = min_control_value;
65       return *this;
66     }
set_max_control_value(double max_control_value)67     Args& set_max_control_value(double max_control_value) {
68       max_control_value_ = max_control_value;
69       return *this;
70     }
set_integral_range(double integral_range)71     Args& set_integral_range(double integral_range) {
72       integral_range_ = integral_range;
73       return *this;
74     }
75 
76    private:
77     double gain_p_ = 0.0;
78     double gain_i_ = 0.0;
79     double gain_d_ = 0.0;
80     double initial_control_value_ = 0.0;
81     double min_control_value_ = std::numeric_limits<double>::min();
82     double max_control_value_ = std::numeric_limits<double>::max();
83     double integral_range_ = std::numeric_limits<double>::max();
84   };
85 
86   explicit PidController(const Args& args);
87 
88   /// Reset the controller internal state: useful when the environment has
89   /// changed significantly
Reset()90   void Reset() {
91     last_error_ = 0.0;
92     last_dc_dt_ = 0.0;
93     error_integral_ = 0.0;
94   }
95 
96   /// Update the controller: given a current error estimate, and the time since
97   /// the last update, returns a new control value
98   double Update(double error, double dt);
99 
100   /// Returns the last control value calculated
last_control_value()101   double last_control_value() const { return last_control_value_; }
102 
103   /// Returns the current error integral (mostly for testing)
error_integral()104   double error_integral() const { return error_integral_; }
105 
106  private:
107   double last_error_ = 0.0;
108   double error_integral_ = 0.0;
109   double last_control_value_;
110   double last_dc_dt_ = 0.0;
111   const Args args_;
112 };
113 
114 }  // namespace grpc_core
115 
116 #endif  // GRPC_SRC_CORE_LIB_TRANSPORT_PID_CONTROLLER_H
117