classdef FFE_DCTracking < FFE_plain
    %FFE_DCTracking Plain FFE with the DC-tracking offset loop.
    %
    % This class reuses the plain FFE process idea and BER mu optimization,
    % but keeps only the DC-tracking path from the larger FFE class. A1, A2,
    % and delayed FFE tap-update buffers are intentionally excluded.

    properties
        dc_tracking_mu
        dc_tracking_adaptive_enabled
        dc_tracking_persistence_gain
        dc_tracking_power_exponent
        dc_tracking_buffer_len
        dc_tracking_mu_eff_max
        e_dc

        optimize_dc_tracking_params = 0
        dc_tracking_optimization
        dc_tracking_optimization_iter = 0
        dc_tracking_optimization_len
        dc_tracking_optimization_max_evals
        dc_tracking_optimization_delay_weight
        dc_tracking_optimization_smoothing_len
    end

    properties (Access = private)
        dc_tracking_mu_min = 1e-6
        dc_tracking_mu_max = 3e-1
        dc_tracking_mu_eff_min = 0
    end

    methods
        function obj = FFE_DCTracking(options)
            arguments(Input)
                options.sps = 2
                options.order = 15

                options.len_tr = 4096
                options.mu_tr = 0
                options.epochs_tr = 5

                options.adaption_technique adaption_method = adaption_method.lms
                options.dd_mode = 1
                options.mu_dd = 1e-5
                options.epochs_dd = 5
                options.dd_len_fraction = 1

                options.dc_tracking_mu = 0
                options.dc_tracking_adaptive_enabled = false
                options.dc_tracking_persistence_gain = 0
                options.dc_tracking_power_exponent = 2
                options.dc_tracking_buffer_len = 1
                options.dc_tracking_mu_eff_max = inf

                options.decide = false

                options.save_debug = 0
                options.optmize_mus = 0
                options.mu_optimization_len = 2^15
                options.plot_mu_optimization = 0
                options.mu_optimization_fignum = 3010
                options.optimize_dc_tracking_params = 0
                options.dc_tracking_optimization_len = 2^15
                options.dc_tracking_optimization_max_evals = 20
                options.dc_tracking_optimization_delay_weight = 1e-3
                options.dc_tracking_optimization_smoothing_len = 501
            end

            obj@FFE_plain( ...
                "sps",options.sps, ...
                "order",options.order, ...
                "len_tr",options.len_tr, ...
                "mu_tr",options.mu_tr, ...
                "epochs_tr",options.epochs_tr, ...
                "adaption_technique",options.adaption_technique, ...
                "dd_mode",options.dd_mode, ...
                "mu_dd",options.mu_dd, ...
                "epochs_dd",options.epochs_dd, ...
                "dd_len_fraction",options.dd_len_fraction, ...
                "decide",options.decide, ...
                "save_debug",options.save_debug, ...
                "optmize_mus",options.optmize_mus, ...
                "mu_optimization_len",options.mu_optimization_len, ...
                "plot_mu_optimization",options.plot_mu_optimization, ...
                "mu_optimization_fignum",options.mu_optimization_fignum);

            obj.dc_tracking_mu = options.dc_tracking_mu;
            obj.dc_tracking_adaptive_enabled = options.dc_tracking_adaptive_enabled;
            obj.dc_tracking_persistence_gain = options.dc_tracking_persistence_gain;
            obj.dc_tracking_power_exponent = options.dc_tracking_power_exponent;
            obj.dc_tracking_buffer_len = floor(options.dc_tracking_buffer_len);
            obj.dc_tracking_mu_eff_max = options.dc_tracking_mu_eff_max;
            obj.e_dc = 0;

            obj.optimize_dc_tracking_params = options.optimize_dc_tracking_params;
            obj.dc_tracking_optimization_len = options.dc_tracking_optimization_len;
            obj.dc_tracking_optimization_max_evals = max(1, ...
                floor(options.dc_tracking_optimization_max_evals));
            obj.dc_tracking_optimization_delay_weight = ...
                max(0,options.dc_tracking_optimization_delay_weight);
            obj.dc_tracking_optimization_smoothing_len = max(1, ...
                floor(options.dc_tracking_optimization_smoothing_len));

            assert(obj.dc_tracking_buffer_len >= 0);
        end

        function [X,Noi] = process(obj,X,D)
            X = X.normalize("mode","rms");
            obj.constellation = unique(D.signal);
            obj.resetTrackingState();

            if obj.optmize_mus
                obj.optimizeMus(X.signal,D.signal);
                obj.resetTrackingState();
            end

            if obj.optimize_dc_tracking_params
                obj.optimizeDcTrackingParams(X.signal,D.signal);
                obj.resetTrackingState();
            end

            training = true;
            showviz = false;
            obj.equalize(X.signal,D.signal,obj.mu_tr,obj.epochs_tr,obj.len_tr,training,showviz);
            obj.e_tr = obj.e;

            n = X.length;
            training = false;
            if obj.dd_mode
                [signal,decision] = obj.equalize(X.signal,D.signal,obj.mu_dd,obj.epochs_dd,n,training,showviz);
            else
                [signal,decision] = obj.equalize(X.signal,D.signal,0,1,n,training,showviz);
            end

            if obj.decide
                X.signal = decision;
            else
                X.signal = signal;
            end

            X.fs = D.fs;
            X = X.logbookentry([num2str(obj.order),' tap FFE DC tracking']);

            Noi = X - D;
        end

        function optimizeMus(obj,x,d)
            [x_opt,d_opt,N_opt] = obj.optimizationSignals(x,d);

            switch obj.adaption_technique
                case adaption_method.lms
                    mu_range = [1e-5, 1e-2];
                case adaption_method.nlms
                    mu_range = [1e-3, 5e-1];
                case adaption_method.rls
                    mu_range = [0.98, 0.99999];
                otherwise
                    builtin("error","FFE_DCTracking:InvalidAdaptionTechnique", ...
                        "Unsupported FFE adaption technique.");
            end

            vars = optimizableVariable("mu_tr",mu_range,"Transform","log");
            if obj.dd_mode
                vars = [vars, optimizableVariable("mu_dd",mu_range,"Transform","log")];
            end
            optimize_dc_tracking_mu = obj.dc_tracking_mu ~= 0 && ...
                ~obj.optimize_dc_tracking_params;
            if optimize_dc_tracking_mu
                vars = [vars, optimizableVariable("dc_tracking_mu",[1e-5,1e-1],"Transform","log")];
            end

            obj.mu_optimization_iter = 0;
            fprintf("FFE_DCTracking mu opt uses %d samples / %d symbols\n",N_opt,numel(d_opt));
            obj.mu_optimization = bayesopt(@(p)obj.muObjective(p,x_opt,d_opt),vars, ...
                "MaxObjectiveEvaluations",20, ...
                "AcquisitionFunctionName","expected-improvement-plus", ...
                "IsObjectiveDeterministic",false, ...
                "Verbose",0, ...
                "PlotFcn",[]);

            obj.mu_tr = obj.mu_optimization.XAtMinObjective.mu_tr;
            if obj.dd_mode
                obj.mu_dd = obj.mu_optimization.XAtMinObjective.mu_dd;
            end
            if optimize_dc_tracking_mu
                obj.dc_tracking_mu = obj.mu_optimization.XAtMinObjective.dc_tracking_mu;
            end

            if obj.dd_mode && optimize_dc_tracking_mu
                fprintf("\nFFE_DCTracking mu opt done: mu_tr=%9.3e, mu_dd=%9.3e, dc_tracking_mu=%9.3e, BER=%9.3e\n", ...
                    obj.mu_tr,obj.mu_dd,obj.dc_tracking_mu,obj.mu_optimization.MinObjective);
            elseif obj.dd_mode
                fprintf("\nFFE_DCTracking mu opt done: mu_tr=%9.3e, mu_dd=%9.3e, BER=%9.3e\n", ...
                    obj.mu_tr,obj.mu_dd,obj.mu_optimization.MinObjective);
            elseif optimize_dc_tracking_mu
                fprintf("\nFFE_DCTracking mu opt done: mu_tr=%9.3e, dc_tracking_mu=%9.3e, BER=%9.3e\n", ...
                    obj.mu_tr,obj.dc_tracking_mu,obj.mu_optimization.MinObjective);
            else
                fprintf("\nFFE_DCTracking mu opt done: mu_tr=%9.3e, BER=%9.3e\n", ...
                    obj.mu_tr,obj.mu_optimization.MinObjective);
            end

            if obj.plot_mu_optimization
                obj.plotMuOptimization();
            end
        end

        function optimizeDcTrackingParams(obj,x,d)
            [x_opt,d_opt,N_opt] = obj.optimizationSignals( ...
                x,d,obj.dc_tracking_optimization_len);

            vars = optimizableVariable( ...
                "dc_tracking_mu",[1e-5,1e-1],"Transform","log");
            initial_values = min(max(obj.dc_tracking_mu,1e-5),1e-1);
            initial_names = "dc_tracking_mu";
            if obj.dc_tracking_adaptive_enabled
                vars = [vars, ...
                    optimizableVariable("dc_tracking_persistence_gain",[0,2]), ...
                    optimizableVariable("dc_tracking_mu_eff_max",[1e-3,3e-1], ...
                    "Transform","log")];
                initial_values = [initial_values, ...
                    min(max(obj.dc_tracking_persistence_gain,0),2), ...
                    min(max(obj.dc_tracking_mu_eff_max,1e-3),3e-1)];
                initial_names = [initial_names, ...
                    "dc_tracking_persistence_gain", "dc_tracking_mu_eff_max"];
            end
            initial_x = array2table(initial_values, ...
                "VariableNames",cellstr(initial_names));

            obj.dc_tracking_optimization_iter = 0;
            fprintf("FFE_DCTracking DC opt uses fixed mu_tr=%9.3e, mu_dd=%9.3e on %d samples / %d symbols\n", ...
                obj.mu_tr,obj.mu_dd,N_opt,numel(d_opt));

            old_rng = rng;
            cleanup_rng = onCleanup(@()rng(old_rng));
            rng(42,"twister");
            obj.dc_tracking_optimization = bayesopt( ...
                @(p)obj.dcTrackingObjective(p,x_opt,d_opt),vars, ...
                "MaxObjectiveEvaluations",obj.dc_tracking_optimization_max_evals, ...
                "InitialX",initial_x, ...
                "AcquisitionFunctionName","expected-improvement-plus", ...
                "IsObjectiveDeterministic",true, ...
                "Verbose",0, ...
                "PlotFcn",[]);
            clear cleanup_rng

            best = obj.dc_tracking_optimization.XAtMinObjective;
            obj.dc_tracking_mu = best.dc_tracking_mu;
            if obj.dc_tracking_adaptive_enabled
                obj.dc_tracking_persistence_gain = ...
                    best.dc_tracking_persistence_gain;
                obj.dc_tracking_mu_eff_max = best.dc_tracking_mu_eff_max;
                fprintf("\nFFE_DCTracking DC opt done: dc_tracking_mu=%9.3e, persistence_gain=%6.3f, mu_eff_max=%9.3e, objective=%9.3e\n", ...
                    obj.dc_tracking_mu,obj.dc_tracking_persistence_gain, ...
                    obj.dc_tracking_mu_eff_max, ...
                    obj.dc_tracking_optimization.MinObjective);
            else
                fprintf("\nFFE_DCTracking DC opt done: dc_tracking_mu=%9.3e, objective=%9.3e\n", ...
                    obj.dc_tracking_mu,obj.dc_tracking_optimization.MinObjective);
            end
        end

        function objective = muObjective(obj,params,x,d)
            old_state = obj.captureTrackingObjectiveState();
            cleanup = onCleanup(@()obj.restoreTrackingObjectiveState(old_state));

            obj.save_debug = 0;
            if any(strcmp(params.Properties.VariableNames,"dc_tracking_mu"))
                obj.dc_tracking_mu = params.dc_tracking_mu;
            end
            obj.resetTrackingState();

            N_tr = min(obj.len_tr,numel(x));
            obj.equalize(x,d,params.mu_tr,obj.epochs_tr,N_tr,true,false);
            if obj.dd_mode
                [signal,~] = obj.equalize(x,d,params.mu_dd,obj.epochs_dd,numel(x),false,false);
            else
                [signal,~] = obj.equalize(x,d,0,1,numel(x),false,false);
            end

            [ber,errors] = obj.berObjective(signal,d);
            objective = ber;
            if ~isfinite(objective)
                objective = inf;
            end

            obj.mu_optimization_iter = obj.mu_optimization_iter + 1;
            has_dc_tracking_mu = any(strcmp(params.Properties.VariableNames,"dc_tracking_mu"));
            if obj.dd_mode && has_dc_tracking_mu
                fprintf("\rFFE_DCTracking mu opt %02d: mu_tr=%9.3e, mu_dd=%9.3e, dc_tracking_mu=%9.3e, BER=%9.3e, errors=%d", ...
                    obj.mu_optimization_iter,params.mu_tr,params.mu_dd,params.dc_tracking_mu,ber,errors);
            elseif obj.dd_mode
                fprintf("\rFFE_DCTracking mu opt %02d: mu_tr=%9.3e, mu_dd=%9.3e, BER=%9.3e, errors=%d", ...
                    obj.mu_optimization_iter,params.mu_tr,params.mu_dd,ber,errors);
            elseif has_dc_tracking_mu
                fprintf("\rFFE_DCTracking mu opt %02d: mu_tr=%9.3e, dc_tracking_mu=%9.3e, BER=%9.3e, errors=%d", ...
                    obj.mu_optimization_iter,params.mu_tr,params.dc_tracking_mu,ber,errors);
            else
                fprintf("\rFFE_DCTracking mu opt %02d: mu_tr=%9.3e, BER=%9.3e, errors=%d", ...
                    obj.mu_optimization_iter,params.mu_tr,ber,errors);
            end

            clear cleanup
        end

        function objective = dcTrackingObjective(obj,params,x,d)
            old_state = obj.captureTrackingObjectiveState();
            cleanup = onCleanup(@()obj.restoreTrackingObjectiveState(old_state));

            obj.applyDcTrackingObjectiveParams(params);
            obj.save_debug = 1;
            obj.resetTrackingState();

            N_tr = min(obj.len_tr,numel(x));
            obj.equalize(x,d,obj.mu_tr,obj.epochs_tr,N_tr,true,false);
            if obj.dd_mode
                [signal,~] = obj.equalize( ...
                    x,d,obj.mu_dd,obj.epochs_dd,numel(x),false,false);
            else
                [signal,~] = obj.equalize(x,d,0,1,numel(x),false,false);
            end

            [ber,errors] = obj.berObjective(signal,d);
            [delay_symbols,delay_corr] = obj.dcTrackingDelayObjective(signal,d);
            delay_penalty = obj.dc_tracking_optimization_delay_weight * ...
                abs(delay_symbols) / max(numel(d),1);
            objective = ber + delay_penalty;
            if ~isfinite(objective)
                objective = inf;
            end

            obj.dc_tracking_optimization_iter = ...
                obj.dc_tracking_optimization_iter + 1;
            if obj.dc_tracking_adaptive_enabled
                fprintf("\rFFE_DCTracking DC opt %02d: dc_tracking_mu=%9.3e, persistence_gain=%6.3f, mu_eff_max=%9.3e, BER=%9.3e, delay=%7.0f, corr=%6.3f, obj=%9.3e, errors=%d", ...
                    obj.dc_tracking_optimization_iter,params.dc_tracking_mu, ...
                    params.dc_tracking_persistence_gain, ...
                    params.dc_tracking_mu_eff_max,ber,delay_symbols,delay_corr, ...
                    objective,errors);
            else
                fprintf("\rFFE_DCTracking DC opt %02d: dc_tracking_mu=%9.3e, BER=%9.3e, delay=%7.0f, corr=%6.3f, obj=%9.3e, errors=%d", ...
                    obj.dc_tracking_optimization_iter,params.dc_tracking_mu, ...
                    ber,delay_symbols,delay_corr,objective,errors);
            end

            clear cleanup
        end

        function [y,d_hat] = equalize(obj,x,d,mu,epochs,N,training,showviz)
            arguments
                obj
                x
                d
                mu
                epochs
                N
                training
                showviz
            end

            unused_showviz = showviz; %#ok<NASGU>
            x = x(:);
            d = d(:);
            N = obj.validSampleLength(N,x,d);
            n_symbols = N / obj.sps;
            y = zeros(n_symbols,1);
            d_hat = zeros(n_symbols,1);

            if n_symbols == 0
                return
            end

            if isempty(obj.constellation)
                obj.constellation = unique(d);
            end
            decision_constellation = obj.constellation(:);

            x = [zeros(floor(obj.order/2),1); x; zeros(obj.order,1)];
            lambda = mu;
            mask = ones(obj.order,1);
            maincursor_pos = ceil(length(obj.e)/2);
            adaption_code = obj.adaptionCode();
            adaption_is_rls = adaption_code == 3;

            if mu == 0 || (~obj.dd_mode && ~training)
                epochs = 1;
            end

            dc_tracking_mu_eff_min = obj.dc_tracking_mu_eff_min;
            dc_tracking_mu_eff_max = obj.dc_tracking_mu_eff_max;
            dc_tracking_persistence_gain = 0;
            if obj.dc_tracking_adaptive_enabled
                dc_tracking_persistence_gain = obj.dc_tracking_persistence_gain;
            end
            dc_tracking_enabled = obj.dc_tracking_mu ~= 0;
            if dc_tracking_enabled
                obj.dc_tracking_mu = min(max(obj.dc_tracking_mu, ...
                    obj.dc_tracking_mu_min),obj.dc_tracking_mu_max);
            end
            dc_tracking_mu = obj.dc_tracking_mu;
            dc_tracking_use_persistence = dc_tracking_persistence_gain > 0;
            dc_tracking_base_mu_eff = min(max(dc_tracking_mu, ...
                dc_tracking_mu_eff_min),dc_tracking_mu_eff_max);
            dc_buffer_enabled = dc_tracking_enabled && obj.dc_tracking_buffer_len > 1;
            if dc_buffer_enabled
                dc_tracking_err_buffer = NaN(obj.dc_tracking_buffer_len,1);
                dc_tracking_err_buffer_pos = 0;
                dc_tracking_err_sum = 0;
                dc_tracking_abs_err_sum = 0;
                dc_tracking_valid_count = 0;
            else
                dc_tracking_err_buffer = [];
                dc_tracking_err_buffer_pos = 0;
                dc_tracking_err_sum = 0;
                dc_tracking_abs_err_sum = 0;
                dc_tracking_valid_count = 0;
            end

            debug_enabled = obj.save_debug;
            if debug_enabled
                obj.initializeTrackingDebug(n_symbols,training);
            end

            for epoch = 1:epochs
                symbol = 0;
                for sample = 1:obj.sps:N
                    symbol = symbol + 1;
                    grad = zeros(obj.order,1);
                    update = zeros(obj.order,1);
                    weight = 0;
                    dc_tracking_mu_eff = 0;

                    U = x(obj.order+sample-1:-1:sample);
                    y(symbol,1) = obj.e_dc + (obj.e.*mask).' * U;

                    if training
                        d_hat(symbol,1) = d(symbol);
                    else
                        [~,symbol_idx] = min(abs(y(symbol) - decision_constellation));
                        d_hat(symbol,1) = decision_constellation(symbol_idx);
                    end

                    err = d_hat(symbol) - y(symbol);

                    switch adaption_code
                        case 1
                            weight = mu / ((U.'*U) + eps);
                            grad = err * U;
                            update = grad * weight;

                        case 2
                            weight = mu;
                            grad = err * U;
                            update = grad * weight;

                        case 3
                            denom = lambda + U.' * obj.P * U;
                            k = (obj.P * U) / denom;
                            update = k * err;
                    end

                    obj.e = obj.e + update;

                    if adaption_is_rls
                        obj.P = (1/lambda) * (obj.P - k * (U.' * obj.P));
                    end

                    if dc_tracking_enabled
                        [obj.e_dc,dc_tracking_mu_eff,dc_tracking_err_buffer, ...
                            dc_tracking_err_buffer_pos,dc_tracking_err_sum, ...
                            dc_tracking_abs_err_sum,dc_tracking_valid_count] = ...
                            obj.updateDcTracking( ...
                            err,dc_tracking_mu,dc_tracking_base_mu_eff, ...
                            dc_tracking_persistence_gain,dc_tracking_use_persistence, ...
                            dc_buffer_enabled,dc_tracking_mu_eff_min,dc_tracking_mu_eff_max, ...
                            symbol,dc_tracking_err_buffer,dc_tracking_err_buffer_pos, ...
                            dc_tracking_err_sum,dc_tracking_abs_err_sum, ...
                            dc_tracking_valid_count);
                    end

                    if debug_enabled && epoch == epochs
                        error_power = err * err';
                        update_power = update.'*update ./ (sqrt((obj.e.'*obj.e) / obj.order) + eps);
                        obj.debug_struct.error(1,symbol) = error_power;
                        obj.debug_struct.main_cursor(1,symbol) = abs(obj.e(maincursor_pos));
                        obj.debug_struct.mu_nlms(1,symbol) = weight;
                        obj.debug_struct.update_gradient(1,symbol) = grad.'*grad;
                        obj.debug_struct.dc_tracking_mu_eff(1,symbol) = dc_tracking_mu_eff;
                        obj.debug_struct.dc_tracking_est(1,symbol) = obj.e_dc;

                        if training
                            obj.debug_struct.error_tr(1,symbol) = error_power;
                            obj.debug_struct.update_tr(1,symbol) = update_power;
                        else
                            obj.debug_struct.error_dd(1,symbol) = error_power;
                            obj.debug_struct.update(1,symbol) = update_power;
                        end
                    end
                end
            end
        end
    end

    methods (Access = private)
        function resetTrackingState(obj)
            obj.e = zeros(obj.order,1);
            obj.e_tr = zeros(obj.order,1);
            obj.error = 0;
            obj.e_dc = 0;
            obj.P = (1/0.05) * eye(obj.order);
            obj.debug_struct = struct();
        end

        function state = captureTrackingObjectiveState(obj)
            state.e = obj.e;
            state.e_tr = obj.e_tr;
            state.error = obj.error;
            state.e_dc = obj.e_dc;
            state.P = obj.P;
            state.save_debug = obj.save_debug;
            state.debug_struct = obj.debug_struct;
            state.dc_tracking_mu = obj.dc_tracking_mu;
            state.dc_tracking_persistence_gain = ...
                obj.dc_tracking_persistence_gain;
            state.dc_tracking_mu_eff_max = obj.dc_tracking_mu_eff_max;
        end

        function restoreTrackingObjectiveState(obj,state)
            obj.e = state.e;
            obj.e_tr = state.e_tr;
            obj.error = state.error;
            obj.e_dc = state.e_dc;
            obj.P = state.P;
            obj.save_debug = state.save_debug;
            obj.debug_struct = state.debug_struct;
            obj.dc_tracking_mu = state.dc_tracking_mu;
            obj.dc_tracking_persistence_gain = ...
                state.dc_tracking_persistence_gain;
            obj.dc_tracking_mu_eff_max = state.dc_tracking_mu_eff_max;
        end

        function applyDcTrackingObjectiveParams(obj,params)
            var_names = string(params.Properties.VariableNames);
            if any(var_names == "dc_tracking_mu")
                obj.dc_tracking_mu = params.dc_tracking_mu;
            end
            if any(var_names == "dc_tracking_persistence_gain")
                obj.dc_tracking_persistence_gain = ...
                    params.dc_tracking_persistence_gain;
            end
            if any(var_names == "dc_tracking_mu_eff_max")
                obj.dc_tracking_mu_eff_max = params.dc_tracking_mu_eff_max;
            end
        end

        function [delay_symbols,delay_corr] = ...
                dcTrackingDelayObjective(obj,signal,d)
            delay_symbols = 0;
            delay_corr = 0;
            if ~isfield(obj.debug_struct,"dc_tracking_est") || ...
                    isempty(obj.debug_struct.dc_tracking_est)
                return
            end

            smooth_len = obj.dc_tracking_optimization_smoothing_len;
            dc_tracking_est_s = movmean( ...
                obj.debug_struct.dc_tracking_est(:),smooth_len,"omitnan");
            avg_lvl_dc = obj.averageLevelTrace(signal,d,smooth_len);

            xcorr_len = min(numel(dc_tracking_est_s),numel(avg_lvl_dc));
            if xcorr_len < 2
                return
            end

            inv_dc_xcorr = -dc_tracking_est_s(1:xcorr_len);
            avg_lvl_xcorr = avg_lvl_dc(1:xcorr_len);
            inv_dc_xcorr = fillmissing( ...
                inv_dc_xcorr,"linear","EndValues","nearest");
            avg_lvl_xcorr = fillmissing( ...
                avg_lvl_xcorr,"linear","EndValues","nearest");
            inv_dc_xcorr = inv_dc_xcorr - mean(inv_dc_xcorr,"omitnan");
            avg_lvl_xcorr = avg_lvl_xcorr - mean(avg_lvl_xcorr,"omitnan");

            if rms(inv_dc_xcorr) <= eps || rms(avg_lvl_xcorr) <= eps
                return
            end

            [dc_level_xcorr,dc_level_lags] = xcorr( ...
                inv_dc_xcorr,avg_lvl_xcorr,"coeff");
            [delay_corr,delay_idx] = max(dc_level_xcorr);
            delay_symbols = dc_level_lags(delay_idx);
            if ~isfinite(delay_corr)
                delay_corr = 0;
                delay_symbols = 0;
            end
        end

        function avg_lvl_dc = averageLevelTrace(obj,signal,d,smooth_len)
            signal = signal(:);
            d = d(:);
            n_symbols = min(numel(signal),numel(d));
            signal = signal(1:n_symbols);
            d = d(1:n_symbols);
            levels = unique(d);
            avg_for_lvl = NaN(numel(levels),n_symbols);

            for level_idx = 1:numel(levels)
                level_mask = d == levels(level_idx);
                level_samples = signal(level_mask);
                if isempty(level_samples)
                    continue
                end

                smooth_window = min(smooth_len,numel(level_samples));
                avg_for_lvl(level_idx,level_mask) = movmean( ...
                    level_samples,smooth_window,"omitnan","Endpoints","shrink");
                avg_for_lvl(level_idx,:) = obj.interpolateMissingAverage( ...
                    avg_for_lvl(level_idx,:));
            end

            avg_lvl_dc = mean(avg_for_lvl,1,"omitnan").';
        end

        function level_average = interpolateMissingAverage(~,level_average)
            valid_samples = isfinite(level_average);
            if nnz(valid_samples) == 0
                return
            elseif nnz(valid_samples) == 1
                level_average(:) = level_average(valid_samples);
                return
            end

            t = 1:numel(level_average);
            level_average(~valid_samples) = interp1( ...
                t(valid_samples),level_average(valid_samples), ...
                t(~valid_samples),"linear","extrap");
        end

        function N = validSampleLength(obj,N,x,d)
            N_available = min(numel(x),numel(d) * obj.sps);
            N = min(N,N_available);
            N = obj.sps * floor(N / obj.sps);
            N = max(0,N);
        end

        function adaption_code = adaptionCode(obj)
            if obj.adaption_technique == adaption_method.nlms
                adaption_code = 1;
            elseif obj.adaption_technique == adaption_method.lms
                adaption_code = 2;
            elseif obj.adaption_technique == adaption_method.rls
                adaption_code = 3;
            else
                builtin("error","FFE_DCTracking:InvalidAdaptionTechnique", ...
                    "Unsupported FFE adaption technique.");
            end
        end

        function initializeTrackingDebug(obj,n_symbols,training)
            obj.debug_struct.error = NaN(1,n_symbols);
            obj.debug_struct.error_first_epoch = NaN(1,n_symbols);
            obj.debug_struct.main_cursor = NaN(1,n_symbols);
            obj.debug_struct.mu_nlms = NaN(1,n_symbols);
            obj.debug_struct.update_gradient = NaN(1,n_symbols);
            obj.debug_struct.dc_tracking_mu_eff = NaN(1,n_symbols);
            obj.debug_struct.dc_tracking_est = NaN(1,n_symbols);

            if training
                obj.debug_struct.error_tr = NaN(1,n_symbols);
                obj.debug_struct.update_tr = NaN(1,n_symbols);
            else
                obj.debug_struct.error_dd = NaN(1,n_symbols);
                obj.debug_struct.update = NaN(1,n_symbols);
            end
        end

        function [e_dc,mu_eff,err_buffer,err_buffer_pos,err_sum,abs_err_sum,valid_count] = ...
                updateDcTracking(obj,err_current,mu_dc,base_mu_eff,persistence_gain, ...
                use_persistence,buffer_enabled,mu_eff_min,mu_eff_max,symbol, ...
                err_buffer,err_buffer_pos,err_sum,abs_err_sum,valid_count)

            mu_eff = 0;
            e_dc = obj.e_dc;

            if buffer_enabled
                err_buffer_pos = err_buffer_pos + 1;
                if err_buffer_pos > obj.dc_tracking_buffer_len
                    err_buffer_pos = 1;
                end

                old_err = err_buffer(err_buffer_pos);
                if isfinite(old_err)
                    err_sum = err_sum - old_err;
                    valid_count = valid_count - 1;
                    if use_persistence
                        abs_err_sum = abs_err_sum - abs(old_err);
                    end
                end

                if isfinite(err_current)
                    err_buffer(err_buffer_pos) = err_current;
                    err_sum = err_sum + err_current;
                    valid_count = valid_count + 1;
                    if use_persistence
                        abs_err_sum = abs_err_sum + abs(err_current);
                    end
                else
                    err_buffer(err_buffer_pos) = NaN;
                end

                if mod(symbol,obj.dc_tracking_buffer_len) == 0
                    if valid_count == 0
                        err_mean = 0;
                        err_abs_mean = 0;
                    else
                        err_mean = err_sum / valid_count;
                        err_abs_mean = abs_err_sum / valid_count;
                    end

                    mu_eff = obj.effectiveDcMu(mu_dc,base_mu_eff,persistence_gain, ...
                        use_persistence,err_mean,err_abs_mean,mu_eff_min,mu_eff_max);
                    e_dc = e_dc + mu_eff * err_mean;
                end
            else
                if isfinite(err_current)
                    err_mean = err_current;
                    err_abs_mean = abs(err_current);
                else
                    err_mean = 0;
                    err_abs_mean = 0;
                end

                mu_eff = obj.effectiveDcMu(mu_dc,base_mu_eff,persistence_gain, ...
                    use_persistence,err_mean,err_abs_mean,mu_eff_min,mu_eff_max);
                e_dc = e_dc + mu_eff * err_mean;
            end
        end

        function mu_eff = effectiveDcMu(~,mu_dc,base_mu_eff,persistence_gain, ...
                use_persistence,err_mean,err_abs_mean,mu_eff_min,mu_eff_max)

            if use_persistence
                persistence_scale = abs(err_mean) / (err_abs_mean + eps);
                persistence_scale = min(max(persistence_scale,0),1);
                mu_eff = mu_dc * (1 + persistence_gain * persistence_scale);
                mu_eff = min(max(mu_eff,mu_eff_min),mu_eff_max);
            else
                mu_eff = base_mu_eff;
            end
        end
    end
end