How jupiterliu/sae works
1. This repository is split into two major pipelines: class-incremental learning (CIL) training and adversarial attack benchmarking. The training side produces target incremental models; the attack side loads those checkpoints and evaluates multiple attack methods against them.
2. The two main entry points are:
- trainCIL.py for training CIL models from an experiment config.
- attack.py for running an attack against a chosen trained model and target class.
Shell scripts in scripts/ batch these flows across CIFAR-100 and ImageNet-100.
3. The CIL training subsystem is organized around:
- models/: implementations of nine incremental-learning algorithms: BiC, DER, Finetune, Foster, iCaRL, MEMO, PodNet, Replay, and WA.
- convs/: backbone/network variants used by those algorithms, including ResNet-style and cosine/modified variants.
- utils/: dataset handling, model factory logic, incremental-learning utilities, augmentation, plotting, and RL helpers.
- exps/: JSON experiment definitions that bind together dataset, method, and hyperparameters.
4. The data layer supports two main datasets:
- CIFAR-100, which is downloaded and prepared automatically.
- ImageNet-100, which is derived from ImageNet-1K using the provided class mapping / split files in datasets/.
The dataset utilities and managers in utils/data_manager.py, datasets/, and utils/data.py feed both CIL training and attack evaluation.
5. The attack benchmarking subsystem is centered in attacks/ and is driven by a shared base interface in attacks/BASEAttack.py plus attacks/attack_config.py. attack.py selects the concrete implementation based on --attack_method, wires in the trained target model, and executes the attack on the requested target class.
6. The attack implementations are mostly self-contained subprojects:
- attacks/SAE/ is the most fully structured package, with its own package source tree under src/gat/, runtime API, surrogate-model utilities, loss functions, optimizers, generators, datasets, and tests.
- attacks/AIM/ has a similar packaged layout with src/gat/, runtime helpers, model components, and examples.
- attacks/CGNC/, attacks/CleanSheet/, attacks/Gaker/, and attacks/UnivIntruder/ each bundle their own generators, losses, dataset adapters, and evaluation code.
7. Several attacks rely on a surrogate/model-guidance layer rather than only perturbing pixels directly. In the structured packages this shows up as:
- surrogate builders/hooks (attacks/AIM/src/gat/models/surrogate/)
- generator modules (.../generator/)
- custom losses and optimizers (.../loss/, .../optim/)
- runtime glue for execution, logging, and metrics (.../runtime/)
This separation suggests a common architecture: build or load a surrogate, generate adversarial examples, then evaluate transfer/sustainability against the frozen target CIL model.
8. CLIP-backed text/image guidance is an important external dependency for some attacks, especially SAE and UnivIntruder. The repo notes that a pretrained CLIP model is fetched from HuggingFace, and several attack packages include text templates, class-name mappings, and CLIP-related loss functions. That makes the attack side partly dependent on multimodal representation alignment, not just classifier gradients.
9. The evaluation flow is checkpoint-driven:
- Train a CIL model with trainCIL.py using an exps/*.json config.
- Store outputs under logs/.
- Run attack.py with the same config plus attack-specific arguments.
- Use the attack scripts to sweep methods/datasets and collect benchmark metrics.
This means the main architectural boundary is between “offline training artifacts” and “attack-time loading/evaluation.”
10. The testing and validation surface is strongest in the packaged attack modules and CleanSheet:
- attacks/AIM/tests/
- attacks/CleanSheet/tests/
- attacks/AIM/src/gat/...
These tests cover datasets, transforms, surrogate components, meter/util functions, configs, and trainer logic, which indicates those attack packages are intended to be reusable libraries rather than just scripts.
11. attacks/AIM/examples/ and attacks/Gaker/Generator/train.py show that some attack methods can be run in standalone training/generation modes, independent of the top-level benchmark runner. So the repo is not just a thin wrapper; it contains both a unified benchmark harness and method-specific subpipelines.
12. From an architecture-diagram perspective, the simplest accurate view is:
- Configs/scripts select a CIL method and attack method.
- Dataset utilities feed both training and attack phases.
- CIL model implementations produce the target checkpoint.
- Attack modules load the checkpoint, optionally use CLIP/surrogates/generators, craft adversarial samples, and report metrics.
- Logs/results are the sink for both training artifacts and attack evaluations.
Main entry points: BASEAttack.py Attack base · attack.py attack.py · trainCIL.py trainCIL.py · data_manager.py Data manager
Components 19
CIL training
Class-incremental learning pipeline that trains target checkpoints.
- trainCIL.py · Main training entry point for class-incremental experiments.
trainCIL.py - CIL models · Incremental-learning methods such as BiC, DER, iCaRL, MEMO, PodNet, Replay, WA, Foster, and Finetune.
models - Backbones · ResNet-style and modified convolutional backbones used by CIL methods.
convs - Training utils · Model factory, incremental-learning helpers, augmentation, plotting, and RL utilities.
utils - Experiment configs · Method- and dataset-specific experiment definitions for CIL runs.
exps
Attack benchmarking
Attack runners and method-specific attack implementations.
- attack.py · Main attack runner that selects an attack method and evaluates a target checkpoint.
attack.py - Attack base · Shared attack interface and configuration layer.
attacks/BASEAttack.py - Attack config · Common attack configuration and method selection settings.
attacks/attack_config.py - AIM · Packaged attack implementation with surrogate, generator, loss, optim, runtime, and tests.
attacks/AIM - SAE · Attack package with CLIP-related utilities, text templates, and model helpers.
attacks/SAE - UnivIntruder · Attack package with dataset adapters and CLIP/SigLIP-style losses.
attacks/UnivIntruder - Gaker · Attack package with generator training and benchmark utilities.
attacks/Gaker - CGNC · Attack package with text-feature extraction, generator, and inference code.
attacks/CGNC - CleanSheet · Attack package with training, poison data, models, and broad tests.
attacks/CleanSheet
Data layer
Shared dataset preparation and loaders used by both pipelines.
- Dataset prep · CIFAR-100 and ImageNet-100 preparation, splits, and class mapping files.
datasets - Data manager · Shared dataset and batch management used by training and attack evaluation.
utils/data_manager.py - Data utils · Shared dataset helpers and data access code for both pipelines.
utils/data.py
Execution flow
Entry points, batch scripts, and artifact flow.
- Shell scripts · Batch scripts for CIL training and attack sweeps on CIFAR-100 and ImageNet-100.
scripts - Artifacts · Training checkpoints and attack outputs produced during evaluation runs.
Connections 25
- Experiment configs → trainCIL.py: selects run · Experiment JSON defines dataset, method, and hyperparameters for training.
- trainCIL.py → CIL models: trains · Training entry point instantiates the chosen incremental-learning algorithm.
- trainCIL.py → Backbones: uses backbone · CIL methods build on shared convolutional backbones and variants.
- trainCIL.py → Data manager: loads data · Training consumes dataset managers and loaders.
- Data manager → Dataset prep: prepares · Dataset manager uses dataset-specific splits and mapping files.
- Data utils → Data manager: supports · Shared data helpers feed loader and dataset orchestration.
- Training utils → CIL models: supports · Factories and utility functions support incremental method execution.
- Shell scripts → trainCIL.py: batch train · Shell scripts launch training sweeps across datasets and methods.
- attack.py → Attack base: dispatches · Top-level attack runner selects a concrete attack implementation through the base interface.
- attack.py → Attack config: reads config · Attack runner consumes shared attack configuration.
- attack.py → Artifacts: loads checkpoint · Attack evaluation operates on trained target artifacts.
- attack.py → Data manager: loads data · Attack evaluation reuses the shared dataset layer.
- Attack base → AIM: implements · AIM is one concrete attack family behind the shared interface.
- Attack base → SAE: implements · SAE is one concrete attack family behind the shared interface.
- Attack base → UnivIntruder: implements · UnivIntruder is one concrete attack family behind the shared interface.
- Attack base → Gaker: implements · Gaker is one concrete attack family behind the shared interface.
- Attack base → CGNC: implements · CGNC is one concrete attack family behind the shared interface.
- Attack base → CleanSheet: implements · CleanSheet is one concrete attack family behind the shared interface.
- AIM → Artifacts: evaluates · AIM attacks run against frozen target models and report metrics.
- SAE → Artifacts: evaluates · SAE loads checkpoints and benchmarks transfer-style attacks.
- UnivIntruder → Artifacts: evaluates · UnivIntruder benchmarks against trained target checkpoints.
- Gaker → Artifacts: evaluates · Gaker generator outputs are evaluated against target models.
- CGNC → Artifacts: evaluates · CGNC inference benchmarks adversarial generation against target models.
- CleanSheet → Artifacts: evaluates · CleanSheet attacks and related training flows produce benchmark outputs.
- Shell scripts → attack.py: batch attack · Shell scripts sweep attack methods and dataset/model settings.