# crismicheli/morphy architecture

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

- Interactive diagram: https://gitdiagram.com/crismicheli/morphy
- Repository: https://github.com/crismicheli/morphy

## Overview

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: [`plotting/scenario_helpers.py`](https://github.com/crismicheli/morphy/blob/main/plotting/scenario_helpers.py) (Scenario plots), [`viabilitykernels/simulation.py`](https://github.com/crismicheli/morphy/blob/main/viabilitykernels/simulation.py) (Simulation), [`figures`](https://github.com/crismicheli/morphy/tree/main/figures) (Figures), [`docs`](https://github.com/crismicheli/morphy/tree/main/docs) (Docs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Config"]
  node_config_defaults["Defaults<br/>params module<br/>[default_params.py]"]
  node_config_scenarios["Scenarios<br/>scenario presets<br/>[scenarios.py]"]
  node_config_api["Config API<br/>package API<br/>[__init__.py]"]
end

subgraph group_core["Core engine"]
  node_core_api["Core API<br/>[__init__.py]"]
  node_odes["ODEs<br/>dynamics module<br/>[odes.py]"]
  node_simulation["Simulation<br/>trajectory engine<br/>[simulation.py]"]
  node_viability["Viability<br/>analysis module<br/>[viability.py]"]
  node_phase_plane["Phase plane<br/>geometry viz<br/>[phase_plane.py]"]
end

subgraph group_classifiers["Classifiers"]
  node_classifier_dispatch["Dispatch<br/>classifier router"]
  node_static_classifier["Static<br/>classifier"]
  node_temporal_classifier["Temporal<br/>classifier"]
  node_state_machine_classifier["State machine<br/>classifier"]
end

subgraph group_plotting["Plotting"]
  node_plot_helpers["Plot helpers<br/>viz primitives<br/>[plot_helpers.py]"]
  node_plot2d_helpers["2D helpers<br/>2d plotting<br/>[plot2d_helpers.py]"]
  node_scenario_helpers["Scenario plots<br/>scenario viz"]
end

subgraph group_workflows["Scripts"]
  node_run_2d["Run 2D<br/>workflow script"]
  node_run_3d["Run 3D<br/>workflow script"]
  node_single_3d["Single 3D<br/>workflow script"]
  node_animate_2d["Animate 2D<br/>workflow script"]
  node_animate_3d["Animate 3D<br/>workflow script"]
  node_taxonomy_3d["Taxonomy<br/>analysis script"]
end

subgraph group_artifacts["Artifacts"]
  node_figures[("Figures<br/>generated output")]
  node_notebooks["Notebook<br/>exploration"]
  node_docs["Docs<br/>workflow notes"]
end

node_config_api -->|"re-exports"| node_config_defaults
node_config_api -->|"re-exports"| node_config_scenarios
node_config_defaults -->|"parameters"| node_simulation
node_config_scenarios -->|"scenarios"| node_simulation
node_core_api -->|"exposes"| node_odes
node_core_api -->|"exposes"| node_simulation
node_core_api -->|"exposes"| node_viability
node_odes -->|"integrates"| node_simulation
node_simulation -->|"produces"| node_viability
node_viability -->|"classifies"| node_classifier_dispatch
node_classifier_dispatch -->|"selects"| node_static_classifier
node_classifier_dispatch -->|"selects"| node_temporal_classifier
node_classifier_dispatch -->|"selects"| node_state_machine_classifier
node_simulation -->|"analyzes"| node_phase_plane
node_phase_plane -->|"renders"| node_plot_helpers
node_plot_helpers -->|"supports"| node_scenario_helpers
node_plot2d_helpers -->|"supports"| node_scenario_helpers
node_scenario_helpers -->|"used by"| node_run_2d
node_scenario_helpers -->|"used by"| node_run_3d
node_scenario_helpers -->|"used by"| node_single_3d
node_scenario_helpers -->|"used by"| node_animate_2d
node_scenario_helpers -->|"used by"| node_animate_3d
node_scenario_helpers -->|"used by"| node_taxonomy_3d
node_run_2d -->|"writes"| node_figures
node_run_3d -->|"writes"| node_figures
node_single_3d -->|"writes"| node_figures
node_animate_2d -->|"writes"| node_figures
node_animate_3d -->|"writes"| node_figures
node_taxonomy_3d -->|"writes"| node_figures
node_docs -.->|"documents"| node_run_2d
node_docs -.->|"documents"| node_animate_2d
node_docs -.->|"documents"| node_animate_3d
node_docs -.->|"documents"| node_single_3d
node_notebooks -.->|"explores"| node_core_api

click node_config_defaults "https://github.com/crismicheli/morphy/blob/main/config/default_params.py"
click node_config_scenarios "https://github.com/crismicheli/morphy/blob/main/config/scenarios.py"
click node_config_api "https://github.com/crismicheli/morphy/blob/main/config/__init__.py"
click node_core_api "https://github.com/crismicheli/morphy/blob/main/viabilitykernels/__init__.py"
click node_odes "https://github.com/crismicheli/morphy/blob/main/viabilitykernels/odes.py"
click node_simulation "https://github.com/crismicheli/morphy/blob/main/viabilitykernels/simulation.py"
click node_viability "https://github.com/crismicheli/morphy/blob/main/viabilitykernels/viability.py"
click node_phase_plane "https://github.com/crismicheli/morphy/blob/main/viabilitykernels/phase_plane.py"
click node_classifier_dispatch "https://github.com/crismicheli/morphy/blob/main/classifiers/classifier_dispatch.py"
click node_static_classifier "https://github.com/crismicheli/morphy/blob/main/classifiers/static_classifier.py"
click node_temporal_classifier "https://github.com/crismicheli/morphy/blob/main/classifiers/temporal_classifier.py"
click node_state_machine_classifier "https://github.com/crismicheli/morphy/blob/main/classifiers/state_machine_classifier.py"
click node_plot_helpers "https://github.com/crismicheli/morphy/blob/main/plotting/plot_helpers.py"
click node_plot2d_helpers "https://github.com/crismicheli/morphy/blob/main/plotting/plot2d_helpers.py"
click node_scenario_helpers "https://github.com/crismicheli/morphy/blob/main/plotting/scenario_helpers.py"
click node_run_2d "https://github.com/crismicheli/morphy/blob/main/scripts/run_scenarios_2d.py"
click node_run_3d "https://github.com/crismicheli/morphy/blob/main/scripts/run_scenarios_3d.py"
click node_single_3d "https://github.com/crismicheli/morphy/blob/main/scripts/single_scenario_3d.py"
click node_animate_2d "https://github.com/crismicheli/morphy/blob/main/scripts/animate_scenario_2d.py"
click node_animate_3d "https://github.com/crismicheli/morphy/blob/main/scripts/animate_scenario_3d.py"
click node_taxonomy_3d "https://github.com/crismicheli/morphy/blob/main/scripts/plot_scenario_3d_taxonomy.py"
click node_figures "https://github.com/crismicheli/morphy/tree/main/figures"
click node_notebooks "https://github.com/crismicheli/morphy/blob/main/notebooks/morphy_scenarios.ipynb"
click node_docs "https://github.com/crismicheli/morphy/tree/main/docs"

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_config_defaults,node_config_scenarios,node_config_api toneBlue
class node_core_api,node_odes,node_simulation,node_viability,node_phase_plane toneAmber
class node_classifier_dispatch,node_static_classifier,node_temporal_classifier,node_state_machine_classifier toneMint
class node_plot_helpers,node_plot2d_helpers,node_scenario_helpers toneRose
class node_run_2d,node_run_3d,node_single_3d,node_animate_2d,node_animate_3d,node_taxonomy_3d toneIndigo
class node_figures,node_notebooks,node_docs toneTeal
```

## Components

### Config

Default parameters and reusable scenario presets.

- [Defaults](https://github.com/crismicheli/morphy/blob/main/config/default_params.py): params module · Central model parameters, bounds, and simulation settings. · `config/default_params.py`
- [Scenarios](https://github.com/crismicheli/morphy/blob/main/config/scenarios.py): scenario presets · Reusable parameter regimes and experimental cases. · `config/scenarios.py`
- [Config API](https://github.com/crismicheli/morphy/blob/main/config/__init__.py): package API · Stable re-export surface for scripts and notebooks. · `config/__init__.py`

### Core engine

Dynamics, simulation, and viability evaluation.

- [Core API](https://github.com/crismicheli/morphy/blob/main/viabilitykernels/__init__.py): package · Importable simulation package boundary. · `viabilitykernels/__init__.py`
- [ODEs](https://github.com/crismicheli/morphy/blob/main/viabilitykernels/odes.py): dynamics module · Scaffold-cell-matrix system equations. · `viabilitykernels/odes.py`
- [Simulation](https://github.com/crismicheli/morphy/blob/main/viabilitykernels/simulation.py): trajectory engine · Runs trajectories and ensemble experiments over scenarios. · `viabilitykernels/simulation.py`
- [Viability](https://github.com/crismicheli/morphy/blob/main/viabilitykernels/viability.py): analysis module · Evaluates viability criteria and produces diagnostics. · `viabilitykernels/viability.py`
- [Phase plane](https://github.com/crismicheli/morphy/blob/main/viabilitykernels/phase_plane.py): geometry viz · Phase-plane and related geometric analysis helpers. · `viabilitykernels/phase_plane.py`

### Classifiers

Outcome labeling and interpretation strategies.

- [Dispatch](https://github.com/crismicheli/morphy/blob/main/classifiers/classifier_dispatch.py): classifier router · Selects the classifier strategy for a run. · `classifiers/classifier_dispatch.py`
- [Static](https://github.com/crismicheli/morphy/blob/main/classifiers/static_classifier.py): classifier · Labels outcomes with snapshot-based rules. · `classifiers/static_classifier.py`
- [Temporal](https://github.com/crismicheli/morphy/blob/main/classifiers/temporal_classifier.py): classifier · Labels outcomes from time-evolving trajectory behavior. · `classifiers/temporal_classifier.py`
- [State machine](https://github.com/crismicheli/morphy/blob/main/classifiers/state_machine_classifier.py): classifier · Interprets outcomes through discrete state transitions. · `classifiers/state_machine_classifier.py`

### Plotting

Reusable visualization helpers.

- [Plot helpers](https://github.com/crismicheli/morphy/blob/main/plotting/plot_helpers.py): viz primitives · Shared plotting primitives and styling helpers. · `plotting/plot_helpers.py`
- [2D helpers](https://github.com/crismicheli/morphy/blob/main/plotting/plot2d_helpers.py): 2d plotting · 2D-specific plot construction helpers. · `plotting/plot2d_helpers.py`
- [Scenario plots](https://github.com/crismicheli/morphy/blob/main/plotting/scenario_helpers.py): scenario viz · Bridges scenario outputs to plotting layouts. · `plotting/scenario_helpers.py`

### Scripts

Runnable orchestration and analysis entry points.

- [Run 2D](https://github.com/crismicheli/morphy/blob/main/scripts/run_scenarios_2d.py): workflow script · Batch 2D scenario runs. · `scripts/run_scenarios_2d.py`
- [Run 3D](https://github.com/crismicheli/morphy/blob/main/scripts/run_scenarios_3d.py): workflow script · Batch 3D scenario runs. · `scripts/run_scenarios_3d.py`
- [Single 3D](https://github.com/crismicheli/morphy/blob/main/scripts/single_scenario_3d.py): workflow script · Single-scenario 3D analysis entry point. · `scripts/single_scenario_3d.py`
- [Animate 2D](https://github.com/crismicheli/morphy/blob/main/scripts/animate_scenario_2d.py): workflow script · 2D animation entry point. · `scripts/animate_scenario_2d.py`
- [Animate 3D](https://github.com/crismicheli/morphy/blob/main/scripts/animate_scenario_3d.py): workflow script · 3D animation entry point. · `scripts/animate_scenario_3d.py`
- [Taxonomy](https://github.com/crismicheli/morphy/blob/main/scripts/plot_scenario_3d_taxonomy.py): analysis script · 3D taxonomy plotting workflow. · `scripts/plot_scenario_3d_taxonomy.py`

### Artifacts

Generated outputs and exploratory analysis.

- [Figures](https://github.com/crismicheli/morphy/tree/main/figures): generated output · Saved plots, animations, and visual outputs. · `figures`
- [Notebook](https://github.com/crismicheli/morphy/blob/main/notebooks/morphy_scenarios.ipynb): exploration · Interactive exploratory analysis. · `notebooks/morphy_scenarios.ipynb`
- [Docs](https://github.com/crismicheli/morphy/tree/main/docs): workflow notes · Narrative command and figure documentation. · `docs`

## Connections

- 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.