# jthan1218/mimogs architecture

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

- Interactive diagram: https://gitdiagram.com/jthan1218/mimogs
- Repository: https://github.com/jthan1218/mimogs

## Overview

1. **What this repository is**
   - MIMO-GS is a research/ML codebase for rendering MIMO channels using a 3D Gaussian Splatting formulation.
   - The core runtime is Python, with performance-critical rasterization and metric kernels implemented as CUDA/C++ extensions.

2. **Top-level execution paths**
   - `train.py` is the main training entry point.
   - `fine_tuning.py` is a separate pipeline for adapting an existing model to new data or conditions.
   - `debug_gaussian.py` is a diagnostic tool for inspecting Gaussian state and rendering behavior.
   - These scripts orchestrate the same underlying components: argument parsing, scene/data loading, Gaussian model updates, rendering, and loss computation.

3. **Configuration and experiment setup**
   - `arguments/` centralizes runtime configuration, likely exposing model, dataset, optimization, and rendering options.
   - This package is the boundary between CLI/user-facing settings and the internal training/rendering pipeline.
   - The repo is designed to be run in a conda environment defined in `environment.yml`.

4. **Data and scene subsystem**
   - `scene/` contains the data-side architecture:
     - `dataloader.py` handles loading and batching of the MIMO/channel scene data.
     - `gaussian_model.py` defines the scene representation in terms of learnable Gaussian primitives.
   - This layer prepares domain data for the renderer and likely maintains camera/view or channel geometry metadata needed for projection and supervision.

5. **Learnable scene representation**
   - The Gaussian model is the main stateful object in the system.
   - It is responsible for storing and updating parameters of the Gaussian set used to represent the channel/scene.
   - In the architecture diagram, this is the central learnable repository of geometry, appearance/channel attributes, and possibly per-Gaussian covariance/opacities/features.

6. **Rendering subsystem**
   - `gaussian_renderer/` is the rendering facade used by training and debugging scripts.
   - It sits between the Python training loop and the native rasterization backend.
   - Its role is to convert Gaussian model state into rendered outputs suitable for supervision and evaluation.

7. **Native acceleration and external CUDA dependencies**
   - `submodules/diff-gaussian-rasterization` is the main differentiable renderer backend.
   - `submodules/simple-knn` provides fast neighbor search, likely used for initialization, clustering, densification, or spatial queries.
   - These are compiled extensions, not pure-Python dependencies, and form the performance boundary of the system.
   - The repo also vendors `submodules/fused-ssim`, a CUDA implementation of SSIM used for image-quality loss or evaluation.

8. **Training and optimization flow**
   - The training loop typically flows as:
     - load arguments,
     - construct scene/data loader,
     - initialize Gaussian model,
     - render predictions through the differentiable rasterizer,
     - compare against ground truth via loss functions,
     - backpropagate through the renderer into Gaussian parameters.
   - This is an end-to-end differentiable pipeline, with gradients flowing from loss metrics back into the Gaussian representation.

9. **Losses, metrics, and evaluation**
   - `utils/loss.py` contains objective functions used during optimization.
   - The presence of `fused-ssim` suggests image similarity is an important training signal alongside pixel-level or structural losses.
   - `utils/logger.py` likely collects scalar metrics, render previews, and training progress for experiments.

10. **General-purpose utilities**
   - `utils/general_utils.py` and `utils/system_utils.py` provide shared helpers for math, tensor handling, filesystem/path management, and environment/device checks.
   - These are support layers rather than architectural pillars, but they reduce coupling across training, rendering, and evaluation code.

11. **Build and dependency boundaries**
   - The repo intentionally separates pure Python orchestration from compiled numerical kernels.
   - The `submodules/` directory contains third-party code that must be built or installed into the environment before training works.
   - That makes the architecture split into:
     - Python control plane,
     - CUDA/C++ compute plane,
     - dataset/scene inputs,
     - experiment outputs/logs.

12. **How to draw the architecture**
   - A useful diagram would place `train.py`/`fine_tuning.py` at the top as orchestrators.
   - Below them, show `arguments/` feeding configuration into `scene/` and `gaussian_renderer/`.
   - Put `scene/dataloader.py` on the input side, feeding data into `scene/gaussian_model.py`.
   - Put the CUDA submodules under the renderer as acceleration backends.
   - Show `utils/` as shared support functions and logging/loss infrastructure around the main loop.

Main entry points: [`train.py`](https://github.com/jthan1218/mimogs/blob/main/train.py) (train.py), [`gaussian_renderer/__init__.py`](https://github.com/jthan1218/mimogs/blob/main/gaussian_renderer/__init__.py) (renderer), [`fine_tuning.py`](https://github.com/jthan1218/mimogs/blob/main/fine_tuning.py) (fine_tune), [`scene/gaussian_model.py`](https://github.com/jthan1218/mimogs/blob/main/scene/gaussian_model.py) (gaussian model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_train_py["train.py<br/>training entrypoint<br/>[train.py]"]
  node_fine_tuning_py["fine_tune<br/>adaptation entrypoint<br/>[fine_tuning.py]"]
  node_debug_py["debug<br/>diagnostic entrypoint<br/>[debug_gaussian.py]"]
  node_arguments_pkg["arguments<br/>config package<br/>[__init__.py]"]
end

subgraph group_scene["Scene core"]
  node_scene_dataloader["data loader<br/>scene input<br/>[dataloader.py]"]
  node_gaussian_model[("gaussian model<br/>learnable state<br/>[gaussian_model.py]")]
  node_gaussian_renderer_pkg["renderer<br/>render facade<br/>[__init__.py]"]
end

subgraph group_native["Native backends"]
  node_diff_raster["rasterizer<br/>cuda renderer backend<br/>[ext.cpp]"]
  node_diff_raster_cuda["cuda raster<br/>cuda kernels<br/>[rasterizer_impl.cu]"]
  node_simple_knn["simple knn<br/>spatial kernel<br/>[ext.cpp]"]
  node_simple_knn_cuda["knn cuda<br/>cuda kernels<br/>[simple_knn.cu]"]
  node_fused_ssim["fused ssim<br/>quality kernel<br/>[ext.cpp]"]
end

subgraph group_support["Support"]
  node_loss_utils["losses<br/>objective functions<br/>[loss.py]"]
  node_logger_utils["logger<br/>experiment logging<br/>[logger.py]"]
  node_general_utils["general utils<br/>shared helpers<br/>[general_utils.py]"]
  node_system_utils["system utils<br/>env helpers<br/>[system_utils.py]"]
end

node_train_py -->|"reads config"| node_arguments_pkg
node_fine_tuning_py -->|"reads config"| node_arguments_pkg
node_debug_py -->|"reads config"| node_arguments_pkg
node_train_py -->|"loads data"| node_scene_dataloader
node_train_py -->|"updates state"| node_gaussian_model
node_train_py -->|"renders"| node_gaussian_renderer_pkg
node_train_py -->|"optimizes with"| node_loss_utils
node_train_py -->|"logs"| node_logger_utils
node_fine_tuning_py -->|"loads data"| node_scene_dataloader
node_fine_tuning_py -->|"adapts state"| node_gaussian_model
node_fine_tuning_py -->|"renders"| node_gaussian_renderer_pkg
node_fine_tuning_py -->|"optimizes with"| node_loss_utils
node_debug_py -->|"inspects"| node_gaussian_model
node_debug_py -->|"renders"| node_gaussian_renderer_pkg
node_gaussian_renderer_pkg -->|"calls"| node_diff_raster
node_diff_raster -->|"accelerates"| node_diff_raster_cuda
node_gaussian_renderer_pkg -->|"uses"| node_simple_knn
node_simple_knn -->|"accelerates"| node_simple_knn_cuda
node_loss_utils -->|"uses"| node_fused_ssim
node_scene_dataloader -->|"provides supervision to"| node_gaussian_model
node_gaussian_model -->|"feeds parameters to"| node_gaussian_renderer_pkg
node_general_utils -->|"supports"| node_train_py
node_general_utils -->|"supports"| node_gaussian_renderer_pkg
node_system_utils -->|"supports"| node_train_py
node_system_utils -->|"supports"| node_fine_tuning_py
node_logger_utils -->|"writes outputs via"| node_system_utils

click node_train_py "https://github.com/jthan1218/mimogs/blob/main/train.py"
click node_fine_tuning_py "https://github.com/jthan1218/mimogs/blob/main/fine_tuning.py"
click node_debug_py "https://github.com/jthan1218/mimogs/blob/main/debug_gaussian.py"
click node_arguments_pkg "https://github.com/jthan1218/mimogs/blob/main/arguments/__init__.py"
click node_scene_dataloader "https://github.com/jthan1218/mimogs/blob/main/scene/dataloader.py"
click node_gaussian_model "https://github.com/jthan1218/mimogs/blob/main/scene/gaussian_model.py"
click node_gaussian_renderer_pkg "https://github.com/jthan1218/mimogs/blob/main/gaussian_renderer/__init__.py"
click node_loss_utils "https://github.com/jthan1218/mimogs/blob/main/utils/loss.py"
click node_logger_utils "https://github.com/jthan1218/mimogs/blob/main/utils/logger.py"
click node_general_utils "https://github.com/jthan1218/mimogs/blob/main/utils/general_utils.py"
click node_system_utils "https://github.com/jthan1218/mimogs/blob/main/utils/system_utils.py"
click node_diff_raster "https://github.com/jthan1218/mimogs/blob/main/submodules/diff-gaussian-rasterization/ext.cpp"
click node_diff_raster_cuda "https://github.com/jthan1218/mimogs/blob/main/submodules/diff-gaussian-rasterization/cuda_rasterizer/rasterizer_impl.cu"
click node_simple_knn "https://github.com/jthan1218/mimogs/blob/main/submodules/simple-knn/ext.cpp"
click node_simple_knn_cuda "https://github.com/jthan1218/mimogs/blob/main/submodules/simple-knn/simple_knn.cu"
click node_fused_ssim "https://github.com/jthan1218/mimogs/blob/main/submodules/fused-ssim/ext.cpp"

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_train_py,node_fine_tuning_py,node_debug_py,node_arguments_pkg toneBlue
class node_scene_dataloader,node_gaussian_model,node_gaussian_renderer_pkg toneAmber
class node_diff_raster,node_diff_raster_cuda,node_simple_knn,node_simple_knn_cuda,node_fused_ssim toneMint
class node_loss_utils,node_logger_utils,node_general_utils,node_system_utils toneRose
```

## Components

### Control plane

CLI entrypoints and runtime configuration

- [train.py](https://github.com/jthan1218/mimogs/blob/main/train.py): training entrypoint · Main end-to-end training orchestrator · `train.py`
- [fine_tune](https://github.com/jthan1218/mimogs/blob/main/fine_tuning.py): adaptation entrypoint · Pipeline for adapting an existing model · `fine_tuning.py`
- [debug](https://github.com/jthan1218/mimogs/blob/main/debug_gaussian.py): diagnostic entrypoint · Inspects Gaussian state and rendering behavior · `debug_gaussian.py`
- [arguments](https://github.com/jthan1218/mimogs/blob/main/arguments/__init__.py): config package · CLI/runtime configuration boundary · `arguments/__init__.py`

### Scene core

Data loading and learnable Gaussian representation

- [data loader](https://github.com/jthan1218/mimogs/blob/main/scene/dataloader.py): scene input · Loads and batches MIMO/channel scene data · `scene/dataloader.py`
- [gaussian model](https://github.com/jthan1218/mimogs/blob/main/scene/gaussian_model.py): learnable state · Stateful Gaussian scene/channel representation · `scene/gaussian_model.py`
- [renderer](https://github.com/jthan1218/mimogs/blob/main/gaussian_renderer/__init__.py): render facade · Python rendering interface used by scripts · `gaussian_renderer/__init__.py`

### Native backends

CUDA/C++ acceleration and compiled extensions

- [rasterizer](https://github.com/jthan1218/mimogs/blob/main/submodules/diff-gaussian-rasterization/ext.cpp): cuda renderer backend · Differentiable Gaussian rasterization kernel · `submodules/diff-gaussian-rasterization/ext.cpp`
- [cuda raster](https://github.com/jthan1218/mimogs/blob/main/submodules/diff-gaussian-rasterization/cuda_rasterizer/rasterizer_impl.cu): cuda kernels · Forward and backward rasterization implementation · `submodules/diff-gaussian-rasterization/cuda_rasterizer/rasterizer_impl.cu`
- [simple knn](https://github.com/jthan1218/mimogs/blob/main/submodules/simple-knn/ext.cpp): spatial kernel · Fast neighbor search extension · `submodules/simple-knn/ext.cpp`
- [knn cuda](https://github.com/jthan1218/mimogs/blob/main/submodules/simple-knn/simple_knn.cu): cuda kernels · Spatial query and neighbor search kernels · `submodules/simple-knn/simple_knn.cu`
- [fused ssim](https://github.com/jthan1218/mimogs/blob/main/submodules/fused-ssim/ext.cpp): quality kernel · CUDA SSIM loss and metric implementation · `submodules/fused-ssim/ext.cpp`

### Support

Losses, logging, and shared utilities

- [losses](https://github.com/jthan1218/mimogs/blob/main/utils/loss.py): objective functions · Training and evaluation loss computation · `utils/loss.py`
- [logger](https://github.com/jthan1218/mimogs/blob/main/utils/logger.py): experiment logging · Tracks metrics, previews, and progress · `utils/logger.py`
- [general utils](https://github.com/jthan1218/mimogs/blob/main/utils/general_utils.py): shared helpers · Common math, tensor, and filesystem helpers · `utils/general_utils.py`
- [system utils](https://github.com/jthan1218/mimogs/blob/main/utils/system_utils.py): env helpers · Device, path, and environment utilities · `utils/system_utils.py`

## Connections

- train.py → arguments: reads config
- fine_tune → arguments: reads config
- debug → arguments: reads config
- train.py → data loader: loads data
- train.py → gaussian model: updates state
- train.py → renderer: renders
- train.py → losses: optimizes with
- train.py → logger: logs
- fine_tune → data loader: loads data
- fine_tune → gaussian model: adapts state
- fine_tune → renderer: renders
- fine_tune → losses: optimizes with
- debug → gaussian model: inspects
- debug → renderer: renders
- renderer → rasterizer: calls
- rasterizer → cuda raster: accelerates
- renderer → simple knn: uses
- simple knn → knn cuda: accelerates
- losses → fused ssim: uses
- data loader → gaussian model: provides supervision to
- gaussian model → renderer: feeds parameters to
- general utils → train.py: supports
- general utils → renderer: supports
- system utils → train.py: supports
- system utils → fine_tune: supports
- logger → system utils: writes outputs via
