# kscalelabs/ksim architecture

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

- Interactive diagram: https://gitdiagram.com/kscalelabs/ksim
- Repository: https://github.com/kscalelabs/ksim

## Overview

##### Project type and purpose
- K-Sim is an open-source Python framework for training reinforcement-learning policies in simulation (MuJoCo).
- It provides modular building blocks (environments, actuators, noise models, reward functions, curricula, etc.) and a training engine that ties them together.

##### File structure
- Top-level:
- setup.py / pyproject.toml: packaging and dependencies (JAX, MuJoCo).
- ksim/: core library modules.
- examples/: end-to-end usage (data, model code, training scripts).
- tests/: unit and integration tests.
- assets/: documentation images.
- ksim/ submodules reveal architectural patterns:
- engine.py: central orchestrator (training loop).
- commands.py ↔ actuators.py: action issuance.
- observation.py: sensor outputs.
- rewards.py, terminations.py, resets.py: environment dynamics hooks.
- curriculum.py: staged training.
- randomization.py, noise.py: domain randomization.
- dataset.py: logging / replay buffers.
- vis.py: built-in visualization.
- task/: predefined RL tasks and algorithm interfaces (PPO, AMP, RL teacher).
- utils/: low-level API wrappers (MuJoCo, validators).

##### README for additional insights
- Emphasizes modularity and ease of use.
- Mentions JAX and MuJoCo as external dependencies.
- Provides examples as the recommended onboarding path.

a. Main components:
- User Script (examples/train.py)
- K-Sim Core
– Engine (Training Loop)
– Task Manager (defines observation/action spaces, reward, termination, reset, curriculum)
– Actuator/Command Layer (action mapping → MuJoCo)
– Observation Layer (simulation → policy inputs)
– Reward & Termination Module
– Randomization & Noise Module
– Dataset/Logger
– Visualization
- External Services
– MuJoCo Simulator
– JAX (computation backend)
b. Relationships and interactions:
- User Script configures: Task, Policy, Optimizer → passes to Engine
- Engine issues Commands → Actuators → MuJoCo steps
- MuJoCo returns states → Observation Layer → Policy (via JAX)
- Policy outputs actions → loop continues
- Rewards & Terminations computed per step → curriculum may adjust task parameters
- Dataset collects trajectories → optional replay or logging
- Visualization taps into Engine / Dataset for real-time plotting
c. Architectural patterns / design principles:
- Modular plug-ins: each hook (reset, reward, termination) implements a single responsibility interface.
- Inversion of control: Engine does not know specifics of Task or Policy internals, only the interfaces.
- Data flow separation: commands, observations, and metrics are distinct pipelines.
- Extensibility: new tasks or randomization modules live under ksim/task or ksim/utils.
d. Key technologies / libraries:
- Python typing (py.typed) for static guarantees
- JAX for high-performance autodiff and parallelism
- MuJoCo for physics simulation
- pytest for test suite

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User"
        US1["User Script\n(examples/kbot/train.py)"]:::user
        US2["User Script\n(examples/walking.py)"]:::user
    end

    subgraph "Core Modules"
        Engine["Engine\n(ksim/engine.py)"]:::core
        subgraph "Task Manager"
            PPO["PPO\n(ksim/task/ppo.py)"]:::core
            AMP["AMP\n(ksim/task/amp.py)"]:::core
            RL["RL\n(ksim/task/rl.py)"]:::core
            Teacher["Teacher\n(ksim/task/teacher.py)"]:::core
        end
        Commands["Commands\n(ksim/commands.py)"]:::core
        Actuators["Actuator\n(ksim/actuators.py)"]:::core
        Actions["Actions\n(ksim/actions.py)"]:::core
        Observation["Observation\n(ksim/observation.py)"]:::core
        Dataset["Dataset\n(ksim/dataset.py)"]:::core
        Vis["Visualization\n(ksim/vis.py)"]:::core
    end

    subgraph "Hooks"
        Rewards["Rewards\n(ksim/rewards.py)"]:::hooks
        Terminations["Terminations\n(ksim/terminations.py)"]:::hooks
        Resets["Resets\n(ksim/resets.py)"]:::hooks
        Curriculum["Curriculum\n(ksim/curriculum.py)"]:::hooks
        Randomization["Randomization\n(ksim/randomization.py)"]:::hooks
        Noise["Noise\n(ksim/noise.py)"]:::hooks
    end

    subgraph "Utils"
        MujocoUtils["MuJoCo Wrapper\n(ksim/utils/mujoco.py)"]:::utils
        API["API\n(ksim/utils/api.py)"]:::utils
        Validators["Validators\n(ksim/utils/validators.py)"]:::utils
        Priors["Priors\n(ksim/utils/priors.py)"]:::utils
        Types["Types\n(ksim/types.py)"]:::utils
        Scales["Scales\n(ksim/scales.py)"]:::utils
    end

    subgraph "External Services"
        MuJoCo["MuJoCo Simulator"]:::ext
        JAX["JAX Compute"]:::ext
    end

    US1 -->|"configures"| Engine
    US2 -->|"configures"| Engine

    Engine -->|"uses"| PPO
    Engine -->|"uses"| AMP
    Engine -->|"uses"| RL
    Engine -->|"uses"| Teacher

    Engine -->|"issues commands"| Commands
    Commands -->|"maps to"| Actuators
    Actuators -->|"step"| MuJoCo
    MuJoCo -->|"state"| Observation
    Observation -->|"observations"| Engine

    Engine -->|"logs"| Dataset
    Engine -->|"renders"| Vis

    Engine -->|"callback"| Rewards
    Engine -->|"callback"| Terminations
    Engine -->|"callback"| Resets
    Engine -->|"callback"| Curriculum
    Engine -->|"callback"| Randomization
    Engine -->|"callback"| Noise

    Actuators -->|"calls"| MujocoUtils
    Observation -->|"calls"| MujocoUtils

    Engine -->|"api calls"| API
    Engine -->|"validates"| Validators
    Engine -->|"samples"| Priors

    Engine -->|"uses types"| Types
    Engine -->|"uses scales"| Scales

    Engine -->|"offload compute"| JAX

    click US1 "https://github.com/kscalelabs/ksim/blob/master/examples/kbot/train.py"
    click US2 "https://github.com/kscalelabs/ksim/blob/master/examples/walking.py"
    click Engine "https://github.com/kscalelabs/ksim/blob/master/ksim/engine.py"
    click PPO "https://github.com/kscalelabs/ksim/blob/master/ksim/task/ppo.py"
    click AMP "https://github.com/kscalelabs/ksim/blob/master/ksim/task/amp.py"
    click RL "https://github.com/kscalelabs/ksim/blob/master/ksim/task/rl.py"
    click Teacher "https://github.com/kscalelabs/ksim/blob/master/ksim/task/teacher.py"
    click Commands "https://github.com/kscalelabs/ksim/blob/master/ksim/commands.py"
    click Actuators "https://github.com/kscalelabs/ksim/blob/master/ksim/actuators.py"
    click Actions "https://github.com/kscalelabs/ksim/blob/master/ksim/actions.py"
    click Observation "https://github.com/kscalelabs/ksim/blob/master/ksim/observation.py"
    click Dataset "https://github.com/kscalelabs/ksim/blob/master/ksim/dataset.py"
    click Vis "https://github.com/kscalelabs/ksim/blob/master/ksim/vis.py"
    click Rewards "https://github.com/kscalelabs/ksim/blob/master/ksim/rewards.py"
    click Terminations "https://github.com/kscalelabs/ksim/blob/master/ksim/terminations.py"
    click Resets "https://github.com/kscalelabs/ksim/blob/master/ksim/resets.py"
    click Curriculum "https://github.com/kscalelabs/ksim/blob/master/ksim/curriculum.py"
    click Randomization "https://github.com/kscalelabs/ksim/blob/master/ksim/randomization.py"
    click Noise "https://github.com/kscalelabs/ksim/blob/master/ksim/noise.py"
    click MujocoUtils "https://github.com/kscalelabs/ksim/blob/master/ksim/utils/mujoco.py"
    click API "https://github.com/kscalelabs/ksim/blob/master/ksim/utils/api.py"
    click Validators "https://github.com/kscalelabs/ksim/blob/master/ksim/utils/validators.py"
    click Priors "https://github.com/kscalelabs/ksim/blob/master/ksim/utils/priors.py"
    click Types "https://github.com/kscalelabs/ksim/blob/master/ksim/types.py"
    click Scales "https://github.com/kscalelabs/ksim/blob/master/ksim/scales.py"

    classDef core fill:#f9f,stroke:#333,stroke-width:2px
    classDef hooks fill:#9ff,stroke:#333,stroke-width:2px
    classDef utils fill:#ff9,stroke:#333,stroke-width:2px
    classDef ext fill:#f99,stroke:#333,stroke-width:2px
    classDef user fill:#ccf,stroke:#333,stroke-width:2px
```
