Add canonical color refinement

[Abdullah-Rady]

Summary

This PR adds canonical color refinement to Graphs.jl using the partition-refinement algorithm described by Berkholz, Bonsma, and Grohe.

Color refinement repeatedly splits color classes according to the number of neighbors each vertex has in every color class. When the refining color set is sufficient, the implementation returns a canonical coloring of the unique coarsest stable partition that refines the initial coloring.

Changes

• Adds canonical_color_refinement.
• Adds color_refinement as a shorter alias.
• Supports:
  • a default unit initial coloring;
  • user-supplied initial colorings;
  • arbitrary integer color labels;
  • user-supplied refining color sets;
  • directed and undirected graphs;
  • AbstractGraph wrapper types.
• Validates initial-coloring lengths and refining colors.
• Handles empty graphs, self-loops, disconnected graphs, duplicate refining colors, and zero or negative labels.
• Adds API documentation and examples.
• Adds deterministic, randomized, edge-case, directed-graph, and canonicality tests.

Canonicality

The returned color numbers do not depend on vertex numbering.

For isomorphic graphs $G_1$ and $G_2$, with isomorphism $\sigma$, corresponding vertices receive the same output color:

$$ c_1(v) = c_2(\sigma(v)). $$

When initial colorings are supplied, they must be transported by the same isomorphism:

$$ \alpha_1(v) = \alpha_2(\sigma(v)). $$

Tests verify exact color-number preservation under vertex relabeling for both unit and nontrivial initial colorings.

Directed graphs

For directed graphs, color degrees count outgoing neighbors, following the reference's primary stability definition.

Testing

• Focused color-refinement tests pass.
• Package tests, Aqua checks, and doctests pass locally.

Reference

C. Berkholz, P. Bonsma, and M. Grohe,
Tight Lower and Upper Bounds for the Complexity of Canonical Colour Refinement
https://arxiv.org/abs/1509.08251

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.51%. Comparing base (356aa72) to head (36506dc).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #522      +/-   ##
==========================================
+ Coverage   97.46%   97.51%   +0.05%     
==========================================
  Files         127      129       +2     
  Lines        7766     7943     +177     
==========================================
+ Hits         7569     7746     +177     
  Misses        197      197              

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.