# sundw2014/c3m architecture

> Architecture diagram of the GitHub repository sundw2014/c3m, 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/sundw2014/c3m
- Repository: https://github.com/sundw2014/c3m
- Video tour (about a minute): https://gitdiagram.com/sundw2014/c3m/video

## Overview

This repository learns contraction-metric-certified controllers for several dynamical-system tasks, then evaluates and plots closed-loop trajectories against generated references. The primary workflow is task selection and sampling, system/model construction, training with contraction constraints, checkpointing, and controller evaluation. The graph preserves the documented plotting and task-specific system capabilities; some task modules and training details were not sampled, so uncertain internal links are omitted.

Main entry points: [`main.py`](https://github.com/sundw2014/c3m/blob/master/main.py) (Training entry), [`plot.py`](https://github.com/sundw2014/c3m/blob/master/plot.py) (Evaluation runner), [`systems`](https://github.com/sundw2014/c3m/tree/master/systems) (Plant dynamics), [`np2pth.py`](https://github.com/sundw2014/c3m/blob/master/np2pth.py) (NumPy adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Controller learning"]
  node_main["Training entry<br/>[main.py]"]
  node_models["Metric and policy"]
  node_constraints["Contraction loss<br/>[main.py]"]
  node_training["Train and validate<br/>[main.py]"]
end

subgraph group_taskdefs["Task definitions"]
  node_configs["Task configuration"]
  node_systems["Plant dynamics"]
end

subgraph group_evaluation["Evaluation and plotting"]
  node_plot["Evaluation runner<br/>[plot.py]"]
  node_wrappers["NumPy adapters<br/>[np2pth.py]"]
  node_integrator["Euler integration<br/>[utils.py]"]
  node_plots["Trajectory plots<br/>[plot.py]"]
end

subgraph group_artifacts["Model artifacts"]
  node_checkpoint["Saved controller<br/>[main.py]"]
  node_aero["Aero network weights"]
end

node_user(("Engineer"))
node_torch["PyTorch"]
node_matplotlib["Matplotlib"]

node_user -->|"selects task"| node_main
node_main -->|"loads bounds"| node_configs
node_main -->|"loads dynamics"| node_systems
node_main -->|"builds networks"| node_models
node_main -->|"runs epochs"| node_training
node_training -->|"computes loss"| node_constraints
node_constraints -->|"evaluates metric"| node_models
node_constraints -->|"evaluates plant"| node_systems
node_training -->|"saves best"| node_checkpoint
node_user -->|"requests evaluation"| node_plot
node_plot -->|"creates reference"| node_configs
node_plot -->|"loads adapters"| node_wrappers
node_plot -->|"integrates trajectories"| node_integrator
node_wrappers -->|"calls dynamics"| node_systems
node_wrappers -->|"loads policy"| node_checkpoint
node_integrator -->|"queries control"| node_wrappers
node_integrator -->|"steps plant"| node_systems
node_plot -->|"renders results"| node_plots
node_plots -->|"draws figures"| node_matplotlib
node_systems -.->|"loads weights"| node_aero
node_main -->|"trains models"| node_torch

click node_main "https://github.com/sundw2014/c3m/blob/master/main.py"
click node_configs "https://github.com/sundw2014/c3m/tree/master/configs"
click node_systems "https://github.com/sundw2014/c3m/tree/master/systems"
click node_models "https://github.com/sundw2014/c3m/tree/master/models"
click node_constraints "https://github.com/sundw2014/c3m/blob/master/main.py"
click node_training "https://github.com/sundw2014/c3m/blob/master/main.py"
click node_checkpoint "https://github.com/sundw2014/c3m/blob/master/main.py"
click node_plot "https://github.com/sundw2014/c3m/blob/master/plot.py"
click node_wrappers "https://github.com/sundw2014/c3m/blob/master/np2pth.py"
click node_integrator "https://github.com/sundw2014/c3m/blob/master/utils.py"
click node_plots "https://github.com/sundw2014/c3m/blob/master/plot.py"
click node_aero "https://github.com/sundw2014/c3m/blob/master/data/Fa_net_12_3_full_Lip16.pth"

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_main,node_models,node_constraints,node_training toneBlue
class node_configs,node_systems toneAmber
class node_plot,node_wrappers,node_integrator,node_plots toneMint
class node_checkpoint,node_aero toneRose
class node_user,node_torch,node_matplotlib toneIndigo
```

## Components

### Controller learning

- [Training entry](https://github.com/sundw2014/c3m/blob/master/main.py): `main.py`
- [Metric and policy](https://github.com/sundw2014/c3m/tree/master/models): `models`
- [Contraction loss](https://github.com/sundw2014/c3m/blob/master/main.py): `main.py`
- [Train and validate](https://github.com/sundw2014/c3m/blob/master/main.py): `main.py`

### Task definitions

- [Task configuration](https://github.com/sundw2014/c3m/tree/master/configs): `configs`
- [Plant dynamics](https://github.com/sundw2014/c3m/tree/master/systems): `systems`

### Evaluation and plotting

- [Evaluation runner](https://github.com/sundw2014/c3m/blob/master/plot.py): `plot.py`
- [NumPy adapters](https://github.com/sundw2014/c3m/blob/master/np2pth.py): `np2pth.py`
- [Euler integration](https://github.com/sundw2014/c3m/blob/master/utils.py): `utils.py`
- [Trajectory plots](https://github.com/sundw2014/c3m/blob/master/plot.py): `plot.py`

### Model artifacts

- [Saved controller](https://github.com/sundw2014/c3m/blob/master/main.py): `main.py`
- [Aero network weights](https://github.com/sundw2014/c3m/blob/master/data/Fa_net_12_3_full_Lip16.pth): `data/Fa_net_12_3_full_Lip16.pth`

### Other components

- **Engineer**
- **PyTorch**
- **Matplotlib**

## Connections

- Engineer → Training entry: selects task
- Training entry → Task configuration: loads bounds
- Training entry → Plant dynamics: loads dynamics
- Training entry → Metric and policy: builds networks
- Training entry → Train and validate: runs epochs
- Train and validate → Contraction loss: computes loss
- Contraction loss → Metric and policy: evaluates metric
- Contraction loss → Plant dynamics: evaluates plant
- Train and validate → Saved controller: saves best
- Engineer → Evaluation runner: requests evaluation
- Evaluation runner → Task configuration: creates reference
- Evaluation runner → NumPy adapters: loads adapters
- Evaluation runner → Euler integration: integrates trajectories
- NumPy adapters → Plant dynamics: calls dynamics
- NumPy adapters → Saved controller: loads policy
- Euler integration → NumPy adapters: queries control
- Euler integration → Plant dynamics: steps plant
- Evaluation runner → Trajectory plots: renders results
- Trajectory plots → Matplotlib: draws figures
- Plant dynamics → Aero network weights: loads weights
- Training entry → PyTorch: trains models