# microsoft/mars architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/mars
- Repository: https://github.com/microsoft/mars

## Overview

##### Project Type and Purpose
- MarS is a simulation engine designed to emulate financial market behaviors using generative models. It primarily serves to generate realistic trading environments, simulate order flows, and evaluate the scaling laws of the Large Market Model (LMM).
- The project is split into a core simulation engine (found in mlib) and sample implementations and examples (in market_simulation) showing how to actually run simulations with agents (like a noise agent) and state updates.

##### Analyzing the File Structure
- Top-Level Directories:
- The ".github", "doc", and configuration files (setup.py, pyproject.toml) indicate standard open-source project management and CI/CD configurations.
- "market_simulation": Contains example scripts, agents (e.g., noise_agent), and state implementations (e.g., trade_info_state and trans_state) that demonstrate how to use the engine.
- "mlib": Houses the core simulation engine. The "core" subdirectory includes essential modules such as engine, exchange, environment (Env), orderbook, events, actions, and state-related modules.
- Testing: "mlib/test" shows unit tests for engine and events.
- Utility modules: "mlib/utils" for timing and progress, etc.
- This structure clearly separates core functionality (mlib) from user examples and simulation implementations (market_simulation), which is indicative of a modular design promoting reusability and ease-of-extension.

##### README Insights
- It introduces the concept of a gym-like simulation environment (Env) where agents register and interact.
- It explains how states are updated (for trade information) as orders are traded, and how agents (like the NoiseAgent) work within that simulation context.
- The provided code snippets show the dynamic between agent creation, environment registration, event processing, and state updates.

a. Main Components:
- Simulation Engine (mlib Core):
- Modules such as Engine, Env, Exchange, Orderbook, Events, Actions, and States.
- “mlib/core” modules that implement market mechanics.
- Agents:
- Located in market_simulation/agents (e.g., NoiseAgent) and are built upon base classes in mlib/core/base_agent.py.
- They generate orders and execute actions based on state observations.
- States:
- Implemented in market_simulation/states (e.g., trans_state, trade_info_state) and mlib/core/state.py.
- They capture trading events, order book snapshots, and other market data.
- Environment (Env):
- Acts as the orchestrator similar to gym environments.
- Registers agents, manages events, interacts with the exchange module, and updates states.
- Example Execution Layer:
- The market_simulation/examples, particularly run_simulation.py, demonstrates how to set up and run a simulation.
b. Relationships and Interactions:
- The Env component integrates the Engine, Exchange, and Orderbook modules to simulate market dynamics.
- Agents register with the Env to receive observations and return corresponding actions.
- States are updated via event callbacks (e.g., on_trading, on_open, on_close) whenever a market event occurs.
- An overarching flow exists: initialization → agent registration → event stream processing → state updating → agent action generation → order simulation feedback into the engine.
c. Architectural Patterns and Design Principles:
- Modularity: Clear separation between core simulation (mlib) and example implementations (market_simulation).
- MVC-like Approach: The environment can be seen as a “controller” that manages user inputs (agents’ decisions) and updates “model” components (states and orderbook).
- Event-Driven Architecture: Market events trigger state updates and subsequent agent reactions.
- Extensibility: The design supports adding new agents or states by plugging into predefined interfaces (e.g., the State class and agent base classes).
d. Relevant Technologies/Frameworks:
- Python (versions 3.8 & 3.9) is the base language.
- A gym-like interface (Env) pattern for simulation.
- CI/CD and code-quality tools (as indicated by .github workflows and pre-commit configurations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Simulation Engine (mlib)
    subgraph "Core Simulation Engine (mlib)"
        ENG["Engine"]:::core
        ENV["Environment (Env)"]:::env
        EXC["Exchange"]:::core
        ORB["Orderbook"]:::core
        EVT["Events"]:::core
        ACT["Actions"]:::core
        CSTATE["Core State"]:::core
        BASEA["Base Agent"]:::core
    end

    %% Market Simulation (Examples)
    subgraph "Market Simulation (Examples)"
        NOISE["NoiseAgent"]:::agent
        EXSTATE1["TradeInfo State"]:::example
        EXSTATE2["Trans State"]:::example
        RUNSIM["Run Simulation"]:::example
    end

    %% High-Level Flow
    RUNSIM ---|"initializes"| ENV
    ENV ---|"orchestrates"| ENG
    ENV ---|"orchestrates"| EXC
    ENV ---|"orchestrates"| ORB
    ENV ---|"registers"| NOISE
    ENG ---|"triggers"| EVT
    EVT ---|"updates"| CSTATE
    CSTATE ---|"notifies"| BASEA
    NOISE ---|"generates"| ACT
    ACT ---|"submits"| ENG

    %% Additional Interaction for Example States
    ENV ---|"integrates state"| EXSTATE1
    ENV ---|"integrates state"| EXSTATE2

    %% Click Events
    click ENG "https://github.com/microsoft/mars/blob/main/mlib/core/engine.py"
    click ENV "https://github.com/microsoft/mars/blob/main/mlib/core/env.py"
    click EXC "https://github.com/microsoft/mars/blob/main/mlib/core/exchange.py"
    click ORB "https://github.com/microsoft/mars/blob/main/mlib/core/orderbook.py"
    click EVT "https://github.com/microsoft/mars/blob/main/mlib/core/event.py"
    click ACT "https://github.com/microsoft/mars/blob/main/mlib/core/action.py"
    click CSTATE "https://github.com/microsoft/mars/blob/main/mlib/core/state.py"
    click BASEA "https://github.com/microsoft/mars/blob/main/mlib/core/base_agent.py"
    click NOISE "https://github.com/microsoft/mars/blob/main/market_simulation/agents/noise_agent.py"
    click RUNSIM "https://github.com/microsoft/mars/blob/main/market_simulation/examples/run_simulation.py"
    click EXSTATE1 "https://github.com/microsoft/mars/blob/main/market_simulation/states/trade_info_state.py"
    click EXSTATE2 "https://github.com/microsoft/mars/blob/main/market_simulation/states/trans_state.py"

    %% Styles
    classDef core fill:#FAD7A0,stroke:#E67E22,stroke-width:2px,color:#333;
    classDef env fill:#AED6F1,stroke:#2874A6,stroke-width:2px,color:#333;
    classDef agent fill:#D5F5E3,stroke:#28B463,stroke-width:2px,color:#333;
    classDef example fill:#F9E79F,stroke:#F1C40F,stroke-width:2px,color:#333;
```
