Assignment & packing

Knapsack

ortidy.binning.knapsack.knapsack(items, capacity, *, value='value', weight='weight', item_id=None, assignment_column='isIncluded')[source]

Solve a 0/1 (optionally multidimensional) knapsack.

Parameters:

  • items (Any) – A dataframe (pandas, Polars, …) with a value and weight column(s).

  • capacity (float | list[float]) – The maximum total weight. For a multidimensional knapsack, a list of capacities, one per weight column.

  • value (str) – Name of the value column. Default "value".

  • weight (str | list[str]) – Name of the weight column, or a list of weight columns for a multidimensional knapsack (e.g. weight and volume). Default "weight".

  • item_id (str | None) – Optional explicit row-id column. If None, identity is handled internally without mutating the returned frame.

  • assignment_column (str) – 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.

Return type:

SolveResult

ortidy.binning.multi_knapsack.multi_knapsack(items, bins, *, value='value', weight='weight', item_id=None, bin_id='binId', capacity='capacity', time_limit=None, random_seed=0)[source]

Solve a multiple-knapsack assignment.

Parameters:

  • items (Any) – Frame with value and weight columns.

  • bins (Any) – Frame with bin-id and capacity columns.

  • value (str) – Name of the item value column.

  • weight (str) – Name of the item weight column.

  • item_id (str | None) – Optional explicit item-id column (synthesized if None).

  • bin_id (str) – Bin-id column; also names the assignment column added to the returned items frame.

  • capacity (str) – Bin capacity column.

  • time_limit (float | None) – Optional wall-clock limit in seconds.

  • random_seed (int) – 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.

Return type:

SolveResult

ortidy.binning.bin_packing.bin_packing(items, capacity, *, weight='weight', item_id=None, bin_id='binId', time_limit=None, random_seed=0)[source]

Solve a bin-packing problem.

Parameters:

  • items (Any) – Frame with a weight column.

  • capacity (float) – The (shared) capacity of every bin.

  • weight (str) – Name of the weight column.

  • item_id (str | None) – Optional explicit item-id column (synthesized if None).

  • bin_id (str) – Name of the bin-assignment column added to the result.

  • time_limit (float | None) – Optional wall-clock limit in seconds.

  • random_seed (int) – 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).

Return type:

SolveResult

Assignment

ortidy.assignment.assignment.assignment(edges, *, left='agent', right='task', value='cost', maximize=False, selected_column='selected', teams=None, team_capacity=None, allowed_groups=None, group_column='group', pattern_column='pattern', member_column='agent', active_column='active', time_limit=None, random_seed=0)[source]

Solve an assignment from a tidy edge list, optionally with team/group rules.

Parameters:

  • edges (Any) – One row per allowed (agent, task) pair with its cost/value.

  • left (str) – The agent, task, and cost columns.

  • right (str) – The agent, task, and cost columns.

  • value (str) – The agent, task, and cost columns.

  • maximize (bool) – Maximize total value instead of minimizing cost.

  • selected_column (str) – Name of the added boolean column.

  • teams (Any) – Optional {agent: team} mapping or (agent, team) frame.

  • team_capacity (int | Mapping[Any, int] | Any) – Max agents each team may use — an int (all teams) or a {team: cap} mapping / (team, cap) frame.

  • allowed_groups (Any) – Optional (group, pattern, agent, active) frame. For each group it enumerates allowed patterns; every group member appears in every pattern with active = 1/0 (whether that agent is active in the pattern). The active agents of each group must equal one of its patterns.

  • group_column (str) – Columns within allowed_groups.

  • pattern_column (str) – Columns within allowed_groups.

  • member_column (str) – Columns within allowed_groups.

  • active_column (str) – Columns within allowed_groups.

  • time_limit (float | None) – CP-SAT controls (constrained variants only).

  • random_seed (int) – CP-SAT controls (constrained variants only).

Returns:

SolveResult whose frame is the edge frame (same backend) plus a boolean selected_column; objective is the total cost/value.

Return type:

SolveResult

ortidy.assignment.generalized_assignment.generalized_assignment(edges, capacities, *, task='task', agent='agent', value='value', size='size', require_all=False, selected_column='selected', time_limit=None, random_seed=0)[source]

Solve a generalized assignment problem from a tidy edge list.

Parameters:

  • edges (Any) – One row per allowed (task, agent) pair, with a value and a size.

  • capacities (Mapping[Any, float] | Any) – Per-agent capacity, as a {agent: capacity} mapping or a two-column (agent, capacity) frame.

  • task (str) – Column names within edges.

  • agent (str) – Column names within edges.

  • value (str) – Column names within edges.

  • size (str) – Column names within edges.

  • require_all (bool) – If True, every task must be assigned (else infeasible); otherwise tasks may be left unassigned.

  • selected_column (str) – Name of the added boolean column.

  • time_limit (float | None) – Optional wall-clock limit in seconds.

  • random_seed (int) – Solver seed for determinism.

Returns:

SolveResult whose frame is the edge frame (same backend) plus a boolean selected_column; objective is the total assigned value.

Return type:

SolveResult

Facility location & covering

ortidy.facility.facility_location.facility_location(edges, setup_costs, *, customer='customer', facility='facility', cost='cost', selected_column='selected', time_limit=None, random_seed=0)[source]

Solve an uncapacitated facility-location problem from a tidy edge list.

Parameters:

  • edges (Any) – One row per allowed (customer, facility) pair with its cost.

  • setup_costs (Mapping[Any, float] | Any) – Per-facility opening cost, as a {facility: cost} mapping or a two-column (facility, cost) frame.

  • customer (str) – Column names within edges.

  • facility (str) – Column names within edges.

  • cost (str) – Column names within edges.

  • selected_column (str) – Name of the added boolean column.

  • time_limit (float | None) – Optional wall-clock limit in seconds.

  • random_seed (int) – Solver seed for determinism.

Returns:

SolveResult whose frame is the edge frame (same backend) plus a boolean selected_column; objective is total setup + assignment cost, and metadata lists the opened facilities.

Return type:

SolveResult

ortidy.covering.set_cover.set_cover(membership, costs, *, subset='subset', element='element', cost_column='cost', partition=False, selected_column='isSelected', time_limit=None, random_seed=0)[source]

Solve a set-cover (or set-partition) problem from a tidy membership list.

Parameters:

  • membership (Any) – One row per (subset, element) pair the subset covers.

  • costs (Mapping[Any, float] | Any) – Per-subset cost, as a {subset: cost} mapping or a two-column (subset, cost) frame.

  • subset (str) – Column names within membership.

  • element (str) – Column names within membership.

  • cost_column (str) – Name of the cost column added to the returned subset frame.

  • partition (bool) – If True, require each element covered exactly once.

  • selected_column (str) – Name of the added boolean column.

  • time_limit (float | None) – Optional wall-clock limit in seconds.

  • random_seed (int) – Solver seed for determinism.

Returns:

SolveResult whose frame (same backend as membership) is one row per subset with its cost and a boolean selected_column; objective is the total selected cost.

Return type:

SolveResult

Blending

ortidy.blending.blend.blend(items, requirements, *, cost='cost', attribute='attribute', minimum='min', maximum='max', quantity_column='quantity')[source]

Solve a blending / diet linear program.

Parameters:

  • items (Any) – One row per item, with a cost column and one numeric column per attribute (the amount a unit of the item contributes to that attribute).

  • requirements (Any) – Tidy (attribute, min) table, optionally with a max column (null max = no upper bound). Each attribute names a column of items.

  • cost (str) – The per-unit cost column in items.

  • attribute (str) – Column names within requirements.

  • minimum (str) – Column names within requirements.

  • maximum (str) – Column names within requirements.

  • quantity_column (str) – Name of the added continuous quantity column.

Returns:

SolveResult whose frame is the items frame (same backend) plus a continuous quantity_column; objective is the minimum total cost.

Return type:

SolveResult