# turbotage/polynode architecture

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

- Interactive diagram: https://gitdiagram.com/turbotage/polynode
- Repository: https://github.com/turbotage/polynode

## Overview

PolyNODE is a PyTorch research library for neural ODE autoencoders on variable-dimensional M-polyfolds, with reconstruction experiments and latent-space flow classification. Users run sphere or spiral reconstruction training, then evaluate learned flows; classification training can load a reconstruction model and learn class-directed latent dynamics, which can also be evaluated. Shared layers provide synthetic geometry, vector fields/ODE integration, and losses. The README documents capabilities beyond the sampled excerpts; arrows for those branches are limited to documented workflows and visible module responsibilities.

Main entry points: [`polynode/reconstruction/experiment_spiral.py`](https://github.com/turbotage/polynode/blob/main/polynode/reconstruction/experiment_spiral.py) (Spiral Training), [`polynode/reconstruction/experiment_sphere.py`](https://github.com/turbotage/polynode/blob/main/polynode/reconstruction/experiment_sphere.py) (Sphere Training), [`polynode/model_lib.py`](https://github.com/turbotage/polynode/blob/main/polynode/model_lib.py) (ODE Flow Model), [`saves/reconstruction`](https://github.com/turbotage/polynode/tree/main/saves/reconstruction) (Reconstruction Runs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_recon["Reconstruction"]
  node_spiral_train["Spiral Training"]
  node_sphere_train["Sphere Training"]
  node_recon_eval_spiral["Spiral Evaluation<br/>[evaluate_spiral.py]"]
  node_recon_eval_sphere["Sphere Evaluation<br/>[evaluate_sphere.py]"]
  node_recon_runs["Reconstruction Runs"]
end

subgraph group_shared["Model Core"]
  node_synth_data["Synthetic Geometry<br/>[data_lib.py]"]
  node_losses["Training Losses<br/>[loss_lib.py]"]
  node_vf["Polyfold Fields<br/>[model_lib.py]"]
  node_flow["ODE Flow Model<br/>[model_lib.py]"]
end

subgraph group_classify["Classification"]
  node_class_train["Spiral Classifier"]
  node_class_setup["Classifier Setup"]
  node_class_vf["Classification Fields"]
  node_class_eval["Classifier Evaluation"]
  node_class_runs["Classification Runs"]
end

subgraph group_visual["Evaluation &amp; Plots"]
  node_plotting["Live &amp; Static Plots<br/>[plotly_plot.py]"]
  node_utilities["Experiment Utilities<br/>[util_lib.py]"]
end

node_user(("Researcher"))
node_ode_solver["torchdiffeq"]

node_user -->|"runs"| node_spiral_train
node_user -->|"runs"| node_sphere_train
node_user -->|"evaluates"| node_recon_eval_spiral
node_user -->|"evaluates"| node_recon_eval_sphere
node_user -->|"runs"| node_class_train
node_user -->|"evaluates"| node_class_eval
node_spiral_train -->|"samples data"| node_synth_data
node_sphere_train -->|"samples data"| node_synth_data
node_spiral_train -->|"configures field"| node_vf
node_sphere_train -->|"configures field"| node_vf
node_spiral_train -->|"integrates"| node_flow
node_sphere_train -->|"integrates"| node_flow
node_spiral_train -->|"computes loss"| node_losses
node_sphere_train -->|"computes loss"| node_losses
node_flow -->|"evaluates field"| node_vf
node_flow -->|"integrates with"| node_ode_solver
node_spiral_train -->|"saves run"| node_recon_runs
node_sphere_train -->|"saves run"| node_recon_runs
node_recon_eval_spiral -->|"loads model"| node_recon_runs
node_recon_eval_sphere -->|"loads model"| node_recon_runs
node_recon_eval_spiral -->|"evaluates flow"| node_flow
node_recon_eval_sphere -->|"evaluates flow"| node_flow
node_recon_eval_spiral -->|"regenerates data"| node_synth_data
node_recon_eval_sphere -->|"regenerates data"| node_synth_data
node_class_train -->|"sets up"| node_class_setup
node_class_setup -->|"loads encoder"| node_recon_runs
node_class_train -->|"trains dynamics"| node_class_vf
node_class_train -->|"saves run"| node_class_runs
node_class_setup -.->|"starts dashboard"| node_plotting
node_class_eval -->|"loads model"| node_class_runs
node_class_eval -->|"loads encoder"| node_recon_runs
node_class_eval -.->|"plots trajectories"| node_plotting
node_spiral_train -->|"reports experiment"| node_utilities
node_sphere_train -->|"reports experiment"| node_utilities
node_recon_eval_spiral -->|"plots metrics"| node_utilities
node_recon_eval_sphere -->|"plots metrics"| node_utilities

click node_spiral_train "https://github.com/turbotage/polynode/blob/main/polynode/reconstruction/experiment_spiral.py"
click node_sphere_train "https://github.com/turbotage/polynode/blob/main/polynode/reconstruction/experiment_sphere.py"
click node_synth_data "https://github.com/turbotage/polynode/blob/main/polynode/data_lib.py"
click node_losses "https://github.com/turbotage/polynode/blob/main/polynode/loss_lib.py"
click node_vf "https://github.com/turbotage/polynode/blob/main/polynode/model_lib.py"
click node_flow "https://github.com/turbotage/polynode/blob/main/polynode/model_lib.py"
click node_recon_eval_spiral "https://github.com/turbotage/polynode/blob/main/polynode/reconstruction/evaluate_spiral.py"
click node_recon_eval_sphere "https://github.com/turbotage/polynode/blob/main/polynode/reconstruction/evaluate_sphere.py"
click node_recon_runs "https://github.com/turbotage/polynode/tree/main/saves/reconstruction"
click node_class_train "https://github.com/turbotage/polynode/blob/main/polynode/classification/classification_spiral.py"
click node_class_setup "https://github.com/turbotage/polynode/blob/main/polynode/classification/classification_spiral_lib.py"
click node_class_vf "https://github.com/turbotage/polynode/blob/main/polynode/classification/classification_lib.py"
click node_class_eval "https://github.com/turbotage/polynode/blob/main/polynode/classification/classification_evaluate.py"
click node_class_runs "https://github.com/turbotage/polynode/tree/main/saves/classification"
click node_plotting "https://github.com/turbotage/polynode/blob/main/polynode/plotly_plot.py"
click node_utilities "https://github.com/turbotage/polynode/blob/main/polynode/util_lib.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_spiral_train,node_sphere_train,node_recon_eval_spiral,node_recon_eval_sphere,node_recon_runs toneBlue
class node_synth_data,node_losses,node_vf,node_flow toneAmber
class node_class_train,node_class_setup,node_class_vf,node_class_eval,node_class_runs toneMint
class node_plotting,node_utilities toneRose
class node_user,node_ode_solver toneIndigo
```

## Components

### Reconstruction

- [Spiral Training](https://github.com/turbotage/polynode/blob/main/polynode/reconstruction/experiment_spiral.py): `polynode/reconstruction/experiment_spiral.py`
- [Sphere Training](https://github.com/turbotage/polynode/blob/main/polynode/reconstruction/experiment_sphere.py): `polynode/reconstruction/experiment_sphere.py`
- [Spiral Evaluation](https://github.com/turbotage/polynode/blob/main/polynode/reconstruction/evaluate_spiral.py): `polynode/reconstruction/evaluate_spiral.py`
- [Sphere Evaluation](https://github.com/turbotage/polynode/blob/main/polynode/reconstruction/evaluate_sphere.py): `polynode/reconstruction/evaluate_sphere.py`
- [Reconstruction Runs](https://github.com/turbotage/polynode/tree/main/saves/reconstruction): `saves/reconstruction`

### Model Core

- [Synthetic Geometry](https://github.com/turbotage/polynode/blob/main/polynode/data_lib.py): `polynode/data_lib.py`
- [Training Losses](https://github.com/turbotage/polynode/blob/main/polynode/loss_lib.py): `polynode/loss_lib.py`
- [Polyfold Fields](https://github.com/turbotage/polynode/blob/main/polynode/model_lib.py): `polynode/model_lib.py`
- [ODE Flow Model](https://github.com/turbotage/polynode/blob/main/polynode/model_lib.py): `polynode/model_lib.py`

### Classification

- [Spiral Classifier](https://github.com/turbotage/polynode/blob/main/polynode/classification/classification_spiral.py): `polynode/classification/classification_spiral.py`
- [Classifier Setup](https://github.com/turbotage/polynode/blob/main/polynode/classification/classification_spiral_lib.py): `polynode/classification/classification_spiral_lib.py`
- [Classification Fields](https://github.com/turbotage/polynode/blob/main/polynode/classification/classification_lib.py): `polynode/classification/classification_lib.py`
- [Classifier Evaluation](https://github.com/turbotage/polynode/blob/main/polynode/classification/classification_evaluate.py): `polynode/classification/classification_evaluate.py`
- [Classification Runs](https://github.com/turbotage/polynode/tree/main/saves/classification): `saves/classification`

### Evaluation & Plots

- [Live & Static Plots](https://github.com/turbotage/polynode/blob/main/polynode/plotly_plot.py): `polynode/plotly_plot.py`
- [Experiment Utilities](https://github.com/turbotage/polynode/blob/main/polynode/util_lib.py): `polynode/util_lib.py`

### Other components

- **Researcher**
- **torchdiffeq**

## Connections

- Researcher → Spiral Training: runs
- Researcher → Sphere Training: runs
- Researcher → Spiral Evaluation: evaluates
- Researcher → Sphere Evaluation: evaluates
- Researcher → Spiral Classifier: runs
- Researcher → Classifier Evaluation: evaluates
- Spiral Training → Synthetic Geometry: samples data
- Sphere Training → Synthetic Geometry: samples data
- Spiral Training → Polyfold Fields: configures field
- Sphere Training → Polyfold Fields: configures field
- Spiral Training → ODE Flow Model: integrates
- Sphere Training → ODE Flow Model: integrates
- Spiral Training → Training Losses: computes loss
- Sphere Training → Training Losses: computes loss
- ODE Flow Model → Polyfold Fields: evaluates field
- ODE Flow Model → torchdiffeq: integrates with
- Spiral Training → Reconstruction Runs: saves run
- Sphere Training → Reconstruction Runs: saves run
- Spiral Evaluation → Reconstruction Runs: loads model
- Sphere Evaluation → Reconstruction Runs: loads model
- Spiral Evaluation → ODE Flow Model: evaluates flow
- Sphere Evaluation → ODE Flow Model: evaluates flow
- Spiral Evaluation → Synthetic Geometry: regenerates data
- Sphere Evaluation → Synthetic Geometry: regenerates data
- Spiral Classifier → Classifier Setup: sets up
- Classifier Setup → Reconstruction Runs: loads encoder
- Spiral Classifier → Classification Fields: trains dynamics
- Spiral Classifier → Classification Runs: saves run
- Classifier Setup → Live & Static Plots: starts dashboard
- Classifier Evaluation → Classification Runs: loads model
- Classifier Evaluation → Reconstruction Runs: loads encoder
- Classifier Evaluation → Live & Static Plots: plots trajectories
- Spiral Training → Experiment Utilities: reports experiment
- Sphere Training → Experiment Utilities: reports experiment
- Spiral Evaluation → Experiment Utilities: plots metrics
- Sphere Evaluation → Experiment Utilities: plots metrics