# cure-lab/deep-active-learning architecture

> Architecture diagram of the GitHub repository cure-lab/deep-active-learning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cure-lab/deep-active-learning
- Repository: https://github.com/cure-lab/deep-active-learning

## Overview

1. **What this repo is**
   This is a PyTorch-based **deep active learning experiment framework**. It is not a single model; it is an orchestration layer that repeatedly trains a classifier, scores an unlabeled pool, acquires new samples, and retrains over multiple rounds.

2. **Top-level control flow**
   `main.py` is the experiment entrypoint, and `run.sh` is the convenience wrapper. The main loop is likely:
   - load dataset and create initial labeled/unlabeled splits
   - instantiate a backbone model
   - train on the labeled subset
   - evaluate on a held-out test set
   - run a query strategy to select samples from the unlabeled pool
   - move queried samples into the labeled pool
   - repeat for several acquisition rounds
   Results are saved under `./save`.

3. **Dataset boundary**
   `dataset.py` is the data boundary for the whole system. It likely handles dataset loading, train/test partitioning, and active-learning pool management for common image benchmarks such as CIFAR-10, as shown in the README example. This is where the labeled set, unlabeled set, and test set are defined and tracked across rounds.

4. **Model zoo / training backends**
   The `models/` directory contains the supervised learners used inside the active learning loop:
   - standard CNN backbones: `resnet.py`, `resnet64.py`, `vgg.py`, `mobilenet.py`, `wideresnet.py`, `shufflenet.py`
   - lightweight or auxiliary heads: `linear.py`, `lossnet.py`
   - graph/network variants: `gcn.py`
   - method-specific wrappers: `wa_model.py`
   These modules are the main “training target” consumed by strategies; many query methods depend on the model’s logits, embeddings, gradients, or uncertainty estimates.

5. **Strategy subsystem**
   The `query_strategies/` package is the core architectural differentiator. `strategy.py` appears to define the common strategy interface/base class, while `util.py` and `cpu_dist.py` provide shared helpers and distance computations. Each strategy module implements one acquisition policy over the unlabeled pool.

6. **Uncertainty-based acquisition**
   Several strategies select points by model uncertainty, using outputs from the current trained classifier:
   - `least_confidence.py`, `margin_sampling.py`, `entropy_sampling.py`
   - dropout variants: `*_dropout.py`
   - ensemble/Bayesian methods: `bayesian_active_learning_disagreement_dropout.py`, `batch_BALD.py`
   - simple baseline/random: `baseline_sampling.py`, `random_sampling.py`
   These methods typically require only predictions from the trained model, so they are the least invasive path through the system.

7. **Diversity / embedding-based acquisition**
   Another major branch uses the learned feature space or sample geometry rather than just uncertainty:
   - `core_set.py`, `kcenter_greedy.py`, `kmeans_sampling.py`
   - `badge_sampling.py`
   - `batch_active_learning_at_scale.py`
   - `selection_via_proxy.py`
   These strategies depend on embeddings/gradients extracted from the model and are used to encourage coverage of the unlabeled space, not just uncertainty.

8. **Adversarial / generative strategies**
   The repository also implements strategies that rely on adversarial objectives or generators:
   - `adversarial_bim.py`, `adversarial_deepfool.py`
   - `vaal.py`, `wasserstein_adversarial.py`
   - `aug_uda.py`, `augmentations.py`
   - `mcadl.py`
   These introduce extra components beyond the classifier, such as discriminator-like models or augmentation pipelines, so the architecture expands from “train classifier + score pool” into multi-network training for selection.

9. **Learning-to-rank / learned acquisition**
   Some strategies explicitly learn a query function:
   - `active_learning_by_learning.py`
   - `learning_loss_for_al.py` with `models/lossnet.py`
   - `lal.py`
   - `batch_active_learning_at_scale.py`
   These methods add a second-stage predictor that estimates which unlabeled points will be most useful, based on features from the current model and/or metadata about training progress.

10. **Graph-based active learning**
   `models/gcn.py` and strategies like `coreGCN.py`, `uncertainGCN.py` show a graph-centric branch. These methods build a graph over samples/features and apply GCN-style reasoning to choose queries. Architecturally, this is a distinct path because selection depends on neighborhood structure, not just pointwise classification output.

11. **Semi-supervised + active learning hybrids**
   The `semi_*` and `ssl_*` modules implement methods that mix query acquisition with unlabeled-loss training:
   - `semi_strategy.py`, `semi_fixmatch.py`, `semi_flexmatch.py`, `semi_pseudolabel.py`
   - `ssl_consistency.py`, `ssl_least_confidence.py`, `ssl_rand.py`, `ssl_diff2augdirect.py`, `ssl_diff2augkmeans.py`
   These strategies consume both labeled and unlabeled data during training, so the unlabeled pool is not only for selection; it also contributes to representation learning between acquisition rounds.

12. **Experiment outputs and reproducibility**
   The repo is set up as an offline research benchmark rather than a service. `requirements.txt` pins the Python/PyTorch/scikit-learn stack, and the README notes Python 3.7 and PyTorch 1.4.0. The main observable output is experiment results saved in `./save`, likely including metrics per round, selected indices, and model checkpoints.

13. **Important architectural boundary to diagram**
   The key boundary is between:
   - **shared experiment orchestration** (`main.py`, `dataset.py`, `utils.py`)
   - **backbone models** (`models/`)
   - **acquisition policies** (`query_strategies/`)
   Each strategy plugs into the same pool-based active-learning loop but may require different model outputs or auxiliary networks. That plug-in architecture is the central design of the repository.

Main entry points: [`query_strategies/strategy.py`](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/strategy.py) (Strategy base), [`main.py`](https://github.com/cure-lab/deep-active-learning/blob/main/main.py) (Main loop), [`query_strategies/semi_strategy.py`](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/semi_strategy.py) (Semi-supervised base), [`query_strategies/learning_loss_for_al.py`](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/learning_loss_for_al.py) (Learn loss)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_main_py["Main loop<br/>experiment driver<br/>[main.py]"]
  node_run_sh["Run script<br/>wrapper script<br/>[run.sh]"]
  node_dataset_py[("Dataset boundary<br/>data management<br/>[dataset.py]")]
  node_utils_py["Shared utils<br/>helpers<br/>[utils.py]"]
end

subgraph group_models["Models"]
  node_resnet_py["ResNet<br/>backbone<br/>[resnet.py]"]
  node_wideresnet_py["WideResNet<br/>backbone<br/>[wideresnet.py]"]
  node_gcn_py["GCN model<br/>graph model<br/>[gcn.py]"]
  node_lossnet_py["LossNet<br/>aux head<br/>[lossnet.py]"]
  node_wa_model_py["WA model<br/>wrapper<br/>[wa_model.py]"]
  node_linear_py["Linear head<br/>classifier head<br/>[linear.py]"]
end

subgraph group_strategies["Query Strategies"]
  node_strategy_py["Strategy base<br/>acquisition interface<br/>[strategy.py]"]
  node_util_qs_py["Strategy utils<br/>strategy helpers<br/>[util.py]"]
  node_random_sampling_py(("Random<br/>baseline acquisition<br/>[random_sampling.py]"))
  node_entropy_sampling_py(("Entropy<br/>uncertainty acquisition"))
  node_core_set_py{{"Core-set<br/>diversity acquisition<br/>[core_set.py]"}}
  node_badge_sampling_py{{"BADGE<br/>gradient acquisition<br/>[badge_sampling.py]"}}
  node_vaal_py{{"VAAL<br/>adversarial acquisition<br/>[vaal.py]"}}
  node_semi_strategy_py["Semi-supervised base<br/>hybrid strategy<br/>[semi_strategy.py]"]
  node_ssl_consistency_py{{"SSL consistency<br/>hybrid acquisition<br/>[ssl_consistency.py]"}}
  node_fixmatch_py{{"FixMatch<br/>hybrid acquisition<br/>[semi_fixmatch.py]"}}
  node_learn_loss_py{{"Learn loss<br/>learned acquisition"}}
  node_albl_py{{"ALBL<br/>learned acquisition"}}
  node_coregcn_py{{"CoreGCN<br/>graph acquisition<br/>[coreGCN.py]"}}
end

node_run_sh -->|"launches"| node_main_py
node_main_py -->|"loads"| node_dataset_py
node_main_py -->|"uses"| node_utils_py
node_main_py -->|"trains"| node_resnet_py
node_main_py -->|"trains"| node_wideresnet_py
node_main_py -->|"trains"| node_gcn_py
node_main_py -->|"attaches"| node_lossnet_py
node_main_py -->|"wraps"| node_wa_model_py
node_main_py -->|"selects via"| node_strategy_py
node_strategy_py -->|"depends on"| node_util_qs_py
node_strategy_py -->|"implements"| node_random_sampling_py
node_strategy_py -->|"implements"| node_entropy_sampling_py
node_strategy_py -->|"implements"| node_core_set_py
node_strategy_py -->|"implements"| node_badge_sampling_py
node_strategy_py -->|"implements"| node_vaal_py
node_strategy_py -->|"extends"| node_semi_strategy_py
node_semi_strategy_py -->|"specializes"| node_ssl_consistency_py
node_semi_strategy_py -->|"specializes"| node_fixmatch_py
node_strategy_py -->|"implements"| node_learn_loss_py
node_strategy_py -->|"implements"| node_albl_py
node_strategy_py -->|"implements"| node_coregcn_py
node_learn_loss_py -->|"uses"| node_lossnet_py
node_coregcn_py -->|"uses"| node_gcn_py

click node_main_py "https://github.com/cure-lab/deep-active-learning/blob/main/main.py"
click node_run_sh "https://github.com/cure-lab/deep-active-learning/blob/main/run.sh"
click node_dataset_py "https://github.com/cure-lab/deep-active-learning/blob/main/dataset.py"
click node_utils_py "https://github.com/cure-lab/deep-active-learning/blob/main/utils.py"
click node_resnet_py "https://github.com/cure-lab/deep-active-learning/blob/main/models/resnet.py"
click node_wideresnet_py "https://github.com/cure-lab/deep-active-learning/blob/main/models/wideresnet.py"
click node_gcn_py "https://github.com/cure-lab/deep-active-learning/blob/main/models/gcn.py"
click node_lossnet_py "https://github.com/cure-lab/deep-active-learning/blob/main/models/lossnet.py"
click node_wa_model_py "https://github.com/cure-lab/deep-active-learning/blob/main/models/wa_model.py"
click node_linear_py "https://github.com/cure-lab/deep-active-learning/blob/main/models/linear.py"
click node_strategy_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/strategy.py"
click node_util_qs_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/util.py"
click node_random_sampling_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/random_sampling.py"
click node_entropy_sampling_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/entropy_sampling.py"
click node_core_set_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/core_set.py"
click node_badge_sampling_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/badge_sampling.py"
click node_vaal_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/vaal.py"
click node_semi_strategy_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/semi_strategy.py"
click node_ssl_consistency_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/ssl_consistency.py"
click node_fixmatch_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/semi_fixmatch.py"
click node_learn_loss_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/learning_loss_for_al.py"
click node_albl_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/active_learning_by_learning.py"
click node_coregcn_py "https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/coreGCN.py"

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 node_main_py,node_run_sh,node_dataset_py,node_utils_py toneBlue
class node_resnet_py,node_wideresnet_py,node_gcn_py,node_lossnet_py,node_wa_model_py,node_linear_py toneAmber
class node_strategy_py,node_util_qs_py,node_random_sampling_py,node_entropy_sampling_py,node_core_set_py,node_badge_sampling_py,node_vaal_py,node_semi_strategy_py,node_ssl_consistency_py,node_fixmatch_py,node_learn_loss_py,node_albl_py,node_coregcn_py toneMint
```

## Components

### Orchestration

Entry point, dataset boundary, and shared experiment helpers.

- [Main loop](https://github.com/cure-lab/deep-active-learning/blob/main/main.py): experiment driver · Runs active-learning rounds: load data, train, evaluate, query, and update pools. · `main.py`
- [Run script](https://github.com/cure-lab/deep-active-learning/blob/main/run.sh): wrapper script · Convenience shell wrapper for launching experiments. · `run.sh`
- [Dataset boundary](https://github.com/cure-lab/deep-active-learning/blob/main/dataset.py): data management · Loads benchmarks and maintains labeled, unlabeled, and test splits. · `dataset.py`
- [Shared utils](https://github.com/cure-lab/deep-active-learning/blob/main/utils.py): helpers · Common experiment utilities used across training and querying. · `utils.py`

### Models

Backbone and auxiliary networks trained inside active-learning rounds.

- [ResNet](https://github.com/cure-lab/deep-active-learning/blob/main/models/resnet.py): backbone · Standard convolutional classifier backbone. · `models/resnet.py`
- [WideResNet](https://github.com/cure-lab/deep-active-learning/blob/main/models/wideresnet.py): backbone · Higher-capacity convolutional classifier backbone. · `models/wideresnet.py`
- [GCN model](https://github.com/cure-lab/deep-active-learning/blob/main/models/gcn.py): graph model · Graph-based learner used by graph-centric acquisition methods. · `models/gcn.py`
- [LossNet](https://github.com/cure-lab/deep-active-learning/blob/main/models/lossnet.py): aux head · Predicts learning loss for learned acquisition strategies. · `models/lossnet.py`
- [WA model](https://github.com/cure-lab/deep-active-learning/blob/main/models/wa_model.py): wrapper · Method-specific model wrapper used by some strategies. · `models/wa_model.py`
- [Linear head](https://github.com/cure-lab/deep-active-learning/blob/main/models/linear.py): classifier head · Lightweight prediction head used in simpler setups. · `models/linear.py`

### Query Strategies

Acquisition policies and semi-supervised variants over the unlabeled pool.

- [Strategy base](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/strategy.py): acquisition interface · Common interface implemented by all query policies. · `query_strategies/strategy.py`
- [Strategy utils](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/util.py): strategy helpers · Shared helpers for query strategies and scoring. · `query_strategies/util.py`
- [Random](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/random_sampling.py): baseline acquisition · Simple random baseline for pool selection. · `query_strategies/random_sampling.py`
- [Entropy](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/entropy_sampling.py): uncertainty acquisition · Selects points with high predictive entropy. · `query_strategies/entropy_sampling.py`
- [Core-set](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/core_set.py): diversity acquisition · Covers feature space by selecting representative points. · `query_strategies/core_set.py`
- [BADGE](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/badge_sampling.py): gradient acquisition · Uses gradient embeddings to balance uncertainty and diversity. · `query_strategies/badge_sampling.py`
- [VAAL](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/vaal.py): adversarial acquisition · Uses a generative/adversarial learner to query informative samples. · `query_strategies/vaal.py`
- [Semi-supervised base](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/semi_strategy.py): hybrid strategy · Base class for methods that train on labeled and unlabeled data. · `query_strategies/semi_strategy.py`
- [SSL consistency](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/ssl_consistency.py): hybrid acquisition · Combines consistency training with active selection. · `query_strategies/ssl_consistency.py`
- [FixMatch](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/semi_fixmatch.py): hybrid acquisition · Semi-supervised active-learning variant using FixMatch-style training. · `query_strategies/semi_fixmatch.py`
- [Learn loss](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/learning_loss_for_al.py): learned acquisition · Learns a query signal using LossNet-style loss prediction. · `query_strategies/learning_loss_for_al.py`
- [ALBL](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/active_learning_by_learning.py): learned acquisition · Active learning by learning a query policy from feedback. · `query_strategies/active_learning_by_learning.py`
- [CoreGCN](https://github.com/cure-lab/deep-active-learning/blob/main/query_strategies/coreGCN.py): graph acquisition · Graph-based selection using neighborhood structure and GCN reasoning. · `query_strategies/coreGCN.py`

## Connections

- Run script → Main loop: launches · Shell wrapper invokes the experiment driver.
- Main loop → Dataset boundary: loads · Main loop creates labeled/unlabeled/test splits.
- Main loop → Shared utils: uses · Shared helpers support training, evaluation, and bookkeeping.
- Main loop → ResNet: trains · One of the main classifier backbones used in rounds.
- Main loop → WideResNet: trains · Alternative backbone for supervised rounds.
- Main loop → GCN model: trains · Used by graph-centric acquisition methods.
- Main loop → LossNet: attaches · Auxiliary head for learning-loss strategies.
- Main loop → WA model: wraps · Method-specific wrapper for some strategies.
- Main loop → Strategy base: selects via · Experiment loop delegates pool selection to a strategy implementation.
- Strategy base → Strategy utils: depends on · Strategies share helper code and scoring utilities.
- Strategy base → Random: implements · Baseline acquisition policy.
- Strategy base → Entropy: implements · Uncertainty-based acquisition policy.
- Strategy base → Core-set: implements · Diversity-based acquisition policy.
- Strategy base → BADGE: implements · Gradient-embedding acquisition policy.
- Strategy base → VAAL: implements · Adversarial acquisition policy.
- Strategy base → Semi-supervised base: extends · Base for semi-supervised active-learning methods.
- Semi-supervised base → SSL consistency: specializes · Adds consistency-based unlabeled training.
- Semi-supervised base → FixMatch: specializes · Adds FixMatch-style semi-supervised training.
- Strategy base → Learn loss: implements · Learned acquisition based on loss prediction.
- Strategy base → ALBL: implements · Learned acquisition by policy learning.
- Strategy base → CoreGCN: implements · Graph-based acquisition policy.
- Learn loss → LossNet: uses · Depends on auxiliary loss prediction network.
- CoreGCN → GCN model: uses · Relies on graph neural network reasoning.