MIP Solver Documentation

What is the MIP Solver?

The Mixed Integer Programming (MIP) Solver is the optimization engine that powers the HOURS schedule generator. It uses mathematical optimization to find the best course schedule given your constraints and preferences.

API Endpoint

POST /api/mip/solve

Content-Type: application/json

Request Schema

{
  "problem_version": "hours.v0",
  "horizon": {
    "terms": 8  // Number of terms to plan (1-12)
  },
  "params": {
    "balance_load_weight": 0.7,    // 0-1: How much to balance load
    "difficulty_penalty": 0.5,      // 0-1: Penalty for hard courses
    "morning_preference": 0.3       // 0-1: Preference for morning classes
  },
  "inputs": {
    "courses": [
      {
        "id": "IE200",
        "name": "Intro to Industrial Engineering",
        "credits": 3,
        "difficulty": 0.35,         // 0-1: Course difficulty
        "term_offered": ["Fall", "Spring"],
        "prereqs": []
      }
    ],
    "degree_rules": {
      "min_credits": 120,
      "max_per_term": 18,
      "min_per_term": 12,
      "must_take": ["IE200", "IE330"],
      "electives": [
        {
          "bucket_id": "tech_electives",
          "candidates": ["IE470", "IE471", "IE480"],
          "min_count": 2
        }
      ]
    }
  }
}

Response Schema

{
  "status": "optimal" | "feasible" | "infeasible" | "error",
  "objective": 0.85,  // Optimization score
  "schedule": [
    {
      "term": 1,
      "course_ids": ["IE200", "MA161", "CS180", "ENGL106"]
    },
    {
      "term": 2,
      "course_ids": ["IE330", "MA162", "PHYS172", "COM114"]
    }
  ],
  "diagnostics": {
    "violations": [],
    "notes": ["Balanced load achieved", "Prerequisites satisfied"]
  }
}

Optimization Objectives

• Minimize total time to graduation
• Balance course load across terms
• Respect prerequisite chains
• Consider course difficulty distribution
• Optimize for concentration requirements
• Account for term availability constraints

Constraints

• Prerequisites must be completed before taking a course
• Maximum credits per term (typically 18)
• Minimum credits per term (typically 12 for full-time)
• Courses only offered in specific terms
• Required courses must be included
• Elective requirements must be satisfied

Current Status

The endpoint currently returns a 501 Not Implemented response with the following structure:

{
  "status": "placeholder_ok",
  "message": "MIP solver not yet implemented",
  "documentation_url": "/docs/mip",
  "echo": { ... }  // Sanitized input for debugging
}

Planned Implementation

The production solver will use Google OR-Tools or a similar optimization library to solve the course scheduling problem as a mixed-integer program. Expected features include:

• Multi-objective optimization
• Soft constraints with penalties
• Alternative schedule generation
• Infeasibility analysis
• Performance metrics and diagnostics

Testing the Endpoint

You can test the current stub implementation with:

curl -X POST http://localhost:3000/api/mip/solve \
  -H "Content-Type: application/json" \
  -d '{
    "problem_version": "hours.v0",
    "horizon": {"terms": 8},
    "inputs": {
      "courses": [],
      "degree_rules": {
        "min_credits": 120,
        "max_per_term": 18,
        "must_take": [],
        "electives": []
      }
    }
  }'