Mercurial > octave-nkf

changeset 11085:2beacd515e09

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update docstrings for convolution family of functions (conv, conv2, fftconv)
author Rik <octave@nomad.inbox5.com>
date Thu, 07 Oct 2010 11:27:03 -0700
parents 0f6c5efce96e
children af03ff97df7b
files scripts/ChangeLog scripts/polynomial/conv.m scripts/signal/fftconv.m src/ChangeLog src/DLD-FUNCTIONS/conv2.cc
diffstat 5 files changed, 59 insertions(+), 28 deletions(-) [+]
line wrap: on
line diff
--- a/scripts/ChangeLog	Thu Oct 07 03:18:44 2010 -0400
+++ b/scripts/ChangeLog	Thu Oct 07 11:27:03 2010 -0700
@@ -1,3 +1,8 @@
+2010-10-07  Rik <octave@nomad.inbox5.com>
+
+	* scripts/polynomial/conv.m: Improve docstring.
+	* scripts/signal/fftconv.m: Improve docstring and error messages.
+
 2010-10-07  John W. Eaton  <jwe@octave.org>
 
 	* polynomial/conv.m: Handle optional third argument.  New
--- a/scripts/polynomial/conv.m	Thu Oct 07 03:18:44 2010 -0400
+++ b/scripts/polynomial/conv.m	Thu Oct 07 11:27:03 2010 -0700
@@ -18,28 +18,26 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {} conv (@var{a}, @var{b}, @var{shape})
+## @deftypefn  {Function File} {} conv (@var{a}, @var{b})
+## @deftypefnx {Function File} {} conv (@var{a}, @var{b}, @var{shape})
 ## Convolve two vectors.
 ##
-## @code{y = conv (a, b)} returns a vector of length equal to
-## @code{length (a) + length (b) - 1}.
-## If @var{a} and @var{b} are polynomial coefficient vectors, @code{conv}
-## returns the coefficients of the product polynomial.
+## @code{c = conv (@var{a}, @var{b})} returns a vector of length equal to
+## @code{length (@var{a}) + length (@var{b}) - 1}.
+## If @var{a} and @var{b} are the coefficient vectors of two polynomials, the
+## returned value is the coefficient vector of the product polynomial.
 ##
-## The optional @var{shape} parameter may be
+## The optional @var{shape} argument may be
 ##
 ## @table @asis
 ## @item @var{shape} = "full"
-## Return the full convolution.
+## Return the full convolution.  (default)
 ##
 ## @item @var{shape} = "same"
-## Return central part of the convolution with the same size as @var{a}.
+## Return the central part of the convolution with the same size as @var{a}.
 ## @end table
 ##
-## @noindent
-## By default, @var{shape} is @samp{"full"}.
-##
-## @seealso{deconv, poly, roots, residue, polyval, polyderiv, polyint}
+## @seealso{deconv, fftconv, conv2, poly}
 ## @end deftypefn
 
 ## Author: Tony Richardson <arichard@stark.cc.oh.us>
@@ -111,8 +109,7 @@
 %!  assert (conv (x, c), [3; 3; 3]);
 %!  assert (conv (y, c), [3, 3, 3]);
 %!  assert (conv (b, c), 6);
-%!error conv ([1, 2; 3, 4], 3);
-%!error conv (2, []);
+
 
 %!test
 %!  a = 1:10;
@@ -134,6 +131,12 @@
 %!test
 %!  a = 1:10;
 %!  b = 1:3;
+%!  assert (conv(a,b,"full"), conv(a,b))
+%!  assert (conv(b,a,"full"), conv(b,a))
+
+%!test
+%!  a = 1:10;
+%!  b = 1:3;
 %!  assert (conv(a,b,'same'), [4, 10, 16, 22, 28, 34, 40, 46, 52, 47])
 %!  assert (conv(b,a,'same'), [28, 34, 40])
 
@@ -142,3 +145,9 @@
 %!  b = (1:3).';
 %!  assert (size(conv(a,b)), [1, numel(a)+numel(b)-1])
 %!  assert (size(conv(b,a)), [1, numel(a)+numel(b)-1])
+
+%% Test input validation
+%!error conv (1);
+%!error conv (1,2,3,4);
+%!error conv ([1, 2; 3, 4], 3);
+%!error conv (2, []);
--- a/scripts/signal/fftconv.m	Thu Oct 07 03:18:44 2010 -0400
+++ b/scripts/signal/fftconv.m	Thu Oct 07 11:27:03 2010 -0700
@@ -18,14 +18,18 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {} fftconv (@var{a}, @var{b}, @var{n})
-## Return the convolution of the vectors @var{a} and @var{b}, as a vector
-## with length equal to the @code{length (a) + length (b) - 1}.  If @var{a}
-## and @var{b} are the coefficient vectors of two polynomials, the returned
-## value is the coefficient vector of the product polynomial.
+## @deftypefn  {Function File} {} fftconv (@var{a}, @var{b})
+## @deftypefnx {Function File} {} fftconv (@var{a}, @var{b}, @var{n})
+## Convolve two vectors using the FFT for computation.
+## 
+## @code{c = fftconv (@var{a}, @var{b})} returns a vector of length equal to
+## @code{length (@var{a}) + length (@var{b}) - 1}.
+## If @var{a} and @var{b} are the coefficient vectors of two polynomials, the
+## returned value is the coefficient vector of the product polynomial.
 ##
 ## The computation uses the FFT by calling the function @code{fftfilt}.  If
 ## the optional argument @var{n} is specified, an N-point FFT is used.
+## @seealso{deconv, conv, conv2}
 ## @end deftypefn
 
 ## Author: KH <Kurt.Hornik@wu-wien.ac.at>
@@ -39,7 +43,7 @@
   endif
 
   if (! (isvector (a) && isvector (b)))
-    error ("fftconv: both a and b should be vectors");
+    error ("fftconv: both A and B must be vectors");
   endif
   la = length (a);
   lb = length (b);
@@ -53,10 +57,12 @@
       c = fftfilt (a, b);
     else
       if (! (isscalar (N)))
-        error ("fftconv: N has to be a scalar");
+        error ("fftconv: N must be a scalar");
       endif
       c = fftfilt (a, b, N);
     endif
   endif
 
 endfunction
+
+%% FIXME: Borrow tests from conv.m.  May need a tolerance on the assert comparison
--- a/src/ChangeLog	Thu Oct 07 03:18:44 2010 -0400
+++ b/src/ChangeLog	Thu Oct 07 11:27:03 2010 -0700
@@ -1,3 +1,7 @@
+2010-10-07  Rik <octave@nomad.inbox5.com>
+
+	* DLD-FUNCTIONS/conv2.cc (convn): Update docstring.  Add 1 new test.
+
 2010-10-07  John W. Eaton  <jwe@octave.org>
 
 	* DLD-FUNCTIONS/conv2.cc (convn): Style fixes.  Edit docstring.
--- a/src/DLD-FUNCTIONS/conv2.cc	Thu Oct 07 03:18:44 2010 -0400
+++ b/src/DLD-FUNCTIONS/conv2.cc	Thu Oct 07 11:27:03 2010 -0700
@@ -46,30 +46,37 @@
 
 %!assert (conv2 (1:3, 1:2, [1,2;3,4;5,6]),
 %!        [1,4,4;5,18,16;14,48,40;19,62,48;15,48,36;]);
+
+%!assert (conv2 (1:3, 1:2, [1,2;3,4;5,6], "full"),
+%!        conv2 (1:3, 1:2, [1,2;3,4;5,6]));
+
 */
 
 
 DEFUN_DLD (conv2, args, ,
   "-*- texinfo -*-\n\
-@deftypefn  {Loadable Function} {y =} conv2 (@var{a}, @var{b}, @var{shape})\n\
-@deftypefnx {Loadable Function} {y =} conv2 (@var{v1}, @var{v2}, @var{m}, @var{shape})\n\
-Return the 2-D convolution of @var{a} and @var{b} where the size\n\
-of @var{c} is given by\n\
+@deftypefn  {Loadable Function} {} conv2 (@var{a}, @var{b})\n\
+@deftypefnx {Loadable Function} {} conv2 (@var{v1}, @var{v2}, @var{m})\n\
+@deftypefnx {Loadable Function} {} conv2 (@dots{}, @var{shape})\n\
+Return the 2-D convolution of @var{a} and @var{b}.  The size of the result\n\
+is determined by the optional @var{shape} argument which takes the following\n\
+values\n\
 \n\
 @table @asis\n\
 @item @var{shape} = \"full\"\n\
-Return the full convolution.\n\
+Return the full convolution.  (default)\n\
 \n\
 @item @var{shape} = \"same\"\n\
-Return central part of the convolution with the same size as @var{a}.\n\
+Return the central part of the convolution with the same size as @var{a}.\n\
 \n\
 @item @var{shape} = \"valid\"\n\
 Return only the parts which do not include zero-padded edges.\n\
 @end table\n\
 \n\
-By default @var{shape} is @samp{\"full\"}.  When the third argument\n\
+When the third argument\n\
 is a matrix, return the convolution of the matrix @var{m} by the vector\n\
 @var{v1} in the column direction and by vector @var{v2} in the row direction\n\
+@seealso{conv, fftconv}\n\
 @end deftypefn")
 {
   octave_value retval;