# zangir/svrp architecture

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

- Interactive diagram: https://gitdiagram.com/zangir/svrp
- Repository: https://github.com/zangir/svrp

## Overview

##### Project Type & Purpose
- It is a research/optimization project focused on applying reinforcement learning techniques to a complex logistics problem (SVRP).
- The core purpose is to learn effective routing strategies under stochastic (uncertain) conditions, where factors like weather and noise influence travel costs and customer demand.

##### Main Components & Their Roles
a. Entry Point & Configuration:
- Main Component: main.py
- Orchestrates the training and testing via command-line arguments.
- Uses configuration settings loaded from config.py.
- Configuration Layer: config.py and requirements.txt
- Sets parameters like number of nodes, vehicles, embedding dimensions, etc.
- Lists dependencies and ensures the environment is correctly set up.

b. Environment Simulation:
- Environment Module (env folder):
- svrp_env.py: Implements the environment for simulating the stochastic vehicle routing problem.
- weather.py: Adds a weather simulation element that affects stochastic components.
- These components simulate the operational context (customer demand variability, travel cost fluctuations) which the RL agent must handle.

c. Models:
- Models Module (models folder):
- embedding.py: Implements state and memory embedding components necessary for representing the environment state.
- attention.py: Contains the attention mechanism used for effective node selection.
- policy.py: Aggregates the network architecture forming the complete policy model.
- This part of the project defines the neural network components critical for decision making.

d. Training:
- Training Module (training folder):
- reinforce.py: Contains the implementation of the REINFORCE algorithm for model training.
- baseline.py: Implements a baseline model to reduce training variance and stabilize learning.
- These files encapsulate the learning algorithms and optimization strategies.

e. Inference:
- Inference Module (inference folder):
- inference.py: Provides various inference strategies (greedy, random sampling, beam search) to evaluate the learned policy.
- This module helps in evaluating model performance and can be used in both simulated and potential real-world scenarios.

##### Relationships & Interactions
- The main.py file acts as the orchestration layer, integrating the configuration settings, environment setup, model instantiation, training routines, and inference operations.
- The environment components feed realistic, stochastic data (incorporating weather effects and noise) into the model.
- The models interact with both training (i.e., the REINFORCE and baseline modules are responsible for updating the model parameters) and inference (for evaluating model decisions using different strategies).
- Data flows are bidirectional: training outcomes update models, and inference results can be analyzed to tweak the training process.

##### Architectural Patterns / Design Principles
- Modular Design: Separation into distinct directories (env, models, training, inference) encourages a decoupled architecture.
- Pipeline/Flowbased Processing: Data flows from environment simulation into the neural network models, then through training and finally into different inference strategies.
- Reinforcement Learning Principles: Adopts algorithms with a baseline approach, illustrating an integration of policy gradient methods with variance reduction strategies.

##### Incorporating Specific Technologies
- Reinforcement Learning framework using REINFORCE with a baseline module.
- Neural network constructs like attention and embeddings, likely utilizing deep learning libraries (implicit from the structure, though specific frameworks like TensorFlow or PyTorch may be in requirements.txt).
- Simulation components in env simulate realistic conditions for the routing problem.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["main.py (Orchestration)"]
    B["config.py"]
    C["requirements.txt"]

    subgraph "Environment Simulation"
        D["svrp_env.py"]
        E["weather.py"]
    end

    subgraph "Neural Network Model"
        F["embedding.py"]
        G["attention.py"]
        H["policy.py"]
    end

    subgraph "Training Module"
        I["reinforce.py"]
        J["baseline.py"]
    end

    K["inference.py (Inference Module)"]

    %% Connections from Entry Point & Configuration
    A -->|"load_config"| B
    A -->|"load_config"| C
    A -->|"initialize"| D
    A -->|"initialize"| E

    %% Environment to Model
    D -->|"state_input"| F

    %% Neural Network Model Data Flow
    F -->|"feature_extract"| G
    G -->|"data_flow"| H

    %% Model and Training Feedback Loop
    H -->|"model_feedback"| I
    H -->|"model_feedback"| J
    I -->|"policy_update"| H
    J -->|"policy_update"| H

    %% Inference Interaction
    H -->|"inference_decision"| K

    %% Click Events
    click A "https://github.com/zangir/svrp/blob/main/main.py"
    click B "https://github.com/zangir/svrp/blob/main/config.py"
    click C "https://github.com/zangir/svrp/blob/main/requirements.txt"
    click D "https://github.com/zangir/svrp/blob/main/env/svrp_env.py"
    click E "https://github.com/zangir/svrp/blob/main/env/weather.py"
    click F "https://github.com/zangir/svrp/blob/main/models/embedding.py"
    click G "https://github.com/zangir/svrp/blob/main/models/attention.py"
    click H "https://github.com/zangir/svrp/blob/main/models/policy.py"
    click I "https://github.com/zangir/svrp/blob/main/training/reinforce.py"
    click J "https://github.com/zangir/svrp/blob/main/training/baseline.py"
    click K "https://github.com/zangir/svrp/blob/main/inference/inference.py"

    %% Styling
    classDef environment fill:#B3CDE0,stroke:#000,stroke-width:2px;
    classDef models fill:#C9E2B3,stroke:#000,stroke-width:2px;
    classDef training fill:#FAD02E,stroke:#000,stroke-width:2px;
    classDef inference fill:#F4978E,stroke:#000,stroke-width:2px;
    
    class D,E environment;
    class F,G,H models;
    class I,J training;
    class K inference;
    class A,B,C default;
```
