# martinakaduc/mm241-assignment architecture

> Architecture diagram of the GitHub repository martinakaduc/mm241-assignment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/martinakaduc/mm241-assignment
- Repository: https://github.com/martinakaduc/mm241-assignment

## Overview

##### Main components
- Core Engine Module – represented by main.py, which acts as the central controller.
- Policy Abstraction – the Policy class (in policy.py) that defines the interface (e.g., the get_action method) for all policy implementations.
- Student Submission Modules – a large number of folders under student_submissions, each containing a student’s policy (e.g., policy[some_student_ID].py), associated grading files (grade_p1.json, grade_p2.json, etc.), and sometimes additional support code.
- Evaluation/Grading System – scripts such as grade_all.py, grade_single.py, compute_score.py, and possibly check_wrong_name.py that gather, validate, grade, and score the different submissions.
- Configuration and Utility Modules – configs.py (for parameters and system configuration) and compute_score.py (which may define logic for scoring policies).
- Data Files – Excel sheets (scores.xlsx, scores_by_student.xlsx) and CSV files (wrong_name_public.csv) that serve as inputs or outputs to the system.
- Demonstration/Visualization Component – the demo folder (including a demo GIF) which shows the behavior of the greedy algorithm.

##### Relationships and interactions
- The Core Engine (main.py) orchestrates the overall process:
- It instantiates the cutting stock problem, loads configuration (configs.py), and selects which policy to use.
- It interacts with the Policy abstraction and calls its get_action method to compute cutting decisions.
- The Policy interface (along with its provided implementation examples) acts as a plug-in point:
- Student-submitted policies inherit from the Policy class.
- The system dynamically loads the appropriate student policy (e.g., by uncommenting an import in main.py).
- The Grading Subsystem:
- Grading scripts (grade_all.py, grade_single.py) call the core engine with each submission.
- They compare the output (grades stored in JSON files within each submission directory) against benchmarks.
- Score files (Excel and CSV) serve to log and summarize the performance.
- The Demo/Visualization Module:
- The demo directory holds assets (e.g., greedy.gif) that show algorithm behavior as a reference example.
- External libraries (numpy, pandas, torch, tensorflow, etc.) support computation within policies.

##### Architectural patterns and design principles
- Modularity and Separation of Concerns are evident:
- The core workflow is separated from grading, demonstration, and policy implementations.
- The Policy class abstracts out the decision-making so that new policies can be “plugged in” without modifying the core engine.
- Extensibility:
- Encourages new implementations by external contributors (students) via standardized naming and folder structure (e.g., student_submissions/s22110xxx).
- Uses inheritance (students create Policy2210xxx that inherits from Policy) as the primary extensibility mechanism.
- Workflow Pipeline:
- The system can be seen as a pipeline where input data (demands, stock sizes) moves through the core engine, processed by the selected policy, then evaluated by the grading process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Workflow
    subgraph "Core Workflow"
        main["Main Engine (main.py)"]:::core
        config["Configuration (configs.py)"]:::config
        policy["Policy Interface (policy.py)"]:::policy
        student["Student Policies (student_submissions/)"]:::student
    end

    %% Grading & Evaluation Subsystem
    subgraph "Grading & Evaluation"
        gradeAll["Grade All Script (grade_all.py)"]:::grading
        gradeSingle["Grade Single Script (grade_single.py)"]:::grading
        computeScore["Compute Score (compute_score.py)"]:::grading
        checkName["Check Wrong Name (check_wrong_name.py)"]:::grading
    end

    %% Data Stores
    subgraph "Data Stores"
        scoreExcel["Scores (scores.xlsx)"]:::data
        scoreByStudent["Scores by Student (scores_by_student.xlsx)"]:::data
        wrongNamePublic["Public Wrong Name (cheating/wrong_name_public.csv)"]:::data
        wrongName["Wrong Name (wrong_name.csv)"]:::data
    end

    %% Demo/Visualization
    subgraph "Demo/Visualization"
        demo["Demo Assets (demo/)"]:::demo
    end

    %% Relationships between components
    main -->|"reads_config"| config
    main -->|"instantiates_Policy"| policy
    policy -->|"loads_implementations"| student
    student -->|"sends_grade_JSONs"| gradeAll
    gradeAll -->|"triggers_core"| main
    gradeSingle -->|"triggers_core"| main
    gradeAll -->|"invokes_compute"| computeScore
    computeScore -->|"updates_scores"| scoreExcel
    computeScore -->|"updates_scores"| scoreByStudent
    checkName -->|"verifies_names"| wrongNamePublic
    checkName -->|"verifies_names"| wrongName
    main -->|"triggers_demo"| demo

    %% Click Events
    click main "https://github.com/martinakaduc/mm241-assignment/blob/main/main.py"
    click config "https://github.com/martinakaduc/mm241-assignment/blob/main/configs.py"
    click policy "https://github.com/martinakaduc/mm241-assignment/blob/main/policy.py"
    click student "https://github.com/martinakaduc/mm241-assignment/tree/main/student_submissions/"
    click gradeAll "https://github.com/martinakaduc/mm241-assignment/blob/main/grade_all.py"
    click gradeSingle "https://github.com/martinakaduc/mm241-assignment/blob/main/grade_single.py"
    click computeScore "https://github.com/martinakaduc/mm241-assignment/blob/main/compute_score.py"
    click checkName "https://github.com/martinakaduc/mm241-assignment/blob/main/check_wrong_name.py"
    click scoreExcel "https://github.com/martinakaduc/mm241-assignment/blob/main/scores.xlsx"
    click scoreByStudent "https://github.com/martinakaduc/mm241-assignment/blob/main/scores_by_student.xlsx"
    click wrongNamePublic "https://github.com/martinakaduc/mm241-assignment/blob/main/cheating/wrong_name_public.csv"
    click wrongName "https://github.com/martinakaduc/mm241-assignment/blob/main/wrong_name.csv"
    click demo "https://github.com/martinakaduc/mm241-assignment/tree/main/demo/"

    %% Styles
    classDef core fill:#F9E79F,stroke:#D68910,stroke-width:2px;
    classDef config fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef policy fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef student fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef grading fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef data fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef demo fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;
```
