math::combinatorics(n)

✨ math::combinatorics ✨

okay bestie, sit down, hydrate, because we are about to get into the Tcl Math Library's combinatorics page and it's genuinely so much. this is the math::combinatorics manual page, and it's lowkey one of the most useful things in the whole math package. no cap. 💖

---

🌸 SYNOPSIS 🌸

the whole vibe in one block, verbatim, don't @ me:

package require Tcl 8.5 9

package require math ?1.2.6?

package require Tcl 8.6 9

package require TclOO

package require math::combinatorics ?2.1?

::math::ln_Gamma z

::math::factorial x

::math::choose n k

::math::Beta z w

::math::combinatorics::permutations n

::math::combinatorics::variations n k

::math::combinatorics::combinations n k

::math::combinatorics::derangements n

::math::combinatorics::catalan n

::math::combinatorics::firstStirling n m

::math::combinatorics::secondStirling n m

::math::combinatorics::partitionP n

::math::combinatorics::list-permutations n

::math::combinatorics::list-variations n k

::math::combinatorics::list-combinations n k

::math::combinatorics::list-derangements n

::math::combinatorics::list-powerset n

::math::combinatorics::permutationObj new/create NAME n

$perm next

$perm reset

$perm setElements elements

$perm setElements

::math::combinatorics::combinationObj new/create NAME n k

$combin next

$combin reset

$combin setElements elements

$combin setElements

---

🦋 DESCRIPTION 🦋

so the math package is out here holding implementations of several functions that are genuinely useful in combinatorial problems. and math::combinatorics extends the collections based on features that showed up in Tcl 8.6. glow-up energy. ✨

heads up bestie: the meaning of the partitionP function, and of Catalan and Stirling numbers, is explained over on the MathWorld website at http://mathworld.wolfram.com. iykyk 💅

---

👑 COMMANDS 👑

🧮 the classic math-y ones

• ::math::ln_Gamma z — hands you the natural logarithm of the Gamma function for the argument z.

real talk, the Gamma function is defined as the improper integral from zero to positive infinity of:

t**(x-1)*exp(-t) dt

the approximation used in the Tcl Math Library comes from Lanczos, ISIAM J. Numerical Analysis, series B, volume 1, p. 86. for x > 1, the absolute error of the result is claimed to be smaller than 5.5*10**-10 — like, when you compute the resulting value of Gamma via

exp( ln_Gamma( x) )

it's expected to be precise to better than nine significant figures. iconic precision, honestly.

• ::math::factorial x — returns the factorial of the argument x. here's the breakdown, and it's giving very specific, so listen up:
  • for integer x, 0 <= x <= 12, an exact integer result is returned.
  • for integer x, 13 <= x <= 21, an exact floating-point result is returned on machines with IEEE floating point.
  • for integer x, 22 <= x <= 170, the result is exact to 1 ULP.
  • for real x, x >= 0, the result is approximated by computing Gamma(x+1) using the ::math::ln_Gamma function, and the result is expected to be precise to better than nine significant figures.

⚠️ it is an error to present x <= -1 or x > 170, or a value of x that is not numeric. do not do this. it will not slay.

• ::math::choose n k — returns the binomial coefficient C(n, k)

C(n,k) = n! / k! (n-k)!

if both parameters are integers and the result fits in 32 bits, the result is rounded to an integer. integer results are exact up to at least n = 34. floating point results are precise to better than nine significant figures. 💖

• ::math::Beta z w — returns the Beta function of the parameters z and w.

Beta(z,w) = Beta(w,z) = Gamma(z) * Gamma(w) / Gamma(z+w)

results come back as a floating point number precise to better than nine significant digits, provided that w and z are both at least 1.

🌈 the counting ones

• ::math::combinatorics::permutations n — returns the number of permutations of n items. and here's the flex: the returned number is always an integer, and it is not limited by the range of 32-or 64-bits integers, because it uses the arbitrary precision integers available in Tcl 8.5 and later. main character energy fr fr.
  • int n — the number of items to be permuted.
• ::math::combinatorics::variations n k — returns the number of variations of k items selected from the total of n items. the order of the items is taken into account. 👀
  • int n — the number of items to be selected from.
  • int k — the number of items to be selected in each variation.
• ::math::combinatorics::combinations n k — returns the number of combinations of k items selected from the total of n items. the order of the items is not important.
  • int n — the number of items to be selected from.
  • int k — the number of items to be selected in each combination.
• ::math::combinatorics::derangements n — returns the number of derangements of n items. a derangement is a permutation where each item is displaced from the original position. chaotic but make it mathematical. 💀
  • int n — the number of items to be rearranged.
• ::math::combinatorics::catalan n — returns the n'th Catalan number. n is expected to be 1 or larger. these numbers occur in various combinatorial problems.
  • int n — the index of the Catalan number.
• ::math::combinatorics::firstStirling n m — calculates a Stirling number of the first kind (signed version, m cycles in a permutation of n items).
  • int n — number of items.
  • int m — number of cycles.
• ::math::combinatorics::secondStirling n m — calculates a Stirling number of the second kind (m non-empty subsets from n items).
  • int n — number of items.
  • int m — number of subsets.
• ::math::combinatorics::partitionP n — calculates the number of ways an integer n can be written as the sum of positive integers.
  • int n — number in question.

🎀 the ones that hand you whole lists

• ::math::combinatorics::list-permutations n — returns the list of permutations of the numbers 0, ..., n-1.
  • int n — the number of items to be permuted.
• ::math::combinatorics::list-variations n k — returns the list of variations of k numbers selected from the numbers 0, ..., n-1. the order of the items is taken into account.
  • int n — the number of items to be selected from.
  • int k — the number of items to be selected in each variation.
• ::math::combinatorics::list-combinations n k — returns the list of combinations of k numbers selected from the numbers 0, ..., n-1. the order of the items is ignored.
  • int n — the number of items to be selected from.
  • int k — the number of items to be selected in each combination.
• ::math::combinatorics::list-derangements n — returns the list of derangements of the numbers 0, ..., n-1.
  • int n — the number of items to be rearranged.
• ::math::combinatorics::list-powerset n — returns the list of all subsets of the numbers 0, ..., n-1.
  • int n — the number of items to be rearranged.

💅 the TclOO objects (the one-by-one girlies)

• ::math::combinatorics::permutationObj new/create NAME n — creates a TclOO object for returning permutations one by one. if the last permutation has been reached, an empty list is returned.
  • int n — the number of items to be rearranged.
• $perm next — returns the next permutation of n objects.
• $perm reset — resets the object, so that the command next returns the complete list again.
• $perm setElements elements — registers a list of items to be permuted, using the nextElements command.
  • list elements — the list of n items that will be permuted.
• $perm setElements — returns the next permulation of the registered items. (yes bestie, that's how the page spells it — keeping it exactly as written, we do not edit the source material 💖)
• ::math::combinatorics::combinationObj new/create NAME n k — creates a TclOO object for returning combinations one by one. if the last combination has been reached, an empty list is returned.
  • int n — the number of items to be rearranged.
• $combin next — returns the next combination of n objects.
• $combin reset — resets the object, so that the command next returns the complete list again.
• $combin setElements elements — registers a list of items to be permuted, using the nextElements command.
  • list elements — the list of n items that will be permuted.
• $combin setElements — returns the next combination of the registered items.

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. it's giving humble but also real. please report such in the category math of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. 🫶

please also report any ideas for enhancements you may have for either the package and/or the documentation. we want the glow-up. ✨

when proposing code changes, please provide unified diffs, i.e. the output of diff -u.

note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. do it right and it'll slay. 💅

---

⭐ CATEGORY ⭐

Mathematics

---

and that's the whole page, bestie! this was math::combinatorics from tcllib, version 2.1 — so go forth and permute, derange, and generally count things with arbitrary precision. periodt. 💖🎀🦋🌸👑