one_pfb.m

%-----------------------------------------------------------------------------
%
% Copyright (C) 2016
% ASTRON (Netherlands Institute for Radio Astronomy) <http://www.astron.nl/>
% P.O.Box 2, 7990 AA Dwingeloo, The Netherlands
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <http://www.gnu.org/licenses/>.
%
%-----------------------------------------------------------------------------
% Author: W. Lubberhuizen, 2015 (top.m for LOFAR Station, uses classes)
%         Eric Kooistra, 2016 (for Apertif)
%
% Purpose : Model one PFB = PFIR + PFFT with real input:
%   1) to show the transfer function of a polyphase filterbank with real
%      input like the subband filterbank
%   2) to create reference data for HDL implementation in data/:
%
%    . PFIR coeffcients:                      one_pfb_m_pfir_coeff_fircls1_16taps_128points_16b.dat
%    . PFIR coeffcients, WG, PFIR, PFFT data: one_pfb_m_chirp_8b_16taps_128points_16b_16b.dat
%
% Description :
%
% * General
%   The data path (DP) is modelled per block of data. The block of data
%   are counted by the block sequence number that thus acts as a
%   timestamp. The data path consist of DSP functions. Each DSP
%   function expects normalized full scale input (range -1:1) and it also
%   normalized full scale output. Dependend on the tb.model_quantization
%   the DSP functions outputs floating point or fixed point data that is
%   quantized to the specified number of bits. The output full scale
%   range remains -1:1.
%
% * Subband filterbank transfer function
%   The real input implies that ctrl_pfft_subband.complex = false, and
%   that the filterbank outputs tb.nof_subbands, where tb.subband_fft_size
%   = tb.nof_complex*tb.nof_subbands.
%   The subband filterbank can use LOFAR settings (tb.model_filterbank =
%   'LOFAR' or 'free choice' settings. With 'free choice' the number of
%   subbands (tb.nof_subbands) and the quantization (tb.model_quantization)
%   are free to set.
%   Using a chirp via tb.chirp = 1 and ctrl_wg.df > 0 shows the transfer
%   function of the polyphase filterbank.
%   If tb.plot_per_block == 1 then the filterbank subband spectrum is
%   plotted per block, else it is only plotted as a subband spectrogram
%   image. Used tb.plot_per_block == 1 to debug the indexing in the
%   filterbank input, pfir and pfft chain. Especially the
%   flipud(ctrl_pfir_subband.coeff) is essential to have the indexing 
%   correct (see pfir.m).
%   The chirp frequency increments forever, so the filterbank output
%   sweeps from subband 0 up to fs/2, down to 0, up to fs/2, etc. For
%   chirp frequency between DC and fsub/2 the subband 0 output is irratic
%   between 1 and 0. For chirp frequency between fs/2-fsub/2 and fs/2 the
%   the subband 0 output is irratic but almost 0.
%   The PFIR can be bypassed using ctrl_pfir_subband.bypass = 0 to only
%   have the FFT in the filterbank. Without PFIR and frequency there is
%   aliasing on all subbands and no particular difference for frequencies
%   near DC or fs/2.
%   Towards fs/2 the WG sinusiod amplitude gets modulated more and more
%   due to that there are less and less samples per period. Hence within