# skakim/arm architecture

> Architecture diagram of the GitHub repository skakim/arm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skakim/arm
- Repository: https://github.com/skakim/arm

## Overview

##### Project Type and Purpose
- This is a scientific/simulation application written in Python.
- Purpose: simulate a robotic arm catching a launched ball, compute joint angles via inverse kinematics, guide the motion using a combination of AI (regression models) and analytic functions, generate datasets, run experiments, and produce graphical analyses.

##### Main Architectural Components
A. Domain Model
- Arm.py – encapsulates the robotic arm’s geometry, joint definitions, forward/inverse kinematics.
- Ball.py – represents the projectile, its trajectory under physics.
B. Simulation Engine
- Simulation.py – orchestrates a simulated “launch‐and‐catch” scenario, instantiates Arm and Ball, steps through time, applies control inputs.
C. AI Controller / Trajectory Planner
- The “combined AI + function” logic lives inside DatasetGenerator.py (for generating training examples) and within Simulation.py or a helper module—using regression weights to determine joint‐trajectory deviations.
D. Data Management
- DatasetGenerator.py – runs batches of simulated catches to emit CSV files under CSVs/Regression1 and CSVs/Regression2.
- CSV storage – raw training sets, trajectory deltas, friction variations, and final regression weights.
E. Experiment Runner
- ExamplesExperiment.py – consumes CSV data, fits regression models (e.g., Fourier series, w0–w6 weights), evaluates error metrics, writes result CSVs (allerrors_*.csv).
F. Visualization Module
- Graficos/ – folder of generated plots (boxplots, Fourier coefficient charts, weight variation graphs).
- Potentially scripts or notebook code (not shown) that read the result CSVs and render PNGs or interactive charts.
G. Configuration & Utilities
- TODO.txt – lists outstanding tasks.
- README.md – project overview and usage instructions.

##### Relationships and Data Flows
- The Simulation Engine pulls in the Domain Model and the AI Controller.
→ Simulation outputs raw trajectories & joint‐angle deltas to CSV.
- Dataset Generator may wrap Simulation Engine to produce large training datasets.
→ DatasetGenerator writes CSV files grouped by scenario (Regression1, Regression2).
- Experiment Runner reads those CSVs, applies regression algorithms (scikit-learn, NumPy/SciPy), computes weights and error statistics, then writes summary CSVs.
- Visualization Module reads experiment CSV outputs, generates charts under Graficos/.

##### Architectural Patterns & Principles
- Modular Separation: domain objects (Arm, Ball) are decoupled from control logic (AI) and from I/O (CSV read/write).
- Single Responsibility: each script/module owns a distinct concern (simulation, data gen, experiment, plotting).

f. Off to one side, show DatasetGenerator.py connecting to Simulation and Storage to emphasize bulk data creation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Domain Layer
    subgraph "Core Domain"
        Arm["Arm.py\n(Geometry & Kinematics)"]:::domain
        Ball["Ball.py\n(Trajectory Physics)"]:::domain
    end

    %% Simulation & Control Layer
    subgraph "Simulation & Control"
        Sim["Simulation.py\n(Launch‐and‐Catch & AI hooks)"]:::simulation
        Dataset["DatasetGenerator.py\n(Data Gen & Regression Logic)"]:::simulation
    end

    %% Data Storage Layer
    subgraph "Data Storage"
        Storage1[(CSV Storage)]:::storage
        subgraph "Regression1 CSVs"
            R1["CSVs/Regression1"]:::storage
        end
        subgraph "Regression2 CSVs"
            R2["CSVs/Regression2"]:::storage
        end
    end

    %% Experiment/Evaluation Layer
    subgraph "Experiment/Evaluation"
        Exper["ExamplesExperiment.py\n(Regression & Error Eval)"]:::experiment
        ExpOut[(Result CSVs)]:::experiment
    end

    %% Visualization Layer
    subgraph "Visualization"
        Viz["Graficos/"]:::viz
    end

    %% Configuration & Utilities
    subgraph "Config & Utilities"
        README["README.md"]:::util
        TODO["TODO.txt"]:::util
        IDEA[".idea/"]:::util
    end

    %% External Libraries
    NumPy["NumPy"]:::extlib
    Pandas["Pandas"]:::extlib
    SciPy["SciPy"]:::extlib
    SKL["scikit-learn"]:::extlib
    Matplotlib["Matplotlib"]:::extlib

    %% Connections
    Arm -->|"calls forward/inverse kinematics"| Sim
    Ball -->|"provides trajectory"| Sim
    Sim -->|"writes raw trajectory & deltas"| Storage1
    Dataset -->|"wraps Simulation\nwrites bulk CSVs"| Storage1
    Storage1 --> R1
    Storage1 --> R2
    R1 -->|"reads training sets"| Exper
    R2 -->|"reads training sets"| Exper
    Exper -->|"writes summary CSVs"| ExpOut
    ExpOut -->|"reads result CSVs"| Viz

    %% Libraries usage
    Sim --- NumPy
    Sim --- Pandas
    Sim --- SciPy
    Exper --- SKL
    Exper --- NumPy
    Exper --- Pandas
    Viz --- Matplotlib

    %% Click Events
    click Arm "https://github.com/skakim/arm/blob/master/Arm.py"
    click Ball "https://github.com/skakim/arm/blob/master/Ball.py"
    click Sim "https://github.com/skakim/arm/blob/master/Simulation.py"
    click Dataset "https://github.com/skakim/arm/blob/master/DatasetGenerator.py"
    click R1 "https://github.com/skakim/arm/tree/master/CSVs/Regression1"
    click R2 "https://github.com/skakim/arm/tree/master/CSVs/Regression2"
    click Exper "https://github.com/skakim/arm/blob/master/ExamplesExperiment.py"
    click ExpOut "https://github.com/skakim/arm/blob/master/allerrors_experiment_results_ratios_only.csv"
    click Viz "https://github.com/skakim/arm/tree/master/Graficos/"

    %% Styles
    classDef domain fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef simulation fill:#d4edda,stroke:#333,stroke-width:1px
    classDef storage fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef experiment fill:#fce5cd,stroke:#333,stroke-width:1px
    classDef viz fill:#e2e3f3,stroke:#333,stroke-width:1px
    classDef util fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef extlib fill:#f0f0f0,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2
```
