How crismicheli/morphy works
1. Repository role and boundary
- Morphy is organized as a scientific Python project around one core model: a scaffold–cell–matrix dynamical system.
- The production code is split between an importable package (viabilitykernels) and a set of orchestration/analysis layers (config, classifiers, plotting, scripts).
- The project is meant to run locally as a simulation-and-visualization toolkit, not as a service or web application.
2. Core simulation package: viabilitykernels/
- This is the computational heart of the repo.
- odes.py defines the system dynamics.
- simulation.py runs trajectories and ensemble experiments over many initial conditions/scenarios.
- viability.py evaluates whether trajectories satisfy viability criteria and produces diagnostics/classifications.
- phase_plane.py holds phase-plane and related visualization helpers for analyzing model behavior geometrically.
3. Model execution flow
- A scenario starts with parameter and bound presets from config/.
- Those settings are fed into the ODE/simulation layer in viabilitykernels/.
- The resulting trajectories are passed into viability diagnostics and classifiers.
- Outputs are then visualized through the plotting helpers and script entry points, often ending as saved figures in figures/.
4. Configuration layer: config/
- default_params.py centralizes default model parameters, bounds, and simulation settings.
- scenarios.py defines reusable scenario presets, likely representing distinct parameter regimes or experimental cases.
- config/__init__.py re-exports the main constants so scripts and notebooks can import a stable API instead of reaching into module internals.
5. Classification subsystem: classifiers/
- This folder contains multiple ways to label or interpret model outcomes:
- static_classifier.py
- temporal_classifier.py
- state_machine_classifier.py
- classifier_dispatch.py appears to select among these strategies.
- The accompanying *_logic.md files indicate the classification logic is intentionally documented separately from the implementation, which suggests this layer is about interpretation of trajectories, not the dynamics themselves.
6. Visualization helpers: plotting/
- plot_helpers.py and plot2d_helpers.py provide reusable plotting primitives.
- scenario_helpers.py likely bridges simulation outputs and plotting calls for scenario-specific layouts.
- The plotting layer is distinct from the simulation layer, so the architecture separates numeric computation from presentation.
7. Scripted workflows: scripts/
- The scripts are the runnable entry points that assemble config, simulation, classification, and plotting into repeatable workflows.
- The tree shows separate entry points for:
- 2D scenario runs and animations
- 3D scenario runs and animations
- single-scenario analysis
- classifier comparisons
- parameter sweeps across all nine scenarios
- This indicates the repo supports both exploratory single-case runs and batch processing over a scenario set.
8. 2D vs 3D analysis paths
- The presence of both animate_scenario_2d.py / run_scenarios_2d.py and the corresponding 3D scripts suggests the project has two visualization modes over the same underlying model.
- The 3D side includes additional analysis variants such as taxonomy plots and quiver-field sweeps, which implies richer geometric analysis in 3D than in 2D.
9. Analysis/documentation artifacts
- notebooks/ is for exploratory, interactive investigation.
- docs/ and scripts/docs/ hold narrative documentation for command-line workflows and figures.
- figures/ is the output boundary for generated graphics.
- These folders are intentionally outside the package boundary, so exploratory work and generated artifacts do not pollute the reusable code.
10. Testing and package structure
- tests/ is present as a future automated verification layer, though the tree suggests it is still minimal.
- pyproject.toml makes the repo installable as a Python package, which matters because scripts and notebooks can import the same internal modules rather than duplicating code.
11. Architectural summary for a diagram
- The most accurate high-level diagram is:
- Inputs: default params + scenario presets
- Core engine: ODE simulation and viability analysis in viabilitykernels
- Interpretation layer: classifiers
- Presentation layer: plotting helpers and scripts
- Outputs: figures, summaries, animations, and notebook-derived analysis
- The main architectural boundary is between model computation and orchestration/visualization; everything else is layered around that boundary.
Main entry points: scenario_helpers.py Scenario plots · simulation.py Simulation · figures Figures · docs Docs
Components 24
Config
Default parameters and reusable scenario presets.
- Defaults · Central model parameters, bounds, and simulation settings.
config/default_params.py - Scenarios · Reusable parameter regimes and experimental cases.
config/scenarios.py - Config API · Stable re-export surface for scripts and notebooks.
config/__init__.py
Core engine
Dynamics, simulation, and viability evaluation.
- Core API · Importable simulation package boundary.
viabilitykernels/__init__.py - ODEs · Scaffold-cell-matrix system equations.
viabilitykernels/odes.py - Simulation · Runs trajectories and ensemble experiments over scenarios.
viabilitykernels/simulation.py - Viability · Evaluates viability criteria and produces diagnostics.
viabilitykernels/viability.py - Phase plane · Phase-plane and related geometric analysis helpers.
viabilitykernels/phase_plane.py
Classifiers
Outcome labeling and interpretation strategies.
- Dispatch · Selects the classifier strategy for a run.
classifiers/classifier_dispatch.py - Static · Labels outcomes with snapshot-based rules.
classifiers/static_classifier.py - Temporal · Labels outcomes from time-evolving trajectory behavior.
classifiers/temporal_classifier.py - State machine · Interprets outcomes through discrete state transitions.
classifiers/state_machine_classifier.py
Plotting
Reusable visualization helpers.
- Plot helpers · Shared plotting primitives and styling helpers.
plotting/plot_helpers.py - 2D helpers · 2D-specific plot construction helpers.
plotting/plot2d_helpers.py - Scenario plots · Bridges scenario outputs to plotting layouts.
plotting/scenario_helpers.py
Scripts
Runnable orchestration and analysis entry points.
- Run 2D · Batch 2D scenario runs.
scripts/run_scenarios_2d.py - Run 3D · Batch 3D scenario runs.
scripts/run_scenarios_3d.py - Single 3D · Single-scenario 3D analysis entry point.
scripts/single_scenario_3d.py - Animate 2D · 2D animation entry point.
scripts/animate_scenario_2d.py - Animate 3D · 3D animation entry point.
scripts/animate_scenario_3d.py - Taxonomy · 3D taxonomy plotting workflow.
scripts/plot_scenario_3d_taxonomy.py
Connections 34
- Config API → Defaults: re-exports · Provides a stable configuration surface.
- Config API → Scenarios: re-exports · Provides scenario presets through one import path.
- Defaults → Simulation: parameters · Supplies default bounds and simulation settings.
- Scenarios → Simulation: scenarios · Feeds preset regimes into runs.
- Core API → ODEs: exposes · Package boundary for dynamics code.
- Core API → Simulation: exposes · Package boundary for trajectory execution.
- Core API → Viability: exposes · Package boundary for viability evaluation.
- ODEs → Simulation: integrates · Simulation advances the ODE system over time.
- Simulation → Viability: produces · Trajectory outputs are assessed for viability.
- Viability → Dispatch: classifies · Routes diagnostics into an interpretation strategy.
- Dispatch → Static: selects · Static labeling strategy.
- Dispatch → Temporal: selects · Time-based labeling strategy.
- Dispatch → State machine: selects · Transition-based labeling strategy.
- Simulation → Phase plane: analyzes · Uses geometric views of model behavior.
- Phase plane → Plot helpers: renders · Feeds geometry into reusable plot primitives.
- Plot helpers → Scenario plots: supports · Scenario-specific plotting composition.
- 2D helpers → Scenario plots: supports · 2D plot construction for scenarios.
- Scenario plots → Run 2D: used by · 2D workflows assemble plots from scenario outputs.
- Scenario plots → Run 3D: used by · 3D workflows assemble plots from scenario outputs.
- Scenario plots → Single 3D: used by · Single-case analysis assembles plots from scenario outputs.
- Scenario plots → Animate 2D: used by · Animation workflow uses shared scenario plotting.
- Scenario plots → Animate 3D: used by · Animation workflow uses shared scenario plotting.
- Scenario plots → Taxonomy: used by · Taxonomy workflow uses shared scenario plotting.
- Run 2D → Figures: writes · Produces saved outputs.
- Run 3D → Figures: writes · Produces saved outputs.
- Single 3D → Figures: writes · Produces saved outputs.
- Animate 2D → Figures: writes · Produces saved outputs.
- Animate 3D → Figures: writes · Produces saved outputs.
- Taxonomy → Figures: writes · Produces saved outputs.
- Docs → Run 2D: documents · Documents command workflows.
- Docs → Animate 2D: documents · Documents command workflows.
- Docs → Animate 3D: documents · Documents command workflows.
- Docs → Single 3D: documents · Documents command workflows.
- Notebook → Core API: explores · Interactive analysis reuses the importable package.