MyVertexModel

A 2D epithelial vertex model implementation for simulating tissue mechanics. It represents a confluent tissue as polygons (cells) whose vertices are shared in a global pool, enabling physically consistent multi-cell interactions. The implementation includes:

• Complete energy functional with area elasticity, perimeter contractility, and line (junction) tension terms
• Gradient descent simulation with global vertex coupling for mechanical equilibration
• Global vertex pool with automatic merging and reconstruction capabilities
• Cell division (cytokinesis) with contractile ring simulation and topological splitting
• ACAM tissue import with topology-aware conversion from center-based models
• Cell growth simulation with configurable parameters and organized output folders
• Comprehensive validation tools for tissue structure integrity
• Enhanced visualization with cell and vertex ID labeling
• Tissue builders for honeycomb and grid patterns
• Extensive test suite and documentation

Features

Core Implementation

• Cell & Tissue data structures with dual representation (local vertices + global vertex pool)
• Global vertex pool with build_global_vertices() and reconstruct_cell_vertices() methods
• Energy functional: $E = \tfrac{1}{2} k_{\text{area}} (A - A_0)^2 + \tfrac{1}{2} k_{\text{perimeter}} P^2 + \gamma, P$
• Gradient computation: Analytical gradient $\nabla E$ implemented; central finite differences used for verification
• Simulation engine: Configurable timestep, damping, and epsilon parameters
• Validation suite: Polygon validity, CCW ordering, duplicate vertex detection

Topological Transitions

• Cytokinesis (cell division): Complete implementation with:
  • Automatic or manual division axis computation
  • Contracting vertices simulating actomyosin ring
  • Active contractile forces integrated with simulation
  • Topological splitting into daughter cells
  • See docs/CYTOKINESIS_GUIDE.md for detailed documentation

Tissue Building & Import

• Honeycomb builders: 14-cell (2-3-4-3-2) and 19-cell (3-4-5-4-3) patterns
• Grid builder: Rectangular tissue lattices
• ACAM tissue conversion: Midpoint-adhesion pipeline implemented in scripts/tissue_acam_to_vertex.py (uses adhesions, PCA-based polylines, endpoint clustering, and edge refinement)
• Automatic global vertex pool construction with tolerance-based merging

Simulation & Analysis

• Cell growth simulation (examples/simulate_cell_growth.py):
  • Single or multi-cell growth with gradual target area increase
  • Comma-separated cell IDs for growing multiple cells simultaneously
  • Global vertex coupling for mechanical consistency
  • Organized output in unique Sim_* folders per run
  • CSV tracking and PNG visualization for all growing cells
• Parameter diagnostic tools for stability testing
• Tissue comparison and validation utilities
• Overdamped Force–Balance (OFB) Solver:
  • Supports overdamped dynamics mode with force-derived global vertex updates
  • Explicit Euler integration: γ · dx/dt = F = −∇E + η
  • Flags for solver selection, friction, noise, and random seed
  • Tuning guidance for dt/gamma, with practical tips for stable growth

Visualization

• Enhanced plotting with plot_tissue():
  • Optional cell ID labels (yellow)
  • Optional vertex ID labels (red, showing global indices)
  • Customizable colors, transparency, and styling
• Diagnostic visualizations for connectivity and structure analysis

Validation & Diagnostics

• Cell-by-cell validation (tests/test_tissue_cell_by_cell.py):
  • Tests all tissues for structural integrity
  • Detects duplicate consecutive vertices
  • Validates CCW ordering, polygon validity, vertex sharing
• Tissue diagnostic tool (examples/diagnose_tissue.py):
  • Structure analysis with detailed metrics
  • Tissue comparison capability
  • Automated repair for duplicate vertices and CCW violations
  • Visualization of connectivity issues

Installation

You can work with this project using uv (fastest), pip/venv, or conda. Each method installs the same dependencies defined in pyproject.toml.

Option A — uv (fastest and reproducible)

Install uv once and let it handle environments and dependency resolution:

# Install uv (one‑time, via pipx or pip)
pipx install uv  # or: pip install --user uv

# Create a virtual environment and sync dependencies
uv venv          # creates .venv in the current directory
uv sync          # installs dependencies from pyproject.toml

# Activate and run your code
source .venv/bin/activate
uv run python -m myvertexmodel  # adjust entrypoint as needed

uv sync resolves and installs the packages declared in your pyproject.toml and lock file.

Option B — pip + venv (standard)

Use standard Python tooling:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

This creates a local virtual environment (.venv) and installs your package in editable mode along with the optional dev extras.

Option C — conda (base environment + pip)

If you prefer conda for Python itself or compiled dependencies, keep the environment.yml minimal and install Python packages via pip:

conda env create -f environment.yml
conda activate myvertexmodel

# Upgrade pip and install the project
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

This pattern ensures conda provides Python and any heavy system libraries, while the actual Python packages come from pyproject.toml, so all three workflows stay in sync.

Quick Start

Cell Division (Cytokinesis)

Simulate cell division with contractile ring constriction:

# Run the cytokinesis demonstration
python examples/demonstrate_cytokinesis.py

This example shows:

1. A single cell with contracting vertices inserted at the division line
2. Simulation with active contractile forces (actomyosin ring)
3. Constriction of the division plane
4. Topological splitting into two daughter cells

See docs/CYTOKINESIS_GUIDE.md for detailed API documentation and examples.

Cell Growth Simulation

Simulate a single cell growing in a honeycomb tissue:

# Honeycomb tissue (14 cells), cell 7 grows, creates output folder
python examples/simulate_cell_growth.py \
  --build-honeycomb 14 \
  --growing-cell-ids 7 \
  --total-steps 100 \
  --plot

Simulate multiple cells growing simultaneously:

# Multiple cells growing at once
python examples/simulate_cell_growth.py \
  --build-honeycomb 14 \
  --growing-cell-ids 3,7,10 \
  --total-steps 100 \
  --plot

Simulate with ACAM tissue (requires smaller timestep):

# ACAM tissue (~79 cells), single cell growth
python examples/simulate_cell_growth.py \
  --tissue-file pickled_tissues/acam_79cells.dill \
  --growing-cell-ids AR \
  --total-steps 100 \
  --dt 0.00001 \
  --plot --enable-merge

# ACAM tissue with multiple cells growing
python examples/simulate_cell_growth.py \
  --tissue-file pickled_tissues/acam_79cells.dill \
  --growing-cell-ids I,AW,AB,AA,V,BF,AV,BR,AL \
  --total-steps 100 \
  --dt 0.00001 \
  --plot --enable-merge

Output: Creates a unique Sim_<tissue>_<cells>_<timestamp>_<random>/ folder containing:

• growth_tracking.csv - Area, energy, and progress data for all growing cells
• growth_initial.png - Initial tissue state
• growth_final.png - Final tissue state

ACAM Tissue Conversion

Convert ACAM center-based model to vertex model (midpoint-adhesion method only):

# Convert ACAM to vertex model using the supported pipeline
python scripts/tissue_acam_to_vertex.py --acam-file acam_tissues/20_cells_adhesion --output pickled_tissues/vertex_20cells.dill

Note: Only the midpoint-adhesion pipeline in scripts/tissue_acam_to_vertex.py is supported for ACAM→vertex conversion.

Important: Always validate and repair ACAM tissues after conversion:

# Validate structure
pytest tests/test_tissue_cell_by_cell.py -v

# Repair if needed (removes duplicate consecutive vertices)
python examples/diagnose_tissue.py pickled_tissues/vertex_20cells.dill --repair --save-repaired pickled_tissues/vertex_20cells_repaired.dill

Tissue Validation

Validate any tissue structure:

# Run comprehensive validation
pytest tests/test_tissue_cell_by_cell.py::test_tissue_cell_by_cell -v -s

# Diagnose specific tissue
python examples/diagnose_tissue.py pickled_tissues/YOUR_TISSUE.dill

# Compare with reference tissue
python examples/diagnose_tissue.py pickled_tissues/YOUR_TISSUE.dill \
  --reference pickled_tissues/honeycomb_14cells.dill

Visualization

Plot tissue with cell and vertex IDs:

from myvertexmodel import load_tissue, plot_tissue
import matplotlib.pyplot as plt

tissue = load_tissue('pickled_tissues/honeycomb_14cells.dill')

# Plot with labels
plot_tissue(tissue, show_cell_ids=True, show_vertex_ids=True)
plt.savefig('tissue_labeled.png', dpi=150)
plt.show()

Installation

Using conda with the provided environment specification:

# Create environment
conda env create -f environment.yml
# Activate
conda activate myvertexmodel
# Editable install (pyproject.toml present)
pip install -e .

If you update dependencies, regenerate the environment or adjust environment.yml accordingly.

Running Tests

The project has comprehensive test coverage:

# Run all tests
python -m pytest -v

# Run specific test modules
python -m pytest tests/test_basic.py -v              # Core functionality
python -m pytest tests/test_tissue_structure.py -v   # Structure validation
python -m pytest tests/test_tissue_cell_by_cell.py -v # Cell-by-cell validation

# Quiet mode
python -m pytest -q

# With output (shows print statements)
python -m pytest -v -s

Key Test Modules

• tests/test_basic.py: Core geometry, energy, and simulation tests
• tests/test_tissue_structure.py: Tissue structure validation and comparison
• tests/test_tissue_cell_by_cell.py: Comprehensive cell-by-cell validation for all tissues
  • Validates all pickled tissues
  • Checks for duplicate consecutive vertices
  • Validates CCW ordering and polygon validity
  • Reports structural issues and connectivity

CLI Usage

Basic Demo Simulation

Run a small simulation (2×2 grid, 10 steps) and show a plot:

python -m myvertexmodel --steps 10 --grid-size 2 --plot

Customize parameters:

python -m myvertexmodel \
  --steps 20 \
  --grid-size 3 \
  --dt 0.02 \
  --k-area 2.0 \
  --k-perimeter 0.25 \
  --gamma 0.1 \
  --target-area 0.8 \
  --epsilon 1e-5 \
  --damping 0.5 \
  --plot --output tissue_custom.png

Suppress energy printing:

python -m myvertexmodel --no-energy-print

Cell Growth Simulation (Recommended)

For realistic simulations, use the dedicated growth script:

# Honeycomb tissue - single cell
python examples/simulate_cell_growth.py \
  --build-honeycomb 14 \
  --growing-cell-ids 7 \
  --total-steps 100 \
  --dt 0.01 \
  --plot

# Honeycomb tissue - multiple cells
python examples/simulate_cell_growth.py \
  --build-honeycomb 14 \
  --growing-cell-ids 3,7,10 \
  --total-steps 100 \
  --dt 0.01 \
  --plot

# ACAM tissue - single cell (use smaller timestep)
python examples/simulate_cell_growth.py \
  --tissue-file pickled_tissues/acam_79cells.dill \
  --growing-cell-ids AR \
  --total-steps 100 \
  --dt 0.00001 \
  --plot --enable-merge

# ACAM tissue - multiple cells
python examples/simulate_cell_growth.py \
  --tissue-file pickled_tissues/acam_79cells.dill \
  --growing-cell-ids I,AW,AB,AA,V,BF,AV,BR,AL \
  --total-steps 100 \
  --dt 0.00001 \
  --plot --enable-merge

Key Options:

• --growing-cell-ids: Comma-separated list of cell IDs to grow (e.g., 7 or I,AW,AB)
• --enable-merge: Enable periodic vertex merging during simulation
• --solver: Choose gradient_descent (default) or overdamped_force_balance
• See python examples/simulate_cell_growth.py --help for all options

See Quick Start for more examples.

Plotting Example Script

A minimal example is provided in examples/plot_example.py:

python examples/plot_example.py

This script constructs a simple tissue and renders it with matplotlib.

Design & Documentation

Design Document

See docs/design_vertex_model.md for technical details:

• Implemented features: Global vertex pool, energy functional, simulation engine
• Data structures: Dual representation (local + global vertices), Cell.vertex_indices
• Energy formula: $E = \frac{1}{2}k_{\text{area}}(A-A_0)^2 + \frac{1}{2}k_{\text{perimeter}}\cdot P^2 + \gamma\cdot P$
• Gradient computation: Finite differences + analytical implementation
• Future extensions: Topological transitions (T1, division), adaptive timestep

Additional Documentation

• docs/ACAM_CONVERSION_GUIDE.md: Complete guide for ACAM tissue conversion

  • Topology-aware conversion workflow
  • Known issues and validation requirements
  • Simulation parameters for ACAM tissues
  • Troubleshooting duplicate consecutive vertices

• ACAM_DIAGNOSTIC_SUMMARY.md: Analysis of ACAM tissue issues and solutions

• ACAM_SIMULATION_SUMMARY.md: Simulation parameters and stability guide

• TISSUE_VALIDATION_RESULTS.md: Validation tool documentation

• VISUALIZATION_COMPLETE.md: Enhanced plotting features guide

Key References

• Farhadifar et al. 2007. The influence of cell mechanics on epithelial morphogenesis. DOI:10.1016/j.cub.2007.11.049
• Nagai & Honda 2009. A dynamic cell model for the formation of epithelial tissues. DOI:10.1016/j.physd.2009.01.001

Project Structure

environment.yml                    # Conda environment specification
pyproject.toml                     # Package metadata / editable install
README.md                          # This file
.gitignore                         # Git ignore patterns (includes Sim_*/)

src/myvertexmodel/                 # Core package modules
├── __init__.py                    # Package exports
├── core.py                        # Cell, Tissue classes, global vertex pool
├── energy.py                      # Energy parameters and computation (EnergyParameters, cell_energy, tissue_energy)
├── mesh_ops.py                    # Mesh operations (merge_nearby_vertices, mesh_edges)
├── geometry.py                    # Polygon geometry calculations
├── simulation.py                  # Simulation engine
├── plotting.py                    # Visualization (enhanced with ID labels)
├── builders.py                    # Tissue builders (honeycomb, grid)
└── io.py                          # Save/load utilities

examples/                          # Example scripts
├── simulate_cell_growth.py        # Cell growth simulation (single or multi-cell, creates Sim_*/ folders)
├── diagnose_tissue.py             # Tissue validation and repair tool
├── diagnose_acam_simulation.py    # ACAM parameter diagnostic
├── plot_acam_79cells_labeled.py   # Visualization with labels
├── plot_problem_cells_detail.py   # Detailed cell inspection
└── ...                            # Additional examples

tests/                             # Pytest suite
├── test_basic.py                  # Core functionality tests
├── test_tissue_structure.py       # Structure validation tests
└── test_tissue_cell_by_cell.py    # Comprehensive cell-by-cell validation

docs/                              # Documentation
├── DESIGN_VERTEX_MODEL.md         # Technical design document
├── ACAM_CONVERSION_GUIDE.md       # ACAM conversion guide
└── ...                            # Additional documentation

scripts/                           # Utility scripts
└── tissue_acam_to_vertex.py       # Main ACAM→vertex conversion CLI tool (midpoint-adhesion pipeline)

pickled_tissues/                   # Pre-built tissue files (.dill)
acam_tissues/                      # ACAM source data
Sim_*/                             # Simulation output folders (gitignored)

Future Development

Implemented Features

1. ✅ Cell division (cytokinesis):
   • Contracting vertices simulating actomyosin ring
   • Active contractile forces integrated with simulation
   • Topological splitting into daughter cells
   • See docs/CYTOKINESIS_GUIDE.md

Planned Features

1. Additional topological transitions:

   • T1 transitions (edge swaps for neighbor rearrangement)
   • Cell extrusion/apoptosis (polygon removal)
   • Automated multi-cell division cascades

2. Adaptive simulation:

   • Adaptive timestep based on gradient magnitude
   • Energy-based step acceptance/rejection
   • Automatic parameter tuning for different tissue sizes

3. Enhanced mechanics:

   • Per-edge heterogeneous tension (currently uniform γ)
   • Bending/curvature energy terms
   • Area constraints via Lagrange multipliers

4. Performance optimization:

   • Cached geometry computations (areas, perimeters)
   • Sparse gradient calculations
   • Vectorized operations for large tissues

5. Analysis tools:

   • Cell tracking across timesteps
   • Stress/strain field visualization
   • Automated parameter sweep utilities

Known Issues

• ACAM tissues may contain duplicate consecutive vertices after conversion (use validation and repair tools)
• Timestep requirements vary by tissue size (ACAM: dt≈0.0001, Honeycomb: dt≈0.01)
• Energy explosion can occur with inappropriate parameters (use diagnostic tools)

See documentation in docs/ for detailed guides and troubleshooting.

Contributing

Contributions are welcome! Please ensure:

• All tests pass (pytest -v)
• New features include tests and documentation
• Code follows existing style conventions
• ACAM tissues are validated after conversion

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

---

Status: Fully functional vertex model implementation with comprehensive validation and diagnostic tools.

For questions, issues, or feature requests, please refer to the documentation in docs/ or file an issue.