# salazarna/marlem architecture

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

- Interactive diagram: https://gitdiagram.com/salazarna/marlem
- Repository: https://github.com/salazarna/marlem

## Overview

MARLEM simulates decentralized local energy markets and trains/evaluates multi-agent reinforcement-learning policies. Its principal workflow is: agent actions are constrained and validated, converted to orders, cleared into trades, applied to agent/grid state, scored with rewards and coordination metrics, then returned as observations for the next decision. The README documents these stages; sampled source confirms market matching, grid handling, profile generation, coordination metrics, and training behavior. Wiring for unsampled environment modules is represented only where the documented step sequence supports it.

Main entry points: [`src/environment/lem.py`](https://github.com/salazarna/marlem/blob/main/src/environment/lem.py) (Market environment), [`src/market/matching.py`](https://github.com/salazarna/marlem/blob/main/src/market/matching.py) (Market matching), [`src/agent/der.py`](https://github.com/salazarna/marlem/blob/main/src/agent/der.py) (DER agents), [`src/environment/train.py`](https://github.com/salazarna/marlem/blob/main/src/environment/train.py) (RL trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning Environment"]
  node_trainer["RL trainer<br/>[train.py]"]
  node_inference["Policy inference<br/>[inference.py]"]
  node_lem["Market environment<br/>[lem.py]"]
  node_action["Action handling<br/>[action.py]"]
  node_observation["Observations<br/>[observation.py]"]
  node_reward["Rewards<br/>[reward.py]"]
end

subgraph group_market["Market Clearing"]
  node_orders["Orders and trades<br/>[order.py]"]
  node_matching["Market matching<br/>[matching.py]"]
  node_mechanism["Pricing mechanisms<br/>[mechanism.py]"]
  node_validation["Trade validation<br/>[validation.py]"]
  node_reputation["Reputation<br/>[reputation.py]"]
  node_dso["DSO fallback<br/>[dso.py]"]
end

subgraph group_energy["Agents and Grid"]
  node_der["DER agents<br/>[der.py]"]
  node_battery["Battery storage<br/>[battery.py]"]
  node_grid["Grid network<br/>[network.py]"]
end

subgraph group_coordination["Coordination and Analysis"]
  node_cooperation["Implicit cooperation"]
  node_coord_metrics["Coordination metrics"]
  node_grid_metrics["Grid metrics<br/>[grid_metrics.py]"]
  node_market_analytics["Market analytics"]
  node_visualization["Visualization<br/>[plotter.py]"]
end

subgraph group_profiles["Scenario Inputs"]
  node_profiles["DER profiles<br/>[der.py]"]
  node_dso_profiles["DSO profiles<br/>[dso.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"configures training"| node_trainer
node_trainer -->|"creates environment"| node_lem
node_inference -->|"runs episodes"| node_lem
node_lem -->|"processes actions"| node_action
node_lem -->|"constrains actions"| node_der
node_action -->|"forms orders"| node_orders
node_lem -->|"clears orders"| node_matching
node_matching -->|"prices trades"| node_mechanism
node_matching -->|"validates trades"| node_validation
node_matching -->|"checks constraints"| node_grid
node_matching -->|"routes unmatched"| node_dso
node_matching -->|"uses reputation"| node_reputation
node_matching -->|"produces trades"| node_orders
node_lem -->|"updates energy state"| node_der
node_der -->|"updates storage"| node_battery
node_lem -->|"updates grid state"| node_grid
node_lem -->|"computes KPIs"| node_cooperation
node_cooperation -->|"provides KPIs"| node_reward
node_lem -->|"calculates rewards"| node_reward
node_lem -->|"updates reputation"| node_reputation
node_lem -->|"builds observations"| node_observation
node_lem -->|"returns episode results"| node_trainer
node_matching -->|"supplies match history"| node_coord_metrics
node_matching -->|"supplies match history"| node_grid_metrics
node_grid -->|"supplies topology"| node_grid_metrics
node_market_analytics -->|"provides analysis"| node_visualization
node_coord_metrics -->|"provides metrics"| node_visualization
node_grid_metrics -->|"provides metrics"| node_visualization
node_profiles -->|"generates profiles"| node_der
node_dso_profiles -->|"supplies prices"| node_dso

click node_trainer "https://github.com/salazarna/marlem/blob/main/src/environment/train.py"
click node_inference "https://github.com/salazarna/marlem/blob/main/src/environment/inference.py"
click node_lem "https://github.com/salazarna/marlem/blob/main/src/environment/lem.py"
click node_action "https://github.com/salazarna/marlem/blob/main/src/environment/action.py"
click node_observation "https://github.com/salazarna/marlem/blob/main/src/environment/observation.py"
click node_reward "https://github.com/salazarna/marlem/blob/main/src/environment/reward.py"
click node_orders "https://github.com/salazarna/marlem/blob/main/src/market/order.py"
click node_matching "https://github.com/salazarna/marlem/blob/main/src/market/matching.py"
click node_mechanism "https://github.com/salazarna/marlem/blob/main/src/market/mechanism.py"
click node_validation "https://github.com/salazarna/marlem/blob/main/src/market/validation.py"
click node_reputation "https://github.com/salazarna/marlem/blob/main/src/market/reputation.py"
click node_dso "https://github.com/salazarna/marlem/blob/main/src/market/dso.py"
click node_der "https://github.com/salazarna/marlem/blob/main/src/agent/der.py"
click node_battery "https://github.com/salazarna/marlem/blob/main/src/agent/battery.py"
click node_grid "https://github.com/salazarna/marlem/blob/main/src/grid/network.py"
click node_profiles "https://github.com/salazarna/marlem/blob/main/src/profile/der.py"
click node_dso_profiles "https://github.com/salazarna/marlem/blob/main/src/profile/dso.py"
click node_cooperation "https://github.com/salazarna/marlem/blob/main/src/coordination/implicit_cooperation.py"
click node_coord_metrics "https://github.com/salazarna/marlem/blob/main/src/analytics/coordination_metrics.py"
click node_grid_metrics "https://github.com/salazarna/marlem/blob/main/src/analytics/grid_metrics.py"
click node_market_analytics "https://github.com/salazarna/marlem/blob/main/src/analytics/market_analytics.py"
click node_visualization "https://github.com/salazarna/marlem/blob/main/src/visualization/plotter.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_trainer,node_inference,node_lem,node_action,node_observation,node_reward toneBlue
class node_orders,node_matching,node_mechanism,node_validation,node_reputation,node_dso toneAmber
class node_der,node_battery,node_grid toneMint
class node_cooperation,node_coord_metrics,node_grid_metrics,node_market_analytics,node_visualization toneRose
class node_profiles,node_dso_profiles,node_researcher toneIndigo
```

## Components

### Learning Environment

- [RL trainer](https://github.com/salazarna/marlem/blob/main/src/environment/train.py): `src/environment/train.py`
- [Policy inference](https://github.com/salazarna/marlem/blob/main/src/environment/inference.py): `src/environment/inference.py`
- [Market environment](https://github.com/salazarna/marlem/blob/main/src/environment/lem.py): `src/environment/lem.py`
- [Action handling](https://github.com/salazarna/marlem/blob/main/src/environment/action.py): `src/environment/action.py`
- [Observations](https://github.com/salazarna/marlem/blob/main/src/environment/observation.py): `src/environment/observation.py`
- [Rewards](https://github.com/salazarna/marlem/blob/main/src/environment/reward.py): `src/environment/reward.py`

### Market Clearing

- [Orders and trades](https://github.com/salazarna/marlem/blob/main/src/market/order.py): `src/market/order.py`
- [Market matching](https://github.com/salazarna/marlem/blob/main/src/market/matching.py): `src/market/matching.py`
- [Pricing mechanisms](https://github.com/salazarna/marlem/blob/main/src/market/mechanism.py): `src/market/mechanism.py`
- [Trade validation](https://github.com/salazarna/marlem/blob/main/src/market/validation.py): `src/market/validation.py`
- [Reputation](https://github.com/salazarna/marlem/blob/main/src/market/reputation.py): `src/market/reputation.py`
- [DSO fallback](https://github.com/salazarna/marlem/blob/main/src/market/dso.py): `src/market/dso.py`

### Agents and Grid

- [DER agents](https://github.com/salazarna/marlem/blob/main/src/agent/der.py): `src/agent/der.py`
- [Battery storage](https://github.com/salazarna/marlem/blob/main/src/agent/battery.py): `src/agent/battery.py`
- [Grid network](https://github.com/salazarna/marlem/blob/main/src/grid/network.py): `src/grid/network.py`

### Coordination and Analysis

- [Implicit cooperation](https://github.com/salazarna/marlem/blob/main/src/coordination/implicit_cooperation.py): `src/coordination/implicit_cooperation.py`
- [Coordination metrics](https://github.com/salazarna/marlem/blob/main/src/analytics/coordination_metrics.py): `src/analytics/coordination_metrics.py`
- [Grid metrics](https://github.com/salazarna/marlem/blob/main/src/analytics/grid_metrics.py): `src/analytics/grid_metrics.py`
- [Market analytics](https://github.com/salazarna/marlem/blob/main/src/analytics/market_analytics.py): `src/analytics/market_analytics.py`
- [Visualization](https://github.com/salazarna/marlem/blob/main/src/visualization/plotter.py): `src/visualization/plotter.py`

### Scenario Inputs

- [DER profiles](https://github.com/salazarna/marlem/blob/main/src/profile/der.py): `src/profile/der.py`
- [DSO profiles](https://github.com/salazarna/marlem/blob/main/src/profile/dso.py): `src/profile/dso.py`

### Other components

- **Researcher**

## Connections

- Researcher → RL trainer: configures training
- RL trainer → Market environment: creates environment
- Policy inference → Market environment: runs episodes
- Market environment → Action handling: processes actions
- Market environment → DER agents: constrains actions
- Action handling → Orders and trades: forms orders
- Market environment → Market matching: clears orders
- Market matching → Pricing mechanisms: prices trades
- Market matching → Trade validation: validates trades
- Market matching → Grid network: checks constraints
- Market matching → DSO fallback: routes unmatched
- Market matching → Reputation: uses reputation
- Market matching → Orders and trades: produces trades
- Market environment → DER agents: updates energy state
- DER agents → Battery storage: updates storage
- Market environment → Grid network: updates grid state
- Market environment → Implicit cooperation: computes KPIs
- Implicit cooperation → Rewards: provides KPIs
- Market environment → Rewards: calculates rewards
- Market environment → Reputation: updates reputation
- Market environment → Observations: builds observations
- Market environment → RL trainer: returns episode results
- Market matching → Coordination metrics: supplies match history
- Market matching → Grid metrics: supplies match history
- Grid network → Grid metrics: supplies topology
- Market analytics → Visualization: provides analysis
- Coordination metrics → Visualization: provides metrics
- Grid metrics → Visualization: provides metrics
- DER profiles → DER agents: generates profiles
- DSO profiles → DSO fallback: supplies prices