Add a function for computing binomial coefficients to the math module

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

BPO	35431
Nosy	@tim-one, @rhettinger, @mdickinson, @jwilk, @stevendaprano, @serhiy-storchaka, @MojoVampire, @pablogsal, @KellerFuchs, @FR4NKESTI3N, @Radcliffe
PRs	python/cpython#11018 python/cpython#11414 python/cpython#13725 python/cpython#13731 python/cpython#13734 python/cpython#13798 python/cpython#13801 python/cpython#13870 python/cpython#14125 python/cpython#14146 python/cpython#14226

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = 'https://github.com/rhettinger' closed_at = created_at = labels = ['type-feature', '3.8'] title = 'Add a function for computing binomial coefficients to the math module' updated_at = user = 'https://github.com/KellerFuchs' ``` bugs.python.org fields: ```python activity = actor = 'serhiy.storchaka' assignee = 'rhettinger' closed = True closed_date = closer = 'rhettinger' components = [] creation = creator = 'kellerfuchs' dependencies = [] files = [] hgrepos = [] issue_num = 35431 keywords = ['patch'] message_count = 85.0 messages = ['331251', '331255', '331256', '331257', '331280', '331281', '331293', '331295', '331296', '331308', '331309', '331312', '331318', '331323', '331325', '331335', '331336', '331337', '331339', '331369', '331402', '331743', '331748', '331859', '332817', '332826', '332838', '332844', '332933', '332957', '332960', '332987', '332988', '332990', '334457', '334458', '334460', '334461', '334474', '334493', '334494', '334499', '334501', '334502', '334683', '334684', '336384', '336458', '336750', '342253', '342257', '344154', '344155', '344165', '344170', '344176', '344186', '344199', '344218', '344219', '344221', '344229', '344230', '344231', '344232', '344235', '344236', '344239', '344243', '344257', '344258', '344292', '344366', '344370', '344371', '344375', '344414', '344420', '344436', '344448', '344450', '344452', '344531', '345860', '346328'] nosy_count = 11.0 nosy_names = ['tim.peters', 'rhettinger', 'mark.dickinson', 'jwilk', 'steven.daprano', 'serhiy.storchaka', 'josh.r', 'pablogsal', 'kellerfuchs', 'FR4NKESTI3N', 'David Radcliffe'] pr_nums = ['11018', '11414', '13725', '13731', '13734', '13798', '13801', '13870', '14125', '14146', '14226'] priority = 'normal' resolution = 'fixed' stage = 'resolved' status = 'closed' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue35431' versions = ['Python 3.8'] ```

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

A recuring pain point, for me and for many others who use Python for mathematical computations, is that the standard library does not provide a function for computing binomial coefficients.

I would like to suggest adding a function, in the math module, with the following signature:

binomial(n: Integral, k: Integral) -> Integral

A simple native Python implementation would be:

  from functools import reduce
  from math import factorial
  from numbers import Integral

  def binomial(n: Integral, k: Integral) -> Integral:
      if k < 0 or n < 0:
          raise ValueError("math.binomial takes non-negative parameters.")

      k = min(k, n-k)
      num, den = 1, 1
      for i in range(k):
          num = num * (n - i)
          den = den * (i + 1)

  return num//den

As far as I can tell, all of the math module is implemented in C, so this should be done in C too, but the implemented behaviour should be equivalent.

I will submit a Github pull request once I have a ready-to-review patch.

Not starting a PEP, per PEP-1:

Small enhancements or patches often don't need a PEP and can be injected into the Python development workflow with a patch submission to the Python issue tracker.

[stevendaprano]

You import reduce but never use it :-)

+1 for this, I certainly miss it too.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

Yes, that was a copypasta mistake (and I also import factorial needlessly) as the file I prototyped it in had some other code for testing my proposed implementation. :)

[rhettinger]

+1 I have wanted this a number of times.

FWIW, most recently I wrote it like this:

    def comb(n, r):
        'Equivalent to factorial(n) // (factorial(r) * factorial(n-r))'
        c = 1
        r = min(r, n-r)
        for i in range(1, r+1):
            c = c * (n - r + i) // i
        return c

I'm not sure is this is better than a single divide, but it kept the intermediate values from exploding in size, taking advantage of cancellation at each step.

Also, I'm not sure what the predominant choice for variable names should be, "n things taken r at a time" or "n things taken k at time".

Also, it's worth considering whether the function should be called "binomial", "choose", "combinations", or "comb". The word "binomial" seems too application specific but would make sense if we ever introduced a "multinomial" counterpart. The word "choose" is how we usually pronounce it. The word "combinations" fits nicely with the related counting functions, "combinations, permutations, and factorial". The word "comb" is short, works well with "perm" and "fact", and nicely differentiates itself as the integer counterparts of the combinatoric functions in the itertools module.

Wolfram uses both choose and Binomial[n,m] SciPy uses comb(n, k). Maple uses both numbcomb(n,m) and binomial(n,m). TeX uses {n \choose k}

[mdickinson]

For some ranges of inputs, it may make sense to use the apparently naive implementation factorial(n) // factorial(k) // factorial(n - k). The current factorial implementation is significantly optimised, and using it directly may be faster than using an iterative solution.

Here are some timings (Python 3.7.1, macOS 10.13), using Raymond's comb function from msg331257:

In [5]: %timeit comb(1000, 600) 186 µs ± 442 ns per loop (mean ± std. dev. of 7 runs, 10000 loops each)

In [6]: %timeit factorial(1000) // factorial(600) // factorial(400) 97.8 µs ± 256 ns per loop (mean ± std. dev. of 7 runs, 10000 loops each)

In [7]: %timeit factorial(1000) // (factorial(600) * factorial(400)) 91.1 µs ± 789 ns per loop (mean ± std. dev. of 7 runs, 10000 loops each)

But that's just one set of inputs, on one system; your results may vary.

[mdickinson]

There's also the question of what inputs should be considered valid: binomial(n, k) for k > n should either return 0 or be a ValueError, but which? Same question for k < 0. There's a symmetry argument for allowing k < 0 if you allow k > n, but I can't think of pragmatic reasons to allow k < 0, while allowing k > n does seem potentially useful.

Note that this needs fixing with both of the code snippets shown so far: they both return 1 for k > n.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

@Raymond Hettinger:

it's worth considering whether the function should be called "binomial", "choose", "combinations", or "comb"

Here goes the bike shed! :) Kidding, this is a pretty important ergonomics/discoverability concern, and I hadn't given it much thought yet.

I'd rather not call it comb, because it collides with a completely-unrelated English word, and it's not obvious what it stands for unless one already knows.

The word "combinations" fits nicely with the related counting functions, "combinations, permutations, and factorial".

That's a good point; math.permutations doesn't exist, but itertools.permutations does, so I would expect (by analogy) a “combinations” functions to produce all possible k-sized subsets (rather than counting them), and that's exactly what itertools.combinations does.

On the other hand, combinations and permutations are names that make it perhaps more obvious what is being counted, so perhaps math.{combinations,permutations} should be aliases for math.{binomial,factorial} ? Is the name collision with itertools a problem?

TL;DR: “binomial” is more consistent with the current naming in math and itertools, but perhaps it makes sense to introduce math.{combination,permutations} as aliases?

(Note that I used math.binomial as the name in the PR so far, but that's only because I needed a name, not because I consider the discussion ended.)

@Mark Dickinson:

The current factorial implementation is significantly optimised, and using it directly may be faster than using an iterative solution.

Yes, I avoided pushing specifically for a given algorithm (rather than getting upfront agreement on the functional behaviour) because the performance characteristics will likely be quite different once implemented in C in the math module.

(Unless I'm mistaken and there is a way to add pure-Python functions to the math module?)

binomial(n, k) for k > n should either return 0 or be a ValueError, but which?

From a mathematical standpoint, (n choose k) is defined for all non-negative k, n, with (n chooze k) = 0 when k>n or k=0.

It's necessary behaviour for the usual equations to hold (like (n + 1 choose k + 1) = (n choose k) + (n choose k + 1)). As such, I'd argue that returning 0 is both more likely to be the thing the user wants (as in, it's necessary behaviour for combinatorics) and easier to reason about.

Negative k and n, on the other hand, should clearly be a ValueError, and so should non-integers inputs; this is consistent with factorial's behaviour.

I started a pull request and (for now) only added tests which document that (proposed) behaviour, so we can more easily discuss whether that's what we want.

Note that this needs fixing with both of the code snippets shown so far: they both return 1 for k > n.

Yes :) I noticed last night, as I wrote Hypothesis tests for the snippet, but didn't think it was super important to send an updated version.

[serhiy-storchaka]

I think that it is better to add this function in a new module imath, which could contain other integer functions: factorial, gcs, as_integer_ration, isqrt, isprime, primes.

See https://mail.python.org/pipermail/python-ideas/2018-July/051917.html

[serhiy-storchaka]

Mathematically, binomial(n, k) for k > n is defined as 0.

[mdickinson]

Mathematically, binomial(n, k) for k > n is defined as 0.

It's not so clear cut. You can find different definitions out there. Knuth et. al., for example, in the book "Concrete Mathematics", extend the definition not just to negative k, but to negative n as well. Mathematicians aren't very good at agreeing on things. :-)

But that doesn't really matter: what we need to decide is what behaviour is useful for the users of the function.

[mdickinson]

@KellerFuchs:

From a mathematical standpoint, (n choose k) is defined for all non-negative k, n, with (n chooze k) = 0 when k>n or k=0.

You don't mean the "k=0" part of that, right?

[mdickinson]

One more decision that needs to be made: should the new function accept integer-valued floats? Or should any float input give a TypeError.

I'd personally prefer that floats not be accepted; I think this was a misfeature of factorial that we shouldn't compound.

[stevendaprano]

On Fri, Dec 07, 2018 at 12:04:44AM +0000, Raymond Hettinger wrote:

Also, I'm not sure what the predominant choice for variable names should be, "n things taken r at a time" or "n things taken k at time".

Also, it's worth considering whether the function should be called "binomial", "choose", "combinations", or "comb".

I've done a quick survey of some of the most common/popular scientific calculators:

TI Nspire TI-84 Plus Casio Classpad Casio FX-82AU Plus II

all call this nCr, and nPr for the permutation version. This matches the notation taught in secondary school maths classes in Australia. That's common and familiar notation for secondary school students, but personally I'm not super-keen on it.

For what its worth, the colour I prefer for this bikeshed are "comb" and "perm", which are the names used by the HP 48GX calculator. Second choice would be to spell the names out in full, "combinations" and "permutations".

[stevendaprano]

Mathematically, binomial(n, k) for k > n is defined as 0.

It's not so clear cut. You can find different definitions out there. Knuth et. al., for example, in the book "Concrete Mathematics", extend the definition not just to negative k, but to negative n as well. Mathematicians aren't very good at agreeing on things. :-)

I think the key word there is *extend*. To the degree that any mathematical definition is "obvious", the obvious definition for number of combinations ("n choose r") is going to be 1 for r == 0 and 0 for r > n.

However, I think that it is too easy to get the order of n and r (n and k) mixed up, and write combinations(5, 10) when you wanted to choose 5 from 10. I know I make that mistake on my calculator *all the time*, and so do my students, even with the nPr notation. So I recommend we raise ValueError for r > n.

[stevendaprano]

On Fri, Dec 07, 2018 at 01:37:36PM +0000, Mark Dickinson wrote:

I'd personally prefer that floats not be accepted;

Agreed. We can always add support for floats later, but its hard to remove it if it turns out to be problematic.

We ought to require n, r (or n, k) to be non-negative ints with 0 \<= r \<= n. Extending this to negative ints or floats is probably YAGNI, but if somebody does need it, they can request an enhancement in the future.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

@Serhiy Storchaka:

I think that it is better to add this function in a new module imath, which could contain other integer functions

imath is a fine idea, and you already started a discussion in python-ideas@, but it's a much bigger undertaking than just adding this one function, and you can move it there once imath happens. As such, I think it's out-of-scope in this issue.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

@Mark Dickinson:

You don't mean the "k=0" part of that, right?

Indeed not; the tests in the PR actually assert binomial(n, n) == binomial(n, 0) == 1.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

I'd personally prefer that floats not be accepted; I think this was a misfeature of factorial that we shouldn't compound.

OK; I only went with that because I assumed there were Good Reasons© that factorial did it, but if rejecting integral floats isn't going to be a controversial move I'm also in favor of it.

Updating the PR momentarily to check that binomial rejects floats.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

@Steven D'Aprano:

all call this nCr, and nPr for the permutation version. This matches the notation taught in secondary school maths classes in Australia. That's common and familiar notation for secondary school students, but personally I'm not super-keen on it.

It's also not universal; in my experience, most calculators are localized for a given market, and may use different notations (in particular, the notation for combinations/binomial numbers changes across countries).

[stevendaprano]

Brett, what was the purpose of the title change?

title: The math module should provide a function for computing binomial coefficients -> Add a function for computing binomial coefficients to the math module

[rhettinger]

For what its worth, the colour I prefer for this bikeshed are "comb" and "perm", which are the names used by the HP 48GX calculator. Second choice would be to spell the names out in full, "combinations" and "permutations".

+1 These would be my preferences as well :-)

[tim-one]

My two cents:

• Spell it comb(n, k).
• TypeError if args aren't ints.
• ValueError if not 0 \<= k \<= n.

Not concerned about speed. It's possible to do this with no divisions involving integers bigger than n and k(*), using O(k) space, but for "practical" arguments I bet that's slower than the dumbest possible loop.

(*) Sketch: make lists of the k numerators and k-1 denominators (skip 1). For each prime P \<= k, a modulus operation can determine the index of the first multiple of P in each list. For that, and for each P'th later list element, divide out the multiples of P, adding 1 to a running count for numerators, subtracting 1 for denominators, and reducing each list element by the Ps divided out. Then if the final P count isn't 0 (it will always be >= 0), append pow(P, count) to a list of factors. pow() is efficient.

After that, all the denominators will be reduced to 1, so can be ignored thereafter. It just remains to multiply all the reduced numerators and prime-power factors.

Catenate them all in a single list, heapify it (min heap), and so long as at least 2 factors remain pop the two smallest and push their product. This attempts to balance bit lengths of incoming factors, allowing close-to-best-case-for-it Karatsuba multiplication to kick in.

But that's nuts ;-) To get even nutsier, special-case P=2 to use shifts instead, skip adding pow(2, count) to the list of factors, and just shift left by the count at the end.

That said, even the "dumbest possible loop" may benefit in C by shifting out all trailing zeroes, multiplying/dividing only odd integers, and shifting left at the end.

[mdickinson]

[Tim]

My two cents:

• Spell it comb(n, k).
• TypeError if args aren't ints.
• ValueError if not 0 \<= k \<= n.

+1 to all of this.

[tim-one]

Just for fun, here's a gonzo implementation (without arg-checking) using ideas from the sketch. All factors of 2 are shifted out first, and all divisions are done before any multiplies.

For large arguments, this can run much faster than a dumb loop. For example, combp(10**100, 400) takes about a quarter the time of a dumb-loop divide-each-time-thru implementation.

    # Return number of trailing zeroes in `n`.
    def tzc(n):
        result = 0
        if n:
            mask = 1
            while n & mask == 0:
                result += 1
                mask <<= 1
        return result

    # Return exponent of prime `p` in prime factorization of
    # factorial(k).
    def facexp(k, p):
        result = 0
        k //= p
        while k:
            result += k
            k //= p
        return result

    def combp(n, k):
        from heapq import heappop, heapify, heapreplace

        if n-k < k:
            k = n-k
        if k == 0:
            return 1
        if k == 1:
            return n
        firstnum = n - k + 1
        nums = list(range(firstnum, n+1))
        assert len(nums) == k

        # Shift all factors of 2 out of numerators.
        shift2 = 0
        for i in range(firstnum & 1, k, 2):
            val = nums[i]
            c = tzc(val)
            assert c
            nums[i] = val >> c
            shift2 += c
        shift2 -= facexp(k, 2) # cancel all 2's in factorial(k)
        assert shift2 >= 0

        # Any prime generator is fine here.  `k` can't be
        # huge, and we only want the primes through `k`.
        pgen = psieve()
        p = next(pgen)
        assert p == 2

        for p in pgen:
            if p > k:
                break
            pcount = facexp(k, p)
            assert pcount
            # Divide that many p's out of numerators.
            i = firstnum % p
            if i:
                i = p - i
            for i in range(i, k, p):
                val, r = divmod(nums[i], p)
                assert r == 0
                pcount -= 1
                while pcount:
                    val2, r = divmod(val, p)
                    if r:
                        break
                    else:
                        val = val2
                        pcount -= 1
                nums[i] = val
                if pcount == 0:
                    break
            assert pcount == 0

        heapify(nums)
        while len(nums) > 1:
            a = heappop(nums)
            heapreplace(nums, a * nums[0])
        return nums[0] << shift2

I'm NOT suggesting to adopt this. Just for history in the unlikely case there's worldwide demand for faster comb of silly arguments ;-)

[e77db631-41f5-43fe-98d8-cca95e504097]

Can I work on C implementation if no-one else is doing it right now?

[mdickinson]

Can I work on C implementation if no-one else is doing it right now?

Sounds fine to me. You might want to coordinate with @KellerFuchs to see what the status of their PR is; maybe the two of you can collaborate?

@KellerFuchs: are you still planning to work on this?

[rhettinger]

Kellar and Yash, my suggestion is to separate the work into two phases.

Start with an initial patch that implements this simplest possible implementation, accompanied by clean documentation and thorough testing.

Once everyone has agreed on the API (i.e. calling it "comb()", how to handle various input datatypes, and handling of corner cases), and the patch is applied, only then turn to a second pass for optimizations (special casing various types, minimizing how big intermediate values can get by doing early cancellation, exploiting even/odd patterns etc).

[e77db631-41f5-43fe-98d8-cca95e504097]

Thanks @mark.dickinson. As @rhettinger suggested, I'll write a basic function that uses division and works in O(k) for now. It's holiday season but hopefully @KellerFuchs will respond by then, and in the meantime I'll write more tests other than pascal's identity and corner cases.

[e77db631-41f5-43fe-98d8-cca95e504097]

I have written the function in the latest patch to work only for positive n. Although the definition of combination or nChoosek makes no sense for negative n, negative binomial distribution exists and so binomial coefficient is defined for negative value of n. So my question is should the function be expanded to calculate for negative n or is the function expected to work only in combination sense?

[stevendaprano]

should the function be expanded to calculate for negative n or is the function expected to work only in combination sense?

If this were my design, I would offer both but in separate functions:

def comb(n, k):
    if n < 0: raise ValueError
    return bincoeff(n, k)

def bincoeff(n, k):
    if n < 0:
        return (-1)**k * bincoeff(n+k+1, k)
    else:
        # implementation here...

I believe we agreed earlier that supporting non-integers was not necessary.

Are you also providing a perm(n, k) function?

[stevendaprano]

    return (-1)**k * bincoeff(n+k+1, k)

Oops, that's meant to be n+k-1.

[e77db631-41f5-43fe-98d8-cca95e504097]

@steven.daprano

Are you also providing a perm(n, k) function? I didn't know it is also being implemented. Should I start on that too?

My implementation is based on these requirements:

• Spell it comb(n, k).
• TypeError if args aren't ints.
• ValueError if not 0 \<= k \<= n.

Should the bincoeff function be same with exception of allowing negative n?

[tim-one]

Please resist pointless feature creep. The original report was about comb(n, k) for integer n and k with 0 \<= k \<= n and that's all. Everyone who commented appeared to agree they'd find that useful.

But nobody has said they'd find generalizing beyond those constraints USEFUL, or that they'd find perm(n, k) USEFUL. They just pointed out that such things are possible.

Every bit of new API implies eternal maintenance, porting, testing, doc, and conceptual costs. So please stick to what's (at least nearly) universally agreed to be useful. Complications can be added later if there turns out to be real demand for them.

[e77db631-41f5-43fe-98d8-cca95e504097]

@tim.peters Got it.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

Hi everyone,

Sorry for the lack of reply, I severely underestimated how exhausting the holiday season would be. Catching up with the comments right now.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

Start with an initial patch that implements this simplest possible implementation, accompanied by clean documentation and thorough testing.

Once everyone has agreed on the API (i.e. calling it "comb()", how to handle various input datatypes, and handling of corner cases), and the patch is applied, only then turn to a second pass for optimizations

+1 from me on that.

@Yash: Thanks a bunch for starting on the implementation. I will have a look shortly :)

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

So, I rebased Yash's and my branches, and merged them together. The result is still in PR#11018.

This involved a few changes, which seem to reflect the consensus here:

• raise ValueError if k>n ;
• rename the function to math.combinations.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

@Raymond Hettinger

Let's name this comb() instead of binomial() please (as requested by me, Mark, and Tim).

(Replying here to keep the discussion in a single place.)

As far as I can tell from the discussions here, Steven and you stated a preference for the shortened names, and that's it. There was also no reply to my comment about comb being confusing (due to the collision with an English word).

Since there was, however, pretty clear agreement on calling it after combinations (shortened or not) rather than binomial(), I went with this.

[99ffcaa5-b43b-4e8e-a35e-9c890007b9cd]

Steven: I'm assuming Brett rearranged the title to put emphasis on the new function and to place it earlier in the title. Especially important if you're reading e-mails with the old subject on an e-mail client with limited subject preview lengths, you end up seeing something like:

"The math module should provide a function for computing..."

rather than the more useful:

"Add a function for computing binomial coefficients to t..."

[stevendaprano]

Sorry for the late reply, I missed Tim's comment when it first came through.

Please resist pointless feature creep. The original report was about comb(n, k) for integer n and k with 0 \<= k \<= n and that's all.
Everyone who commented appeared to agree they'd find that useful.

But nobody has said [...] that they'd find perm(n, k) USEFUL.

I'm not going to argue for binomial coefficients with negative n, but I find it hard to imagine anyone needing combinations without also needing permutations, and I didn't think it was necessary to explicitly say so.

But since you insist, I'll say so: I would find it useful to have a function to compute the number of permutations of n taking k at a time.

My perspective may be biased from my experience with secondary school maths, where they are taught together, but providing one without the other strikes me as weird as providing tan without sin and cos.

There are other functions from combinatorics which I personally use, like derangements, but I know when I'm pushing my luck :-)

[stevendaprano]

This involved a few changes, which seem to reflect the consensus here:

• raise ValueError if k>n ;
• rename the function to math.combinations.

I see at least four people (myself, Raymond, Mark and Tim) giving comb as first choice, and I didn't see anyone give combinations as their first choice.

I don't object to you taking it upon yourself to go with the longer name (which is my second choice), but I do object to you claiming concensus for the change without evidence of such.

There was also no reply to my comment about comb being confusing (due to the collision with an English word).

To be honest, I didn't think that comment needed a reply.

Collisions between words in different knowledge domains are not unusual. I don't think people think that math.tan has anything to do with changing the colour of their skin, or math.sin is about being wicked. Due to their length, permutation, combination and factorial are frequently abbreviated to perm, comb, fact and anyone looking for those functions should recognise the abbreviations.

But given the precedent set by itertools and math.factorial, perhaps you are right and we ought to stick to the longer name.

[rhettinger]

But given the precedent set by itertools and math.factorial, perhaps you are right and we ought to stick to the longer name

I disagree. Let's stick with comb() which is what SciPy uses. It is tedious to write out combinations in a formula what includes other steps. Also, I really want to differentiate it from the existing combinations() in the itertools module (it is reasonably forseeable that the two will used together.

[e77db631-41f5-43fe-98d8-cca95e504097]

Agreed, comb sounds much better than combination. And using the name binomial would make it sound like something that would puke out whole binomial series rather than a single coefficient(maybe leave it for that in case is it decided to be useful in the future).

PR 11414 implements simple algorithm that performs slower than using a factorial definition for k>n/3. @KellerFuchs I'd prefer if we could work on this since it's conflict free and already reflects the behavior everyone agreed upon.

Would it be better to create a separate issue for math.perm to discuss its behavior?

If the behavior of comb is satisfactory, can we start with optimizations?

[tim-one]

As far as I can tell from the discussions here, Steven and you stated a preference for the shortened names, and that's it.

Plus Mark, plus me - all backed "comb()" specifically.

I find it hard to imagine anyone needing combinations without also needing permutations, and I didn't think it was necessary \< to explicitly say so.

Of course it is. Merely saying something is possible is no reason at all to do it. The original report didn't say anything about counting partial permutations, and so it's "feature creep" on the face of it to tack that on.

I personally have scant use for perm(), but have written my own comb() many times. Far more often than I've written a factorial() and a product() combined, but I've written each of the latter more than twice, and a perm() not even once. Especially if prod() (the topic of a different report) is added, the case for adding a perm() gets weaker (rising and falling factorials are special cases of what prod() does, and perm() is just an instance of falling factorial).

Which doesn't mean perm() must not be added ;-) You're now the first to say it would be useful, which is a start. Can we get a second?

In any case, I don't want to see this report get bogged down by feature creep: comb() is what it was about from the start, and everyone so far has agreed comb() would be useful.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

@Steven

This involved a few changes, which seem to reflect the consensus here:

• raise ValueError if k>n ;
• rename the function to math.combinations. [...] As far as I can tell from the discussions here, Steven and you stated a preference for the shortened names, and that's it. There was also no reply to my comment about comb being confusing (due to the collision with an English word).

Since there was, however, pretty clear agreement on calling it after combinations (shortened or not) rather than binomial(), I went with this.

I see at least four people (myself, Raymond, Mark and Tim) giving comb as first choice, and I didn't see anyone give combinations as their first choice.

I don't object to you taking it upon yourself to go with the longer name (which is my second choice), but I do object to you claiming concensus

I wasn't claiming consensus on the short-vs.-long name issue, but on the binomial-vs-combinations one. I thought that would have been clear considering the context quoted above (which was missing from your reply)

Given that people clarified they prefer comb(), and that people conspicuously didn't comment on it being entirely-opaque to people who do not elready know what it is, I guess there is indeed consensus.

[f92613b6-9dd3-4bc5-90be-d115bcb40af5]

Given that people clarified they prefer comb(), and that people conspicuously didn't comment on it being entirely-opaque to people who do not elready know what it is, I guess there is indeed consensus.

commit afb3d36e82b8d690a410fa9dca8029a8fad42984 Author: The Fox in the Shell \KellerFuchs@hashbang.sh\ Date: Fri Feb 1 15:42:11 2019 +0100

Rename math.combinations to math.comb

[e77db631-41f5-43fe-98d8-cca95e504097]

Can I get a consensus on weather math.perm() is needed?

[mdickinson]

Can I get a consensus on weather math.perm() is needed?

It's not, for the purposes of this issue. I think math.perm should be the subject of a separate issue and discussion, and a separate PR. That way it doesn't block completion of this issue.

[e77db631-41f5-43fe-98d8-cca95e504097]

@mark.dickinson Ok, then I will work on comb for now then.

[mdickinson]

@KellerFuchs @FR4NKESTI3N

We seem to have two open PRs for this feature, both with some review comments. Which is the one true PR? Can we close the other one?