How alishhde/couriers-planning-problem works
Based on our analysis of the file tree and the README, this project is a constraint‐programming–based operational research tool designed to solve a Multiple Couriers Planning Problem. In essence, the project implements several different modeling formulations (or “modelings”) to optimize the assignment of items to couriers and the routes they take, subject to capacities and distance minimization. The system integrates input instance data, several solver model files (written in .mzn format for solvers such as Gecode, Chuffed, ORTOOLS, etc.), processing scripts (in Python), Docker orchestration, and output result extraction.
Main components
• Input/Data Layer:
• “Instances” directory: Contains raw instance files formatted both as .dat and .dzn.
• “dat to dzn converter.py”: Converts instance data to the correct format for solver consumption.
• Modeling/Algorithm Layer:
• “Solvers” directory: Contains multiple subdirectories corresponding to different modeling approaches (e.g., 3D path-based, 2D path/sequence-based, heuristic models). Each subdirectory holds .mzn files that define the constraint models.
• “Main_MZN.py” and “Docker_Main_MZN.py”: Python scripts that likely serve as entry points for executing models and possibly interacting with solvers.
• Execution/Deployment Layer:
• “Dockerfile” and .github/workflows: Indicate containerization and CI/CD (used to build, test, and run models via Docker).
• Output/Results Layer:
• “Results” directory: Holds solution outputs (e.g., .json files) from various solver runs and a results extraction script (“results_extracter.py”).
• Documentation:
• “README.md” and the provided PDF file: Explain the modeling choices, the experimental study, and performance results.
• Configuration:
• “requirements.txt” and “LICENSE”: Standard project configuration and legal files.
Relationships and interactions
• Data (instances) flows into the converter, which standardizes the input.
• The “Main_MZN.py” (or Docker_Main_MZN.py) acts as a controller that “calls” the appropriate solver models in the “Solvers” directory. The selection among different modeling approaches is informed by the solver’s performance trade-offs described exhaustively in the README.
• The solver models (constraint formulations) utilize decision variables, constraints, and objective functions (minimize the maximum route length) which are described in detail in the README. These models interact with the solver engine (Gecode, Chuffed, ORTOOLS, etc.) via the provided .mzn files.
• The output from solver runs is stored in the “Results” directory and then processed via “results_extracter.py” for further analysis or reporting.
• CI/CD via GitHub workflows ensures continuous integration, testing (using “run-docker.yml”), and containerized deployments.
Architectural patterns/design principles
• Separation of Concerns: The system separates data management (instances and conversions), model formulation (in the Solvers folder), execution (via main scripts and Docker), and result analysis.
• Modularity & Extensibility: With multiple solver model directories and variant implementations, new model formulations or solvers can be added easily.
• Heuristics & Optimization Layers: The README details layered search strategies (sequence construction, item assignment, route length optimization) that are central to the solver’s heuristic approach.
• Containerization: Docker is used ensuring consistent execution environments.