octave_packages/communications-1.1.1/biterr.m

   1 ## Copyright (C) 2003 David Bateman
   2 ##
   3 ## This program is free software; you can redistribute it and/or modify it under
   4 ## the terms of the GNU General Public License as published by the Free Software
   5 ## Foundation; either version 3 of the License, or (at your option) any later
   6 ## version.
   7 ##
   8 ## This program is distributed in the hope that it will be useful, but WITHOUT
   9 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 ## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
  11 ## details.
  12 ##
  13 ## You should have received a copy of the GNU General Public License along with
  14 ## this program; if not, see <http://www.gnu.org/licenses/>.
  15
  16 ## -*- texinfo -*-
  17 ## @deftypefn {Function File} {[@var{num}, @var{rate}] = } biterr (@var{a},@var{b})
  18 ## @deftypefnx {Function File} {[@var{num}, @var{rate}] = } biterr (@var{...},@var{k})
  19 ## @deftypefnx {Function File} {[@var{num}, @var{rate}] = } biterr (@var{...},@var{flag})
  20 ## @deftypefnx {Function File} {[@var{num}, @var{rate} @var{ind}] = } biterr (@var{...})
  21 ##
  22 ## Compares two matrices and returns the number of bit errors and the bit
  23 ## error rate. The binary representations of the variables @var{a} and
  24 ## @var{b} are treated and @var{a} and @var{b} can be either:
  25 ##
  26 ## @table @asis
  27 ## @item Both matrices
  28 ## In this case both matrices must be the same size and then by default the
  29 ## the return values @var{num} and @var{rate} are the overall number of bit
  30 ## errors and the overall bit error rate.
  31 ## @item One column vector
  32 ## In this case the column vector is used for bit error comparision column-wise
  33 ## with the matrix. The returned values @var{num} and @var{rate} are then
  34 ## row vectors containing the num of bit errors and the bit error rate for
  35 ## each of the column-wise comparisons. The number of rows in the matrix
  36 ## must be the same as the length of the column vector
  37 ## @item One row vector
  38 ## In this case the row vector is used for bit error comparision row-wise
  39 ## with the matrix. The returned values @var{num} and @var{rate} are then
  40 ## column vectors containing the num of bit errors and the bit error rate for
  41 ## each of the row-wise comparisons. The number of columns in the matrix
  42 ## must be the same as the length of the row vector
  43 ## @end table
  44 ##
  45 ## This behaviour can be overridden with the variable @var{flag}. @var{flag}
  46 ## can take the value 'column-wise', 'row-wise' or 'overall'. A column-wise
  47 ## comparision is not possible with a row vector and visa-versa.
  48 ##
  49 ## By default the number of bits in each symbol is assumed to be give by the
  50 ## number required to represent the maximum value of @var{a} and @var{b}.
  51 ## The number of bits to represent a symbol can be overridden by the variable
  52 ## @var{k}.
  53 ## @end deftypefn
  54
  55 ## 2003 FEB 13
  56 ##   initial release
  57
  58 function [num, rate, ind] = biterr (a, b, varargin)
  59
  60   if ((nargin < 2) || (nargin > 4))
  61     usage ("[num rate ind] = biterr (a, b [,k [,flag]])");
  62   endif
  63
  64   if (ndims (a) > 2 || ndims (b) > 2)
  65     error ("biterr: a and b must have at most two dimensions");
  66   endif
  67
  68   if (any(any(isinf(a))) || any(any(isnan(a))) || any(any(isinf(b))) || ...
  69       any(any(isnan(b))) || !isreal(a) || !isreal(b) || ...
  70       any(any((floor(a)) != a)) || any(any((floor(b)) != b)) || ...
  71       any(any(a < 0)) || any(any(b < 0)))
  72     error ("biterr: a and b must contain only non-negative integers");
  73   endif
  74
  75   [ar,ac] = size(a);
  76   [br,bc] = size(b);
  77
  78   k = max([max(a(:)),max(b(:))]);
  79   m = 1;
  80   while (k > (2^m-1))
  81     m = m + 1;
  82   end
  83
  84   if ((ar == br) && (ac == bc))
  85     type = "matrix";
  86     flag = "overall";
  87     c = 1;
  88   elseif (any([ar,br] == 1))
  89     type = "row";
  90     flag = "row";
  91     if (ac != bc)
  92       error ("biterr: row-wise comparison must have the same number of columns in inputs");
  93     endif
  94     if (ar == 1)
  95       a = ones(br,1) * a;
  96     else
  97       b = ones(ar,1) * b;
  98     endif
  99   elseif (any([ac,bc] == 1))
 100     type = "column";
 101     flag = "column";
 102     if (ar != br)
 103       error ("biterr: column-wise comparison must have the same number of rows in inputs");
 104     endif
 105     if (ac == 1)
 106       a = a * ones(1,bc);
 107     else
 108       b = b * ones(1,ac);
 109     endif
 110   else
 111     error ("biterr: matrix sizes must match");
 112   endif
 113
 114   k = 0;
 115   for i =1:length(varargin)
 116     arg = varargin{i};
 117     if (ischar(arg))
 118       if (strcmp(arg,"row-wise"))
 119               if (strcmp(type,"column"))
 120                 error ("biterr: row-wise comparison not possible with column inputs");
 121               endif
 122               flag = "row";
 123       elseif (strcmp(arg,"column-wise"))
 124               if (strcmp(type,"row"))
 125                 error ("biterr: column-wise comparison not possible with row inputs");
 126               endif
 127               flag = "column";
 128       elseif (strcmp(arg,"overall"))
 129               flag = "overall";
 130       else
 131               error ("biterr: unrecognized string argument");
 132       endif
 133     else
 134       k = arg;
 135       if (k < m)
 136               error ("biterr: the symbol size is too small for largest element");
 137       endif
 138     endif
 139   end
 140
 141   if (k == 0)
 142     k = m;
 143   endif
 144
 145   ## Call the core error function to count the bit errors
 146   ind = __errcore__(a,b);
 147
 148   switch (flag)
 149     case 'row',
 150       if (strcmp(type,"matrix") && (ac == 1))
 151               num = ind;
 152       else
 153         num = sum(ind')';
 154       endif
 155       rate = num / k / max(ac,bc);
 156     case 'column',
 157       if (strcmp(type,"matrix") && (ar == 1))
 158               num = ind;
 159       else
 160               num = sum(ind);
 161       endif
 162       rate = num / k / max(ar,br);
 163     case 'overall',
 164       num = sum(sum(ind));
 165       rate = num / k / max(ar,br) / max(ac,bc);
 166     otherwise
 167       error("impossible");
 168   endswitch
 169
 170 endfunction