░█████╗░███████╗██╗░░░░░░█████╗░██████╗░██████╗░░█████╗░░░░░░░██████╗░██████╗░
			██╔══██╗██╔════╝██║░░░░░██╔══██╗██╔══██╗██╔══██╗██╔══██╗░░░░░░╚════██╗██╔══██╗
			██║░░╚═╝█████╗░░██║░░░░░███████║██║░░██║██████╔╝██║░░██║█████╗░█████╔╝██║░░██║
			██║░░██╗██╔══╝░░██║░░░░░██╔══██║██║░░██║██╔══██╗██║░░██║╚════╝░╚═══██╗██║░░██║
			╚█████╔╝███████╗███████╗██║░░██║██████╔╝██║░░██║╚█████╔╝░░░░░░██████╔╝██████╔╝
			░╚════╝░╚══════╝╚══════╝╚═╝░░╚═╝╚═════╝░╚═╝░░╚═╝░╚════╝░░░░░░░╚═════╝░╚═════╝░
			------------------------------------------------------------------------------
                 				Celadro: Cells as active droplets
                    			Romain Mueller (2016-2017) & Siavash Monfared (2020-21)

Three-dimensional phase-field modeling of epithelial cells using finite-difference integrator

CELADRO-3D is a computational framework for simulating active matter and cellular dynamics in three dimensions using phase-field methods. The model treats cells as active droplets and captures complex behaviors including cell division, migration, and tissue morphogenesis.

• Modern C++ compiler supporting C++14 standard
• CMake (version 3.0 or higher)
• Boost libraries (specifically boost::program_options)
• VTK library (for visualization)

mkdir build
cd build
cmake ..
make

cd example
../build/celadro simCard.dat [options]

The simulation card contains all simulation parameters:

# Sample runcard
config = input const       # Configuration type
nsteps = 3000             # Number of simulation steps
ninfo = 5                 # Output frequency
LX = 64                   # System size in X direction
LY = 64                   # System size in Y direction
LZ = 40                   # System size in Z direction
nsubsteps = 10            # Number of substeps per step
bc = 2                    # Boundary conditions (0=periodic, 1=no-flux, 2=periodic in xy, no-flux in z)
margin = 18               # Margin size
relax-time = 0            # Relaxation time
nphases = 4               # Number of phases/cells
gamma = 0.008             # Surface tension parameter
mu = 45.0                 # Chemical potential difference
lambda = 3.0              # Lagrange multiplier for volume constraint
kappa_cc = 0.5            # Bending rigidity
R = 8.0                   # Preferred cell radius
xi = 1.0                  # Friction coefficient
omega_cc = 0.0008         # Activity parameter
wall-thickness = 7.0      # Wall thickness for boundary conditions

• LX, LY, LZ: Define the 3D simulation box dimensions
• nphases: Number of individual cells/droplets in the system
• gamma: Controls surface tension between cells and medium
• mu: Chemical potential driving phase separation
• R: Sets preferred/equilibrium cell radius
• omega_cc: Activity parameter determining self-propulsion strength

Defines initial cell positions (one line per cell):

x_center y_center z_center

Example:

8 8 11      # Cell 1 at position (8,8,11)
24 8 11     # Cell 2 at position (24,8,11)
24 24 11    # Cell 3 at position (24,24,11)
8 24 11     # Cell 4 at position (8,24,11)

celadro_three_dimensional/
├── src/                    # Source code
│   ├── main.cpp           # Main program and algorithm
│   ├── header.hpp         # Common includes and definitions
│   ├── model.hpp          # Core model definitions
│   ├── options.cpp        # Command line option parsing
│   ├── init.cpp           # Initialization routines
│   ├── run.cpp            # Main simulation loop
│   ├── files.cpp          # File I/O operations
│   ├── write.cpp          # Output writing functions
│   ├── serialization.cpp  # Data serialization
│   ├── threads.cpp        # Threading utilities
│   ├── random.cpp         # Random number generation
│   ├── vec.hpp            # Vector operations
│   ├── tools.hpp          # Utility functions
│   ├── derivatives.hpp    # Numerical derivatives
│   ├── stencil.hpp        # Finite difference stencils
│   └── error_msg.hpp      # Error handling
├── example/               # Example simulations and scripts
│   ├── simCard.dat       # Sample simulation parameters
│   ├── input_str.dat     # Sample initial configuration
│   ├── createInput.cpp   # C++ input generation utility
│   ├── createInput.py    # Python input generation utility
│   ├── vtk_VolRender.py  # VTK visualization script
│   └── celadro_3D_scripts_final/ # Analysis and plotting tools
├── build/                 # Build directory
├── CMakeLists.txt        # CMake configuration
├── config.gif            # Example output visualization
└── README.md             # This file

• Phase-field solver: Implements Cahn-Hilliard dynamics with activity
• Finite difference methods: High-order stencils for spatial derivatives
• Multi-threading support: Parallel execution for performance
• Flexible I/O: JSON and VTK output formats
• Command-line interface: Extensive parameter control

Get complete list of options:

../build/celadro -h

Common usage patterns:

# Basic run
../build/celadro simCard.dat

# Specify output directory
../build/celadro simCard.dat --output=results/

# Compressed output
../build/celadro simCard.dat --compress-full

# Override parameters
../build/celadro simCard.dat --nsteps=5000 --gamma=0.01

The simulation generates several output files:

• config_XXXX.json: Cell configurations at different time steps
• config_XXXX.vtk: VTK format for visualization
• log files: Simulation progress and diagnostics

1. Load the generated .vtk files
2. Apply appropriate filters and coloring
3. Create animations and visualizations

cd example
python vtk_VolRender.py  # Run VTK-based visualization

The example/celadro_3D_scripts_final/ directory contains:

• plotting utilities: Generate publication-quality figures
• data analysis: Extract physical quantities
• animation tools: Create movies from simulation data

CELADRO-3D implements a phase-field model where each cell is represented as a distinct phase with:

• Surface tension: Controlled by parameter gamma
• Volume conservation: Each cell maintains approximately constant volume
• Self-propulsion: Active forces drive cell motility
• Cell-cell interactions: Repulsive forces prevent overlap
• Environmental coupling: Cells respond to substrate and boundaries

The governing equations combine:

• Cahn-Hilliard dynamics for phase evolution
• Active matter forces for self-propulsion
• Mechanical constraints for volume conservation

CELADRO-3D has been used to study:

• Collective cell migration
• Tissue morphogenesis
• Cell sorting and pattern formation
• Effects of confinement on cell behavior
• Active matter phase transitions

Primary Publications:

@article{monfared2023elife,
  title={Active vertex model for epithelial cell dynamics},
  author={Monfared, Siavash and others},
  journal={eLife},
  volume={12},
  pages={e82435},
  year={2023},
  doi={10.7554/eLife.82435}
}

@article{monfared2022arxiv,
  title={Three-dimensional active vertex model for epithelial tissue morphogenesis},
  author={Monfared, Siavash and others},
  journal={arXiv preprint arXiv:2210.08112},
  year={2022},
  doi={10.48550/arXiv.2210.08112}
}

@article{mueller2019prl,
  title={Emergence of Active Nematic Behavior in Monolayers of Isotropic Cells},
  author={Mueller, Romain and others},
  journal={Physical Review Letters},
  volume={122},
  pages={048004},
  year={2019},
  doi={10.1103/PhysRevLett.122.048004}
}

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

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

• Siavash Monfared - Primary developer (2020-2021)
• Romain Mueller - Original framework (2016-2017)

For questions and support, please open an issue on GitHub or contact the authors through their institutional affiliations.

CELADRO-3D: Advancing our understanding of collective cellular behavior through computational modeling