# spaicom/semantic-alignment-via-dual-sim architecture

> Architecture diagram of the GitHub repository spaicom/semantic-alignment-via-dual-sim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spaicom/semantic-alignment-via-dual-sim
- Repository: https://github.com/spaicom/semantic-alignment-via-dual-sim

## Overview

This repository implements research experiments for over-the-air semantic alignment: prepare vision embeddings, train or select an alignment strategy, transmit through simulated SIM stacks and wireless channels, then score classification or reconstruction quality. It also supports learned unrolled optimization for channel-varying joint Dual-SIM configurations and plotting experiment results. The graph emphasizes runtime experiment paths and shared simulation layers. README statements and indexed references support the shown links; several script and model internals were not sampled, so uncertain implementation-level connections are omitted.

Main entry points: [`scripts/classification.py`](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/classification.py) (Classification Runs), [`src/semantic_alignment/evaluation/tasks.py`](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/evaluation/tasks.py) (Task Scoring), [`scripts/reconstruction.py`](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/reconstruction.py) (Reconstruction Runs), [`src/semantic_alignment/sim/original/joint.py`](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/original/joint.py) (Joint Dual-SIM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and Tasks"]
  node_prepare["Data Preparation<br/>[prepare.py]"]
  node_semasia["Semantic Embeddings<br/>[semasia.py]"]
  node_reconstruction_data["Reconstruction Data<br/>[reconstruction.py]"]
  node_autoencoder["Autoencoders<br/>[autoencoder.py]"]
  node_tasks["Task Scoring<br/>[tasks.py]"]
  node_inference["Link Inference<br/>[inference.py]"]
  node_linear_probe["Linear Probe<br/>[linear_probe.py]"]
end

subgraph group_physical["SIM Physical Layer"]
  node_channel["Channel Utilities<br/>[channel.py]"]
  node_sim_variants["SIM Architectures"]
  node_joint_runner["Joint Dual-SIM<br/>[joint.py]"]
  node_mono_optimizer["Mono-SIM Optimizer<br/>[monosim.py]"]
  node_dual_optimizer["Dual-SIM Optimizer<br/>[dualsim.py]"]
  node_cascade["Cascade Simulation<br/>[_cascade.py]"]
  node_sim_core["SCA Optimization<br/>[core.py]"]
  node_link["Transmit Link<br/>[link.py]"]
end

subgraph group_unrolled["Unrolled Optimization"]
  node_unrolled_run["Unrolled Runs"]
  node_unrolled_pipeline["Unrolled Pipeline"]
  node_unrolled_steps["Learned Steps<br/>[_step.py]"]
  node_unrolled_runner["Unrolled Runner<br/>[runner.py]"]
end

subgraph group_experiments["Experiments and Results"]
  node_classification_run["Classification Runs<br/>[classification.py]"]
  node_reconstruction_run["Reconstruction Runs<br/>[reconstruction.py]"]
  node_classification_plots["Classification Plots"]
  node_reconstruction_plots["Reconstruction Plots"]
end

node_researcher(("Researcher"))

node_researcher -->|"launches"| node_classification_run
node_researcher -->|"launches"| node_reconstruction_run
node_researcher -->|"launches"| node_unrolled_run
node_classification_run -->|"loads data"| node_prepare
node_prepare -->|"uses embeddings"| node_semasia
node_classification_run -->|"evaluates"| node_linear_probe
node_classification_run -->|"configures task"| node_tasks
node_classification_run -->|"uses channel tools"| node_channel
node_reconstruction_run -->|"uses data"| node_reconstruction_data
node_reconstruction_data -->|"uses models"| node_autoencoder
node_reconstruction_run -->|"scores runs"| node_tasks
node_classification_run -->|"sweeps architectures"| node_sim_variants
node_sim_variants -->|"includes joint"| node_joint_runner
node_joint_runner -->|"optimizes"| node_dual_optimizer
node_joint_runner -->|"builds transmit"| node_link
node_mono_optimizer -->|"uses optimization"| node_sim_core
node_dual_optimizer -->|"uses optimization"| node_sim_core
node_sim_core -->|"builds cascades"| node_cascade
node_link -->|"adds noise"| node_channel
node_tasks -->|"evaluates links"| node_inference
node_tasks -->|"scores transmit"| node_link
node_unrolled_run -->|"runs pipeline"| node_unrolled_pipeline
node_unrolled_pipeline -->|"trains and evaluates"| node_unrolled_runner
node_unrolled_runner -->|"applies steps"| node_unrolled_steps
node_unrolled_pipeline -->|"scores results"| node_tasks
node_classification_plots -.->|"plots results"| node_classification_run
node_reconstruction_plots -.->|"plots results"| node_reconstruction_run

click node_classification_run "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/classification.py"
click node_reconstruction_run "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/reconstruction.py"
click node_unrolled_run "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/unrolled_classification.py"
click node_unrolled_pipeline "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/unrolled_pipeline.py"
click node_prepare "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/data/prepare.py"
click node_semasia "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/data/semasia.py"
click node_reconstruction_data "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/data/reconstruction.py"
click node_autoencoder "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/models/autoencoder.py"
click node_tasks "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/evaluation/tasks.py"
click node_inference "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/evaluation/inference.py"
click node_linear_probe "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/evaluation/linear_probe.py"
click node_channel "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/utils/channel.py"
click node_sim_variants "https://github.com/spaicom/semantic-alignment-via-dual-sim/tree/main/src/semantic_alignment/sim/original"
click node_joint_runner "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/original/joint.py"
click node_mono_optimizer "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/original/optimizers/monosim.py"
click node_dual_optimizer "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/original/optimizers/dualsim.py"
click node_cascade "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/_cascade.py"
click node_sim_core "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/core.py"
click node_link "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/link.py"
click node_unrolled_steps "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/unrolled/_step.py"
click node_unrolled_runner "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/unrolled/runner.py"
click node_classification_plots "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/plot_results_classification.py"
click node_reconstruction_plots "https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/plot_results_reconstruction.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_prepare,node_semasia,node_reconstruction_data,node_autoencoder,node_tasks,node_inference,node_linear_probe toneBlue
class node_channel,node_sim_variants,node_joint_runner,node_mono_optimizer,node_dual_optimizer,node_cascade,node_sim_core,node_link toneAmber
class node_unrolled_run,node_unrolled_pipeline,node_unrolled_steps,node_unrolled_runner toneMint
class node_classification_run,node_reconstruction_run,node_classification_plots,node_reconstruction_plots toneRose
class node_researcher toneIndigo
```

## Components

### Data and Tasks

- [Data Preparation](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/data/prepare.py): `src/semantic_alignment/data/prepare.py`
- [Semantic Embeddings](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/data/semasia.py): `src/semantic_alignment/data/semasia.py`
- [Reconstruction Data](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/data/reconstruction.py): `src/semantic_alignment/data/reconstruction.py`
- [Autoencoders](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/models/autoencoder.py): `src/semantic_alignment/models/autoencoder.py`
- [Task Scoring](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/evaluation/tasks.py): `src/semantic_alignment/evaluation/tasks.py`
- [Link Inference](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/evaluation/inference.py): `src/semantic_alignment/evaluation/inference.py`
- [Linear Probe](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/evaluation/linear_probe.py): `src/semantic_alignment/evaluation/linear_probe.py`

### SIM Physical Layer

- [Channel Utilities](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/utils/channel.py): `src/semantic_alignment/utils/channel.py`
- [SIM Architectures](https://github.com/spaicom/semantic-alignment-via-dual-sim/tree/main/src/semantic_alignment/sim/original): `src/semantic_alignment/sim/original`
- [Joint Dual-SIM](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/original/joint.py): `src/semantic_alignment/sim/original/joint.py`
- [Mono-SIM Optimizer](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/original/optimizers/monosim.py): `src/semantic_alignment/sim/original/optimizers/monosim.py`
- [Dual-SIM Optimizer](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/original/optimizers/dualsim.py): `src/semantic_alignment/sim/original/optimizers/dualsim.py`
- [Cascade Simulation](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/_cascade.py): `src/semantic_alignment/sim/_cascade.py`
- [SCA Optimization](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/core.py): `src/semantic_alignment/sim/core.py`
- [Transmit Link](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/link.py): `src/semantic_alignment/sim/link.py`

### Unrolled Optimization

- [Unrolled Runs](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/unrolled_classification.py): `scripts/unrolled_classification.py`
- [Unrolled Pipeline](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/unrolled_pipeline.py): `scripts/unrolled_pipeline.py`
- [Learned Steps](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/unrolled/_step.py): `src/semantic_alignment/sim/unrolled/_step.py`
- [Unrolled Runner](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/src/semantic_alignment/sim/unrolled/runner.py): `src/semantic_alignment/sim/unrolled/runner.py`

### Experiments and Results

- [Classification Runs](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/classification.py): `scripts/classification.py`
- [Reconstruction Runs](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/reconstruction.py): `scripts/reconstruction.py`
- [Classification Plots](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/plot_results_classification.py): `scripts/plot_results_classification.py`
- [Reconstruction Plots](https://github.com/spaicom/semantic-alignment-via-dual-sim/blob/main/scripts/plot_results_reconstruction.py): `scripts/plot_results_reconstruction.py`

### Other components

- **Researcher**

## Connections

- Researcher → Classification Runs: launches (evidence: `README.md`)
- Researcher → Reconstruction Runs: launches (evidence: `README.md`)
- Researcher → Unrolled Runs: launches (evidence: `README.md`)
- Classification Runs → Data Preparation: loads data (evidence: `scripts/classification.py`)
- Data Preparation → Semantic Embeddings: uses embeddings (evidence: `src/semantic_alignment/data/prepare.py`)
- Classification Runs → Linear Probe: evaluates (evidence: `scripts/classification.py`)
- Classification Runs → Task Scoring: configures task (evidence: `scripts/classification.py`)
- Classification Runs → Channel Utilities: uses channel tools (evidence: `scripts/classification.py`)
- Reconstruction Runs → Reconstruction Data: uses data (evidence: `README.md`)
- Reconstruction Data → Autoencoders: uses models (evidence: `src/semantic_alignment/data/reconstruction.py`)
- Reconstruction Runs → Task Scoring: scores runs (evidence: `README.md`)
- Classification Runs → SIM Architectures: sweeps architectures (evidence: `README.md`)
- SIM Architectures → Joint Dual-SIM: includes joint (evidence: `README.md`)
- Joint Dual-SIM → Dual-SIM Optimizer: optimizes (evidence: `src/semantic_alignment/sim/original/joint.py`)
- Joint Dual-SIM → Transmit Link: builds transmit (evidence: `src/semantic_alignment/sim/original/joint.py`)
- Mono-SIM Optimizer → SCA Optimization: uses optimization (evidence: `src/semantic_alignment/sim/original/optimizers/monosim.py`)
- Dual-SIM Optimizer → SCA Optimization: uses optimization (evidence: `src/semantic_alignment/sim/original/optimizers/dualsim.py`)
- SCA Optimization → Cascade Simulation: builds cascades (evidence: `src/semantic_alignment/sim/core.py`)
- Transmit Link → Channel Utilities: adds noise (evidence: `src/semantic_alignment/sim/link.py`)
- Task Scoring → Link Inference: evaluates links (evidence: `src/semantic_alignment/evaluation/tasks.py`)
- Task Scoring → Transmit Link: scores transmit (evidence: `src/semantic_alignment/evaluation/tasks.py`)
- Unrolled Runs → Unrolled Pipeline: runs pipeline (evidence: `scripts/unrolled_classification.py`)
- Unrolled Pipeline → Unrolled Runner: trains and evaluates (evidence: `scripts/unrolled_pipeline.py`)
- Unrolled Runner → Learned Steps: applies steps
- Unrolled Pipeline → Task Scoring: scores results (evidence: `scripts/unrolled_pipeline.py`)
- Classification Plots → Classification Runs: plots results (evidence: `README.md`)
- Reconstruction Plots → Reconstruction Runs: plots results (evidence: `README.md`)
