\n\nYou can think of it as first generating (0, 0), whose sum is 0; then (1, 0) and (0, 1), whose sum is 1; then (2, 0), (1, 1), and (0, 2), whose sum is 2; and so on. This path describes a bijection between the indices 0, 1, 2, ..., and all pairs of natural numbers. The opposite direction of this bijection, that takes pairs to indices, is known as the Cantor pairing function.\n\nThis bijection has some nice properties; for example, the function from pairs to indices is a polynomial in the elements of the pair: the pair $$(x, y)$$ corresponds to index $$\\tfrac{1}{2}(x + y)(x + y + 1)$$. We can also look at the two functions from sequence index to the first and second elements of the pairs. These functions look like this:\n\n
\n \n
\n\nAlthough the functions jump around a lot (they have to, since they must evaluate to every natural number infinitely many times), there's a sense in which they are nicely balanced. Both are $$O(\\sqrt n)$$, and if you take evaluate them at a random large input, they're generally about the same size:\n\n
\n \n
\n\nHowever, it isn't obvious how generalize the Cantor pairing function to triples in a balanced way. The standard way to create a tripling function from a pairing function is $$g(x, y, z) = f(x, f(y, z))$$, but this is no longer balanced. If $$f$$ is the Cantor pairing function, then the three outputs of $$g^{-1}$$ are $$O(\\sqrt n)$$, $$O(\\sqrt[4] n)$$, and $$O(\\sqrt[4]n)$$. Here's what the corresponding table looks like:\n\n
\n \n
\n\n## More balance and flexibility with bit interleaving\n\nInstead of the Cantor pairing function, Malachite uses bit interleaving. This idea is not new; it has been described by [Steven Pigeon](https://hbfs.wordpress.com/2011/09/27/pairing-functions/) and others.\n\nTo generate the pairs corresponding to index 0, 1, 2, and so on, first write the indices in binary, with infinitely many leading zeros:\n\n
\n \n
\n\nAnd then distribute the bits of each index into the two slots of the corresponding pair. The even-indexed bits (counting from the right) end up in the second slot, and the odd-indexed bits in the first:\n\n
\n \n
\n\nI've color-coded the bits according to which slot they end up in. Malachite keeps track of this using an explicit bit map that looks like $$[1, 0, 1, 0, 1, 0, \\ldots]$$, indicating that bit 0 goes to slot 1, bit 1 goes to slot 0, bit 2 goes to slot 1, and so on.\n\nThis is how this method walks through the grid of pairs of natural numbers:\n\n
\n \n
\n\nThis path is called a [Z-order curve](https://en.wikipedia.org/wiki/Z-order_curve), although with this choice of coordinates it looks like it's made up of N's rather than Z's.\n\nAnd here's what the functions from the index to the first and second elements of the pairs look like:\n\n
\n \n
\n\nLike the inverses of the Cantor pairing function, these functions are balanced in the sense that both are $$O(\\sqrt n)$$, although here the first element lags noticeably behind the second. And here's a table showing them evaluated at large indices:\n\n
\n \n
\n\nThe advantage that this approach has over the Cantor pairing approach is flexibility. We can generate triples in a balanced way simply by changing the bit map to $$[2, 1, 0, 2, 1, 0, 2, 1, 0, \\ldots]$$:\n\n
\n \n
\n\nHere are the three functions from index to output. They each are $$O(\\sqrt[3]n)$$.\n\n
\n \n
\n\nHere they are evaluated at large indices:\n\n
\n \n
\n\nThis generalizes straightforwardly to $$k$$-tuples for any $$k$$. Notice that the first $$2^{ka}$$ tuples are all the tuples with elements less than $$2^a$$.\n\n## Customized balancing\n\nBy changing the bit map further, we can deliberately unbalance the tuples. For example, if we want to produce pairs where the second element of the pair is $$O(\\sqrt[3]n)$$ and the first element is $$O(n^{2/3})$$, we can use the bit map $$[1, 0, 0, 1, 0, 0, 1, 0, 0, \\ldots]$$. If we want the the first element to be exponentially larger than the second, we can use $$[0, 1, 1, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, \\ldots]$$, where there is a 1 at the $$2^i$$th position and 0 elsewhere.\n\nTo actually generate the pair sequences in the two preceding examples, you can use\n\n```rust\nexhaustive_pairs_custom_output(\n exhaustive_naturals(),\n exhaustive_naturals(),\n BitDistributorOutputType::normal(2),\n BitDistributorOutputType::normal(1),\n)\n```\nand\n```rust\nexhaustive_pairs_custom_output(\n exhaustive_naturals(),\n exhaustive_naturals(),\n BitDistributorOutputType::normal(1),\n BitDistributorOutputType::tiny(),\n)\n```\nrespectively. See the documentation of [exhaustive_pairs_custom_output](https://docs.rs/malachite-base/0.2.4/malachite_base/tuples/exhaustive/fn.exhaustive_pairs_custom_output.html) and [BitDistributorOutputType](https://docs.rs/malachite-base/latest/malachite_base/iterators/bit_distributor/struct.BitDistributorOutputType.html) for more details.\n\n## Generating tuples of other iterators\n\nSo far I've only talked about generating tuples of `Natural`s. What about tuples of elements from some other iterator `xs`? If `xs` is infinitely long, then the process is straightforward. Instead of generating, say, (8, 3), generate the pair consisting of the 8th and 3rd elements of `xs` (indexing from 0, of course). Internally, Malachite uses a structure called [`IteratorCache`](https://docs.rs/malachite-base/latest/malachite_base/iterators/iterator_cache/struct.IteratorCache.html), which stores the values produced by `xs` into a `Vec` for easy access.\n\nFor example, here's how to generate all pairs of the characters `'a'` to `'z'` (in this case, there are additional complications due to `xs` being finite, but we'll address those in a moment):\n\n```rust\nfor p in exhaustive_pairs_from_single('a'..='z').take(10) {\n println!(\"{:?}\", p);\n}\n```\n```\n(a, a)\n(a, b)\n(b, a)\n(b, b)\n(a, c)\n(a, d)\n(b, c)\n(b, d)\n(c, a)\n(c, b)\n```\n\n## Dealing with finite iterators\n\nFinite iterators are a bit of a problem. You can't generate the (8th, 3rd) pair if the input iterator has no 8th element. To take an extreme case, consider `exhaustive_pairs(exhaustive_naturals(), exhaustive_bools())`. There are only two bools, so any index pair $$(i, j)$$ where $$j \\geq 2$$ can't be used for indexing. Here's our grid of indices again, with valid indices green and invalid indices red:\n\n
\n \n
\n\nMy original solution was just to skip over the invalid indices, with a bit of extra logic to determine when both input iterators are finished. This was very slow: out of the first $$n$$ pairs, only about $$2 \\sqrt n$$ are valid, and the situation gets worse for higher-arity tuples. So what does `exhaustive_pairs` do instead?\n\nAgain, we can leverage the bit map! This scenario is actually what led me to make the bit map an explicit object in memory. What `exhaustive_pairs` does is notice when one of its iterators has completed, and then adjusts the bit map on the fly. In this particular case, it realizes that since `exhaustive_bools` produces two elements, it only needs a single bit for indexing; and then bit map is modified from $$[1, 0, 1, 0, 1, 0, 1, 0, \\ldots]$$, to $$[1, 0, 0, 0, 0, 0, 0, \\ldots]$$. In general, modifying the bit map on the fly is dangerous because you might end up repeating some output that you've already produced, but `exhaustive_pairs` only modifies the part of the map that hasn't been used yet.\n\nIf the finite iterator's length is a power of 2, as it was in this example, then updating the bit map results in all indices being valid. If it isn't a power of 2, then some indices will remain invalid; for example, in `exhaustive_pairs(exhaustive_naturals(), 0..6)` the bit map will be updated from $$[1, 0, 1, 0, 1, 0, 1, 0, \\ldots]$$, to $$[1, 0, 1, 0, 1, 0, 0, 0, \\ldots]$$, so that the index of the second pair slot will vary from 0 to 7, and only $$3/4$$ of all the indices will be valid. But this is a constant proportion; it's much better than the earlier example where only $$(2 \\sqrt n)/n$$ were valid.\n\n(In this particular case, the best thing to do would be to use `lex_pairs(exhaustive_naturals(), exhaustive_bools())`, which would produce (0, false), (0, true), (1, false), (1, true), and so on. But in general, when you call `exhaustive_pairs(xs, ys)` you might not know ahead of time whether `ys` is short, long, or infinite.)\n\nIn the next part, I will discuss how Malachite generates all `Vec`s containing elements from some iterator.\n"
},
{
"path": "docs/_posts/2022-07-30-denominators.md",
"content": "---\nlayout: post\ntitle: Which denominators does an interval contain?\nauthor: Mikhail Hogrefe\n---\n\n## Introduction\n\nIn this post I'm going to talk a bit about a problem that came up when I was figuring out how to generate rational numbers exhaustively. Malachite generates all positive rationals using the [Calkin-Wilf sequence](https://en.wikipedia.org/wiki/Calkin%E2%80%93Wilf_tree#Breadth_first_traversal):\n\n1, 1/2, 2, 1/3, 3/2, 2/3, 3, 1/4, 4/3, 3/5, 5/2, 2/5, 5/3, 3/4, 4, 1/5, 5/4, 4/7, 7/3, 3/8, ...,\n\nand by manipulating this sequence a bit it can also generate all rationals, all negative rationals, and so on. How about generating all rationals in a specified interval? This has many uses: for example, when testing conversion from rationals to floats, we might want to generate rationals that fall into the 64-bit subnormal float range.\n\nFor the remainder of this post I'm going to consider closed intervals only.\n\n## First try\n\nThe most straightforward approach is this:\n1. Generate all rationals in $$[0, 1]$$.\n2. Scale those rationals to bring them into the target interval.\n\nStep 1 is easy: we can generate 0 and 1, and then select every other rational from the above sequence:\n\n0, 1, 1/2, 1/3, 2/3, 1/4, 3/5, 2/5, 3/4, 1/5, 4/7, 3/8, 5/7, 2/7, 5/8, 3/7, 4/5, 1/6, 5/9, 4/11, ... .\n\nStep 2 is also easy. If our target interval is $$[a, b]$$, we transform each rational using $$x \\to (b - a)x + a$$. For example, here are the rationals in $$[1/3, 1/2]$$:\n\n1/3, 1/2, 5/12, 7/18, 4/9, 3/8, 13/30, 2/5, 11/24, 11/30, 3/7, 19/48, 19/42, 8/21, 7/16, 17/42, 7/15, 13/36, 23/54, 13/33, ... .\n\nFor a simple interval this approach works fine. But what if we generate intervals in $$[268876667/98914198, 245850922/78256779]$$? The endpoints of this interval are the simplest rationals that round to the best 64-bit float representations of $$e$$ and $$\\pi$$, respectively. Our algorithm gives us\n\n268876667/98914198, 245850922/78256779, 45359568684866149/15481413065696484, 33200495296270871/11611059799272363, 69677715462056705/23222119598544726, 87442412500217335/30962826131392968, 19172880691153809/6450588777373535, 111760559277407891/38703532664241210, 31331954079749087/10320942043797656, 54241917203946464/19351766332120605, ... .\n\nThis is not so nice. Our interval contains nice rationals like 3, 11/4, 14/5, and 17/6, but they are nowhere to be seen (they will appear eventually, but much later in the sequence). We want an algorithm that gives preferential treatment to rationals with small denominators. Here's what Malachite does:\n\nAn improved algorithm\n---------------------\n\nMalachite's algorithm needs to be able to do three things:\n1. Determine which denominators occur in an interval;\n2. Generate all rationals with a given denominator in an interval;\n3. Given infinitely many iterators, each generating rationals with different denominators, interleave the iterators into a single iterator.\n\nNumber 2 is easy to do and not very interesting. You can see the details [here](https://docs.rs/malachite-q/latest/malachite_q/exhaustive/fn.exhaustive_rationals_with_denominator_inclusive_range.html). Number 3 is more interesting, but already solved. I'll post about it in the future, but for now I'll just leave a link to the relevant function [here](https://docs.rs/malachite-base/latest/malachite_base/tuples/exhaustive/fn.exhaustive_dependent_pairs.html). That leaves number 1.\n\n## Finding all denominators in an interval\n\nLet's define the problem more explicitly.\n\n**Problem:** Given a closed interval $$[a, b]$$ with $$a, b \\in \\mathbb{Q}$$ and $$a < b$$, for which $$d \\in \\N^+$$ does there exist an $$n \\in \\Z$$ with $$\\gcd(n, d) = 1$$ and $$n/d \\in [a, b]$$?\n\nThe simplest algorithm is to consider each denominator 1, 2, 3, ... in turn and determine whether some rational with the denominator exists in the interval. This works fine unless the diameter $$b - a$$ is very small. If the interval is $$[0, 2^{-100}]$$, it would take a very long time to find an admissible denominator greater than 1.\n\nLuckily, Malachite knows how to find the simplest rational in an interval (\"simplest\" meaning \"having the lowest denominator\"). It uses the continued fractions of the endpoints and follows the algorithm sketched out [here](https://en.wikipedia.org/wiki/Continued_fraction#Best_rational_approximations). This gives us the lowest denominator in the interval in $$O(n^2 \\log n \\log\\log n)$$ time, $$n$$ being the maximum bit-length of the numerators and denominators of both endpoints. Once we've found the lowest denominator, we can find the $$m$$ rationals with that denominator in $$[a, b]$$ and then partition $$[a, b]$$ into $$m + 1$$ smaller intervals. Then we can repeat the process to get the second-lowest denominator, and so on.\n\nThis algorithm is efficient enough to be useful, but it's still a bit cumbersome. Our intuition suggests that $$[a, b]$$ contains every denominator in $$\\N^+$$ except for finitely many exceptions: in other words, that for every interval $$[a, b]$$ there exists a threshold $$D$$ such that for all $$d \\geq D$$, $$[a, b]$$ contains a rational with denominator $$d$$. If we knew what $$D$$ was, then we could find start finding denominators using our cumbersome continued-fraction method, but once we reached $$D$$ we could simply generate $$D, D + 1, D + 2, \\ldots$$ forever.\n\nFor the remainder of this post, I'll prove that a $$D$$ exists for any interval and give an efficient algorithm for finding it (though it generally won't be the lowest possible $$D$$).\n\n## The relationship between an interval's diameter and the denominators it contains\n\nLet $$s = b - a$$ be the diameter of $$[a, b]$$. If $$s \\geq 1$$, then we can take $$D = 1$$: $$[a, b]$$ contains all denominators in $$\\N^+$$. (For any denominator $$d$$, $$k + 1/d$$ is in $$[a, b]$$ for some integer $$k$$.)\n\nWhat if $$s < 1$$? We might think that if $$s \\geq 1/d$$ then $$[a, b]$$ must contain some rational with denominator $$d$$, but this is not the case. For example, an interval with $$s > 1/6$$ might not contain any sixths:\n\n
\n \n
\n\nThe largest gap between sixths is $$2/3$$. Let's define $$f(d)$$ to be the largest gap between fractions with denominator $$d$$:\n\n
\n \n
\n\n
\n \n
\n\nAny interval with $$s \\geq f(d)$$ is, by definition, guaranteed to contain some rational with denominator $$d$$. If $$f$$ were monotonically decreasing, then we could use that to prove that $$D$$ exists. We'd simply need to find a $$D$$ such that $$f(D) \\leq s$$, and then any $$f(d)$$ for $$d \\geq D$$ would also be less than or equal to $$s$$. But $$f$$ does not monotonically decrease.\n\n## The Jacobsthal function and primorials\n\nI couldn't find any reference to $$f(n)$$ in the literature, but fortunately $$g(n) = n f(n)$$ has been studied: it's called the [Jacobsthal function](http://oeis.org/A048669) (not to be confused with the Jacobsthal numbers, which are something unrelated). $$g(n)$$ is the size of the maximal gap in the list of all integers relatively prime to $$n$$.\n\n
\n \n
\n\nWe can make use of the bound ([^1]) $$g(n) \\leq 2^w$$, where $$w$$ is the number of distinct prime factors of $$n$$.\n\n| constraint on $$n$$ | bound on $$w$$ | bound on $$g$$ | bound on $$f$$ |\n|-----------------------|----------------|------------------|----------------------|\n| $$1 \\leq n < 2$$ | $$w \\leq 0$$ | $$g(n) \\leq 1$$ | $$f(n) \\leq 1$$ |\n| $$2 \\leq n < 6$$ | $$w \\leq 1$$ | $$g(n) \\leq 2$$ | $$f(n) \\leq 1$$ |\n| $$6 \\leq n < 30$$ | $$w \\leq 2$$ | $$g(n) \\leq 4$$ | $$f(n) \\leq 2/3$$ |\n| $$30 \\leq n < 210$$ | $$w \\leq 3$$ | $$g(n) \\leq 8$$ | $$f(n) \\leq 4/15$$ |\n| $$210 \\leq n < 2310$$ | $$w \\leq 4$$ | $$g(n) \\leq 16$$ | $$f(n) \\leq 8/105$$ |\n| $$\\ldots$$ | $$\\ldots$$ | $$\\ldots$$ | $$\\ldots$$ |\n\nThe sequence in the leftmost column, 1, 2, 6, 30, 210, ..., is the sequence of [primorials](https://en.wikipedia.org/wiki/Primorial): they are the products of the first 0, 1, 2, ... primes and therefore the smallest integers with 0, 1, 2, ... distinct prime factors. The $$n$$th primorial is denoted $$p_n\\#$$. The sequence of bounds in the rightmost column, 1, 1, 2/3, 4/15, 8/105, ... is $$2^n/p_n\\#$$ and is weakly monotonically decreasing. This allows us to construct a weakly monotonically decreasing function $$h$$ that bounds $$f$$ from above:\n\n$$h(n) = 2^k/p_k\\# \\ \\text{where} \\ p_k\\# \\leq n < p_{k+1}\\#$$.\n\nHere are $$f$$ and $$h$$ plotted together:\n\n
\n \n
\n\n$$h$$ is not a very tight bound. With more careful analysis, we could come up with a better one, perhaps by interpolating between the primorials or by making use of the bound ([^1]) $$g(h) \\leq 2k^{2+2e\\log k}$$.\n\nWe now have an algorithm or determining a threshold $$D$$ for an interval $$[a, b]$$:\n1. Find the diameter $$s = b - a$$.\n2. Compute the sequence $$2^n/p_n\\#$$ until it is less than or equal to $$s$$: the sequence decreases as $$O((2/n)^n)$$, so this step doesn't take long.\n3. Let $$n$$ be the value at which $$2^n/p_n\\# \\leq s$$. Then take $$D$$ to be $$p_n\\#$$.\n\n## Results\n\nLet's go back to our example interval, $$[268876667/98914198, 245850922/78256779]$$. Its diameter is about 0.42, so its $$D$$ is 30, meaning that it's guaranteed to contain all denominators greater than or equal to 30. This threshold is low enough that we can just test all the denominators 1 through 29, and after doing this we find that the denominators 1, 4, and all denominators greater than 4 are present.\n\nMalachite generates the rationals contained in the interval in this order:\n\n3, 11/4, 14/5, 20/7, 17/6, 23/8, 25/8, 30/11, 25/9, 29/10, 26/9, 31/11, 28/9, 31/10, 32/11, 41/15, 34/11, 35/12, 37/12, 39/14, ... .\n\n[^1]: Hans-Joachim Kanold, *Über eine zahlentheoretische Funktion von Jacobsthal*, Mathematische Annalen 170.4 (1967): 314-326\n"
},
{
"path": "docs/assets/denominators/gap-and-bound-graph.asy",
"content": "import graph;\n\nsize(600,400,IgnoreAspect);\n\nint gcd(int a, int b) {\n while (b != 0) {\n int t = b;\n b = a % b;\n a = t;\n }\n return a;\n}\n\nint jacobsthal(int n) {\n int previous = 0;\n int largest_gap = 0;\n for (int i = 0; i <= 2 * n; ++i) {\n if (gcd(i, n) == 1) {\n int gap = i - previous;\n if (gap > largest_gap) {\n largest_gap = gap;\n }\n previous = i;\n }\n }\n return largest_gap;\n}\n\nscale(Linear,Log);\nreal[] x={};\nreal[] y1={};\nreal[] y2={};\nfor (int i = 1; i < 500; ++i) {\n x.push(i);\n y1.push(jacobsthal(i)/i);\n if (i < 6) {\n y2.push(1);\n } else if (i < 30) {\n y2.push(2/3);\n } else if (i < 210) {\n y2.push(4/15);\n } else if (i < 2310) {\n y2.push(8/105);\n }\n}\n\ndraw(graph(x,y1),black,\"$f(n)$\");\ndraw(graph(x,y2),red,\"$h(n)$\");\n\nxaxis(BottomTop,LeftTicks);\nyaxis(LeftRight, RightTicks);\nadd(legend(),point(NW),(50,-25),UnFill);\n"
},
{
"path": "docs/assets/denominators/gap-graph.asy",
"content": "import graph;\n\nsize(600,400,IgnoreAspect);\n\nint gcd(int a, int b) {\n while (b != 0) {\n int t = b;\n b = a % b;\n a = t;\n }\n return a;\n}\n\nint jacobsthal(int n) {\n int previous = 0;\n int largest_gap = 0;\n for (int i = 0; i <= 2 * n; ++i) {\n if (gcd(i, n) == 1) {\n int gap = i - previous;\n if (gap > largest_gap) {\n largest_gap = gap;\n }\n previous = i;\n }\n }\n return largest_gap;\n}\n\nscale(Linear,Log);\nreal[] x={};\nreal[] y={};\nfor (int i = 1; i < 500; ++i) {\n x.push(i);\n y.push(jacobsthal(i)/i);\n}\n\ndraw(graph(x,y),black,\"$f(n)$\");\n\nxaxis(BottomTop,LeftTicks);\nyaxis(LeftRight, RightTicks);\nadd(legend(),point(NW),(25,-25),UnFill);\n"
},
{
"path": "docs/assets/denominators/gaps.asy",
"content": "import graph;\nsize(15cm);\npen small=fontcommand(\"\\scriptsize\");\n\nint gcd(int a, int b) {\n while (b != 0) {\n int t = b;\n b = a % b;\n a = t;\n }\n return a;\n}\n\nint jacobsthal(int n) {\n int previous = 0;\n int largest_gap = 0;\n for (int i = 0; i <= 2 * n; ++i) {\n if (gcd(i, n) == 1) {\n int gap = i - previous;\n if (gap > largest_gap) {\n largest_gap = gap;\n }\n previous = i;\n }\n }\n return largest_gap;\n}\n\nstring gap_function(int d) {\n int n = jacobsthal(d);\n int g = gcd(n, d);\n n = n#g;\n d = d#g;\n if (d == 1) {\n return string(n);\n } else {\n return string(n) + \"/\" + string(d);\n }\n}\n\nvoid draw_rationals(int d, real offset) {\n guide gaxis=(0,offset)--(20,offset);\n draw(gaxis);\n for(int i = 0; i < 3; ++i){\n tick(relpoint(gaxis,i/2),-plain.I*reldir(gaxis,i/2),ticksize*2);\n }\n for(int i = 0; i < 20; ++i){\n tick(relpoint(gaxis,i/20),-plain.I*reldir(gaxis,i/20),ticksize);\n }\n label(\"$0$\",relpoint(gaxis,0),-3*plain.I*reldir(gaxis,0));\n label(\"$1$\",relpoint(gaxis,0.5),-3*plain.I*reldir(gaxis,0.5));\n label(\"$2$\",relpoint(gaxis,1),-3*plain.I*reldir(gaxis,1));\n \n for (int i= 0; i <= 2 * d; ++i) {\n if (gcd(i, d) == 1) {\n dot((i*10/d, offset), red);\n if (d != 1) {\n label(\"$\" + string(i) + \"/\" + string(d) + \"$\",relpoint(gaxis,i/(2*d)),-2*plain.I*reldir(gaxis,0.5), red+small);\n }\n }\n }\n \n label(\"$f(\" + string(d) + \") = \" + gap_function(d) + \"$\",(24.5, offset), align=LeftSide);\n}\n\nreal offset = 0;\nfor (int d = 1; d <= 10; ++d) {\n draw_rationals(d, offset);\n offset -= 2;\n}\n\n// Force bottom margin to expand\ndraw(box((-1,1),(-0.5, -20)),white);\n"
},
{
"path": "docs/assets/denominators/j-graph.asy",
"content": "import graph;\n\nsize(600,400,IgnoreAspect);\n\nint gcd(int a, int b) {\n while (b != 0) {\n int t = b;\n b = a % b;\n a = t;\n }\n return a;\n}\n\nint jacobsthal(int n) {\n int previous = 0;\n int largest_gap = 0;\n for (int i = 0; i <= 2 * n; ++i) {\n if (gcd(i, n) == 1) {\n int gap = i - previous;\n if (gap > largest_gap) {\n largest_gap = gap;\n }\n previous = i;\n }\n }\n return largest_gap;\n}\n\n//scale(Linear,Log);\nreal[] x={};\nreal[] y={};\nfor (int i = 1; i < 500; ++i) {\n x.push(i);\n y.push(jacobsthal(i));\n}\n\ndraw(graph(x,y),black,\"$g(n)$\");\n\nxaxis(BottomTop,LeftTicks);\nyaxis(LeftRight, RightTicks);\nadd(legend(),point(NW),(25,-25),UnFill);\n"
},
{
"path": "docs/assets/denominators/sixths.asy",
"content": "import graph;\nsize(10cm);\nguide gaxis=(0,0)--(20,0);\npen small=fontcommand(\"\\footnotesize\");\ndraw(gaxis);\n\nfor(int i = 0; i < 3; ++i){\n tick(relpoint(gaxis,i/2),-plain.I*reldir(gaxis,i/2),ticksize*2);\n}\nfor(int i = 0; i < 20; ++i){\n tick(relpoint(gaxis,i/20),-plain.I*reldir(gaxis,i/20),ticksize);\n}\nlabel(\"$0$\",relpoint(gaxis,0),-3*plain.I*reldir(gaxis,0));\nlabel(\"$1$\",relpoint(gaxis,0.5),-3*plain.I*reldir(gaxis,0.5));\nlabel(\"$2$\",relpoint(gaxis,1),-3*plain.I*reldir(gaxis,1));\n\nint gcd(int a, int b) {\n while (b != 0) {\n int t = b;\n b = a % b;\n a = t;\n }\n return a;\n}\n\nfor (int i= 0; i <= 12; ++i) {\n if (gcd(i, 6) == 1) {\n dot((i*10/6, 0), red);\n label(\"$\" + string(i) + \"/6$\",relpoint(gaxis,i/(2*6)),-2*plain.I*reldir(gaxis,0.5), red+small);\n }\n}\n\ndraw((1.8, 0.2)--(1.8, -0.2),blue+linewidth(0.5mm));\ndraw((1.8, 0)--(8.2, 0),blue+linewidth(0.5mm));\ndraw((8.2, 0.2)--(8.2, -0.2),blue+linewidth(0.5mm));\n"
},
{
"path": "docs/assets/exhaustive-part-2/cantor-graph.asy",
"content": "import graph;\n\nsize(600,400,IgnoreAspect);\n\npair unpair(int i) {\n int j = 0;\n int r = i;\n while (r >= j) {\n r -= j;\n j += 1;\n }\n j -= 1;\n return (j - r, r);\n}\n\nreal[] x={};\nreal[] y1={};\nreal[] y2={};\nfor (int i = 0; i < 500; ++i) {\n x.push(i);\n y1.push(unpair(i).x);\n y2.push(unpair(i).y);\n}\nreal[] z=sqrt(2x);\n\ndraw(graph(x,y1),red,\"first element\");\ndraw(graph(x,y2),blue,\"second element\");\ndraw(graph(x,z),black,\"$\\sqrt{2x}$\");\n\nxaxis(BottomTop,LeftTicks);\nyaxis(LeftRight, RightTicks);\nadd(legend(),point(NW),(25,-25),UnFill);\n"
},
{
"path": "docs/assets/exhaustive-part-2/cantor-grid.asy",
"content": "unitsize(1cm);\nint size = 5;\nfor (int x = 0; x < size; ++x) {\n for (int y = 0; y < size; ++y) {\n dot((x, y));\n }\n}\n\npair unpair(int i) {\n int j = 0;\n int r = i;\n while (r >= j) {\n r -= j;\n j += 1;\n }\n j -= 1;\n return (j - r, r);\n}\n\npath boundary = box((-0.5, -0.5), (size + 0.5, size + 0.5));\npair previous = (0, 0);\nfor (int i = 1; i < 15; ++i) {\n pair next = unpair(i);\n bool previous_in_range = previous.x < size && previous.y < size;\n bool next_in_range = next.x < size && next.y < size;\n if (previous_in_range && next_in_range) {\n draw(previous -- next, arrow=Arrow, gray);\n } else {\n draw(previous -- next, gray+Dotted());\n }\n previous = next;\n}\nclip(boundary);"
},
{
"path": "docs/assets/exhaustive-part-2/cantor-large.tex",
"content": "\\documentclass[11pt]{article}\n\\usepackage{amsmath}\n\n\\begin{document}\n\n\\begin{equation*}\n\\begin{split}\n3^{20} &\\rightarrow (33123, 50384) \\\\\n3^{40} &\\rightarrow (2293673435, 2637384353) \\\\\n3^{60} &\\rightarrow (158808187801698, 132365843578904) \\\\\n3^{80} &\\rightarrow (12105097562203174223, 5088437816790055004) \\\\\n3^{100} &\\rightarrow (416864661676079910029691, 598396408918091282666529) \\\\\n\\end{split}\n\\end{equation*}\n\n\\end{document}"
},
{
"path": "docs/assets/exhaustive-part-2/cantor-triples-large.tex",
"content": "\\documentclass[11pt]{article}\n\\usepackage{amsmath}\n\n\\begin{document}\n\n\\begin{equation*}\n\\begin{split}\n3^{20} &\\rightarrow (33123, 298, 18) \\\\\n3^{40} &\\rightarrow (2293673435, 7475, 65152) \\\\\n3^{60} &\\rightarrow (158808187801698, 13757728, 2512848) \\\\\n3^{80} &\\rightarrow (12105097562203174223, 2695483339, 494638230) \\\\\n3^{100} &\\rightarrow (416864661676079910029691, 871747234874, 222233029040) \\\\\n\\end{split}\n\\end{equation*}\n\n\\end{document}\n"
},
{
"path": "docs/assets/exhaustive-part-2/interleave-bits-1.tex",
"content": "\\documentclass[11pt]{article}\n\\usepackage{amsmath}\n\n\\begin{document}\n\n\\begin{tabular}{rcr}\n0 & $\\rightarrow$ & \\ldots 000000 \\\\\n1 & $\\rightarrow$ & \\ldots 000001 \\\\\n2 & $\\rightarrow$ & \\ldots 000010 \\\\\n3 & $\\rightarrow$ & \\ldots 000011 \\\\\n4 & $\\rightarrow$ & \\ldots 000100 \\\\\n5 & $\\rightarrow$ & \\ldots 000101 \\\\\n6 & $\\rightarrow$ & \\ldots 000110 \\\\\n7 & $\\rightarrow$ & \\ldots 000111 \\\\\n\\end{tabular}\n\n\\end{document}\n"
},
{
"path": "docs/assets/exhaustive-part-2/interleave-bits-2.tex",
"content": "\\documentclass[11pt]{article}\n\\usepackage{amsmath}\n\\usepackage{xcolor}\n\n\\begin{document}\n\n\\begin{tabular}{rcrcrcr}\n0 & $\\rightarrow$ & \\ldots \\color{red}0\\color{blue}0\\color{red}0\\color{blue}0\\color{red}0\\color{blue}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00000 \\color{black})$ & $\\rightarrow$ & $(0, 0)$ \\\\\n1 & $\\rightarrow$ & \\ldots \\color{red}0\\color{blue}0\\color{red}0\\color{blue}0\\color{red}0\\color{blue}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00001 \\color{black})$ & $\\rightarrow$ & $(0, 1)$ \\\\\n2 & $\\rightarrow$ & \\ldots \\color{red}0\\color{blue}0\\color{red}0\\color{blue}0\\color{red}1\\color{blue}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00000 \\color{black})$ & $\\rightarrow$ & $(1, 0)$ \\\\\n3 & $\\rightarrow$ & \\ldots \\color{red}0\\color{blue}0\\color{red}0\\color{blue}0\\color{red}1\\color{blue}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00001 \\color{black})$ & $\\rightarrow$ & $(1, 1)$ \\\\\n4 & $\\rightarrow$ & \\ldots \\color{red}0\\color{blue}0\\color{red}0\\color{blue}1\\color{red}0\\color{blue}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00010 \\color{black})$ & $\\rightarrow$ & $(0, 2)$ \\\\\n5 & $\\rightarrow$ & \\ldots \\color{red}0\\color{blue}0\\color{red}0\\color{blue}1\\color{red}0\\color{blue}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00011 \\color{black})$ & $\\rightarrow$ & $(0, 3)$ \\\\\n6 & $\\rightarrow$ & \\ldots \\color{red}0\\color{blue}0\\color{red}0\\color{blue}1\\color{red}1\\color{blue}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00010 \\color{black})$ & $\\rightarrow$ & $(1, 2)$ \\\\\n7 & $\\rightarrow$ & \\ldots \\color{red}0\\color{blue}0\\color{red}0\\color{blue}1\\color{red}1\\color{blue}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00011 \\color{black})$ & $\\rightarrow$ & $(1, 3)$ \\\\\n\\end{tabular}\n\n\\end{document}\n"
},
{
"path": "docs/assets/exhaustive-part-2/interleave-grid-filtered.asy",
"content": "unitsize(1cm);\nint size = 8;\nfor (int x = 0; x < size; ++x) {\n for (int y = 0; y < size; ++y) {\n if (y < 2) {\n \tdot((x, y), green);\n } else {\n dot((x, y), red);\n }\n }\n}\n\npair unpair(int i) {\n int x = 0;\n int y = 0;\n bool on_x = false;\n int out_mask = 1;\n while (i != 0) {\n if (i % 2 != 0) {\n if (on_x) {\n x += out_mask;\n } else {\n y += out_mask;\n }\n }\n if (on_x) {\n on_x = false;\n out_mask *= 2;\n } else {\n on_x = true;\n }\n i #= 2;\n }\n return (x, y);\n}\n\npath boundary = box((-0.5, -0.5), (size + 0.5, size + 0.5));\npair previous = (0, 0);\nfor (int i = 1; i < size * size; ++i) {\n pair next = unpair(i);\n bool previous_in_range = previous.x <= size && previous.y <= size;\n bool next_in_range = next.x <= size && next.y <= size;\n if (previous_in_range && next_in_range) {\n draw(previous -- next, arrow=Arrow, gray);\n } else {\n draw(previous -- next, gray+Dotted());\n }\n previous = next;\n}\nclip(boundary);"
},
{
"path": "docs/assets/exhaustive-part-2/interleave-grid.asy",
"content": "unitsize(1cm);\nint size = 8;\nfor (int x = 0; x < size; ++x) {\n for (int y = 0; y < size; ++y) {\n dot((x, y));\n }\n}\n\npair unpair(int i) {\n int x = 0;\n int y = 0;\n bool on_x = false;\n int out_mask = 1;\n while (i != 0) {\n if (i % 2 != 0) {\n if (on_x) {\n x += out_mask;\n } else {\n y += out_mask;\n }\n }\n if (on_x) {\n on_x = false;\n out_mask *= 2;\n } else {\n on_x = true;\n }\n i #= 2;\n }\n return (x, y);\n}\n\npath boundary = box((-0.5, -0.5), (size + 0.5, size + 0.5));\npair previous = (0, 0);\nfor (int i = 1; i < size * size; ++i) {\n pair next = unpair(i);\n bool previous_in_range = previous.x <= size && previous.y <= size;\n bool next_in_range = next.x <= size && next.y <= size;\n if (previous_in_range && next_in_range) {\n draw(previous -- next, arrow=Arrow, gray);\n } else {\n draw(previous -- next, gray+Dotted());\n }\n previous = next;\n}\nclip(boundary);"
},
{
"path": "docs/assets/exhaustive-part-2/interleave-large.tex",
"content": "\\documentclass[11pt]{article}\n\\usepackage{amsmath}\n\n\\begin{document}\n\n\\begin{equation*}\n\\begin{split}\n3^{20} &\\rightarrow (47160, 48725) \\\\\n3^{40} &\\rightarrow (4005651428, 74192769) \\\\\n3^{60} &\\rightarrow (191657527975116, 14476912773621) \\\\\n3^{80} &\\rightarrow (8489200491033962112, 13032031964488297961) \\\\\n3^{100} &\\rightarrow (231900172002858385847832, 957915753008438345446493) \\\\\n\\end{split}\n\\end{equation*}\n\n\\end{document}\n"
},
{
"path": "docs/assets/exhaustive-part-2/interleave-pairs-graph.asy",
"content": "import graph;\n\nsize(600,400,IgnoreAspect);\n\npair unpair(int i) {\n int x = 0;\n int y = 0;\n bool on_x = false;\n int out_mask = 1;\n while (i != 0) {\n if (i % 2 != 0) {\n if (on_x) {\n x += out_mask;\n } else {\n y += out_mask;\n }\n }\n if (on_x) {\n on_x = false;\n out_mask *= 2;\n } else {\n on_x = true;\n }\n i #= 2;\n }\n return (x, y);\n}\n\nreal[] x={};\nreal[] y1={};\nreal[] y2={};\nfor (int i = 0; i < 10000; ++i) {\n x.push(i);\n y1.push(unpair(i).x);\n y2.push(unpair(i).y);\n}\nreal[] z=sqrt(3*x);\n\ndraw(graph(x,y1),red,\"first element\");\ndraw(graph(x,y2),blue,\"second element\");\ndraw(graph(x,z),black,\"$\\sqrt{3x}$\");\n\nxaxis(BottomTop,LeftTicks);\nyaxis(LeftRight, RightTicks);\nadd(legend(),point(NW),(25,-25),UnFill);\n"
},
{
"path": "docs/assets/exhaustive-part-2/interleave-triples-bits.tex",
"content": "\\documentclass[11pt]{article}\n\\usepackage{amsmath}\n\\usepackage{xcolor}\n\n\\begin{document}\n\n\\begin{tabular}{rcrcrcr}\n0 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}0\\color{red}0\\color{blue}0\\color{green}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00000, \\ \\color{green} \\ldots 00000 \\color{black})$ & $\\rightarrow$ & $(0, 0, 0)$ \\\\\n1 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}0\\color{red}0\\color{blue}0\\color{green}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00000, \\ \\color{green} \\ldots 00001 \\color{black})$ & $\\rightarrow$ & $(0, 0, 1)$ \\\\\n2 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}0\\color{red}0\\color{blue}1\\color{green}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00001, \\ \\color{green} \\ldots 00000 \\color{black})$ & $\\rightarrow$ & $(0, 1, 0)$ \\\\\n3 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}0\\color{red}0\\color{blue}1\\color{green}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00001, \\ \\color{green} \\ldots 00001 \\color{black})$ & $\\rightarrow$ & $(0, 1, 1)$ \\\\\n4 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}0\\color{red}1\\color{blue}0\\color{green}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00000, \\ \\color{green} \\ldots 00000 \\color{black})$ & $\\rightarrow$ & $(1, 0, 0)$ \\\\\n5 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}0\\color{red}1\\color{blue}0\\color{green}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00000, \\ \\color{green} \\ldots 00001 \\color{black})$ & $\\rightarrow$ & $(1, 0, 1)$ \\\\\n6 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}0\\color{red}1\\color{blue}1\\color{green}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00001, \\ \\color{green} \\ldots 00000 \\color{black})$ & $\\rightarrow$ & $(1, 1, 0)$ \\\\\n7 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}0\\color{red}1\\color{blue}1\\color{green}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00001, \\ \\color{green} \\ldots 00001 \\color{black})$ & $\\rightarrow$ & $(1, 1, 1)$ \\\\\n8 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}1\\color{red}0\\color{blue}0\\color{green}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00000, \\ \\color{green} \\ldots 00010 \\color{black})$ & $\\rightarrow$ & $(0, 0, 2)$ \\\\\n9 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}1\\color{red}0\\color{blue}0\\color{green}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00000, \\ \\color{green} \\ldots 00011 \\color{black})$ & $\\rightarrow$ & $(0, 0, 3)$ \\\\\n10 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}1\\color{red}0\\color{blue}1\\color{green}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00001, \\ \\color{green} \\ldots 00010 \\color{black})$ & $\\rightarrow$ & $(0, 1, 2)$ \\\\\n11 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}1\\color{red}0\\color{blue}1\\color{green}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00000, \\ \\color{blue} \\ldots 00001, \\ \\color{green} \\ldots 00011 \\color{black})$ & $\\rightarrow$ & $(0, 1, 3)$ \\\\\n12 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}1\\color{red}1\\color{blue}0\\color{green}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00000, \\ \\color{green} \\ldots 00010 \\color{black})$ & $\\rightarrow$ & $(1, 0, 2)$ \\\\\n13 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}1\\color{red}1\\color{blue}0\\color{green}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00000, \\ \\color{green} \\ldots 00011 \\color{black})$ & $\\rightarrow$ & $(1, 0, 3)$ \\\\\n14 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}1\\color{red}1\\color{blue}1\\color{green}0 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00001, \\ \\color{green} \\ldots 00010 \\color{black})$ & $\\rightarrow$ & $(1, 1, 2)$ \\\\\n15 & $\\rightarrow$ & \\ldots \\color{green}0\\color{red}0\\color{blue}0\\color{green}1\\color{red}1\\color{blue}1\\color{green}1 & $\\rightarrow$ & $(\\color{red} \\ldots 00001, \\ \\color{blue} \\ldots 00001, \\ \\color{green} \\ldots 00011 \\color{black})$ & $\\rightarrow$ & $(1, 1, 3)$ \\\\\n\\end{tabular}\n\n\\end{document}\n"
},
{
"path": "docs/assets/exhaustive-part-2/interleave-triples-graph.asy",
"content": "import graph;\n\nsize(600,400,IgnoreAspect);\n\ntriple untriple(int i) {\n int x = 0;\n int y = 0;\n int z = 0;\n int j = 2;\n int out_mask = 1;\n while (i != 0) {\n if (i % 2 != 0) {\n if (j == 0) {\n x += out_mask;\n } else if (j == 1) {\n y += out_mask;\n } else {\n z += out_mask;\n }\n }\n if (j == 0) {\n j = 2;\n out_mask *= 2;\n } else if (j == 1) {\n j = 0;\n } else {\n j = 1;\n }\n i #= 2;\n }\n return (x, y, z);\n}\n\nreal[] x={};\nreal[] y1={};\nreal[] y2={};\nreal[] y3={};\nfor (int i = 0; i < 10000; ++i) {\n x.push(i);\n y1.push(untriple(i).x);\n y2.push(untriple(i).y);\n y3.push(untriple(i).z);\n}\nreal[] z=(7*x)^(1/3);\n\ndraw(graph(x,y1),red,\"first element\");\ndraw(graph(x,y2),blue,\"second element\");\ndraw(graph(x,y3),green,\"third element\");\ndraw(graph(x,z),black,\"$\\sqrt[3]{7x}$\");\n\nxaxis(BottomTop,LeftTicks);\nyaxis(LeftRight, RightTicks);\nadd(legend(),point(NW),(25,-25),UnFill);\n"
},
{
"path": "docs/assets/exhaustive-part-2/interleave-triples-large.tex",
"content": "\\documentclass[11pt]{article}\n\\usepackage{amsmath}\n\n\\begin{document}\n\n\\begin{equation*}\n\\begin{split}\n3^{20} &\\rightarrow (460, 1414, 1881) \\\\\n3^{40} &\\rightarrow (709242, 1441904, 2284385) \\\\\n3^{60} &\\rightarrow (2679879830, 1355562942, 821033137) \\\\\n3^{80} &\\rightarrow (3812501379408, 1191406597864, 8482842874549) \\\\\n3^{100} &\\rightarrow (7172636040844612, 458719279115590, 7931619284932509) \\\\\n\\end{split}\n\\end{equation*}\n\n\\end{document}\n"
},
{
"path": "docs/assets/logo.asy",
"content": "unitsize(1mm);\n\npair p1 = (25.0, -279.5970461708813);\npair p2 = (73.21397343575165, -453.91200545461675);\npair p3 = (87.46591514137958, -478.59709259527415);\npair p4 = (135.6798885771313, -87.89385577922775);\npair p5 = (139.89273037187124, -171.40290740472582);\npair p6 = (202.35864551325085, -370.4029538291187);\npair p7 = (214.32011142286873, -607.5090980498909);\npair p8 = (284.53465067912623, -562.1061442207722);\npair p9 = (310.7480582943721, -42.490901950109105);\npair p10 = (339.2519417056279, -42.490901950109105);\npair p11 = (347.00056582050587, -196.08799454538328);\npair p12 = (425.6407886662433, -408.50905162549805);\npair p13 = (435.67988857713124, -607.5090980498909);\npair p14 = (514.3201114228686, -87.89385577922775);\npair p15 = (550.5726189490025, -241.49094837450195);\npair p16 = (562.5340848586204, -478.59709259527415);\npair p17 = (576.7860265642483, -453.91200545461675);\npair p18 = (625.0, -279.5970461708813);\n\npair a = (0.5, sqrt(3)/2);\npair b = (0, 0);\npair c = (1, 0);\n\npair center = (0.5, sqrt(3)/6);\n\npen[] colors = new pen [] {\n RGB(115, 209, 160),\n RGB(86,158,118),\n RGB(56,106,76),\n RGB(27, 44, 34)\n};\n\nfill(p1 -- p3 -- p6 -- p5 -- cycle, colors[2]);\nfill(p12 -- p17 -- p13 -- p8 -- cycle, colors[2]);\nfill(p9 -- p14 -- p15 -- p11 -- cycle, colors[2]);\n\nfill(p6 -- p12 -- p11 -- cycle, colors[2]);\nfill(p3 -- p8 -- p7 -- cycle, colors[2]);\nfill(p9 -- p5 -- p4 -- cycle, colors[2]);\nfill(p17 -- p15 -- p18 -- cycle, colors[2]);\n\nfill(p1 -- p2 -- p3 -- cycle, colors[1]);\nfill(p3 -- p6 -- p8 -- cycle, colors[1]);\nfill(p6 -- p8 -- p12 -- cycle, colors[0]);\nfill(p6 -- p5 -- p11 -- cycle, colors[0]);\nfill(p13 -- p8 -- p7 -- cycle, colors[1]);\nfill(p13 -- p16 -- p17 -- cycle, colors[1]);\nfill(p12 -- p17 -- p15 -- cycle, colors[1]);\nfill(p12 -- p11 -- p15 -- cycle, colors[0]);\nfill(p1 -- p5 -- p4 -- cycle, colors[1]);\nfill(p9 -- p5 -- p11 -- cycle, colors[1]);\nfill(p9 -- p10 -- p14 -- cycle, colors[1]);\nfill(p14 -- p15 -- p18 -- cycle, colors[1]);\n"
},
{
"path": "docs/index.md",
"content": "
\r\n \r\n
\r\n\r\nMalachite is an arbitrary-precision arithmetic library for [Rust](https://www.rust-lang.org/). It\r\nachieves high performance in part by using algorithms derived from [GMP](https://gmplib.org/),\r\n[FLINT](https://www.flintlib.org/), and [MPFR](https://www.mpfr.org/).\r\n\r\nThe documentation for Malachite is [here](https://docs.rs/malachite/latest/malachite/), and its crate is [here](https://crates.io/crates/malachite).\r\n\r\n```rust\r\nuse malachite::num::arithmetic::traits::Factorial;\r\nuse malachite::Natural;\r\n\r\nfn main() {\r\n println!(\"{}\", Natural::factorial(100));\r\n}\r\n```\r\nThe code above outputs the following:\r\n```\r\n93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000\r\n```\r\nYou have to scroll to see the entire output.\r\n\r\nHere's a more complex example, calculating the negative-one-millionth power of 3 and displaying the\r\nresult with 30 digits of precision.\r\n\r\n```rust\r\nuse malachite::num::arithmetic::traits::Pow;\r\nuse malachite::num::conversion::string::options::ToSciOptions;\r\nuse malachite::num::conversion::traits::ToSci;\r\nuse malachite::Rational;\r\n\r\nfn main() {\r\n let mut options = ToSciOptions::default();\r\n options.set_precision(30);\r\n println!(\"{}\", Rational::from(3).pow(-1_000_000i64).to_sci_with_options(options));\r\n}\r\n```\r\nThe output is this:\r\n```\r\n5.56263209915712886588211486263e-477122\r\n```\r\nEvery digit is correct, except that the least-significant digit was rounded up from 2. The default\r\nrounding mode,\r\n[`Nearest`](https://docs.rs/malachite-base/latest/malachite_base/rounding_modes/enum.RoundingMode.html#variant.Nearest),\r\nuses [bankers' rounding](https://en.wikipedia.org/wiki/Rounding#Rounding_half_to_even), but you may\r\nspecify different rounding behavior via the options parameter.\r\n\r\nMalachite is designed to work with very large numbers efficiently. See [here](/performance) for a\r\nperformance comparison against other libraries.\r\n\r\nMalachite uses `no_std`, unless the `random`, `test_build`, or `bin_build` features are enabled.\r\n\r\nTo use Malachite, add the following to your project's `Cargo.toml` file:\r\n```yaml\r\n[dependencies.malachite]\r\nversion = \"0.9.1\"\r\n```\r\n\r\nBy default, all of Malachite's features are included, but you can opt out of some of them. For\r\nexample, if you want to use `Natural` and `Integer` but not `Rational`, you can instead use\r\n```yaml\r\n[dependencies.malachite]\r\nversion = \"0.9.1\"\r\ndefault-features = false\r\nfeatures = [ \"naturals_and_integers\" ]\r\n```\r\n\r\nThe `malachite` crate re-exports three sub-crates.\r\n- **malachite-base** ([crates.io](https://crates.io/crates/malachite-base)) is a collection of utilities\r\n supporting the other crates. It includes\r\n - Traits that wrap functions from the standard library, like\r\n [`CheckedAdd`](https://docs.rs/malachite-base/latest/malachite_base/num/arithmetic/traits/trait.CheckedAdd.html);\r\n - Traits that give extra functionality to primitive types, like\r\n [`Gcd`](https://docs.rs/malachite-base/latest/malachite_base/num/arithmetic/traits/trait.Gcd.html),\r\n [`FloorSqrt`](https://docs.rs/malachite-base/latest/malachite_base/num/arithmetic/traits/trait.FloorSqrt.html),\r\n and\r\n [`BitAccess`](https://docs.rs/malachite-base/latest/malachite_base/num/logic/traits/trait.BitAccess.html);\r\n - Iterator-producing functions that let you generate values for testing.\r\n- **malachite-nz** ([crates.io](https://crates.io/crates/malachite-nz)) defines two bignum types,\r\n [`Natural`](https://docs.rs/malachite-nz/latest/malachite_nz/natural/struct.Natural.html)s and\r\n [`Integer`](https://docs.rs/malachite-nz/latest/malachite_nz/integer/struct.Integer.html)s. The\r\n functions defined on these types include\r\n - All the ones you'd expect, like addition, subtraction, multiplication, and integer division;\r\n - Implementations of\r\n [`DivRound`](https://docs.rs/malachite-base/latest/malachite_base/num/arithmetic/traits/trait.DivRound.html),\r\n which provides division that rounds according to a specified\r\n [`RoundingMode`](https://docs.rs/malachite-base/latest/malachite_base/rounding_modes/enum.RoundingMode.html);\r\n - Various mathematical functions, like implementations of\r\n [`FloorSqrt`](https://docs.rs/malachite-base/latest/malachite_base/num/arithmetic/traits/trait.FloorSqrt.html)\r\n and\r\n [`Gcd`](https://docs.rs/malachite-base/latest/malachite_base/num/arithmetic/traits/trait.Gcd.html);\r\n - Modular arithmetic functions, like implementations of\r\n [`ModAdd`](https://docs.rs/malachite-base/latest/malachite_base/num/arithmetic/traits/trait.ModAdd.html)\r\n and\r\n [`ModPow`](https://docs.rs/malachite-base/latest/malachite_base/num/arithmetic/traits/trait.ModPow.html),\r\n and of traits for arithmetic modulo a power of 2, like\r\n [`ModPowerOf2Add`](https://docs.rs/malachite-base/latest/malachite_base/num/arithmetic/traits/trait.ModPowerOf2Add.html)\r\n and\r\n [`ModPowerOf2Pow`](https://docs.rs/malachite-base/latest/malachite_base/num/arithmetic/traits/trait.ModPowerOf2Pow.html);\r\n - Various functions for logic and bit manipulation, like\r\n [`BitAnd`](https://doc.rust-lang.org/nightly/core/ops/trait.BitAnd.html) and\r\n [`BitAccess`](https://docs.rs/malachite-base/latest/malachite_base/num/logic/traits/trait.BitAccess.html).\r\n\r\n If you need to explicitly include this crate as a dependency of the `malachite` crate, use the\r\n `naturals_and_integers` or `malachite-nz` feature.\r\n- **malachite-q** ([crates.io](https://crates.io/crates/malachite-q)) defines\r\n [`Rational`](https://docs.rs/malachite-q/latest/malachite_q/struct.Rational.html)s. The\r\n functions defined on this type include\r\n - All the ones you'd expect, like addition, subtraction, multiplication, and division;\r\n - Functions related to conversion between\r\n [`Rational`](https://docs.rs/malachite-q/latest/malachite_q/struct.Rational.html)s and other\r\n kinds of numbers, including primitive floats;\r\n - Functions for Diophantine approximation;\r\n - Functions for expressing\r\n [`Rational`](https://docs.rs/malachite-q/latest/malachite_q/struct.Rational.html)s in\r\n scientific notation.\r\n\r\n If you need to explicitly include this crate as a dependency of the `malachite` crate, use the\r\n `rationals` or `malachite-q` feature.\r\n\r\n- **malachite-float** Arbitrary-precision floating-point numbers. These are in development, and\r\n most features are missing.\r\n\r\nMalachite is under active development, with many more types and features planned for the future.\r\nNonetheless, it is extensively tested and documented, and ready for use today. Just be aware that\r\nits API is not stable yet, and that Malachite is licensed under LGPL 3.0.\r\n\r\nMalachite is developed by Mikhail Hogrefe. `malachite-bigint`, a drop-in num-bigint replacement based on Malachite, was created by Steve Shi and is now maintained by Mikhail Hogrefe. Thanks to b4D8, florian1345, konstin, Rowan Hart, YunWon Jeong, Park Joon-Kyu, Antonio Mamić, OliverNChalk, shekohex, and skycloudd for additional contributions.\r\n\r\n# FAQ\r\n**How is \"Malachite\" pronounced, and what does it mean?**\r\n\"Malachite\" is pronounced MA-luh-kite, or /ˈmæl.əˌkaɪt/. It is the name of\r\n[a green gemstone](https://en.wikipedia.org/wiki/Malachite). Unfortunately, malachite does not\r\ncontain iron, which would have made it a particularly good namesake for a Rust library.\r\n\r\nMalachite's logo is an image of a [snub cube](https://en.wikipedia.org/wiki/Snub_cube).\r\n\r\n**When does Malachite allocate memory?**\r\nAny `Natural` less than $$2^{64}$$ is represented inline, without allocating memory. Any `Integer`\r\nwhose absolute value is less than $$2^{64}$$ doesn't allocate either, and neither does any\r\n`Rational` whose absolute numerator and denominator are both less than $$2^{64}$$. If you're using\r\na build with `--features 32_bit_limbs`, then the threshold is $$2^{32}$$ instead.\r\n\r\n**Can I build Malachite for WebAssembly?**\r\nYes. If, in the future, Malachite includes code incompatible with Wasm (for example, code that uses\r\n[rayon](https://docs.rs/rayon/latest/rayon/)), it will be possible to disable that code with cargo\r\nflags.\r\n\r\n# Blog Posts\r\n
\n\nThe most significant operations involved in adding two rational numbers (fractions) are GCD\ncomputation and division.\n\nFor GCD computation, `num` uses the\n[binary GCD algorithm](https://en.wikipedia.org/wiki/Binary_GCD_algorithm), a quadratic algorithm.\nMalachite follows GMP in using\n[Lehmer's GCD algorithm](https://en.wikipedia.org/wiki/Lehmer%27s_GCD_algorithm), which takes\nadvantage of fast multiplication algorithms to achieve $$O(n (\\log n)^2 \\log \\log n)$$ time.\n\nFor division, `num` uses Knuth's\n[Algorithm D](https://ridiculousfish.com/blog/posts/labor-of-division-episode-iv.html), which is\nalso quadratic. Malachite, again following GMP, uses several division algorithms depending on the\ninput size. For the largest inputs, it uses a kind of\n[Barrett reduction](https://en.wikipedia.org/wiki/Barrett_reduction), which takes\n$$O(n \\log n \\log \\log n)$$ time.\n\n## Converting a Natural to a string\n`cargo run --features bin_build --release -- -l 100000 -m random -b benchmark_natural_to_string_library_comparison -c \"mean_bits_n 1024\"`\n
\n \n
\n\nWhen converting a natural number to a string, `num` seems to use an $$O(n^{3/2})$$ algorithm.\nMalachite uses a divide-and-conquer algorithm that takes $$O(n (\\log n)^2 \\log \\log n)$$ time.\n\n## Natural multiplication\n`cargo run --features bin_build --release -- -l 20000 -m random -b benchmark_natural_mul_library_comparison -c \"mean_bits_n 16384\"`\n
\n \n
\n\nFor multiplying two natural numbers, `num` uses a basecase quadratic algorithm for small inputs,\nthen [Toom-22](https://en.wikipedia.org/wiki/Toom%E2%80%93Cook_multiplication) (Karatsuba)\nmultiplication for larger inputs, and finally Toom-33 for the largest ones. This means that\nmultiplication takes $$O(n^{\\log_3 5}) \\approx O(n^{1.465})$$ time.\n\nMalachite also uses a basecase quadratic algorithm, then 13 variants of Toom-Cook multiplication,\nand finally [Schönhage-Strassen (FFT) multiplication](https://en.wikipedia.org/wiki/Schonhage-Strassen_algorithm) for the largest inputs, achieving $$O(n \\log n \\log \\log n)$$\ntime.\n\nGiven all of this machinery, it's a little disappointing that Malachite isn't much faster at\nmultiplying than `num` is, in practice. I have a few improvements in mind that should boost\nMalachite's multiplication performance further.\n\nFor numbers of up to 1000 bits, all three libraries are about equally fast:\n\n`cargo run --features bin_build --release -- -l 100000 -m random -b benchmark_natural_mul_library_comparison -c \"mean_bits_n 64\"`\n
\n \n
\n\n## Natural addition\n`cargo run --features bin_build --release -- -l 100000 -m random -b benchmark_natural_add_library_comparison -c \"mean_bits_n 1024\"`\n
![\"Logo\"](\"docs/assets/logo-and-name.svg\"){kind=logo}
\n\nAn arbitrary-precision arithmetic library for Rust.\n\nParts of Malachite are derived from [GMP](https://gmplib.org/),\n[FLINT](https://www.flintlib.org/), and [MPFR](https://www.mpfr.org/).\n\nThe documentation for Malachite is [here](https://docs.rs/malachite/latest/malachite/), and its crate is [here](https://crates.io/crates/malachite).\n\nFloats (arbitrary-precision floating-point numbers) are in development and are currently experimental. They are missing many important functions. However, the floating-point functions that *are* currently implemented are thoroughly tested and documented, with the exception of string conversion functions. The current floating-point string conversion functions are incomplete and will be changed in the future to match MPFR's behavior.\n\nMalachite is developed by Mikhail Hogrefe. Thanks to 43615, b4D8, coolreader18, Dasaav-dsv, Duncan Freeman, florian1345, konstin, Rowan Hart, YunWon Jeong, Park Joon-Kyu, Antonio Mamić, OliverNChalk, Kevin Phoenix, probablykasper, shekohex, skycloudd, John Vandenberg, Brandon Weeks, and Will Youmans for additional contributions.\n\n![\"The](\"/assets/exhaustive-part-2/cantor-grid.svg\")
\n![\"The](\"/assets/exhaustive-part-2/cantor-graph.svg\")
\n![\"The](\"/assets/exhaustive-part-2/cantor-large.svg\")
\n![\"An](\"/assets/exhaustive-part-2/cantor-triples-large.svg\")
\n![\"First](\"/assets/exhaustive-part-2/interleave-bits-1.svg\")
\n![\"Final](\"/assets/exhaustive-part-2/interleave-bits-2.svg\")
\n![\"The](\"/assets/exhaustive-part-2/interleave-grid.svg\")
\n![\"The](\"/assets/exhaustive-part-2/interleave-pairs-graph.svg\")
\n![\"Bit](\"/assets/exhaustive-part-2/interleave-large.svg\")
\n![\"un-interleaving](\"/assets/exhaustive-part-2/interleave-triples-bits.svg\")
\n![\"The](\"/assets/exhaustive-part-2/interleave-triples-graph.svg\")
\n![\"Bit](\"/assets/exhaustive-part-2/interleave-triples-large.svg\")
\n![\"Valid](\"/assets/exhaustive-part-2/interleave-grid-filtered.svg\")
\n![\"The](\"/assets/denominators/sixths.svg\")
\n![\"The](\"/assets/denominators/gaps.svg\")
\n![\"A](\"/assets/denominators/gap-graph.svg\")
\n![\"A](\"/assets/denominators/j-graph.svg\")
\n![\"A](\"/assets/denominators/gap-and-bound-graph.svg\")
\n![\"Logo\"](\"/assets/logo-and-name.svg\"){kind=logo}
\r\n![\"Rational](\"/assets/benchmarks/2022-06-04-q-add.svg\")
\n![\"Natural](\"/assets/benchmarks/2022-06-04-n-to_string.svg\")
\n![\"Natural](\"/assets/benchmarks/2022-06-04-n-mul.svg\")
\n![\"Natural](\"/assets/benchmarks/2022-06-04-n-mul-small.svg\")
\n![\"Natural](\"/assets/benchmarks/2022-06-04-n-add.svg\")
\n