# hl-yuan/pmimc architecture

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

- Interactive diagram: https://gitdiagram.com/hl-yuan/pmimc
- Repository: https://github.com/hl-yuan/pmimc

## Overview

##### Project type and purpose
- This is a research-oriented machine-learning codebase implementing “Prototype Matching Learning” for incomplete multi-view clustering.
- It provides modules for loading multi-view data, defining a neural network, computing prototype-matching losses, running a clustering algorithm (k-means GPU), and evaluating clustering performance.

##### File structure
Top-level files & directories:
- Dataset/
– Caltech101_7.mat, handwritten1031_v73.mat – raw multi-view datasets
- datasets.py – dataset wrappers & preprocessing pipelines
- load_data.py – functions to split views and simulate missing views
- network.py – PyTorch module definitions for the clustering network
- loss.py – prototype matching loss functions
- Nmetrics.py – evaluation metrics (e.g., clustering accuracy, NMI)
- kmeans_gpu.py – GPU-accelerated k-means clustering
- main.py – orchestration script: parses arguments, calls all pieces in order
- utils.py – shared utilities (logging, checkpointing, argument parsing)
- Dataset/ – storage of .mat files

##### Extract architectural insights from the README
- Core dependencies: PyTorch, NumPy, scikit-learn, munkres (Hungarian algorithm)
- Entry point: `python main.py --i_d 0 --missrate 0.5`
- Workflow stages mentioned: data loading, training, evaluation

##### Major system components
a. Data Storage & Input
– Raw `.mat` files under Dataset/
– Configuration (hyperparameters, missing-rate) passed to main.py
b. Data Loader & Preprocessor (`datasets.py`, `load_data.py`)
– Loads views, applies missing-view simulation
– Outputs batched multi-view tensors
c. Model Definition (`network.py`)
– Neural network encoders per view
– Prototype representation layers
d. Loss Computation (`loss.py`)
– Prototype Matching Loss
– Reconstruction or contrastive terms if any
e. Clustering Module (`kmeans_gpu.py`)
– Runs k-means on learned features to update prototypes
f. Training Loop (`main.py`)
– Orchestrates forward/backward passes, optimizer steps, prototype updates
g. Evaluation (`Nmetrics.py`)
– Calculates clustering metrics (ACC, NMI) after each epoch or final
h. Utilities (`utils.py`)
– Logging, checkpoint save/load, argument parsing

##### Relationships & data flows
- Data Loader outputs → Model Definition (forward pass)
- Model outputs & Prototypes → Loss Computation
- Loss → Optimizer step (inside Training Loop)
- Feature embeddings → Clustering Module to recompute prototypes
- Clustering labels + ground truth → Evaluation Module
- Utilities wrap around Training Loop for config, logging, checkpoints

##### Architectural patterns and design principles
- Modular separation: data, model, loss, clustering, evaluation
- Iterative EM-like loop: feature learning ↔ prototype update (k-means)
- Dependency injection: main.py wires all components based on config

##### Technologies & frameworks call-outs
- PyTorch: network, autograd, optim
- NumPy/Scipy: data manipulation, .mat loading
- scikit-learn & munkres: metrics and assignment algorithms
- CUDA (via PyTorch & kmeans_gpu.py) for acceleration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Handling
    subgraph "Data Handling"
        DS[(Dataset/)]:::data
        datasets["datasets.py"]:::data
        load["load_data.py"]:::data
    end

    %% Model & Loss
    subgraph "Model & Loss"
        net["network.py"]:::model
        loss["loss.py"]:::loss
    end

    %% Clustering
    subgraph "Clustering Module"
        kmeans["kmeans_gpu.py"]:::compute
    end

    %% Training & Orchestration
    subgraph "Training & Orchestration"
        main["main.py"]:::script
        utils["utils.py"]:::util
        conf["Config (args, hyperparams)"]:::util
    end

    %% Evaluation
    subgraph "Evaluation"
        eval["Nmetrics.py"]:::eval
    end

    %% Data Flow
    DS -->|raw .mat files| datasets
    datasets -->|batched tensors| load
    load -->|processed views| net
    net -->|embeddings| loss
    loss -->|loss values| main
    main -->|calls k-means| kmeans
    kmeans -->|prototypes| net
    main -->|evaluates| eval

    %% Utilities and Config
    conf -->|arguments| main
    utils -.->|logging, checkpoints| main

    %% Click Events
    click DS "https://github.com/hl-yuan/pmimc/tree/main/Dataset/"
    click datasets "https://github.com/hl-yuan/pmimc/blob/main/datasets.py"
    click load "https://github.com/hl-yuan/pmimc/blob/main/load_data.py"
    click net "https://github.com/hl-yuan/pmimc/blob/main/network.py"
    click loss "https://github.com/hl-yuan/pmimc/blob/main/loss.py"
    click kmeans "https://github.com/hl-yuan/pmimc/blob/main/kmeans_gpu.py"
    click main "https://github.com/hl-yuan/pmimc/blob/main/main.py"
    click utils "https://github.com/hl-yuan/pmimc/blob/main/utils.py"
    click eval "https://github.com/hl-yuan/pmimc/blob/main/Nmetrics.py"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef model fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef loss fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef compute fill:#FFD700,stroke:#333,stroke-width:1px;
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef script fill:#F0E68C,stroke:#333,stroke-width:1px;
    classDef eval fill:#DDA0DD,stroke:#333,stroke-width:1px;
```
