How akhileshpnn/cell-memory works
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”