tom@516: % Copyright 2012, Google, Inc.
dicklyon@523: % Author Richard F. Lyon
tom@516: %
tom@516: % This Matlab file is part of an implementation of Lyon's cochlear model:
tom@516: % "Cascade of Asymmetric Resonators with Fast-Acting Compression"
tom@516: % to supplement Lyon's upcoming book "Human and Machine Hearing"
tom@516: %
tom@516: % Licensed under the Apache License, Version 2.0 (the "License");
tom@516: % you may not use this file except in compliance with the License.
tom@516: % You may obtain a copy of the License at
tom@516: %
tom@516: %     http://www.apache.org/licenses/LICENSE-2.0
tom@516: %
tom@516: % Unless required by applicable law or agreed to in writing, software
tom@516: % distributed under the License is distributed on an "AS IS" BASIS,
tom@516: % WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
tom@516: % See the License for the specific language governing permissions and
tom@516: % limitations under the License.
tom@516: 
tom@516: function [naps, CF, decim_naps] = CARFAC_Run ...
tom@516:   (CF, input_waves, AGC_plot_fig_num)
dicklyon@523: % function [naps, CF, decim_naps] = CARFAC_Run ...
dicklyon@523: %   (CF, input_waves, AGC_plot_fig_num)
tom@516: % This function runs the CARFAC; that is, filters a 1 or more channel
tom@516: % sound input to make one or more neural activity patterns (naps).
tom@516: %
tom@516: % The CF struct holds the filterbank design and state; if you want to
tom@516: % break the input up into segments, you need to use the updated CF
tom@516: % to keep the state between segments.
tom@516: %
tom@516: % input_waves is a column vector if there's just one audio channel;
tom@516: % more generally, it has a row per time sample, a column per audio channel.
tom@516: %
tom@516: % naps has a row per time sample, a column per filterbank channel, and
tom@516: % a layer per audio channel if more than 1.
tom@516: % decim_naps is like naps but time-decimated by the int CF.decimation.
tom@516: %
tom@516: % the input_waves are assumed to be sampled at the same rate as the
tom@516: % CARFAC is designed for; a resampling may be needed before calling this.
tom@516: %
tom@516: % The function works as an outer iteration on time, updating all the
tom@516: % filters and AGC states concurrently, so that the different channels can
tom@516: % interact easily.  The inner loops are over filterbank channels, and
tom@516: % this level should be kept efficient.
tom@516: %
tom@516: % See other functions for designing and characterizing the CARFAC:
tom@516: % CF = CARFAC_Design(fs, CF_filter_params, CF_AGC_params, n_mics)
tom@516: % transfns = CARFAC_Transfer_Functions(CF, to_chans, from_chans)
tom@516: 
tom@516: [n_samp, n_mics] = size(input_waves);
tom@516: n_ch = CF.n_ch;
tom@516: 
tom@516: if nargin < 3
tom@516:   AGC_plot_fig_num = 0;
tom@516: end
tom@516: 
tom@516: if n_mics ~= CF.n_mics
tom@516:   error('bad number of input_waves channels passed to CARFAC_Run')
tom@516: end
tom@516: 
dicklyon@523: % fastest decimated rate determines some interp needed:
dicklyon@523: decim1 = CF.AGC_params.decimation(1);
tom@516: 
tom@516: naps = zeros(n_samp, n_ch, n_mics);
dicklyon@523: decim_k = 0;
dicklyon@523: k_NAP_decim = 0;
dicklyon@523: NAP_decim = 8;
tom@516: if nargout > 2
tom@516:   % make decimated detect output:
dicklyon@523:   decim_naps = zeros(ceil(n_samp/NAP_decim), CF.n_ch, CF.n_mics);
tom@516: else
tom@516:   decim_naps = [];
tom@516: end
tom@516: 
tom@516: 
dicklyon@523: k_AGC = 0;
dicklyon@523: AGC_plot_decim = 16;  % how often to plot AGC state; TODO: use segments
tom@516: 
dicklyon@523: 
dicklyon@523: detects = zeros(n_ch, n_mics);
tom@516: for k = 1:n_samp
dicklyon@523:   CF.k_mod_decim = mod(CF.k_mod_decim + 1, decim1);  % global time phase
dicklyon@523:   k_NAP_decim = mod(k_NAP_decim + 1, NAP_decim);  % phase of decimated nap
tom@516:   % at each time step, possibly handle multiple channels
tom@516:   for mic = 1:n_mics
tom@516:     [filters_out, CF.filter_state(mic)] = CARFAC_FilterStep( ...
tom@516:       input_waves(k, mic), CF.filter_coeffs, CF.filter_state(mic));
dicklyon@523:     
tom@516:     % update IHC state & output on every time step, too
tom@516:     [ihc_out, CF.IHC_state(mic)] = CARFAC_IHCStep( ...
tom@516:       filters_out, CF.IHC_coeffs, CF.IHC_state(mic));
dicklyon@523:     
dicklyon@523:     detects(:, mic) = ihc_out;  % for input to AGC, and out to SAI
dicklyon@523:     
tom@516:     naps(k, :, mic) = ihc_out;  % output to neural activity pattern
dicklyon@523:     
tom@516:   end
dicklyon@523:   if ~isempty(decim_naps) && (k_NAP_decim == 0)
dicklyon@523:     decim_k = decim_k + 1;   % index of decimated NAP
dicklyon@523:     for mic = 1:n_mics
dicklyon@523:       decim_naps(decim_k, :, mic) = CF.IHC_state(mic).ihc_accum / ...
dicklyon@523:         NAP_decim;  % for cochleagram
dicklyon@523:       CF.IHC_state(mic).ihc_accum = zeros(n_ch,1);
tom@516:     end
dicklyon@523:   end
dicklyon@523:   % run the AGC update step, taking input from IHC_state, decimating
dicklyon@523:   % internally, all mics at once due to mixing across them:
dicklyon@523:   [CF.AGC_state, updated] = ...
dicklyon@523:     CARFAC_AGCStep(CF.AGC_coeffs, detects, CF.AGC_state);
dicklyon@523:   
dicklyon@523:   % connect the feedback from AGC_state to filter_state when it updates
dicklyon@523:   if updated
tom@516:     for mic = 1:n_mics
dicklyon@523:       new_damping = CF.AGC_state(mic).AGC_memory(:, 1);  % stage 1 result
tom@516:       % set the delta needed to get to new_damping:
dicklyon@523:       % TODO: update this to use da and dc instead of dr maybe?
tom@516:       CF.filter_state(mic).dzB_memory = ...
tom@516:         (new_damping - CF.filter_state(mic).zB_memory) ...
dicklyon@523:         / decim1;
tom@516:     end
tom@516:   end
dicklyon@523:   
dicklyon@523:   k_AGC = mod(k_AGC + 1, AGC_plot_decim);
dicklyon@523:   if AGC_plot_fig_num && k_AGC == 0
dicklyon@523:     figure(AGC_plot_fig_num); hold off; clf
dicklyon@523:     set(gca, 'Position', [.25, .25, .5, .5])
dicklyon@523:     
dicklyon@523:     maxsum = 0;
dicklyon@523:     for mic = 1:n_mics
dicklyon@523:       plot(CF.AGC_state(mic).AGC_memory(:, 1), 'k-', 'LineWidth', 1)
dicklyon@523:       maxes(mic) = max(CF.AGC_state(mic).AGC_memory(:));
dicklyon@523:       hold on
dicklyon@523:       stage1 = 4; % as opposed to stage
dicklyon@523:       for stage = 1:3;
dicklyon@523:         plot(2^(stage1-1) * (CF.AGC_state(mic).AGC_memory(:, stage) - ...
dicklyon@523:           2 * CF.AGC_state(mic).AGC_memory(:, stage+1)));
dicklyon@523:       end
dicklyon@523:       stage = 4;
dicklyon@523:       plot(2^(stage1-1) * CF.AGC_state(mic).AGC_memory(:, stage));
dicklyon@523:     end
dicklyon@523:     axis([0, CF.n_ch+1, -0.01, max(maxes) + 0.01]);
dicklyon@523:     drawnow
dicklyon@523:   end
dicklyon@523:   
tom@516: end
tom@516: