# sparkdroidwastaken/dqn-geometry-steering architecture

> Architecture diagram of the GitHub repository sparkdroidwastaken/dqn-geometry-steering, 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/dqn-geometry-steering
- Repository: https://github.com/sparkdroidwastaken/dqn-geometry-steering

## Overview

This repository is a CartPole DQN interpretability project: it trains and runs an agent, steers its hidden activations, and studies the resulting representation geometry. The documented workflow proceeds from browser-based training through state collection and steering to geometric analysis and visualization. The tree includes analysis scripts and data, but not every artifact named in the README; the graph therefore uses only paths present in the tree. Some relationships are documented in the README rather than visible in the sampled source.

Main entry points: [`Data/states.zip`](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/states.zip) (Trajectory data), [`Analysis/GetSteeringVector.py`](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/GetSteeringVector.py) (Vector calculation), [`Analysis/CartpoleSteering.html`](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/CartpoleSteering.html) (Steered inference), [`Analysis/GeometryAnalysis.py`](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/GeometryAnalysis.py) (Geometry findings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent workflow"]
  node_training["DQN training"]
  node_collection["State collection"]
  node_episodes[("Trajectory data<br/>[states.zip]")]
end

subgraph group_steering["Activation steering"]
  node_inference["Steered inference"]
  node_vector_calc["Vector calculation"]
  node_vector_idn["Identity vector"]
  node_vector_relu["ReLU vector<br/>[v_linear_relu.json]"]
  node_vector_tanh["Tanh vector<br/>[v_linear_tanh.json]"]
  node_vector_sigmoid["Sigmoid vector"]
end

subgraph group_geometry["Geometry analysis"]
  node_geometry_calc["Trajectory geometry"]
  node_comparison["Steering comparison"]
end

subgraph group_results["Results and visualization"]
  node_visualization["Manifold visualizer<br/>[Visualisation.py]"]
  node_geometry_report["Geometry findings"]
end

node_researcher(("Researcher"))

node_researcher -->|"trains agent"| node_training
node_training -->|"exports policy"| node_collection
node_collection -->|"collects states"| node_episodes
node_episodes -->|"provides states"| node_vector_calc
node_vector_calc -.->|"computes vector"| node_vector_idn
node_vector_calc -->|"computes vector"| node_vector_relu
node_vector_calc -.->|"computes vector"| node_vector_tanh
node_vector_calc -.->|"computes vector"| node_vector_sigmoid
node_vector_idn -.->|"steers activations"| node_inference
node_vector_relu -->|"steers activations"| node_inference
node_vector_tanh -.->|"steers activations"| node_inference
node_vector_sigmoid -.->|"steers activations"| node_inference
node_inference -->|"produces trajectories"| node_episodes
node_episodes -->|"supplies trajectories"| node_geometry_calc
node_episodes -->|"supplies episode data"| node_comparison
node_geometry_calc -->|"computes metrics"| node_geometry_report
node_comparison -->|"compares metrics"| node_geometry_report
node_episodes -.->|"visualizes trajectories"| node_visualization
node_geometry_report -->|"shows metrics"| node_visualization
node_researcher -->|"explores manifolds"| node_visualization

click node_training "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/CartpoleManifold.html"
click node_collection "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/CartpoleStateCollecter.html"
click node_episodes "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/states.zip"
click node_inference "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/CartpoleSteering.html"
click node_vector_calc "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/GetSteeringVector.py"
click node_vector_idn "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/v_linear_idn"
click node_vector_relu "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/v_linear_relu.json"
click node_vector_tanh "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/v_linear_tanh.json"
click node_vector_sigmoid "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/v_linear_sigmoid.json"
click node_geometry_calc "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/GeometryAnalysis.py"
click node_comparison "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/SteeringAnalysis.py"
click node_visualization "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/Visualisation.py"
click node_geometry_report "https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/GeometryAnalysis.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_training,node_collection,node_episodes toneBlue
class node_inference,node_vector_calc,node_vector_idn,node_vector_relu,node_vector_tanh,node_vector_sigmoid toneAmber
class node_geometry_calc,node_comparison toneMint
class node_visualization,node_geometry_report toneRose
class node_researcher toneIndigo
```

## Components

### Agent workflow

- [DQN training](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/CartpoleManifold.html): `Analysis/CartpoleManifold.html`
- [State collection](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/CartpoleStateCollecter.html): `Analysis/CartpoleStateCollecter.html`
- [Trajectory data](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/states.zip): `Data/states.zip`

### Activation steering

- [Steered inference](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/CartpoleSteering.html): `Analysis/CartpoleSteering.html`
- [Vector calculation](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/GetSteeringVector.py): `Analysis/GetSteeringVector.py`
- [Identity vector](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/v_linear_idn): `Data/v_linear_idn`
- [ReLU vector](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/v_linear_relu.json): `Data/v_linear_relu.json`
- [Tanh vector](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/v_linear_tanh.json): `Data/v_linear_tanh.json`
- [Sigmoid vector](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Data/v_linear_sigmoid.json): `Data/v_linear_sigmoid.json`

### Geometry analysis

- [Trajectory geometry](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/GeometryAnalysis.py): `Analysis/GeometryAnalysis.py`
- [Steering comparison](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/SteeringAnalysis.py): `Analysis/SteeringAnalysis.py`

### Results and visualization

- [Manifold visualizer](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/Visualisation.py): `Analysis/Visualisation.py`
- [Geometry findings](https://github.com/sparkdroidwastaken/dqn-geometry-steering/blob/main/Analysis/GeometryAnalysis.py): `Analysis/GeometryAnalysis.py`

### Other components

- **Researcher**

## Connections

- Researcher → DQN training: trains agent (evidence: `README.md`)
- DQN training → State collection: exports policy (evidence: `README.md`)
- State collection → Trajectory data: collects states (evidence: `README.md`)
- Trajectory data → Vector calculation: provides states (evidence: `Analysis/GetSteeringVector.py`)
- Vector calculation → Identity vector: computes vector
- Vector calculation → ReLU vector: computes vector (evidence: `Analysis/GetSteeringVector.py`)
- Vector calculation → Tanh vector: computes vector
- Vector calculation → Sigmoid vector: computes vector
- Identity vector → Steered inference: steers activations
- ReLU vector → Steered inference: steers activations (evidence: `README.md`)
- Tanh vector → Steered inference: steers activations
- Sigmoid vector → Steered inference: steers activations
- Steered inference → Trajectory data: produces trajectories (evidence: `README.md`)
- Trajectory data → Trajectory geometry: supplies trajectories (evidence: `Analysis/GeometryAnalysis.py`)
- Trajectory data → Steering comparison: supplies episode data (evidence: `Analysis/SteeringAnalysis.py`)
- Trajectory geometry → Geometry findings: computes metrics (evidence: `Analysis/GeometryAnalysis.py`)
- Steering comparison → Geometry findings: compares metrics (evidence: `README.md`)
- Trajectory data → Manifold visualizer: visualizes trajectories
- Geometry findings → Manifold visualizer: shows metrics (evidence: `Analysis/Visualisation.py`)
- Researcher → Manifold visualizer: explores manifolds (evidence: `README.md`)