Year 2021 Day 18 documentation plus day 17 fixes.

Author: maneatingape

src/year2021/day17.rs

@@ -7,7 +7,7 @@
 //! For example launching a probe at a y-velocity of 5 initially,
 //! would result in a  speed and y-position:
 //!
-//! ```
+//! ```text
 //!     Time:       0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12
 //!     Speed:      5,  4,  3,  2,  1,  0, -1, -2, -3, -4, -5, -6, -7
 //!     Y-Position: 0,  5,  9, 12, 14, 15, 15, 14, 12,  9,  5,  0, -6
@@ -31,7 +31,8 @@
 //! counts how many are still in the target area at time `t`.
 //!
 //! For example using the sample `target area: x=20..30, y=-10..-5` gives a progression:
-//! ```
+//!
+//! ```text
 //!     X-Velocity : 6
 //!     Time:        0,  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20
 //!     New:         0,  0, 0, 0, 0, 1, 0, 0, 0, 0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0
@@ -59,7 +60,8 @@
 //! this happens we add *both* `new` and `continuing` to the total. For subsequent times while we're
 //! still in the target area we add only the `new` values, as the `continuing` are trajectories
 //! that we've already considered. For example for an initial y-velocity of 0:
-//! ```
+//!
+//! ```text
 //!     Time:       0,   1,   2,     3,   4
 //!     Speed:      0,  -1,  -2,    -3,  -4
 //!     Y-Position: 0,  -1,  -3,    -6, -10

src/year2021/day18.rs

@@ -1,10 +1,48 @@
+//! # Snailfish
+//!
+//! The key observation is that snailfish numbers represent
+//! [binary trees](https://en.wikipedia.org/wiki/Binary_tree).
+//!
+//! For example the first four sample numbers on the problem description look like the following
+//! in binary tree form:
+//!
+//! ```text
+//! [1,2]    [[1,2],3]    [9,[8,7]]    [[1,9],[8,5]]
+//!   ■          ■            ■              ■
+//!  / \        / \          / \           /   \
+//! 1   2      ■   3        9   ■         ■     ■
+//!           / \              / \       / \   / \
+//!          1   2            8   7     1   9 8   5
+//! ```
+//!
+//! The addition rules have an important consequence. Exploding removes two leaf nodes at depth 5
+//! and moves them to neighbouring nodes. Since exploding repeatedly happens before splitting until
+//! there are no more values at depth 5 this means that the tree will never exceed a depth of 5.
+//!
+//! Each level of a tree can contain up to 2ⁿ nodes, so the maximum size of a snailfish tree is
+//! 1 + 2 + 4 + 8 + 16 + 32 = 2⁶-1 = 63 nodes.
+//!
+//! This means that we can store each snailfish number as an implicit data structure in a fixed size
+//! array. This is faster, smaller and more convenient than using a traditional struct with pointers.
+//! The root node is stored at index 0. For a node at index `i` its left child is at index
+//! `2i + 1`, right child at index `2i + 2` and parent at index `i / 2`. As leaf nodes are
+//! always greater than or equal to zero, `-1` is used as a special sentinel value for non-leaf nodes.
+
 type Snailfish = [i32; 63];
 
+/// The indices for [in-order traversal](https://en.wikipedia.org/wiki/Tree_traversal) of the first
+/// 4 levels of the implicit binary tree stored in an array.
 const IN_ORDER: [usize; 30] = [
     1, 3, 7, 15, 16, 8, 17, 18, 4, 9, 19, 20, 10, 21, 22, 2, 5, 11, 23, 24, 12, 25, 26, 6, 13, 27,
     28, 14, 29, 30,
 ];
 
+/// Parse a snailfish number into an implicit binary tree stored in an array.
+///
+/// Since no number will greater than 9 initially we can consider each character individually.
+/// `[` means moves down a level to parse children, `,` means move from left to right node,
+/// `]` means move up a level to return to parent and a digit from 0-9 creates a leaf node
+/// with that value.
 pub fn parse(input: &str) -> Vec<Snailfish> {
     fn helper(bytes: &[u8]) -> Snailfish {
         let mut tree = [-1; 63];
@@ -24,11 +62,14 @@ pub fn parse(input: &str) -> Vec<Snailfish> {
     input.lines().map(|line| helper(line.as_bytes())).collect()
 }
 
+/// Add all snailfish numbers, reducing to a single magnitude.
 pub fn part1(input: &[Snailfish]) -> i32 {
     let mut sum = input.iter().copied().reduce(|acc, n| add(&acc, &n)).unwrap();
     magnitude(&mut sum)
 }
 
+/// Find the largest magnitude of any two snailfish numbers, remembering that snailfish addition
+/// is *not* commutative.
 pub fn part2(input: &[Snailfish]) -> i32 {
     let mut result = 0;
 
@@ -43,6 +84,14 @@ pub fn part2(input: &[Snailfish]) -> i32 {
     result
 }
 
+/// Add two snailfish numbers.
+///
+/// The initial step creates a new root node then makes the numbers the left and right children
+/// of this new root node, by copying the respective ranges of the implicit trees.
+///
+/// We can optimize the rules a little. This initial combination is the only time that more than one
+/// pair will be 4 levels deep simultaneously, so we can sweep from left to right on all possible
+/// leaf nodes in one pass.
 fn add(left: &Snailfish, right: &Snailfish) -> Snailfish {
     let mut tree = [-1; 63];
 
@@ -66,10 +115,19 @@ fn add(left: &Snailfish, right: &Snailfish) -> Snailfish {
     tree
 }
 
+/// Explode a specific pair identified by an index.
+///
+/// Storing the tree as an implicit structure has a nice benefit that finding the next left or right
+/// node is straightforward. We first move to the next left or right leaf node by adding or
+/// subtracting one to the index. If this node is empty then we move to the parent node until we
+/// find a leaf node.
+///
+/// The leaf node at index 31 has no possible nodes to the left and similarly the leaf node at
+/// index 62 has no possible nodes to the right.
 fn explode(tree: &mut Snailfish, pair: usize) {
     if pair > 31 {
         let mut i = pair - 1;
-        while i > 0 {
+        loop {
             if tree[i] >= 0 {
                 tree[i] += tree[pair];
                 break;
@@ -80,7 +138,7 @@ fn explode(tree: &mut Snailfish, pair: usize) {
 
     if pair < 61 {
         let mut i = pair + 2;
-        while i > 0 {
+        loop {
             if tree[i] >= 0 {
                 tree[i] += tree[pair + 1];
                 break;
@@ -94,6 +152,12 @@ fn explode(tree: &mut Snailfish, pair: usize) {
     tree[(pair - 1) / 2] = 0;
 }
 
+/// Split a node into two child nodes.
+///
+/// Search the tree in an *in-order* traversal, splitting the first node over `10` found (if any).
+/// We can optimize the rules by immediately exploding if this results in a node 4 levels deep,
+/// as we know that the prior optimzation in the [`add`] function means that this is the only
+/// explosion possible.
 fn split(tree: &mut Snailfish) -> bool {
     for &i in IN_ORDER.iter() {
         if tree[i] >= 10 {
@@ -110,6 +174,10 @@ fn split(tree: &mut Snailfish) -> bool {
     false
 }
 
+/// Calculate the magnitude of a snailfish number in place without using recursion.
+///
+/// This operation is destructive but much faster than using a recursive approach and acceptable
+/// as we no longer need the original snailfish number afterwards.
 fn magnitude(tree: &mut Snailfish) -> i32 {
     for i in (0..31).rev() {
         if tree[i] == -1 {