Advanced Customization

This page collects advanced scheduling controls that most users do not need for basic runs.

Hard Constraints

Use these APIs before solving to force or forbid specific outcomes:

# 1) forbid_meeting(visitor, faculty, time_slot=None)
s.forbid_meeting("Visitor 1", "Prof. C")         # forbid all slots
s.forbid_meeting("Visitor 2", "Prof. A", 3)      # forbid only slot 3

# 2) require_meeting(visitor, faculty, time_slot=None)
s.require_meeting("Visitor 3", "Prof. B")        # require exactly once across all slots
s.require_meeting("Visitor 4", "Prof. D", 2)     # require slot 2 specifically

# 3) require_break(visitor, slots=None, min_breaks=1)
s.require_break("Visitor 5")                     # at least one break in all slots
s.require_break("Visitor 6", slots=[2, 3], min_breaks=1)

These are hard MILP constraints (not preference weights). Duplicate calls are idempotent.

Optional Per-Entity Meeting Bounds

When global meeting bounds are too strict for a specific person, use targeted overrides:

# Visitor-specific override (None => use global defaults)
s.set_visitor_meeting_bounds("Visitor 1", min_meetings=1, max_meetings=2)
s.set_visitor_meeting_bounds("Visitor 2", min_meetings=None, max_meetings=None)  # clear override

# Faculty-specific override (None => use global defaults)
s.set_faculty_meeting_bounds("Prof. A", min_meetings=1, max_meetings=4)
s.set_faculty_meeting_bounds("Prof. B", min_meetings=None, max_meetings=None)  # clear override

Override precedence:

  • Visitor bounds override global min_faculty for that visitor.

  • Faculty bounds override global min_visitors / max_visitors for that faculty.

  • Hard constraints (require_*, forbid_*) remain hard.

Pre-Solve Checks

When advanced hard constraints or per-entity bounds are configured, the scheduler runs pre-solve consistency checks and raises ValueError for obvious contradictions (for example, required meetings that exceed max bounds, or slot-specific conflicts).

Error messages include actionable suggestions such as:

  • set_visitor_meeting_bounds(...)

  • set_faculty_meeting_bounds(...)

This helps non-expert users avoid solver-level infeasibility diagnostics.

Debugging Infeasibility

By default, pre-checks fail fast before model construction:

s.schedule_visitors(
    min_faculty=2,
    debug_infeasible=False,  # default
)

For expert workflows, use:

s.schedule_visitors(
    min_faculty=2,
    debug_infeasible=True,
)

With debug_infeasible=True, the model is built first, then pre-check errors are raised. This leaves s.model available for IIS/manual inspection.

The same option is available on schedule_visitors_top_n(...).