feat: Efficient LCA algorithm for the hierarchy

[aborgna-q]

Implement the lowest-common-ancestor algorithm on hierarchies, using the "binary lifting" algorithm.
This is needed for the mermaid rendering, but it's also a useful algorithm to have around. (There's already been talk of using it in hugr).

Precomputation time: O(n log d)
lca(a,b) query time: O(log d)
is_ancestor(a,b) query time: O(1)
Memory: O(n log d)

where n=#nodes and d=max depth.

There's also a constant time algorithm based on RMQ, but it doesn't tend to be much faster than this one. This impl is much simpler.

[codecov]

Codecov Report

Attention: Patch coverage is 94.84536% with 5 lines in your changes missing coverage. Please review.

Project coverage is 80.17%. Comparing base (b3c8142) to head (c63e8b1).
Report is 1 commits behind head on main.

Files	Patch %	Lines
src/algorithms/lca.rs	94.84%	3 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #138      +/-   ##
==========================================
+ Coverage   79.77%   80.17%   +0.40%     
==========================================
  Files          21       22       +1     
  Lines        5043     5140      +97     
  Branches     5043     5140      +97     
==========================================
+ Hits         4023     4121      +98     
+ Misses        949      946       -3     
- Partials       71       73       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[lmondada]

Very neat!

[lmondada]

This would be a good use case for .scan, although I'm still on the fence whether .scan can ever be easy to read... Up to you!

Suggested change

	if let Some(parent) = parent {
	let mut climb = vec![parent];
	let mut prev = parent;
	for i in 1.. {
	let Some(&u) = lca.climb_nodes[prev].get(i - 1) else {
	break;
	};
	climb.push(u);
	prev = u;
	}
	lca.climb_nodes[node] = climb;
	}
	let climb: Vec<_> = (1..)
	.scan(parent, |state, i| {
	let prev = state?;
	*state = lca.climb_nodes[prev].get(i - 1);
	Some(prev)
	})
	.collect();
	if !climb.is_empty() {
	lca.climb_nodes[node] = climb;
	}

[lmondada]

I might be taking functional style too far today, but consider (you'll need to import std::iter):

Suggested change

	loop {
	let Some(&last_climb) = self.climb_nodes[u].last() else {
	// We reached a root, and it is not an ancestor of `b`.
	return None;
	};
	if self.is_ancestor(last_climb, b) {
	// We found a `u` where the last ancestor is an ancestor of `b`.
	break;
	}
	u = last_climb;
	}
	// Find a `u` where the last ancestor is an ancestor of `b`.
	let mut u = iter::from_fn(|| {
	u = self.climb_nodes[u].last();
	u
	}).find(|last_climb| self.is_ancestor(last_climb, b))?;

[aborgna-q]

I had to modify it a bit, but I like the functional style :)

[lmondada]

I've added some comments that made it clearer for me. You could add another comment that this is binary search and that 2^i is the size of the interval the LCA must be in.

Suggested change

	// The 2^i ancestor is not an ancestor of `b`.
	// Lets update `u`.
	u = v;
	// Decrease `i`, and ensure it is within bounds.
	i = i.max(self.climb_nodes[u].len() - 1);
	// The 2^i ancestor of `u` is not an ancestor of `b` so the LCA must be between
	// the 2^i and 2^{i+1} ancestor of `u`. Hence update `u` to the 2^i ancestor.
	u = v;
	// Ensure `i` is within bounds.
	i = i.max(self.climb_nodes[u].len() - 1);

[aborgna-q]

👍
I added more comments.