# marco144803025/crew-scheduling-set-partitioning-problem architecture

> Architecture diagram of the GitHub repository marco144803025/crew-scheduling-set-partitioning-problem, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marco144803025/crew-scheduling-set-partitioning-problem
- Repository: https://github.com/marco144803025/crew-scheduling-set-partitioning-problem

## Overview

##### Project Type and Purpose
- This is an open‐source, command‐line Python tool for solving the airline crew scheduling (set‐partitioning) problem using three metaheuristic algorithms: Simulated Annealing (SA), a standard binary Genetic Algorithm (BGA), and an improved BGA.
- Its primary function is to load a flight‐crew dataset, run the chosen algorithm, track cost and constraint satisfaction over iterations, generate evolution plots, and write detailed results to text files.

##### Top‐Level Architectural Components
a. CLI Layer
- argparse‐based parser
- Accepts flags: --algorithm, --dataset
b. Data Layer
- Dataset loader reads sppnw*.txt files
- Preprocesses into in‐memory data structures (flight list, crew pairing matrix)
c. Algorithm Orchestrator
- Dispatcher that picks SA, BGA, or improved BGA
- Common interfaces: initialize_solution(), evaluate_fitness(), record_iteration()
d. Metaheuristic Modules
- SA Module
– Temperature schedule, neighbor generator (bit flips), acceptance criterion
- Standard BGA Module
– Population initializer, tournament selection, crossover, mutation
- Improved BGA Module
– Pseudo‐random initialization, stochastic ranking constraint handler, heuristic improvement operator
e. Utilities
- Cost & coverage calculation routines
- Constraint checkers (ensure each flight covered exactly once)
- Random number services (random, numpy.random)
- Parallel evaluation (concurrent.futures)
f. Output Layer
- Plot generator (matplotlib) for cost history
- File writer for detailed results (airline_crew_scheduling.py writes to output folder)

##### Relationships and Data Flow
- User invokes CLI → CLI Layer parses inputs → Data Layer loads dataset
- CLI Layer calls Algorithm Orchestrator with dataset & algorithm choice
- Orchestrator dispatches to the selected Metaheuristic Module
→ calls initialize_solution(), then for each iteration:
– Module calls Utility routines for cost & coverage
– Module updates best solution & logs metrics
- At completion, Orchestrator calls Output Layer:
– Plot generator consumes logged metrics → produces PNG/figure
– File writer dumps solution & cost history to text files

##### Architectural Patterns & Design Principles
- Modular design: separate Algorithm modules implementing a common interface
- Single Responsibility: each layer (CLI, Data, Algorithms, Output) has a distinct role
- Open‐Closed: new algorithms can be plugged in by conforming to the orchestrator interface
- Reuse: shared utilities for cost evaluation, constraint checking, file I/O, plotting

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top-level flow
    subgraph "Documentation"
        README["README.md"]:::doc
    end

    README -.-> CLI

    %% CLI Entry
    CLI(("CLI Parser\n(argparse flags)")):::cli
    click CLI "https://github.com/marco144803025/crew-scheduling-set-partitioning-problem/blob/main/airline_crew_scheduling.py"

    %% Dataset Layer
    subgraph "Datasets"
        TXT1["sppnw41.txt"]:::io
        TXT2["sppnw42.txt"]:::io
        TXT3["sppnw43.txt"]:::io
    end

    TXT1 --- DataLoader
    TXT2 --- DataLoader
    TXT3 --- DataLoader

    DataLoader["Dataset Loader\n(load sppnw*.txt)"]:::io
    click DataLoader "https://github.com/marco144803025/crew-scheduling-set-partitioning-problem/blob/main/airline_crew_scheduling.py"

    %% Orchestrator
    Orchestrator["Algorithm Orchestrator\n(dispatcher)"]:::core
    click Orchestrator "https://github.com/marco144803025/crew-scheduling-set-partitioning-problem/blob/main/airline_crew_scheduling.py"

    %% Metaheuristic Modules
    SA["SA Module\n(temp schedule, neighbor gen,\nacceptance)"]:::alg
    BGA["BGA Module\n(pop init, selection,\ncrossover, mutation)"]:::alg
    iBGA["Improved BGA Module\n(pseudo-random init,\nstochastic ranking,\nheuristic improvement)"]:::alg

    click SA "https://github.com/marco144803025/crew-scheduling-set-partitioning-problem/blob/main/airline_crew_scheduling.py"
    click BGA "https://github.com/marco144803025/crew-scheduling-set-partitioning-problem/blob/main/airline_crew_scheduling.py"
    click iBGA "https://github.com/marco144803025/crew-scheduling-set-partitioning-problem/blob/main/airline_crew_scheduling.py"

    %% Utilities and Logger
    Utils["Utilities\n(cost, coverage,\nconstraints, random)"]:::util
    click Utils "https://github.com/marco144803025/crew-scheduling-set-partitioning-problem/blob/main/airline_crew_scheduling.py"

    Logger["Logger\n(iteration metrics)"]:::log

    %% Output Layer
    Plotter["Plot Generator\n(matplotlib)"]:::io
    click Plotter "https://github.com/marco144803025/crew-scheduling-set-partitioning-problem/blob/main/airline_crew_scheduling.py"

    FileWriter["File Writer\n(text results)"]:::io
    click FileWriter "https://github.com/marco144803025/crew-scheduling-set-partitioning-problem/blob/main/airline_crew_scheduling.py"

    %% Connections
    CLI -->|"parsed args"| DataLoader
    DataLoader -->|"parsed data"| Orchestrator

    Orchestrator -->|"invoke algorithm()"| SA
    Orchestrator -->|"invoke algorithm()"| BGA
    Orchestrator -->|"invoke algorithm()"| iBGA

    SA -->|"compute cost/coverage\nrandom services"| Utils
    BGA -->|"compute cost/coverage\nrandom services"| Utils
    iBGA -->|"compute cost/coverage\nrandom services"| Utils

    SA -->|"log metrics"| Logger
    BGA -->|"log metrics"| Logger
    iBGA -->|"log metrics"| Logger

    Logger -->|"metrics"| Plotter
    Logger -->|"solution data"| FileWriter

    %% Styles
    classDef cli fill:#f9f,stroke:#933;
    classDef io fill:#cfc,stroke:#393;
    classDef core fill:#eef,stroke:#559;
    classDef alg fill:#ccf,stroke:#55f;
    classDef util fill:#ffc,stroke:#aa5;
    classDef log fill:#fcf,stroke:#c39;
    classDef doc fill:#eee,stroke:#999,stroke-dasharray: 5 5;
```
