octave_packages/m/specfun/nchoosek.m

   1 ## Copyright (C) 2001-2012 Rolf Fabian and Paul Kienzle
   2 ## Copyright (C) 2008 Jaroslav Hajek
   3 ##
   4 ## This file is part of Octave.
   5 ##
   6 ## Octave is free software; you can redistribute it and/or modify it
   7 ## under the terms of the GNU General Public License as published by
   8 ## the Free Software Foundation; either version 3 of the License, or (at
   9 ## your option) any later version.
  10 ##
  11 ## Octave is distributed in the hope that it will be useful, but
  12 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 ## General Public License for more details.
  15 ##
  16 ## You should have received a copy of the GNU General Public License
  17 ## along with Octave; see the file COPYING.  If not, see
  18 ## <http://www.gnu.org/licenses/>.
  19
  20 ## -*- texinfo -*-
  21 ## @deftypefn  {Function File} {@var{c} =} nchoosek (@var{n}, @var{k})
  22 ## @deftypefnx {Function File} {@var{c} =} nchoosek (@var{set}, @var{k})
  23 ##
  24 ## Compute the binomial coefficient or all combinations of a set of items.
  25 ##
  26 ## If @var{n} is a scalar then calculate the binomial coefficient
  27 ## of @var{n} and @var{k} which is defined as
  28 ## @tex
  29 ## $$
  30 ##  {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
  31 ##                = {n! \over k! (n-k)!}
  32 ## $$
  33 ## @end tex
  34 ## @ifnottex
  35 ##
  36 ## @example
  37 ## @group
  38 ##  /   \
  39 ##  | n |    n (n-1) (n-2) @dots{} (n-k+1)       n!
  40 ##  |   |  = ------------------------- =  ---------
  41 ##  | k |               k!                k! (n-k)!
  42 ##  \   /
  43 ## @end group
  44 ## @end example
  45 ##
  46 ## @end ifnottex
  47 ## @noindent
  48 ## This is the number of combinations of @var{n} items taken in groups of
  49 ## size @var{k}.
  50 ##
  51 ## If the first argument is a vector, @var{set}, then generate all
  52 ## combinations of the elements of @var{set}, taken @var{k} at a time, with
  53 ## one row per combination.  The result @var{c} has @var{k} columns and
  54 ## @w{@code{nchoosek (length (@var{set}), @var{k})}} rows.
  55 ##
  56 ## For example:
  57 ##
  58 ## How many ways can three items be grouped into pairs?
  59 ##
  60 ## @example
  61 ## @group
  62 ## nchoosek (3, 2)
  63 ##    @result{} 3
  64 ## @end group
  65 ## @end example
  66 ##
  67 ## What are the possible pairs?
  68 ##
  69 ## @example
  70 ## @group
  71 ## nchoosek (1:3, 2)
  72 ##    @result{}  1   2
  73 ##        1   3
  74 ##        2   3
  75 ## @end group
  76 ## @end example
  77 ##
  78 ## @code{nchoosek} works only for non-negative, integer arguments.  Use
  79 ## @code{bincoeff} for non-integer and negative scalar arguments, or for
  80 ## computing many binomial coefficients at once with vector inputs
  81 ## for @var{n} or @var{k}.
  82 ##
  83 ## @seealso{bincoeff, perms}
  84 ## @end deftypefn
  85
  86 ## Author: Rolf Fabian  <fabian@tu-cottbus.de>
  87 ## Author: Paul Kienzle <pkienzle@users.sf.net>
  88 ## Author: Jaroslav Hajek
  89
  90 function A = nchoosek (v, k)
  91
  92   if (nargin != 2
  93       || !isnumeric (k) || !isnumeric (v)
  94       || !isscalar (k) || ! (isscalar (v) || isvector (v)))
  95     print_usage ();
  96   endif
  97   if (k < 0 || k != fix (k)
  98       || (isscalar (v) && (v < k || v < 0 || v != fix (v))))
  99     error ("nchoosek: args are non-negative integers with V not less than K");
 100   endif
 101
 102   n = length (v);
 103
 104   if (n == 1)
 105     ## Improve precision at next step.
 106     k = min (k, v-k);
 107     A = round (prod ((v-k+1:v)./(1:k)));
 108     if (A*2*k*eps >= 0.5)
 109       warning ("nchoosek", "nchoosek: possible loss of precision");
 110     endif
 111   elseif (k == 0)
 112     A = [];
 113   elseif (k == 1)
 114     A = v(:);
 115   elseif (k == n)
 116     A = v(:).';
 117   elseif (k > n)
 118     A = zeros (0, k, class (v));
 119   elseif (k == 2)
 120     ## Can do it without transpose.
 121     x = repelems (v(1:n-1), [1:n-1; n-1:-1:1]).';
 122     y = cat (1, cellslices (v(:), 2:n, n*ones (1, n-1)){:});
 123     A = [x, y];
 124   elseif (k < n)
 125     v = v(:).';
 126     A = v(k:n);
 127     l = 1:n-k+1;
 128     for j = 2:k
 129       c = columns (A);
 130       cA = cellslices (A, l, c*ones (1, n-k+1), 2);
 131       l = c-l+1;
 132       b = repelems (v(k-j+1:n-j+1), [1:n-k+1; l]);
 133       A = [b; cA{:}];
 134       l = cumsum (l);
 135       l = [1, 1 + l(1:n-k)];
 136     endfor
 137     clear cA b;
 138     A = A.';
 139   endif
 140 endfunction
 141
 142
 143 %!assert (nchoosek (80,10), bincoeff (80,10))
 144 %!assert (nchoosek(1:5,3), [1:3;1,2,4;1,2,5;1,3,4;1,3,5;1,4,5;2:4;2,3,5;2,4,5;3:5])
 145
 146 %% Test input validation
 147 %!warning nchoosek (100,45);
 148 %!error nchoosek ("100", 45)
 149 %!error nchoosek (100, "45")
 150 %!error nchoosek (100, ones (2,2))
 151 %!error nchoosek (repmat (100, [2 2]), 45)
 152 %!error nchoosek (100, -45)
 153 %!error nchoosek (100, 45.5)
 154 %!error nchoosek (100, 145)
 155 %!error nchoosek (-100, 45)
 156 %!error nchoosek (100.5, 45)
 157