# tlancian/dith architecture

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

- Interactive diagram: https://gitdiagram.com/tlancian/dith
- Repository: https://github.com/tlancian/dith

## Overview

##### File structure
- Top level
- datasets/ – input graphs and their precomputed proximity/distance tables
- sw/ – the software package (source and compiled binaries)
- output/ – where result TSV files are written
- sw/src/algorithms/ – the core class SuperGreedyPP.java implementing the DITH algorithm
- sw/src/tools/ – supporting data structures (e.g., FastAndSimpleIndexMinPQ.java)
- sw/bin/algorithms/ and sw/bin/tools/ mirror the compiled .class files (ready to run)

##### Extract insights from the README
- The entry point is `java -Xms4g -Xmx4g algorithms.SuperGreedyPP ...`
- Positional arguments feed:
- path to dataset folder
- graph file (tsv)
- sets A and R (attractors/repulsers)
- λ₁, λ₂ coefficients
- proximity/distance files
- iteration cap T and approximation γ
- output folder + experiment ID

##### Main components to reflect
a. Data Sources
- Graph files (datasets/*/*.tsv)
- Precomputed proximity & distance tables
b. Compute Module
- JVM runtime loading sw/bin/algorithms/SuperGreedyPP
- Algorithms package (SuperGreedyPP.java)
- Tools package (FastAndSimpleIndexMinPQ.java, etc.)
c. CLI Interface
- Shell/Terminal invoking `java …` with parameters
d. Output Sink
- Result TSV in output_data_directory

##### Relationships and data flow
- CLI → JVM (启动 Java process)
- JVM reads Graph TSV + proximity/distance TSV from datasets
- JVM instantiates data structures via code in tools/
- SuperGreedyPP runs iterative greedy loops (uses FastAndSimpleIndexMinPQ)
- Computation writes summary TSV to output/

##### Architectural patterns & design principles
- Modular separation:
- **algorithms** module for core logic
- **tools** module for reusable data structures
- Single process, batch-oriented pipeline
- Explicit parameterization for reproducibility (all inputs passed as args)

## Diagram (Mermaid)

```mermaid
graph TB
    %% CLI Interface
    CLI["Shell/Terminal CLI"]:::cli
    CLI -->|"args: dataset_path, graph.tsv, sets A/R, λ₁, λ₂, proximity.tsv, distance.tsv, T, γ, output_dir, expID"| JVM

    %% Java Runtime
    JVM["Java 11 Runtime\n(java -Xms4g -Xmx4g algorithms.SuperGreedyPP)"]:::runtime

    %% Data Sources
    subgraph "Data Sources"
        DS["datasets/"]:::datastore
        subgraph "Graph TSVs"
            G1["gunsense.tsv"]:::datastore
            G2["vaxnovax.tsv"]:::datastore
        end
        subgraph "Distance TSVs"
            D1["gunsense_distance.tsv"]:::datastore
            D2["vaxnovax_distance.tsv"]:::datastore
        end
        subgraph "Proximity TSVs"
            P1["gunsense_proximity.tsv"]:::datastore
            P2["vaxnovax_proximity.tsv"]:::datastore
        end
    end

    %% Code Modules
    subgraph "Modules"
        AlgoSrc["SuperGreedyPP.java"]:::module
        AlgoBin["sw/bin/algorithms/"]:::module
        ToolsSrc["FastAndSimpleIndexMinPQ.java"]:::module
        ToolsBin["sw/bin/tools/"]:::module
    end

    %% Output Sink
    Output["output/"]:::datastore

    %% Data Flow
    JVM -->|"reads datasets"| DS
    JVM -->|"reads graph.tsv"| G1
    JVM -->|"reads graph.tsv"| G2
    JVM -->|"reads distance.tsv"| D1
    JVM -->|"reads distance.tsv"| D2
    JVM -->|"reads proximity.tsv"| P1
    JVM -->|"reads proximity.tsv"| P2

    JVM -->|"loads algorithm"| AlgoSrc
    JVM -->|"loads binaries"| AlgoBin
    JVM -->|"loads tools"| ToolsSrc
    JVM -->|"loads binaries"| ToolsBin

    AlgoSrc -->|"uses PQ"| ToolsSrc
    JVM -->|"executes SuperGreedyPP"| AlgoSrc
    JVM -->|"executes PQ"| ToolsSrc

    AlgoSrc -->|"writes result.tsv"| Output

    %% Click Events
    click DS "https://github.com/tlancian/dith/tree/main/datasets/"
    click G1 "https://github.com/tlancian/dith/blob/main/datasets/gunsense/gunsense.tsv"
    click G2 "https://github.com/tlancian/dith/blob/main/datasets/vaxnovax/vaxnovax.tsv"
    click D1 "https://github.com/tlancian/dith/blob/main/datasets/gunsense/gunsense_distance.tsv"
    click D2 "https://github.com/tlancian/dith/blob/main/datasets/vaxnovax/vaxnovax_distance.tsv"
    click P1 "https://github.com/tlancian/dith/blob/main/datasets/gunsense/gunsense_proximity.tsv"
    click P2 "https://github.com/tlancian/dith/blob/main/datasets/vaxnovax/vaxnovax_proximity.tsv"
    click AlgoSrc "https://github.com/tlancian/dith/blob/main/sw/src/algorithms/SuperGreedyPP.java"
    click AlgoBin "https://github.com/tlancian/dith/tree/main/sw/bin/algorithms/"
    click ToolsSrc "https://github.com/tlancian/dith/blob/main/sw/src/tools/FastAndSimpleIndexMinPQ.java"
    click ToolsBin "https://github.com/tlancian/dith/tree/main/sw/bin/tools/"

    %% Styles
    classDef module fill:#e0f7fa,stroke:#006064,stroke-width:1px;
    classDef datastore fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px;
    classDef cli fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px;
    classDef runtime fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px;
```
