Shift Scheduling in Python with OR-Tools
Given the headcount needed in each period, PyWorkforce calculates how many people to assign to each predefined shift. The worked Python example runs both solvers on the same two-day demand and shift coverage arrays.
pyworkforce provides two constraint-programming solvers, both built on OR-Tools:
MinAbsDifferenceminimizes the total coverage gap, counting both overstaffing and understaffing. Use it when some shortfalls are acceptable.MinRequiredResourcesrequires full coverage in every period. It minimizes scheduled headcount, or total shift cost if you supply weights.
For demand estimates, start with Erlang C. To assign named employees after deciding how many are needed per shift, use rostering.
Inputs
Both solvers share the same core inputs:
| Argument | Description |
|---|---|
num_days | Number of days to schedule |
periods | Number of periods per day |
shifts_coverage | {shift_name: [0/1, …]}, each array of length periods |
required_resources | Array of shape [num_days, periods] |
max_period_concurrency | Max resources allowed in any period |
max_shift_concurrency | Max resources allowed on any single shift |
shift_limits | Optional (day, shift_name) keys with inclusive (minimum, maximum) staffing bounds |
TIP
Use the shift coverage builders to create shifts_coverage instead of writing 0/1 arrays by hand. pyworkforce validates that every coverage array and every required_resources row has exactly periods entries, and raises a clear error otherwise.
Example
from pyworkforce.scheduling import MinAbsDifference, MinRequiredResources
required_resources = [
[9, 11, 17, 9, 7, 12, 5, 11, 8, 9, 18, 17, 8, 12, 16, 8, 7, 12, 11, 10, 13, 19, 16, 7],
[13, 13, 12, 15, 18, 20, 13, 16, 17, 8, 13, 11, 6, 19, 11, 20, 19, 17, 10, 13, 14, 23, 16, 8],
]
shifts_coverage = {
"Morning": [0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"Afternoon": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0],
"Night": [1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1],
"Mixed": [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0],
}
difference = MinAbsDifference(
num_days=2, periods=24,
shifts_coverage=shifts_coverage,
required_resources=required_resources,
max_period_concurrency=27, max_shift_concurrency=25,
)
print(difference.solve()["status"])
requirements = MinRequiredResources(
num_days=2, periods=24,
shifts_coverage=shifts_coverage,
required_resources=required_resources,
max_period_concurrency=27, max_shift_concurrency=25,
)
print(requirements.solve()["status"])The solution
solve() returns a dictionary and also stores it on the estimator as solution_:
{
"status": "OPTIMAL",
"cost": 157.0,
"resources_shifts": [
{"day": 0, "shift": "Morning", "resources": 8},
{"day": 0, "shift": "Afternoon", "resources": 11},
...
],
}status—OPTIMAL,FEASIBLEorINFEASIBLE.cost— final objective value (-1when infeasible).resources_shifts— resources to assign per day and shift.
Weighting shifts (MinRequiredResources)
By default every shift costs 1. Pass a cost_dict to make some shifts more expensive than others (for example, night shifts):
cost_dict = {"Morning": 8, "Afternoon": 8, "Night": 10, "Mixed": 7}
scheduler = MinRequiredResources(
num_days=2, periods=24,
shifts_coverage=shifts_coverage,
required_resources=required_resources,
cost_dict=cost_dict,
max_period_concurrency=27, max_shift_concurrency=25,
)cost_dict must contain exactly the same shift names as shifts_coverage.
Search control
Both solvers accept max_search_time (seconds, default 120/240) and num_search_workers (default 2) to bound the optimization.
Common pitfalls
required_resourcesmust have one row per day and exactlyperiodsvalues per row.max_period_concurrencyandmax_shift_concurrencyare upper bounds.MinRequiredResourcesreturnsINFEASIBLEif those bounds prevent full coverage.MinAbsDifferencereports a shortfall when the bounds allow a partial plan. Conflicting staffing limits can make either solver infeasible.- Use
MinRequiredResourceswhen every period must be covered; useMinAbsDifferencewhen matching demand closely is more important than strict coverage. - Shift definitions drive feasibility. Validate
shifts_coveragebefore assuming the demand pattern is impossible.
Use coverage() and compare_coverage() to inspect the periods that the solved plan covers and compare it with alternate demand.