# pita-research/mjx_pita architecture

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

- Interactive diagram: https://gitdiagram.com/pita-research/mjx_pita
- Repository: https://github.com/pita-research/mjx_pita

## Overview

MJX_ZS trains and runs reinforcement-learning locomotion policies for the XG quadruped. The principal workflow is experiment selection and configuration, MJX environment construction, velocity-task simulation, PPO policy updates and checkpointing; play loads a policy and visualizes rollouts. Task mechanics are divided between a velocity component and reusable mechanical subcomponents, with EnvInfo carrying simulation state. The graph follows README capabilities and indexed source references; unsampled factory and training details are represented only where documented or indexed, so some relationships are omitted rather than inferred.

Main entry points: [`src/play.py`](https://github.com/pita-research/mjx_pita/blob/main/src/play.py) (Inference entrypoint), [`src/envs/backends/generic_env.py`](https://github.com/pita-research/mjx_pita/blob/main/src/envs/backends/generic_env.py) (MJX environment), [`src/components/mechanical_base.py`](https://github.com/pita-research/mjx_pita/blob/main/src/components/mechanical_base.py) (Mechanical facade), [`src/cfg/experiments/base.py`](https://github.com/pita-research/mjx_pita/blob/main/src/cfg/experiments/base.py) (Experiment registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Experiment and entrypoints"]
  node_train["Training entrypoint<br/>[train.py]"]
  node_play["Inference entrypoint<br/>[play.py]"]
  node_experiment["Experiment registry<br/>[base.py]"]
  node_config["XG configuration<br/>[xg_config.py]"]
end

subgraph group_simulation["Environment and simulation"]
  node_envfactory["Environment factory<br/>[factory.py]"]
  node_genericenv["MJX environment<br/>[generic_env.py]"]
  node_envstate["Environment state<br/>[state.py]"]
  node_envinfo["Typed info bus<br/>[info.py]"]
  node_compat["Info compatibility<br/>[info_compat.py]"]
  node_viewer["Viewer and video<br/>[viewer.py]"]
end

subgraph group_task["Task mechanics"]
  node_componentfactory["Component factory<br/>[factory.py]"]
  node_basecomponent["Task component API<br/>[base.py]"]
  node_mechanical["Mechanical facade<br/>[mechanical_base.py]"]
  node_velocity["Velocity component<br/>[__init__.py]"]
  node_velocityrules["Velocity task rules<br/>[rewards.py]"]
  node_control["Actuator control<br/>[control.py]"]
  node_kinematics["Kinematics<br/>[kinematics.py]"]
  node_reset["Reset mechanics<br/>[reset.py]"]
  node_mechanicalparts["Reusable mechanics"]
end

subgraph group_learning["Policy and learning"]
  node_network["Actor-critic networks<br/>[mlp.py]"]
  node_lstm["LSTM network<br/>[lstm.py]"]
  node_ppo["PPO trainer<br/>[ppo.py]"]
end

subgraph group_robot["Robot and task specs"]
  node_robot["Robot specification<br/>[base.py]"]
  node_taskspec["Task specification<br/>[base.py]"]
end

node_user(("Engineer"))
node_checkpoint[("Checkpoint files")]
node_mjx["MuJoCo MJX"]

node_user -->|"starts training"| node_train
node_user -->|"runs inference"| node_play
node_train -->|"selects experiment"| node_experiment
node_play -->|"selects experiment"| node_experiment
node_experiment -->|"builds config"| node_config
node_experiment -->|"specifies robot"| node_robot
node_experiment -->|"specifies task"| node_taskspec
node_train -->|"builds environment"| node_envfactory
node_play -->|"builds environment"| node_envfactory
node_envfactory -.->|"constructs backend"| node_genericenv
node_genericenv -->|"steps simulation"| node_mjx
node_genericenv -->|"creates component"| node_componentfactory
node_componentfactory -->|"selects task"| node_velocity
node_velocity -->|"extends mechanics"| node_mechanical
node_mechanical -->|"implements interface"| node_basecomponent
node_mechanical -->|"delegates control"| node_control
node_mechanical -->|"uses kinematics"| node_kinematics
node_mechanical -->|"delegates reset"| node_reset
node_mechanical -.->|"uses subcomponents"| node_mechanicalparts
node_velocity -->|"computes rewards"| node_velocityrules
node_genericenv -->|"returns state"| node_envstate
node_envstate -->|"carries info"| node_envinfo
node_genericenv -->|"bridges info"| node_compat
node_genericenv -->|"delegates rendering"| node_viewer
node_train -->|"runs PPO"| node_ppo
node_ppo -.->|"updates policy"| node_network
node_play -->|"loads policy"| node_network
node_ppo -->|"collects rollouts"| node_envstate
node_play -->|"runs rollout"| node_envstate
node_ppo -.->|"saves parameters"| node_checkpoint
node_play -->|"loads parameters"| node_checkpoint
node_lstm -.->|"shares network family"| node_network

click node_train "https://github.com/pita-research/mjx_pita/blob/main/src/train.py"
click node_play "https://github.com/pita-research/mjx_pita/blob/main/src/play.py"
click node_experiment "https://github.com/pita-research/mjx_pita/blob/main/src/cfg/experiments/base.py"
click node_config "https://github.com/pita-research/mjx_pita/blob/main/src/cfg/xg_config.py"
click node_envfactory "https://github.com/pita-research/mjx_pita/blob/main/src/envs/factory.py"
click node_genericenv "https://github.com/pita-research/mjx_pita/blob/main/src/envs/backends/generic_env.py"
click node_envstate "https://github.com/pita-research/mjx_pita/blob/main/src/envs/state.py"
click node_envinfo "https://github.com/pita-research/mjx_pita/blob/main/src/envs/info.py"
click node_compat "https://github.com/pita-research/mjx_pita/blob/main/src/envs/info_compat.py"
click node_viewer "https://github.com/pita-research/mjx_pita/blob/main/src/envs/backends/viewer.py"
click node_componentfactory "https://github.com/pita-research/mjx_pita/blob/main/src/components/factory.py"
click node_basecomponent "https://github.com/pita-research/mjx_pita/blob/main/src/components/base.py"
click node_mechanical "https://github.com/pita-research/mjx_pita/blob/main/src/components/mechanical_base.py"
click node_velocity "https://github.com/pita-research/mjx_pita/blob/main/src/components/tasks/velocity/__init__.py"
click node_velocityrules "https://github.com/pita-research/mjx_pita/blob/main/src/components/tasks/velocity/rewards.py"
click node_control "https://github.com/pita-research/mjx_pita/blob/main/src/components/subcomponents/control.py"
click node_kinematics "https://github.com/pita-research/mjx_pita/blob/main/src/components/subcomponents/kinematics.py"
click node_reset "https://github.com/pita-research/mjx_pita/blob/main/src/components/subcomponents/reset.py"
click node_mechanicalparts "https://github.com/pita-research/mjx_pita/tree/main/src/components/subcomponents"
click node_robot "https://github.com/pita-research/mjx_pita/blob/main/src/robots/base.py"
click node_taskspec "https://github.com/pita-research/mjx_pita/blob/main/src/tasks/base.py"
click node_network "https://github.com/pita-research/mjx_pita/blob/main/src/networks/mlp.py"
click node_lstm "https://github.com/pita-research/mjx_pita/blob/main/src/networks/lstm.py"
click node_ppo "https://github.com/pita-research/mjx_pita/blob/main/src/training/ppo.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_play,node_experiment,node_config toneBlue
class node_envfactory,node_genericenv,node_envstate,node_envinfo,node_compat,node_viewer,node_checkpoint toneAmber
class node_componentfactory,node_basecomponent,node_mechanical,node_velocity,node_velocityrules,node_control,node_kinematics,node_reset,node_mechanicalparts toneMint
class node_network,node_lstm,node_ppo toneRose
class node_robot,node_taskspec,node_user,node_mjx toneIndigo
```

## Components

### Experiment and entrypoints

- [Training entrypoint](https://github.com/pita-research/mjx_pita/blob/main/src/train.py): `src/train.py`
- [Inference entrypoint](https://github.com/pita-research/mjx_pita/blob/main/src/play.py): `src/play.py`
- [Experiment registry](https://github.com/pita-research/mjx_pita/blob/main/src/cfg/experiments/base.py): `src/cfg/experiments/base.py`
- [XG configuration](https://github.com/pita-research/mjx_pita/blob/main/src/cfg/xg_config.py): `src/cfg/xg_config.py`

### Environment and simulation

- [Environment factory](https://github.com/pita-research/mjx_pita/blob/main/src/envs/factory.py): `src/envs/factory.py`
- [MJX environment](https://github.com/pita-research/mjx_pita/blob/main/src/envs/backends/generic_env.py): `src/envs/backends/generic_env.py`
- [Environment state](https://github.com/pita-research/mjx_pita/blob/main/src/envs/state.py): `src/envs/state.py`
- [Typed info bus](https://github.com/pita-research/mjx_pita/blob/main/src/envs/info.py): `src/envs/info.py`
- [Info compatibility](https://github.com/pita-research/mjx_pita/blob/main/src/envs/info_compat.py): `src/envs/info_compat.py`
- [Viewer and video](https://github.com/pita-research/mjx_pita/blob/main/src/envs/backends/viewer.py): `src/envs/backends/viewer.py`

### Task mechanics

- [Component factory](https://github.com/pita-research/mjx_pita/blob/main/src/components/factory.py): `src/components/factory.py`
- [Task component API](https://github.com/pita-research/mjx_pita/blob/main/src/components/base.py): `src/components/base.py`
- [Mechanical facade](https://github.com/pita-research/mjx_pita/blob/main/src/components/mechanical_base.py): `src/components/mechanical_base.py`
- [Velocity component](https://github.com/pita-research/mjx_pita/blob/main/src/components/tasks/velocity/__init__.py): `src/components/tasks/velocity/__init__.py`
- [Velocity task rules](https://github.com/pita-research/mjx_pita/blob/main/src/components/tasks/velocity/rewards.py): `src/components/tasks/velocity/rewards.py`
- [Actuator control](https://github.com/pita-research/mjx_pita/blob/main/src/components/subcomponents/control.py): `src/components/subcomponents/control.py`
- [Kinematics](https://github.com/pita-research/mjx_pita/blob/main/src/components/subcomponents/kinematics.py): `src/components/subcomponents/kinematics.py`
- [Reset mechanics](https://github.com/pita-research/mjx_pita/blob/main/src/components/subcomponents/reset.py): `src/components/subcomponents/reset.py`
- [Reusable mechanics](https://github.com/pita-research/mjx_pita/tree/main/src/components/subcomponents): `src/components/subcomponents`

### Policy and learning

- [Actor-critic networks](https://github.com/pita-research/mjx_pita/blob/main/src/networks/mlp.py): `src/networks/mlp.py`
- [LSTM network](https://github.com/pita-research/mjx_pita/blob/main/src/networks/lstm.py): `src/networks/lstm.py`
- [PPO trainer](https://github.com/pita-research/mjx_pita/blob/main/src/training/ppo.py): `src/training/ppo.py`

### Robot and task specs

- [Robot specification](https://github.com/pita-research/mjx_pita/blob/main/src/robots/base.py): `src/robots/base.py`
- [Task specification](https://github.com/pita-research/mjx_pita/blob/main/src/tasks/base.py): `src/tasks/base.py`

### Other components

- **Engineer**
- **Checkpoint files**
- **MuJoCo MJX**

## Connections

- Engineer → Training entrypoint: starts training
- Engineer → Inference entrypoint: runs inference
- Training entrypoint → Experiment registry: selects experiment (evidence: `src/train.py`)
- Inference entrypoint → Experiment registry: selects experiment (evidence: `src/play.py`)
- Experiment registry → XG configuration: builds config (evidence: `src/cfg/experiments/xg_velocity.py`)
- Experiment registry → Robot specification: specifies robot (evidence: `src/cfg/experiments/base.py`)
- Experiment registry → Task specification: specifies task (evidence: `src/cfg/experiments/base.py`)
- Training entrypoint → Environment factory: builds environment (evidence: `src/train.py`)
- Inference entrypoint → Environment factory: builds environment (evidence: `src/play.py`)
- Environment factory → MJX environment: constructs backend
- MJX environment → MuJoCo MJX: steps simulation (evidence: `src/envs/backends/generic_env.py`)
- MJX environment → Component factory: creates component (evidence: `src/envs/backends/generic_env.py`)
- Component factory → Velocity component: selects task (evidence: `src/components/factory.py`)
- Velocity component → Mechanical facade: extends mechanics (evidence: `src/components/tasks/velocity/__init__.py`)
- Mechanical facade → Task component API: implements interface (evidence: `src/components/mechanical_base.py`)
- Mechanical facade → Actuator control: delegates control (evidence: `src/components/mechanical_base.py`)
- Mechanical facade → Kinematics: uses kinematics (evidence: `src/components/mechanical_base.py`)
- Mechanical facade → Reset mechanics: delegates reset (evidence: `src/components/mechanical_base.py`)
- Mechanical facade → Reusable mechanics: uses subcomponents (evidence: `src/components/mechanical_base.py`)
- Velocity component → Velocity task rules: computes rewards (evidence: `src/components/tasks/velocity/__init__.py`)
- MJX environment → Environment state: returns state (evidence: `src/envs/backends/generic_env.py`)
- Environment state → Typed info bus: carries info (evidence: `src/envs/state.py`)
- MJX environment → Info compatibility: bridges info (evidence: `src/envs/backends/generic_env.py`)
- MJX environment → Viewer and video: delegates rendering (evidence: `src/envs/backends/generic_env.py`)
- Training entrypoint → PPO trainer: runs PPO (evidence: `src/train.py`)
- PPO trainer → Actor-critic networks: updates policy
- Inference entrypoint → Actor-critic networks: loads policy (evidence: `src/play.py`)
- PPO trainer → Environment state: collects rollouts (evidence: `src/training/ppo.py`)
- Inference entrypoint → Environment state: runs rollout (evidence: `src/play.py`)
- PPO trainer → Checkpoint files: saves parameters
- Inference entrypoint → Checkpoint files: loads parameters (evidence: `src/play.py`)
- LSTM network → Actor-critic networks: shares network family
