Edge types

[cmalinmayor]

Remove hyperedges and implement edge types - Continuation, Merge, and Split edges.
Closes #127 , closes #107 , closes #104

New Features:

• All edges keep an EdgeSelected variable, but also have EdgeSplit (1 iff the source node is a split), EdgeMerge (1 iff the target node is a merge), and EdgeContinuation (1 iff not [split or merge]). Create new variables for types of links (replace hyperdges) #127
• EdgeSplitPair variable and SymmetricDivision cost added, as an example of how to use the new edge types Add symmetric division cost #107
• Docs updates - extending docs use EdgeContinuation to implement curvature, reference SymmetricDivision.

Breaking changes:

• Hyperedges completely removed - anything that tried to pass in hyperedges will now treat those as normal edges and fail when the position is missing Revisit hyperedge representation #104
• EdgeDistance only operates on Continuation edges (not merge or split). EdgeSelection Cost still exists and applies to all edges.

Questions about naming:

1. EdgeSplitCost and EdgeMergeCost have "Cost" at the end, becuase the variables are already called EdgeSplit and EdgeMerge. We were not putting "Cost" at the end of any of the other costs.
   Options:
   a. Variable and Cost share the same name: EdgeSplit, EdgeMerge. We never expose in the global namespace, and users don't access variables directly unless they are extending a custom cost. Then, the usage would be from motile import variables; variables.EdgeSplit(...)
   b. Keep Cost at the end of the Costs -> EdgeSplitCost, EdgeMergeCost - Hate this one but it is clear
   c. Add "Var" or something at the end of the variables. This avoids any possible name collision, keeps Costs clean as the most commonly used API, and isn't too messy/long.
2. The node split and merge costs are called "Split" and "Merge" which is a little ambiguous now. We could update those to be consistent with whatever we decide for EdgeSplit and EdgeMerge, or leave them.
3. If we choose 1a or 1c, do we add the suffix to ALL costs/variables?

Question about TrackingGraph:
Now that we have removed hyperedges, is there still a reason to store local node and edge dicts isntead of a networkx graph, which is essentially node and edge dicts?

[cmalinmayor]

Upon further discussion about API with Jan, it is too difficult to support generic EdgeGroups, because it breaks the singleton Variable pattern. Instead, the user can just directly specify the groups they want by creating a new variable, as with the continuation cost. (Alternatively, we could have a factory function that makes the variable and cost... but this is not necessary). The tricky part is just defining the edge semantics so that we can attach the costs specifically to continuation, or division.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.14%. Comparing base (3d9b07f) to head (a95f1f7).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #160      +/-   ##
==========================================
+ Coverage   93.91%   96.14%   +2.23%     
==========================================
  Files          32       38       +6     
  Lines         805      909     +104     
==========================================
+ Hits          756      874     +118     
+ Misses         49       35      -14     

☔ View full report in Codecov by Sentry.
📢 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.