# dependablesystemslab/tensorfi2 architecture

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

- Interactive diagram: https://gitdiagram.com/dependablesystemslab/tensorfi2
- Repository: https://github.com/dependablesystemslab/tensorfi2

## Overview

##### Project type and purpose
- This is an open-source Python library/tool (TensorFI2) for injecting faults into TensorFlow 2/Keras models. It is not a full-stack web app but a standalone fault-injection framework with accompanying experiments and case studies.

##### File structure
- Top-level files:
- README.md, LICENSE, CONTRIBUTING.md, requirements.txt
- src/: the core injector implementation (tensorfi2 logic, config loader)
- conf/: YAML schema and default configurations for injection modes
- experiments/: example scripts showing dynamic (layer-outputs) and static (layer-states) injection methods, plus model checkpoints under experiments/*/h5
- case-studies/: higher-level end-to-end examples (traffic recognition, image segmentation) using the tool
- test-suite/: validation tests for injector correctness
- Patterns:
- src/tensorfi2.py implements the Injector API
- Configuration‐driven design: YAML → config parser → injection pipeline
- Plug-in style: user code calls tfi.inject(…) around Keras model

##### README for additional insights
- Architecture section describes two injection targets: layer states (static) and layer outputs (dynamic).
- Usage: import the library, call inject(model, confFile) before inference.

##### Relationships and interactions
- User Application → loads a Keras model → trains it
- User Application → imports TensorFI2 → calls inject(…)
- Injector Engine ← reads YAML config
- Injector Engine ↔ TensorFlow Model Graph (hooks into layers)
- Fault Types Module used by Injector Engine at injection points
- Results written to output directories (CSV, plots)
- Experiments/Case Studies use this pipeline end-to-end
- Test Suite separately invokes parts of the Injector Engine with mock models

##### Architectural patterns and design principles
- Configuration-driven: decouples injection logic from user code
- Dependency-inversion: Injector Engine interfaces with high‐level Keras APIs, not low‐level framework internals
- Plugin/Hook pattern: runtime wrapping of layer methods
- Separation of concerns: core library vs. examples vs. configs vs. tests

##### Relevant technologies, frameworks, or libraries
- Python 3.x
- TensorFlow 2 / Keras
- PyYAML for config parsing
- numpy
- h5py (via TensorFlow) for model files

##### Detailed capture of essential elements
- Don’t just group “src” as a blob—break it into Config Loader, Injector Engine, Fault Types
- Experiments and case-studies as client-applications invoking the core

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "User Application"
        UA["User Script / Notebook"]:::app
    end

    subgraph "Core Library (src/)"
        CL["Config Loader"]:::core
        IE["Injector Engine"]:::core
        FT["Fault Types Module"]:::core
    end

    subgraph "Configuration (conf/)"
        CONF["YAML Config Files"]:::config
    end

    subgraph "Experiments"
        subgraph "Layer-Outputs Experiments"
            LO_SCRIPTS["Python Demos (*.py)"]:::exp
            LO_H5["Model Checkpoints (h5)"]:::data
            LO_CONF["sample.yaml"]:::config
        end
        subgraph "Layer-States Experiments"
            LS_SCRIPTS["Python Demos (*.py)"]:::exp
            LS_H5["Model Checkpoints (h5)"]:::data
            LS_CONF["sample.yaml"]:::config
        end
    end

    subgraph "Case Studies"
        subgraph "Traffic Recognition"
            CS1_SCRIPT["traffic.py"]:::cs
            CS1_RES1["res-conv1 CSVs"]:::data
            CS1_RES2["res-conv2 CSVs"]:::data
        end
        subgraph "Image Segmentation"
            CS2_SCRIPT["imgseg.py"]:::cs
            CS2_OUT["fi-img outputs"]:::data
        end
    end

    subgraph "Test Suite"
        TESTS["Unit & Integration Tests"]:::test
    end

    subgraph "External Dependencies"
        TF["TensorFlow / Keras"]:::external
        PY["PyYAML, numpy"]:::external
    end

    subgraph "Documentation & Metadata"
        README["README.md"]:::doc
        CONTRIB["CONTRIBUTING.md"]:::doc
        LICENSE["LICENSE"]:::doc
        REQS["requirements.txt"]:::doc
    end

    %% Relationships
    UA -->|"calls tfi.inject"| IE
    UA -->|"defines/trains model"| TF
    IE -->|"reads config"| CL
    CL -->|"loads YAML"| CONF
    IE -->|"hooks into model"| TF
    IE -->|"uses fault types"| FT
    CONF -->|"drives injection"| IE

    LO_SCRIPTS -->|"demonstrate dynamic injection"| IE
    LO_CONF -->|"config for dynamic"| IE
    LO_H5 -->|"models for demos"| TF

    LS_SCRIPTS -->|"demonstrate static injection"| IE
    LS_CONF -->|"config for static"| IE
    LS_H5 -->|"models for demos"| TF

    CS1_SCRIPT -->|"uses core pipeline"| IE
    CS1_SCRIPT -->|"loads model"| TF
    IE -->|"writes results"| CS1_RES1
    IE -->|"writes results"| CS1_RES2

    CS2_SCRIPT -->|"uses core pipeline"| IE
    CS2_SCRIPT -->|"loads model"| TF
    IE -->|"writes results"| CS2_OUT

    TESTS -->|"validate loader & engine"| CL
    TESTS -->|"validate loader & engine"| IE

    PY -->|"used by"| CL
    PY -->|"used by"| IE

    %% Click Events
    click CL "https://github.com/dependablesystemslab/tensorfi2/blob/master/src/config.py"
    click IE "https://github.com/dependablesystemslab/tensorfi2/blob/master/src/tensorfi2.py"
    click FT "https://github.com/dependablesystemslab/tensorfi2/blob/master/src/tensorfi2.py"
    click CONF "https://github.com/dependablesystemslab/tensorfi2/tree/master/conf/"
    click LO_CONF "https://github.com/dependablesystemslab/tensorfi2/blob/master/experiments/layer-outputs/confFiles/sample.yaml"
    click LS_CONF "https://github.com/dependablesystemslab/tensorfi2/blob/master/experiments/layer-states/confFiles/sample.yaml"
    click LO_SCRIPTS "https://github.com/dependablesystemslab/tensorfi2/tree/master/experiments/layer-outputs/"
    click LO_H5 "https://github.com/dependablesystemslab/tensorfi2/tree/master/experiments/layer-outputs/h5/"
    click LS_SCRIPTS "https://github.com/dependablesystemslab/tensorfi2/tree/master/experiments/layer-states/"
    click LS_H5 "https://github.com/dependablesystemslab/tensorfi2/tree/master/experiments/layer-states/h5/"
    click CS1_SCRIPT "https://github.com/dependablesystemslab/tensorfi2/blob/master/case-studies/1-traffic-recognition/traffic.py"
    click CS1_RES1 "https://github.com/dependablesystemslab/tensorfi2/tree/master/case-studies/1-traffic-recognition/res-conv1/"
    click CS1_RES2 "https://github.com/dependablesystemslab/tensorfi2/tree/master/case-studies/1-traffic-recognition/res-conv2/"
    click CS2_SCRIPT "https://github.com/dependablesystemslab/tensorfi2/blob/master/case-studies/2-image-segmentation/imgseg.py"
    click CS2_OUT "https://github.com/dependablesystemslab/tensorfi2/tree/master/case-studies/2-image-segmentation/fi-img/"
    click TESTS "https://github.com/dependablesystemslab/tensorfi2/tree/master/test-suite/"
    click README "https://github.com/dependablesystemslab/tensorfi2/blob/master/README.md"
    click CONTRIB "https://github.com/dependablesystemslab/tensorfi2/blob/master/CONTRIBUTING.md"
    click LICENSE "https://github.com/dependablesystemslab/tensorfi2/tree/master/LICENSE"
    click REQS "https://github.com/dependablesystemslab/tensorfi2/blob/master/requirements.txt"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef config fill:#ff9,stroke:#333,stroke-width:1px
    classDef exp fill:#9ff,stroke:#333,stroke-width:1px
    classDef cs fill:#9f9,stroke:#333,stroke-width:1px
    classDef data fill:#fc9,stroke:#333,stroke-width:1px
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
    classDef app fill:#cdf,stroke:#333,stroke-width:1px
    classDef test fill:#f99,stroke:#333,stroke-width:1px
    classDef doc fill:#ddd,stroke:#333,stroke-width:1px
```
