# reiinakano/invariant-risk-minimization architecture

> Architecture diagram of the GitHub repository reiinakano/invariant-risk-minimization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reiinakano/invariant-risk-minimization
- Repository: https://github.com/reiinakano/invariant-risk-minimization

## Overview

##### Main Components
- Experiment Runner: This is the main entry point (main.py) and includes the separate notebook version (invariant_risk_minimization_colored_mnist.ipynb) for demonstration purposes in collaborative environments.
- Model & Training Logic: Components such as colored_mnist.py, minimum_irm.py, and parts of main.py implement the model (building the classifier and the IRM-specific penalty handling), the gradient norm scheduling, and the early stopping mechanism.
- Experiment Configuration: Represent the environment.yml and .gitignore/README files as part of the configuration and project metadata that set up dependencies (like PyTorch) and guide reproducibility.

##### Relationships and Interactions
- That the Experiment Runner (main.py & the notebook) orchestrates the overall experiment.
- Feedback loop for the early stopping mechanism, where performance (from training and evaluation) influences the training process.

##### Architectural Patterns and Principles
- Separation of Concerns: Even though the file structure is flat, conceptually separate the experiment orchestration (main.py/notebook) from the implementation of model training (colored_mnist.py and minimum_irm.py).
- Iterative/Incremental Training: The system uses a scheduled increase of the gradient norm penalty—a critical detail. Make sure to note this as part of the training loop component.
- Early Stopping Mechanism: Capture that while early stopping is built into the loop (with performance measured on all environments, including the test), it’s acknowledged as “imperfect” but crucial for training stability.

##### Relevant Technologies, Frameworks, or Libraries
- PyTorch: Mark this as a core dependency for implementing the model, loss functions, and backpropagation.
- Jupyter/Colab: For the interactive notebook demonstration.
- Environment Management: Mention the environment.yml file that guides dependency installation and setup.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Configuration & Dependencies
    subgraph "Configuration & Dependencies"
        C1["Configuration & Dependencies (environment.yml, .gitignore, README.md)"]:::config
    end

    %% Experiment Orchestration
    subgraph "Experiment Orchestration"
        ER1["Experiment Runner (main.py)"]:::process
        ER2["Notebook (invariant_risk_minimization_colored_mnist.ipynb)"]:::process
    end

    %% Dataset & Training
    subgraph "Dataset & Training"
        D1["Data Module (colored_mnist.py for data loading)"]:::data
        T1["Training Loop & IRM Logic (colored_mnist.py & minimum_irm.py)"]:::model
        T2["Evaluation & Feedback (EarlyStopping)"]:::process
    end

    %% Connections
    C1 -->|"initialize"| ER1
    C1 -->|"initialize"| ER2

    ER1 -->|"loadData"| D1
    ER2 -->|"loadData"| D1

    ER1 -->|"trainModel"| T1
    ER2 -->|"trainModel"| T1

    T1 -->|"evaluate"| T2
    T2 -->|"feedbackEarlyStopping"| T1

    %% Click Events
    click ER1 "https://github.com/reiinakano/invariant-risk-minimization/blob/master/main.py"
    click ER2 "https://github.com/reiinakano/invariant-risk-minimization/blob/master/invariant_risk_minimization_colored_mnist.ipynb"
    click D1 "https://github.com/reiinakano/invariant-risk-minimization/blob/master/colored_mnist.py"
    click T1 "https://github.com/reiinakano/invariant-risk-minimization/blob/master/minimum_irm.py"
    click C1 "https://github.com/reiinakano/invariant-risk-minimization/blob/master/environment.yml"

    %% Styles
    classDef process fill:#FEE,stroke:#F66,stroke-width:2px;
    classDef data fill:#CCF,stroke:#33F,stroke-width:2px;
    classDef model fill:#CFC,stroke:#393,stroke-width:2px;
    classDef config fill:#EEE,stroke:#999,stroke-width:2px;
```
