ortidy 0.2.0__py3-none-any.whl

ortidy/__init__.py

@@ -0,0 +1,41 @@
+"""ortidy — operations research on tidy dataframes.
+
+A backend-agnostic (Narwhals) dataframe façade over Google OR-Tools. Solvers
+accept native frames (pandas, Polars, …), return the same backend, and hand back
+a :class:`~ortidy.result.SolveResult` carrying the result frame, a status enum,
+the objective, and solve metadata.
+"""
+
+from __future__ import annotations
+
+from ortidy import data
+from ortidy.assignment.assignment import assignment
+from ortidy.binning.bin_packing import bin_packing
+from ortidy.binning.knapsack import knapsack
+from ortidy.binning.multi_knapsack import multi_knapsack
+from ortidy.facility.facility_location import facility_location
+from ortidy.flow.flow import max_flow, min_cost_flow, shortest_path
+from ortidy.result import SolveResult, SolveStatus
+from ortidy.routing.distance import distance_matrix
+from ortidy.routing.routing import solve_routing
+from ortidy.scheduling.shift_scheduling import shift_scheduling
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "knapsack",
+    "multi_knapsack",
+    "bin_packing",
+    "assignment",
+    "max_flow",
+    "min_cost_flow",
+    "shortest_path",
+    "solve_routing",
+    "distance_matrix",
+    "shift_scheduling",
+    "facility_location",
+    "data",
+    "SolveResult",
+    "SolveStatus",
+    "__version__",
+]

ortidy/_narwhals.py

@@ -0,0 +1,62 @@
+"""Narwhals boundary helpers.
+
+The library is backend-agnostic: a user who passes pandas gets pandas back, a
+user who passes Polars gets Polars back. We accept native frames at the public
+boundary, do internal work in Narwhals, and return native frames. At the solver
+boundary we extract plain Python lists/ints/floats — OR-Tools does not consume
+dataframes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import narwhals.stable.v1 as nw
+
+ID_COLUMN_DEFAULT = "__ortidy_row_id__"
+
+
+def to_nw(frame: Any) -> nw.DataFrame:
+    """Wrap a native frame in a Narwhals DataFrame at the public boundary."""
+    return nw.from_native(frame, eager_only=True)
+
+
+def to_native(frame: nw.DataFrame) -> Any:
+    """Unwrap a Narwhals DataFrame back to the user's native backend."""
+    return frame.to_native()
+
+
+def column_to_list(frame: nw.DataFrame, column: str) -> list:
+    """Extract a column as a plain Python list (the solver-boundary handoff)."""
+    return frame.get_column(column).to_list()
+
+
+def ensure_id_column(
+    frame: nw.DataFrame, id_column: str | None
+) -> tuple[nw.DataFrame, str, bool]:
+    """Guarantee an explicit row-identity column (no implicit positional index).
+
+    If ``id_column`` is given it must exist. If ``None`` we synthesize a stable
+    integer id column, honoring the index-free model: identity is always an
+    explicit column, never a positional index.
+
+    Returns:
+        ``(frame, id_column_name, was_synthesized)``.
+    """
+    if id_column is not None:
+        if id_column not in frame.columns:
+            raise KeyError(
+                f"id column {id_column!r} not found; columns are {frame.columns}"
+            )
+        return frame, id_column, False
+    frame = frame.with_row_index(name=ID_COLUMN_DEFAULT)
+    return frame, ID_COLUMN_DEFAULT, True
+
+
+def drop_if_synthesized(
+    frame: nw.DataFrame, id_column: str, was_synthesized: bool
+) -> nw.DataFrame:
+    """Drop the helper id column if we created it ourselves."""
+    if was_synthesized and id_column in frame.columns:
+        return frame.drop(id_column)
+    return frame

ortidy/_scaling.py

@@ -0,0 +1,58 @@
+"""Unit-scaling layer for integer-only solvers.
+
+OR-Tools' knapsack solver (and CP-SAT) require integer coefficients, but real
+data has floats. We scale floats to ints, solve, and unscale, rather than
+silently truncating floats at the solver boundary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+# Default precision: 6 significant fractional digits. Chosen to stay well within
+# 63-bit integer range for realistically-sized coefficients.
+_DEFAULT_MAX_FACTOR = 10**6
+
+
+def _all_integral(values: Sequence[float]) -> bool:
+    return all(float(v).is_integer() for v in values)
+
+
+def choose_factor(
+    values: Sequence[float], *, max_factor: int = _DEFAULT_MAX_FACTOR
+) -> int:
+    """Pick an integer scale factor (a power of ten) for ``values``.
+
+    Returns ``1`` when every value is already integral, otherwise the smallest
+    power of ten (capped at ``max_factor``) that renders the values integral.
+    """
+    if not values or _all_integral(values):
+        return 1
+    factor = 1
+    while factor < max_factor:
+        factor *= 10
+        if _all_integral([v * factor for v in values]):
+            return factor
+    return max_factor
+
+
+def scale_to_int(
+    values: Sequence[float], *, factor: int | None = None
+) -> tuple[list[int], int]:
+    """Scale floats to ints.
+
+    Args:
+        values: The float (or int) sequence to scale.
+        factor: An explicit scale factor; if ``None`` it is chosen automatically.
+
+    Returns:
+        ``(scaled_ints, factor)`` where ``scaled_ints[i] == round(values[i] * factor)``.
+    """
+    if factor is None:
+        factor = choose_factor(values)
+    return [round(v * factor) for v in values], factor
+
+
+def unscale(value: float, factor: int) -> float:
+    """Invert :func:`scale_to_int` for a single (objective) value."""
+    return value / factor if factor != 1 else value

ortidy/assignment/__init__.py

@@ -0,0 +1,5 @@
+"""Assignment solvers (assignment-matrix shape)."""
+
+from ortidy.assignment.assignment import assignment
+
+__all__ = ["assignment"]

ortidy/assignment/assignment.py

@@ -0,0 +1,101 @@
+"""Linear sum assignment — assignment-matrix shape.
+
+A cost matrix *is* a dataframe: rows are agents, columns are tasks. We assign each
+agent to exactly one task minimizing (or maximizing) total cost, and return the
+input matrix frame with ``assignedTo`` and ``cost`` columns added.
+
+Link:
+    https://developers.google.com/optimization/assignment/assignment_example
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import narwhals.stable.v1 as nw
+from ortools.graph.python import linear_sum_assignment
+
+from ortidy import _narwhals as _nw
+from ortidy import _scaling, schema
+from ortidy.result import SolveResult, SolveStatus
+
+
+def assignment(
+    costs: Any,
+    *,
+    id_column: str | None = None,
+    maximize: bool = False,
+    assigned_column: str = "assignedTo",
+    cost_column: str = "cost",
+) -> SolveResult:
+    """Solve a balanced/over-supplied linear assignment from a cost matrix.
+
+    Parameters:
+        costs: A cost-matrix frame. Each non-id column is a task; each row an agent.
+        id_column: Optional column labelling agents (not treated as a task). If
+            ``None``, agents are positional and the column is not added back.
+        maximize: Maximize total value instead of minimizing cost.
+        assigned_column: Name of the added column holding each agent's task label.
+        cost_column: Name of the added column holding each agent's assignment cost.
+
+    Returns:
+        SolveResult whose ``frame`` is the input matrix (same backend) plus the
+        assignment and per-agent cost columns, with status and total objective.
+    """
+    frame = _nw.to_nw(costs)
+    schema.require_nonempty(frame, frame_name="costs")
+    if id_column is not None:
+        schema.require_columns(frame, {id_column}, frame_name="costs")
+
+    task_columns = [c for c in frame.columns if c != id_column]
+    if not task_columns:
+        raise ValueError("costs must have at least one task column.")
+    schema.require_numeric(frame, set(task_columns), frame_name="costs")
+
+    n_agents = frame.shape[0]
+    n_tasks = len(task_columns)
+    if n_agents > n_tasks:
+        raise ValueError(
+            f"assignment needs at least as many tasks as agents; got "
+            f"{n_agents} agents and {n_tasks} tasks."
+        )
+
+    columns = [_nw.column_to_list(frame, c) for c in task_columns]
+    flat = [columns[j][i] for i in range(n_agents) for j in range(n_tasks)]
+    _, factor = _scaling.scale_to_int(flat)
+    sign = -1 if maximize else 1
+
+    solver = linear_sum_assignment.SimpleLinearSumAssignment()
+    for i in range(n_agents):
+        for j in range(n_tasks):
+            solver.add_arc_with_cost(i, j, sign * round(columns[j][i] * factor))
+
+    status = solver.solve()
+    if status != solver.OPTIMAL:
+        mapped = (
+            SolveStatus.INFEASIBLE
+            if status == solver.INFEASIBLE
+            else SolveStatus.MODEL_INVALID
+        )
+        return SolveResult(
+            frame=_nw.to_native(frame),
+            status=mapped,
+            objective=None,
+            metadata={"solver": "LinearSumAssignment"},
+        )
+
+    assigned = [task_columns[solver.right_mate(i)] for i in range(n_agents)]
+    per_agent_cost = [columns[solver.right_mate(i)][i] for i in range(n_agents)]
+    objective = sum(per_agent_cost)
+
+    frame = frame.with_columns(
+        nw.new_series(assigned_column, assigned, backend=frame.implementation),
+        nw.new_series(cost_column, per_agent_cost, backend=frame.implementation),
+    )
+
+    return SolveResult(
+        frame=_nw.to_native(frame),
+        status=SolveStatus.OPTIMAL,
+        objective=objective,
+        metadata={"solver": "LinearSumAssignment"},
+    )

ortidy/binning/__init__.py

@@ -0,0 +1,7 @@
+"""Binning solvers (assignment-matrix shape)."""
+
+from ortidy.binning.bin_packing import bin_packing
+from ortidy.binning.knapsack import knapsack
+from ortidy.binning.multi_knapsack import multi_knapsack
+
+__all__ = ["knapsack", "multi_knapsack", "bin_packing"]

ortidy/binning/bin_packing.py

@@ -0,0 +1,122 @@
+"""Bin packing — assignment-matrix shape.
+
+Packs every item into bins of a common capacity, minimizing the number of bins
+used. Returns the original items frame with a ``binId`` column (contiguously
+numbered from 0) added.
+
+Built on CP-SAT — no per-row variable construction.
+
+Link:
+    https://developers.google.com/optimization/bin/bin_packing
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import narwhals.stable.v1 as nw
+from ortools.sat.python import cp_model
+
+from ortidy import _narwhals as _nw
+from ortidy import _scaling, result, schema
+from ortidy.result import SolveResult
+
+
+def bin_packing(
+    items: Any,
+    capacity: float,
+    *,
+    weight: str = "weight",
+    item_id: str | None = None,
+    bin_id: str = "binId",
+    time_limit: float | None = None,
+    random_seed: int = 0,
+) -> SolveResult:
+    """Solve a bin-packing problem.
+
+    Parameters:
+        items: Frame with a weight column.
+        capacity: The (shared) capacity of every bin.
+        weight: Name of the weight column.
+        item_id: Optional explicit item-id column (synthesized if ``None``).
+        bin_id: Name of the bin-assignment column added to the result.
+        time_limit: Optional wall-clock limit in seconds.
+        random_seed: Solver seed for determinism.
+
+    Returns:
+        SolveResult whose ``frame`` is the items frame (same backend) plus a
+        ``bin_id`` column, with status and objective (number of bins used).
+    """
+    frame = _nw.to_nw(items)
+    schema.require_nonempty(frame, frame_name="items")
+    schema.require_columns(frame, {weight}, frame_name="items")
+    schema.require_numeric(frame, {weight}, frame_name="items")
+
+    frame, id_col, synthesized = _nw.ensure_id_column(frame, item_id)
+    weights = _nw.column_to_list(frame, weight)
+
+    factor = _scaling.choose_factor(list(weights) + [capacity])
+    int_weights, _ = _scaling.scale_to_int(weights, factor=factor)
+    int_capacity = round(capacity * factor)
+
+    n = len(weights)  # at most one bin per item is ever needed
+    model = cp_model.CpModel()
+    x = {(i, j): model.new_bool_var(f"x_{i}_{j}") for i in range(n) for j in range(n)}
+    y = [model.new_bool_var(f"y_{j}") for j in range(n)]
+
+    for i in range(n):
+        model.add_exactly_one(x[i, j] for j in range(n))
+    for j in range(n):
+        model.add(
+            sum(x[i, j] * int_weights[i] for i in range(n)) <= int_capacity * y[j]
+        )
+    # Symmetry break: bins fill in order, which also speeds the search.
+    for j in range(n - 1):
+        model.add(y[j] >= y[j + 1])
+    model.minimize(sum(y))
+
+    solver = cp_model.CpSolver()
+    solver.parameters.random_seed = random_seed
+    if time_limit is not None:
+        solver.parameters.max_time_in_seconds = time_limit
+    status = solver.solve(model)
+    solve_status = result.from_cp_sat(status)
+
+    if not solve_status.is_success:
+        frame = _nw.drop_if_synthesized(frame, id_col, synthesized)
+        return SolveResult(
+            frame=_nw.to_native(frame),
+            status=solve_status,
+            objective=None,
+            metadata=_metadata(solver),
+        )
+
+    raw_bin: list[int] = [-1] * n
+    for i in range(n):
+        for j in range(n):
+            if solver.value(x[i, j]) == 1:
+                raw_bin[i] = j
+                break
+    # Renumber used bins contiguously from 0 in order of first appearance.
+    remap: dict[int, int] = {}
+    contiguous = [remap.setdefault(b, len(remap)) for b in raw_bin]
+
+    frame = frame.with_columns(
+        nw.new_series(bin_id, contiguous, backend=frame.implementation)
+    )
+    frame = _nw.drop_if_synthesized(frame, id_col, synthesized)
+
+    return SolveResult(
+        frame=_nw.to_native(frame),
+        status=solve_status,
+        objective=round(solver.objective_value),
+        metadata=_metadata(solver),
+    )
+
+
+def _metadata(solver: cp_model.CpSolver) -> dict[str, Any]:
+    return {
+        "solver": "CP-SAT",
+        "wall_time": solver.wall_time,
+        "best_objective_bound": solver.best_objective_bound,
+    }

ortidy/binning/knapsack.py

@@ -0,0 +1,80 @@
+"""0/1 knapsack — assignment-matrix shape.
+
+Selects the subset of items maximizing total value subject to a weight capacity.
+Returns the original frame with an ``isIncluded`` boolean column added.
+
+Link:
+    https://developers.google.com/optimization/bin/knapsack
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import narwhals.stable.v1 as nw
+from ortools.algorithms.python import knapsack_solver
+
+from ortidy import _narwhals as _nw
+from ortidy import _scaling, schema
+from ortidy.result import SolveResult, SolveStatus
+
+
+def knapsack(
+    items: Any,
+    capacity: float,
+    *,
+    value: str = "value",
+    weight: str = "weight",
+    item_id: str | None = None,
+    assignment_column: str = "isIncluded",
+) -> SolveResult:
+    """Solve a 0/1 knapsack.
+
+    Parameters:
+        items: A dataframe (pandas, Polars, …) with a value and a weight column.
+        capacity: The maximum total weight of the knapsack.
+        value: Name of the value column. Default ``"value"``.
+        weight: Name of the weight column. Default ``"weight"``.
+        item_id: Optional explicit row-id column. If ``None``, identity is handled
+            internally without mutating the returned frame.
+        assignment_column: Name of the added boolean column. Default ``"isIncluded"``.
+
+    Returns:
+        SolveResult whose ``frame`` is the input frame (same backend) plus a
+        boolean ``assignment_column``, with status and total selected value.
+    """
+    frame = _nw.to_nw(items)
+    schema.require_nonempty(frame, frame_name="items")
+    schema.require_columns(frame, {value, weight}, frame_name="items")
+    schema.require_numeric(frame, {value, weight}, frame_name="items")
+
+    frame, id_col, synthesized = _nw.ensure_id_column(frame, item_id)
+
+    raw_values = _nw.column_to_list(frame, value)
+    raw_weights = _nw.column_to_list(frame, weight)
+
+    int_values, _ = _scaling.scale_to_int(raw_values)
+    int_weights, weight_factor = _scaling.scale_to_int(raw_weights)
+    int_capacity = round(capacity * weight_factor)
+
+    solver = knapsack_solver.KnapsackSolver(
+        knapsack_solver.SolverType.KNAPSACK_MULTIDIMENSION_BRANCH_AND_BOUND_SOLVER,
+        "ortidy_knapsack",
+    )
+    solver.init(int_values, [int_weights], [int_capacity])
+    solver.solve()
+
+    included = [solver.best_solution_contains(i) for i in range(len(int_values))]
+    objective = sum(v for v, keep in zip(raw_values, included, strict=False) if keep)
+
+    frame = frame.with_columns(
+        nw.new_series(assignment_column, included, backend=frame.implementation)
+    )
+    frame = _nw.drop_if_synthesized(frame, id_col, synthesized)
+
+    return SolveResult(
+        frame=_nw.to_native(frame),
+        status=SolveStatus.OPTIMAL,  # branch-and-bound returns the optimum
+        objective=objective,
+        metadata={"solver": "KNAPSACK_MULTIDIMENSION_BRANCH_AND_BOUND"},
+    )

ortidy/binning/multi_knapsack.py

@@ -0,0 +1,127 @@
+"""Multiple knapsack — assignment-matrix shape.
+
+Packs items into capacitated bins to maximize total packed value; each item goes
+into at most one bin. Returns the original items frame with a bin-assignment
+column added (null where an item was left unpacked).
+
+Built on CP-SAT — no per-row variable construction.
+
+Link:
+    https://developers.google.com/optimization/bin/multiple_knapsack
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import narwhals.stable.v1 as nw
+from ortools.sat.python import cp_model
+
+from ortidy import _narwhals as _nw
+from ortidy import _scaling, result, schema
+from ortidy.result import SolveResult
+
+
+def multi_knapsack(
+    items: Any,
+    bins: Any,
+    *,
+    value: str = "value",
+    weight: str = "weight",
+    item_id: str | None = None,
+    bin_id: str = "binId",
+    capacity: str = "capacity",
+    time_limit: float | None = None,
+    random_seed: int = 0,
+) -> SolveResult:
+    """Solve a multiple-knapsack assignment.
+
+    Parameters:
+        items: Frame with value and weight columns.
+        bins: Frame with bin-id and capacity columns.
+        value: Name of the item value column.
+        weight: Name of the item weight column.
+        item_id: Optional explicit item-id column (synthesized if ``None``).
+        bin_id: Bin-id column; also names the assignment column added to the
+            returned items frame.
+        capacity: Bin capacity column.
+        time_limit: Optional wall-clock limit in seconds.
+        random_seed: Solver seed for determinism.
+
+    Returns:
+        SolveResult whose ``frame`` is the items frame (same backend) plus a
+        ``bin_id`` column (the assigned bin, or null), with status and objective.
+    """
+    items_nw = _nw.to_nw(items)
+    bins_nw = _nw.to_nw(bins)
+    schema.require_nonempty(items_nw, frame_name="items")
+    schema.require_nonempty(bins_nw, frame_name="bins")
+    schema.require_columns(items_nw, {value, weight}, frame_name="items")
+    schema.require_numeric(items_nw, {value, weight}, frame_name="items")
+    schema.require_columns(bins_nw, {bin_id, capacity}, frame_name="bins")
+    schema.require_numeric(bins_nw, {capacity}, frame_name="bins")
+
+    items_nw, id_col, synthesized = _nw.ensure_id_column(items_nw, item_id)
+
+    weights = _nw.column_to_list(items_nw, weight)
+    values = _nw.column_to_list(items_nw, value)
+    capacities = _nw.column_to_list(bins_nw, capacity)
+    bin_ids = _nw.column_to_list(bins_nw, bin_id)
+
+    # Common integer scale for weights and capacities so the constraints align.
+    factor = _scaling.choose_factor(list(weights) + list(capacities))
+    int_weights, _ = _scaling.scale_to_int(weights, factor=factor)
+    int_caps, _ = _scaling.scale_to_int(capacities, factor=factor)
+    int_values, value_factor = _scaling.scale_to_int(values)
+
+    n, m = len(weights), len(capacities)
+    model = cp_model.CpModel()
+    x = {(i, j): model.new_bool_var(f"x_{i}_{j}") for i in range(n) for j in range(m)}
+    for i in range(n):
+        model.add_at_most_one(x[i, j] for j in range(m))
+    for j in range(m):
+        model.add(sum(x[i, j] * int_weights[i] for i in range(n)) <= int_caps[j])
+    model.maximize(sum(x[i, j] * int_values[i] for i in range(n) for j in range(m)))
+
+    solver = cp_model.CpSolver()
+    solver.parameters.random_seed = random_seed
+    if time_limit is not None:
+        solver.parameters.max_time_in_seconds = time_limit
+    status = solver.solve(model)
+    solve_status = result.from_cp_sat(status)
+
+    if not solve_status.is_success:
+        items_nw = _nw.drop_if_synthesized(items_nw, id_col, synthesized)
+        return SolveResult(
+            frame=_nw.to_native(items_nw),
+            status=solve_status,
+            objective=None,
+            metadata=_metadata(solver),
+        )
+
+    assigned: list[Any] = [None] * n
+    for i in range(n):
+        for j in range(m):
+            if solver.value(x[i, j]) == 1:
+                assigned[i] = bin_ids[j]
+                break
+
+    items_nw = items_nw.with_columns(
+        nw.new_series(bin_id, assigned, backend=items_nw.implementation)
+    )
+    items_nw = _nw.drop_if_synthesized(items_nw, id_col, synthesized)
+
+    return SolveResult(
+        frame=_nw.to_native(items_nw),
+        status=solve_status,
+        objective=_scaling.unscale(solver.objective_value, value_factor),
+        metadata=_metadata(solver),
+    )
+
+
+def _metadata(solver: cp_model.CpSolver) -> dict[str, Any]:
+    return {
+        "solver": "CP-SAT",
+        "wall_time": solver.wall_time,
+        "best_objective_bound": solver.best_objective_bound,
+    }

ortidy/data/__init__.py

@@ -0,0 +1,61 @@
+"""Bundled sample datasets for examples, docs, and golden-file tests.
+
+Each loader returns a native dataframe in the requested ``backend`` (``"pandas"``
+by default, ``"polars"`` also supported), so the same fixtures drive the
+backend-parity tests.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+_DATA_DIR = os.path.dirname(__file__)
+
+
+def bins(backend: str = "pandas") -> Any:
+    return _get_dataset("binning/bins", backend)
+
+
+def items_knapsack(backend: str = "pandas") -> Any:
+    return _get_dataset("binning/items_knapsack", backend)
+
+
+def items_multi(backend: str = "pandas") -> Any:
+    return _get_dataset("binning/items_multi", backend)
+
+
+def items_bin_packing(backend: str = "pandas") -> Any:
+    return _get_dataset("binning/items_bin_packing", backend)
+
+
+def locations(backend: str = "pandas") -> Any:
+    return _get_dataset("routing/locations", backend)
+
+
+def vehicles(with_capacity: bool = True, backend: str = "pandas") -> Any:
+    data = _get_dataset("routing/vehicles", "pandas")
+    if not with_capacity:
+        data = data.drop(columns=["capacity"])
+    return _to_backend(data, backend)
+
+
+def pickups_and_deliveries(backend: str = "pandas") -> Any:
+    return _get_dataset("routing/pickups_and_deliveries", backend)
+
+
+def _get_dataset(name: str, backend: str) -> Any:
+    import pandas as pd
+
+    df = pd.read_csv(os.path.join(_DATA_DIR, f"{name}.csv"))
+    return _to_backend(df, backend)
+
+
+def _to_backend(df: Any, backend: str) -> Any:
+    if backend == "pandas":
+        return df
+    if backend == "polars":
+        import polars as pl
+
+        return pl.from_pandas(df)
+    raise ValueError(f"Unknown backend {backend!r}; expected 'pandas' or 'polars'.")

ortidy/data/binning/bins.csv

@@ -0,0 +1,6 @@
+capacity
+100
+50
+100
+70
+150

ortidy/data/binning/items_bin_packing.csv

@@ -0,0 +1,12 @@
+weight
+48
+30
+19
+36
+36
+27
+42
+42
+36
+24
+30