# fffasttime/mrfi architecture

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

- Interactive diagram: https://gitdiagram.com/fffasttime/mrfi
- Repository: https://github.com/fffasttime/mrfi

## Overview

##### Project Type and Purpose
- This is an open-source Python library and CLI/GUI tool called **Multi-Resolution Fault Injector (MRFI)** for injecting configurable faults into PyTorch neural networks.
- It provides both programmatic APIs (`mrfi/`), command-line scripts (`run_experiment.py`, `run_gui.py`), a Qt-based GUI (`mrfi_gui/`), preset configuration files (`easyconfigs/`), and example usage notebooks and scripts (`experiments/`, `dataset/`).

##### File Structure and Architectural Patterns
- Top-level directories:
- **mrfi/** – core fault-injection engine, split into modules: `selector`, `error_mode`, `quantization`, `observer`, `experiment`, `easyconfig_presets`.
- **mrfi_gui/** – GUI layer built on Qt (PySide/PyQt), presenting the engine via a visual interface.
- **dataset/** – helper scripts to load sample datasets and model definitions.
- **easyconfigs/** – YAML presets for common injection scenarios, loaded via `EasyConfig`.
- **experiments/** – user-level scripts and notebooks that wire up dataset + MRFI to run full experiments.
- **test/** – unit tests organized by core module (e.g., `test_selector.py`, `test_quantization.py`).
- Config & CI: `.github/workflows` (Codecov), `mkdocs.yml` for documentation site, `pyproject.toml` and `requirements*.txt` for build/deps.

a. **User Interfaces**
- **CLI Runner** (`run_experiment.py`)
- **GUI App** (`run_gui.py` → `mrfi_gui/mainwindow.py`)
b. **Core Engine** (`mrfi/`) subdivided into:
- **Configuration Loader** (`easyconfig_presets.py`, YAML files)
- **Selector** (`selector.py`) – decides injection positions
- **Error Mode** (`error_mode.py`) – bit-flip, noise, stuck-at, etc.
- **Quantization** (`quantization.py`) – preprocessing models to fixed/floating-point, dynamic/static ranges
- **Injector & Observer** (`mrfi.py`, `observer.py`) – applies faults and collects metrics
- **Experiment Orchestrator** (`experiment.py`) – wraps accuracy/BER experiments, golden runs
c. **Dataset & Model Definitions** (`dataset/`) – provides data loaders and network classes (LeNet, ResNet, etc.)
d. **External Dependencies** – PyTorch, NumPy, Matplotlib, PyYAML, Qt

##### Relationships and Data Flow
- **CLI/GUI** → initialize **Configuration Loader** (YAML → `EasyConfig` objects)
- Load a **Model** from `dataset/` → wrap in **MRFI Engine**
- **Quantization** module transforms model weights/activations if needed
- **Selector** & **Error Mode** modules decide where and how to inject faults
- During inference, **Injector** applies faults; **Observer** collects internal metrics
- **Experiment** routines (`Acc_experiment`, `BER_Acc_experiment`) drive multiple runs, modify selector rates, record results
- Results → returned to CLI/GUI or plotted via Matplotlib, saved to disk

##### Architectural Patterns and Principles
- **Modular plug-in design**: `selector`, `error_mode`, and `quantization` are swappable via a common interface
- **Separation of concerns**: config loading, injection logic, observation, and experiment orchestration are in distinct modules
- **Extensibility**: Users can add new selectors or error modes, extend via Python or YAML

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI Runner<br/>(run_experiment.py)"]:::ui
        GUI["GUI App<br/>(run_gui.py)"]:::ui
        GUI --> GUILayout
    end

    %% GUI components
    GUILayout["GUI Layout<br/>(mainwindow.ui)"]:::ui

    %% Configuration
    subgraph "Configuration Loader"
        Config["EasyConfig Loader<br/>(easyconfig_presets.py)"]:::config
        PresetGen["Preset Generator<br/>(make_preset.py)"]:::config
        Config -->|"loads presets"| PresetGen
    end

    %% Core Engine
    subgraph "Core Engine (mrfi/)"
        direction TB
        Selector["Selector Module<br/>(selector.py)"]:::core
        ErrorMode["Error Mode Module<br/>(error_mode.py)"]:::core
        Quant["Quantization Module<br/>(quantization.py)"]:::core
        Injector["Injector Engine<br/>(mrfi.py)"]:::core
        Observer["Observer Module<br/>(observer.py)"]:::core
        Experiment["Experiment Orchestrator<br/>(experiment.py)"]:::core

        Experiment --> Quant
        Experiment --> Selector
        Experiment --> ErrorMode
        Experiment --> Injector
        Experiment --> Observer
    end

    %% Data sources and scripts
    subgraph "Data & Examples"
        Dataset["Dataset & Models<br/>(dataset/)"]:::data
        Examples["Example Experiments<br/>(experiments/)"]:::scripts
    end

    %% Easyconfigs directory
    EasyConfigs["YAML Presets<br/>(easyconfigs/)"]:::config

    %% Unit Tests
    subgraph "Unit Tests"
        TestSel["test_selector.py"]:::tests
        TestErr["test_error_mode.py"]:::tests
        TestQuant["test_quantization.py"]:::tests
        TestObs["test_observer.py"]:::tests
        TestExp["test_experiment.py"]:::tests
    end

    %% External Dependencies
    subgraph "External Libraries"
        PyTorch["PyTorch"]:::ext
        NumPy["NumPy"]:::ext
        Matplotlib["Matplotlib"]:::ext
        PyYAML["PyYAML"]:::ext
        QtLib["Qt (PySide/PyQt)"]:::ext
    end

    %% Data flows
    CLI -->|"init"| Config
    GUI -->|"init"| Config
    EasyConfigs -->|"provides YAML"| Config
    Dataset -->|"load models/data"| Experiment
    Examples -->|"use engine"| Experiment
    Config -->|"provide config"| Experiment

    Experiment -->|"calls"| Injector
    Injector -->|"injects faults into"| Dataset
    Dataset -->|"model weights/activations"| Quant
    Quant -->|"preprocess model"| Injector
    Selector -->|"position selection"| Injector
    ErrorMode -->|"fault definition"| Injector
    Injector -->|"faulted inference"| Observer
    Observer -->|"collect metrics"| Experiment

    %% Tests relations
    TestSel --> Selector
    TestErr --> ErrorMode
    TestQuant --> Quant
    TestObs --> Observer
    TestExp --> Experiment

    %% External deps usage
    Experiment --> PyTorch
    Experiment --> NumPy
    Experiment --> Matplotlib
    Config --> PyYAML
    GUI --> QtLib

    %% Click events
    click CLI "https://github.com/fffasttime/mrfi/blob/main/run_experiment.py"
    click GUI "https://github.com/fffasttime/mrfi/blob/main/run_gui.py"
    click GUILayout "https://github.com/fffasttime/mrfi/blob/main/mrfi_gui/mainwindow.ui"
    click Config "https://github.com/fffasttime/mrfi/blob/main/mrfi/easyconfig_presets.py"
    click PresetGen "https://github.com/fffasttime/mrfi/blob/main/easyconfigs/make_preset.py"
    click Selector "https://github.com/fffasttime/mrfi/blob/main/mrfi/selector.py"
    click ErrorMode "https://github.com/fffasttime/mrfi/blob/main/mrfi/error_mode.py"
    click Quant "https://github.com/fffasttime/mrfi/blob/main/mrfi/quantization.py"
    click Injector "https://github.com/fffasttime/mrfi/blob/main/mrfi/mrfi.py"
    click Observer "https://github.com/fffasttime/mrfi/blob/main/mrfi/observer.py"
    click Experiment "https://github.com/fffasttime/mrfi/blob/main/mrfi/experiment.py"
    click Dataset "https://github.com/fffasttime/mrfi/tree/main/dataset/"
    click Examples "https://github.com/fffasttime/mrfi/tree/main/experiments/"
    classDef ui fill:#f9f,stroke:#333,stroke-width:1px
    classDef config fill:#ff9,stroke:#333,stroke-width:1px
    classDef core fill:#9f9,stroke:#333,stroke-width:1px
    classDef data fill:#9ff,stroke:#333,stroke-width:1px
    classDef scripts fill:#fc9,stroke:#333,stroke-width:1px
    classDef tests fill:#ccc,stroke:#333,stroke-width:1px
    classDef ext fill:#eef,stroke:#333,stroke-width:1px
```
