# stack-of-tasks/tsid architecture

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

- Interactive diagram: https://gitdiagram.com/stack-of-tasks/tsid
- Repository: https://github.com/stack-of-tasks/tsid

## Overview

##### Main Components
- Core Library Modules:
- Contacts: Contains definitions for various contact models (files in src/contacts and include/tsid/contacts). Responsible for representing and computing contact forces.
- Formulations: Implements the inverse dynamics formulations (e.g., contact-level formulations found under src/formulations and include/tsid/formulations).
- Tasks: Manages the definition and implementation of tasks and constraints (see src/tasks and include/tsid/tasks), such as joint bounds, center-of-mass objectives, and posture tracking.
- Math: Provides underlying mathematical utilities and constraint management logic (located in src/math and include/tsid/math).
- Solvers: Integrates and interfaces with quadratic programming solvers (files under src/solvers and include/tsid/solvers), including specialized solvers like HQP-eiquadprog, OSQP, and ProxQP.
- Trajectories: Manages trajectory definitions and manipulations (in src/trajectories and include/tsid/trajectories).
- Robot Handling: Implements a robot wrapper class (under src/robots and include/tsid/robots) to interact with underlying whole-body dynamics.
- Utilities: Contains additional helper functions (source under src/utils and include/tsid/utils).
- Bindings:
- Python Bindings: Located in the bindings directory (and its subdirectories) which provide a C++ → Python interface using Boost.Python and EigenPy.
- Demos, Exercizes, and Tests:
- Demo scripts and exercise notebooks show sample usages (in demo and exercizes folders).
- Tests (in tests) cover unit tests for each module, including separate tests for Python bindings.

##### Relationships and Interactions
- Data Flow/Control Flow:
- The “Robot Handling” module (robot-wrapper) serves as the interface to robot models (URDF files under models) and passes dynamics information (using external library Pinocchio).
- The “Tasks” and “Contacts” modules define objectives and constraints that are fed into the “Formulations” module which sets up the inverse dynamics problem.
- The “Solvers” module then receives the problem data (from formulations) and executes the optimization step, producing torque/force outputs.
- “Trajectories” may be used to plan and simulate smooth movements which can affect task definitions.
- The Python bindings act as a bridge to expose these functionalities to end users, enabling rapid prototyping in Python.
- External Dependencies:
- There’s a dependency on the Pinocchio library for rigid multi-body dynamics.
- Other dependencies include Eigen3 (for linear algebra), boost (for testing and bindings), and various QP solver libraries.

##### Architectural Patterns and Design Principles
- Modular Design: The project is clearly modular, with each folder representing a major part of the inverse dynamics computation.
- Layered Structure: At the lowest level are math utilities and solver implementations (core algorithms) that build up to higher-level task formulations and robot model management.
- API Abstraction: The Python bindings abstract away the complexity of the C++ backend to provide a more user-friendly and interactive API.
- Test Driven: The dedicated tests folder demonstrates an emphasis on validating each module independently.

##### Relevant Technologies and Frameworks
- C++ for high-performance numerical algorithms.
- Boost.Python and EigenPy for binding generation.
- External libraries: Pinocchio for multi-body dynamics and solvers like Eiquadprog, OSQP, and ProxQP.
- CMake for build configuration and management.

##### Elements
- From External Dependencies to Core Modules.
- From Robot Wrapper to Formulations (through Task definitions).
- From Solvers output back to Robot Wrapper or as end robot control commands.

- To annotate each block with key responsibilities.
- Testing and demo components as peripheral systems validating the core functionality.
- A note can be added to show that the “models” directory contains URDF files and associated meshes used by the Robot Wrapper, which integrates with Pinocchio.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies Layer
    subgraph "External Dependencies"
        Pinocchio["Pinocchio Library"]:::external
        Eigen3["Eigen3 Library"]:::external
        Boost["Boost Library"]:::external
        QPSolvers["QP Solvers"]:::external
    end

    %% Core C++ Library Layer
    subgraph "Core C++ Library"
        Contacts["Contacts Module"]:::core
        Formulations["Formulations Module"]:::core
        Tasks["Tasks Module"]:::core
        Math["Math Module"]:::core
        Solvers["Solvers Module"]:::core
        Trajectories["Trajectories Module"]:::core
        RobotHandling["Robot Handling Module"]:::core
        Utilities["Utilities Module"]:::core
    end

    %% Bindings Layer
    subgraph "Interfaces/Bindings"
        PythonBindings["Python Bindings"]:::bindings
    end

    %% User Interface Layer
    subgraph "User Interfaces"
        DemoTests["Demo/Exercizes/Tests"]:::frontend
    end

    %% External Dependencies to Core Modules
    Pinocchio -->|"provides dynamics"| RobotHandling
    Eigen3 -->|"math support"| Math
    QPSolvers -->|"optimization support"| Solvers
    Boost -->|"binding support"| PythonBindings

    %% Internal Core Module Interactions
    Contacts -->|"defines contacts"| Formulations
    Tasks -->|"provides task constraints"| Formulations
    Trajectories -->|"trajectory planning"| Tasks
    Formulations -->|"sets-up dynamics problem"| Solvers
    Solvers -->|"optimization results"| RobotHandling

    %% Bindings Interaction with Core
    PythonBindings -->|"exposes C++ API"| Contacts

    %% Frontend invokes Bindings
    DemoTests -->|"invokes"| PythonBindings

    %% Styles
    classDef external fill:#FCEBB6,stroke:#F08A5D,stroke-width:2px;
    classDef core fill:#BEE3DB,stroke:#355C7D,stroke-width:2px;
    classDef bindings fill:#C8A2C8,stroke:#6C5B7B,stroke-width:2px;
    classDef frontend fill:#D8BFD8,stroke:#A67673,stroke-width:2px;

    %% Click Events for Core Modules
    click Contacts "https://github.com/stack-of-tasks/tsid/tree/master/src/contacts"
    click Contacts "https://github.com/stack-of-tasks/tsid/tree/master/include/tsid/contacts"
    click Formulations "https://github.com/stack-of-tasks/tsid/tree/master/src/formulations"
    click Formulations "https://github.com/stack-of-tasks/tsid/tree/master/include/tsid/formulations"
    click Tasks "https://github.com/stack-of-tasks/tsid/tree/master/src/tasks"
    click Tasks "https://github.com/stack-of-tasks/tsid/tree/master/include/tsid/tasks"
    click Math "https://github.com/stack-of-tasks/tsid/tree/master/src/math"
    click Math "https://github.com/stack-of-tasks/tsid/tree/master/include/tsid/math"
    click Solvers "https://github.com/stack-of-tasks/tsid/tree/master/src/solvers"
    click Solvers "https://github.com/stack-of-tasks/tsid/tree/master/include/tsid/solvers"
    click Trajectories "https://github.com/stack-of-tasks/tsid/tree/master/src/trajectories"
    click Trajectories "https://github.com/stack-of-tasks/tsid/tree/master/include/tsid/trajectories"
    click RobotHandling "https://github.com/stack-of-tasks/tsid/blob/master/src/robots/robot-wrapper.cpp"
    click RobotHandling "https://github.com/stack-of-tasks/tsid/blob/master/include/tsid/robots/robot-wrapper.hpp"
    click Utilities "https://github.com/stack-of-tasks/tsid/tree/master/src/utils"
    click Utilities "https://github.com/stack-of-tasks/tsid/tree/master/include/tsid/utils"

    %% Click Events for Bindings and Frontend
    click PythonBindings "https://github.com/stack-of-tasks/tsid/tree/master/bindings"
    click PythonBindings "https://github.com/stack-of-tasks/tsid/tree/master/include/tsid/bindings/python"
    click DemoTests "https://github.com/stack-of-tasks/tsid/tree/master/demo"
    click DemoTests "https://github.com/stack-of-tasks/tsid/tree/master/exercizes"
    click DemoTests "https://github.com/stack-of-tasks/tsid/tree/master/tests"
```
