# mit-emze/cimloop architecture

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

- Interactive diagram: https://gitdiagram.com/mit-emze/cimloop
- Repository: https://github.com/mit-emze/cimloop

## Overview

CiMLoop is a configurable compute-in-memory (CiM) architecture modeling tool built around Timeloop and Accelergy. Users select macro, tile, chip, and system models and workload layers; the workspace combines those descriptions into a specification, runs mapping and energy estimation, and provides results for analysis. The repository also supplies published architecture models, memory-cell and component models, photonic accelerator examples, and scripts for parsing and plotting results. Source excerpts show the modeling and analysis utilities, but not every runtime detail; some subsystem links below reflect README documentation or remain unverified.

Main entry points: [`workspace/scripts/utils.py`](https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/utils.py) (Spec Builder), [`workspace/models/arch`](https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch) (Architecture Models), [`workspace/scripts/tl_output_parsing.py`](https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/tl_output_parsing.py) (Output Parsing), [`workspace/models/components/accelergy_plug_ins/X2X_ladder.py`](https://github.com/mit-emze/cimloop/blob/main/workspace/models/components/accelergy_plug_ins/X2X_ladder.py) (Energy Plug-ins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model_inputs["Model Inputs"]
  node_architectures["Architecture Models"]
  node_workloads["Workload Layers"]
  node_cell_models["Memory Cells"]
  node_component_models["Component Models"]
  node_macro_models["Macro Models"]
  node_tile_models["Tile Models"]
  node_chip_models["Chip Models"]
  node_system_models["System Models"]
  node_model_includes["Model Includes"]
end

subgraph group_model_engine["Modeling Engine"]
  node_top_template["Top Specification<br/>[top.yaml.jinja2]"]
  node_spec_builder["Spec Builder<br/>[utils.py]"]
  node_array_processor["Array Processor<br/>[processors.py]"]
  node_mapper["Mapper Runner<br/>[utils.py]"]
  node_accelergy_plugins["Energy Plug-ins<br/>[X2X_ladder.py]"]
  node_bit_helpers["Bit Helpers<br/>[bit_functions.py]"]
  node_misc_helpers["Circuit Helpers<br/>[misc.py]"]
end

subgraph group_analysis["Analysis"]
  node_result_parser["Output Parsing"]
  node_result_utils["Result Utilities<br/>[utils.py]"]
  node_notebook_tools["Notebook Tools<br/>[notebook_utils.py]"]
  node_plotting["Result Plotting<br/>[plots.py]"]
  node_results["Model Results"]
end

subgraph group_integrations["External Tools"]
  node_timeloop["Timeloop"]
  node_accelergy["Accelergy"]
end

node_user(("Modeler"))

node_user -->|"selects models"| node_architectures
node_user -->|"selects workloads"| node_workloads
node_architectures -->|"configures"| node_spec_builder
node_workloads -->|"configures"| node_spec_builder
node_cell_models -.->|"configures"| node_spec_builder
node_component_models -.->|"configures"| node_spec_builder
node_macro_models -->|"specializes"| node_architectures
node_tile_models -.->|"defines stage"| node_architectures
node_chip_models -.->|"defines stage"| node_architectures
node_system_models -.->|"defines stage"| node_architectures
node_model_includes -.->|"supplies config"| node_spec_builder
node_top_template -->|"builds from"| node_spec_builder
node_spec_builder -->|"configures"| node_array_processor
node_spec_builder -->|"runs specification"| node_mapper
node_mapper -->|"invokes"| node_timeloop
node_mapper -->|"invokes estimation"| node_accelergy
node_accelergy_plugins -->|"uses"| node_bit_helpers
node_accelergy_plugins -->|"uses"| node_misc_helpers
node_mapper -.->|"parses output"| node_result_parser
node_result_parser -.->|"produces"| node_results
node_result_utils -->|"uses"| node_result_parser
node_result_utils -->|"uses"| node_plotting
node_notebook_tools -->|"uses"| node_result_utils
node_results -.->|"visualizes"| node_plotting

click node_architectures "https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch"
click node_workloads "https://github.com/mit-emze/cimloop/tree/main/workspace/models/workloads"
click node_cell_models "https://github.com/mit-emze/cimloop/tree/main/workspace/models/memory_cells"
click node_component_models "https://github.com/mit-emze/cimloop/tree/main/workspace/models/components"
click node_macro_models "https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch/1_macro"
click node_tile_models "https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch/2_tile"
click node_chip_models "https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch/3_chip"
click node_system_models "https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch/4_system"
click node_model_includes "https://github.com/mit-emze/cimloop/tree/main/workspace/models/include"
click node_top_template "https://github.com/mit-emze/cimloop/blob/main/workspace/models/top.yaml.jinja2"
click node_spec_builder "https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/utils.py"
click node_array_processor "https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/processors.py"
click node_mapper "https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/utils.py"
click node_accelergy_plugins "https://github.com/mit-emze/cimloop/blob/main/workspace/models/components/accelergy_plug_ins/X2X_ladder.py"
click node_bit_helpers "https://github.com/mit-emze/cimloop/blob/main/workspace/models/components/accelergy_plug_ins/utils/bit_functions.py"
click node_misc_helpers "https://github.com/mit-emze/cimloop/blob/main/workspace/models/components/accelergy_plug_ins/misc.py"
click node_result_parser "https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/tl_output_parsing.py"
click node_result_utils "https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/utils.py"
click node_notebook_tools "https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/notebook_utils.py"
click node_plotting "https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/plots.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_architectures,node_workloads,node_cell_models,node_component_models,node_macro_models,node_tile_models,node_chip_models,node_system_models,node_model_includes toneBlue
class node_top_template,node_spec_builder,node_array_processor,node_mapper,node_accelergy_plugins,node_bit_helpers,node_misc_helpers toneAmber
class node_result_parser,node_result_utils,node_notebook_tools,node_plotting,node_results toneMint
class node_timeloop,node_accelergy toneRose
class node_user toneIndigo
```

## Components

### Model Inputs

- [Architecture Models](https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch): `workspace/models/arch`
- [Workload Layers](https://github.com/mit-emze/cimloop/tree/main/workspace/models/workloads): `workspace/models/workloads`
- [Memory Cells](https://github.com/mit-emze/cimloop/tree/main/workspace/models/memory_cells): `workspace/models/memory_cells`
- [Component Models](https://github.com/mit-emze/cimloop/tree/main/workspace/models/components): `workspace/models/components`
- [Macro Models](https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch/1_macro): `workspace/models/arch/1_macro`
- [Tile Models](https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch/2_tile): `workspace/models/arch/2_tile`
- [Chip Models](https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch/3_chip): `workspace/models/arch/3_chip`
- [System Models](https://github.com/mit-emze/cimloop/tree/main/workspace/models/arch/4_system): `workspace/models/arch/4_system`
- [Model Includes](https://github.com/mit-emze/cimloop/tree/main/workspace/models/include): `workspace/models/include`

### Modeling Engine

- [Top Specification](https://github.com/mit-emze/cimloop/blob/main/workspace/models/top.yaml.jinja2): `workspace/models/top.yaml.jinja2`
- [Spec Builder](https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/utils.py): `workspace/scripts/utils.py`
- [Array Processor](https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/processors.py): `workspace/scripts/processors.py`
- [Mapper Runner](https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/utils.py): `workspace/scripts/utils.py`
- [Energy Plug-ins](https://github.com/mit-emze/cimloop/blob/main/workspace/models/components/accelergy_plug_ins/X2X_ladder.py): `workspace/models/components/accelergy_plug_ins/X2X_ladder.py`
- [Bit Helpers](https://github.com/mit-emze/cimloop/blob/main/workspace/models/components/accelergy_plug_ins/utils/bit_functions.py): `workspace/models/components/accelergy_plug_ins/utils/bit_functions.py`
- [Circuit Helpers](https://github.com/mit-emze/cimloop/blob/main/workspace/models/components/accelergy_plug_ins/misc.py): `workspace/models/components/accelergy_plug_ins/misc.py`

### Analysis

- [Output Parsing](https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/tl_output_parsing.py): `workspace/scripts/tl_output_parsing.py`
- [Result Utilities](https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/utils.py): `workspace/scripts/utils.py`
- [Notebook Tools](https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/notebook_utils.py): `workspace/scripts/notebook_utils.py`
- [Result Plotting](https://github.com/mit-emze/cimloop/blob/main/workspace/scripts/plots.py): `workspace/scripts/plots.py`
- **Model Results**

### External Tools

- **Timeloop**
- **Accelergy**

### Other components

- **Modeler**

## Connections

- Modeler → Architecture Models: selects models (evidence: `README.md`)
- Modeler → Workload Layers: selects workloads (evidence: `README.md`)
- Architecture Models → Spec Builder: configures (evidence: `workspace/scripts/utils.py`)
- Workload Layers → Spec Builder: configures (evidence: `workspace/scripts/utils.py`)
- Memory Cells → Spec Builder: configures
- Component Models → Spec Builder: configures
- Macro Models → Architecture Models: specializes (evidence: `README.md`)
- Tile Models → Architecture Models: defines stage
- Chip Models → Architecture Models: defines stage
- System Models → Architecture Models: defines stage
- Model Includes → Spec Builder: supplies config
- Top Specification → Spec Builder: builds from (evidence: `workspace/scripts/utils.py`)
- Spec Builder → Array Processor: configures (evidence: `workspace/scripts/utils.py`)
- Spec Builder → Mapper Runner: runs specification (evidence: `workspace/scripts/utils.py`)
- Mapper Runner → Timeloop: invokes (evidence: `workspace/scripts/utils.py`)
- Mapper Runner → Accelergy: invokes estimation (evidence: `workspace/scripts/utils.py`)
- Energy Plug-ins → Bit Helpers: uses (evidence: `workspace/models/components/accelergy_plug_ins/X2X_ladder.py`)
- Energy Plug-ins → Circuit Helpers: uses (evidence: `workspace/models/components/accelergy_plug_ins/X2X_ladder.py`)
- Mapper Runner → Output Parsing: parses output (evidence: `workspace/scripts/utils.py`)
- Output Parsing → Model Results: produces
- Result Utilities → Output Parsing: uses (evidence: `workspace/scripts/utils.py`)
- Result Utilities → Result Plotting: uses (evidence: `workspace/scripts/utils.py`)
- Notebook Tools → Result Utilities: uses (evidence: `workspace/scripts/notebook_utils.py`)
- Model Results → Result Plotting: visualizes