# kjkoster/stability-preserving-pid-autotuner architecture

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

- Interactive diagram: https://gitdiagram.com/kjkoster/stability-preserving-pid-autotuner
- Repository: https://github.com/kjkoster/stability-preserving-pid-autotuner

## Overview

This repository is an experimental stability-preserving PID auto-tuner for a simulated or hardware plant. Its main workflow proposes PID gains, runs a supervised control episode, evaluates the episode, and feeds the result back to the learner. The README also emphasizes conventional plant control and fallback supervision as distinct stages. The graph reflects sampled runtime code and documented design; some internals and optional integrations are described at directory or module level where source excerpts were incomplete.

Main entry points: [`autotuning_supervised_plant_control.py`](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/autotuning_supervised_plant_control.py) (Auto-tuning Driver), [`ddpg_torch.py`](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/ddpg_torch.py) (DDPG Agent), [`plant_control.py`](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/plant_control.py) (Plant Control Loop), [`supervised_plant_control.py`](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/supervised_plant_control.py) (Stability Supervisor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Plant Control"]
  node_supervisor["Stability Supervisor"]
  node_plantcontrol["Plant Control Loop<br/>[plant_control.py]"]
  node_pid["PID Controller<br/>[plant_control.py]"]
  node_plant["Simulated Or Hardware Plant<br/>[plant_control.py]"]
end

subgraph group_learning["Tuning And Learning"]
  node_autotune["Auto-tuning Driver"]
  node_randomtune["Random Tuner"]
  node_agent["DDPG Agent<br/>[ddpg_torch.py]"]
  node_actor["Actor Network<br/>[ddpg_torch.py]"]
  node_critic["Critic Network<br/>[ddpg_torch.py]"]
  node_replay["Replay Buffer<br/>[ddpg_torch.py]"]
end

subgraph group_episode["Episode Data"]
  node_episode["Episode Utilities<br/>[episodes.py]"]
  node_episodefile[("Episode Files")]
end

subgraph group_analysis["Results Analysis"]
  node_plotter["Learning Plotter<br/>[plot_learning.py]"]
end

node_engineer(("Engineer"))
node_tclab["TCLab Interface"]
node_operator(("Human Operator"))

node_engineer -->|"starts training"| node_autotune
node_autotune -->|"runs episodes"| node_supervisor
node_autotune -->|"chooses gains"| node_agent
node_autotune -->|"records reward"| node_agent
node_autotune -->|"saves episode"| node_episode
node_autotune -->|"scales actions"| node_actor
node_agent -->|"predicts actions"| node_actor
node_agent -->|"updates values"| node_critic
node_agent -->|"stores transitions"| node_replay
node_agent -->|"samples transitions"| node_replay
node_supervisor -->|"steps plant"| node_plantcontrol
node_supervisor -->|"sets fallback gains"| node_plantcontrol
node_plantcontrol -->|"computes control"| node_pid
node_plantcontrol -->|"applies output"| node_plant
node_plant -->|"returns measurements"| node_plantcontrol
node_plant -.->|"uses interface"| node_tclab
node_operator -->|"runs control"| node_plantcontrol
node_randomtune -->|"runs episodes"| node_supervisor
node_randomtune -->|"saves episode"| node_episode
node_episode -->|"writes episode"| node_episodefile
node_engineer -->|"analyzes runs"| node_plotter
node_plotter -->|"reads episodes"| node_episodefile

click node_autotune "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/autotuning_supervised_plant_control.py"
click node_randomtune "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/random_but_stable_pid_autotuner.py"
click node_agent "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/ddpg_torch.py"
click node_actor "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/ddpg_torch.py"
click node_critic "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/ddpg_torch.py"
click node_replay "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/ddpg_torch.py"
click node_supervisor "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/supervised_plant_control.py"
click node_plantcontrol "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/plant_control.py"
click node_pid "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/plant_control.py"
click node_plant "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/plant_control.py"
click node_episode "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/episodes.py"
click node_plotter "https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/plot_learning.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_supervisor,node_plantcontrol,node_pid,node_plant toneBlue
class node_autotune,node_randomtune,node_agent,node_actor,node_critic,node_replay toneAmber
class node_episode,node_episodefile toneMint
class node_plotter toneRose
class node_engineer,node_tclab,node_operator toneIndigo
```

## Components

### Plant Control

- [Stability Supervisor](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/supervised_plant_control.py): `supervised_plant_control.py`
- [Plant Control Loop](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/plant_control.py): `plant_control.py`
- [PID Controller](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/plant_control.py): `plant_control.py`
- [Simulated Or Hardware Plant](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/plant_control.py): `plant_control.py`

### Tuning And Learning

- [Auto-tuning Driver](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/autotuning_supervised_plant_control.py): `autotuning_supervised_plant_control.py`
- [Random Tuner](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/random_but_stable_pid_autotuner.py): `random_but_stable_pid_autotuner.py`
- [DDPG Agent](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/ddpg_torch.py): `ddpg_torch.py`
- [Actor Network](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/ddpg_torch.py): `ddpg_torch.py`
- [Critic Network](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/ddpg_torch.py): `ddpg_torch.py`
- [Replay Buffer](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/ddpg_torch.py): `ddpg_torch.py`

### Episode Data

- [Episode Utilities](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/episodes.py): `episodes.py`
- **Episode Files**

### Results Analysis

- [Learning Plotter](https://github.com/kjkoster/stability-preserving-pid-autotuner/blob/master/plot_learning.py): `plot_learning.py`

### Other components

- **Engineer**
- **TCLab Interface**
- **Human Operator**

## Connections

- Engineer → Auto-tuning Driver: starts training
- Auto-tuning Driver → Stability Supervisor: runs episodes
- Auto-tuning Driver → DDPG Agent: chooses gains
- Auto-tuning Driver → DDPG Agent: records reward
- Auto-tuning Driver → Episode Utilities: saves episode
- Auto-tuning Driver → Actor Network: scales actions
- DDPG Agent → Actor Network: predicts actions
- DDPG Agent → Critic Network: updates values
- DDPG Agent → Replay Buffer: stores transitions
- DDPG Agent → Replay Buffer: samples transitions
- Stability Supervisor → Plant Control Loop: steps plant
- Stability Supervisor → Plant Control Loop: sets fallback gains
- Plant Control Loop → PID Controller: computes control
- Plant Control Loop → Simulated Or Hardware Plant: applies output
- Simulated Or Hardware Plant → Plant Control Loop: returns measurements
- Simulated Or Hardware Plant → TCLab Interface: uses interface
- Human Operator → Plant Control Loop: runs control
- Random Tuner → Stability Supervisor: runs episodes
- Random Tuner → Episode Utilities: saves episode
- Episode Utilities → Episode Files: writes episode
- Engineer → Learning Plotter: analyzes runs
- Learning Plotter → Episode Files: reads episodes