# petrsokerin/hidden_adversarial_attacks architecture

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

- Interactive diagram: https://gitdiagram.com/petrsokerin/hidden_adversarial_attacks
- Repository: https://github.com/petrsokerin/hidden_adversarial_attacks

## Overview

#### Purpose and execution entry points
This repository benchmarks concealed adversarial attacks against time-series classifiers. Attacks are optimized both to cause misclassification and to evade a trained perturbation discriminator. The three experiment entry points are `train_classifier.py`, `train_discriminator.py`, and `attack_run.py`; batch orchestration is available in `run_full_experiments.sh`.

#### Configuration-driven experiment assembly
Hydra-style configuration selects dataset, classifier/attack target, discriminator, and attack procedure. Example composition roots are `config_examples/train_classifier_config.yaml`, `config_examples/train_disc_config.yaml`, and `config_examples/attack_run_config.yaml`; reusable selections live under `config_examples/model/` and `config_examples/attack/`. Runtime config interpretation is centralized in `src/config/config.py`.

#### Data ingestion boundary
The data layer loads time-series classification datasets, principally externally downloaded UCR data expected outside the tracked source tree. It converts dataset records into the tensors and splits consumed by training and attack stages. The architectural boundary is `src/data/data.py`, isolating dataset-format handling from models and experiment scripts.

#### Classifier and discriminator model layer
The same model family layer supplies both target classifiers and discriminators: the discriminator learns to distinguish clean from adversarial series, while the classifier supplies attack gradients and success labels. Shared model contracts are in `src/models/base_model.py` and `src/models/utils.py`; implementations span recurrent, convolutional, transformer, state-space, and representation models, including `src/models/LSTM.py`, `src/models/ResidualCNN.py`, and `src/models/S4.py`. TS2Vec includes a vendored internal implementation at `src/models/TS2Vec_src/ts2vec.py`.

#### Training pipelines and model artifacts
Training scripts construct configured models and datasets, then delegate fitting/evaluation logic to `src/training/train.py`. `train_classifier.py` produces target-classifier checkpoints; `train_discriminator.py` trains detection models against adversarial perturbations. Checkpoints are a material filesystem contract: later attack and discriminator-check runs depend on the corresponding saved model weights.

#### Attack generation and concealment optimization
`attack_run.py` drives adversarial sample generation against a trained classifier, optionally using one or more discriminator models for concealment scoring. Attack abstractions and common scheduling are in `src/attacks/base_attacks.py` and `src/attacks/attack_scheduler.py`; concrete gradient attacks include `src/attacks/fgsm.py`, `src/attacks/pgd.py`, and `src/attacks/kll2.py`. The central distinction from vanilla attacks is regularization in `src/attacks/regularizers.py`, which incorporates discriminator-oriented penalties into perturbation optimization.

#### Evaluation and result reporting
Generated attacks are evaluated for classifier effectiveness and detectability/concealability, then persisted as experiment results for comparison. Metric/estimation logic is separated into `src/estimation/estimators.py` and `src/estimation/utils.py`, while attack procedure coordination resides in `src/attacks/procedures.py`. The repository expects writable `checkpoints` and `results` directories.

#### Runtime and infrastructure
The project is Python-based with dependencies declared in `requirements.txt` and `pyproject.toml`. Docker is optional and defined by `docker_scripts/Dockerfile`, `docker_scripts/build`, and `docker_scripts/launch_container`. External dependencies include the UCR time-series archive and, potentially, experiment-tracking/metric workflows represented by `notebooks/clearml_metrics.ipynb`.

Main entry points: [`src/attacks/procedures.py`](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/attacks/procedures.py) (Attack procedures), [`src/training/train.py`](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/training/train.py) (Training pipeline), [`src/data/data.py`](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/data/data.py) (Dataset loader & splits), [`src/models/ResidualCNN.py`](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/models/ResidualCNN.py) (Classifier & discriminator models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Experiment Configuration"]
  node_config_roots["Hydra config roots<br/>configuration"]
  node_config_runtime["Config interpreter<br/>configuration<br/>[config.py]"]
end

subgraph group_data["Data Boundary"]
  node_ucr_data[("UCR archive<br/>external dataset")]
  node_data_loader["Dataset loader &amp; splits<br/>data layer<br/>[data.py]"]
end

subgraph group_models["Model Layer"]
  node_model_contracts["Model contracts<br/>model interface<br/>[base_model.py]"]
  node_model_families["Classifier &amp; discriminator models<br/>model implementations<br/>[ResidualCNN.py]"]
  node_ts2vec["Vendored TS2Vec<br/>representation model<br/>[ts2vec.py]"]
end

subgraph group_attack["Attack &amp; Evaluation"]
  node_attack_entry["Attack run<br/>entry point<br/>[attack_run.py]"]
  node_attack_scheduler["Attack scheduler<br/>attack orchestration"]
  node_gradient_attacks["Gradient attacks<br/>attack implementations<br/>[pgd.py]"]
  node_concealment["Concealment regularizers<br/>optimization layer<br/>[regularizers.py]"]
  node_attack_procedures["Attack procedures<br/>procedure coordinator<br/>[procedures.py]"]
  node_estimators["Effectiveness &amp; detectability metrics<br/>evaluation layer<br/>[estimators.py]"]
  node_results[("Experiment results<br/>filesystem artifact")]
end

subgraph group_runs["Experiment Runtimes"]
  node_training["Training pipeline<br/>training service<br/>[train.py]"]
  node_classifier_entry["Classifier training<br/>entry point"]
  node_discriminator_entry["Discriminator training<br/>entry point"]
  node_checkpoints[("Model checkpoints<br/>filesystem artifact")]
  node_batch_runner["Full experiment runner<br/>batch entry point"]
end

node_config_roots -->|"composes"| node_config_runtime
node_config_runtime -->|"selects dataset"| node_data_loader
node_config_runtime -->|"selects models"| node_model_families
node_ucr_data -->|"loads"| node_data_loader
node_model_contracts -->|"defines interface"| node_model_families
node_ts2vec -->|"included in"| node_model_families
node_classifier_entry -->|"delegates fitting"| node_training
node_discriminator_entry -->|"delegates fitting"| node_training
node_data_loader -->|"provides tensors and splits"| node_training
node_model_families -->|"provides configured model"| node_training
node_training -->|"saves weights"| node_checkpoints
node_attack_entry -->|"runs"| node_attack_procedures
node_data_loader -->|"provides evaluation data"| node_attack_procedures
node_checkpoints -->|"loads classifier and detectors"| node_attack_procedures
node_attack_procedures -->|"coordinates"| node_attack_scheduler
node_attack_scheduler -->|"schedules"| node_gradient_attacks
node_concealment -->|"regularizes optimization"| node_gradient_attacks
node_attack_procedures -->|"evaluates generated attacks"| node_estimators
node_estimators -->|"persists metrics"| node_results
node_batch_runner -->|"orchestrates"| node_classifier_entry
node_batch_runner -->|"orchestrates"| node_discriminator_entry
node_batch_runner -->|"orchestrates"| node_attack_entry

click node_config_roots "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/config_examples/attack_run_config.yaml"
click node_config_runtime "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/config/config.py"
click node_data_loader "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/data/data.py"
click node_model_contracts "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/models/base_model.py"
click node_model_families "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/models/ResidualCNN.py"
click node_ts2vec "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/models/TS2Vec_src/ts2vec.py"
click node_training "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/training/train.py"
click node_classifier_entry "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/train_classifier.py"
click node_discriminator_entry "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/train_discriminator.py"
click node_attack_entry "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/attack_run.py"
click node_attack_scheduler "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/attacks/attack_scheduler.py"
click node_gradient_attacks "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/attacks/pgd.py"
click node_concealment "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/attacks/regularizers.py"
click node_attack_procedures "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/attacks/procedures.py"
click node_estimators "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/estimation/estimators.py"
click node_batch_runner "https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/run_full_experiments.sh"

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_config_roots,node_config_runtime toneBlue
class node_ucr_data,node_data_loader toneAmber
class node_model_contracts,node_model_families,node_ts2vec toneMint
class node_attack_entry,node_attack_scheduler,node_gradient_attacks,node_concealment,node_attack_procedures,node_estimators,node_results toneRose
class node_training,node_classifier_entry,node_discriminator_entry,node_checkpoints,node_batch_runner toneIndigo
```

## Components

### Experiment Configuration

- [Hydra config roots](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/config_examples/attack_run_config.yaml): configuration · Selects dataset, models, and attack procedure. · `config_examples/attack_run_config.yaml`
- [Config interpreter](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/config/config.py): configuration · `src/config/config.py`

### Data Boundary

- **UCR archive**: external dataset · Downloaded time-series datasets outside the repository.
- [Dataset loader & splits](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/data/data.py): data layer · `src/data/data.py`

### Model Layer

- [Model contracts](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/models/base_model.py): model interface · `src/models/base_model.py`
- [Classifier & discriminator models](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/models/ResidualCNN.py): model implementations · Shared recurrent, convolutional, transformer, state-space, and representation model family. · `src/models/ResidualCNN.py`
- [Vendored TS2Vec](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/models/TS2Vec_src/ts2vec.py): representation model · `src/models/TS2Vec_src/ts2vec.py`

### Attack & Evaluation

- [Attack run](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/attack_run.py): entry point · `attack_run.py`
- [Attack scheduler](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/attacks/attack_scheduler.py): attack orchestration · `src/attacks/attack_scheduler.py`
- [Gradient attacks](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/attacks/pgd.py): attack implementations · FGSM, PGD, and KLL2 perturbation generators. · `src/attacks/pgd.py`
- [Concealment regularizers](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/attacks/regularizers.py): optimization layer · Adds discriminator-oriented penalties to perturbation optimization. · `src/attacks/regularizers.py`
- [Attack procedures](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/attacks/procedures.py): procedure coordinator · `src/attacks/procedures.py`
- [Effectiveness & detectability metrics](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/estimation/estimators.py): evaluation layer · `src/estimation/estimators.py`
- **Experiment results**: filesystem artifact · Persisted metrics and attack comparisons.

### Experiment Runtimes

- [Training pipeline](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/src/training/train.py): training service · Fits and evaluates configured classifier or discriminator models. · `src/training/train.py`
- [Classifier training](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/train_classifier.py): entry point · `train_classifier.py`
- [Discriminator training](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/train_discriminator.py): entry point · Trains detectors on adversarial perturbations. · `train_discriminator.py`
- **Model checkpoints**: filesystem artifact · Saved weights consumed by later attack and detection runs.
- [Full experiment runner](https://github.com/petrsokerin/hidden_adversarial_attacks/blob/main/run_full_experiments.sh): batch entry point · `run_full_experiments.sh`

## Connections

- Hydra config roots → Config interpreter: composes
- Config interpreter → Dataset loader & splits: selects dataset
- Config interpreter → Classifier & discriminator models: selects models
- UCR archive → Dataset loader & splits: loads
- Model contracts → Classifier & discriminator models: defines interface
- Vendored TS2Vec → Classifier & discriminator models: included in
- Classifier training → Training pipeline: delegates fitting
- Discriminator training → Training pipeline: delegates fitting
- Dataset loader & splits → Training pipeline: provides tensors and splits
- Classifier & discriminator models → Training pipeline: provides configured model
- Training pipeline → Model checkpoints: saves weights
- Attack run → Attack procedures: runs
- Dataset loader & splits → Attack procedures: provides evaluation data
- Model checkpoints → Attack procedures: loads classifier and detectors
- Attack procedures → Attack scheduler: coordinates
- Attack scheduler → Gradient attacks: schedules
- Concealment regularizers → Gradient attacks: regularizes optimization
- Attack procedures → Effectiveness & detectability metrics: evaluates generated attacks
- Effectiveness & detectability metrics → Experiment results: persists metrics
- Full experiment runner → Classifier training: orchestrates
- Full experiment runner → Discriminator training: orchestrates
- Full experiment runner → Attack run: orchestrates