# amghalcyon/mech_rl architecture

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

- Interactive diagram: https://gitdiagram.com/amghalcyon/mech_rl
- Repository: https://github.com/amghalcyon/mech_rl

## Overview

Mech_RL trains PPO policies for energy-aware torque control of a 2-DOF planar arm, then evaluates performance and robustness. The principal path is configured training → simulated control episodes → saved policy → evaluation and visualizations; a standalone benchmark compares baseline controllers. Unsampled subsystem wiring is included only where README documentation supports the capability, so some internal relationships are intentionally not drawn.

Main entry points: [`src/mech_rl/environment/robot_env.py`](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/environment/robot_env.py) (Gym arm environment), [`src/mech_rl/training/train.py`](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/training/train.py) (PPO training), [`src/mech_rl/evaluation/final_eval.py`](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/evaluation/final_eval.py) (Final evaluation), [`src/mech_rl/evaluation/baseline_benchmark.py`](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/evaluation/baseline_benchmark.py) (Baseline benchmark)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Training and control"]
  node_train["PPO training<br/>[train.py]"]
  node_ppo["PPO policy"]
  node_baseline["Baseline benchmark"]
end

subgraph group_simulation["Arm simulation"]
  node_env["Gym arm environment<br/>[robot_env.py]"]
  node_state["Robot state<br/>[state.py]"]
  node_kinematics["Forward kinematics<br/>[kinematics.py]"]
  node_integrator["Time integrators<br/>[integrator.py]"]
  node_dynamics["Arm dynamics<br/>[dynamics.py]"]
  node_reward["Reward calculation"]
end

subgraph group_evaluation["Evaluation and analysis"]
  node_eval["Evaluation loop<br/>[eval_loop.py]"]
  node_finaleval["Final evaluation<br/>[final_eval.py]"]
  node_visualization["Plots and policy video"]
  node_benchmark["Baseline comparison"]
  node_results["Evaluation results"]
end

subgraph group_configuration["Configuration and tracking"]
  node_parameters["Validated parameters<br/>[parameters.py]"]
  node_configs["Hydra configuration"]
  node_yaml["YAML configuration<br/>[config.yaml]"]
  node_seed["Reproducibility utilities<br/>[reproducibility.py]"]
  node_tracker["MLflow tracking<br/>[mlflow_tracker.py]"]
end

node_user(("Researcher"))

node_user -->|"starts training"| node_train
node_user -->|"requests evaluation"| node_finaleval
node_user -->|"runs benchmark"| node_baseline
node_yaml -->|"supplies settings"| node_configs
node_configs -->|"configures run"| node_train
node_train -->|"validates parameters"| node_parameters
node_train -->|"seeds run"| node_seed
node_train -->|"creates environment"| node_env
node_train -->|"trains policy"| node_ppo
node_train -.->|"logs run"| node_tracker
node_ppo -->|"selects torque"| node_env
node_env -->|"advances state"| node_integrator
node_integrator -->|"computes acceleration"| node_dynamics
node_integrator -->|"returns new state"| node_state
node_env -->|"computes end-effector"| node_kinematics
node_env -->|"computes reward"| node_reward
node_env -->|"stores current state"| node_state
node_finaleval -->|"measures reward"| node_eval
node_finaleval -->|"creates test environments"| node_env
node_finaleval -->|"records policy"| node_visualization
node_eval -->|"evaluates policy"| node_ppo
node_finaleval -->|"writes summary"| node_results
node_visualization -->|"writes plots and video"| node_results
node_baseline -->|"benchmarks controllers"| node_env
node_baseline -->|"reports comparison"| node_results

click node_train "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/training/train.py"
click node_baseline "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/evaluation/baseline_benchmark.py"
click node_env "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/environment/robot_env.py"
click node_state "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/domain/state.py"
click node_parameters "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/domain/parameters.py"
click node_kinematics "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/physics/kinematics.py"
click node_integrator "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/physics/integrator.py"
click node_dynamics "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/physics/dynamics.py"
click node_reward "https://github.com/amghalcyon/mech_rl/tree/main/src/mech_rl/reward"
click node_configs "https://github.com/amghalcyon/mech_rl/tree/main/src/mech_rl/configs"
click node_yaml "https://github.com/amghalcyon/mech_rl/blob/main/configs/config.yaml"
click node_seed "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/utils/reproducibility.py"
click node_tracker "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/tracking/mlflow_tracker.py"
click node_eval "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/evaluation/eval_loop.py"
click node_finaleval "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/evaluation/final_eval.py"
click node_visualization "https://github.com/amghalcyon/mech_rl/tree/main/src/mech_rl/visualization"
click node_benchmark "https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/evaluation/baseline_benchmark.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_train,node_ppo,node_baseline toneBlue
class node_env,node_state,node_kinematics,node_integrator,node_dynamics,node_reward toneAmber
class node_eval,node_finaleval,node_visualization,node_benchmark,node_results toneMint
class node_parameters,node_configs,node_yaml,node_seed,node_tracker toneRose
class node_user toneIndigo
```

## Components

### Training and control

- [PPO training](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/training/train.py): `src/mech_rl/training/train.py`
- **PPO policy**
- [Baseline benchmark](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/evaluation/baseline_benchmark.py): `src/mech_rl/evaluation/baseline_benchmark.py`

### Arm simulation

- [Gym arm environment](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/environment/robot_env.py): `src/mech_rl/environment/robot_env.py`
- [Robot state](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/domain/state.py): `src/mech_rl/domain/state.py`
- [Forward kinematics](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/physics/kinematics.py): `src/mech_rl/physics/kinematics.py`
- [Time integrators](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/physics/integrator.py): `src/mech_rl/physics/integrator.py`
- [Arm dynamics](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/physics/dynamics.py): `src/mech_rl/physics/dynamics.py`
- [Reward calculation](https://github.com/amghalcyon/mech_rl/tree/main/src/mech_rl/reward): `src/mech_rl/reward`

### Evaluation and analysis

- [Evaluation loop](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/evaluation/eval_loop.py): `src/mech_rl/evaluation/eval_loop.py`
- [Final evaluation](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/evaluation/final_eval.py): `src/mech_rl/evaluation/final_eval.py`
- [Plots and policy video](https://github.com/amghalcyon/mech_rl/tree/main/src/mech_rl/visualization): `src/mech_rl/visualization`
- [Baseline comparison](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/evaluation/baseline_benchmark.py): `src/mech_rl/evaluation/baseline_benchmark.py`
- **Evaluation results**

### Configuration and tracking

- [Validated parameters](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/domain/parameters.py): `src/mech_rl/domain/parameters.py`
- [Hydra configuration](https://github.com/amghalcyon/mech_rl/tree/main/src/mech_rl/configs): `src/mech_rl/configs`
- [YAML configuration](https://github.com/amghalcyon/mech_rl/blob/main/configs/config.yaml): `configs/config.yaml`
- [Reproducibility utilities](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/utils/reproducibility.py): `src/mech_rl/utils/reproducibility.py`
- [MLflow tracking](https://github.com/amghalcyon/mech_rl/blob/main/src/mech_rl/tracking/mlflow_tracker.py): `src/mech_rl/tracking/mlflow_tracker.py`

### Other components

- **Researcher**

## Connections

- Researcher → PPO training: starts training
- Researcher → Final evaluation: requests evaluation
- Researcher → Baseline benchmark: runs benchmark
- YAML configuration → Hydra configuration: supplies settings
- Hydra configuration → PPO training: configures run
- PPO training → Validated parameters: validates parameters
- PPO training → Reproducibility utilities: seeds run
- PPO training → Gym arm environment: creates environment
- PPO training → PPO policy: trains policy
- PPO training → MLflow tracking: logs run
- PPO policy → Gym arm environment: selects torque
- Gym arm environment → Time integrators: advances state
- Time integrators → Arm dynamics: computes acceleration
- Time integrators → Robot state: returns new state
- Gym arm environment → Forward kinematics: computes end-effector
- Gym arm environment → Reward calculation: computes reward
- Gym arm environment → Robot state: stores current state
- Final evaluation → Evaluation loop: measures reward
- Final evaluation → Gym arm environment: creates test environments
- Final evaluation → Plots and policy video: records policy
- Evaluation loop → PPO policy: evaluates policy
- Final evaluation → Evaluation results: writes summary
- Plots and policy video → Evaluation results: writes plots and video
- Baseline benchmark → Gym arm environment: benchmarks controllers
- Baseline benchmark → Evaluation results: reports comparison