TimescaleTuner.hpp
1 // Distributed under the MIT License.
2 // See LICENSE.txt for details.
3 
4 #pragma once
5 
6 #include <array>
7 
8 #include "DataStructures/DataVector.hpp"
9 
10 /*!
11  * \ingroup ControlSystemGroup
12  * \brief Manages control system timescales
13  *
14  * The TimescaleTuner adjusts the damping timescale, \f$\tau\f$, of the control
15  * system.\n The damping timescale is restricted to
16  * `min_timescale`\f$\le\tau\le\f$`max_timescale`
17  *
18  * The damping time is adjusted according to the following criteria:
19  *
20  * **Decrease** the timescale by a factor of `decrease_factor` if either \n
21  * - the error is too large: \f$|Q| >\f$ `decrease_timescale_threshold`
22  * OR
23  * the error is changing quickly: \f$|\dot{Q}|\tau >\f$
24  * `decrease_timescale_threshold`,\n
25  * AND \n
26  * - the error is growing: \f$\dot{Q}Q > 0\f$
27  * OR
28  * the expected change in \f$Q\f$ is less than half its current value:
29  * \f$|\dot{Q}|\tau < |Q|/2\f$
30  *
31  * **Increase** the timescale by a factor of `increase_factor` if \n
32  * - the error is sufficiently small: \f$|Q|<\f$ `increase_timescale_threshold`
33  * \n
34  * AND \n
35  * - the expected change in \f$Q\f$ is less than the difference between the
36  * current error and the threshold:
37  * \f$|\dot{Q}|\tau < \f$ (`increase_timescale_threshold` \f$-|Q|\f$)
38  */
39 
41  public:
42  TimescaleTuner(DataVector initial_timescale, double max_timescale,
43  double min_timescale, double decrease_timescale_threshold,
44  double increase_timescale_threshold, double increase_factor,
45  double decrease_factor) noexcept;
46 
47  TimescaleTuner(TimescaleTuner&&) noexcept = default;
48  TimescaleTuner& operator=(TimescaleTuner&&) noexcept = default;
49  TimescaleTuner(const TimescaleTuner&) = delete;
50  TimescaleTuner& operator=(const TimescaleTuner&) = delete;
51  ~TimescaleTuner() = default;
52 
53  /// returns the current timescale for each component of a FunctionOfTime
54  const DataVector& current_timescale() noexcept { return timescale_; }
55  /// manually sets all timescales to a specified value, unless the value is
56  /// outside of the specified minimum and maximum timescale bounds, in which
57  /// case it is set to the nearest bounded value
58  void set_timescale_if_in_allowable_range(double suggested_timescale) noexcept;
59  /// the update function responsible for modifying the timescale based on
60  /// the control system errors
61  void update_timescale(const std::array<DataVector, 2>& q_and_dtq) noexcept;
62 
63  private:
64  DataVector timescale_;
65  double max_timescale_;
66  double min_timescale_;
67  double decrease_timescale_threshold_;
68  double increase_timescale_threshold_;
69  double increase_factor_;
70  double decrease_factor_;
71 };
void set_timescale_if_in_allowable_range(double suggested_timescale) noexcept
manually sets all timescales to a specified value, unless the value is outside of the specified minim...
Definition: TimescaleTuner.cpp:67
Stores a collection of function values.
Definition: DataVector.hpp:46
const DataVector & current_timescale() noexcept
returns the current timescale for each component of a FunctionOfTime
Definition: TimescaleTuner.hpp:54
void update_timescale(const std::array< DataVector, 2 > &q_and_dtq) noexcept
the update function responsible for modifying the timescale based on the control system errors ...
Definition: TimescaleTuner.cpp:74
Manages control system timescales.
Definition: TimescaleTuner.hpp:40