# changxincao/tsppsvu architecture

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

- Interactive diagram: https://gitdiagram.com/changxincao/tsppsvu
- Repository: https://github.com/changxincao/tsppsvu

## Overview

TSPP-SVU is research software for transportation-service procurement under contextual stochastic uncertainty. Its core workflow prepares historical or generated instances, represents demand scenarios and procurement parameters, solves a procurement optimization model, and records decisions and diagnostics. The Java model layer spans SAA/CSAA, RCSAA, divergence-DRO, Wasserstein-DRO, and decomposition approaches; Python helpers support random-forest weighting and partial cross-moment experiments. The README documents formal experiment entry points, but those runners are absent from the supplied tree, so they are not represented as source nodes. Links for unsampled capabilities are limited to documented relationships.

Main entry points: [`src/Basic/Data.java`](https://github.com/changxincao/tsppsvu/blob/main/src/Basic/Data.java) (Procurement data), [`src/Model/SAAModel.java`](https://github.com/changxincao/tsppsvu/blob/main/src/Model/SAAModel.java) (SAA / CSAA), [`src/Model/Solution.java`](https://github.com/changxincao/tsppsvu/blob/main/src/Model/Solution.java) (Solution diagnostics), [`src/Model/ContextualWassersteinBoxCcgSolver.java`](https://github.com/changxincao/tsppsvu/blob/main/src/Model/ContextualWassersteinBoxCcgSolver.java) (Wasserstein CCG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Data and configuration"]
  node_historical_loader["History loader"]
  node_sample_builder["Sample builder<br/>[SampleBuilder.java]"]
  node_instance_generator["Instance generator"]
  node_config["Run configuration<br/>[Config.java]"]
  node_procurement_data["Procurement data<br/>[Data.java]"]
  node_parameters["Procurement parameters"]
end

subgraph group_context["Context weighting"]
  node_context_weights["Context weights"]
  node_knn_weights["KNN weights"]
end

subgraph group_optimization["Optimization models"]
  node_saa["SAA / CSAA<br/>[SAAModel.java]"]
  node_second_stage["Recourse evaluation"]
  node_rcsaa["RCSAA decomposition"]
  node_rcsaa_support["RCSAA support"]
  node_dro["Divergence DRO<br/>[DROBenders.java]"]
  node_wasserstein["Wasserstein DRO"]
  node_wasserstein_ccg["Wasserstein CCG"]
  node_wasserstein_input["Wasserstein input"]
  node_wasserstein_oracle["Wasserstein oracle"]
end

subgraph group_experiments["Python experiments"]
  node_rf_weights["Forest weights<br/>[rf_leaf_weights.py]"]
  node_pcm_solver["PCM solver<br/>[solve_pcm.py]"]
  node_feasible_solver["Feasible solver"]
end

subgraph group_results["Results"]
  node_solution["Solution diagnostics<br/>[Solution.java]"]
  node_output_manager["Result writer<br/>[OutputManager.java]"]
end

node_researcher(("Researcher"))
node_cplex(("CPLEX"))
node_mosek(("MOSEK"))

node_researcher -.->|"loads history"| node_historical_loader
node_researcher -.->|"runs experiments"| node_instance_generator
node_historical_loader -->|"builds samples"| node_sample_builder
node_instance_generator -->|"creates instances"| node_procurement_data
node_sample_builder -->|"assembles data"| node_procurement_data
node_config -->|"configures weighting"| node_context_weights
node_procurement_data -->|"weights samples"| node_context_weights
node_procurement_data -->|"weights neighbors"| node_knn_weights
node_procurement_data -->|"solves scenarios"| node_saa
node_saa -->|"evaluates recourse"| node_second_stage
node_procurement_data -->|"solves robust model"| node_rcsaa
node_rcsaa -->|"solves scenario cuts"| node_rcsaa_support
node_procurement_data -->|"solves DRO"| node_dro
node_procurement_data -->|"solves contextual DRO"| node_wasserstein
node_procurement_data -->|"builds input"| node_wasserstein_input
node_wasserstein -.->|"uses input"| node_wasserstein_input
node_wasserstein_ccg -->|"uses input"| node_wasserstein_input
node_wasserstein_ccg -->|"separates demands"| node_wasserstein_oracle
node_researcher -.->|"runs Python helper"| node_rf_weights
node_researcher -.->|"runs PCM experiment"| node_pcm_solver
node_pcm_solver -->|"uses feasibility solver"| node_feasible_solver
node_saa -->|"returns solution"| node_solution
node_dro -->|"returns solution"| node_solution
node_wasserstein -->|"returns solution"| node_solution
node_output_manager -->|"writes diagnostics"| node_solution
node_output_manager -->|"writes data outputs"| node_procurement_data
node_saa -.->|"optimizes model"| node_cplex
node_wasserstein_ccg -->|"optimizes master"| node_cplex
node_pcm_solver -.->|"solves PCM"| node_mosek

click node_historical_loader "https://github.com/changxincao/tsppsvu/blob/main/src/Helper/basicHelper/CsvHistoryLoader.java"
click node_sample_builder "https://github.com/changxincao/tsppsvu/blob/main/src/Helper/basicHelper/SampleBuilder.java"
click node_instance_generator "https://github.com/changxincao/tsppsvu/blob/main/src/Helper/basicHelper/InstanceGenerator.java"
click node_config "https://github.com/changxincao/tsppsvu/blob/main/src/Helper/basicHelper/Config.java"
click node_procurement_data "https://github.com/changxincao/tsppsvu/blob/main/src/Basic/Data.java"
click node_parameters "https://github.com/changxincao/tsppsvu/blob/main/src/Basic/ProcurementParams.java"
click node_context_weights "https://github.com/changxincao/tsppsvu/blob/main/src/Helper/calculateHelper/WeightCalculator.java"
click node_knn_weights "https://github.com/changxincao/tsppsvu/blob/main/src/Helper/calculateHelper/KNearestNeighborWeightCalculator.java"
click node_saa "https://github.com/changxincao/tsppsvu/blob/main/src/Model/SAAModel.java"
click node_second_stage "https://github.com/changxincao/tsppsvu/blob/main/src/Model/SecondStageEvaluator.java"
click node_rcsaa "https://github.com/changxincao/tsppsvu/blob/main/src/Model/RCSAALBBDSearchSolver.java"
click node_rcsaa_support "https://github.com/changxincao/tsppsvu/blob/main/src/Model/RCSAADecompositionSupport.java"
click node_dro "https://github.com/changxincao/tsppsvu/blob/main/src/Model/DROBenders.java"
click node_wasserstein "https://github.com/changxincao/tsppsvu/blob/main/src/Model/ContextualWassersteinBoxSolver.java"
click node_wasserstein_ccg "https://github.com/changxincao/tsppsvu/blob/main/src/Model/ContextualWassersteinBoxCcgSolver.java"
click node_wasserstein_input "https://github.com/changxincao/tsppsvu/blob/main/src/Model/WassersteinBoxInput.java"
click node_wasserstein_oracle "https://github.com/changxincao/tsppsvu/blob/main/src/Model/WassersteinBoxOracle.java"
click node_rf_weights "https://github.com/changxincao/tsppsvu/blob/main/analysis/trb_svu/rf_leaf_weights.py"
click node_pcm_solver "https://github.com/changxincao/tsppsvu/blob/main/analysis/trb_svu/solve_pcm.py"
click node_feasible_solver "https://github.com/changxincao/tsppsvu/blob/main/analysis/trb_svu/msk_feasible_solver.py"
click node_solution "https://github.com/changxincao/tsppsvu/blob/main/src/Model/Solution.java"
click node_output_manager "https://github.com/changxincao/tsppsvu/blob/main/src/Helper/basicHelper/OutputManager.java"

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_historical_loader,node_sample_builder,node_instance_generator,node_config,node_procurement_data,node_parameters toneBlue
class node_context_weights,node_knn_weights toneAmber
class node_saa,node_second_stage,node_rcsaa,node_rcsaa_support,node_dro,node_wasserstein,node_wasserstein_ccg,node_wasserstein_input,node_wasserstein_oracle toneMint
class node_rf_weights,node_pcm_solver,node_feasible_solver toneRose
class node_solution,node_output_manager,node_researcher,node_cplex,node_mosek toneIndigo
```

## Components

### Data and configuration

- [History loader](https://github.com/changxincao/tsppsvu/blob/main/src/Helper/basicHelper/CsvHistoryLoader.java): `src/Helper/basicHelper/CsvHistoryLoader.java`
- [Sample builder](https://github.com/changxincao/tsppsvu/blob/main/src/Helper/basicHelper/SampleBuilder.java): `src/Helper/basicHelper/SampleBuilder.java`
- [Instance generator](https://github.com/changxincao/tsppsvu/blob/main/src/Helper/basicHelper/InstanceGenerator.java): `src/Helper/basicHelper/InstanceGenerator.java`
- [Run configuration](https://github.com/changxincao/tsppsvu/blob/main/src/Helper/basicHelper/Config.java): `src/Helper/basicHelper/Config.java`
- [Procurement data](https://github.com/changxincao/tsppsvu/blob/main/src/Basic/Data.java): `src/Basic/Data.java`
- [Procurement parameters](https://github.com/changxincao/tsppsvu/blob/main/src/Basic/ProcurementParams.java): `src/Basic/ProcurementParams.java`

### Context weighting

- [Context weights](https://github.com/changxincao/tsppsvu/blob/main/src/Helper/calculateHelper/WeightCalculator.java): `src/Helper/calculateHelper/WeightCalculator.java`
- [KNN weights](https://github.com/changxincao/tsppsvu/blob/main/src/Helper/calculateHelper/KNearestNeighborWeightCalculator.java): `src/Helper/calculateHelper/KNearestNeighborWeightCalculator.java`

### Optimization models

- [SAA / CSAA](https://github.com/changxincao/tsppsvu/blob/main/src/Model/SAAModel.java): `src/Model/SAAModel.java`
- [Recourse evaluation](https://github.com/changxincao/tsppsvu/blob/main/src/Model/SecondStageEvaluator.java): `src/Model/SecondStageEvaluator.java`
- [RCSAA decomposition](https://github.com/changxincao/tsppsvu/blob/main/src/Model/RCSAALBBDSearchSolver.java): `src/Model/RCSAALBBDSearchSolver.java`
- [RCSAA support](https://github.com/changxincao/tsppsvu/blob/main/src/Model/RCSAADecompositionSupport.java): `src/Model/RCSAADecompositionSupport.java`
- [Divergence DRO](https://github.com/changxincao/tsppsvu/blob/main/src/Model/DROBenders.java): `src/Model/DROBenders.java`
- [Wasserstein DRO](https://github.com/changxincao/tsppsvu/blob/main/src/Model/ContextualWassersteinBoxSolver.java): `src/Model/ContextualWassersteinBoxSolver.java`
- [Wasserstein CCG](https://github.com/changxincao/tsppsvu/blob/main/src/Model/ContextualWassersteinBoxCcgSolver.java): `src/Model/ContextualWassersteinBoxCcgSolver.java`
- [Wasserstein input](https://github.com/changxincao/tsppsvu/blob/main/src/Model/WassersteinBoxInput.java): `src/Model/WassersteinBoxInput.java`
- [Wasserstein oracle](https://github.com/changxincao/tsppsvu/blob/main/src/Model/WassersteinBoxOracle.java): `src/Model/WassersteinBoxOracle.java`

### Python experiments

- [Forest weights](https://github.com/changxincao/tsppsvu/blob/main/analysis/trb_svu/rf_leaf_weights.py): `analysis/trb_svu/rf_leaf_weights.py`
- [PCM solver](https://github.com/changxincao/tsppsvu/blob/main/analysis/trb_svu/solve_pcm.py): `analysis/trb_svu/solve_pcm.py`
- [Feasible solver](https://github.com/changxincao/tsppsvu/blob/main/analysis/trb_svu/msk_feasible_solver.py): `analysis/trb_svu/msk_feasible_solver.py`

### Results

- [Solution diagnostics](https://github.com/changxincao/tsppsvu/blob/main/src/Model/Solution.java): `src/Model/Solution.java`
- [Result writer](https://github.com/changxincao/tsppsvu/blob/main/src/Helper/basicHelper/OutputManager.java): `src/Helper/basicHelper/OutputManager.java`

### Other components

- **Researcher**
- **CPLEX**
- **MOSEK**

## Connections

- Researcher → History loader: loads history (evidence: `README.md`)
- Researcher → Instance generator: runs experiments (evidence: `README.md`)
- History loader → Sample builder: builds samples (evidence: `src/Helper/basicHelper/SampleBuilder.java`)
- Instance generator → Procurement data: creates instances (evidence: `src/Helper/basicHelper/InstanceGenerator.java`)
- Sample builder → Procurement data: assembles data (evidence: `src/Helper/basicHelper/SampleBuilder.java`)
- Run configuration → Context weights: configures weighting (evidence: `src/Helper/calculateHelper/WeightCalculator.java`)
- Procurement data → Context weights: weights samples (evidence: `src/Helper/calculateHelper/WeightCalculator.java`)
- Procurement data → KNN weights: weights neighbors (evidence: `src/Helper/calculateHelper/KNearestNeighborWeightCalculator.java`)
- Procurement data → SAA / CSAA: solves scenarios (evidence: `src/Model/SAAModel.java`)
- SAA / CSAA → Recourse evaluation: evaluates recourse (evidence: `src/Model/SAAModel.java`)
- Procurement data → RCSAA decomposition: solves robust model (evidence: `src/Model/RCSAALBBDSearchSolver.java`)
- RCSAA decomposition → RCSAA support: solves scenario cuts (evidence: `src/Model/RCSAALBBDSearchSolver.java`)
- Procurement data → Divergence DRO: solves DRO (evidence: `src/Model/DROBenders.java`)
- Procurement data → Wasserstein DRO: solves contextual DRO (evidence: `src/Model/ContextualWassersteinBoxSolver.java`)
- Procurement data → Wasserstein input: builds input (evidence: `src/Model/WassersteinBoxInput.java`)
- Wasserstein DRO → Wasserstein input: uses input
- Wasserstein CCG → Wasserstein input: uses input (evidence: `src/Model/ContextualWassersteinBoxCcgSolver.java`)
- Wasserstein CCG → Wasserstein oracle: separates demands (evidence: `src/Model/ContextualWassersteinBoxCcgSolver.java`)
- Researcher → Forest weights: runs Python helper (evidence: `README.md`)
- Researcher → PCM solver: runs PCM experiment (evidence: `README.md`)
- PCM solver → Feasible solver: uses feasibility solver (evidence: `analysis/trb_svu/solve_pcm.py`)
- SAA / CSAA → Solution diagnostics: returns solution (evidence: `src/Model/SAAModel.java`)
- Divergence DRO → Solution diagnostics: returns solution (evidence: `src/Model/DROBenders.java`)
- Wasserstein DRO → Solution diagnostics: returns solution (evidence: `src/Model/ContextualWassersteinBoxSolver.java`)
- Result writer → Solution diagnostics: writes diagnostics (evidence: `src/Helper/basicHelper/OutputManager.java`)
- Result writer → Procurement data: writes data outputs (evidence: `src/Helper/basicHelper/OutputManager.java`)
- SAA / CSAA → CPLEX: optimizes model (evidence: `README.md`)
- Wasserstein CCG → CPLEX: optimizes master (evidence: `src/Model/ContextualWassersteinBoxCcgSolver.java`)
- PCM solver → MOSEK: solves PCM (evidence: `README.md`)
