munkres 2.0.0__py3-none-any.whl

munkres/__init__.py

@@ -0,0 +1,104 @@
+# Copyright (c) 2008-2020 Brian M. Clapper (original author)
+# Copyright (c) 2026 Eishit Nigam (modifications for 2.x)
+# Licensed under the Apache License, Version 2.0. See LICENSE.md and NOTICE.
+"""
+Munkres: the Hungarian (Kuhn-Munkres) algorithm for the assignment problem.
+
+Given a cost for every (row, column) pairing, find the one-to-one assignment
+with the lowest total cost::
+
+    >>> from munkres import Munkres
+    >>> cost = [[4, 1, 3],
+    ...         [2, 0, 5],
+    ...         [3, 2, 2]]
+    >>> Munkres().compute(cost)
+    [(0, 1), (1, 0), (2, 2)]
+
+Forbid a pairing with `DISALLOWED`; turn a profit matrix into a cost matrix
+with `make_cost_matrix`. If the forbidden cells make a complete assignment
+impossible, `UnsolvableMatrix` is raised at once (it never hangs).
+
+The package has no runtime dependencies. numpy arrays and pandas DataFrames
+are accepted as input if you have them, and are never modified.
+"""
+
+from munkres._analysis import (
+    Prices,
+    bottleneck,
+    counterfactual,
+    k_best,
+    shadow_prices,
+    tolerance,
+)
+from munkres._api import (
+    Assignment,
+    Diagnosis,
+    build_cost_matrix,
+    diagnose,
+    linear_sum_assignment,
+    solve,
+)
+from munkres._core import (
+    DISALLOWED,
+    DISALLOWED_OBJ,
+    DISALLOWED_PRINTVAL,
+    AnyNum,
+    Cell,
+    Matrix,
+    MatrixLike,
+    Munkres,
+    Number,
+    UnsolvableMatrix,
+    make_cost_matrix,
+    print_matrix,
+)
+from munkres._extras import (
+    SinkhornResult,
+    Transport,
+    sinkhorn,
+    soft_assignment,
+    stable_matching,
+    transport,
+)
+from munkres._trace import Trace
+
+__all__ = [
+    "DISALLOWED",
+    "DISALLOWED_OBJ",
+    "DISALLOWED_PRINTVAL",
+    "AnyNum",
+    "Assignment",
+    "Cell",
+    "Diagnosis",
+    "Matrix",
+    "MatrixLike",
+    "Munkres",
+    "Number",
+    "Prices",
+    "SinkhornResult",
+    "Trace",
+    "Transport",
+    "UnsolvableMatrix",
+    "bottleneck",
+    "build_cost_matrix",
+    "counterfactual",
+    "diagnose",
+    "k_best",
+    "linear_sum_assignment",
+    "make_cost_matrix",
+    "print_matrix",
+    "shadow_prices",
+    "sinkhorn",
+    "soft_assignment",
+    "solve",
+    "stable_matching",
+    "tolerance",
+    "transport",
+]
+
+__version__ = "2.0.0"
+__author__ = "Brian Clapper, bmc@clapper.org"
+__maintainer__ = "Eishit Nigam"
+__url__ = "https://github.com/iameishit/Paldita-munkres"
+__copyright__ = "(c) 2008-2020 Brian M. Clapper; (c) 2026 Eishit Nigam"
+__license__ = "Apache-2.0"

munkres/__main__.py

@@ -0,0 +1,64 @@
+# Copyright (c) 2008-2020 Brian M. Clapper; (c) 2026 Eishit Nigam
+# Licensed under the Apache License, Version 2.0. See LICENSE.md and NOTICE.
+"""``python -m munkres`` -- with no arguments, solve a set of built-in example
+matrices and check each answer against its known optimum (an installation smoke
+test); with arguments, the command line interface (see ``python -m munkres -h``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from munkres import DISALLOWED, Munkres, print_matrix
+
+D = DISALLOWED
+
+EXAMPLES: list[tuple[list[list[Any]], float]] = [
+    # Square
+    ([[400, 150, 400], [400, 450, 600], [300, 225, 300]], 850),
+    # Rectangular variant
+    ([[400, 150, 400, 1], [400, 450, 600, 2], [300, 225, 300, 3]], 452),
+    # Square
+    ([[10, 10, 8], [9, 8, 1], [9, 7, 4]], 18),
+    # Square variant with floating point value
+    ([[10.1, 10.2, 8.3], [9.4, 8.5, 1.6], [9.7, 7.8, 4.9]], 19.5),
+    # Rectangular variant
+    ([[10, 10, 8, 11], [9, 8, 1, 1], [9, 7, 4, 10]], 15),
+    # Rectangular variant with floating point value
+    ([[10.01, 10.02, 8.03, 11.04], [9.05, 8.06, 1.07, 1.08], [9.09, 7.1, 4.11, 10.12]], 15.2),
+    # Rectangular with DISALLOWED
+    ([[4, 5, 6, D], [1, 9, 12, 11], [D, 5, 4, D], [12, 12, 12, 10]], 20),
+    # Rectangular variant with DISALLOWED and floating point value
+    (
+        [
+            [4.001, 5.002, 6.003, D],
+            [1.004, 9.005, 12.006, 11.007],
+            [D, 5.008, 4.009, D],
+            [12.01, 12.011, 12.012, 10.013],
+        ],
+        20.028,
+    ),
+    # DISALLOWED to force pairings
+    ([[1, D, D, D], [D, 2, D, D], [D, D, 3, D], [D, D, D, 4]], 10),
+    # DISALLOWED to force pairings with floating point value
+    ([[1.1, D, D, D], [D, 2.2, D, D], [D, D, 3.3, D], [D, D, D, 4.4]], 11.0),
+]
+
+
+def main() -> None:
+    solver = Munkres()
+    for cost_matrix, expected_total in EXAMPLES:
+        print_matrix(cost_matrix, msg="cost matrix")
+        total_cost: Any = 0
+        for r, c in solver.compute(cost_matrix):
+            value = cost_matrix[r][c]
+            total_cost += value
+            print(f"({r}, {c}) -> {value}")
+        print(f"lowest cost={total_cost}")
+        if expected_total != total_cost:
+            raise SystemExit(f"self-check failed: expected {expected_total}, got {total_cost}")
+
+
+if __name__ == "__main__":
+    from munkres.cli import main as cli_main
+
+    raise SystemExit(cli_main())

munkres/_analysis.py

@@ -0,0 +1,185 @@
+# Copyright (c) 2026 Eishit Nigam. Licensed under the Apache License, Version 2.0.
+"""Analysis of an assignment problem: prices, what-ifs, runners-up, bottleneck."""
+
+from __future__ import annotations
+
+import heapq
+import itertools
+from dataclasses import dataclass
+from typing import Any
+
+from munkres._api import Assignment, _make_assignment, _negated, solve
+from munkres._core import (
+    DISALLOWED,
+    MatrixLike,
+    UnsolvableMatrix,
+    _as_lists,
+    _assign,
+    _validated_edges,
+)
+
+__all__ = ["Prices", "bottleneck", "counterfactual", "k_best", "shadow_prices", "tolerance"]
+
+
+@dataclass(frozen=True)
+class Prices:
+    """
+    LP dual variables of the assignment problem ("shadow prices").
+
+    For every allowed cell, `cost[i][j] >= row_prices[i] + col_prices[j]`, with
+    equality on every pair of the optimal assignment, and
+    `total == sum(row_prices) + sum(col_prices) ==` the optimal cost. That
+    equality is a *proof of optimality* anyone can re-check in O(rows * columns).
+    A row price says how much one more unit of "demand" at that row would cost.
+    """
+
+    row_prices: tuple[Any, ...]
+    col_prices: tuple[Any, ...]
+    total: Any
+
+
+def shadow_prices(matrix: MatrixLike) -> Prices:
+    """Solve the problem and return its dual variables (see `Prices`)."""
+    n_rows, n_cols, edges = _validated_edges(matrix)
+    duals: list[Any] = []
+    _assign(n_rows, n_cols, edges, duals=duals)
+    u, v = duals
+    rows_p, cols_p = (u, v) if n_rows <= n_cols else (v, u)
+    return Prices(tuple(rows_p), tuple(cols_p), sum(rows_p) + sum(cols_p))
+
+
+def _check_cell(matrix: list[list[Any]], row: int, col: int) -> None:
+    n_rows, n_cols, edges = _validated_edges(matrix)
+    if not (0 <= row < n_rows and 0 <= col < n_cols):
+        raise ValueError(f"cell ({row}, {col}) is outside the {n_rows}x{n_cols} matrix")
+    if all(c != col for c, _ in edges[row]):
+        raise ValueError(f"cell ({row}, {col}) is forbidden")
+
+
+def counterfactual(matrix: MatrixLike, row: int, col: int) -> Any:
+    """
+    "What would it cost to force `row` onto `col`?" Returns how much the optimal
+    total rises if that pair is made mandatory (0 if some optimal assignment
+    already contains it). Raises `UnsolvableMatrix` if forcing it makes the
+    problem impossible, and `ValueError` for a forbidden or out-of-range cell.
+    """
+    rows = _as_lists(matrix)
+    _check_cell(rows, row, col)
+    best = solve(rows).total
+    forced = [list(r) for r in rows]
+    for j in range(len(rows[0])):
+        if j != col:
+            forced[row][j] = DISALLOWED
+    for i in range(len(rows)):
+        if i != row:
+            forced[i][col] = DISALLOWED
+    return solve(forced).total - best
+
+
+def tolerance(matrix: MatrixLike, row: int, col: int) -> Any:
+    """
+    How much can the cost of a pair in the optimal assignment *rise* before the
+    assignment has to change? (the optimum without that pair, minus the optimum).
+    `float('inf')` if the pair can never be replaced. `ValueError` if the pair is
+    not in the assignment `solve` returns.
+    """
+    rows = _as_lists(matrix)
+    _check_cell(rows, row, col)
+    chosen = solve(rows)
+    if (row, col) not in chosen.pairs:
+        raise ValueError(f"({row}, {col}) is not in the optimal assignment")
+    without = [list(r) for r in rows]
+    without[row][col] = DISALLOWED
+    try:
+        return solve(without).total - chosen.total
+    except UnsolvableMatrix:
+        return float("inf")
+
+
+def k_best(matrix: MatrixLike, k: int, *, maximize: bool = False) -> list[Assignment]:
+    """
+    The `k` best complete assignments, best first (Murty's algorithm). Fewer are
+    returned if fewer exist. Each is a distinct set of pairs; ties are ordered
+    arbitrarily.
+    """
+    if k < 0:
+        raise ValueError("k must be >= 0")
+    original = _as_lists(matrix)
+    work = _negated(original) if maximize else original
+    n_rows, n_cols, _ = _validated_edges(work)
+    found: list[Assignment] = []
+    if k == 0:
+        return found
+
+    def constrained(forbid: tuple[tuple[int, int], ...], force: tuple[tuple[int, int], ...]) -> Any:
+        grid = [list(r) for r in work]
+        for i, j in forbid:
+            grid[i][j] = DISALLOWED
+        for i, j in force:
+            for jj in range(n_cols):
+                if jj != j:
+                    grid[i][jj] = DISALLOWED
+            for ii in range(n_rows):
+                if ii != i:
+                    grid[ii][j] = DISALLOWED
+        try:
+            return solve(grid)
+        except UnsolvableMatrix:
+            return None
+
+    counter = itertools.count()
+    heap: list[Any] = []
+    first = constrained((), ())
+    if first is not None:
+        heapq.heappush(heap, (first.total, next(counter), first, (), ()))
+    while heap and len(found) < k:
+        _, _, node, forbid, force = heapq.heappop(heap)
+        pairs = list(node.pairs)
+        found.append(_make_assignment(original, pairs, (n_rows, n_cols), maximize=maximize))
+        for t, pair in enumerate(pairs):
+            child_force = force + tuple(pairs[:t])
+            child_forbid = (*forbid, pair)
+            child = constrained(child_forbid, child_force)
+            if child is not None:
+                heapq.heappush(heap, (child.total, next(counter), child, child_forbid, child_force))
+    return found
+
+
+def bottleneck(matrix: MatrixLike, *, maximize: bool = False) -> Assignment:
+    """
+    The assignment whose *single worst pair* is as good as possible (minimise the
+    largest cost; with `maximize=True`, maximise the smallest profit). Among
+    assignments that tie on the worst pair, the lowest total (highest, when
+    maximising) wins. Good for fairness: "nobody gets a terrible job".
+    Raises `UnsolvableMatrix` if no complete assignment exists.
+    """
+    original = _as_lists(matrix)
+    work = _negated(original) if maximize else original
+    n_rows, n_cols, edges = _validated_edges(work)
+    shape = (n_rows, n_cols)
+    values = sorted({c for allowed in edges for _, c in allowed})
+    if not values:
+        _assign(n_rows, n_cols, edges)  # raises if rows exist but nothing is allowed
+        return _make_assignment(original, [], shape, maximize=maximize)
+
+    def capped(limit: Any) -> list[list[tuple[int, Any]]]:
+        return [[(j, c) for j, c in allowed if c <= limit] for allowed in edges]
+
+    def feasible(limit: Any) -> bool:
+        try:
+            _assign(n_rows, n_cols, capped(limit))
+        except UnsolvableMatrix:
+            return False
+        return True
+
+    if not feasible(values[-1]):
+        _assign(n_rows, n_cols, edges)  # raise the real, explanatory error
+    lo, hi = 0, len(values) - 1
+    while lo < hi:
+        mid = (lo + hi) // 2
+        if feasible(values[mid]):
+            hi = mid
+        else:
+            lo = mid + 1
+    pairs = _assign(n_rows, n_cols, capped(values[lo]))
+    return _make_assignment(original, pairs, shape, maximize=maximize)

munkres/_api.py

@@ -0,0 +1,298 @@
+# Copyright (c) 2026 Eishit Nigam. Licensed under the Apache License, Version 2.0.
+"""The 2.x high-level API: `solve`, `Assignment`, `diagnose`, `linear_sum_assignment`."""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from munkres._core import (
+    _INF,
+    _NUMBER_TYPES,
+    DISALLOWED,
+    MatrixLike,
+    UnsolvableMatrix,
+    _as_lists,
+    _assign,
+    _validated_edges,
+)
+from munkres._trace import Trace
+
+__all__ = [
+    "Assignment",
+    "Diagnosis",
+    "build_cost_matrix",
+    "diagnose",
+    "linear_sum_assignment",
+    "solve",
+]
+
+_A = TypeVar("_A")
+_B = TypeVar("_B")
+_NO_PAIRS: Any = object()  # sentinel: a threshold so strict that nothing can be matched
+
+
+@dataclass(frozen=True)
+class Assignment:
+    """
+    The result of `solve`.
+
+    - `pairs`: the matched `(row, column)` index pairs, sorted by row
+    - `total`: the sum of *your original* matrix values over `pairs`
+      (the total cost, or the total profit when `maximize=True`)
+    - `unmatched_rows` / `unmatched_cols`: indexes left without a partner
+      (always the surplus side of a rectangular matrix, plus anything gated out)
+    - `shape`: `(rows, columns)` of the input
+    - `row_labels` / `col_labels`: the DataFrame's index / columns, if you passed one
+    - `trace`: a `Trace` if you asked for one
+
+    Iterating an `Assignment` yields its pairs, so it can stand in for the list
+    `Munkres().compute()` returns. Note that an empty one is falsy.
+    """
+
+    pairs: tuple[tuple[int, int], ...]
+    total: Any
+    unmatched_rows: tuple[int, ...]
+    unmatched_cols: tuple[int, ...]
+    shape: tuple[int, int]
+    maximize: bool = False
+    row_labels: tuple[Any, ...] | None = None
+    col_labels: tuple[Any, ...] | None = None
+    trace: Trace | None = None
+
+    def __iter__(self) -> Iterator[tuple[int, int]]:
+        return iter(self.pairs)
+
+    def __len__(self) -> int:
+        return len(self.pairs)
+
+    @property
+    def rows(self) -> tuple[int, ...]:
+        """Matched row indexes, in order (like SciPy's `row_ind`)."""
+        return tuple(r for r, _ in self.pairs)
+
+    @property
+    def cols(self) -> tuple[int, ...]:
+        """Matched column indexes, aligned with `rows` (like SciPy's `col_ind`)."""
+        return tuple(c for _, c in self.pairs)
+
+    def as_dict(self) -> dict[int, int]:
+        """`{row: column}` for every matched row."""
+        return dict(self.pairs)
+
+    def labelled(self) -> list[tuple[Any, Any]]:
+        """The pairs as `(row label, column label)`; plain indexes if there are no labels."""
+        return [
+            (
+                self.row_labels[r] if self.row_labels is not None else r,
+                self.col_labels[c] if self.col_labels is not None else c,
+            )
+            for r, c in self.pairs
+        ]
+
+
+@dataclass(frozen=True)
+class Diagnosis:
+    """Why a matrix has no complete assignment (a violation of Hall's condition)."""
+
+    message: str
+    rows: tuple[int, ...]
+    cols: tuple[int, ...]
+
+
+def _negated(rows: list[list[Any]]) -> list[list[Any]]:
+    """Profit -> cost by negation (exact for int, Fraction and Decimal)."""
+    out: list[list[Any]] = []
+    for i, row in enumerate(rows):
+        new: list[Any] = []
+        for j, value in enumerate(row):
+            if value is DISALLOWED or not isinstance(value, _NUMBER_TYPES):
+                new.append(value)  # forbidden, or a TypeError for validation to report
+                continue
+            try:
+                infinite_profit = value == _INF
+            except ArithmeticError:  # Decimal('sNaN'): validation reports it
+                new.append(value)
+                continue
+            if infinite_profit:
+                raise ValueError(
+                    f"cell [{i}][{j}] is +infinity, which has no defined assignment value "
+                    "(use -inf or DISALLOWED to forbid a pairing)"
+                )
+            new.append(-value)
+        out.append(new)
+    return out
+
+
+def _gate(threshold: Any, *, maximize: bool) -> Any:
+    """Turn the user's threshold into a cost-space gate (None = no gating)."""
+    if threshold is None:
+        return None
+    name = "min_profit" if maximize else "max_cost"
+    if not isinstance(threshold, _NUMBER_TYPES):
+        raise TypeError(f"{name} must be a number, got {threshold!r}")
+    if threshold != threshold:  # noqa: PLR0124
+        raise ValueError(f"{name} is NaN")
+    gate = -threshold if maximize else threshold
+    if gate == _INF:
+        return None
+    if gate == -_INF:
+        return _NO_PAIRS
+    return gate
+
+
+def _labels(matrix: Any) -> tuple[tuple[Any, ...] | None, tuple[Any, ...] | None]:
+    index: Any = getattr(matrix, "index", None)
+    columns: Any = getattr(matrix, "columns", None)
+    if hasattr(index, "tolist") and hasattr(columns, "tolist"):  # a DataFrame, not a list
+        return tuple(index.tolist()), tuple(columns.tolist())
+    return None, None
+
+
+def solve(
+    matrix: MatrixLike,
+    *,
+    maximize: bool = False,
+    max_cost: Any = None,
+    min_profit: Any = None,
+    trace: bool = False,
+) -> Assignment:
+    """
+    Solve an assignment problem and describe the answer.
+
+    **Parameters**
+
+    - `matrix`: costs (or profits, with `maximize=True`) as nested sequences, a
+      numpy array or a pandas DataFrame. `DISALLOWED` and `+inf` (`-inf` when
+      maximising) forbid a pairing.
+    - `maximize`: maximise the total instead of minimising it. Exact for int,
+      `Fraction` and `Decimal`, because values are negated rather than subtracted
+      from a maximum.
+    - `max_cost`: **gating** (minimising only). Pairs costing more than this are
+      never made, and a row may be left unmatched instead. The result minimises
+      the cost of the pairs made plus `max_cost` for every row left unmatched, so
+      a pair is only worth making if it costs less than `max_cost`. A pair
+      costing exactly `max_cost` is a tie with leaving the row unmatched. With
+      gating a matrix can never be unsolvable.
+    - `min_profit`: the same gate when `maximize=True`: pairs earning less than
+      this are never made.
+    - `trace`: record the solver's steps in `Assignment.trace`.
+
+    **Raises**
+
+    - `UnsolvableMatrix`: forbidden cells make a complete assignment impossible
+      (not possible with gating)
+    - `ValueError`: ragged matrix, `NaN`, an infinite value with no meaning, a
+      threshold that does not fit the mode
+    - `TypeError`: a non-numeric cell or threshold
+    """
+    if maximize and max_cost is not None:
+        raise ValueError("max_cost is for minimising; use min_profit with maximize=True")
+    if not maximize and min_profit is not None:
+        raise ValueError("min_profit needs maximize=True; use max_cost when minimising")
+    gate = _gate(min_profit if maximize else max_cost, maximize=maximize)
+
+    row_labels, col_labels = _labels(matrix)
+    original = _as_lists(matrix)
+    n_rows, n_cols, edges = _validated_edges(_negated(original) if maximize else original)
+
+    recorder = Trace(shape=(n_rows, n_cols)) if trace else None
+    if gate is _NO_PAIRS:
+        pairs: list[tuple[int, int]] = []
+        if recorder is not None:
+            recorder.events.append({"event": "done", "pairs": []})
+    else:
+        pairs = _assign(n_rows, n_cols, edges, gate=gate, trace=recorder)
+
+    return _make_assignment(
+        original, pairs, (n_rows, n_cols), maximize=maximize,
+        labels=(row_labels, col_labels), trace=recorder,
+    )  # fmt: skip
+
+
+def _make_assignment(
+    original: list[list[Any]],
+    pairs: list[tuple[int, int]],
+    shape: tuple[int, int],
+    *,
+    maximize: bool,
+    labels: tuple[tuple[Any, ...] | None, tuple[Any, ...] | None] = (None, None),
+    trace: Trace | None = None,
+) -> Assignment:
+    n_rows, n_cols = shape
+    matched_rows = {r for r, _ in pairs}
+    matched_cols = {c for _, c in pairs}
+    return Assignment(
+        pairs=tuple(pairs),
+        total=sum(original[r][c] for r, c in pairs),
+        unmatched_rows=tuple(i for i in range(n_rows) if i not in matched_rows),
+        unmatched_cols=tuple(j for j in range(n_cols) if j not in matched_cols),
+        shape=shape,
+        maximize=maximize,
+        row_labels=labels[0],
+        col_labels=labels[1],
+        trace=trace,
+    )
+
+
+def diagnose(matrix: MatrixLike, *, maximize: bool = False) -> Diagnosis | None:
+    """
+    Explain why a matrix cannot be solved, without raising.
+
+    Returns `None` if a complete assignment exists. Otherwise returns a
+    `Diagnosis` naming rows that can only use too few columns (or the reverse for
+    a tall matrix), which is exactly Hall's marriage-theorem violation.
+    """
+    original = _as_lists(matrix)
+    n_rows, n_cols, edges = _validated_edges(_negated(original) if maximize else original)
+    try:
+        _assign(n_rows, n_cols, edges)
+    except UnsolvableMatrix as bad:
+        return Diagnosis(str(bad), bad.rows, bad.cols)
+    return None
+
+
+def linear_sum_assignment(cost_matrix: MatrixLike, maximize: bool = False) -> tuple[Any, Any]:
+    """
+    A drop-in for `scipy.optimize.linear_sum_assignment`: returns
+    `(row_ind, col_ind)`, sorted by row.
+
+    The return type follows the input: numpy arrays (and DataFrames) get numpy
+    index arrays back; anything else gets lists. As in SciPy, `+inf` forbids a
+    pairing, an infeasible matrix raises `ValueError` (here the subclass
+    `UnsolvableMatrix`), and when several optimal answers exist the one returned
+    may differ from SciPy's (the total cost is always the same).
+    """
+    try:
+        result = solve(cost_matrix, maximize=maximize)
+    except TypeError as bad:
+        raise ValueError(str(bad)) from None
+    rows, cols = list(result.rows), list(result.cols)
+    if hasattr(cost_matrix, "tolist") or hasattr(cost_matrix, "to_numpy"):
+        try:
+            np = importlib.import_module("numpy")
+        except ImportError:
+            return rows, cols
+        return np.array(rows, dtype=np.intp), np.array(cols, dtype=np.intp)
+    return rows, cols
+
+
+def build_cost_matrix(
+    rows: Iterable[_A], cols: Iterable[_B], cost: Callable[[_A, _B], Any]
+) -> list[list[Any]]:
+    """
+    Build a matrix by calling `cost(row_item, col_item)` for every pair, e.g. a
+    distance between points. If `cost` returns `None` that pairing is
+    `DISALLOWED`.
+    """
+    col_items = list(cols)
+    matrix: list[list[Any]] = []
+    for a in rows:
+        row: list[Any] = []
+        for b in col_items:
+            value = cost(a, b)
+            row.append(DISALLOWED if value is None else value)
+        matrix.append(row)
+    return matrix