# txie-93/cdvae architecture

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

- Interactive diagram: https://gitdiagram.com/txie-93/cdvae
- Repository: https://github.com/txie-93/cdvae

## Overview

CDVAE learns periodic crystal structures from curated datasets, then supports reconstruction, latent-space generation, and property-guided inverse design. The documented workflow is configured training, followed by model-backed evaluation and metric computation. The graph covers data preparation and the principal model components; evaluation links are based on the README and source index. Some internal model wiring and unsampled evaluation behavior are not shown, so those connections are omitted.

Main entry points: [`scripts/eval_utils.py`](https://github.com/txie-93/cdvae/blob/main/scripts/eval_utils.py) (Evaluation utilities), [`cdvae/pl_data/datamodule.py`](https://github.com/txie-93/cdvae/blob/main/cdvae/pl_data/datamodule.py) (Data module), [`cdvae/run.py`](https://github.com/txie-93/cdvae/blob/main/cdvae/run.py) (Training entry), [`scripts/evaluate.py`](https://github.com/txie-93/cdvae/blob/main/scripts/evaluate.py) (Task evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["User workflow"]
  node_training["Training entry<br/>[run.py]"]
  node_configs["Run configuration"]
end

subgraph group_data["Crystal data"]
  node_datasets[("Crystal datasets")]
  node_datamodule["Data module<br/>[datamodule.py]"]
  node_dataset["Crystal datasets<br/>[dataset.py]"]
  node_crystal_utils["Crystal preprocessing<br/>[data_utils.py]"]
end

subgraph group_model["Generative model"]
  node_model["CDVAE model<br/>[model.py]"]
  node_gnn["Graph encoders<br/>[gnn.py]"]
  node_decoder["Crystal decoder<br/>[decoder.py]"]
  node_gemnet["GemNet network<br/>[gemnet.py]"]
  node_gemnet_layers["Message-passing layers"]
  node_embeddings["Element embeddings"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Task evaluation<br/>[evaluate.py]"]
  node_eval_utils["Evaluation utilities<br/>[eval_utils.py]"]
  node_metrics["Metric computation<br/>[compute_metrics.py]"]
  node_results["Evaluation artifacts"]
end

node_user(("Researcher"))

node_user -->|"starts training"| node_training
node_training -->|"uses configuration"| node_configs
node_training -.->|"trains with data"| node_datamodule
node_datasets -->|"provides splits"| node_datamodule
node_datamodule -->|"instantiates"| node_dataset
node_dataset -->|"preprocesses crystals"| node_crystal_utils
node_model -->|"uses crystal utilities"| node_crystal_utils
node_model -->|"uses embeddings"| node_embeddings
node_decoder -->|"uses network"| node_gemnet
node_gemnet -->|"uses layers"| node_gemnet_layers
node_gemnet_layers -->|"embeds atoms"| node_embeddings
node_user -->|"selects tasks"| node_evaluation
node_evaluation -->|"loads evaluation helpers"| node_eval_utils
node_eval_utils -->|"builds tensor dataset"| node_dataset
node_eval_utils -->|"loads data module"| node_datamodule
node_eval_utils -->|"loads checkpoint"| node_model
node_evaluation -->|"writes task outputs"| node_results
node_user -->|"requests metrics"| node_metrics
node_metrics -->|"uses evaluation utilities"| node_eval_utils
node_metrics -->|"writes metrics"| node_results

click node_training "https://github.com/txie-93/cdvae/blob/main/cdvae/run.py"
click node_configs "https://github.com/txie-93/cdvae/tree/main/conf"
click node_datasets "https://github.com/txie-93/cdvae/tree/main/data"
click node_datamodule "https://github.com/txie-93/cdvae/blob/main/cdvae/pl_data/datamodule.py"
click node_dataset "https://github.com/txie-93/cdvae/blob/main/cdvae/pl_data/dataset.py"
click node_crystal_utils "https://github.com/txie-93/cdvae/blob/main/cdvae/common/data_utils.py"
click node_model "https://github.com/txie-93/cdvae/blob/main/cdvae/pl_modules/model.py"
click node_gnn "https://github.com/txie-93/cdvae/blob/main/cdvae/pl_modules/gnn.py"
click node_decoder "https://github.com/txie-93/cdvae/blob/main/cdvae/pl_modules/decoder.py"
click node_gemnet "https://github.com/txie-93/cdvae/blob/main/cdvae/pl_modules/gemnet/gemnet.py"
click node_gemnet_layers "https://github.com/txie-93/cdvae/tree/main/cdvae/pl_modules/gemnet/layers"
click node_embeddings "https://github.com/txie-93/cdvae/tree/main/cdvae/pl_modules/embeddings"
click node_evaluation "https://github.com/txie-93/cdvae/blob/main/scripts/evaluate.py"
click node_eval_utils "https://github.com/txie-93/cdvae/blob/main/scripts/eval_utils.py"
click node_metrics "https://github.com/txie-93/cdvae/blob/main/scripts/compute_metrics.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_training,node_configs toneBlue
class node_datasets,node_datamodule,node_dataset,node_crystal_utils toneAmber
class node_model,node_gnn,node_decoder,node_gemnet,node_gemnet_layers,node_embeddings toneMint
class node_evaluation,node_eval_utils,node_metrics,node_results toneRose
class node_user toneIndigo
```

## Components

### User workflow

- [Training entry](https://github.com/txie-93/cdvae/blob/main/cdvae/run.py): `cdvae/run.py`
- [Run configuration](https://github.com/txie-93/cdvae/tree/main/conf): `conf`

### Crystal data

- [Crystal datasets](https://github.com/txie-93/cdvae/tree/main/data): `data`
- [Data module](https://github.com/txie-93/cdvae/blob/main/cdvae/pl_data/datamodule.py): `cdvae/pl_data/datamodule.py`
- [Crystal datasets](https://github.com/txie-93/cdvae/blob/main/cdvae/pl_data/dataset.py): `cdvae/pl_data/dataset.py`
- [Crystal preprocessing](https://github.com/txie-93/cdvae/blob/main/cdvae/common/data_utils.py): `cdvae/common/data_utils.py`

### Generative model

- [CDVAE model](https://github.com/txie-93/cdvae/blob/main/cdvae/pl_modules/model.py): `cdvae/pl_modules/model.py`
- [Graph encoders](https://github.com/txie-93/cdvae/blob/main/cdvae/pl_modules/gnn.py): `cdvae/pl_modules/gnn.py`
- [Crystal decoder](https://github.com/txie-93/cdvae/blob/main/cdvae/pl_modules/decoder.py): `cdvae/pl_modules/decoder.py`
- [GemNet network](https://github.com/txie-93/cdvae/blob/main/cdvae/pl_modules/gemnet/gemnet.py): `cdvae/pl_modules/gemnet/gemnet.py`
- [Message-passing layers](https://github.com/txie-93/cdvae/tree/main/cdvae/pl_modules/gemnet/layers): `cdvae/pl_modules/gemnet/layers`
- [Element embeddings](https://github.com/txie-93/cdvae/tree/main/cdvae/pl_modules/embeddings): `cdvae/pl_modules/embeddings`

### Evaluation

- [Task evaluation](https://github.com/txie-93/cdvae/blob/main/scripts/evaluate.py): `scripts/evaluate.py`
- [Evaluation utilities](https://github.com/txie-93/cdvae/blob/main/scripts/eval_utils.py): `scripts/eval_utils.py`
- [Metric computation](https://github.com/txie-93/cdvae/blob/main/scripts/compute_metrics.py): `scripts/compute_metrics.py`
- **Evaluation artifacts**

### Other components

- **Researcher**

## Connections

- Researcher → Training entry: starts training (evidence: `README.md`)
- Training entry → Run configuration: uses configuration (evidence: `README.md`)
- Training entry → Data module: trains with data
- Crystal datasets → Data module: provides splits (evidence: `README.md`)
- Data module → Crystal datasets: instantiates (evidence: `cdvae/pl_data/datamodule.py`)
- Crystal datasets → Crystal preprocessing: preprocesses crystals (evidence: `cdvae/pl_data/dataset.py`)
- CDVAE model → Crystal preprocessing: uses crystal utilities (evidence: `cdvae/pl_modules/model.py`)
- CDVAE model → Element embeddings: uses embeddings (evidence: `cdvae/pl_modules/model.py`)
- Crystal decoder → GemNet network: uses network (evidence: `cdvae/pl_modules/decoder.py`)
- GemNet network → Message-passing layers: uses layers (evidence: `cdvae/pl_modules/gemnet/gemnet.py`)
- Message-passing layers → Element embeddings: embeds atoms (evidence: `cdvae/pl_modules/gemnet/layers/embedding_block.py`)
- Researcher → Task evaluation: selects tasks (evidence: `README.md`)
- Task evaluation → Evaluation utilities: loads evaluation helpers (evidence: `scripts/evaluate.py`)
- Evaluation utilities → Crystal datasets: builds tensor dataset (evidence: `scripts/eval_utils.py`)
- Evaluation utilities → Data module: loads data module (evidence: `scripts/eval_utils.py`)
- Evaluation utilities → CDVAE model: loads checkpoint (evidence: `scripts/eval_utils.py`)
- Task evaluation → Evaluation artifacts: writes task outputs (evidence: `README.md`)
- Researcher → Metric computation: requests metrics (evidence: `README.md`)
- Metric computation → Evaluation utilities: uses evaluation utilities (evidence: `scripts/compute_metrics.py`)
- Metric computation → Evaluation artifacts: writes metrics (evidence: `README.md`)
