From 9aa13e8cc6bc118b36a2b23f9a7142b589cb6fc9 Mon Sep 17 00:00:00 2001
From: mbe <marco.berzborn@akustik.rwth-aachen.de>
Date: Thu, 12 Jan 2017 17:51:43 +0100
Subject: [PATCH] added some more documentation to sph mimo simulation

---
 .../ita_sph_mimo_error_simulation.m           | 33 +++++++++++--------
 .../ita_sph_modal_strength.m                  | 18 +++++-----
 .../ita_sph_sampling_displacement.m           | 12 +++----
 3 files changed, 34 insertions(+), 29 deletions(-)

diff --git a/applications/SphericalHarmonics/ita_sph_mimo_error_simulation.m b/applications/SphericalHarmonics/ita_sph_mimo_error_simulation.m
index eee1379c..979af99c 100644
--- a/applications/SphericalHarmonics/ita_sph_mimo_error_simulation.m
+++ b/applications/SphericalHarmonics/ita_sph_mimo_error_simulation.m
@@ -1,18 +1,23 @@
 function varargout = ita_sph_mimo_error_simulation(varargin)
 %ITA_SPH_MIMO_ERROR_SIMULATION - Simulate aliasing and noise errors in
 %  spherical MIMO systems.
-%  This function 
+%  This function simulates the mismatch errors from noise, sampling dispacement and aliasing 
+%  for a MIMO system comprised of a spherical loudspeaker array and a spherical microphone
+%  array.
 %
 %  Syntax:
 %   itaResult = ita_sph_mimo_error_simulation(options)
 %
 %   Options (default):
-%           'opt1' (defaultopt1) : description
-%           'opt2' (defaultopt1) : description
-%           'opt3' (defaultopt1) : description
+%           'SNR'				(60)	: SNR at each transducer
+%           'nRuns'				(5)		: calculate average of nRuns number of source-receiver orientations
+%           'dirMeasurementFile' ( [] ) : Filename for a directivity file that is to be included
+%
+%  Directivity files need to be in hdf5 format. The name of data fields need to be 'fullDirRe' and 
+%  'fullDirIm' for the real and imaginary part respectively.
 %
 %  Example:
-%   audioObjOut = ita_sph_mimo_error_simulation(audioObjIn)
+%   [individualTerms, allTerms, totalError] = ita_sph_mimo_error_simulation(sourceParams, receiverParams, opts)
 %
 %  See also:
 %   ita_toolbox_gui, ita_read, ita_write, ita_generate
@@ -26,7 +31,7 @@ function varargout = ita_sph_mimo_error_simulation(varargin)
 % </ITA-Toolbox>
 
 
-% Author: Marco Berzborn -- Email: marco.berzborn@rwth-aachen.de
+% Author: Marco Berzborn -- Email: marco.berzborn@akustik.rwth-aachen.de
 % Created:  29-Mar-2016 
 
 
@@ -47,6 +52,7 @@ sArgs = struct('pos1_source','struct',...
                'dirMeasurementFile',[]);
 [source,receiver,sArgs] = ita_parse_arguments(sArgs,varargin);
 
+% save all struct fields as variables for speed improvements in the parfor loop
 receiverNmax = receiver.Nmax;
 receiverSampling = receiver.sampling;
 
@@ -74,7 +80,7 @@ simWNG = sArgs.simWNG;
 
 yMIMOgroundTruth = zeros(sArgs.nRuns,1,numel(kVec));
 
-
+% check if source and receiver sampling have a unique radius within a certain tolerance
 if numel(unique(sourceSampling.r)) > 1
     uniRSort = sort(unique(sourceSampling.r));
     if uniRSort(1) > uniRSort(end)*(1-2*eps) && uniRSort(end) < uniRSort(1)*(1+2*eps)
@@ -90,8 +96,10 @@ if numel(unique(receiverSampling.r)) > 1
     end
 end
 
+% include measured source directivity
 dirMeasurementFile = sArgs.dirMeasurementFile;
-%% separate error bounds
+
+% initialize constant variables
 receiverYalias = ita_sph_base(receiverSampling,receiverNmaxAlias);
 sourceYalias = ita_sph_base(sourceSampling,sourceNmaxAlias);
 sourceGalias = ita_sph_aperture_function_sla(sourceSampling,sourceNmaxAlias,sourcerMem);
@@ -100,11 +108,9 @@ sourceG = sourceGalias(:,1:(sourceNmax+1)^2);
 sourceY = sourceYalias(:,1:(sourceNmax+1)^2);
 receiverY = receiverYalias(:,1:(receiverNmax+1)^2);
 
-%% init
-% sma terms
+% declare non constant variables
 eMismatchReceiver = zeros(sArgs.nRuns,1,numel(freqVec));
 eAliasReceiver = zeros(sArgs.nRuns,1,numel(freqVec));
-% sla terms
 eMismatchSource = zeros(sArgs.nRuns,1,numel(freqVec));
 eAliasSource = zeros(sArgs.nRuns,1,numel(freqVec));
 elapsedTime = zeros(sArgs.nRuns,1);
@@ -185,6 +191,7 @@ for idxRun = 1:sArgs.nRuns
                     Msource = sourceB .* (sourceG.'.*sourceY');
                 end
             else
+				% include measured source directivity
                 dirMat = h5read(dirMeasurementFile,'/dir/fullRe',[1,1,idxFreq],[sourceSampling.nPoints,(sourceNmaxAlias+1)^2,1]) +...
                     1i* h5read(dirMeasurementFile,'/dir/fullIm',[1,1,idxFreq],[sourceSampling.nPoints,(sourceNmaxAlias+1)^2,1]);
                 Msource = dirMat(:,1:(sourceNmax+1)^2).';
@@ -235,8 +242,6 @@ for idxRun = 1:sArgs.nRuns
             end
         end
         
-        % alias error needed here since antialias bf needs them and parfor
-        % requires the variables to be initialized
         if simSMA
             if numel(unique(receiverSampling.r)) == 1
                 EreceiverAlias = receiverYalias*receiverBalias;
@@ -256,7 +261,7 @@ for idxRun = 1:sArgs.nRuns
             EsourceAlias = [];
         end
         
-        % just use random dnm for simulation
+        % use random weighting coefficients for simulation
         sourceLambda = sourceRandPattern / norm(sourceRandPattern) .* ita_sph_base(sourceLookDir,sourceNmax)' * 4*pi/(sourceNmax+1)^2;
         receiverLambda = receiverRandPattern / norm(receiverRandPattern) .* ita_sph_base(receiverLookDir,receiverNmax)' * 4*pi/(receiverNmax+1)^2;
         
diff --git a/applications/SphericalHarmonics/ita_sph_modal_strength.m b/applications/SphericalHarmonics/ita_sph_modal_strength.m
index 1d2226a1..0b5502e0 100644
--- a/applications/SphericalHarmonics/ita_sph_modal_strength.m
+++ b/applications/SphericalHarmonics/ita_sph_modal_strength.m
@@ -1,17 +1,19 @@
 function varargout = ita_sph_modal_strength(varargin)
-%ITA_SPH_MODAL_STRENGTH - +++ Short Description here +++
-%  This function ++++ FILL IN INFO HERE +++
+%ITA_SPH_MODAL_STRENGTH - Calculate the modal strength function for a spherical array
+%  This function calculates the modal strength for a plane wave incident 
+%  onto a spherical microphone aray. The output is a diagonal matrix if the sampling 
+%  has a unique radius. If not, the output is a matrix with full rank. In case the wave 
+%  number k is given as a vector the output is of size N x M x nBins.
 %
 %  Syntax:
-%   audioObjOut = ita_sph_modal_strength(audioObjIn, options)
+%   B = ita_sph_modal_strength(sampling, Nmax, k, 'rigid')
 %
 %   Options (default):
-%           'opt1' (defaultopt1) : description
-%           'opt2' (defaultopt1) : description
-%           'opt3' (defaultopt1) : description
+%           'transducer' (microphone)	: microphone or loudspeaker array
+%           'hankelKind' (2)			: choose kind of Hankel function
 %
 %  Example:
-%   audioObjOut = ita_sph_modal_strength(audioObjIn)
+%   B = ita_sph_modal_strength(sampling, Nmax, k, 'rigid')
 %
 %  See also:
 %   ita_toolbox_gui, ita_read, ita_write, ita_generate
@@ -25,7 +27,7 @@ function varargout = ita_sph_modal_strength(varargin)
 % </ITA-Toolbox>
 
 
-% Author: Marco Berzborn -- Email: marco.berzborn@rwth-aachen.de
+% Author: Marco Berzborn -- Email: marco.berzborn@akustik.rwth-aachen.de
 % Created:  26-Feb-2016 
 
 %% Initialization and Input Parsing
diff --git a/applications/SphericalHarmonics/ita_sph_sampling/ita_sph_sampling_displacement.m b/applications/SphericalHarmonics/ita_sph_sampling/ita_sph_sampling_displacement.m
index 24dd1249..8d393088 100644
--- a/applications/SphericalHarmonics/ita_sph_sampling/ita_sph_sampling_displacement.m
+++ b/applications/SphericalHarmonics/ita_sph_sampling/ita_sph_sampling_displacement.m
@@ -4,15 +4,13 @@ function varargout = ita_sph_sampling_displacement(varargin)
 %  positions taken from a given sampling grid
 %  
 %   Syntax:
-%   audioObjOut = ita_sph_sampling_displacement(audioObjIn, options)
+%   samplingDisplaced = ita_sph_sampling_displacement(sampling, opts)
 %
 %   Options (default):
-%           'opt1' (defaultopt1) : description
-%           'opt2' (defaultopt1) : description
-%           'opt3' (defaultopt1) : description
+%           'relativeError' ([0.1,0.1,0.1]) : relative displacement in percent/100
 %
 %  Example:
-%   audioObjOut = ita_sph_sampling_displacement(audioObjIn)
+%   samplingDisplaced = ita_sph_sampling_displacement(sampling, [0.01,0.01,0.01])
 %
 %  See also:
 %   ita_toolbox_gui, ita_read, ita_write, ita_generate
@@ -26,7 +24,7 @@ function varargout = ita_sph_sampling_displacement(varargin)
 % </ITA-Toolbox>
 
 
-% Author: Marco Berzborn -- Email: marco.berzborn@rwth-aachen.de
+% Author: Marco Berzborn -- Email: marco.berzborn@akustik.rwth-aachen.de
 % Created:  29-Mar-2016 
 
 
@@ -66,4 +64,4 @@ if sArgs.relativeError(:,1) == 0
 end
 
 varargout{1} = samplingError;
-end
\ No newline at end of file
+end
-- 
GitLab