API — Scheduling
pyworkforce.scheduling
Both schedulers share the same constructor signature (except cost_dict) and the same solve() output. They validate that every shifts_coverage array and every required_resources row has exactly periods entries.
MinAbsDifference
MinAbsDifference(num_days, periods, shifts_coverage, required_resources,
max_period_concurrency, max_shift_concurrency,
max_search_time=120.0, num_search_workers=2, *, shift_limits=None)Minimizes the total absolute difference between required and scheduled resources per period.
MinRequiredResources
MinRequiredResources(num_days, periods, shifts_coverage, required_resources,
max_period_concurrency, max_shift_concurrency,
cost_dict=None, max_search_time=240.0, num_search_workers=2,
*, shift_limits=None)Minimizes the (optionally weighted) number of scheduled resources while covering every period.
- cost_dict (
dict, optional) —{shift_name: cost}; must contain exactly the same shift names asshifts_coverage. Defaults to a cost of1per shift.
Daily shift limits
Both schedulers accept shift_limits={(day, shift_name): (minimum, maximum)}. Days are zero-based and bounds are inclusive non-negative integers. The maximum cannot exceed max_shift_concurrency. Unspecified pairs use the global bounds. Fixed limits may still make the model infeasible, for example if their sum exceeds max_period_concurrency during an overlap.
Inspecting a solved schedule
These methods require the last solve() to have returned OPTIMAL or FEASIBLE. Otherwise they raise RuntimeError.
scheduled_resources()returns{shift_name: [count_day_0, …]}forBreakScheduleror other consumers.coverage(required_resources=None)returns a pandas DataFrame withday,period,required,scheduled,shortfall, andsurplus. Each row represents one zero-based period on one zero-based day. Alternate demand must have shape(num_days, periods)and consist of non-negative 64-bit integers.compare_coverage(scenarios)takes a non-empty mapping of scenario names to demand arrays. UseNonefor the original forecast. Each scenario yieldsrequired,scheduled,shortfall, andsurplustotals in person-periods, plusunderstaffed_periods. The assignments stay fixed throughout.
See the schedule stress-test tutorial.
Common parameters
- num_days (
int) — days to schedule. - periods (
int) — periods per day. - shifts_coverage (
dict) —{shift_name: [0/1, …]}, lengthperiods. - required_resources (
list) — shape[num_days, periods]. - max_period_concurrency (
int) — max resources per period. - max_shift_concurrency (
int) — max resources per shift. - max_search_time (
float) — solver time limit, seconds. - num_search_workers (
int) — solver worker threads.
solve()
Returns a dict (also stored as solution_):
- status —
"OPTIMAL","FEASIBLE"or"INFEASIBLE". - cost — objective value (
-1if infeasible). - resources_shifts — list of
{"day", "shift", "resources"}.
See the scheduling guide.