How fffasttime/mrfi works
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