# zhtmgxr/generative-face-modeling architecture

> Architecture diagram of the GitHub repository zhtmgxr/generative-face-modeling, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhtmgxr/generative-face-modeling
- Repository: https://github.com/zhtmgxr/generative-face-modeling

## Overview

This is a PyTorch research package comparing VAE, GAN, and hybrid VAE-GAN face generation on CelebA. Its main workflow loads configured CelebA images, trains the selected model with its corresponding objectives, and saves checkpoints and generated samples; separate commands evaluate generated images and analyze VAE latent attribute directions. The training excerpt is partial, so the graph omits uncertain internal wiring beyond the calls shown and documented capabilities.

Main entry points: [`src/facegen/train.py`](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/train.py) (Training entry), [`src/facegen/evaluate.py`](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/evaluate.py) (Evaluation command), [`src/facegen/latent_analysis.py`](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/latent_analysis.py) (Latent analysis), [`src/facegen/utils.py`](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/utils.py) (Experiment utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training"]
  node_train["Training entry<br/>[train.py]"]
end

subgraph group_models["Models and objectives"]
  node_models["Model components<br/>[models.py]"]
  node_losses["Training objectives<br/>[losses.py]"]
end

subgraph group_data["Data and configuration"]
  node_config["Config loader<br/>[config.py]"]
  node_celeba["CelebA loader<br/>[data.py]"]
end

subgraph group_analysis["Evaluation and latent analysis"]
  node_evaluate["Evaluation command<br/>[evaluate.py]"]
  node_inception["Inception Score<br/>[evaluate.py]"]
  node_laplacian["Laplacian Variance<br/>[evaluate.py]"]
  node_latent["Latent analysis<br/>[latent_analysis.py]"]
  node_traversal["Attribute traversal<br/>[latent_analysis.py]"]
end

subgraph group_persistence["Experiment outputs"]
  node_utils["Experiment utilities<br/>[utils.py]"]
  node_checkpoints[("Checkpoints")]
  node_samples["Generated samples"]
  node_metrics["Training metrics"]
  node_evaluation_results["Evaluation results"]
  node_traversal_image["Traversal image"]
end

node_researcher(("Researcher"))
node_dataset[("CelebA dataset")]

node_researcher -->|"selects model"| node_train
node_train -->|"loads settings"| node_config
node_train -->|"builds loader"| node_celeba
node_celeba -->|"loads and transforms"| node_dataset
node_train -->|"constructs and trains"| node_models
node_train -->|"computes objectives"| node_losses
node_train -->|"records outputs"| node_utils
node_utils -->|"writes"| node_checkpoints
node_utils -->|"writes"| node_samples
node_utils -->|"writes"| node_metrics
node_researcher -->|"requests evaluation"| node_evaluate
node_evaluate -->|"loads"| node_checkpoints
node_evaluate -->|"loads and samples"| node_models
node_evaluate -->|"computes"| node_inception
node_evaluate -->|"computes"| node_laplacian
node_evaluate -->|"writes"| node_evaluation_results
node_researcher -->|"requests traversal"| node_latent
node_latent -->|"loads settings"| node_config
node_latent -->|"builds loader"| node_celeba
node_latent -->|"loads"| node_checkpoints
node_latent -->|"encodes examples"| node_models
node_latent -->|"estimates direction and renders"| node_traversal
node_traversal -->|"writes"| node_traversal_image

click node_train "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/train.py"
click node_config "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/config.py"
click node_celeba "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/data.py"
click node_models "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/models.py"
click node_losses "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/losses.py"
click node_utils "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/utils.py"
click node_evaluate "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/evaluate.py"
click node_inception "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/evaluate.py"
click node_laplacian "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/evaluate.py"
click node_latent "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/latent_analysis.py"
click node_traversal "https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/latent_analysis.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_train toneBlue
class node_models,node_losses,node_dataset toneAmber
class node_config,node_celeba toneMint
class node_evaluate,node_inception,node_laplacian,node_latent,node_traversal toneRose
class node_utils,node_checkpoints,node_samples,node_metrics,node_evaluation_results,node_traversal_image,node_researcher toneIndigo
```

## Components

### Training

- [Training entry](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/train.py): `src/facegen/train.py`

### Models and objectives

- [Model components](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/models.py): `src/facegen/models.py`
- [Training objectives](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/losses.py): `src/facegen/losses.py`

### Data and configuration

- [Config loader](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/config.py): `src/facegen/config.py`
- [CelebA loader](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/data.py): `src/facegen/data.py`

### Evaluation and latent analysis

- [Evaluation command](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/evaluate.py): `src/facegen/evaluate.py`
- [Inception Score](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/evaluate.py): `src/facegen/evaluate.py`
- [Laplacian Variance](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/evaluate.py): `src/facegen/evaluate.py`
- [Latent analysis](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/latent_analysis.py): `src/facegen/latent_analysis.py`
- [Attribute traversal](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/latent_analysis.py): `src/facegen/latent_analysis.py`

### Experiment outputs

- [Experiment utilities](https://github.com/zhtmgxr/generative-face-modeling/blob/main/src/facegen/utils.py): `src/facegen/utils.py`
- **Checkpoints**
- **Generated samples**
- **Training metrics**
- **Evaluation results**
- **Traversal image**

### Other components

- **Researcher**
- **CelebA dataset**

## Connections

- Researcher → Training entry: selects model
- Training entry → Config loader: loads settings
- Training entry → CelebA loader: builds loader
- CelebA loader → CelebA dataset: loads and transforms
- Training entry → Model components: constructs and trains
- Training entry → Training objectives: computes objectives
- Training entry → Experiment utilities: records outputs
- Experiment utilities → Checkpoints: writes
- Experiment utilities → Generated samples: writes
- Experiment utilities → Training metrics: writes
- Researcher → Evaluation command: requests evaluation
- Evaluation command → Checkpoints: loads
- Evaluation command → Model components: loads and samples
- Evaluation command → Inception Score: computes
- Evaluation command → Laplacian Variance: computes
- Evaluation command → Evaluation results: writes
- Researcher → Latent analysis: requests traversal
- Latent analysis → Config loader: loads settings
- Latent analysis → CelebA loader: builds loader
- Latent analysis → Checkpoints: loads
- Latent analysis → Model components: encodes examples
- Latent analysis → Attribute traversal: estimates direction and renders
- Attribute traversal → Traversal image: writes