octave_packages/specfun-1.1.0/multinom_exp.m

   1 %% Copyright (c) 2011 Jordi Gutiérrez Hermoso <jordigh@octave.org>
   2 %% Copyright (c) 2011 Juan Pablo Carbajal <carbajal@ifi.uzh.ch>
   3 %%
   4 %%    This program is free software: you can redistribute it and/or modify
   5 %%    it under the terms of the GNU General Public License as published by
   6 %%    the Free Software Foundation, either version 3 of the License, or
   7 %%    any later version.
   8 %%
   9 %%    This program is distributed in the hope that it will be useful,
  10 %%    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 %%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 %%    GNU General Public License for more details.
  13 %%
  14 %%    You should have received a copy of the GNU General Public License
  15 %%    along with this program. If not, see <http://www.gnu.org/licenses/>.
  16
  17 %% -*- texinfo -*-
  18 %% @deftypefn {Function File} {@var{alpha} =} multinom_exp (@var{m}, @var{n})
  19 %% @deftypefnx {Function File} {@var{alpha} =} multinom_exp (@var{m}, @var{n},@var{sort})
  20 %% Returns the exponents of the terms in the multinomial expansion
  21 %% @tex
  22 %% $$
  23 %% (x_1 + x_2 + ... + x_m).^n
  24 %% $$
  25 %% @end tex
  26 %% @ifnottex
  27 %%
  28 %% @example
  29 %% (x1 + x2 + ... + xm).^@var{n}
  30 %% @end example
  31 %%
  32 %% @end ifnottex
  33 %%
  34 %% For example, for m=2, n=3 the expansion has the terms
  35 %% @tex
  36 %% $$
  37 %% x1^3, x2^3, x1^2*x2, x1*x2^2
  38 %% $$
  39 %% @end tex
  40 %% @ifnottex
  41 %%
  42 %% @example
  43 %% x1^3, x2^3, x1^2*x2, x1*x2^2
  44 %% @end example
  45 %%
  46 %% @end ifnottex
  47 %%
  48 %% then @code{alpha = [3 0; 2 1; 1 2; 0 3]};
  49 %%
  50 %% The optional argument @var{sort} is passed to function @code{sort} to
  51 %% sort the exponents by the maximum degree.
  52 %% The example above calling @code{ multinom(m,n,"ascend")} produces
  53 %%
  54 %% @code{alpha = [2 1; 1 2; 3 0; 0 3]};
  55 %%
  56 %% calling @code{ multinom(m,n,"descend")} produces
  57 %%
  58 %% @code{alpha = [3 0; 0 3; 2 1; 1 2]};
  59 %%
  60 %% @seealso{multinom, multinom_coeff, sort}
  61 %% @end deftypefn
  62
  63 function alpha = multinom_exp(m, n, sortmethod)
  64
  65      %% This is standard stars and bars.
  66      numsymbols = m+n-1;
  67      stars = nchoosek (1:numsymbols, n);
  68
  69      %% Star labels minus their consecutive position becomes their index
  70      %% position!
  71      idx  = bsxfun (@minus, stars, [0:n-1]);
  72
  73      %% Manipulate indices into the proper shape for accumarray.
  74      nr   = size (idx, 1);
  75      a    = repmat ([1:nr], n, 1);
  76      b    = idx';
  77      idx  = [a(:), b(:)];
  78
  79      alpha = accumarray (idx, 1);
  80
  81      if nargin > 2
  82         [~, idx] = sort (max (alpha, [], 2), 1, sortmethod);
  83         alpha    = alpha(idx, :);
  84      end
  85 end
  86
  87 %!demo
  88 %! m=2;
  89 %! n=3;
  90 %! alpha = multinom_exp(m,n)
  91 %! alpha_asc = multinom_exp(m,n,'ascend')
  92 %! alpha_dec = multinom_exp(m,n,'descend')