# jaeykimusa/a1-gait-planning-sim architecture

> Architecture diagram of the GitHub repository jaeykimusa/a1-gait-planning-sim, 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/jaeykimusa/a1-gait-planning-sim
- Repository: https://github.com/jaeykimusa/a1-gait-planning-sim

## Overview

This repository is a MuJoCo quadruped gait-planning simulation. Its runtime loop advances per-leg gait states, generates foot and joint references, computes torques, steps the simulated robot, and renders the result. The graph also retains the kinematics, contact-force, robot-model, and command-control modules identified as core. Source excerpts establish the main loop and several controller calls; some internal links rely on the SOURCE INDEX, so unsampled behavior is not inferred beyond those references.

Main entry points: [`a1_trot/mj_a1_trot.py`](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/mj_a1_trot.py) (MuJoCo Loop), [`a1_trot/globals.py`](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/globals.py) (Runtime State), [`a1_trot/cartesian_traj.py`](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/cartesian_traj.py) (Foot Trajectories), [`a1_trot/joint_traj.py`](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/joint_traj.py) (Joint Trajectories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sim["Simulation"]
  node_simloop["MuJoCo Loop<br/>[mj_a1_trot.py]"]
  node_scene["Robot Scene<br/>[scene.xml]"]
end

subgraph group_gait["Gait Planning"]
  node_fsm["Gait State Machine<br/>[state_machine.py]"]
  node_carttraj["Foot Trajectories<br/>[cartesian_traj.py]"]
  node_quintic["Quintic Profiles<br/>[quintic_poly.py]"]
  node_jointtraj["Joint Trajectories<br/>[joint_traj.py]"]
  node_command["Step Commands"]
  node_globals["Runtime State<br/>[globals.py]"]
  node_params["Gait Parameters<br/>[parameters.py]"]
end

subgraph group_control["Kinematics Control"]
  node_jointcontrol["Joint Controller<br/>[joint_control.py]"]
  node_highcontrol["High-Level Control"]
  node_stance["Stance Forces<br/>[stance_force.py]"]
  node_jacobian["Leg Jacobian"]
  node_fkleg["Leg Kinematics"]
  node_ik["Analytic Inverse Kinematics"]
  node_fkrobot["Robot Kinematics"]
end

subgraph group_model["Robot Model"]
  node_robotdata[("Robot Data<br/>[robot_data.py]")]
  node_utility["Rotation Utilities<br/>[utility.py]"]
end

node_operator(("Operator"))

node_operator -.->|"starts"| node_simloop
node_simloop -->|"loads model"| node_scene
node_simloop -->|"updates gait"| node_fsm
node_simloop -->|"generates feet"| node_carttraj
node_simloop -->|"generates joints"| node_jointtraj
node_simloop -->|"computes torques"| node_jointcontrol
node_simloop -->|"updates control"| node_highcontrol
node_simloop -->|"reads writes"| node_globals
node_fsm -->|"updates state"| node_globals
node_fsm -->|"reads phases"| node_params
node_carttraj -->|"evaluates profiles"| node_quintic
node_carttraj -->|"writes references"| node_globals
node_carttraj -->|"reads gait timing"| node_params
node_jointtraj -->|"uses inverse kinematics"| node_ik
node_jointtraj -->|"uses Jacobian"| node_jacobian
node_jointtraj -.->|"reads writes"| node_globals
node_highcontrol -->|"sets step command"| node_command
node_highcontrol -->|"uses runtime state"| node_globals
node_globals -->|"initializes from"| node_params
node_jointcontrol -->|"requests forces"| node_stance
node_jointcontrol -->|"computes torque mapping"| node_jacobian
node_jointcontrol -->|"reads writes"| node_globals
node_stance -->|"gets foot positions"| node_fkrobot
node_stance -->|"reads state"| node_globals
node_jacobian -->|"uses leg transforms"| node_fkleg
node_fkrobot -->|"reads body model"| node_robotdata
node_fkrobot -->|"uses rotations"| node_utility
node_robotdata -->|"normalizes quaternions"| node_utility

click node_simloop "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/mj_a1_trot.py"
click node_scene "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/unitree_robotics_a1/scene.xml"
click node_fsm "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/state_machine.py"
click node_carttraj "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/cartesian_traj.py"
click node_quintic "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/quintic_poly.py"
click node_jointtraj "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/joint_traj.py"
click node_command "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/set_command_step.py"
click node_globals "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/globals.py"
click node_params "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/parameters.py"
click node_jointcontrol "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/joint_control.py"
click node_highcontrol "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/high_level_control.py"
click node_stance "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/stance_force.py"
click node_jacobian "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/jac_end_effector_leg.py"
click node_fkleg "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/forward_kinematics_leg.py"
click node_ik "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/inverse_kinematics_analytic.py"
click node_fkrobot "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/forward_kinematics_robot.py"
click node_robotdata "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/robot_data.py"
click node_utility "https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/utility.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_simloop,node_scene toneBlue
class node_fsm,node_carttraj,node_quintic,node_jointtraj,node_command,node_globals,node_params toneAmber
class node_jointcontrol,node_highcontrol,node_stance,node_jacobian,node_fkleg,node_ik,node_fkrobot toneMint
class node_robotdata,node_utility toneRose
class node_operator toneIndigo
```

## Components

### Simulation

- [MuJoCo Loop](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/mj_a1_trot.py): `a1_trot/mj_a1_trot.py`
- [Robot Scene](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/unitree_robotics_a1/scene.xml): `unitree_robotics_a1/scene.xml`

### Gait Planning

- [Gait State Machine](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/state_machine.py): `a1_trot/state_machine.py`
- [Foot Trajectories](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/cartesian_traj.py): `a1_trot/cartesian_traj.py`
- [Quintic Profiles](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/quintic_poly.py): `a1_trot/quintic_poly.py`
- [Joint Trajectories](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/joint_traj.py): `a1_trot/joint_traj.py`
- [Step Commands](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/set_command_step.py): `a1_trot/set_command_step.py`
- [Runtime State](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/globals.py): `a1_trot/globals.py`
- [Gait Parameters](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/parameters.py): `a1_trot/parameters.py`

### Kinematics Control

- [Joint Controller](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/joint_control.py): `a1_trot/joint_control.py`
- [High-Level Control](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/high_level_control.py): `a1_trot/high_level_control.py`
- [Stance Forces](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/stance_force.py): `a1_trot/stance_force.py`
- [Leg Jacobian](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/jac_end_effector_leg.py): `a1_trot/jac_end_effector_leg.py`
- [Leg Kinematics](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/forward_kinematics_leg.py): `a1_trot/forward_kinematics_leg.py`
- [Analytic Inverse Kinematics](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/inverse_kinematics_analytic.py): `a1_trot/inverse_kinematics_analytic.py`
- [Robot Kinematics](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/forward_kinematics_robot.py): `a1_trot/forward_kinematics_robot.py`

### Robot Model

- [Robot Data](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/robot_data.py): `a1_trot/robot_data.py`
- [Rotation Utilities](https://github.com/jaeykimusa/a1-gait-planning-sim/blob/main/a1_trot/utility.py): `a1_trot/utility.py`

### Other components

- **Operator**

## Connections

- Operator → MuJoCo Loop: starts
- MuJoCo Loop → Robot Scene: loads model (evidence: `a1_trot/mj_a1_trot.py`)
- MuJoCo Loop → Gait State Machine: updates gait (evidence: `a1_trot/mj_a1_trot.py`)
- MuJoCo Loop → Foot Trajectories: generates feet (evidence: `a1_trot/mj_a1_trot.py`)
- MuJoCo Loop → Joint Trajectories: generates joints (evidence: `a1_trot/mj_a1_trot.py`)
- MuJoCo Loop → Joint Controller: computes torques (evidence: `a1_trot/mj_a1_trot.py`)
- MuJoCo Loop → High-Level Control: updates control (evidence: `a1_trot/mj_a1_trot.py`)
- MuJoCo Loop → Runtime State: reads writes (evidence: `a1_trot/mj_a1_trot.py`)
- Gait State Machine → Runtime State: updates state (evidence: `a1_trot/state_machine.py`)
- Gait State Machine → Gait Parameters: reads phases (evidence: `a1_trot/state_machine.py`)
- Foot Trajectories → Quintic Profiles: evaluates profiles (evidence: `a1_trot/cartesian_traj.py`)
- Foot Trajectories → Runtime State: writes references (evidence: `a1_trot/cartesian_traj.py`)
- Foot Trajectories → Gait Parameters: reads gait timing (evidence: `a1_trot/cartesian_traj.py`)
- Joint Trajectories → Analytic Inverse Kinematics: uses inverse kinematics (evidence: `a1_trot/joint_traj.py`)
- Joint Trajectories → Leg Jacobian: uses Jacobian (evidence: `a1_trot/joint_traj.py`)
- Joint Trajectories → Runtime State: reads writes (evidence: `a1_trot/joint_traj.py`)
- High-Level Control → Step Commands: sets step command (evidence: `a1_trot/high_level_control.py`)
- High-Level Control → Runtime State: uses runtime state (evidence: `a1_trot/high_level_control.py`)
- Runtime State → Gait Parameters: initializes from (evidence: `a1_trot/globals.py`)
- Joint Controller → Stance Forces: requests forces (evidence: `a1_trot/joint_control.py`)
- Joint Controller → Leg Jacobian: computes torque mapping (evidence: `a1_trot/joint_control.py`)
- Joint Controller → Runtime State: reads writes (evidence: `a1_trot/joint_control.py`)
- Stance Forces → Robot Kinematics: gets foot positions (evidence: `a1_trot/stance_force.py`)
- Stance Forces → Runtime State: reads state (evidence: `a1_trot/stance_force.py`)
- Leg Jacobian → Leg Kinematics: uses leg transforms (evidence: `a1_trot/jac_end_effector_leg.py`)
- Robot Kinematics → Robot Data: reads body model (evidence: `a1_trot/forward_kinematics_robot.py`)
- Robot Kinematics → Rotation Utilities: uses rotations (evidence: `a1_trot/forward_kinematics_robot.py`)
- Robot Data → Rotation Utilities: normalizes quaternions (evidence: `a1_trot/robot_data.py`)
