# HG changeset patch # User Rik # Date 1286476023 25200 # Node ID 2beacd515e09d41cac8c82e7680e0080252ac848 # Parent 0f6c5efce96e590455b45df646af5cc7af80ab96 Update docstrings for convolution family of functions (conv, conv2, fftconv) diff --git a/scripts/ChangeLog b/scripts/ChangeLog --- a/scripts/ChangeLog +++ b/scripts/ChangeLog @@ -1,3 +1,8 @@ +2010-10-07 Rik + + * scripts/polynomial/conv.m: Improve docstring. + * scripts/signal/fftconv.m: Improve docstring and error messages. + 2010-10-07 John W. Eaton * polynomial/conv.m: Handle optional third argument. New diff --git a/scripts/polynomial/conv.m b/scripts/polynomial/conv.m --- a/scripts/polynomial/conv.m +++ b/scripts/polynomial/conv.m @@ -18,28 +18,26 @@ ## . ## -*- 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 @@ -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, []); diff --git a/scripts/signal/fftconv.m b/scripts/signal/fftconv.m --- a/scripts/signal/fftconv.m +++ b/scripts/signal/fftconv.m @@ -18,14 +18,18 @@ ## . ## -*- 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 @@ -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 diff --git a/src/ChangeLog b/src/ChangeLog --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,7 @@ +2010-10-07 Rik + + * DLD-FUNCTIONS/conv2.cc (convn): Update docstring. Add 1 new test. + 2010-10-07 John W. Eaton * DLD-FUNCTIONS/conv2.cc (convn): Style fixes. Edit docstring. diff --git a/src/DLD-FUNCTIONS/conv2.cc b/src/DLD-FUNCTIONS/conv2.cc --- a/src/DLD-FUNCTIONS/conv2.cc +++ b/src/DLD-FUNCTIONS/conv2.cc @@ -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;