# irb-lab/py-ga-vrptw architecture

> Architecture diagram of the GitHub repository irb-lab/py-ga-vrptw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/irb-lab/py-ga-vrptw
- Repository: https://github.com/irb-lab/py-ga-vrptw

## Overview

py-ga-VRPTW solves vehicle-routing-with-time-windows instances using a genetic algorithm. A user runs a sample entry point, which configures costs and GA parameters and calls the solver; the solver loads an instance, evolves customer-order chromosomes, decodes and scores routes, then prints the best route and optionally exports generation metrics. The repository also supports Solomon benchmark data and custom text-to-JSON conversion. The graph follows documented capabilities and shown calls; unsampled solver details are represented only where the excerpts or README support them.

Main entry points: [`gavrptw/core.py`](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py) (GA orchestration), [`gavrptw/utils.py`](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/utils.py) (Text converter), [`text2json.py`](https://github.com/irb-lab/py-ga-vrptw/blob/master/text2json.py) (Standard conversion), [`text2json_customize.py`](https://github.com/irb-lab/py-ga-vrptw/blob/master/text2json_customize.py) (Custom conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Problem data"]
  node_benchmark["Solomon instances"]
  node_textdata["Text instances"]
  node_customdata["Custom instance"]
end

subgraph group_conversion["Instance conversion"]
  node_utils["Instance utilities<br/>[utils.py]"]
  node_converter["Text converter<br/>[utils.py]"]
  node_standardconvert["Standard conversion<br/>[text2json.py]"]
  node_customconvert["Custom conversion"]
end

subgraph group_solver["Genetic solver"]
  node_samples["Sample runs<br/>[sample_C204.py]"]
  node_customsample["Custom sample"]
  node_solverrun["GA orchestration<br/>[core.py]"]
  node_decode["Route decoding<br/>[core.py]"]
  node_fitness["Route evaluation<br/>[core.py]"]
  node_selection["Roulette selection<br/>[core.py]"]
  node_crossover["PMX crossover<br/>[core.py]"]
  node_mutation["Inverse mutation<br/>[core.py]"]
end

subgraph group_outputs["Results"]
  node_routeoutput["Best route output<br/>[core.py]"]
  node_csvoutput["Generation CSV"]
end

node_user(("User"))

node_user -->|"runs"| node_samples
node_user -->|"runs"| node_customsample
node_samples -->|"calls"| node_solverrun
node_customsample -->|"calls"| node_solverrun
node_solverrun -->|"loads instance"| node_benchmark
node_solverrun -->|"selects custom data"| node_customdata
node_solverrun -->|"loads instance"| node_utils
node_solverrun -->|"evaluates population"| node_fitness
node_fitness -->|"decodes chromosome"| node_decode
node_solverrun -->|"selects offspring"| node_selection
node_solverrun -->|"mates offspring"| node_crossover
node_solverrun -->|"mutates offspring"| node_mutation
node_solverrun -->|"prints best route"| node_routeoutput
node_solverrun -->|"writes metrics"| node_csvoutput
node_user -->|"converts data"| node_standardconvert
node_user -->|"converts data"| node_customconvert
node_standardconvert -->|"calls"| node_converter
node_customconvert -->|"calls"| node_converter
node_converter -->|"reads"| node_textdata
node_converter -->|"reads"| node_customdata
node_converter -->|"writes JSON"| node_benchmark

click node_benchmark "https://github.com/irb-lab/py-ga-vrptw/tree/master/data/json"
click node_textdata "https://github.com/irb-lab/py-ga-vrptw/tree/master/data/text"
click node_customdata "https://github.com/irb-lab/py-ga-vrptw/tree/master/data/text_customize"
click node_samples "https://github.com/irb-lab/py-ga-vrptw/blob/master/sample_C204.py"
click node_customsample "https://github.com/irb-lab/py-ga-vrptw/blob/master/sample_customized_data.py"
click node_solverrun "https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py"
click node_decode "https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py"
click node_fitness "https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py"
click node_selection "https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py"
click node_crossover "https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py"
click node_mutation "https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py"
click node_utils "https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/utils.py"
click node_converter "https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/utils.py"
click node_standardconvert "https://github.com/irb-lab/py-ga-vrptw/blob/master/text2json.py"
click node_customconvert "https://github.com/irb-lab/py-ga-vrptw/blob/master/text2json_customize.py"
click node_routeoutput "https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py"
click node_csvoutput "https://github.com/irb-lab/py-ga-vrptw/tree/master/results"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_benchmark,node_textdata,node_customdata,node_user toneBlue
class node_utils,node_converter,node_standardconvert,node_customconvert toneAmber
class node_samples,node_customsample,node_solverrun,node_decode,node_fitness,node_selection,node_crossover,node_mutation toneMint
class node_routeoutput,node_csvoutput toneRose
```

## Components

### Problem data

- [Solomon instances](https://github.com/irb-lab/py-ga-vrptw/tree/master/data/json): `data/json`
- [Text instances](https://github.com/irb-lab/py-ga-vrptw/tree/master/data/text): `data/text`
- [Custom instance](https://github.com/irb-lab/py-ga-vrptw/tree/master/data/text_customize): `data/text_customize`

### Instance conversion

- [Instance utilities](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/utils.py): `gavrptw/utils.py`
- [Text converter](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/utils.py): `gavrptw/utils.py`
- [Standard conversion](https://github.com/irb-lab/py-ga-vrptw/blob/master/text2json.py): `text2json.py`
- [Custom conversion](https://github.com/irb-lab/py-ga-vrptw/blob/master/text2json_customize.py): `text2json_customize.py`

### Genetic solver

- [Sample runs](https://github.com/irb-lab/py-ga-vrptw/blob/master/sample_C204.py): `sample_C204.py`
- [Custom sample](https://github.com/irb-lab/py-ga-vrptw/blob/master/sample_customized_data.py): `sample_customized_data.py`
- [GA orchestration](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py): `gavrptw/core.py`
- [Route decoding](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py): `gavrptw/core.py`
- [Route evaluation](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py): `gavrptw/core.py`
- [Roulette selection](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py): `gavrptw/core.py`
- [PMX crossover](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py): `gavrptw/core.py`
- [Inverse mutation](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py): `gavrptw/core.py`

### Results

- [Best route output](https://github.com/irb-lab/py-ga-vrptw/blob/master/gavrptw/core.py): `gavrptw/core.py`
- [Generation CSV](https://github.com/irb-lab/py-ga-vrptw/tree/master/results): `results`

### Other components

- **User**

## Connections

- User → Sample runs: runs (evidence: `README.md`)
- User → Custom sample: runs (evidence: `README.md`)
- Sample runs → GA orchestration: calls (evidence: `sample_C204.py`)
- Custom sample → GA orchestration: calls (evidence: `sample_customized_data.py`)
- GA orchestration → Solomon instances: loads instance (evidence: `README.md`)
- GA orchestration → Custom instance: selects custom data
- GA orchestration → Instance utilities: loads instance (evidence: `gavrptw/core.py`)
- GA orchestration → Route evaluation: evaluates population (evidence: `gavrptw/core.py`)
- Route evaluation → Route decoding: decodes chromosome (evidence: `gavrptw/core.py`)
- GA orchestration → Roulette selection: selects offspring (evidence: `gavrptw/core.py`)
- GA orchestration → PMX crossover: mates offspring (evidence: `gavrptw/core.py`)
- GA orchestration → Inverse mutation: mutates offspring (evidence: `gavrptw/core.py`)
- GA orchestration → Best route output: prints best route (evidence: `gavrptw/core.py`)
- GA orchestration → Generation CSV: writes metrics (evidence: `gavrptw/core.py`)
- User → Standard conversion: converts data (evidence: `README.md`)
- User → Custom conversion: converts data (evidence: `README.md`)
- Standard conversion → Text converter: calls (evidence: `text2json.py`)
- Custom conversion → Text converter: calls (evidence: `text2json_customize.py`)
- Text converter → Text instances: reads (evidence: `gavrptw/utils.py`)
- Text converter → Custom instance: reads (evidence: `gavrptw/utils.py`)
- Text converter → Solomon instances: writes JSON (evidence: `gavrptw/utils.py`)