# ami-iit/jaxsim architecture

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

- Interactive diagram: https://gitdiagram.com/ami-iit/jaxsim
- Repository: https://github.com/ami-iit/jaxsim

## Overview

##### Project Type and Purpose
- JaxSim is a physics simulation engine specialized in multibody dynamics and control algorithms. It is designed primarily for robotics and locomotion applications.
- The project leverages JAX for just-in-time (JIT) compilation, automatic vectorization, and automatic differentiation, making it efficient on CPUs, GPUs, and TPUs.
- The README and file tree indicate that it provides two main functionalities: simulation (stepping through simulation loops) and multibody dynamics (computing kinematics, dynamics, Jacobians, etc.).

##### File Structure
- Top-Level Directories:
- "src": Contains the core implementation, organized into packages such as “api”, “math”, “mujoco”, “parsers”, “rbda”, “terrain”, “utils”, and “typing”. Each of these packages encapsulates specific functionalities:
- The "api" package defines high-level functions and classes (e.g., model building, stepping, integration, frame operations).
- "math" includes utilities for rotations, transformations, skew matrices, etc.
- "rbda" is dedicated to core algorithms like the Articulated Body Algorithm (ABA), Composite Rigid Body Algorithm (CRBA), Recursive Newton-Euler Algorithm (RNEA), and associated utilities.
- "parsers" provides support for reading model descriptions (URDF, SDF) and converting them into the engine’s intermediate representations.
- "mujoco" integrates with an external simulator/viewer interface, easing visualization tasks.
- "docs": Contains documentation files and examples that further detail the architecture and API usage.
- "examples": Demonstrates how to use the API for simulation and dynamics computation.
- "tests": Contains unit tests that validate the functionality of various system components.
- Configuration directories like ".github", ".devcontainer", and CI/CD files indicate robust support for automated testing and development environments.

##### README for Additional Insights
- The README provides usage examples showing how a client loads a model (via a parser), sets up simulation data, and advances simulation states through API calls.
- It emphasizes the project’s role in linking model description parsing, physics simulation (based on reduced coordinates), and integration with autodifferentiation—all critical for robot control tasks.
- The examples highlight two main use cases: running a simulation loop (stepping simulation) and computing kinematics/dynamics properties for multibody analysis.
- The installation guidelines and continuous integration workflow files reinforce modularity and robustness.

a. Main Components to Represent:
- Client/Interface Layer: Represents users' scripts or notebooks that invoke the public API (as seen in examples).
- API/Service Layer: The "jaxsim/api" package that provides key simulation functionalities (model building, stepping, frame transformations, etc.).
- Core Engine:
- Model Building & Reduction: Modules in "model.py" that build a full model from parsed descriptions and reduce it based on specified joints.
- Simulation and Step Computation: Functions for computing dynamics, integrating state over time.
- Dynamics Computation Subsystem:
- RBDA Algorithms: The "rbda" package with ABA, CRBA, RNEA, and associated utilities.
- Math Utilities: Modules in "math" for handling transformations, rotations, inertia computations, etc.
- Model Parsing Layer: The "parsers" package (including "descriptions" and "rod") that interprets SDF/URDF files.
- Visualization/Integration:
- Mujoco Interface: The "mujoco" package that wraps API calls for passive viewer usage and conversion of models for visualization.
- Terrain & Environment: The "terrain" package defining simulation surfaces.
- Supporting Infrastructure:
- Logging & Exception Handling: Modules in "logging" and "exceptions" to handle system feedback and debugging.
- Utilities & Typing: Additional helper modules providing common functionality.
- External Components:
- JAX Library: Underpins automatic differentiation, JIT compilation, and vectorization.
- Docker and CI/CD: The ".devcontainer" and ".github" directories denote development and deployment support.

b. Relationships and Interactions:
- Clients call the API which in turn uses the parsers to load models.
- The model is then processed by the model building and reduction components.
- Simulation data, once created through the API, is passed to the dynamics engines (which rely on both the math utilities and RBDA implementations) for computing state updates.
- The Mujoco package interfaces with external visualization tools to display simulation results.
- Logging and error handling modules monitor the health of the simulation process.
- The use of JAX is pervasive: it underpins the computation pipelines in the API, math, and dynamic solvers.
- Data flows from model loading, through computation (via integrators and transformation functions), to the final simulation results or visual outputs.

c. Architectural Patterns/Design Principles:
- Modular Design: Clear separation into packages based on functionality (API, math, dynamics, parsers, visualization).
- Functional Programming and Differentiability: Emphasizes use of JAX’s functional paradigm for high-performance and differentiable computations.
- Layered Architecture: Distinct separation between model acquisition (parsers), simulation/analysis (dynamics engine), and application/browser (client API and visualization).

d. Relevant Technologies and Frameworks:
- JAX for auto-differentiation and JIT compilation.
- Python packages, as seen from pyproject.toml and setup.py, indicating Python 100% implementation.
- Integration with Docker containers (.devcontainer files) and CI/CD workflows (.github directory) ensure robust deployment.
- Usage of external formats (URDF, SDF) and conversions to support diverse model specifications.

##### Instructing the Principal Software Engineer
– Client/Script/Notebook (external usage layer)
– API Layer (jaxsim/api)
– Model Processing (model building, reduction)
– Dynamics Computation:
▪ RBDA algorithms (ABA, CRBA, RNEA etc.)
▪ Mathematical utilities (rotations, transforms)
– Model Parsers (SDF/URDF handling)
– Visualization / Mujoco interfacing
– Supporting Modules (logging, exception handling, utilities)
- Depicting external dependencies like JAX and integration tools such as CI/CD and Docker for a comprehensive view.
- Provide annotations or legends that emphasize important architectural decisions: the use of functional programming paradigms, modularity, and the focus on differentiable simulation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Interface Layer
    subgraph "Client/Interface Layer"
        Client["Client/Script/Notebook"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        API["API (src/jaxsim/api)"]:::api
        ModelBuild["Model Building & Reduction (src/jaxsim/api/model.py)"]:::api
        Integrators["Integrators (src/jaxsim/api/integrators.py)"]:::api
    end

    %% Model Parsing Layer
    subgraph "Model Parsing Layer"
        Parser["Model Parsers (src/jaxsim/parsers)"]:::parser
    end

    %% Dynamics Computation Subsystem
    subgraph "Dynamics Computation Subsystem"
        RBDA["RBDA Algorithms (src/jaxsim/rbda)"]:::dynamics
        MathUtils["Math Utilities (src/jaxsim/math)"]:::dynamics
    end

    %% Visualization/Integration
    subgraph "Visualization/Integration"
        Mujoco["Mujoco Interface (src/jaxsim/mujoco)"]:::visualization
        Terrain["Terrain & Environment (src/jaxsim/terrain)"]:::visualization
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        Logging["Logging & Exceptions (src/jaxsim/logging.py, src/jaxsim/exceptions.py)"]:::supporting
        Utils["Utilities & Typing (src/jaxsim/utils, src/jaxsim/typing.py)"]:::supporting
        CI["CI/CD & Docker (.github, .devcontainer)"]:::supporting
    end

    %% External Components
    External["External JAX Library"]:::external

    %% Connections
    Client -->|"callsAPI"| API
    API -->|"invokesParser"| Parser
    Parser -->|"suppliesModel"| ModelBuild
    ModelBuild -->|"feedsDataTo"| RBDA
    ModelBuild -->|"feedsDataTo"| MathUtils
    RBDA -->|"updatesState"| Integrators
    MathUtils -->|"supports"| Integrators
    Integrators -->|"advancesSim"| Mujoco
    Integrators -->|"advancesSim"| Terrain
    Mujoco -->|"visualizesResults"| Client

    %% Supporting Infrastructure connections (monitoring and support)
    Logging ---|"monitors"| API
    Logging ---|"monitors"| Parser
    Logging ---|"monitors"| RBDA
    Logging ---|"monitors"| MathUtils
    Utils ---|"supports"| API
    CI ---|"facilitates"| API
    External ---|"optimizes"| API
    External ---|"optimizes"| RBDA
    External ---|"optimizes"| MathUtils

    %% Click Events
    click Client "https://github.com/ami-iit/jaxsim/blob/main/examples/jaxsim_as_physics_engine.ipynb"
    click API "https://github.com/ami-iit/jaxsim/tree/main/src/jaxsim/api"
    click ModelBuild "https://github.com/ami-iit/jaxsim/blob/main/src/jaxsim/api/model.py"
    click Integrators "https://github.com/ami-iit/jaxsim/blob/main/src/jaxsim/api/integrators.py"
    click Parser "https://github.com/ami-iit/jaxsim/tree/main/src/jaxsim/parsers"
    click RBDA "https://github.com/ami-iit/jaxsim/tree/main/src/jaxsim/rbda"
    click MathUtils "https://github.com/ami-iit/jaxsim/tree/main/src/jaxsim/math"
    click Mujoco "https://github.com/ami-iit/jaxsim/tree/main/src/jaxsim/mujoco"
    click Terrain "https://github.com/ami-iit/jaxsim/blob/main/src/jaxsim/terrain/terrain.py"
    click Logging "https://github.com/ami-iit/jaxsim/blob/main/src/jaxsim/logging.py"
    click Utils "https://github.com/ami-iit/jaxsim/tree/main/src/jaxsim/utils"
    click CI "https://github.com/ami-iit/jaxsim/blob/main/.devcontainer"

    %% Styles
    classDef client fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef api fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef parser fill:#f8961e,stroke:#333,stroke-width:2px;
    classDef dynamics fill:#277da1,stroke:#333,stroke-width:2px;
    classDef visualization fill:#577590,stroke:#333,stroke-width:2px;
    classDef supporting fill:#f94144,stroke:#333,stroke-width:2px;
    classDef external fill:#90caf9,stroke:#333,stroke-width:2px;
```
