# ufcompressor/caesar architecture

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

- Interactive diagram: https://gitdiagram.com/ufcompressor/caesar
- Repository: https://github.com/ufcompressor/caesar

## Overview

CAESAR reduces scientific spatio-temporal tensors through a C++ compression/decompression workflow, with Python model and training components providing learned architectures and a parallel Python compressor. The README also documents model catalog and checkpoint verification. The sampled CLI excerpt shows command dispatch and metadata handling, while the source index confirms selected module references; some runtime links are omitted where implementation excerpts do not establish them.

Main entry points: [`CAESAR/models/caesar_compress.cpp`](https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/caesar_compress.cpp) (Compression engine), [`pyCAESAR/compressor.py`](https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/compressor.py) (Python compressor), [`CAESAR/CAESAR.cpp`](https://github.com/ufcompressor/caesar/blob/master/CAESAR/CAESAR.cpp) (CAESAR CLI), [`CAESAR/models/caesar_decompress.cpp`](https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/caesar_decompress.cpp) (Decompression engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cpp["C++ reduction"]
  node_cli["CAESAR CLI<br/>[CAESAR.cpp]"]
  node_tensor["Tensor utilities<br/>[data_utils.h]"]
  node_dataset["Scientific dataset<br/>[dataset.h]"]
  node_compress["Compression engine"]
  node_decompress["Decompression engine"]
  node_range["rANS coding<br/>[rans_coder.cpp]"]
  node_stream["Compressed output"]
  node_restored["Reconstructed data"]
end

subgraph group_learned["Learned models"]
  node_gae["GAE correction<br/>[runGaeCuda.cpp]"]
  node_lossless["GPU lossless<br/>[gpu_lossess.cpp]"]
  node_lbrc["LBRC method<br/>[lbrc.cpp]"]
  node_nglr["NGLR method<br/>[nglr.cpp]"]
  node_cache["Model cache<br/>[model_cache.h]"]
end

subgraph group_python["Python workflows"]
  node_pycompress["Python compressor<br/>[compressor.py]"]
  node_pygae["Python GAE<br/>[run_gae_cuda.py]"]
  node_vae["VAE components"]
  node_bcrn["Super-resolution<br/>[bcrn_model.py]"]
  node_encoding["Python range coding<br/>[RangeEncoding.py]"]
  node_video["Video diffusion"]
  node_training["VAE training<br/>[train_vae3d.py]"]
end

subgraph group_catalog["Model catalog"]
  node_registry["Checkpoint registry<br/>[model_registry.py]"]
  node_register["Model registration<br/>[register_model.py]"]
end

node_scientist(("Scientific user"))

node_scientist -->|"invokes"| node_cli
node_cli -->|"dispatches compression"| node_compress
node_cli -->|"dispatches decompression"| node_decompress
node_cli -->|"writes metadata"| node_stream
node_cli -->|"writes result"| node_restored
node_compress -->|"uses dataset"| node_dataset
node_compress -->|"uses conversion"| node_tensor
node_compress -->|"encodes latents"| node_range
node_compress -->|"uses correction"| node_gae
node_compress -->|"supports method"| node_lbrc
node_compress -->|"supports method"| node_nglr
node_compress -->|"loads models"| node_cache
node_decompress -->|"decodes latents"| node_range
node_decompress -->|"uses reconstruction"| node_gae
node_compress -.->|"produces payload"| node_stream
node_decompress -.->|"produces data"| node_restored
node_scientist -.->|"runs workflow"| node_pycompress
node_pycompress -->|"invokes"| node_pygae
node_pycompress -->|"uses model"| node_vae
node_pycompress -->|"uses upscaling"| node_bcrn
node_pycompress -->|"uses coding"| node_encoding
node_pycompress -->|"uses interpolation"| node_video
node_training -->|"trains components"| node_vae
node_training -->|"uses network"| node_bcrn
node_scientist -.->|"selects checkpoint"| node_registry
node_register -->|"updates catalog"| node_registry

click node_cli "https://github.com/ufcompressor/caesar/blob/master/CAESAR/CAESAR.cpp"
click node_tensor "https://github.com/ufcompressor/caesar/blob/master/CAESAR/data_utils.h"
click node_dataset "https://github.com/ufcompressor/caesar/blob/master/CAESAR/dataset/dataset.h"
click node_compress "https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/caesar_compress.cpp"
click node_decompress "https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/caesar_decompress.cpp"
click node_range "https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/range_coder/rans_coder.cpp"
click node_gae "https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/runGaeCuda.cpp"
click node_lossless "https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/gpu_lossess.cpp"
click node_lbrc "https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/lbrc.cpp"
click node_nglr "https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/nglr.cpp"
click node_cache "https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/model_cache.h"
click node_pycompress "https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/compressor.py"
click node_pygae "https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/models/run_gae_cuda.py"
click node_vae "https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/models/network_components.py"
click node_bcrn "https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/models/BCRN/bcrn_model.py"
click node_encoding "https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/models/RangeEncoding.py"
click node_video "https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/models/video_diffusion_interpo.py"
click node_training "https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/train_vae3d.py"
click node_registry "https://github.com/ufcompressor/caesar/blob/master/model_registry.py"
click node_register "https://github.com/ufcompressor/caesar/blob/master/register_model.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_cli,node_tensor,node_dataset,node_compress,node_decompress,node_range,node_stream,node_restored,node_scientist toneBlue
class node_gae,node_lossless,node_lbrc,node_nglr,node_cache toneAmber
class node_pycompress,node_pygae,node_vae,node_bcrn,node_encoding,node_video,node_training toneMint
class node_registry,node_register toneRose
```

## Components

### C++ reduction

- [CAESAR CLI](https://github.com/ufcompressor/caesar/blob/master/CAESAR/CAESAR.cpp): `CAESAR/CAESAR.cpp`
- [Tensor utilities](https://github.com/ufcompressor/caesar/blob/master/CAESAR/data_utils.h): `CAESAR/data_utils.h`
- [Scientific dataset](https://github.com/ufcompressor/caesar/blob/master/CAESAR/dataset/dataset.h): `CAESAR/dataset/dataset.h`
- [Compression engine](https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/caesar_compress.cpp): `CAESAR/models/caesar_compress.cpp`
- [Decompression engine](https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/caesar_decompress.cpp): `CAESAR/models/caesar_decompress.cpp`
- [rANS coding](https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/range_coder/rans_coder.cpp): `CAESAR/models/range_coder/rans_coder.cpp`
- **Compressed output**
- **Reconstructed data**

### Learned models

- [GAE correction](https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/runGaeCuda.cpp): `CAESAR/models/runGaeCuda.cpp`
- [GPU lossless](https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/gpu_lossess.cpp): `CAESAR/models/gpu_lossess.cpp`
- [LBRC method](https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/lbrc.cpp): `CAESAR/models/lbrc.cpp`
- [NGLR method](https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/nglr.cpp): `CAESAR/models/nglr.cpp`
- [Model cache](https://github.com/ufcompressor/caesar/blob/master/CAESAR/models/model_cache.h): `CAESAR/models/model_cache.h`

### Python workflows

- [Python compressor](https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/compressor.py): `pyCAESAR/compressor.py`
- [Python GAE](https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/models/run_gae_cuda.py): `pyCAESAR/models/run_gae_cuda.py`
- [VAE components](https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/models/network_components.py): `pyCAESAR/models/network_components.py`
- [Super-resolution](https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/models/BCRN/bcrn_model.py): `pyCAESAR/models/BCRN/bcrn_model.py`
- [Python range coding](https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/models/RangeEncoding.py): `pyCAESAR/models/RangeEncoding.py`
- [Video diffusion](https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/models/video_diffusion_interpo.py): `pyCAESAR/models/video_diffusion_interpo.py`
- [VAE training](https://github.com/ufcompressor/caesar/blob/master/pyCAESAR/train_vae3d.py): `pyCAESAR/train_vae3d.py`

### Model catalog

- [Checkpoint registry](https://github.com/ufcompressor/caesar/blob/master/model_registry.py): `model_registry.py`
- [Model registration](https://github.com/ufcompressor/caesar/blob/master/register_model.py): `register_model.py`

### Other components

- **Scientific user**

## Connections

- Scientific user → CAESAR CLI: invokes (evidence: `CAESAR/CAESAR.cpp`)
- CAESAR CLI → Compression engine: dispatches compression (evidence: `CAESAR/CAESAR.cpp`)
- CAESAR CLI → Decompression engine: dispatches decompression (evidence: `CAESAR/CAESAR.cpp`)
- CAESAR CLI → Compressed output: writes metadata (evidence: `CAESAR/CAESAR.cpp`)
- CAESAR CLI → Reconstructed data: writes result (evidence: `CAESAR/CAESAR.cpp`)
- Compression engine → Scientific dataset: uses dataset
- Compression engine → Tensor utilities: uses conversion
- Compression engine → rANS coding: encodes latents
- Compression engine → GAE correction: uses correction
- Compression engine → LBRC method: supports method
- Compression engine → NGLR method: supports method
- Compression engine → Model cache: loads models
- Decompression engine → rANS coding: decodes latents
- Decompression engine → GAE correction: uses reconstruction
- Compression engine → Compressed output: produces payload
- Decompression engine → Reconstructed data: produces data
- Scientific user → Python compressor: runs workflow
- Python compressor → Python GAE: invokes (evidence: `pyCAESAR/compressor.py`)
- Python compressor → VAE components: uses model (evidence: `pyCAESAR/compressor.py`)
- Python compressor → Super-resolution: uses upscaling (evidence: `pyCAESAR/compressor.py`)
- Python compressor → Python range coding: uses coding (evidence: `pyCAESAR/compressor.py`)
- Python compressor → Video diffusion: uses interpolation (evidence: `pyCAESAR/compressor.py`)
- VAE training → VAE components: trains components (evidence: `pyCAESAR/train_vae3d.py`)
- VAE training → Super-resolution: uses network (evidence: `pyCAESAR/train_vae3d.py`)
- Scientific user → Checkpoint registry: selects checkpoint
- Model registration → Checkpoint registry: updates catalog (evidence: `register_model.py`)
