# andyj1/scga architecture

> Architecture diagram of the GitHub repository andyj1/scga, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andyj1/scga
- Repository: https://github.com/andyj1/scga

## Overview

This repository is a research-training codebase for a black-box generative adversarial attack method called SCGA. Architecturally, it is not a deployed service; it is an offline PyTorch pipeline centered on generating adversarial perturbations, training a generator against surrogate classifiers, and evaluating transferability on multiple image datasets.

Main system boundaries

1. Training entrypoint
- `train_BIA_ours.py` is the primary top-level script.
- It orchestrates the full experiment: argument parsing, dataset selection, model construction, training, and evaluation.
- The README points to `utee/parser.py` for the supported CLI options, so the training behavior is configured centrally rather than through multiple scripts.

2. Dataset and data-loading layer
The repository separates generic dataset support from a specialized fine-grained dataset package.

- `datasets/paths.py`
  - Defines the root data directory (`DATA_ROOT_DIR`), which is the filesystem boundary between code and local datasets.

- `datasets/imagenet/`
  - Handles ImageNet-specific loading and label metadata.
  - Contains dataset logic plus multiple model wrappers (`alexnet.py`, `resnet.py`, `vgg.py`, `inception.py`, `squeezenet.py`) and mapping files for class IDs and names.
  - This indicates the project uses ImageNet both as a training/evaluation domain and as a label-resolution source.

- `datasets/DCL_finegrained/`
  - A self-contained fine-grained dataset submodule for AIR, CUB, and Stanford Cars.
  - Includes dataset definitions, transforms, configuration, model loading, and a dedicated training script.
  - The presence of `train.txt` and `test.txt` files under each dataset folder indicates the loaders are driven by explicit split lists rather than only by folder structure.
  - Files such as `dataset.py`, `dataset_DCL.py`, `our_dataset.py`, and `LoadModel.py` suggest this package includes custom data abstractions and model-loading support tailored to those datasets.

- Top-level `datasets/train.py` and `datasets/eval.py`
  - These appear to be reusable dataset training/evaluation helpers, likely used by the main attack pipeline and/or for auxiliary classifier training.

Data flow through this layer:
- Raw images and split metadata are read from the dataset root.
- Dataset-specific loaders produce tensors and labels.
- Transform pipelines preprocess samples before they are fed into the generator/surrogate training loop.

3. Generator subsystem
- The `generator/` directory contains the core attack model family.
- Implementations include:
  - `resnet.py`
  - `resnet_gap.py`
  - `resnet_nat.py`
- These files suggest multiple generator variants based on ResNet-like backbones, probably differing in pooling strategy or normalization/architecture details.
- In the architecture of SCGA, the generator is the component that produces adversarial perturbations in a single forward pass at test time, which is the key efficiency advantage over iterative attacks.

Functional boundary:
- The generator is the “attack producer.”
- It takes preprocessed input images and emits perturbed outputs or perturbation tensors.
- It is the main object being optimized during training.

4. Surrogate model subsystem
- The `surrogate/` directory contains the victim-side proxy classifiers used during training:
  - `Dense169.py`
  - `Res152.py`
  - `VGG16.py`
  - `VGG19.py`
- These are the surrogate networks against which the generator is optimized.
- They provide the loss signal that guides adversarial example generation when the true black-box target is unavailable.

Architectural role:
- Surrogates form the “black-box approximation” boundary.
- Training computes gradients or losses through these local substitute models, while deployment assumes transfer to an unseen target model.

5. SCGA-specific semantic-consistency mechanism
The README describes SCGA as an add-on that enforces semantic consistency by aligning early generator intermediate features to an EMA teacher.

Architecturally, this implies an internal training branch:
- The generator has intermediate feature activations that are monitored during training.
- An EMA teacher provides a stabilized reference representation.
- The training objective combines standard surrogate-driven attack loss with a semantic-alignment term.
- This mechanism affects only training; the README emphasizes no inference-time overhead.

Even though there is no dedicated top-level “teacher” module in the file tree, the method’s logic is embedded in the generator/training stack.

6. Shared preprocessing, transforms, and utilities
- Top-level `transforms/`
  - Contains generic transform and functional utilities used across datasets and training flows.
- `datasets/DCL_finegrained/transforms.py`
  - Dataset-specific transform logic for the fine-grained branch.
- `utee/`
  - Utility layer for the experiment framework:
    - `Normalize.py` for normalization
    - `logger.py` for experiment logging
    - `metric.py` for metrics
    - `misc.py` for helper functions
    - `parser.py` for CLI argument definitions
    - `selector.py` for choosing models/components by name or config
  - This layer acts as the shared infrastructure glue between the entrypoint, datasets, generator, and surrogate models.

Important evaluation and reporting behavior

The README mentions several evaluation metrics:
- ASR
- FR
- Accuracy
- ACR

That implies a dedicated evaluation path that computes attack outcomes from model predictions. In architectural terms:
- The generator output is evaluated against surrogate or target predictions.
- Metrics are computed to distinguish intended misclassification from accidental correction, which is important because ACR is intended to fix a blind spot in standard attack metrics.

Repository structure as a diagram-friendly view

- Top-level experiment driver
  - `train_BIA_ours.py`
  - configured by `utee/parser.py`

- Data layer
  - `datasets/paths.py`
  - `datasets/imagenet/`
  - `datasets/DCL_finegrained/`
  - top-level dataset helpers in `datasets/train.py` and `datasets/eval.py`

- Model layer
  - attack generator implementations in `generator/`
  - surrogate classifiers in `surrogate/`

- Shared infrastructure
  - `transforms/`
  - `utee/`

- Documentation and experiment metadata
  - `docs/`
  - `environment.yaml`
  - README dataset instructions and installation guidance

Overall architecture summary

This repository is a modular adversarial-attack research pipeline. The central flow is:
- configuration and path setup
- dataset loading and preprocessing
- generator forward pass
- surrogate model loss computation
- SCGA semantic-consistency regularization during training
- metric computation and evaluation for black-box transferability

The main architectural separation is between:
- the attack generator,
- the surrogate classifiers used for training,
- the dataset-specific loaders and transforms,
- and the shared experiment utilities that bind everything together.

Main entry points: [`train_BIA_ours.py`](https://github.com/andyj1/scga/blob/HEAD/train_BIA_ours.py) (Train script), [`surrogate`](https://github.com/andyj1/scga/tree/HEAD/surrogate) (Surrogates), [`generator`](https://github.com/andyj1/scga/tree/HEAD/generator) (Generator), [`datasets/DCL_finegrained`](https://github.com/andyj1/scga/tree/HEAD/datasets/DCL_finegrained) (Fine-grained stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Training"
  train["Train script<br/>entrypoint<br/>[train_BIA_ours.py]"]
end

subgraph "Data"
  paths["Data root<br/>filesystem boundary<br/>[paths.py]"]
  ds_train["Dataset train<br/>helper<br/>[train.py]"]
  ds_eval["Dataset eval<br/>helper<br/>[eval.py]"]
  imagenet["ImageNet stack<br/>dataset package"]
  finegrained["Fine-grained stack<br/>dataset package"]
  ft_dataset["FG datasets<br/>data loaders<br/>[dataset.py]"]
  ft_transforms["FG transforms<br/>preprocessing<br/>[transforms.py]"]
  ft_model["FG model<br/>dataset model<br/>[model.py]"]
end

subgraph "Models"
  gen["Generator<br/>attack model"]
  gen_resnet["Gen ResNet<br/>generator variant<br/>[resnet.py]"]
  gen_gap["Gen GAP<br/>generator variant<br/>[resnet_gap.py]"]
  gen_nat["Gen NAT<br/>generator variant<br/>[resnet_nat.py]"]
  surrogate["Surrogates<br/>proxy classifiers"]
  s_dense["Dense169<br/>surrogate model<br/>[Dense169.py]"]
  s_res152["Res152<br/>surrogate model<br/>[Res152.py]"]
  s_vgg16["VGG16<br/>surrogate model<br/>[VGG16.py]"]
  s_vgg19["VGG19<br/>surrogate model<br/>[VGG19.py]"]
end

subgraph "Utilities"
  parser["CLI parser<br/>config<br/>[parser.py]"]
  normalize["Normalize<br/>preprocess utility<br/>[Normalize.py]"]
  selector["Selector<br/>component factory<br/>[selector.py]"]
  logger["Logger<br/>logging<br/>[logger.py]"]
  metric["Metrics<br/>evaluation<br/>[metric.py]"]
  shared_tf["Transforms<br/>preprocessing"]
end

train -->|"reads options"| parser
train -->|"resolves data"| paths
train -->|"loads data"| ds_train
train -->|"evaluates"| ds_eval
train -->|"builds generator"| gen
train -->|"builds surrogates"| surrogate
train -->|"preprocesses"| normalize
train -->|"transforms"| shared_tf
train -->|"logs"| logger
train -->|"reports"| metric
train -->|"selects components"| selector
gen -->|"implements"| gen_resnet
gen -->|"implements"| gen_gap
gen -->|"implements"| gen_nat
surrogate -->|"implements"| s_dense
surrogate -->|"implements"| s_res152
surrogate -->|"implements"| s_vgg16
surrogate -->|"implements"| s_vgg19
imagenet -->|"uses"| shared_tf
finegrained -->|"contains"| ft_dataset
finegrained -->|"contains"| ft_transforms
finegrained -->|"contains"| ft_model
ds_train -->|"supports"| imagenet
ds_train -->|"supports"| finegrained
ds_eval -->|"computes"| metric
parser -->|"drives"| selector
normalize -->|"pairs with"| shared_tf

click train "https://github.com/andyj1/scga/blob/master/train_BIA_ours.py"
click parser "https://github.com/andyj1/scga/blob/master/utee/parser.py"
click paths "https://github.com/andyj1/scga/blob/master/datasets/paths.py"
click ds_train "https://github.com/andyj1/scga/blob/master/datasets/train.py"
click ds_eval "https://github.com/andyj1/scga/blob/master/datasets/eval.py"
click imagenet "https://github.com/andyj1/scga/tree/master/datasets/imagenet"
click finegrained "https://github.com/andyj1/scga/tree/master/datasets/DCL_finegrained"
click ft_dataset "https://github.com/andyj1/scga/blob/master/datasets/DCL_finegrained/dataset.py"
click ft_transforms "https://github.com/andyj1/scga/blob/master/datasets/DCL_finegrained/transforms.py"
click ft_model "https://github.com/andyj1/scga/blob/master/datasets/DCL_finegrained/model.py"
click gen "https://github.com/andyj1/scga/tree/master/generator"
click gen_resnet "https://github.com/andyj1/scga/blob/master/generator/resnet.py"
click gen_gap "https://github.com/andyj1/scga/blob/master/generator/resnet_gap.py"
click gen_nat "https://github.com/andyj1/scga/blob/master/generator/resnet_nat.py"
click surrogate "https://github.com/andyj1/scga/tree/master/surrogate"
click s_dense "https://github.com/andyj1/scga/blob/master/surrogate/Dense169.py"
click s_res152 "https://github.com/andyj1/scga/blob/master/surrogate/Res152.py"
click s_vgg16 "https://github.com/andyj1/scga/blob/master/surrogate/VGG16.py"
click s_vgg19 "https://github.com/andyj1/scga/blob/master/surrogate/VGG19.py"
click normalize "https://github.com/andyj1/scga/blob/master/utee/Normalize.py"
click selector "https://github.com/andyj1/scga/blob/master/utee/selector.py"
click logger "https://github.com/andyj1/scga/blob/master/utee/logger.py"
click metric "https://github.com/andyj1/scga/blob/master/utee/metric.py"
click shared_tf "https://github.com/andyj1/scga/tree/master/transforms"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class train toneBlue
class paths,ds_train,ds_eval,imagenet,finegrained,ft_dataset,ft_transforms,ft_model toneAmber
class gen,gen_resnet,gen_gap,gen_nat,surrogate,s_dense,s_res152,s_vgg16,s_vgg19 toneMint
class parser,normalize,selector,logger,metric,shared_tf toneRose
```

## Components

### Training

Top-level experiment orchestration

- [Train script](https://github.com/andyj1/scga/blob/HEAD/train_BIA_ours.py): entrypoint · Main experiment driver for training and evaluation · `train_BIA_ours.py`

### Data

Dataset roots, loaders, and preprocessing

- [Data root](https://github.com/andyj1/scga/blob/HEAD/datasets/paths.py): filesystem boundary · Defines the dataset root directory used by loaders · `datasets/paths.py`
- [Dataset train](https://github.com/andyj1/scga/blob/HEAD/datasets/train.py): helper · Reusable training helper for dataset flows · `datasets/train.py`
- [Dataset eval](https://github.com/andyj1/scga/blob/HEAD/datasets/eval.py): helper · Reusable evaluation helper for dataset flows · `datasets/eval.py`
- [ImageNet stack](https://github.com/andyj1/scga/tree/HEAD/datasets/imagenet): dataset package · ImageNet loaders, metadata, and model wrappers · `datasets/imagenet`
- [Fine-grained stack](https://github.com/andyj1/scga/tree/HEAD/datasets/DCL_finegrained): dataset package · AIR, CUB, and Stanford Cars dataset submodule · `datasets/DCL_finegrained`
- [FG datasets](https://github.com/andyj1/scga/blob/HEAD/datasets/DCL_finegrained/dataset.py): data loaders · Custom dataset abstractions and split-driven loaders · `datasets/DCL_finegrained/dataset.py`
- [FG transforms](https://github.com/andyj1/scga/blob/HEAD/datasets/DCL_finegrained/transforms.py): preprocessing · Dataset-specific transforms for the fine-grained branch · `datasets/DCL_finegrained/transforms.py`
- [FG model](https://github.com/andyj1/scga/blob/HEAD/datasets/DCL_finegrained/model.py): dataset model · Dataset-side model definitions and loading support · `datasets/DCL_finegrained/model.py`

### Models

Attack generator and surrogate classifiers

- [Generator](https://github.com/andyj1/scga/tree/HEAD/generator): attack model · Produces adversarial perturbations for SCGA training and transfer · `generator`
- [Gen ResNet](https://github.com/andyj1/scga/blob/HEAD/generator/resnet.py): generator variant · ResNet-based generator backbone · `generator/resnet.py`
- [Gen GAP](https://github.com/andyj1/scga/blob/HEAD/generator/resnet_gap.py): generator variant · Generator variant with GAP-based design · `generator/resnet_gap.py`
- [Gen NAT](https://github.com/andyj1/scga/blob/HEAD/generator/resnet_nat.py): generator variant · Generator variant with natural/normalization-specific design · `generator/resnet_nat.py`
- [Surrogates](https://github.com/andyj1/scga/tree/HEAD/surrogate): proxy classifiers · Local substitute models used to optimize black-box transfer · `surrogate`
- [Dense169](https://github.com/andyj1/scga/blob/HEAD/surrogate/Dense169.py): surrogate model · DenseNet-style surrogate classifier · `surrogate/Dense169.py`
- [Res152](https://github.com/andyj1/scga/blob/HEAD/surrogate/Res152.py): surrogate model · ResNet-152 surrogate classifier · `surrogate/Res152.py`
- [VGG16](https://github.com/andyj1/scga/blob/HEAD/surrogate/VGG16.py): surrogate model · VGG-16 surrogate classifier · `surrogate/VGG16.py`
- [VGG19](https://github.com/andyj1/scga/blob/HEAD/surrogate/VGG19.py): surrogate model · VGG-19 surrogate classifier · `surrogate/VGG19.py`

### Utilities

Shared experiment infrastructure

- [CLI parser](https://github.com/andyj1/scga/blob/HEAD/utee/parser.py): config · Central argument and option definitions · `utee/parser.py`
- [Normalize](https://github.com/andyj1/scga/blob/HEAD/utee/Normalize.py): preprocess utility · Input normalization helper · `utee/Normalize.py`
- [Selector](https://github.com/andyj1/scga/blob/HEAD/utee/selector.py): component factory · Chooses models and components by name or config · `utee/selector.py`
- [Logger](https://github.com/andyj1/scga/blob/HEAD/utee/logger.py): logging · Experiment logging and reporting · `utee/logger.py`
- [Metrics](https://github.com/andyj1/scga/blob/HEAD/utee/metric.py): evaluation · Metric computation for attack and transfer outcomes · `utee/metric.py`
- [Transforms](https://github.com/andyj1/scga/tree/HEAD/transforms): preprocessing · Repository-wide transform and functional utilities · `transforms`

## Connections

- Train script → CLI parser: reads options · Training is configured through the shared CLI parser
- Train script → Data root: resolves data · Entrypoint uses the dataset root boundary
- Train script → Dataset train: loads data · Training flow uses reusable dataset helpers
- Train script → Dataset eval: evaluates · Evaluation flow computes attack outcomes
- Train script → Generator: builds generator · Main script constructs the attack model
- Train script → Surrogates: builds surrogates · Main script constructs local proxy classifiers
- Train script → Normalize: preprocesses · Input normalization is applied before model execution
- Train script → Transforms: transforms · Shared transforms support training data pipelines
- Train script → Logger: logs · Training and evaluation results are logged
- Train script → Metrics: reports · Attack metrics are computed during evaluation
- Train script → Selector: selects components · Component selection is centralized
- Generator → Gen ResNet: implements · One generator family variant
- Generator → Gen GAP: implements · One generator family variant
- Generator → Gen NAT: implements · One generator family variant
- Surrogates → Dense169: implements · One surrogate architecture
- Surrogates → Res152: implements · One surrogate architecture
- Surrogates → VGG16: implements · One surrogate architecture
- Surrogates → VGG19: implements · One surrogate architecture
- ImageNet stack → Transforms: uses · ImageNet data pipeline relies on shared transforms
- Fine-grained stack → FG datasets: contains · Fine-grained package provides custom loaders
- Fine-grained stack → FG transforms: contains · Fine-grained package provides preprocessing
- Fine-grained stack → FG model: contains · Fine-grained package provides dataset-side model support
- Dataset train → ImageNet stack: supports · Reusable training helpers operate over ImageNet-style datasets
- Dataset train → Fine-grained stack: supports · Reusable training helpers also support the fine-grained branch
- Dataset eval → Metrics: computes · Evaluation helper feeds attack metrics
- CLI parser → Selector: drives · CLI options determine selected components
- Normalize → Transforms: pairs with · Normalization complements the shared transform layer
