# brusa99/r-mabm architecture

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

- Interactive diagram: https://gitdiagram.com/brusa99/r-mabm
- Repository: https://github.com/brusa99/r-mabm

## Overview

R-MABM provides a multi-agent reinforcement-learning interface to the CATS macroeconomic model. A typical run resets the Gymnasium environment, obtains observations, has agents select actions, advances the Julia-backed economic model, and returns observations, rewards, and termination information; optional training updates Q-learning agents, and optional logging persists episode data. The README and sampled source support this workflow and the documented ABCredit integration. CatsLog is registered in the package, but its implementation was not sampled, so its internal behavior and connections are not shown.

Main entry points: [`rmabm/simulation.py`](https://github.com/brusa99/r-mabm/blob/master/rmabm/simulation.py) (Episode simulation), [`rmabm/environments/cats.py`](https://github.com/brusa99/r-mabm/blob/master/rmabm/environments/cats.py) (CATS environment), [`rmabm/agents/qlearners.py`](https://github.com/brusa99/r-mabm/blob/master/rmabm/agents/qlearners.py) (Q-learning agent), [`rmabm/logger.py`](https://github.com/brusa99/r-mabm/blob/master/rmabm/logger.py) (Episode logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Simulation"]
  node_simulation["Episode simulation<br/>[simulation.py]"]
  node_histories["Episode histories<br/>[simulation.py]"]
end

subgraph group_agents["Agents"]
  node_qlearner["Q-learning agent<br/>[qlearners.py]"]
  node_dummy["Baseline agent<br/>[heuristic.py]"]
end

subgraph group_environment["Economic Environment"]
  node_cats["CATS environment<br/>[cats.py]"]
  node_catslog["Logged CATS variant<br/>[__init__.py]"]
end

subgraph group_persistence["Logging"]
  node_logger["Episode logger<br/>[logger.py]"]
end

node_researcher(("Experiment runner"))
node_abcredit["ABCredit model"]
node_logfiles[("Log files")]

node_researcher -->|"runs episodes"| node_simulation
node_simulation -->|"resets and steps"| node_cats
node_simulation -->|"requests actions"| node_qlearner
node_simulation -->|"requests actions"| node_dummy
node_simulation -->|"passes actions"| node_cats
node_cats -->|"returns transitions"| node_simulation
node_simulation -->|"trains with transitions"| node_qlearner
node_simulation -->|"records transitions"| node_histories
node_qlearner -->|"reads space bounds"| node_cats
node_cats -->|"initializes and advances"| node_abcredit
node_simulation -->|"logs episode data"| node_logger
node_logger -->|"writes arrays"| node_logfiles

click node_simulation "https://github.com/brusa99/r-mabm/blob/master/rmabm/simulation.py"
click node_histories "https://github.com/brusa99/r-mabm/blob/master/rmabm/simulation.py"
click node_qlearner "https://github.com/brusa99/r-mabm/blob/master/rmabm/agents/qlearners.py"
click node_dummy "https://github.com/brusa99/r-mabm/blob/master/rmabm/agents/heuristic.py"
click node_cats "https://github.com/brusa99/r-mabm/blob/master/rmabm/environments/cats.py"
click node_catslog "https://github.com/brusa99/r-mabm/blob/master/rmabm/environments/__init__.py"
click node_logger "https://github.com/brusa99/r-mabm/blob/master/rmabm/logger.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_simulation,node_histories toneBlue
class node_qlearner,node_dummy,node_logfiles toneAmber
class node_cats,node_catslog toneMint
class node_logger toneRose
class node_researcher,node_abcredit toneIndigo
```

## Components

### Simulation

- [Episode simulation](https://github.com/brusa99/r-mabm/blob/master/rmabm/simulation.py): `rmabm/simulation.py`
- [Episode histories](https://github.com/brusa99/r-mabm/blob/master/rmabm/simulation.py): `rmabm/simulation.py`

### Agents

- [Q-learning agent](https://github.com/brusa99/r-mabm/blob/master/rmabm/agents/qlearners.py): `rmabm/agents/qlearners.py`
- [Baseline agent](https://github.com/brusa99/r-mabm/blob/master/rmabm/agents/heuristic.py): `rmabm/agents/heuristic.py`

### Economic Environment

- [CATS environment](https://github.com/brusa99/r-mabm/blob/master/rmabm/environments/cats.py): `rmabm/environments/cats.py`
- [Logged CATS variant](https://github.com/brusa99/r-mabm/blob/master/rmabm/environments/__init__.py): `rmabm/environments/__init__.py`

### Logging

- [Episode logger](https://github.com/brusa99/r-mabm/blob/master/rmabm/logger.py): `rmabm/logger.py`

### Other components

- **Experiment runner**
- **ABCredit model**
- **Log files**

## Connections

- Experiment runner → Episode simulation: runs episodes
- Episode simulation → CATS environment: resets and steps
- Episode simulation → Q-learning agent: requests actions
- Episode simulation → Baseline agent: requests actions
- Episode simulation → CATS environment: passes actions
- CATS environment → Episode simulation: returns transitions
- Episode simulation → Q-learning agent: trains with transitions
- Episode simulation → Episode histories: records transitions
- Q-learning agent → CATS environment: reads space bounds
- CATS environment → ABCredit model: initializes and advances
- Episode simulation → Episode logger: logs episode data
- Episode logger → Log files: writes arrays