pyadrc 0.5.0__py3-none-any.whl

pyadrc/__init__.py

@@ -0,0 +1,11 @@
+"""Top-level package for pyadrc."""
+
+__author__ = """Ongun Türkcüoglu"""
+__email__ = 'onguntoglu@gmail.com'
+__version__ = '0.5.0'
+
+from .pyadrc import StateSpace, TransferFunction, FeedbackTF, saturation
+from .models import QuadAltitude, System
+
+__all__ = ['StateSpace', 'TransferFunction', 'FeedbackTF', 'saturation',
+           'QuadAltitude', 'System', '__version__']

pyadrc/models.py

@@ -0,0 +1,180 @@
+import numpy as np
+import scipy.signal
+
+
+class QuadAltitude(object):
+    """Discrete-time model of altitude of a quadcopter
+
+    Parameters
+    ----------
+    dt : float, optional
+        Discretization time (zero-order hold), by default 0.001
+    m : float, optional
+        Mass of the quadcopter, by default 0.028
+    g : float, optional
+        Gravitational acceleration, by default 9.807
+    """
+
+    def __init__(self, dt: float = 0.001,
+                 m: float = 0.028, g: float = 9.807):
+
+        assert isinstance(g, float), 'Gravity needs to be of type float'
+        assert isinstance(m, float), 'Mass of quadcopter \
+            needs to be of type float'
+
+        self.g = g
+        self.m = m
+        self.dt = dt
+
+        self.vel = 0
+        self.pos = 0
+        self.acc = 0
+
+    def __call__(self, u: float) -> float:
+        """Input port to the quadcopter
+
+        Parameters
+        ----------
+        u : float
+            Thrust of the rotors
+
+        Returns
+        -------
+        float:
+            Current altitude of quadcopter
+
+        """
+
+        acc = u * (1/self.m) - self.g
+
+        self.vel += acc * self.dt
+        self.pos += self.vel * self.dt
+        self.acc = acc
+
+        # Include ground
+        if self.pos <= 0:
+            self.vel = 0
+            self.pos = 0
+
+        return self.pos
+
+    @property
+    def states(self):
+        """Return the state of the quadcopter
+        """
+
+        return self.pos, self.vel, self.acc
+
+    @states.setter
+    def states(self, value):
+        """Sets the state of the quadcopter to value
+        value = (pos, vel, acc). If a state is None, it is not changed.
+
+        Parameters
+        ----------
+        value : tuple
+            new state vector of quadcopter
+        """
+
+        self.pos = value[0] if isinstance(value[0], (float, int)) else self.pos
+        self.vel = value[1] if isinstance(value[1], (float, int)) else self.vel
+        self.acc = value[2] if isinstance(value[2], (float, int)) else self.acc
+
+    def reset(self):
+        """Reset position and velocity to zero
+        """
+
+        self.pos = 0.
+        self.vel = 0.
+
+
+class System(object):
+
+    """Python class to generate a first-or second-order process
+    for simulation and verification purposes
+
+    Parameters
+    ----------
+    K : float, optional
+        system gain, by default 1.0
+    T : float, optional
+        time constant, by default 1.0
+    D : float, optional
+        damping factor, by default None
+    delta : float, optional
+        discretization time in seconds, by default 0.001
+    """
+
+    def __init__(self, K: float = 1.0, T: float = 1.0,
+                 D: float = None, delta: float = 0.001) -> None:
+
+        assert isinstance(K, float)
+        assert isinstance(T, float)
+        assert delta > 0, "Sampling time has to be positive"
+
+        # First-order process
+        num = np.array([K]).reshape(-1)
+        den = np.array([T, 1]).reshape(-1)
+
+        if D is not None:
+            assert isinstance(D, float),\
+                "Damping factor D must be type float"
+            # Second-order process
+            den = np.array([T**2, 2 * D * T, 1]).reshape(-1)
+
+        system = scipy.signal.tf2ss(num, den)
+
+        system = scipy.signal.cont2discrete(system, delta)
+
+        self.A = system[0]
+        self.B = system[1]
+        self.C = system[2]
+
+        self.x = np.zeros((len(den) - 1, 1), dtype=np.float64)
+
+    def __call__(self, u: float) -> float:
+        """System response w.r.t. control signal u
+
+        Parameters
+        ----------
+        u : float
+            control signal u
+
+        Returns
+        -------
+        float
+            system response y
+        """
+
+        self.x = self.A.dot(self.x) + self.B.dot(u)
+
+        return (self.C @ self.x).item()
+
+
+class RandomSystem(object):
+
+    def __init__(self, states=1) -> None:
+        """Create random discrete state space system
+
+        Args:
+            states (int, optional): number of states. Defaults to 1.
+
+        Returns:
+            None: [description]
+        """
+
+        import control
+
+        system = control.drss(states=states)
+
+        self.A = np.array(system.A)
+        self.B = np.array(system.B)
+        self.C = np.array(system.C)
+        self.D = np.array(system.D)
+
+        self.x = np.zeros((states, 1), dtype=np.float64)
+
+    def __call__(self, u: float) -> float:
+
+        self.x = self.A.dot(self.x) + self.B.dot(u)
+        return (self.C @ self.x + self.D * u).item()

pyadrc/pyadrc.py

@@ -0,0 +1,949 @@
+"""Active Disturbance Rejection Control for Python
+
+It is highly recommended to check the documentation first before attempting
+to use the package. Although it is simple in nature, ADRC requires some
+basic knowledge about PID control, observers and state-feedback.
+
+"""
+
+import numpy as np
+import time
+
+from collections import deque
+
+
+def saturation(_limits: tuple, _val: float) -> float:
+    """Saturation function
+
+    Parameters
+    ----------
+    _limits : tuple
+        saturation limits (low, high)
+    _val : float
+        sat(_val)
+
+    Returns
+    -------
+    float
+        saturated signal
+    """
+
+    lo, hi = _limits
+
+    if _val is None:
+        return None
+    elif hi is not None and _val > hi:
+        return hi
+    elif lo is not None and _val < lo:
+        return lo
+
+    return _val
+
+
+class StateSpace():
+
+    """Discrete linear time-invariant state space implementation\
+    of ADRC
+
+    Parameters
+    ----------
+    order : int
+        first- or second-order ADRC
+    delta : float
+        sampling time in seconds
+    b0 : float
+        gain parameter b0
+    w_cl : float
+        desired closed-loop bandwidth [rad/s], 4 / w_cl and 6 / w_cl is the
+        corresponding settling time in seconds for first- and second-order ADRC
+        respectively
+    k_eso : float
+        relational observer bandwidth
+    inc_form : float
+        toggle incremental form of ADRC, by default False. If the incremental
+        form is toggled, the controller will return the incrementation to the
+        current control signal. This value needs to be accumulated by the user.
+        Functionally identical to the non-incremental (normal) form.
+    eso_init : tuple, optional
+        initial state for the extended state observer, by default False
+    r_lim : tuple, optional
+        rate limits for the control signal, by default (None, None)
+    m_lim : tuple, optional
+        magnitude limits for the control signal, by default (None, None)
+    half_gain : tuple, optional
+        half gain tuning for controller/observer gains,\
+        by default (False, False)
+
+    References
+    ----------
+    .. [1] G. Herbst, "Practical active disturbance rejection control:
+        Bumpless transfer, rate limitation, and incremental algorithm",
+        https://arxiv.org/abs/1908.04610
+
+    .. [2] G. Herbst, "Half-Gain Tuning for Active Disturbance Rejection
+        Control", https://arxiv.org/abs/2003.03986
+    """
+
+    def __init__(self,
+                 order: int,
+                 delta: float,
+                 b0: float,
+                 w_cl: float,
+                 k_eso: float,
+                 inc_form: bool = False,
+                 eso_init: tuple = False,
+                 r_lim: tuple = (None, None),
+                 m_lim: tuple = (None, None),
+                 half_gain: tuple = (False, False)):
+
+        assert (order == 1) or (order == 2),\
+            'Only first- and second-order ADRC is implemented'
+
+        self.b0 = b0
+        nx = order + 1
+        self.delta = delta
+
+        if order == 1:
+            self.Ad = np.vstack(([1, delta], [0, 1]))
+            self.Bd = np.vstack((b0 * delta, 0))
+            self.Cd = np.hstack((1, 0)).reshape(1, -1)
+            self.Dd = 0
+
+            # Controller parameters for closed-loop dynamics
+            t_settle = 4 / w_cl
+            sCL = -4 / t_settle
+            self.Kp = -sCL
+
+            # Observer dynamics
+            sESO = k_eso * sCL
+            zESO = np.exp(sESO * delta)
+
+            # Observer gains resulting in common-location observer poles
+            self.L = np.array([1 - (zESO)**2,
+                               (1 / delta) * (1 - zESO)**2]).reshape(-1, 1)
+
+            # Controller gains
+            self.w = np.array([self.Kp / self.b0,
+                               1 / self.b0]).reshape(-1, 1)
+
+        elif order == 2:
+            self.Ad = np.vstack((
+                [1, delta, (delta**2) / 2],
+                [0, 1, delta],
+                [0, 0, 1]))
+            self.Bd = np.vstack((b0 * (delta**2) / 2, b0 * delta, 0))
+            self.Cd = np.hstack((1, 0, 0)).reshape(1, -1)
+            self.Dd = 0
+
+            # Controller parameters for closed-loop dynamics
+            t_settle = 6 / w_cl
+            sCL = -6 / t_settle
+            self.Kp = sCL**2
+            self.Kd = -2 * sCL
+
+            # Observer dynamics
+            sESO = k_eso * sCL
+            zESO = np.exp(sESO * delta)
+
+            # Observer gains resulting in common-location observer poles
+            self.L = np.array([1 - (zESO)**3,
+                               (3 / (2 * delta)) * (1 - zESO)**2 * (1 + zESO),
+                               (1 / delta**2) * (1 - zESO)**3]
+                              ).reshape(-1, 1)
+
+            # Controller gains
+            self.w = np.array([self.Kp / self.b0,
+                               self.Kd / self.b0,
+                               1 / self.b0]).reshape(-1, 1)
+
+        self.xhat = np.zeros((nx, 1), dtype=np.float64)
+
+        self.ukm1 = 0.
+
+        self.m_lim = m_lim
+        self.r_lim = r_lim
+
+        if half_gain[0] is True:
+            self.w = self.w / 2
+        if half_gain[1] is True:
+            self.L = self.L / 2
+
+        if eso_init is not False:
+            assert len(eso_init) == nx,\
+                'Length of initial state vector of LESO not compatible\
+                    with order'
+            self.xhat = np.fromiter(eso_init, np.float64).reshape(-1, 1)
+
+        self._last_time = None
+        self._last_output = None
+        self._last_input = None
+        self.inc_form = inc_form
+
+        self._linear_extended_state_observer()
+
+    def _linear_extended_state_observer(self):
+        """Internal function implementing the one-step update
+        equation for the linear extended state observer
+        """
+
+        self.oA = self.Ad - self.L @ self.Cd @ self.Ad
+        self.oB = self.Bd - self.L @ self.Cd @ self.Bd
+        self.oC = self.Cd
+
+        if self.inc_form is True:
+            self.oA = self.oA - np.eye(self.oA.shape[0])
+            self.rkm1 = 0.
+
+    def _update_eso(self, y: float, ukm1: float):
+        """Update the linear extended state observer
+
+        Parameters
+        ----------
+        y : float
+            Current measurement y[k]
+        ukm1 : float
+            Previous control signal u[k-1]
+        """
+        if self.inc_form is False:
+            self.xhat = self.oA.dot(self.xhat) + self.oB.dot(
+                ukm1).reshape(-1, 1) + self.L.dot(y)
+        else:  # self.inc_form is True
+            self.xhat_delta = self.oA.dot(self.xhat) + self.oB.dot(
+                ukm1).reshape(-1, 1) + self.L.dot(y)
+
+            self.xhat = self.xhat + self.xhat_delta
+
+    def _limiter(self, u_control: float) -> float:
+        """Implements rate and magnitude limiter
+
+        Parameters
+        ----------
+        u_control : float
+            control signal to be limited
+
+        Returns
+        -------
+        float
+            float: rate and magnitude limited control signal
+        """
+
+        # Limiting the rate of u (delta_u)
+        delta_u = saturation((self.r_lim[0], self.r_lim[1]),
+                             u_control - self.ukm1)
+
+        # Limiting the magnitude of u
+        self.ukm1 = saturation((self.m_lim[0],
+                                self.m_lim[1]),
+                               delta_u + self.ukm1)
+
+        return self.ukm1
+
+    @property
+    def eso_states(self) -> tuple:
+        """Returns the states of the linear extended state observer
+
+        Returns
+        -------
+        tuple
+            States of the linear extended state observer
+        """
+
+        return self.xhat
+
+    @property
+    def limiter(self) -> tuple:
+        """Returns the value of both limiters of the controller
+
+        Returns
+        -------
+        tuple of tuples
+            Returns (magnitude_limits, rate_limits)
+        """
+
+        return self.m_lim, self.r_lim
+
+    @limiter.setter
+    def limiter(self, lim_tuple: tuple) -> None:
+        """Setter for magnitude and rate limiter
+
+        Parameters
+        ----------
+            lim_tuple : tuple of tuples
+                New magnitude limits
+        """
+
+        assert len(lim_tuple) == 2
+        assert len(lim_tuple[0]) == 2 and len(lim_tuple[1]) == 2
+        # assert lim[0] < lim[1]
+        self.m_lim = lim_tuple[0]
+        self.r_lim = lim_tuple[1]
+
+    def __call__(self, y: float, u: float, r: float, zoh: bool = False):
+        """Returns value of the control signal depending on current
+        measurements, previous control action, reference signal.
+
+        Parameters
+        ----------
+        y : float
+            Current measurement y[k] of the process
+        u : float
+            Previous control signal u[k-1]
+        r : float
+            Current reference signal r[k]
+        zoh : bool, optional
+            Only update every delta seconds, by default False
+
+        Returns
+        -------
+        float
+            Current control signal u[k]
+        """
+
+        now = time.monotonic()
+
+        if zoh is True:
+            try:
+                dt = now - self._last_time if now - self._last_time else 1e-16
+            except TypeError:
+                dt = 1e-16
+
+        if zoh is True and dt < self.delta and self._last_output is not None:
+            # Return last output of the controller if dt < delta
+            return self._last_output
+
+        self._update_eso(y, u)
+
+        if self.inc_form is False:
+            u = (self.Kp / self.b0) * r - (self.w.T @ self.xhat).item()
+            u = self._limiter(u)
+        else:  # self.inc_form is True:
+            delta_r = r - self.rkm1
+            delta_u = ((self.Kp / self.b0) * delta_r
+                       - (self.w.T @ self.xhat_delta).item())
+            u = delta_u
+
+            self.rkm1 = r
+
+        self._last_output = float(u)
+        self._last_time = now
+        return float(u)
+
+    def reset(self, x0=None):
+        """Resets the extended state observer
+
+        Parameters
+        ----------
+        x0 : np.array, optional
+            new initial state vector for the extended state observer,
+            by default None, i.e. resets to zero
+        """
+
+        nx = len(self.xhat)
+
+        assert x0 is None or len(np.fromiter(x0, float)) == nx,\
+            "Invalid state vector"
+
+        if x0 is None:
+            self.xhat = np.zeros((nx, 1), dtype=np.float64)
+        else:
+            self.xhat = np.fromiter(x0, np.float64).reshape(-1, 1)
+
+
+class FeedbackTF(object):
+
+    """Minimal footprint ADRC implemented with transfer functions in\
+    feedback path
+
+    Parameters
+    ----------
+    order : int
+        first- or second-order ADRC
+    delta : float
+        sampling time in seconds
+    b0 : float
+        gain parameter b0
+    w_cl : float
+        desired closed-loop bandwidth [rad/s], 4 / w_cl and 6 / w_cl is the
+        corresponding settling time in seconds for first- and second-order ADRC
+        respectively
+    k_eso : float
+        relational observer bandwidth
+    x_init : tuple, optional
+        initial state for the storage variables, by default False
+    r_lim : tuple, optional
+        rate limits of the controller, by default (None, None)
+    m_lim : tuple, optional
+        magnitude limits of the controller, by default (None, None)
+
+    References
+    ----------
+    .. [3] G. Herbst, "A Minimum-Footprint Implementation
+        of Discrete-Time ADRC", https://arxiv.org/abs/2104.01943
+    """
+
+    def __init__(self,
+                 order: int,
+                 delta: float,
+                 b0: float,
+                 w_cl: float,
+                 k_eso: float,
+                 x_init: tuple = False,
+                 r_lim: tuple = (None, None),
+                 m_lim: tuple = (None, None)) -> None:
+
+        assert order == 1 or order == 2, 'First- and second-order FBTF-ADRC\
+            implemented'
+
+        self.order = order
+        self.delta = delta
+
+        zESO = np.exp(-k_eso * w_cl * delta)
+
+        if order == 1:
+            self.coeff = {'a1': -2 * zESO, 'a2': zESO**2,
+                          'b0': delta * w_cl * zESO**2 - (1 - zESO)**2,
+                          'b1': - delta * w_cl * zESO**2,
+                          'g0': (1/(b0 * delta)) * (delta * w_cl
+                                                    * (1-zESO**2)
+                                                    + (1 - zESO)**2),
+                          'g1': (1/(b0 * delta)) * (2 * delta * w_cl
+                                                    * (zESO**2 - zESO)
+                                                    - (1 - zESO)**2),
+                          'k': w_cl / b0}
+
+            self.states = {'x1': 0., 'x2': 0.}
+
+        elif order == 2:
+            _GC = 1/(b0 * delta**2)  # coefficient gamma_n constant
+            self.coeff = {'a1': -3 * zESO, 'a2': 3 * zESO**2, 'a3': -zESO**3,
+                          'b0': 0.5 * (- delta * w_cl * zESO**3
+                                       * (4 - delta * w_cl)
+                                       + delta * w_cl * (1 + zESO)**3
+                                       - (1 - zESO)**3),
+                          'b1': 0.5 * (- delta * w_cl
+                                       * (1 + zESO)**3 - (1 - zESO)**3),
+                          'b2': 0.5 * (delta * w_cl * zESO**3
+                                       * (4 - delta * w_cl)),
+                          'g0': _GC * (delta**2 * w_cl**2 * (1 - zESO**3)
+                                       + 3 * delta * w_cl
+                                       * (1 - zESO - zESO**2 + zESO**3)
+                                       + (1 - zESO)**3),
+                          'g1': _GC * (3 * delta**2 * w_cl**2
+                                       * (- zESO + zESO**3)
+                                       + 4 * delta * w_cl
+                                       * (-1 + 3 * zESO**2 - 2*zESO**3)
+                                       - 2 * (1 - zESO)**3),
+                          'g2': _GC * (3 * delta**2 * w_cl**2
+                                       * (zESO**2 - zESO**3)
+                                       + delta * w_cl
+                                       * (1 + 3 * zESO - 9*zESO**2 + 5*zESO**3)
+                                       + (1 - zESO)**3),
+                          'k': w_cl**2 / b0}
+
+            self.states = {'x1': 0., 'x2': 0., 'x3': 0.}
+
+        # Initialize limiters
+        self.ukm1 = 0.
+        self.r_lim = r_lim
+        self.m_lim = m_lim
+
+        # Zero-order hold variables
+        self._last_time = None
+        self._last_output = None
+        self._last_input = None
+
+    @property
+    def x_states(self) -> tuple:
+        """Returns the storage variables
+
+        Returns
+        -------
+        tuple
+            Storage variables
+        """
+
+        return tuple(self.states.values())
+
+    @property
+    def limiter(self) -> tuple:
+        """Returns the value of both limiters of the controller
+
+        Returns
+        -------
+        tuple of tuples
+            Returns (magnitude_limits, rate_limits)
+        """
+
+        return self.m_lim, self.r_lim
+
+    @limiter.setter
+    def limiter(self, lim_tuple: tuple) -> None:
+        """Setter for magnitude and rate limiter
+
+        Parameters
+        ----------
+            lim_tuple : tuple of tuples
+                New magnitude limits
+        """
+
+        assert len(lim_tuple) == 2
+        assert len(lim_tuple[0]) == 2 and len(lim_tuple[1]) == 2
+        # assert lim[0] < lim[1]
+        self.m_lim = lim_tuple[0]
+        self.r_lim = lim_tuple[1]
+
+    def _limiter(self, u_control: float) -> float:
+        """Implements rate and magnitude limiter
+
+        Parameters
+        ----------
+        u_control : float
+            control signal to be limited
+
+        Returns
+        -------
+        float
+            float: rate and magnitude limited control signal
+        """
+
+        # Limiting the rate of u (delta_u)
+        delta_u = saturation((self.r_lim[0], self.r_lim[1]),
+                             u_control - self.ukm1)
+
+        # Limiting the magnitude of u
+        self.ukm1 = saturation((self.m_lim[0],
+                                self.m_lim[1]),
+                               delta_u + self.ukm1)
+
+        return self.ukm1
+
+    def _update_xn(self, ck: float, u_lim: float, y: float) -> None:
+        """Internal function to update the storage variables after the control
+        signal is calculated
+
+        Parameters
+        ----------
+        ck : float
+            combined transfer function output
+        u_lim : float
+            limited control signal
+        y : float
+            plant output
+        """
+        self.states['x1'] = (self.states['x2']
+                             - self.coeff['a1'] * ck
+                             + self.coeff['b0'] * u_lim
+                             + self.coeff['g1'] * y)
+
+        if self.order == 1:
+            self.states['x2'] = (- self.coeff['a2'] * ck
+                                 + self.coeff['b1'] * u_lim)
+
+        elif self.order == 2:
+            self.states['x2'] = (self.states['x3']
+                                 - self.coeff['a2'] * ck
+                                 + self.coeff['b1'] * u_lim
+                                 + self.coeff['g2'] * y)
+
+            self.states['x3'] = (- self.coeff['a3'] * ck
+                                 + self.coeff['b2'] * u_lim)
+
+    def __call__(self, y: float, r: float, zoh: bool = False) -> float:
+        """Returns value of the control signal depending on current
+        measurements and reference signal.
+
+        Parameters
+        ----------
+        y : float
+            Current measurement y[k] of the process
+        r : float
+            Current reference signal r[k]
+        zoh : bool, optional
+            Only update every delta seconds, by default False
+
+        Returns
+        -------
+        float
+            Current control signal u[k]
+        """
+        now = time.monotonic()
+
+        if zoh is True:
+            try:
+                dt = now - self._last_time if now - self._last_time else 1e-16
+            except TypeError:
+                dt = 1e-16
+
+        if zoh is True and dt < self.delta and self._last_output is not None:
+            # Return last output of the controller if dt < delta
+            return self._last_output
+
+        # Compute the combined transfer function output c(k)
+        ck = self.coeff['g0'] * y + self.states['x1']
+        # Compute unlimited control output u(k)
+        u = self.coeff['k'] * r - ck
+        # Limit controller output to obtain u_lim(k)
+        u_lim = self._limiter(u)
+
+        # Update storage variables x_n
+        self._update_xn(ck, u_lim, y)
+
+        self._last_output = float(u_lim)
+        self._last_time = now
+        return float(u_lim)
+
+
+class TransferFunction(object):
+
+    """Discrete time linear active disturbance rejection control\
+        in transfer function representation
+
+    Parameters
+    ----------
+    order : int
+        first- or second-order ADRC TF
+    delta : float
+        sampling time in seconds
+    b0 : float
+        modelling parameter b0
+    w_cl : float
+        desired closed-loop bandwidth [rad/s], 4 / w_cl and 6 / w_cl is the
+        corresponding settling time in seconds for first- and second-order ADRC
+        respectively
+    k_eso : float
+        observer bandwidth is parametrized as k_eso-multiple faster than w_cl
+    method : str, optional, 'general_terms' or 'bandwidth'
+        method with which the transfer function parameters are calculated,
+        functionally identical, by default 'general_terms'
+
+    References
+    ----------
+    .. [4] G. Herbst, Transfer Function Analysis and
+        Implementation of Active Disturbance Rejection Control
+        https://arxiv.org/abs/2011.01044
+    """
+
+    def __init__(self, order: int, delta: float, b0: float,
+                 w_cl: float, k_eso: float,
+                 method: str = 'general_terms') -> None:
+
+        assert order == 1 or order == 2, 'First- and second-order ADRC TF\
+            implemented'
+
+        # Define attributes
+        self.order = order
+        self.acc = 0.
+        zESO = np.exp(-k_eso * w_cl * delta)
+
+        self.params = self._calculate_parameters(order, delta, b0, w_cl, zESO,
+                                                 method=method)
+
+        self._calculate_coeffs()
+        self._create_states()
+
+    @property
+    def accumulator(self):
+        """Get accumulator
+
+        Returns
+        -------
+        float
+            accumulator output
+        """
+        return self.acc
+
+    @accumulator.setter
+    def accumulator(self, value):
+        """Set accumulator output to value
+
+        Parameters
+        ----------
+        value : float
+            value to set the accumulator
+        """
+        self.acc = float(value)
+
+    @property
+    def parameters(self):
+        """Get parameters
+
+        Returns
+        -------
+        dict
+            calculated paramaters
+        """
+        return self.params
+
+    def _create_states(self):
+        """Create state vectors to store past values for transfer functions
+        """
+
+        if self.order == 1:
+
+            # Reference prefilter
+            self.r_k = deque([0, 0], maxlen=2)
+            self.r_yk = deque([0], maxlen=1)
+
+            # Feedback controller
+            self.e_k = deque([0], maxlen=1)
+            self.u_k = deque([0], maxlen=1)
+
+        else:
+
+            # Reference prefilter
+            self.r_k = deque([0, 0, 0], maxlen=3)
+            self.r_yk = deque([0, 0], maxlen=2)
+
+            # Feedback controller
+            self.e_k = deque([0, 0], maxlen=2)
+            self.u_k = deque([0, 0], maxlen=2)
+
+    def _control_loop(self, y, r_k):
+
+        if self.order == 1:
+
+            # reference prefilter
+            ref_yk = (r_k * self.pf['num'][0]
+                      + self.r_k[0] * self.pf['num'][1]
+                      + self.r_k[1] * self.pf['num'][2]
+                      - self.r_yk[0] * self.pf['den'][1])
+
+            # advance time
+            self.r_k.appendleft(r_k)
+            self.r_yk.appendleft(ref_yk)
+
+            # calculate error
+            e_k = ref_yk - y
+
+            # feedback controller
+            u_k = (e_k * self.fb['num'][0]
+                   + self.e_k[0] * self.fb['num'][1]
+                   - self.u_k[0] * self.fb['den'][1])
+
+            # advance time
+            self.e_k.appendleft(e_k)
+            self.u_k.appendleft(u_k)
+
+        else:  # self.order == 2
+
+            # reference prefilter
+            ref_yk = (r_k * self.pf['num'][0]
+                      + self.r_k[0] * self.pf['num'][1]
+                      + self.r_k[1] * self.pf['num'][2]
+                      + self.r_k[2] * self.pf['num'][3]
+                      - self.r_yk[0] * self.pf['den'][1]
+                      - self.r_yk[1] * self.pf['den'][2])
+
+            # advance time
+            self.r_k.appendleft(r_k)
+            self.r_yk.appendleft(ref_yk)
+
+            # calculate error
+            e_k = ref_yk - y
+
+            # feedback controller
+            u_k = (e_k * self.fb['num'][0]
+                   + self.e_k[0] * self.fb['num'][1]
+                   + self.e_k[1] * self.fb['num'][2]
+                   - self.u_k[0] * self.fb['den'][1]
+                   - self.u_k[1] * self.fb['den'][2])
+
+            # advance time
+            self.e_k.appendleft(e_k)
+            self.u_k.appendleft(u_k)
+
+        # Accumulate feedback controller output
+        self.accumulator = self.accumulator + u_k
+
+        return self.accumulator
+
+    def _calculate_coeffs(self):
+        """Internal function to calculate the coefficients for the reference
+        prefilter and feedback controller (denominator and numerator)
+        Uses the z^-1 notation, coefficients in descending order, i.e
+        z^0, z^-1, ..., z^-n
+        """
+
+        if self.order == 1:
+            fb = {'num': [self.params['be0'], self.params['be1']],
+                  'den': [1, self.params['a1']]}
+            pf = {'num': [self.params['g0'],
+                          self.params['g1'], self.params['g2']],
+                  'den': [1, self.params['be1'] / self.params['be0']]}
+        else:
+            fb = {'num': [self.params['be0'], self.params['be1'],
+                          self.params['be2']],
+                  'den': [1, self.params['a1'], self.params['a2']]}
+            pf = {'num': [self.params['g0'], self.params['g1'],
+                          self.params['g2'], self.params['g3']],
+                  'den': [1, self.params['be1'] / self.params['be0'],
+                          self.params['be2'] / self.params['be0']]}
+
+        self.fb = fb
+        self.pf = pf
+
+    def _calculate_parameters(self, order, delta, b0,
+                              w_cl, zESO, method='general_terms'):
+
+        """Calculate the coefficients of num and den of TransferFunction ADRC,
+        using either general terms or bandwidth parameterization
+
+        Parameters
+        ----------
+        order : int
+            internal variable
+        delta : float
+            internal variable
+        b0 : float
+            internal variable
+        w_cl : float
+            internal variable
+        zESO : float
+            internal variable
+        method : str, optional
+            Calculation via general terms (i.e. controller and observer gains)
+            or bandwidth parametrization, functionally identical,
+            by default 'general_terms'
+
+        Returns
+        -------
+        list
+            Ordered transfer function parameters
+
+        Notes
+        -----
+        * For first-order ADRC: [a1, be0, be1, g0, g1, g2]
+        * For second-order ADRC: [a1, a2, be0, be1, be2, g0, g1, g2, g3]
+        """
+
+        if method == 'general_terms':
+            if order == 1:
+                # Controller gains
+                k1 = w_cl
+
+                # Observer gains
+                l1 = 1 - zESO**2
+                l2 = (1 / delta) * (1 - zESO)**2
+
+                _C_TERM = (k1 * l1 + l2)
+
+                a1 = (delta * k1 - 1) * (1 - l1)
+                be0 = (1 / b0) * _C_TERM
+                be1 = (1 / b0) * (delta * k1 * l2 - k1 * l1 - l2)
+                g0 = k1 / _C_TERM
+                g1 = k1 * (delta * l2 + l1 - 2) / _C_TERM
+                g2 = k1 * (1 - l1) / _C_TERM
+
+            elif order == 2:
+
+                k1 = w_cl**2
+                k2 = 2 * w_cl
+
+                l1 = 1 - zESO**3
+                l2 = (3 / (2 * delta)) * (1 - zESO)**2 * (1 + zESO)
+                l3 = (1 / delta**2) * (1 - zESO)**3
+
+                _C_TERM = (k1 * l1 + k2 * l2 + l3)
+
+                a1 = ((delta ** 2 / 2) * (k1 - k1 * l1 - k2 * l2)
+                      + delta * k2 + delta * l2 + l1 - 2)
+
+                a2 = ((((delta**2 * k1) / 2) - delta * k2 + 1) * (1 - l1))
+
+                be0 = (1 / b0) * _C_TERM
+
+                be1 = ((1 / b0) * (((delta**2 * k1 * l3) / 2)
+                                   + delta * k1 * l2 + delta
+                                   * k2 * l3 - 2
+                                   * _C_TERM))
+
+                be2 = ((1 / b0) * (((delta**2 * k1 * l3) / 2)
+                                   - delta * k1 * l2 - delta
+                                   * k2 * l3 + _C_TERM))
+
+                g0 = k1 / _C_TERM
+
+                g1 = ((k1 * (delta**2 * l3 + 2 * delta * l2 + 2 * l1 - 6))
+                      / (2 * _C_TERM))
+
+                g2 = ((k1 * (delta**2 * l3 - 2 * delta * l2 - 4 * l1 + 6))
+                      / (2 * _C_TERM))
+
+                g3 = (k1 * (l1 - 1)) / _C_TERM
+
+        elif method == 'bandwidth':
+            if order == 1:
+
+                _C_TERM = ((delta * w_cl) * (1 - zESO**2) + (1 - zESO)**2)
+
+                a1 = (delta * w_cl - 1) * zESO**2
+
+                be0 = ((1/(b0 * delta)) * _C_TERM)
+
+                be1 = ((1/(b0 * delta)) * ((-2 * delta * w_cl * zESO)
+                                           * (1 - zESO) - (1 - zESO)**2))
+
+                g0 = (delta * w_cl) / _C_TERM
+                g1 = (-2 * delta * w_cl * zESO) / _C_TERM
+                g2 = (delta * w_cl * zESO**2) / _C_TERM
+
+            elif order == 2:
+
+                _C_TERM = (delta**2 * w_cl**2 * (1 - zESO**3)
+                           + 3 * delta * w_cl * (1 - zESO - zESO**2 + zESO**3)
+                           + (1 - zESO)**3)
+
+                a1 = ((1/2) * (delta**2 * w_cl**2 * zESO**3
+                               + delta * w_cl
+                               * (1 + 3 * zESO + 3 * zESO**2 - 3 * zESO**3)
+                               + (1 - 3 * zESO - 3 * zESO**2 + zESO**3)))
+
+                a2 = ((zESO**3 / 2)
+                      * (delta**2 * w_cl**2 - 4 * delta * w_cl + 2))
+
+                be0 = ((1 / (b0 * delta**2)) * _C_TERM)
+
+                be1 = ((1 / (b0 * delta**2))
+                       * (-3 * delta**2 * w_cl**2 * zESO * (1 - zESO**2)
+                          - 4 * delta * w_cl * (1 - 3 * zESO**2 + 2 * zESO**3)
+                          - 2 * (1 - zESO)**3))
+
+                be2 = ((1 / (b0 * delta**2))
+                       * (3 * delta**2 * w_cl**2 * zESO**2 * (1 - zESO)
+                          + delta * w_cl
+                          * (1 + 3 * zESO - 9 * zESO**2 + 5 * zESO**3)
+                          + (1 - zESO)**3))
+
+                g0 = (delta**2 * w_cl**2) / _C_TERM
+                g1 = (-3 * delta**2 * w_cl**2 * zESO) / _C_TERM
+                g2 = (3 * delta**2 * w_cl**2 * zESO**2) / _C_TERM
+                g3 = (-1 * delta**2 * w_cl**2 * zESO**3) / _C_TERM
+
+        if order == 1:
+            params = {'a1': a1, 'be0': be0,
+                      'be1': be1, 'g0': g0,
+                      'g1': g1, 'g2': g2}
+        else:
+            params = {'a1': a1, 'a2': a2, 'be0': be0,
+                      'be1': be1, 'be2': be2, 'g0': g0,
+                      'g1': g1, 'g2': g2, 'g3': g3}
+
+        return params
+
+    def __call__(self, y, r):
+        """Control loop call
+
+        Parameters
+        ----------
+        y : float
+            current output signal
+        r : float
+            current reference signal
+
+        Returns
+        -------
+        float
+            control signal to the plant (accumulator output)
+        """
+
+        return self._control_loop(y, r)

pyadrc-0.5.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: pyadrc
+Version: 0.5.0
+Summary: Active Disturbance Rejection Control for Python
+Author-email: Ongun Türkcüoglu <onguntoglu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/onguntoglu/pyadrc
+Project-URL: Documentation, https://pyadrc.readthedocs.io
+Keywords: pyadrc,adrc,control
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.rst
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: control; extra == "dev"
+Dynamic: license-file
+
+# pyadrc's Documentation
+
+[![PyPI](https://img.shields.io/pypi/v/pyadrc.svg)](https://pypi.python.org/pypi/pyadrc)
+[![CI](https://github.com/onguntoglu/pyadrc/actions/workflows/ci.yml/badge.svg)](https://github.com/onguntoglu/pyadrc/actions/workflows/ci.yml)
+[![Documentation Status](https://readthedocs.org/projects/pyadrc/badge/?version=latest)](https://pyadrc.readthedocs.io/en/latest/?badge=latest)
+[![Licence](https://img.shields.io/github/license/onguntoglu/pyadrc.svg)](https://github.com/onguntoglu/pyadrc/blob/master/LICENSE)
+[![Downloads](https://pepy.tech/badge/pyadrc)](https://pepy.tech/project/pyadrc)
+
+Active Disturbance Rejection Control for Python
+
+A simple, yet powerful control method for when a PID controller just doesn't cut it.
+
+## Features
+
+- Discrete linear time invariant active disturbance rejection controller for digital control systems.
+- First- and second-order ADRC in state-space, transfer function and minimum-footprint (FeedbackTF) form.
+- For practical application - half-gain tuning, magnitude and rate limiter for actuator limitations
+- User guide and/or theoretical background (for when you don't have anything else to read).
+- A first/second-order LTI model generator and a quadcopter altitude model for experimentation, testing and verification.
+
+## Installation
+
+Installing **pyadrc** is really simple, just run this command in your terminal:
+
+```bash
+pip install pyadrc
+```
+
+or you can clone the repository and install it manually:
+
+```bash
+git clone https://github.com/onguntoglu/pyadrc
+cd pyadrc
+pip install .
+```
+
+## Licence
+
+**pyadrc** is licenced under the MIT Licence
+
+## Acknowledgements
+
+None of this work would be possible without **Gernot Herbst** and his papers:
+
+- *[Practical Active Disturbance Rejection Control: Bumpless Transfer, Rate Limitation and Incremental Algorithm](https://arxiv.org/abs/1908.04610)*
+- *[A Simulative Study on Active Disturbance Rejection Control (ADRC) as a Control Tool for Practitioners](https://arxiv.org/abs/1908.04596)*
+- *[Transfer Function Analysis and Implementation of Active Disturbance Rejection Control](https://arxiv.org/abs/2011.01044)*
+- *[Half-Gain Tuning for Active Disturbance Rejection Control](https://arxiv.org/abs/2003.03986)*
+- *[A Minimum-Footprint Implementation of Discrete-Time ADRC](https://arxiv.org/abs/2104.01943)*

pyadrc-0.5.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pyadrc/__init__.py,sha256=EjRk0BEOE8D0dllkwHj14Dtwr5aJJUCijh1WXWmb614,373
+pyadrc/models.py,sha256=C9srGX5FJBTO9sunvwXvCQrVrRQrkIX74bt_d6WGl5I,4477
+pyadrc/pyadrc.py,sha256=wx6OZvWo3UKQB_3aGm26cxvDzSGwZ8xjfzuG5dTil0c,30169
+pyadrc-0.5.0.dist-info/licenses/AUTHORS.rst,sha256=w9A68eGmFO3a9taKcnJh_NWUZbkj38cuPTLLiOB31Gc,164
+pyadrc-0.5.0.dist-info/licenses/LICENSE,sha256=_0pf3xnvyOF8LaQNKgm75XW9Byjp2CBgYbZbhwlpDQw,1077
+pyadrc-0.5.0.dist-info/METADATA,sha256=4DL5qjBz0VGsXuT5mvdmEZbfIEVHNeZK_8HSNh5Jnjg,3361
+pyadrc-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pyadrc-0.5.0.dist-info/top_level.txt,sha256=DiqtzK4DShwozIn-DOeRaXW19dIqGTnuoO13_r1gF0A,7
+pyadrc-0.5.0.dist-info/RECORD,,

pyadrc-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyadrc-0.5.0.dist-info/licenses/AUTHORS.rst

@@ -0,0 +1,13 @@
+=======
+Credits
+=======
+
+Development Lead
+----------------
+
+* Ongun Türkcüoglu <onguntoglu@gmail.com>
+
+Contributors
+------------
+
+None yet. Why not be the first?

pyadrc-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021, Ongun Türkcüoglu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

pyadrc-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyadrc