SEU Injection Framework

Research Paper | Interactive Explainer

---

A Python framework for Single Event Upset (SEU) injection in neural networks for robustness analysis in harsh environments.

Documentation | Quick Start

Installation

Option 1 (recommended): PyPI

# Minimal core dependencies (PyTorch, NumPy, SciPy, tqdm)
pip install seu-injection-framework

# With analysis tools (scikit-learn, pandas, matplotlib, seaborn)
pip install "seu-injection-framework[analysis]"

# Everything (development, notebooks, vision models, docs)
pip install "seu-injection-framework[all]"

Option 2: Source (development)

git clone https://github.com/wd7512/seu-injection-framework.git
cd seu-injection-framework

# Using uv (recommended for development)
uv sync --extra dev --extra analysis --extra vision --extra notebooks

# Or using pip
pip install -e ".[all]"

GPU (optional): install a CUDA-enabled PyTorch first if required:

# Example for CUDA 12.x (adjust for your system)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install seu-injection-framework

Verify installation:

python -c "from seu_injection import ExhaustiveSEUInjector; print('Ready')"

Having issues? See Installation Guide.

Quick example

import torch
from seu_injection.core import ExhaustiveSEUInjector
from seu_injection.metrics import classification_accuracy

# Create a simple model and test data
model = torch.nn.Sequential(
  torch.nn.Linear(10, 64),
  torch.nn.ReLU(), 
  torch.nn.Linear(64, 2)
)
x_test = torch.randn(100, 10)
y_test = torch.randint(0, 2, (100,))

# Initialize SEU injector
injector = ExhaustiveSEUInjector(
  trained_model=model,
  criterion=classification_accuracy, 
  x=x_test,
  y=y_test
)

# Check baseline performance
print(f"Baseline accuracy: {injector.baseline_score:.2%}")

# Inject bit flips into sign bits (bit position 0)
results = injector.run_injector(bit_i=0)
print(f"Performed {len(results['criterion_score'])} injections")

# Sample some results
fault_impacts = [injector.baseline_score - score for score in results['criterion_score']]
print(f"Average accuracy drop: {sum(fault_impacts)/len(fault_impacts):.1%}")

Full tutorial: Quick Start Guide.

Examples

• Basic CNN robustness: examples/basic_cnn_robustness.py
• Architecture comparison: examples/architecture_comparison.py
• Interactive notebook: examples/Example_Attack_Notebook.ipynb
• ShipsNet experiments and notebook: examples/shipsnet/ (see README in folder)

Recent updates include reproducible ShipsNet experiments and improvements to injection protocols and metrics.

Features

• Works with standard PyTorch models (no code changes required)
• Suitable for reliability studies in harsh environments (space, nuclear, radiation)
• Optimized bit operations (10–100× faster than naive Python)
• Multiple injection modes: systematic per-bit or stochastic sampling
• Optional CUDA acceleration

Contributing & support

• Documentation: https://wd7512.github.io/seu-injection-framework/
• Contributing: CONTRIBUTING.md
• Issues: GitHub Issues
• Contact: wwdennis.home@gmail.com

Citation

If you use this framework in your research, please cite both the software and the research paper:

@software{seu_injection_framework,
  author = {William Dennis},
  title = {SEU Injection Framework},
  year = {2025},
  url = {https://github.com/wd7512/seu-injection-framework},
  version = {1.1.12}
}

@conference{icaart25,
  author = {William Dennis and James Pope},
  title = {A Framework for Developing Robust Machine Learning Models in Harsh Environments: A Review of CNN Design Choices},
  booktitle = {Proceedings of the 17th International Conference on Agents and Artificial Intelligence - Volume 2: ICAART},
  year = {2025},
  pages = {322-333},
  publisher = {SciTePress},
  organization = {INSTICC},
  doi = {10.5220/0013155000003890},
  isbn = {978-989-758-737-5},
  issn = {2184-433X}
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ for the research community studying neural network robustness in harsh environments.