clock_tracking_loop.h

/* -*- c++ -*- */
/*
 * Copyright (C) 2011,2013,2016-2017 Free Software Foundation, Inc.
 *
 * This file is part of GNU Radio
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 */

#ifndef INCLUDED_DIGITAL_CLOCK_TRACKING_LOOP_H
#define INCLUDED_DIGITAL_CLOCK_TRACKING_LOOP_H

namespace gr {
namespace digital {

/*!
 * \brief A second-order control loop implementation class.
 *
 * \details
 * This class implements most of a second order symbol clock
 * tracking loop and is intended to act as a parent class to blocks
 * which need a symbol clock tracking loop to determine the optimal
 * instant to sample a received symbol from an input sample
 * stream (i.e. *_clock_recovery* and *_clock_sync* blocks).
 * It takes in an expected timing error detector gain, a normalized loop
 * bandwidth and damping factor, as well as clock period bounds, and
 * provides the functions that control the update of the loop.
 *
 * This control loop runs at the rate of the output clock, so
 * each step of the loop produces estimates about the output clock,
 * and the clock phase/timing error input must come at a rate of
 * once per output clock.
 *
 * This class does not include a timing error detector, and the
 * caller is expected to provide the clock phase/timing error input
 * for each step of the loop.
 *
 * The loop's low pass filter is a Proportional-Integral (PI) filter.
 * The proportional and integral gains of the filter are termed alpha
 * and beta respectively. These gains are calculated using the input
 * expected timing error detector gain, loop bandwidth and damping factor.
 * If needed, the alpha and beta gain values can be set using their
 * respective #set_alpha or #set_beta functions.
 *
 * The class estimates the average clock period, T_avg; the instantaneous
 * clock period, T_inst; and the instantaneous clock phase, tau; of a
 * symbol clock based on an error signal from an external clock phase/
 * timing error detector which provides one error signal sample per
 * clock (one error sample at the end of every T_inst clock cycle).
 * The error calculation is unique for each TED algorithm and is
 * calculated externally and passed to the advance_loop function,
 * which uses this to update its estimates.
 *
 * This class also provides the functions #phase_wrap and
 * #period_limit to easily keep the clock phase estimate, tau, and the
 * average clock period estimate, T_avg, within set bounds (phase_wrap
 * keeps the phase within +/-T_avg/2).
 *
 * The clock tracking loop, with its PI filter, when properly implemented, has
 * a digital loop phase-transfer function, in terms of the timing error
 * detector gain, \f$K_{ted}\f$; proportional gain, \f$\alpha\f$; and the
 * integral gain, \f$\beta\f$, as follows:
 *
 * \f{align*}
 *    H(z) &= \dfrac {\Theta_o(z)}{\Theta_i(z)}
 *          = K_{ted}(\alpha + \beta)z^{-1} \cdot
 *            \dfrac{
 *                   1
 *                   - \dfrac{\alpha}{\alpha + \beta} z^{-1}
 *                  }
 *                  {
 *                   1
 *                   - 2 \left(1 - K_{ted}\dfrac{\alpha + \beta}{2}\right) z^{-1}
 *                   + (1 - K_{ted}\alpha) z^{-2}
 *                  } \\
 * \f}
 *
 * Mapping the above phase-transfer function to the standard form of a transfer
 * function for an analog second order control loop mapped to the digital domain
 * with the mapping \f$z = e^{sT}\f$ applied to the s-plane poles,
 * \f$s_{1,2} = -\zeta\omega_{n} \pm \omega_{n}\sqrt{\zeta^{2}-1}\f$, one obtains an
 * alternate form of the transfer function, directly related to the damping factor
 * \f$\zeta\f$, the natural radian frequency \f$\omega_{n}\f$, the damped radian frequency
 * of oscillation \f$\omega_{d}\f$, and the symbol clock period \f$T\f$:
 *
 * \f{align*}
 *   H(z) &=
 *      \begin{cases}
 *         \dfrac{
 *                [2 -2\cos(\omega_{d}T)e^{-\zeta\omega_{n}T}] z
 *                -2\sinh(\zeta\omega_{n}T)e^{-\zeta\omega_{n}T}
 *               }
 *               {
 *                z^{2}
 *                - 2 \cos(\omega_{d}T) e^{-\zeta\omega_{n}T} z
 *                + e^{-2\zeta\omega_{n}T}
 *               }
 *               & \quad \text{for} \quad \zeta < 1 \quad \text{with}
 *               \quad \omega_{d}T = \omega_{n}T \sqrt{1 - \zeta^{2}}
 *               \\
 * \\
 *         \dfrac{
 *                [2 -2(1)e^{-\zeta\omega_{n}T}] z
 *                -2\sinh(\zeta\omega_{n}T)e^{-\zeta\omega_{n}T}
 *               }
 *               {
 *                z^{2}
 *                - 2(1)e^{-\zeta\omega_{n}T} z
 *                + e^{-2\zeta\omega_{n}T}
 *               }
 *               & \quad \text{for} \quad \zeta = 1 \quad \text{with}
 *               \quad \omega_{d}T = 0
 *               \\
 * \\
 *         \dfrac{
 *                [2 -2\cosh(\omega_{d}T)e^{-\zeta\omega_{n}T}] z
 *                -2\sinh(\zeta\omega_{n}T)e^{-\zeta\omega_{n}T}
 *               }
 *               {
 *                z^{2}
 *                - 2 \cosh(\omega_{d}T) e^{-\zeta\omega_{n}T} z
 *                + e^{-2\zeta\omega_{n}T}
 *               }
 *               & \quad \text{for} \quad \zeta > 1 \quad \text{with}
 *               \quad \omega_{d}T = \omega_{n}T \sqrt{\zeta^{2} - 1}
 *               \\
 *      \end{cases}
 * \\
 * \f}
 *
 * The PI filter gains, expressed in terms of the damping factor, \f$\zeta\f$;
 * the natural radian frequency, \f$\omega_{n}\f$; the damped radian frequency of
 * oscillation, \f$\omega_{d}\f$; the timing error detector gain \f$K_{ted}\f$;
 * and the clock period \f$T\f$ are:
 *
 * \f{align*}
 *   \alpha &= \dfrac{2}{K_{ted}}e^{-\zeta\omega_{n}T} \sinh(\zeta\omega_{n}T) \\
 * \\
 *   \beta  &=
 *      \begin{cases}
 *         \dfrac{2}{K_{ted}} \left(1 -
 *          e^{-\zeta\omega_{n}T} [\sinh(\zeta\omega_{n}T) + \cos(\omega_{d}T)]
 *          \right) &
 *         \text{for} \quad \zeta < 1 \quad (under \: damped)\\ \\
 *         \dfrac{2}{K_{ted}} \left(1 -
 *          e^{-\zeta\omega_{n}T} [\sinh(\zeta\omega_{n}T) + 1]
 *          \right) &
 *         \text{for} \quad \zeta = 1 \quad (critically \: damped)\\ \\
 *         \dfrac{2}{K_{ted}} \left(1 -
 *          e^{-\zeta\omega_{n}T} [\sinh(\zeta\omega_{n}T) +\cosh(\omega_{d}T)]
 *          \right) &
 *         \text{for} \quad \zeta > 1 \quad (over \: damped)\\
 *      \end{cases} \\
 * \\
 * \f}
 *
 * It should be noted that the clock period \f$T\f$ is being estimated by the clock
 * tracking loop and can vary over time, so that setting the loop bandwidth
 * directly can be a problem.  However, we specify loop bandwidth in terms
 * of the normalized digital natural radian frequency \f$\omega_{n\_norm}\f$ of the loop.
 * \f$\omega_{n\_norm}\f$ can only usefully be a small positive number, close to
 * zero.  The damping factor, \f$\zeta\f$, dictates the maximum value
 * \f$\omega_{n\_norm}\f$ can practically take on.  In the extreme a case of
 * \f$\zeta = 0.0\f$, \f$\omega_{n\_norm}\f$ is practically limited to the range
 * \f$(0, \pi)\f$, as \f$\pi\f$ then corresponds to the Nyquist frequency
 * of the clock.  However, whatever the damping factor, large values of
 * \f$\omega_{n\_norm}\f$ are usually not useful and yield poor results.
 *
 * \f{align*}
 *     \omega_{n}T = \omega_{n\_norm} = 2 \pi f_{n\_norm} = 2 \pi f_{n} T =
 *     \pi \dfrac{f_{n}}{\left(\dfrac{F_{c}}{2}\right)}
 * \f}
 *
 * In practice, the timing error detector (TED) of the symbol clock
 * tracking loop is implemented with an estimator of symbol clock phase
 * error, which has some gain \f$K_{ted}\f$.  The gain, \f$K_{ted}\f$, is
 * defined as the slope of a TED's S-curve plot at a symbol clock phase
 * offset of \f$\tau = 0\f$.  The S-curve shape and central slope, and
 * hence the gain \f$K_{ted}\f$, depend on the TED's estimator espression,
 * the input signal level, the pulse shaping filter, and the \f$E_s/N_0\f$
 * of the incomping signal.  The user must determine the TED's
 * S-curve by analysis or simulation of the particular situation, in order
 * to determine an appropriate value for \f$K_{ted}\f$.
 *
 * * A note on symbol clock phase vs. interpolating resampler sample phase,
 * since most GNURadio symbol synchronization blocks seem to have the same
 * implementation error:
 *
 * In general, the symbol clock phase, that the symbol clock tracking loop
 * estimates and tracks, cannot be used alone to derive the interpolating resampler
 * sample phase used in symbol synchronization, except in the very special case of
 * the symbol clock period being exactly divisible by the input sample stream
 * sample period.  Since this is never guaranteed in tracking real symbol clocks,
 * one should not use the symbol clock phase alone to compute the interpolating
 * resampler sample phase.
 *
 * Consider, in the analog time domain, the optimum symbol sampling instants
 * \f$t_{k}\f$, of an analog input signal \f$x(t)\f$, at an optimal symbol clock
 * phase \f$\tau_{0}\f$ and the symbol clock period \f$T_{c}\f$:
 *
 * \f{align*}
 *    t_{k} &= \tau_{0} + k T_{c} \\
 *    y_{k} &= x(t_{k}) = x(\tau_{0} + k T_{c}) \\
 * \f}
 *
 * If one divides the \f$t_{k}\f$ times by the input sample stream sample period
 * \f$T_{i}\f$, the correct interpolating resampler sample phase \f$\tau_{0\_i}\f$ will
 * get a contribution from the term \f$T_{c\_remainder}\f$ (which is an error) as shown
 * below:
 *
 * \f{align*}
 *    \dfrac{t_{k}}{T_{i}} &= \dfrac{\tau_{0}}{T_{i}} + \dfrac{k T_{c}}{T_{i}} \\
 *     &= (m + \tau_{0\_remainder}) + (n + T_{c\_remainder}) \\
 *     &= \tau_{0\_remainder} + T_{c\_remainder} + (m + n) \\
 *     &= \tau_{0\_i} + k^{\prime}
 * \f}
 *
 * So instead of using the symbol clock sample phase alone to obtain the
 * interpolating resampler sample phase, one should use the previous interpolating
 * resampler sample phase and the instantaneous clock period estimate provided by
 * the symbol clock tracking loop.
 *
 */
class clock_tracking_loop
{
protected:
    // Estimate of the average clock period, T_avg, in units of
    // input sample clocks (so this is the average number of
    // input samples per output symbol, aka samples/symbol).
    // To convert to seconds, divide by the input sample rate: F_s_input.
    float d_avg_period;

    // Limits on how far the average clock period estimate can wander,
    // and the nominal average clock period, in units of input sample clocks.
    // To convert to seconds, divide by the input sample rate: F_s_input.
    float d_max_avg_period, d_min_avg_period;
    float d_nom_avg_period;

    // Instantaneous clock period estimate, T_inst, in units of
    // input sample clocks (so this is the intantaneous number of
    // input samples per output symbol, aka instantaneous samples/symbol).
    // To convert to seconds, divide by the input sample rate: F_s_input.
    float d_inst_period;

    // Instantaneous clock phase estimate, tau, in units of
    // input sample clocks.
    // To convert to seconds, divide by the input sample rate: F_s_input.
    // To wrap, add or subtract a multiple of the estimate of the
    // average clock period, T_avg.
    // To convert to a normalized (but not wrapped) clock phase estimate,
    // divide by the estimate of the average clock period, T_avg.
    // To further convert the normalized clock phase estimate to radians,
    // multiply the normalized clock phase estimate by 2*pi.
    float d_phase;

    // Damping factor of the 2nd order loop transfer function.
    // Zeta in the range (0.0, 1.0) yields an under-damped loop.
    // Zeta in the range (1.0, Inf) yields an over-damped loop.
    // Zeta equal to 1.0 yields a crtically-damped loop.
    float d_zeta;

    // Normalized natural radian frequency of the 2nd order loop transfer
    // function.  It should be a small positive number, corresponding to
    // the normalized natural radian frequency of the loop as digital
    // low-pass filter that is filtering the clock phase/timing error signal.
    // omega_n_norm = omega_n*T  = 2*pi*f_n*T = 2*pi*f_n_norm
    float d_omega_n_norm;

    // Expected gain of the timing error detector in use, given the
    // TED estimator expression, the expected input amplitude, the
    // input pulse shape, and the expected input Es/No.  (This value is the
    // slope of the TED's S-curve plot at a timing offset of tau = 0, and
    // must be determined by analysis and/or simulation by the user.)
    float d_ted_gain;

    // Proportional gain of the PI loop filter (aka gain_mu)
    // (aka gain_mu in some clock recovery blocks)
    float d_alpha;

    // Integral gain of the PI loop filter
    // (aka gain_omega in some clock recovery blocks)
    float d_beta;

    // For reverting the loop state one iteration (only)
    float d_prev_avg_period;
    float d_prev_inst_period;
    float d_prev_phase;

public:
    clock_tracking_loop(void) {}

    /*! \brief Construct a clock_tracking_loop object.
     *
     * \details
     * This function instantiates a clock_tracking_loop object.
     *
     * \param loop_bw
     * Normalized approximate loop bandwidth.
     * It should be a small positive number, corresponding to the normalized
     * natural radian frequency of the loop as digital low-pass filter that is
     * filtering the clock phase/timing error.
     *
     * Technically this parameter corresponds to the natural radian frequency
     * of the 2nd order loop transfer function (scaled by Fs),
     * which is the radius of the pole locations in the s-plane of an
     * underdamped analog 2nd order system.
     *
     * \param max_period
     * Maximum limit for the estimated clock period, in units of
     * input stream sample periods. (i.e. maximum samples/symbol)
     *
     * \param min_period
     * Minimum limit for the estimated clock period, in units of
     * input stream sample periods. (i.e. minimum samples/symbol)
     *
     * \param nominal_period
     * Nominal value for the estimated clock period, in units of
     * input stream sample periods. (i.e. nominal samples/symbol)
     * If not specified, this value will be set to the average of
     * min_period and max_period,
     *
     * \param damping
     * Damping factor of the 2nd order loop transfer function.
     * Damping in the range (0.0, 1.0) yields an under-damped loop.
     * Damping in the range (1.0, Inf) yields an over-damped loop.
     * Damping equal to 1.0 yields a crtically-damped loop.
     * Under-damped loops are not generally useful for clock tracking.
     * This parameter defaults to 1.0, if not specified.
     *
     * \param ted_gain
     * Expected gain of the timing error detector, given the TED in use
     * and the anticipated input amplitude, pulse shape, and Es/No.
     * This value is the slope of the TED's S-curve at timing offset tau = 0.
     * This value is normally computed by the user analytically or by
     * simulation in a tool outside of GNURadio.
     * This value must be correct for the loop filter gains to be computed
     * properly from the desired input loop bandwidth and damping factor.
     * This parameter defaults to 1.0, if not specified.
     */
    clock_tracking_loop(float loop_bw,
                        float max_period,
                        float min_period,
                        float nominal_period = 0.0f,
                        float damping = 1.0f,
                        float ted_gain = 1.0f);

    virtual ~clock_tracking_loop();

    /*! \brief Update the gains from the ted_gain, loop bw and damping factor.
     *
     * \details
     * This function updates the gains based on the loop
     * bandwidth and damping factor of the system. These two
     * factors can be set separately through their own set
     * functions.
     */
    void update_gains();

    /*! \brief Advance the loop based on the current gain
     *  settings and the input error signal.
     */
    void advance_loop(float error)
    {
        // So the loop can be reverted one step, if needed.
        d_prev_avg_period = d_avg_period;
        d_prev_inst_period = d_inst_period;
        d_prev_phase = d_phase;

        // Integral arm of PI filter
        d_avg_period = d_avg_period + d_beta * error;
        // Limit the integral arm output here, as a large negative
        // error input can lead to a negative d_avg_period, which
        // will cause an infitine loop in the phase wrap method.
        period_limit();

        // Proportional arm of PI filter and final sum of PI filter arms
        d_inst_period = d_avg_period + d_alpha * error;
        // Limit the filter output here, for the errant case of a large
        // negative error input, that can lead to a negative d_inst_period,
        // which results in an incorrect phase increment, as it is assumed
        // to be moving forward to the next symbol.
        if (d_inst_period <= 0.f)
            d_inst_period = d_avg_period;

        // Compute the new, unwrapped clock phase
        d_phase = d_phase + d_inst_period;
    }

    /*! \brief Undo a single, prior advance_loop() call.
     *
     * \details
     * Reverts a single, prior call to advance_loop().
     * It cannot usefully called again, until after the next call
     * to advance_loop().
     *
     * This method is needed so clock recovery/sync blocks can
     * perform correctly given the constraints of GNURadio's streaming
     * engine, interpolation filtering, and tag propagation.
     */
    void revert_loop()
    {
        d_avg_period = d_prev_avg_period;
        d_inst_period = d_prev_inst_period;
        d_phase = d_prev_phase;
    }

    /*! \brief
     * Keep the clock phase estimate, tau, between -T_avg/2 and T_avg/2.
     *
     * \details
     * This function keeps the clock phase estimate, tau, between
     * -T_avg/2 and T_avg/2, by wrapping it modulo the estimated
     * average clock period, T_avg.  (N.B. Wrapping an estimated phase
     * by an *estimated*, *average* period.)
     *
     * This function can be called after advance_loop to keep the
     * phase value small.  It is set as a separate method in case
     * another way is desired as this is fairly heavy-handed.
     * Clock recovery/sync blocks usually do not need the phase of the
     * clock, and this class doesn't actually use the phase at all,
     * so calling this is optional.
     */
    void phase_wrap()
    {
        float period = d_avg_period; // One could argue d_inst_period instead
        float limit = period / 2.0f;

        while (d_phase > limit)
            d_phase -= period;

        while (d_phase <= -limit)
            d_phase += period;
    }

    /*! \brief
     * Keep the estimated average clock period, T_avg, between T_avg_min
     * and T_avg_max.
     *
     * \details
     * This function keeps the estimated average clock period, T_avg,
     * between T_avg_min and T_avg_max. It accomplishes this by hard limiting.
     * This is needed because T_avg is essentially computed by the
     * integrator portion of an IIR filter, so T_avg could potentially
     * wander very far during periods of noise/nonsense input.
     *
     * This function is called in advance_loop to keep the
     * estimated average clock period, T_avg, in the specified range.
     * It is set as a separate virtual method in case another way is desired
     * as this is fairly heavy-handed.
     */
    virtual void period_limit()
    {
        if (d_avg_period > d_max_avg_period)
            d_avg_period = d_max_avg_period;
        else if (d_avg_period < d_min_avg_period)
            d_avg_period = d_min_avg_period;
    }

    /*******************************************************************
     * SET FUNCTIONS
     *******************************************************************/

    /*!
     * \brief Set the normalized approximate loop bandwidth.
     *
     * \details
     * Set the normalized approximate loop bandwidth.
     * Useful values are usually close to 0.0, e.g. 2*pi*0.045.
     *
     * It should be a small positive number, corresponding to the normalized
     * natural radian frequency of the loop as digital low-pass filter that is
     * filtering the clock phase/timing error.
     *
     * Technically this parameter corresponds to the natural radian frequency
     * of the 2nd order loop transfer function (scaled by Fs),
     * which is the radius of the pole locations in the s-plane of an
     * underdamped analog 2nd order system.
     *
     * The input parameter corresponds to omega_n_norm in the following
     * relation:
     *
     *     omega_n_norm = omega_n*T = 2*pi*f_n*T = 2*pi*f_n_norm
     *
     * where T is the period of the clock being estimated by this
     * clock tracking loop, and omega_n is the natural radian frequency
     * of the 2nd order loop transfer function.
     *
     * When a new loop bandwidth is set, the gains, alpha and beta,
     * of the loop are recalculated by a call to update_gains().
     *
     * \param bw    normalized approximate loop bandwidth
     */
    virtual void set_loop_bandwidth(float bw);

    /*!
     * \brief Set the loop damping factor.
     *
     * \details
     * Set the damping factor of the loop.
     * Damping in the range (0.0, 1.0) yields an under-damped loop.
     * Damping in the range (1.0, Inf) yields an over-damped loop.
     * Damping equal to 1.0 yields a crtically-damped loop.
     * Under-damped loops are not generally useful for clock tracking.
     * For clock tracking, as a first guess, set the damping factor to 2.0,
     * or 1.5 or 1.0.
     *
     * Damping factor of the 2nd order loop transfer function.
     * When a new damping factor is set, the gains, alpha and beta,
     * of the loop are recalculated by a call to update_gains().
     *
     * \param df    loop damping factor
     */
    void set_damping_factor(float df);

    /*!
     * \brief Set the expected gain of the Timing Error Detector.
     *
     * \details
     * Sets the expected gain of the timing error detector, given the TED in
     * use and the anticipated input amplitude, pulse shape, and Es/No.
     * This value is the slope of the TED's S-curve at timing offset tau = 0.
     * This value is normally computed by the user analytically or by
     * simulation in a tool outside of GNURadio.
     * This value must be correct for the loop filter gains to be computed
     * properly from the desired input loop bandwidth and damping factor.
     *
     * When a new ted_gain is set, the gains, alpha and beta,
     * of the loop are automatically recalculated.
     *
     * \param ted_gain    expected gain of the timing error detector
     */
    void set_ted_gain(float ted_gain);

    /*!
     * \brief Set the PI filter proportional gain, alpha.
     *
     * \details
     * Sets the PI filter proportional gain, alpha.
     * This gain directly mutliplies the clock phase/timing error
     * term in the PI filter when advancing the loop.
     * It most directly affects the instantaneous clock period estimate,
     * T_inst, and instantaneous clock phase estimate, tau.
     *
     * This value would normally be adjusted by setting the loop
     * bandwidth and damping factor and calling update_gains(). However,
     * it can be set here directly if desired.
     *
     * Setting this parameter directly is probably only feasible if
     * the user is directly observing the estimates of average clock
     * period and instantaneous clock period over time in response to
     * an impulsive change in the input stream (i.e. watching the loop
     * transient behavior at the start of a data burst).
     *
     * \param alpha    PI filter proportional gain
     */
    void set_alpha(float alpha);

    /*!
     * \brief Set the PI filter integral gain, beta.
     *
     * \details
     * Sets the PI filter integral gain, beta.
     * This gain is used when integrating the clock phase/timing error
     * term in the PI filter when advancing the loop.
     * It most directly affects the average clock period estimate,
     * T_avg.
     *
     * This value would normally be adjusted by setting the loop
     * bandwidth and damping factor and calling update_gains(). However,
     * it can be set here directly if desired.
     *
     * Setting this parameter directly is probably only feasible if
     * the user is directly observing the estimates of average clock
     * period and instantaneous clock period over time in response to
     * an impulsive change in the input stream (i.e. watching the loop
     * transient behavior at the start of a data burst).
     *
     * \param beta    PI filter integral gain
     */
    void set_beta(float beta);

    /*!
     * \brief Set the average clock period estimate, T_avg.
     *
     * \details
     * Directly sets the average clock period estimate, T_avg,
     * in units of input stream sample clocks (so the average number of
     * input samples per output symbol, aka samples/symbol).
     *
     * The average clock period estimate, T_avg, is normally updated by
     * the advance_loop() and period_limit() calls. This method is used
     * manually reset the estimate when needed.
     *
     * \param period
     * Average clock period, T_avg, in units of input stream sample clocks.
     */
    void set_avg_period(float period);

    /*!
     * \brief Set the instantaneous clock period estimate, T_inst.
     *
     * \details
     * Directly sets the instantaneous clock period estimate, T_inst,
     * in units of input stream sample clocks (so the instantaneous number of
     * input samples per output symbol, aka instantaneous samples/symbol).
     *
     * The instantaneous clock period estimate, T_inst, is normally updated by
     * the advance_loop() call. This method is used manually reset the
     * estimate when needed.
     *
     * \param period
     * Instantaneous clock period, T_inst, in units of input stream sample
     * clocks.
     */
    void set_inst_period(float period);

    /*!
     * \brief Set the instantaneous clock phase estimate, tau.
     *
     * \details
     * Directly sets the instantaneous clock phase estimate, tau,
     * in units of input stream sample clocks.
     *
     * The instantaneous clock phase estimate, tau, is normally updated by
     * the advance_loop() call. This method is used manually reset the
     * estimate when needed.
     *
     * \param phase
     * Instantaneous clock phase, tau, in units of input stream sample clocks.
     *
     */
    void set_phase(float phase);

    /*!
     * \brief Set the maximum average clock period estimate limit, T_avg_max.
     *
     * \details
     * Sets the maximum average clock period estimate limit, T_avg_max
     * in units of input stream sample clocks (so the maximum average number
     * of input samples per output symbol, aka maximum samples/symbol).
     *
     * This limit is needed because T_avg is essentially computed by the
     * integrator portion of an IIR filter, so T_avg could potentially
     * wander very far during periods of noise/nonsense input.
     *
     * \param period
     * Maximum average clock period, T_avg_max, in units of input stream
     * sample clocks.
     */
    void set_max_avg_period(float period);

    /*!
     * \brief Set the minimum average clock period estimate limit, T_avg_min.
     *
     * \details
     * Sets the minimum average clock period estimate limit, T_avg_min
     * in units of input stream sample clocks (so the minimum average number
     * of input samples per output symbol, aka minimum samples/symbol).
     *
     * This limit is needed because T_avg is essentially computed by the
     * integrator portion of an IIR filter, so T_avg could potentially
     * wander very far during periods of noise/nonsense input.
     *
     * \param period
     * Minimum average clock period, T_avg_min, in units of input stream
     * sample clocks.
     */
    void set_min_avg_period(float period);

    /*!
     * \brief Set the nominal average clock period estimate limit, T_avg_nom.
     *
     * \details
     * Sets the nominal average clock period estimate limit, T_avg_nom
     * in units of input stream sample clocks (so the nominal average number
     * of input samples per output symbol, aka minimum samples/symbol).
     *
     * \param period
     * Nominal average clock period, T_avg_nom, in units of input stream
     * sample clocks.
     */
    void set_nom_avg_period(float period);

    /*******************************************************************
     * GET FUNCTIONS
     *******************************************************************/

    /*!
     * \brief Returns the normalized approximate loop bandwidth.
     *
     * \details
     * See the documentation for set_loop_bandwidth() for more details.
     *
     * Note that if set_alpha() or set_beta() were called to directly
     * set gains, the value returned by this method will be inaccurate/stale.
     */
    float get_loop_bandwidth() const;

    /*!
     * \brief Returns the loop damping factor.
     *
     * \details
     * See the documentation for set_damping_factor() for more details.
     *
     * Note that if set_alpha() or set_beta() were called to directly
     * set gains, the value returned by this method will be inaccurate/stale.
     */
    float get_damping_factor() const;

    /*!
     * \brief Returns the user providded expected gain of the Timing Error
     * Detector.
     *
     * \details
     * See the documentation for set_ted_gain() for more details.
     */
    float get_ted_gain() const;

    /*!
     * \brief Returns the PI filter proportional gain, alpha.
     *
     * \details
     * See the documentation for set_alpha() for more details.
     */
    float get_alpha() const;

    /*!
     * \brief Returns the PI filter integral gain, beta.
     *
     * \details
     * See the documentation for set_beta() for more details.
     */
    float get_beta() const;

    /*!
     * \brief Get the average clock period estimate, T_avg.
     *
     * \details
     * Gets the average clock period estimate, T_avg,
     * in units of input stream sample clocks (so the average number of
     * input samples per output symbol, aka samples/symbol).
     *
     * To convert to seconds, divide by the input stream sample rate:
     * F_s_input.
     */
    float get_avg_period() const;

    /*!
     * \brief Get the instantaneous clock period estimate, T_inst.
     *
     * \details
     * Gets the instantaneous clock period estimate, T_inst,
     * in units of input stream sample clocks (so the instantaneous number of
     * input samples per output symbol, aka instantaneous samples/symbol).
     *
     * To convert to seconds, divide by the input stream sample rate:
     * F_s_input.
     */
    float get_inst_period() const;

    /*!
     * \brief Get the instantaneous clock phase estimate, tau.
     *
     * \details
     * Gets the instantaneous clock phase estimate, tau, in units of
     * input stream sample clocks.
     *
     * To convert to seconds, divide by the input stream sample rate:
     * F_s_input.
     *
     * To manually wrap, add or subtract a multiple of the estimate of the
     * average clock period, T_avg.
     *
     * To convert to a normalized (but not wrapped) clock phase estimate,
     * divide by the estimate of the average clock period, T_avg.
     * To further convert the normalized clock phase estimate to radians,
     * multiply the normalized clock phase estimate by 2*pi.
     */
    float get_phase() const;

    /*!
     * \brief Get the maximum average clock period estimate limit, T_avg_max.
     *
     * \details
     * See the documentation for set_max_avg_period() for more details.
     */
    float get_max_avg_period() const;

    /*!
     * \brief Get the minimum average clock period estimate limit, T_avg_min.
     *
     * \details
     * See the documentation for set_min_avg_period() for more details.
     */
    float get_min_avg_period() const;

    /*!
     * \brief Get the nominal average clock period, T_avg_nom.
     *
     * \details
     * Gets the nominal average clock period, T_avg_nom,
     * in units of input stream sample clocks (so the nominal average
     * number of input samples per output symbol, aka nominal samples/symbol).
     *
     * To convert to seconds, divide by the input stream sample rate:
     * F_s_input.
     */
    float get_nom_avg_period() const;
};

} /* namespace digital */
} /* namespace gr */

#endif /* INCLUDED_DIGITAL_CLOCK_TRACKING_LOOP_H */