# chungmin99/pyroki architecture

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

- Interactive diagram: https://gitdiagram.com/chungmin99/pyroki
- Repository: https://github.com/chungmin99/pyroki

## Overview

PyRoki is a Python/JAX toolkit for robot kinematics and optimization. The main workflow is to parse a URDF into a differentiable robot model, define pose, limit, manipulability, or collision objectives, and use an external Levenberg–Marquardt solver to find joint configurations; the same residuals support trajectory regularization. Collision modeling, visualization, and interactive weight tuning are supporting capabilities. The graph follows the documented API and sampled implementations; solver call-site wiring and several documented application workflows were not sampled, so uncertain links are omitted.

Main entry points: [`src/pyroki/_robot.py`](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_robot.py) (Forward kinematics), [`src/pyroki/costs.py`](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/costs.py) (Cost factories), [`src/pyroki/_residuals/_residuals.py`](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_residuals/_residuals.py) (Optimization residuals), [`src/pyroki/collision/_robot_collision.py`](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/collision/_robot_collision.py) (Robot collision model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Robot model"]
  node_parser["URDF parser"]
  node_robot["Robot model<br/>[_robot.py]"]
  node_fk["Forward kinematics<br/>[_robot.py]"]
end

subgraph group_collision["Collision modeling"]
  node_robot_collision["Robot collision model"]
  node_geometry["Collision geometry<br/>[_geometry.py]"]
  node_distance["Geometry distances<br/>[_geometry_pairs.py]"]
end

subgraph group_optimization["Optimization"]
  node_residuals["Optimization residuals<br/>[_residuals.py]"]
  node_analytic_pose["Analytic pose Jacobian"]
  node_numerical_pose["Numerical pose Jacobian"]
  node_costs["Cost factories<br/>[costs.py]"]
  node_trajectory["Trajectory objectives<br/>[_residuals.py]"]
end

subgraph group_tools["Visualization tools"]
  node_manip_view["Manipulability display"]
  node_weight_tuner["Weight tuner<br/>[_weight_tuner.py]"]
end

node_user(("Robot developer"))
node_urdf["URDF description"]
node_solver["LM solver"]
node_viser["Viser interface"]
node_joint_result["Joint solution"]

node_user -->|"provides model"| node_urdf
node_user -->|"loads robot"| node_parser
node_urdf -->|"parsed from"| node_parser
node_parser -->|"builds model"| node_robot
node_robot -->|"computes poses"| node_fk
node_robot -->|"provides link model"| node_robot_collision
node_robot_collision -->|"requests link poses"| node_fk
node_robot_collision -->|"transforms bodies"| node_geometry
node_distance -->|"measures pairs"| node_geometry
node_residuals -->|"computes pose terms"| node_fk
node_residuals -->|"queries collisions"| node_robot_collision
node_residuals -->|"uses distances"| node_distance
node_analytic_pose -->|"differentiates poses"| node_fk
node_numerical_pose -->|"evaluates poses"| node_fk
node_costs -->|"wraps residuals"| node_residuals
node_costs -->|"exports pose cost"| node_analytic_pose
node_costs -->|"exports pose cost"| node_numerical_pose
node_user -->|"defines objectives"| node_costs
node_user -->|"runs optimization"| node_solver
node_costs -->|"optimized by"| node_solver
node_solver -->|"returns configuration"| node_joint_result
node_trajectory -->|"supports motion terms"| node_fk
node_user -->|"defines trajectory terms"| node_trajectory
node_viser -->|"renders display"| node_manip_view
node_manip_view -->|"computes manipulability"| node_fk
node_viser -->|"hosts controls"| node_weight_tuner
node_weight_tuner -->|"tunes weights"| node_costs

click node_parser "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_robot_urdf_parser.py"
click node_robot "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_robot.py"
click node_fk "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_robot.py"
click node_robot_collision "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/collision/_robot_collision.py"
click node_geometry "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/collision/_geometry.py"
click node_distance "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/collision/_geometry_pairs.py"
click node_residuals "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_residuals/_residuals.py"
click node_analytic_pose "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_residuals/_pose_residual_analytic_jac.py"
click node_numerical_pose "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_residuals/_pose_residual_numerical_jac.py"
click node_costs "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/costs.py"
click node_trajectory "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_residuals/_residuals.py"
click node_manip_view "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/viewer/_manipulability_ellipse.py"
click node_weight_tuner "https://github.com/chungmin99/pyroki/blob/main/src/pyroki/viewer/_weight_tuner.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_parser,node_robot,node_fk toneBlue
class node_robot_collision,node_geometry,node_distance toneAmber
class node_residuals,node_analytic_pose,node_numerical_pose,node_costs,node_trajectory toneMint
class node_manip_view,node_weight_tuner toneRose
class node_user,node_urdf,node_solver,node_viser,node_joint_result toneIndigo
```

## Components

### Robot model

- [URDF parser](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_robot_urdf_parser.py): `src/pyroki/_robot_urdf_parser.py`
- [Robot model](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_robot.py): `src/pyroki/_robot.py`
- [Forward kinematics](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_robot.py): `src/pyroki/_robot.py`

### Collision modeling

- [Robot collision model](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/collision/_robot_collision.py): `src/pyroki/collision/_robot_collision.py`
- [Collision geometry](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/collision/_geometry.py): `src/pyroki/collision/_geometry.py`
- [Geometry distances](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/collision/_geometry_pairs.py): `src/pyroki/collision/_geometry_pairs.py`

### Optimization

- [Optimization residuals](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_residuals/_residuals.py): `src/pyroki/_residuals/_residuals.py`
- [Analytic pose Jacobian](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_residuals/_pose_residual_analytic_jac.py): `src/pyroki/_residuals/_pose_residual_analytic_jac.py`
- [Numerical pose Jacobian](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_residuals/_pose_residual_numerical_jac.py): `src/pyroki/_residuals/_pose_residual_numerical_jac.py`
- [Cost factories](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/costs.py): `src/pyroki/costs.py`
- [Trajectory objectives](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/_residuals/_residuals.py): `src/pyroki/_residuals/_residuals.py`

### Visualization tools

- [Manipulability display](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/viewer/_manipulability_ellipse.py): `src/pyroki/viewer/_manipulability_ellipse.py`
- [Weight tuner](https://github.com/chungmin99/pyroki/blob/main/src/pyroki/viewer/_weight_tuner.py): `src/pyroki/viewer/_weight_tuner.py`

### Other components

- **Robot developer**
- **URDF description**
- **LM solver**
- **Viser interface**
- **Joint solution**

## Connections

- Robot developer → URDF description: provides model
- Robot developer → URDF parser: loads robot
- URDF description → URDF parser: parsed from
- URDF parser → Robot model: builds model
- Robot model → Forward kinematics: computes poses
- Robot model → Robot collision model: provides link model
- Robot collision model → Forward kinematics: requests link poses
- Robot collision model → Collision geometry: transforms bodies
- Geometry distances → Collision geometry: measures pairs
- Optimization residuals → Forward kinematics: computes pose terms
- Optimization residuals → Robot collision model: queries collisions
- Optimization residuals → Geometry distances: uses distances
- Analytic pose Jacobian → Forward kinematics: differentiates poses
- Numerical pose Jacobian → Forward kinematics: evaluates poses
- Cost factories → Optimization residuals: wraps residuals
- Cost factories → Analytic pose Jacobian: exports pose cost
- Cost factories → Numerical pose Jacobian: exports pose cost
- Robot developer → Cost factories: defines objectives
- Robot developer → LM solver: runs optimization
- Cost factories → LM solver: optimized by
- LM solver → Joint solution: returns configuration
- Trajectory objectives → Forward kinematics: supports motion terms
- Robot developer → Trajectory objectives: defines trajectory terms
- Viser interface → Manipulability display: renders display
- Manipulability display → Forward kinematics: computes manipulability
- Viser interface → Weight tuner: hosts controls
- Weight tuner → Cost factories: tunes weights