My Itching Need To Contribute Open-Source

As the spring semester tied up, I was eager to return contributing to open source projects. Although, like most developers, I was unsure of which projects that I could provide substantial contributions to and not ancillary items such as editing documentation, patching minute bugs, etc. After perusing Github's repository showcases I settled on a math library, preferably written in Javascript, seeing how I just finished the second installment of combinatorics taught by Professor Vincent Vatter.

There are several notable math libraries available, including Numeric.js, Math.js, and Numbers.js, however, the only package that would benefit from a combinatorics module was Math.js since the others catered toward specific functionalities and/or less active. Another great development technique utilized in Math.js is their extensive testing suite. Incorporating Underscore.js and Node's Assert module yield robust testing for every function, type, unit, etc. Although I have never used the aforementioned test suites, I'm happy that I get to learn a new test suite for future use.

There are existing Combinatorics modules in other math packages, including Sage, Maple, and Mathematica, however, I really wanted to improve my Javascript skills.

Combinatorics Functions To Implement

Since there were no combinatorics-related functions implemented except the 'combinations' method, I took it upon myself to start writing the foundational combinatorics functions for other submodules to utilize. So far, I have implemented the Stirling Numbers of the Second Kind (I know, it has an unusual name), and Bell Numbers. I have written multinomial and integer partition methods have not been merged yet.

Stirling Numbers of the Second Kind

Combinatorics in layman's terms means "ways to count things". So each function implemented are ways to count 'things'. The term 'things' is vague though there is an infinite amount of 'things' we can count.

The Stirling Numbers of the Second Kind count the number of ways to partition n elements into k element non-empty subsets. One way to visualize this relating n objects to tennis balls and k element non-empty subsets as boxes. So essentially, the Stirling Numbers count how many ways we can put n tennis balls into k-sized boxes ($n \geq k$). The term 'non-empty' signifies that we cannot place zero tennis balls in zero or more boxes.

We denote these numbers by $S(n,k)$ and it's recurrence relation by $$S(n,k)=\frac{1}{k!}\sum_{i=0}^{k}(-1)^{k-j}\binom{k}{i}i^{n}$$

Permutation Type

Most people are familiar with permutations as an ordered combination (classic example: "how many ways can you pick the top 3 runners out of 100"). Although Math.js already supports this function, it doesn't represent a combinatorially permutation object. This type of Permutation is a function from $[n]\rightarrow [n]$, denoted as $p = p_1 p_2 \ldots p_n$. It is a unique function $p : [n]\rightarrow [n]$ such that $p(i) = p_i$.


There are many permutation properties though the most prominent is permutation cycles. A cycle is defined as

Let $p : [n] \rightarrow [n]$ be a permutation. Let $x \in [n]$, and let $i$ be the smallest positive integer so that $p^i(x) = x$. Then we say that the entries $x,p(x),p^2(x),\cdots ,p^{i-1}(x)$ form an i-cycle in p.

[Referenced in A Walk Through Combinatorics by Miklos Bona]

This might be convoluted to some, though an example will elucidate the notion of cycles. Take a permutation $4231$ (this is a function $p : [6]\rightarrow [6]$). Notice that the first element is 4 ($p(1) = 4$) and follow 4 to find the fourth element; this is $p(4) = 1$. By repeatedly applying $p$, 1 and 4 permute amongst each other forming a 2-cycle. Contrastingly, $p(2) = 2$ and $p(3) = 3$ are known as fixed points. Therefore, in cycle-notation, this is written as $(41)(2)(3)$.

Cycles form a basis for many advanced functions. In order to write these methods there needs to be a Permutation type to support cycles, sorting, Ramsey's theorem, Permutation classes, etc.

In Javascript, I let a Permutation be either a nested Array or Matrix, where each inner array represents a cycle. In the case of $4231$, it is composed as [[4,1],[2],[3]]. This object supports representing a stringified JSON version of it's disjoint cycles, computing the inverse and multiplying Permutations. Although Underscore.js is used mainly in testing, I have used it for condition checking due to its robustness. For example, here is the multiply function:

							* Permutation.multiply
							* Computes the product of 'this' and a multiplicand and returns it product as a set of disjoint cycles.
							* @params {Permutation} Multiplicand
							* @returns {Permutation} Product permutation
							Permutation.prototype.multiply = function(multiplicand) {
								var product = [];
								if(!_.isEmpty(this._permutation)) {
									if(!_.isEmpty(multiplicand._permutation)) {
										for (var i = 0; i < multiplicand._permutation.length; i++) {
											product.push(_.indexOf(this._permutation, multiplicand._permutation[i+1]) + 1);
										return product;
									} else {
										return this._permutation;
								} else {
									return multiplicand._permutation;

Future Work

Currently, I have finished 4 functions including Stirling Numbers of the Second Kind, Bell Numbers, Multinomial, and Integer Partitions. I am excited to finalize the Permutation type because this is a huge addition and stepping stone for further implementing Combinatorics functions. I am very thrilled to see where this takes me and what I will learn from contributing to this repository. If you have anything to contribute to Math.js, please do!