Improvements to pid & ltisys. Updated docs. bump to 1.3.9

Author: camilo

doc/qltisys.dox

@@ -176,4 +176,136 @@
 *      }
 *  }
 *  @endcode
+*
+* @section qltisys_transportdelay Transport-Delay
+*
+* The  qlibs::transportDelay class models a "pure time delay" in a discrete-time
+* system.
+* It holds incoming samples in a buffer and outputs a sample from the past after
+* a fixed number of discrete steps.
+*
+* Mathematically, a transport delay can be expressed as:
+* <center>
+* \f$ y[k] = x[k - N] \f$
+* </center>
+*
+* where:
+* - \f$ y[k] \f$ is the current output sample,
+* - \f$ x[k] \f$ is the current input sample,
+* - \f$ N \f$ is the number of discrete delay steps (@a numberOfDelays).
+*
+* This is useful for:
+* - Simulating signal propagation delays.
+* - Implementing dead-time elements in control systems.
+* - Testing systems where data arrival is intentionally delayed.
+*
+* The delay amount is determined in discrete steps, not directly in seconds.
+* To convert a time delay in seconds to discrete steps, you can use:
+* - The  qlibs::delayFromTime() helper function, or
+* - The qlibs::timeDelay literal facility @c _td .
+*
+* In simulation or discrete-time signal processing, a pure delay shifts the
+* input signal in time without altering its shape or magnitude.
+* In continuous-time systems, a pure time delay is represented by:
+*
+* <center>
+* \f$ G(s) = e^{-sT_d} \f$
+* </center>
+*
+* where \f$ T_d \f$ is the delay time.
+* When discretized for simulation (with a time step \f$ \Delta t \f$), the delay
+* becomes a **FIFO buffer** of length:
+*
+* <center>
+* \f$ N = \frac{T_d}{\Delta t} \f$
+* </center>
+*
+* The qlibs::transportDelay class implements this buffer with:
+* - @b Insertion of the newest sample at each step.
+* - @b Extraction of the oldest stored sample as the delayed output.
+*
+* This is especially important in control system simulations where transport
+* delays affect stability and performance.
+*
+* @subsection td_basic Basic Example
+*
+* @code{.c}
+* #include <qlibs.h>
+*
+* using namespace qlibs;
+*
+* constexpr real_t dt = 0.1_re; // 100 ms simulation step
+* transportDelay<3> myDelay;    // Delay by 3 discrete steps (0.3 seconds)
+*
+* void simulate() {
+*     real_t inputSignal = 1.0_re;
+*     real_t outputSignal = myDelay.delay(inputSignal);
+*     // outputSignal contains the value of inputSignal from 0.3 seconds ago
+* }
+* @endcode
+*
+* @subsection td_timeconv Using Time Conversion
+*
+* If you want a delay in seconds but only know the simulation step (dt),
+* use qlibs::delayFromTime() or @c _td:
+*
+* @code{.c}
+* constexpr real_t dt = 0.1_re;
+*
+* // Delay by 2.5 seconds
+* transportDelay<delayFromTime(2.5, dt)> myDelay1;
+*
+* // Using the _td literal:
+* transportDelay<2.5_td(dt)> myDelay2;
+*
+* // Using operator[] form:
+* transportDelay<4.3_td[dt]> myDelay3;
+* @endcode
+*
+* @subsection td_continuous Example: Continuous System with Delay
+*
+* This example simulates a first-order system with a pure transport delay.
+* The system is:
+*
+* <center>
+* \f$ G(s) = \frac{1}{\tau s + 1} \cdot e^{-sT_d} \f$
+* </center>
+*
+* The delay is implemented with qlibs::transportDelay after the continuous system
+* output.
+*
+* @code{.c}
+* #include <iostream>
+* #include <chrono>
+* #include <thread>
+* #include <qlibs.h>
+*
+* using namespace qlibs;
+*
+* void xTaskSystemSimulate( void )
+* {
+*     // Continuous system parameters
+*     constexpr real_t tau = 1.0_re; // Time constant
+*     constexpr real_t dt  = 0.01_re; // Simulation step
+*     constexpr real_t Td  = 0.5_re; // Transport delay in seconds
+*     std::chrono::milliseconds delay(static_cast<long long>( dt*1000 ) );
+*
+*     continuousTF<1> ctf= {
+*         { 0.0f, 1.0f, },
+*         { tau, 1.0f, },
+*     };
+*     continuousSystem gc( ctf, dt );
+*     transportDelay<delayFromTime(Td, dt)> delayBlock;
+*     real_t ut, yt;
+*
+*     for( ;; ) {
+*         ut = BSP_InputGet();
+*         yt = delayBlock( gc.excite( ut ) );
+*
+*         std::this_thread::sleep_for(delay);
+*         std::cout << "u(t) = " << ut << " y(t) = " << yt << std::endl;
+*     }
+* }
+* @endcode
+*
 */

doc/qtdl.dox

@@ -1,24 +1,23 @@
 /*! @page qtdl_desc Tapped Delay Line in O(1)
 * The class \ref qtdl is an implementation of the Tapped Delay Line (TDL) structure.
-* A TDL is a discrete element in digital filter theory, that allows a signal to 
+* A TDL is a discrete element in digital filter theory, that allows a signal to
 * be delayed by a number of samples and provides an output signal for each delay.
-* Here, a TDL is implemented as a circular buffer. This means 
+* Here, a TDL is implemented as a circular buffer. This means
 * that the complexity of the enqueue and dequeue operations is constant @c O(1), so
 * integer delays can be computed very efficiently.
 *
-* The delay by one sample is notated \f$z^{-1}\f$ and delays of \f$N\f$ samples 
-* is notated as \f$z^{-N}\f$  motivated by the role the z-transform plays in 
+* The delay by one sample is notated \f$z^{-1}\f$ and delays of \f$N\f$ samples
+* is notated as \f$z^{-N}\f$  motivated by the role the z-transform plays in
 * describing digital filter structures.
 *
 * To create a TDL, you just need to define an instance of type \ref qlibs::tdl and
 * then, configure it by using the constructor or \ref qlibs::tdl::setup(),
-* where you can define the number of lines to be delayed and the initial values 
+* where you can define the number of lines to be delayed and the initial values
 * for all of them. Then, you can start operating over this structure by inserting
 * samples of the input signal by using \ref qlibs::tdl::insertSample().
 * You can also get any specific delay from it by using:
 *
 * - \ref qlibs::tdl::getOldest(), to get the oldest delay at tap \f$z^{-N}\f$
-* You can also use the index at @c -1 as follows: @c "delay[ -1 ]"
 * - \ref qlibs::tdl::getAtIndex(), to get the delay at tap \f$z^{-i}\f$.
 * You can also use the index using an unsigned value as follows: @c "delay[ i ]"
 * - Index operator
@@ -27,7 +26,7 @@
 * base component of some aspects of \ref qlibs::smoother and \ref qlibs::ltisys.
 *
 * @section qtdl_ex1 Example : Code snippet to instantiate a TDL to hold up to 256 delays.
-* 
+*
 *  @code{.c}
 *  real_t storage[ 256 ] = { 0.0f };
 *  tdl delay( storage );
@@ -41,6 +40,6 @@
 *
 * @code{.c}
 *  auto d3 = delay[ 3 ]; // get delay at t-3, same as delay.getAtIndex( 3 )
-*  auto dOldest = delay[ -1 ]; // get delay at t-255 , same as delay.getOldest()
+*  auto dOldest = delay.getOldest(); // get the oldest sample at t-N
 *  @endcode
 */

library.json

@@ -16,7 +16,7 @@
       "maintainer": true
     }
   ],
-  "version": "1.3.8",
+  "version": "1.3.9",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*"

library.properties

@@ -1,5 +1,5 @@
 name=qlibs
-version=1.3.8
+version=1.3.9
 license=MIT
 author=J. Camilo Gomez C. <[email protected]>
 maintainer=J. Camilo Gomez C. <[email protected]>

src/CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required( VERSION 3.2 )
 project( qlibs-cpp
-         VERSION 1.3.8
+         VERSION 1.3.9
          DESCRIPTION "A collection of useful C++ libraries for embedded systems"
          LANGUAGES CXX )
 

src/include/ltisys.hpp

@@ -249,7 +249,7 @@ namespace qlibs {
 
             /**
             * @brief Returns the number of delay steps configured for this instance.
-            * 
+            *
             * @return The number of delays (equal to the template parameter).
             */
             size_t getNumberOfDelays() const noexcept {
@@ -802,6 +802,10 @@ namespace qlibs {
             bool setIntegrationMethod( integrationMethod m );
     };
 
+
+    using customProcessModel = real_t(*)(real_t, void*);
+
+
     /**
      * @brief A Smith Predictor implementation for compensating time delays in
      * control systems.
@@ -812,10 +816,12 @@ namespace qlibs {
      */
     class smithPredictor {
     private:
-        ltisys *model;
+        ltisys *model{nullptr};
+        customProcessModel modelAlternate{ nullptr };
         ITransportDelay *modelDelay;
         ltisys *filter{ nullptr };
         real_t yp_hat;
+        void *alternateData{ nullptr };
     public:
         virtual ~smithPredictor() {}
         /**
@@ -835,6 +841,22 @@ namespace qlibs {
                         const real_t initialCondition = 0.0_re )
                         : model(&modelTf), modelDelay(&mDelay), yp_hat(initialCondition) {}
 
+        /**
+         * @brief Constructs a Smith Predictor with a plant model, delay model,
+         * and optional initial output estimate.
+         * @param[in] modelCustom Reference to the system model representing the
+         * delay-free plant. User should define a custom function that recreates
+         * the system dynamics.
+         * @param[in] mDelay Reference to the transport delay block modeling the
+         * plant’s dead time.
+         * @param[in] initialCondition Initial value for the internal output
+         * prediction (@c yp_hat). Default is 0.0.
+         */
+        smithPredictor( customProcessModel modelCustom,
+                        ITransportDelay& mDelay,
+                        const real_t initialCondition = 0.0_re )
+                        : modelAlternate(modelCustom), modelDelay(&mDelay), yp_hat(initialCondition) {}
+
         /**
          * @brief Constructs a Smith Predictor with a plant model, delay model,
          * and optional initial output estimate.
@@ -855,6 +877,27 @@ namespace qlibs {
                         const real_t initialCondition = 0.0_re )
                         : model(&modelTf), modelDelay(&mDelay), filter(&filterTf), yp_hat(initialCondition) {}
 
+        /**
+         * @brief Constructs a Smith Predictor with a plant model, delay model,
+         * and optional initial output estimate.
+         * @param[in] modelCustom Reference to the system model representing the
+         * delay-free plant. User should define a custom function that recreates
+         * the system dynamics.
+         * @param[in] mDelay Reference to the transport delay block modeling the
+         * plant’s dead time.
+         * @param[in] filterTf Reference to the LTI system used as the robustness
+         * filter.
+         * @param[in] initialCondition Initial value for the internal output
+         * prediction (@c yp_hat). Default is 0.0.
+         *
+         * @note Both the model and delay block are passed by reference and stored internally as pointers.
+         */
+        smithPredictor( customProcessModel modelCustom,
+                        ITransportDelay& mDelay,
+                        ltisys& filterTf,
+                        const real_t initialCondition = 0.0_re )
+                        : modelAlternate(modelCustom), modelDelay(&mDelay), filter(&filterTf), yp_hat(initialCondition) {}
+
         /**
          * @brief Updates the internal prediction based on control input and
          * measured plant output.
@@ -895,8 +938,27 @@ namespace qlibs {
          * and does not affect the plant or delay block directly.
          */
         bool setFilter( ltisys& filterTf ) noexcept {
-            filter = &filterTf;
-            return true;
+            bool retValue = filter != &filterTf;
+            if ( retValue ) {
+                filter = &filterTf;
+            }
+            return retValue;
+        }
+
+        /**
+         * @brief Sets the model data when alternate when a custom delay-free
+         * plant model is used
+         *
+         * @param[in] data The data passed to the user-defined model at the moment
+         * of evaluation
+         * @return @c true on success. False otherwise
+         */
+        bool setModelData( void* data ) noexcept {
+            bool retValue = data != alternateData;
+            if ( retValue ) {
+                alternateData = data;
+            }
+            return retValue;
         }
     };
 

src/include/pid.hpp

@@ -162,8 +162,9 @@ namespace qlibs {
     */
     class pidController : public pidGains, public nState, private nonCopyable {
         private:
-            real_t b, c, sat_Min, sat_Max, epsilon, kw, kt, D, u1, beta, uSat;
+            real_t b, c, sat_Min, sat_Max, epsilon, kw, kt, D, u1, beta, uSat, gainBlend;
             real_t dt{ 1.0_re };
+            pidGains nextGains;
             real_t m, mInput;
             const real_t *yr{ nullptr };
             real_t alpha, gamma; /*MRAC additive controller parameters*/
@@ -419,11 +420,13 @@ namespace qlibs {
             * @param[in] Mu Algorithm momentum. [ 0 <= Mu <= 1 ].
             * @param[in] Alpha Final controller speed adjustment. [ 0 < Alpha <= 1 ].
             * @param[in] lambda Algorithm forgetting factor [ 0.8 <= lambda <= 1 ].
+            * @param[in] Tb Gains blend-time[  Tb > 0  ].
             * @return @c true on success, @c false on failure.
             */
             bool setAutoTuningParameters( const real_t Mu,
                                           const real_t Alpha,
-                                          const real_t lambda ) noexcept;
+                                          const real_t lambda,
+                                          const real_t Tb = 3.0_re ) noexcept;
 
             /**
             * @brief Select the PID type to tune.

src/ltisys.cpp

@@ -280,11 +280,26 @@ bool continuousSystem::setIntegrationMethod( integrationMethod m )
 bool smithPredictor::updatePrediction( const real_t ut,
                                        const real_t yt ) noexcept
 {
-    const real_t yt_hat_d = model->excite( ut );
-    const real_t yt_hat = modelDelay->delay( yt_hat_d );
-    const real_t ep_hat = yt - yt_hat;
+    bool retValue = true;
+    real_t yt_hat_d = 0.0_re;
 
-    yp_hat = yt_hat_d + ( ( nullptr != filter ) ? filter->excite( ep_hat ) : ep_hat );
-    return true;
+    if ( nullptr != model ) {
+        yt_hat_d = model->excite( ut );
+    }
+    else if ( nullptr != modelAlternate ) {
+        yt_hat_d = modelAlternate( ut, alternateData );
+    }
+    else {
+        retValue = false;
+    }
+
+    if ( retValue ) {
+        const real_t yt_hat = modelDelay->delay( yt_hat_d );
+        const real_t ep_hat = yt - yt_hat;
+
+        yp_hat = yt_hat_d + ( ( nullptr != filter ) ? filter->excite( ep_hat )
+                                                    : ep_hat );
+    }
+    return retValue;
 }
 /*============================================================================*/