# sparkdroidwastaken/cartpole-tda architecture

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

- Interactive diagram: https://gitdiagram.com/sparkdroidwastaken/cartpole-tda
- Repository: https://github.com/sparkdroidwastaken/cartpole-tda

## Overview

This repository is a CartPole reinforcement-learning comparison: JavaScript implements regular and symmetry-informed DQN agents, while Python analyzes run performance and policy topology. The documented workflow trains agents in the CartPole environment, uses a custom neural network, then evaluates rewards and applies persistent-homology analysis to state/action batches. The simulation HTML is present in the tree but was not excerpted, so its internal control flow and data wiring cannot be verified; the analysis scripts were only partially excerpted.

Main entry points: [`Simulation/Cartpole geo.html`](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/Cartpole%20geo.html) (CartPole environment), [`Analysis/TDA Analysis.py`](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Analysis/TDA%20Analysis.py) (State/action batches), [`Simulation/NeuralNetwork.js`](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/NeuralNetwork.js) (Neural network), [`Analysis/Analysis.py`](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Analysis/Analysis.py) (Performance statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["CartPole simulation"]
  node_cartpole["CartPole environment<br/>[Cartpole geo.html]"]
  node_dqn["DQN agents<br/>[Cartpole geo.html]"]
  node_geometric["Mirror augmentation<br/>[Cartpole geo.html]"]
  node_network["Neural network<br/>[NeuralNetwork.js]"]
  node_visualization["Canvas visualization<br/>[Cartpole geo.html]"]
end

subgraph group_analysis["Results analysis"]
  node_performance["Performance statistics<br/>[Analysis.py]"]
end

subgraph group_tda["Topology analysis"]
  node_batch_data["State/action batches<br/>[TDA Analysis.py]"]
  node_persistent_homology["Persistent homology<br/>[TDA Analysis.py]"]
  node_topology_comparison["Topology comparisons<br/>[TDA Analysis.py]"]
end

node_researcher(("Researcher"))
node_run_data["Run data"]

node_researcher -.->|"runs experiment"| node_cartpole
node_dqn -.->|"acts in"| node_cartpole
node_dqn -.->|"uses network"| node_network
node_geometric -.->|"augments learning"| node_dqn
node_cartpole -.->|"visualizes on canvas"| node_visualization
node_cartpole -.->|"produces runs"| node_run_data
node_run_data -.->|"analyzes rewards"| node_performance
node_run_data -.->|"provides batches"| node_batch_data
node_batch_data -->|"computes signatures"| node_persistent_homology
node_persistent_homology -->|"compares diagrams"| node_topology_comparison

click node_cartpole "https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/Cartpole%20geo.html"
click node_dqn "https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/Cartpole%20geo.html"
click node_geometric "https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/Cartpole%20geo.html"
click node_network "https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/NeuralNetwork.js"
click node_visualization "https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/Cartpole%20geo.html"
click node_performance "https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Analysis/Analysis.py"
click node_batch_data "https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Analysis/TDA%20Analysis.py"
click node_persistent_homology "https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Analysis/TDA%20Analysis.py"
click node_topology_comparison "https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Analysis/TDA%20Analysis.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_cartpole,node_dqn,node_geometric,node_network,node_visualization toneBlue
class node_performance toneAmber
class node_batch_data,node_persistent_homology,node_topology_comparison toneMint
class node_researcher,node_run_data toneIndigo
```

## Components

### CartPole simulation

- [CartPole environment](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/Cartpole%20geo.html): `Simulation/Cartpole geo.html`
- [DQN agents](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/Cartpole%20geo.html): `Simulation/Cartpole geo.html`
- [Mirror augmentation](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/Cartpole%20geo.html): `Simulation/Cartpole geo.html`
- [Neural network](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/NeuralNetwork.js): `Simulation/NeuralNetwork.js`
- [Canvas visualization](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Simulation/Cartpole%20geo.html): `Simulation/Cartpole geo.html`

### Results analysis

- [Performance statistics](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Analysis/Analysis.py): `Analysis/Analysis.py`

### Topology analysis

- [State/action batches](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Analysis/TDA%20Analysis.py): `Analysis/TDA Analysis.py`
- [Persistent homology](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Analysis/TDA%20Analysis.py): `Analysis/TDA Analysis.py`
- [Topology comparisons](https://github.com/sparkdroidwastaken/cartpole-tda/blob/main/Analysis/TDA%20Analysis.py): `Analysis/TDA Analysis.py`

### Other components

- **Researcher**
- **Run data**

## Connections

- Researcher → CartPole environment: runs experiment (evidence: `README.md`)
- DQN agents → CartPole environment: acts in (evidence: `README.md`)
- DQN agents → Neural network: uses network (evidence: `README.md`)
- Mirror augmentation → DQN agents: augments learning (evidence: `README.md`)
- CartPole environment → Canvas visualization: visualizes on canvas (evidence: `README.md`)
- CartPole environment → Run data: produces runs (evidence: `README.md`)
- Run data → Performance statistics: analyzes rewards (evidence: `README.md`)
- Run data → State/action batches: provides batches (evidence: `Analysis/TDA Analysis.py`)
- State/action batches → Persistent homology: computes signatures (evidence: `Analysis/TDA Analysis.py`)
- Persistent homology → Topology comparisons: compares diagrams (evidence: `Analysis/TDA Analysis.py`)