# akhileshpnn/cell-memory architecture

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

- Interactive diagram: https://gitdiagram.com/akhileshpnn/cell-memory
- Repository: https://github.com/akhileshpnn/cell-memory

## Overview

This repo is a **research-grade numerical simulation codebase** used to reproduce results from the eLife paper *“Cells use molecular working memory to navigate in changing chemoattractant fields”*. It is not a single “application” with a runtime service architecture; it’s a **set of computational pipelines** that generate figures via simulation.

There are **two largely independent simulation stacks**:
1. **Polarity model**: 1D reaction–diffusion / stochastic dynamics used to generate **kymographs** and related figure panels.

##### File structure (map folders to architectural boundaries)
Top-level:
- `Polarity model/` → complete simulation package for polarity memory model
- `EgfrPtpSde_main.py` → main orchestrator / entrypoint
- `Models.py` → model equations & parameters (core domain logic)
- `InitialConditions.py` → initial state constructors
- `LaplaceBeltramiOperator.py` → spatial operator / discretization support
- `Experiments.py` → stimulus definitions / experiment scenarios
- `colormaps.py` → visualization helpers (supporting)
- `Physical model of single-cell chemotaxis/` → level set based physical cell simulation
- `LevelSet_main.py` → main orchestrator / entrypoint
- `Kymographs/*.npy` → stored data artifact used as input (e.g., Fig 1D)
- `termConvection.py`, `termreinit.py` → numerical PDE terms (level-set evolution)
- `pressure_functions.py`, `derivFunc.py` → physics/numerics support
- `addGhostExtrapolate.py`, `membrane_index.py`, `utils_.py` → grid/mask/utility helpers
- `plot_functions.py`, `colormaps.py` → visualization helpers
- `README.md` → explicitly states: each folder has a `_main.py` coordinating objects from peers

This strongly suggests each subfolder is a **self-contained pipeline** with:
- entrypoint script (`*_main.py`)
- a set of computational modules (operators/terms/models)
- optional visualization modules
- data artifacts (notably the `.npy` kymograph input)

##### Extract key architectural intent from README (what relationships matter)
From README:
- `EgfrPtpSde_main.py` loads equations/parameters from `Models.py`.
- Typical execution constructs: `model`, `initial_condition`, `lbo`, `stimulus`, then creates `ReactionDiffusion1D(...)` and runs `simulate()`.
- Physical model is heavy compute (~24h CPU), which is a cue to represent **offline batch computation** and possibly checkpoints/outputs.

- **module composition** inside each pipeline
- **data flow between the two pipelines**: *Polarity model → kymograph → Physical model* (even if in practice the kymograph is shipped as a `.npy` artifact)

##### Environment / Execution Context
- Python runtime (>=2.7 per README)
- Local workstation / single CPU execution
- `requirements.txt` as dependency spec

##### Pipeline 1: Polarity model
- `EgfrPtpSde_main.py` (Orchestrator)
- Core modules:
- `Models.py` (model equations/params; EgfrPtp model)
- `InitialConditions.py`
- `LaplaceBeltramiOperator.py` (Periodic operator)
- `Experiments.py` (stimuli like `single_gradient()`)
- Solver object (conceptual): `ReactionDiffusion1D` and `.simulate()` (even if class is inside one of the files; represent it as a logical component)
- Output artifact: **Kymograph** (Figure 1D + supplements)

##### Pipeline 2: Physical model of single-cell chemotaxis
- `LevelSet_main.py` (Orchestrator)
- Input artifact: `Kymographs/Figure1D_Kymograph_Ep_seed(...).npy`
- Core numerical components:
- `termConvection.py` (convection term)
- `termreinit.py` (reinitialization term)
- `pressure_functions.py` (forces/pressure coupling)
- `derivFunc.py` (derivatives / discretization)
- `addGhostExtrapolate.py` (ghost cells / boundary handling)
- `membrane_index.py` (membrane geometry/indexing)
- `utils_.py` (utilities)

**Within Polarity model**
- `EgfrPtpSde_main.py` → calls/loads:
- `Models.py` (build `EgfrPtp()` model)
- `InitialConditions.py` (build `around_steadystate()`)
- `LaplaceBeltramiOperator.py` (build `Periodic()`)
- `Experiments.py` (build `single_gradient()`)
- These feed into → `ReactionDiffusion1D.simulate()` → produces → `kymograph` output

**Between pipelines**
- `kymograph output` → saved as `.npy` (explicit data boundary)
- `.npy` → consumed by `LevelSet_main.py`

**Within Physical model**
- `LevelSet_main.py` → uses numerical term modules (`termConvection`, `termreinit`, etc.) iteratively during simulation loop

**Cross-cutting**
- Visualization (`plot_functions.py`/`colormaps.py`) consumes simulation outputs

##### Architectural patterns/design principles present
- **Entrypoint Orchestrator pattern**: each folder has a `*_main.py` that wires the pipeline.
- **Modular numerical operators**: PDE terms and discretization are split into dedicated modules (esp. in level-set pipeline).
- **Experiment configuration as code**: stimuli and initial conditions are factories/functions (`single_gradient()`, `around_steadystate()`).
- **Artifact-driven coupling** between pipelines: kymographs as serialized `.npy` inputs to the physical model.

##### Relevant technologies/frameworks
Only include what is justified by repo contents:
- Python (>=2.7)
- NumPy (`.npy` artifacts strongly indicate)
- “Level-set method” and “reaction–diffusion 1D solver” as conceptual technologies (domain methods)

##### “Best and most detailed” without overthinking: maximize component separation
Given your instruction to separate into as many components as possible:
- In the polarity model, explicitly show `Models`, `InitialConditions`, `LaplaceBeltramiOperator`, `Experiments` feeding the solver orchestration.

- “construct model parameters”
- “define stimulus field”
- “time-stepping loop”
- “serialize kymograph (.npy)”
- “load kymograph and drive boundary forces”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Environment / Context
  %% =========================
  subgraph "Execution Environment (Offline Batch, Research Reproducibility)"
    direction TB
    PY["Python Runtime (>=2.7)"]:::env
    WS["Local Workstation / Single CPU"]:::env
    REQ["requirements.txt\n(dependency spec)"]:::meta
    RD["README.md\n(execution instructions)"]:::meta
  end

  %% =========================
  %% Pipeline 1: Polarity model
  %% =========================
  subgraph "Pipeline 1: Polarity model (1D reaction–diffusion / stochastic dynamics)"
    direction TB

    P_DIR["Polarity model/"]:::group

    P_MAIN["EgfrPtpSde_main.py\n(Orchestrator / Entrypoint)"]:::orchestrator

    subgraph "Core Science Modules (Polarity)"
      direction TB
      P_MODELS["Models.py\n(equations & parameters)"]:::core
      P_INIT["InitialConditions.py\n(initial state constructors)"]:::core
      P_LBO["LaplaceBeltramiOperator.py\n(periodic spatial operator)"]:::core
      P_EXP["Experiments.py\n(stimulus scenarios)"]:::core
      P_SOLVER["ReactionDiffusion1D\n(simulate())"]:::solver
    end

    P_CMAP["colormaps.py\n(visualization helper)"]:::viz

    P_OUT["Kymograph Output\n(Fig 1D + supplements)"]:::artifact
  end

  %% =========================
  %% Artifact boundary between pipelines
  %% =========================
  subgraph "Artifact-driven Coupling (Serialized Data)"
    direction TB
    NPYSTORE["Kymographs/\n(.npy store)"]:::datastore
    NPY1D["Figure1D_Kymograph_Ep_seed(180988).npy"]:::datafile
  end

  %% =========================
  %% Pipeline 2: Physical model
  %% =========================
  subgraph "Pipeline 2: Physical model of single-cell chemotaxis (Level-set / PDE-based)"
    direction TB

    L_DIR["Physical model of single-cell chemotaxis/"]:::group

    L_MAIN["LevelSet_main.py\n(Orchestrator / Entrypoint)"]:::orchestrator

    subgraph "Core Numerics Modules (Level-set Evolution)"
      direction TB
      L_CONV["termConvection.py\n(convection term)"]:::core
      L_REINIT["termreinit.py\n(reinitialization term)"]:::core
      L_PRESS["pressure_functions.py\n(pressure/force coupling)"]:::core
      L_DERIV["derivFunc.py\n(derivatives / discretization)"]:::core
      L_GHOST["addGhostExtrapolate.py\n(ghost cells / boundary handling)"]:::core
      L_MEM["membrane_index.py\n(membrane geometry/indexing)"]:::core
      L_UTIL["utils_.py\n(utilities)"]:::core
      L_LOOP["Level-set Time-stepping Loop\n(~24h CPU)"]:::solver
    end

    L_PLOT["plot_functions.py\n(plotting helpers)"]:::viz
    L_CMAP["colormaps.py\n(colormaps helper)"]:::viz

    L_OUT["Cell Shapes Output\n(Fig 1E, Fig 4B, etc.)"]:::artifact
  end

  %% =========================
  %% Global relationships
  %% =========================
  WS -->|"runs"| P_MAIN
  WS -->|"runs"| L_MAIN
  PY -->|"executes"| P_MAIN
  PY -->|"executes"| L_MAIN
  REQ -->|"pins dependencies for"| PY
  RD -->|"documents how to run"| WS

  %% Pipeline 1 wiring
  P_DIR --> P_MAIN
  P_MAIN -->|"loads/constructs"| P_MODELS
  P_MAIN -->|"loads/constructs"| P_INIT
  P_MAIN -->|"loads/constructs"| P_LBO
  P_MAIN -->|"loads/constructs"| P_EXP
  P_MODELS -->|"parameters"| P_SOLVER
  P_INIT -->|"initial state"| P_SOLVER
  P_LBO -->|"spatial operator"| P_SOLVER
  P_EXP -->|"stimulus field"| P_SOLVER
  P_MAIN -->|"runs"| P_SOLVER
  P_SOLVER -->|"produces"| P_OUT
  P_OUT -.->|"serialize (.npy)"| NPYSTORE
  NPYSTORE --> NPY1D

  P_OUT -->|"visualize"| P_CMAP

  %% Artifact to Pipeline 2
  NPY1D -.->|"load kymograph"| L_MAIN

  %% Pipeline 2 wiring
  L_DIR --> L_MAIN
  L_MAIN -->|"drives"| L_LOOP
  L_MAIN -->|"uses"| L_CONV
  L_MAIN -->|"uses"| L_REINIT
  L_MAIN -->|"uses"| L_PRESS
  L_MAIN -->|"uses"| L_DERIV
  L_MAIN -->|"uses"| L_GHOST
  L_MAIN -->|"uses"| L_MEM
  L_MAIN -->|"uses"| L_UTIL

  L_CONV -->|"term in loop"| L_LOOP
  L_REINIT -->|"term in loop"| L_LOOP
  L_PRESS -->|"forces"| L_LOOP
  L_DERIV -->|"derivatives"| L_LOOP
  L_GHOST -->|"boundary handling"| L_LOOP
  L_MEM -->|"geometry indexing"| L_LOOP
  L_UTIL -->|"helpers"| L_LOOP

  L_LOOP -->|"produces"| L_OUT
  L_OUT -->|"plot/save"| L_PLOT
  L_OUT -->|"colormap"| L_CMAP

  %% =========================
  %% Click events (component mappings)
  %% =========================
  click REQ "https://github.com/akhileshpnn/cell-memory/blob/main/requirements.txt"
  click RD "https://github.com/akhileshpnn/cell-memory/blob/main/README.md"

  click P_DIR "https://github.com/akhileshpnn/cell-memory/tree/main/Polarity model/"
  click P_MAIN "https://github.com/akhileshpnn/cell-memory/blob/main/Polarity model/EgfrPtpSde_main.py"
  click P_MODELS "https://github.com/akhileshpnn/cell-memory/blob/main/Polarity model/Models.py"
  click P_INIT "https://github.com/akhileshpnn/cell-memory/blob/main/Polarity model/InitialConditions.py"
  click P_LBO "https://github.com/akhileshpnn/cell-memory/blob/main/Polarity model/LaplaceBeltramiOperator.py"
  click P_EXP "https://github.com/akhileshpnn/cell-memory/blob/main/Polarity model/Experiments.py"
  click P_CMAP "https://github.com/akhileshpnn/cell-memory/blob/main/Polarity model/colormaps.py"

  click L_DIR "https://github.com/akhileshpnn/cell-memory/tree/main/Physical model of single-cell chemotaxis/"
  click L_MAIN "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/LevelSet_main.py"
  click NPYSTORE "https://github.com/akhileshpnn/cell-memory/tree/main/Physical model of single-cell chemotaxis/Kymographs/"
  click NPY1D "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/Kymographs/Figure1D_Kymograph_Ep_seed(180988).npy"
  click L_CONV "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/termConvection.py"
  click L_REINIT "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/termreinit.py"
  click L_PRESS "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/pressure_functions.py"
  click L_DERIV "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/derivFunc.py"
  click L_GHOST "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/addGhostExtrapolate.py"
  click L_MEM "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/membrane_index.py"
  click L_UTIL "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/utils_.py"
  click L_PLOT "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/plot_functions.py"
  click L_CMAP "https://github.com/akhileshpnn/cell-memory/blob/main/Physical model of single-cell chemotaxis/colormaps.py"

  %% =========================
  %% Styles
  %% =========================
  classDef env fill:#EEF2FF,stroke:#3B82F6,stroke-width:1px,color:#0F172A
  classDef meta fill:#E0F2FE,stroke:#0284C7,stroke-width:1px,color:#0F172A
  classDef group fill:#F8FAFC,stroke:#94A3B8,stroke-width:1px,color:#0F172A

  classDef orchestrator fill:#1D4ED8,stroke:#0B3AA6,stroke-width:1px,color:#FFFFFF
  classDef core fill:#16A34A,stroke:#0F7A35,stroke-width:1px,color:#052E16
  classDef solver fill:#0EA5A4,stroke:#0F766E,stroke-width:1px,color:#042F2E
  classDef viz fill:#F59E0B,stroke:#B45309,stroke-width:1px,color:#451A03

  classDef artifact fill:#E5E7EB,stroke:#6B7280,stroke-width:1px,color:#111827
  classDef datastore fill:#D1D5DB,stroke:#4B5563,stroke-width:1px,color:#111827
  classDef datafile fill:#F3F4F6,stroke:#374151,stroke-width:1px,color:#111827
```
