# diegoflg/mcm architecture

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

- Interactive diagram: https://gitdiagram.com/diegoflg/mcm
- Repository: https://github.com/diegoflg/mcm

## Overview

##### Project Type and Purpose
- Full‐stack.ml pipeline (research implementation) for multi‐label recognition under noisy supervision.
- Core components: data ingestion (VOC datasets), model definition (confusion mixture modeling), training and evaluation scripts.

##### File Structure
- Top‐level scripts:
- mcm.py        – main training and evaluation driver
- test_sym.py   – evaluation/test harness
- voc_sym.py    – dataset loader and noise simulator for PASCAL VOC
- models.py     – neural network and confusion mixture modules
- utils.py      – helper functions (logging, metrics, checkpoints)
- requirements.txt – external dependencies (PyTorch, NumPy, Pandas)

##### Extract Insights from README
- Data: PASCAL VOC 2007 & 2012 (noisy/noiseless splits)
- Execution: command‐line flags control batch size, epochs, noise rate, etc.
- Architecture: PyTorch model with confusion mixture layer on top of base CNN (inferred from the paper title)

##### Main Components
a. Data Layer
– External: PASCAL VOC dataset repository
– Module: voc_sym.py loads images/labels and injects noise
b. Preprocessing & DataLoader
– Batch sampler, transforms, noise application
c. Model Layer
– Base CNN backbone (e.g., ResNet, defined in models.py)
– Confusion Mixture Module (custom layers in models.py)
d. Training Pipeline
– mcm.py orchestrates: forward pass → loss computation → backward pass → optimizer step
– utils.py functions: checkpointing, learning‐rate scheduling, logging metrics
e. Evaluation
– test_sym.py uses trained weights to compute mAP, precision, recall
f. External Services/Hardware
– PyTorch & CUDA on NVIDIA A100 GPU
– File system I/O for dataset and output folders

##### Relationships and Interactions
- Data flows from dataset files → voc_sym.py → DataLoader
- DataLoader feeds batches to the Model Layer
- Model outputs logits → Loss computation in training script
- Optimizer updates model parameters → Training loop in mcm.py
- utils.py invoked throughout for metrics, checkpoints, and logs
- test_sym.py reads model checkpoints, runs inference, outputs evaluation metrics

##### Architectural Patterns & Principles
- Modular separation: data loading vs. model definition vs. training logic
- Single‐responsibility files: each script focuses on one phase (train vs. eval)
- Dependency injection via command‐line args (flexible hyperparameterization)

##### Final Checklist
- All major .py files represented as components
- External datasets and hardware dependencies clearly marked
- Sufficient detail to trace from raw images to final evaluation metrics

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data & I/O Layer
    Dataset["PASCAL VOC 2007/2012"]:::data
    voc_sym["voc_sym.py\n(Data Loader & Noise Injector)"]:::data
    Dataset -->|"raw images & labels"| voc_sym
    click voc_sym "https://github.com/diegoflg/mcm/blob/main/voc_sym.py"

    %% Orchestration: Training
    mcm["mcm.py\n(Training Orchestration)"]:::orchestration
    voc_sym -->|"DataLoader.next()"| mcm
    click mcm "https://github.com/diegoflg/mcm/blob/main/mcm.py"

    %% Model & Computation Layer
    models["models.py\n(Base CNN +\nConfusion Mixture)"]:::model
    mcm -->|"model.forward()"| models
    models -->|"logits"| mcm
    mcm -->|"optimizer.step()"| models
    click models "https://github.com/diegoflg/mcm/blob/main/models.py"

    %% Utilities & Checkpoints
    utils["utils.py\n(Logging, Metrics,\nCheckpointing)"]:::util
    mcm -->|"logs, metrics"| utils
    mcm -->|"save_checkpoint()"| utils
    click utils "https://github.com/diegoflg/mcm/blob/main/utils.py"

    Checkpoint["Model Checkpoint\n(cylinder)"]:::data
    utils -->|"writes checkpoint"| Checkpoint

    %% Evaluation Harness
    test_sym["test_sym.py\n(Evaluation & mAP)"]:::orchestration
    Checkpoint -->|"load checkpoint"| test_sym
    test_sym -->|"compute mAP, precision, recall"| utils
    click test_sym "https://github.com/diegoflg/mcm/blob/main/test_sym.py"

    %% External Frameworks & Hardware
    PyTorchCUDA(["PyTorch + CUDA\n(NVIDIA A100 GPU)"]):::external
    models --> PyTorchCUDA
    mcm --> PyTorchCUDA

    %% Documentation & Dependencies
    requirements["requirements.txt\n(dependencies)"]:::data
    README["README.md\n(Overview & Usage)"]:::data
    click requirements "https://github.com/diegoflg/mcm/blob/main/requirements.txt"
    click README "https://github.com/diegoflg/mcm/blob/main/README.md"

    %% Styles
    classDef data fill:#add8e6,stroke:#000,stroke-width:1px
    classDef model fill:#98fb98,stroke:#000,stroke-width:1px
    classDef orchestration fill:#ffa500,stroke:#000,stroke-width:1px
    classDef util fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef external fill:#dda0dd,stroke:#000,stroke-width:1px
```
