# higisx/recovnet architecture

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

- Interactive diagram: https://gitdiagram.com/higisx/recovnet
- Repository: https://github.com/higisx/recovnet

## Overview

##### Project Type and Purpose
- This is an open-source research codebase implementing and comparing three solution methods (Genetic Algorithm, Gurobi solver, and a deep reinforcement learning model called ReCovNet) for the Maximal Coverage Billboard Location Problem (MCBLP).
- It combines combinatorial optimization, deep learning (PyTorch/TensorFlow), and GIS data processing.

##### High-Level Component Analysis
- Data Layer: raw problem instances (data/MCLP_origin/*.pkl, data/real/*.shp/.csv)
- Problem Definition Layer: classes and state representations under problems/MCLP (problem_MCLP.py, state_MCLP.py)
- Algorithmic Solvers:
- GA module (Algorithm/GA.py and Billboard_MCLP_GA.ipynb)
- Gurobi solver notebooks (Billboard_MCLP_solver.ipynb)
- ReCovNet deep RL module (nets/*.py for attention_model, graph_encoder, reinforce_baselines; Billboard_MCLP_DRL.ipynb)
- Orchestration Scripts: train.py, run.py, eval.py, generalization.py, options.py
- Utilities: reusable helpers under utils/ (data loading, boolean masks, logging, common functions)
- Output & Logging:
- logs/ for TensorBoard event files
- output/ for trained model checkpoints and run configs
- results/ for evaluation outputs

##### Relationships and Data Flow
- Data files → data_utils → Problem classes → State objects → Solver modules
- Solver modules (GA, Gurobi, ReCovNet) invoke problem API to evaluate candidate solutions or step through episodes
- During ReCovNet training: nets/graph_encoder and attention_model take state representation → produce action distributions → env stepping via state_MCLP → training loop in train.py → checkpoints to output/ and scalars to logs/
- eval.py and generalization.py consume trained models and problem instances → produce final results under results/
- Jupyter notebooks serve as interactive entry points to launch each solver

##### Architectural Patterns and Design Principles
- Modular separation of concerns: data ingestion, problem modeling, solver implementations, utilities, orchestration, and evaluation
- Plugin-style solver architecture: problems/MCLP defines a solver interface, allowing GA, Gurobi, and ReCovNet to be swapped or compared
- ML training pipeline: separation between model definition (nets/), training loop (train.py), configuration (options.py), and logging (utils/log_utils.py, tensorboardX)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "ReCovNet MCBLP Project"
        direction TB

        subgraph "Data Layer"
            direction TB
            DL1(("Raw Instances: data/MCLP_origin")):::data
            DL2(("Raw Instances: data/real")):::data
        end

        subgraph "Problem Layer"
            direction TB
            PL1["Problem Class\n(problem_MCLP.py)"]:::problem
            PL2["State Representation\n(state_MCLP.py)"]:::problem
        end

        subgraph "Algorithm Layer"
            direction TB
            subgraph "GA Solver" 
                direction TB
                GA1["GA Module\n(Algorithm/GA.py)"]:::algo
                GA2[/Notebook:\nBillboard_MCLP_GA.ipynb/]:::algo
            end
            subgraph "Gurobi Solver"
                direction TB
                GBR[/Notebook:\nBillboard_MCLP_solver.ipynb/]:::algo
            end
            subgraph "ReCovNet Solver"
                direction TB
                RN1["Attention Model\n(nets/attention_model.py)"]:::algo
                RN2["Graph Encoder\n(nets/graph_encoder.py)"]:::algo
                RN3["Reinforce Baselines\n(nets/reinforce_baselines.py)"]:::algo
                RN4[/Notebook:\nBillboards_MCLP_DRL.ipynb/]:::algo
            end
        end

        subgraph "Orchestration Layer"
            direction TB
            O1[/train.py/]:::orches
            O2[/run.py/]:::orches
            O3[/eval.py/]:::orches
            O4[/generalization.py/]:::orches
            O5[/options.py/]:::orches
        end

        subgraph "Utilities Layer"
            direction TB
            U1["Data Utils\n(utils/data_utils.py)"]:::util
            U2["Bool Mask Utils\n(utils/boolmask.py)"]:::util
            U3["Common Functions\n(utils/functions.py)"]:::util
            U4["Logging Utils\n(utils/log_utils.py)"]:::util
        end

        subgraph "Output Layer"
            direction TB
            OUT1(("Logs")):::output
            OUT2(("Checkpoints")):::output
            OUT3(("Results")):::output
        end
    end

    %% Data to Problem
    DL1 -->|"load data"| PL1
    DL2 -->|"load data"| PL1

    %% Problem to Solvers
    PL1 -->|"initialize state"| GA1
    PL1 -->|"initialize state"| GBR
    PL1 -->|"initialize state"| RN1
    PL2 -->|"provide state"| RN1

    %% Solvers to Orchestration
    GA1 -->|"run GA"| O2
    GBR -->|"run Gurobi"| O2
    RN1 -->|"train model"| O1
    RN2 -->|"encode graph"| O1
    RN3 -->|"baseline step"| O1

    RN4 -->|"interactive DRL"| O2

    %% Orchestration to Output
    O1 -->|"save checkpoint"| OUT2
    O1 -->|"write logs"| OUT1
    O3 -->|"write results"| OUT3
    O4 -->|"write results"| OUT3
    O2 -->|"write logs"| OUT1

    %% Utilities support all
    U1 -.-> DL1
    U1 -.-> DL2
    U1 -.-> PL1
    U1 -.-> GA1
    U1 -.-> GBR
    U1 -.-> RN1

    U2 -.-> PL2
    U3 -.-> PL1
    U3 -.-> GA1
    U4 -.-> O1
    U4 -.-> O3

    %% Click Events
    click DL1 "https://github.com/higisx/recovnet/tree/master/data/MCLP_origin/"
    click DL2 "https://github.com/higisx/recovnet/tree/master/data/real/"
    click PL1 "https://github.com/higisx/recovnet/blob/master/problems/MCLP/problem_MCLP.py"
    click PL2 "https://github.com/higisx/recovnet/blob/master/problems/MCLP/state_MCLP.py"
    click GA1 "https://github.com/higisx/recovnet/blob/master/Algorithm/GA.py"
    click GA2 "https://github.com/higisx/recovnet/blob/master/Billboard_MCLP_GA.ipynb"
    click GBR "https://github.com/higisx/recovnet/blob/master/Billboard_MCLP_solver.ipynb"
    click RN1 "https://github.com/higisx/recovnet/blob/master/nets/attention_model.py"
    click RN2 "https://github.com/higisx/recovnet/blob/master/nets/graph_encoder.py"
    click RN3 "https://github.com/higisx/recovnet/blob/master/nets/reinforce_baselines.py"
    click RN4 "https://github.com/higisx/recovnet/blob/master/Billboards_MCLP_DRL.ipynb"
    click O1 "https://github.com/higisx/recovnet/blob/master/train.py"
    click O2 "https://github.com/higisx/recovnet/blob/master/run.py"
    click O3 "https://github.com/higisx/recovnet/blob/master/eval.py"
    click O4 "https://github.com/higisx/recovnet/blob/master/generalization.py"
    click O5 "https://github.com/higisx/recovnet/blob/master/options.py"
    click U1 "https://github.com/higisx/recovnet/blob/master/utils/data_utils.py"
    click U2 "https://github.com/higisx/recovnet/blob/master/utils/boolmask.py"
    click U3 "https://github.com/higisx/recovnet/blob/master/utils/functions.py"
    click U4 "https://github.com/higisx/recovnet/blob/master/utils/log_utils.py"
    click OUT1 "https://github.com/higisx/recovnet/tree/master/logs/"
    click OUT2 "https://github.com/higisx/recovnet/tree/master/output/"
    click OUT3 "https://github.com/higisx/recovnet/tree/master/results/"

    %% Styles
    classDef data fill:#e0f2f1,stroke:#00695c,color:#004d40
    classDef problem fill:#e3f2fd,stroke:#1a237e,color:#0d47a1
    classDef algo fill:#fff3e0,stroke:#e65100,color:#bf360c
    classDef orches fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
    classDef util fill:#eeeeee,stroke:#424242,color:#212121
    classDef output fill:#e0f7fa,stroke:#00838f,color:#006064
```
