# tanmoyie/location-allocation-using-mip architecture

> Architecture diagram of the GitHub repository tanmoyie/location-allocation-using-mip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tanmoyie/location-allocation-using-mip
- Repository: https://github.com/tanmoyie/location-allocation-using-mip

## Overview

##### Main Components
- Inputs: The “Inputs” folder holds raw data files (Excel and text) that contain spill information, location data, and other necessary datasets.
- Optimization Models: The heart of the project lies in the optimization models – with the main engine in “model_PAMIP.py” and additional modules such as “model_analysis.py” and “model_mclp.py” potentially representing different modeling approaches or analyses.
- Core Application Logic: “main.py” serves as the driver that ties the optimization engine, data input, and output generation together, leveraging custom functions from “custom_functions.py” to streamline repeated logic.
- Visualization: “data_visualization.py” contains the code to generate the figures that showcase the outputs, including the tradeoff and analysis graphs.
- Outputs: All resultant files (CSV, LP model file, etc.) are stored in the “Outputs” directory and represent the system’s feedback and results.
- Dependencies & Documentation: “requirement.txt” (for Python package dependencies) and “main_predictive_analytics_and_modeling.pdf” (which might detail further project insights or methodology) are fundamental for setup and documentation.

##### Relationships and Interactions
- Data Flow: Raw data is read from the “Inputs” folder by main.py and possibly by supporting modules. This input data is processed and fed into the optimization engine (primarily in model_PAMIP.py) where the MIP model is executed.
- Processing & Custom Functions: The “custom_functions.py” module encapsulates any repetitive or utility logic called from the main program or the optimization modules.
- Outputs & Visualization: Results from the optimization (e.g., optimal facility locations, tradeoff information) are output as CSV files and a model file, and these outputs are further visualized using functions from “data_visualization.py.”
- Documentation Linkage: The PDF and the README provide critical context on methodology and expected results; they can be included as reference nodes in the architecture.

##### Important Architectural Patterns and Design Principles
- Separation of Concerns: There is a clear separation between data handling (Inputs and Outputs), business logic (optimization model and analysis scripts), and presentation (visualization).
- Modularity: The use of separate modules for custom functions, various aspects of the optimization (different models), and visualizations indicates a modular design.
- Pipeline Architecture: The project essentially follows a linear pipeline—from reading inputs, processing data through the optimization engine, and finally producing outputs and visualizations.

- From Inputs → Main Application Controller.
- From Main Application Controller → Optimization Engine.
- From Optimization Engine → Custom Functions (if applicable) and then to Outputs.
- From Outputs → Visualization Module.
- External Dependencies: Optionally, include additional nodes noting “Python Packages (requirement.txt)” and “Documentation (README & PDF)” indicating supporting resources.

##### Instructing the Principal Software Engineer
- A descriptive label for each component, e.g., “Data Input – Reads Excel and Text Files,” “Optimization Engine – MIP Model Execution,” “Visualization – Generates Figures from Outputs.”
- Do not hesitate to create sub-components if needed. For instance, consider splitting “Optimization Engine” into its submodules (model_PAMIP.py, model_analysis.py, model_mclp.py) to capture their distinct roles if more granular detail is needed.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Data Layer"
        D("Data Input – Reads Excel & Text Files"):::data
        O("Outputs – CSV & LP Model Files"):::data
    end

    subgraph "Business Logic"
        M("Main Application Controller – Orchestrates Execution"):::logic
        C("Custom Functions – Utility Functions"):::logic
        subgraph "Optimization Engine"
            PAMIP("model_PAMIP.py – MIP Model Execution"):::logic
            ANALYSIS("model_analysis.py – Analysis Module"):::logic
            MCLP("model_mclp.py – Additional Analysis"):::logic
        end
    end

    subgraph "Visualization"
        V("Visualization – Generates Figures"):::presentation
    end

    subgraph "Documentation & Dependencies"
        DEP("requirement.txt"):::documentation
        PDF("main_predictive_analytics_and_modeling.pdf"):::documentation
        READ("README.md"):::documentation
    end

    D -->|"supplies_data"| M
    M -->|"triggers_optimization"| PAMIP
    M -->|"calls_functions"| C
    PAMIP -->|"outputs_results"| O
    ANALYSIS -->|"outputs_results"| O
    MCLP -->|"outputs_results"| O
    O -->|"feeds_visualization"| V
    V -->|"interactive_feedback"| M
    M -->|"references"| DEP
    M -->|"references"| PDF
    M -->|"references"| READ

    click D "https://github.com/tanmoyie/location-allocation-using-mip/tree/main/Inputs/"
    click PAMIP "https://github.com/tanmoyie/location-allocation-using-mip/blob/main/model_PAMIP.py"
    click ANALYSIS "https://github.com/tanmoyie/location-allocation-using-mip/blob/main/model_analysis.py"
    click MCLP "https://github.com/tanmoyie/location-allocation-using-mip/blob/main/model_mclp.py"
    click C "https://github.com/tanmoyie/location-allocation-using-mip/blob/main/custom_functions.py"
    click M "https://github.com/tanmoyie/location-allocation-using-mip/blob/main/main.py"
    click V "https://github.com/tanmoyie/location-allocation-using-mip/blob/main/data_visualization.py"
    click O "https://github.com/tanmoyie/location-allocation-using-mip/tree/main/Outputs/"
    click DEP "https://github.com/tanmoyie/location-allocation-using-mip/blob/main/requirement.txt"
    click PDF "https://github.com/tanmoyie/location-allocation-using-mip/blob/main/main_predictive_analytics_and_modeling.pdf"
    click READ "https://github.com/tanmoyie/location-allocation-using-mip/blob/main/README.md"

    classDef data fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef logic fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef presentation fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef documentation fill:#FADBD8,stroke:#922B21,stroke-width:2px;
```
