HungarianMapper

Optimal mapping using Hungarian algorithm.

Uses the Hungarian (Munkres) algorithm for globally optimal assignment. Minimizes total distance across all pairings, unlike greedy matching which may get stuck in local minima. Algorithm: 1. Build cost matrix of distances between all item pairs 2. For N!=M cases, replicate items to create square matrix 3. Apply Hungarian algorithm to find minimum-cost perfect matching 4. Map assignments back to original items For N>M (merging): Multiple start items morph to same end item For N<M (splitting): Same start item morphs to multiple end items For N=M: Direct optimal 1:1 assignment Advantages over greedy: - Globally optimal (minimum total distance) - Better results when items are clustered or evenly spaced - More predictable behavior Disadvantages: - Slower: O(n^3) vs O(n^2) for greedy - Requires scipy (optional dependency) Requires: scipy.optimize.linear_sum_assignment

HungarianMapper(args, kwargs)

map(
    start_items: List[T],
    end_items: List[T],
    get_position: Callable[[T], Point2D]
) -> List[Match[T]]