# nlab-mpg/cosda-hr architecture

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

- Interactive diagram: https://gitdiagram.com/nlab-mpg/cosda-hr
- Repository: https://github.com/nlab-mpg/cosda-hr

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is **research/experimental ML code** for **continual object recognition with continual open-set domain adaptation** (COSDA-HR). It’s not a “service architecture” project; the “system” is primarily a **training + evaluation pipeline** driven by a single entrypoint (`main.py`) that orchestrates:
- reading experiment config (`config.py`, `config.yaml`)
- loading COSDA-HR dataset + task splits (the `sequential_source/*` and `sequential_target/*` lists)
- building a model (`net.py`)
- training/adapting over sequential tasks (continual learning)
- evaluating results (`eval.py`, `eval/*` lists)
- utilities/helpers (`lib.py`)

##### Experiment Runner (main.py)
- Responsibilities: load config, set seeds/device, instantiate dataset/dataloaders, build model, train loop over tasks, call eval, save results.

##### Configuration Layer (config.yaml + config.py)
- Inputs: YAML file (and maybe CLI args)
- Outputs: structured config object consumed by main/data/model/eval

##### Data Pipeline (data.py)
- Inputs:
- COSDA-HR dataset files on disk
- task split lists: `sequential_source/*`, `sequential_target/*`
- eval lists: `eval/*`
- Outputs:
- train loaders per task (source/target)
- eval loaders

##### Model / Network (net.py)
- Inputs: batches from Data Pipeline
- Outputs: logits/embeddings; possibly domain outputs

##### Training Utilities (lib.py)
- Loss functions, metrics, pseudo-labeling, replay/buffer (if used), optimizer/scheduler helpers, checkpointing.

##### Evaluation (eval.py)
- Inputs: trained model checkpoints / in-memory model, eval loaders, evaluation protocol lists
- Outputs: metrics (accuracy, open-set metrics), logs/results files

##### Outputs / Artifacts
- Checkpoints (model weights)
- Logs (console / file)
- Result tables / metrics dumps

##### External dependencies (explicitly call out)
Even if not visible in the tree, it’s almost certainly:
- **Python runtime**
- **Deep learning framework** (very likely PyTorch)
- **GPU/CUDA** (optional but typical)

##### Continual / sequential task loop

**for t in tasks(0..9):**
- load task t source split
- load task t target split
- train/adapt model on task t
- evaluate (optional) on cumulative/all tasks

Visually, either:

##### Domain adaptation (source + target streams)
**two parallel input streams** into training:
- Source domain labeled data (supervised)
- Target domain unlabeled/weakly labeled (UDA)

##### Open-set handling
Because the paper is “open set domain adaptation”, the evaluation likely includes:
- known classes accuracy
- unknown detection / rejection performance
This as:
- “Known/Unknown decision” in eval, or
- “Open-set module” in model/loss (if that’s how it’s implemented).

**Goal:** show how code modules + artifacts interact.

**Goal:** show the temporal order in continual learning.
Participants: `main.py`, `data.py`, `net.py`, `lib.py`, `eval.py`, filesystem (dataset).
Sequence:

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Global / External Entities
  %% =========================
  User["Researcher / CLI User"]:::external
  RunSh["run.sh (Experiment Launcher)"]:::control
  Env["Execution Environment\n(Python + DL Framework e.g., PyTorch\n+ CUDA/GPU optional)"]:::env

  %% =========================
  %% Configuration Layer
  %% =========================
  subgraph "Configuration Layer"
    ConfigYaml["config.yaml\n(Experiment Parameters)"]:::configDoc
    ConfigPy["config.py\n(Config Parser / Merger)"]:::control
  end

  %% =========================
  %% Orchestration / Runtime
  %% =========================
  subgraph "Runtime Orchestration"
    Main["main.py\n(Experiment Runner / Controller)"]:::control

    subgraph "Continual Learning Task Loop (t = 0..9)"
      TaskSched["Task Scheduler\n(iterate tasks / boundaries)"]:::control
      TrainStep["Training / Adaptation Step\n(per task t)"]:::train
      SourceStream["Source Stream\n(labeled supervised)"]:::data
      TargetStream["Target Stream\n(target UDA stream\nunlabeled/weak)"]:::data
      Ckpt["Checkpoint + Logging\n(save state, seeds, summaries)"]:::artifact
    end
  end

  %% =========================
  %% Data Inputs & Pipeline
  %% =========================
  subgraph "Data Inputs (on disk)"
    Dataset["COSDA-HR Dataset\n(Images/Annotations on Disk)"]:::storage
    SrcLists["sequential_source/*.txt\n(10 task splits + all)"]:::doc
    TgtLists["sequential_target/*.txt\n(10 task splits + all)"]:::doc
    EvalProto["eval/*.txt\n(Evaluation Protocol Lists)"]:::doc
  end

  subgraph "Data Pipeline"
    DataPy["data.py\n(Dataset I/O + Dataloaders + Transforms)"]:::data
    SrcLoader["Source Loader per task t"]:::data
    TgtLoader["Target Loader per task t"]:::data
    EvalLoader["Eval Loader(s)"]:::data
  end

  %% =========================
  %% Model + Utilities
  %% =========================
  subgraph "Model + Training Utilities"
    NetPy["net.py\n(Model / Network Definition)"]:::model
    LibPy["lib.py\n(Losses, Metrics, Optim/Sched,\nPseudo-labeling, Checkpoint helpers)"]:::train
  end

  %% =========================
  %% Evaluation
  %% =========================
  subgraph "Evaluation"
    EvalPy["eval.py\n(Evaluation Runner + Metrics)"]:::eval
    OpenSetMetrics["Open-set Metrics\n(Known acc + Unknown detection/rejection)"]:::eval
  end

  %% =========================
  %% Outputs / Artifacts
  %% =========================
  subgraph "Outputs (Artifacts)"
    OutCkpt[("Model Checkpoints")]:::storage
    OutLogs[("Logs")]:::storage
    OutReports[("Metric Summaries / Tables")]:::storage
  end

  Readme["README.md\n(Dataset + Run Instructions)"]:::doc

  %% =========================
  %% Control / Startup Flow
  %% =========================
  User -->|"launches"| RunSh
  RunSh -->|"invokes"| Main
  Main -->|"runs_in"| Env

  Readme -.->|"guides_setup"| Dataset
  Readme -.->|"how_to_run"| RunSh

  %% =========================
  %% Config Flow
  %% =========================
  ConfigYaml -->|"hyperparameters"| ConfigPy
  ConfigPy -->|"structured_config"| Main

  %% =========================
  %% Data Flow
  %% =========================
  Main -->|"init_datasets/loaders (paths, transforms, batch_size)"| DataPy
  Dataset -->|"raw_files"| DataPy
  SrcLists -->|"task_split_list (source)"| DataPy
  TgtLists -->|"task_split_list (target)"| DataPy
  EvalProto -->|"eval_protocol_lists"| DataPy

  DataPy -->|"build"| SrcLoader
  DataPy -->|"build"| TgtLoader
  DataPy -->|"build"| EvalLoader

  %% =========================
  %% Continual Task Loop Wiring
  %% =========================
  Main -->|"orchestrates"| TaskSched
  TaskSched -->|"for_each_task_t"| TrainStep

  SrcLoader -->|"train_batches (source)"| SourceStream
  TgtLoader -->|"train_batches (target)"| TargetStream

  SourceStream -->|"feeds"| TrainStep
  TargetStream -->|"feeds"| TrainStep

  Main -->|"instantiate_model"| NetPy
  TrainStep -->|"forward_pass logits/embeddings"| NetPy
  NetPy -->|"predictions/embeddings"| TrainStep

  TrainStep <-->|"losses/optim/scheduler/metrics/checkpoint_helpers"| LibPy

  TrainStep -->|"save_state"| Ckpt
  Ckpt -->|"writes"| OutCkpt
  Ckpt -->|"writes"| OutLogs

  %% =========================
  %% Evaluation Flow
  %% =========================
  TaskSched -->|"evaluate_at_boundaries_or_end"| EvalPy
  EvalLoader -->|"eval_batches"| EvalPy
  EvalProto -->|"protocol (subsets/known-unknown)"| EvalPy
  NetPy -->|"inference outputs"| EvalPy
  EvalPy -->|"compute"| OpenSetMetrics
  OpenSetMetrics -->|"metrics + reports"| OutReports
  EvalPy -->|"logs"| OutLogs

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click Main "https://github.com/nlab-mpg/cosda-hr/blob/master/bic+UDA/main.py"
  click ConfigPy "https://github.com/nlab-mpg/cosda-hr/blob/master/bic+UDA/config.py"
  click ConfigYaml "https://github.com/nlab-mpg/cosda-hr/blob/master/bic+UDA/config.yaml"
  click DataPy "https://github.com/nlab-mpg/cosda-hr/blob/master/bic+UDA/data.py"
  click NetPy "https://github.com/nlab-mpg/cosda-hr/blob/master/bic+UDA/net.py"
  click LibPy "https://github.com/nlab-mpg/cosda-hr/blob/master/bic+UDA/lib.py"
  click EvalPy "https://github.com/nlab-mpg/cosda-hr/blob/master/bic+UDA/eval.py"
  click RunSh "https://github.com/nlab-mpg/cosda-hr/blob/master/bic+UDA/run.sh"
  click Readme "https://github.com/nlab-mpg/cosda-hr/blob/master/README.md"
  click SrcLists "https://github.com/nlab-mpg/cosda-hr/tree/master/bic+UDA/sequential_source/"
  click TgtLists "https://github.com/nlab-mpg/cosda-hr/tree/master/bic+UDA/sequential_target/"
  click EvalProto "https://github.com/nlab-mpg/cosda-hr/blob/master/bic+UDA/eval/evaluation_list.txt"
  click EvalProto "https://github.com/nlab-mpg/cosda-hr/blob/master/bic+UDA/eval/source_eval_list.txt"

  %% =========================
  %% Styles
  %% =========================
  classDef control fill:#1f77b4,stroke:#0d3d66,color:#ffffff,stroke-width:1.5px
  classDef configDoc fill:#77bdf2,stroke:#0d3d66,color:#0b2239,stroke-width:1.2px
  classDef data fill:#2ca02c,stroke:#1b5e20,color:#ffffff,stroke-width:1.5px
  classDef model fill:#ff7f0e,stroke:#8a3f00,color:#ffffff,stroke-width:1.5px
  classDef train fill:#f39c12,stroke:#8a3f00,color:#ffffff,stroke-width:1.5px
  classDef eval fill:#8e44ad,stroke:#4a235a,color:#ffffff,stroke-width:1.5px
  classDef storage fill:#7f8c8d,stroke:#2c3e50,color:#ffffff,stroke-width:1.5px
  classDef artifact fill:#95a5a6,stroke:#2c3e50,color:#0b2239,stroke-width:1.2px
  classDef env fill:#ffffff,stroke:#7f8c8d,color:#2c3e50,stroke-dasharray: 6 4,stroke-width:1.5px
  classDef doc fill:#d5f5e3,stroke:#1b5e20,color:#0b2239,stroke-width:1.2px
  classDef external fill:#ecf0f1,stroke:#7f8c8d,color:#2c3e50,stroke-width:1.2px
```
