Protocol for simulating cell-contact dynamics of proliferating epithelia using the vertex model

Summary

Vertex models simulate epithelial mechanics at single-cell resolution but represent cell division as a single in-plane split, agnostic to the differential apicobasal geometry of mitotic cells. Here, we present a protocol that simulates basal mitosis as two sequential changes: basal-cell diminution followed by daughter-cell reinsertion. Apical-side simulations can be performed with minimal code modification. We provide instructions for generating initial configurations, running simulations, and quantifying mechanical and topological rearrangements using command-line operations accessible to experimental biologists.

For complete details on the use and execution of this protocol, please refer to Ramanathan et al.¹

Graphical abstract

Highlights

• •Software installation and generation of initial configurations
• •2D vertex model simulation of basal diminution and daughter-cell reinsertion
• •Guidance on data processing, visualization, and analysis
• •Accessible workflow using simple commands and minimal script editing

Publisher’s note: Undertaking any experimental protocol requires adherence to local institutional guidelines for laboratory safety and ethics.

Vertex models simulate epithelial mechanics at single-cell resolution but represent cell division as a single in-plane split, agnostic to the differential apicobasal geometry of mitotic cells. Here, we present a protocol that simulates basal mitosis as two sequential changes: basal-cell diminution followed by daughter-cell reinsertion. Apical-side simulations can be performed with minimal code modification. We provide instructions for generating initial configurations, running simulations, and quantifying mechanical and topological rearrangements using command-line operations accessible to experimental biologists.

Before you begin

Overview of the vertex model

The vertex model is a state-of-the-art computational framework for simulating tissue mechanics at single-cell resolution.^2,3,4,5,6 In this framework, the cells are described by geometrical shapes depending on system dimensionality. In two dimensions, each cell is a polygon whose shape is determined by the location of its vertices (Figure 1). The cell shapes evolve as the vertices move under the influence of forces. In a friction-dominated environment, frictional forces are balanced primarily by passive forces derived from potential energies, and in some cases by additional active forces. These potential energies are defined by specific geometrical properties of cells, such as surface area, edge length, etc., with model-specific formulations (Figure 1). Additionally, the cells perform topological transformations of exchanging neighbors even if they are tightly packed (known as T1 transitions), which require dynamic modifications of the underlying connectivity.

Figure 1.

Schematic representation of the vertex model used in the simulations

A cell is represented as a polygon whose shape is defined by vertices connected by edges, with edges forming the boundaries between neighboring cells (left). The corresponding potential energy W comprises an area-elasticity term that penalizes deviations of the cell area a_i from its preferred area $a_i^0$, and a perimeter-elasticity term that penalizes deviations of the cell perimeter p_i from its preferred perimeter $p_i^0$ (right).

Because the vertex model couples geometry, topology, and mechanical interactions through specialized data structures, designing a universal implementation for all forms of potential energy is challenging. Instead, each specific energy formulation needs to be implemented carefully. Even after an energy has been implemented, generating suitable initial configurations, selecting simulation parameters, and analyzing simulation outputs remain technically demanding, creating a substantial barrier to researchers with limited computational expertise.

The protocol below addresses these barriers by providing a complete workflow for simulating the distribution of T1 transitions during mitosis in the basal regions of the epithelium. To accurately reflect the topological state of basal region in epithelial tissues in vivo,^7,8,9 a single mitotic cell first undergoes diminution and the daughter cells are subsequently reinserted in the in silico simulation. Beyond the implementation of this specific model, the protocol provides detailed guidance for software installation, generation of initial configurations, execution of simulations, and post-processing of the results, thereby lowering the barrier to using and adapting vertex model simulations. For further details, see Ramanathan et al. 2025.¹

Underlying mechanical framework

We use the two-dimensional area- and perimeter-elasticity (APE) model^2,3,4,5,6 to describe the potential energy of the tissue and implemented its expression in our in-house code.

The potential energy in the APE model includes contributions from cell area and perimeter, expressed as:

$$W=\sum _{i\in \mathrm{cells}}\left[K_{a_i}{\left(a_i-a_i^0\right)}^2+K_{p_i}{\left(p_i-p_i^0\right)}^2\right]\text{,}$$

where a_i and p_i are the actual area and perimeter of the i-th cell, $a_i^0$ and $p_i^0$ are the corresponding preferred values, and $K_{a_i}$ and $K_{p_i}$ are the moduli associated with area and perimeter elasticity, respectively. We consider preferred areas and perimeters of normal cells to be uniform across the tissue such that $a_i^0=a_0$ and $p_i^0=p_0$ for all normal cells i. We use a₀ to set the area scale of the system with lengths normalized by $\sqrt{a_0}$ . Thus, after nondimensionalization, the preferred area of every normal cell is a₀ = 1. In simulations, we use dimensionless preferred perimeter $p_0=p_0/\sqrt{a_0}$, which is also a prominent marker of tissue’s mechanical behavior.⁵ See Table 1 for the mapping between dimensionless and dimensional values of preferred perimeters assuming the average cell size in the tissue is approximately 50 μm², where multiplying dimensionless p₀ values by $\sqrt{50}\mathrm{\mu }\mathrm{m}$ provides values with dimension. For example, p₀ = 3.75 corresponds to 26.52 μm.Thus, p₀ can be chosen continuously and is not restricted to the values listed in Table 1; no finite tolerance or parameter binning is imposed.

Table 1.

Mapping between dimensional and nondimensional preferred perimeter (p₀)

p0: preferred perimeter (in μm)	p0: preferred perimeter (dimensionless)
26.16	3.70
27.22	3.85
28.28	4.00
29.34	4.15

On the other hand, we define a characteristic time ${\tau }_0=\frac{\eta }{K_p}$, which is used to nondimensionalize all time scales of the system, where η is the friction coefficient of the vertices and K_p is the perimeter-elasticity modulus, taken to be identical for all cells. Thus, although the preferred area and perimeter may vary between cells during diminution and reinsertion, the same K_p sets the characteristic time scale throughout the simulations. The reported simulation time in arbitrary units (AU) is therefore measured in units of τ₀.

We use a pre-generated disordered tissue with cells as a base to prepare initial conditions. From this base configuration, cells are selected one at a time and their preferred areas are set to 1.33. The configuration is then melted to remove any configuration bias using an active-tension-fluctuations scheme based on the Ornstein-Uhlenbeck model.^10,11

Specifically, this active fluctuations are applied for 3000 time units, followed by a sharp quench and minimization over an additional 7000 time units. During these two stages local cell neighbor exchanges or T1 transitions are allowed. The resulting four-fold vertices are then resolved into small edges of length 10⁻³. The configuration is subsequently minimized for 1000 time units using a smaller integration time step of 10⁻⁴. This procedure generates a randomized initial condition containing a large mitotic cell at a random location (leftmost panel, Figure 2). T1 transitions throughout the procedure are performed by removing a shrinking edge below a threshold of 10⁻² between a pair of cells and reopening the edge in the perpendicular direction.

Figure 2.

Schematic comparison of the cell-division protocols used in the simulations

(A) Basal diminution–reinsertion protocol, in which the mitotic cell progressively diminishes from the basal surface before division, followed by gradual reinsertion of the two daughter cells.

(B) Conventional division protocol, in which the mitotic cell divides directly into two daughter cells without the preceding basal diminution–reinsertion sequence.

For each prepared initial configuration, two simulations are performed, corresponding to the basal and apical versions of the model. Apart from the prescribed target area of the mitotic cell, the two simulations follow the same sequence of operations: (1) relaxation of the initial configuration for 300 time units; (2) progressive modification (diminution) of the mitotic cell’s preferred area over 100 time units; (3) relaxation of the modified configuration; (4) division of the mitotic cell followed by gradual adjustment of the preferred areas of the two daughter cells for 100 time units; and (5) a final relaxation for 300 time units (Figures 2 and 3).

Figure 3.

Representative snapshots illustrating the temporal progression of the cellular arrangement around the mitotic cell on the basal side for p₀ = 3.70 μm

From left to right, the snapshots show late interphase, progressive basal diminution of the mitotic cell, and subsequent daughter-cell reinsertion. The mitotic cell and surrounding cells are color-coded according to their topological distance from the mitotic cell (white colored cell), with different colors representing successive topological orders.

The distinction between the basal and apical protocols is introduced through the target preferred area $a_{tar}^0$ of the mitotic cell. For the basal protocol, $a_{tar}^0=0$, corresponding to complete diminution of the mitotic cell before division. For the apical protocol, $a_{tar}^0=a_{max}$, where $a_{max}$ = 0.5×1.33, 1.33, or 2 × 1.33, corresponding to the different prescribed target sizes. All preferred area changes of the mitotic cells are performed linearly; for example, during cell diminution, its preferred area varies from 1.33 times the normal-cell area to zero over 100 time units. Additionally, the preferred perimeter of the mitotic cell is not varied independently; at each time step it is determined from the instantaneous preferred area $a_{ch}^0\left(t\right)$ according to $p_0\sqrt{a_{ch}^0\left(t\right)}$, where p₀ denotes the preferred perimeter of a normal cell.

After the preferred area reaches its target value, the configuration is allowed to relax for an additional 100 time units. The mitotic cell is then divided along a randomly selected axis passing through its centroid, and this centroid location defines the reinsertion position of the daughter cells. Immediately after division, the two daughter cells are assigned equal preferred areas, each equal to one-half of the mitotic-cell target area. Their preferred areas $a_{chl}^0\left(t\right)$ are then varied linearly toward 0.5×1.33 over the prescribed growth duration, with the corresponding preferred perimeter updated according to $p_0\sqrt{a_{chl}^0\left(t\right)}$.

Accessibility

Most vertex-model implementations involve geometry, topology, and mechanics, which are entangled within specialized data structures that are difficult to inspect or modify without substantial computational expertise. This protocol is built instead around a modular implementation in which each stage of the workflow, including initial configuration generation, simulation, and analysis, can be executed and tested independently. This separation lets users with limited programming experience reproduce results and explore parameter space through simple command-line operations and minimal script editing, while users developing new models can extend individual components of the source code directly. By exposing the workflow as discrete, annotated modules, the protocol lowers the barrier to adapting vertex-model simulations and supports collaboration between experimental and theoretical groups.

Innovation

A distinct advance concerns how division itself is represented. Conventional vertex-model implementations represent mitosis as a single topological bifurcation: a new interface splits the mother polygon into two daughters within the plane of the sheet. However, such mechanically idealized single in-plane division model does not capture the apico-basal segregation between loss of the mother cell’s basal footprint and reinsertion of the daughter pair. This protocol instead explicitly separates the two operations: diminution of the mother cell’s basal footprint, followed by reinsertion of the daughters. We provide this as a documented, independently modifiable module rather than a general replacement for the single-split representation; the diminution–reinsertion scheme is suited specifically to model the apical and basal neighbor rearrangements analyzed in Ramanathan et al.¹

Experimental design summary

This protocol is organized into four main stages: obtaining the source code from GitLab and installing the required software; generating initial states for simulations; performing cell diminution and daughter-cell reinsertion simulations; and performing quantification and statistical analysis.

Each stage is described step by step, with expected outcomes and possible error sources clearly indicated. We employ our in-house vertex model code (implemented primarily in C with some C++ features and compiled with g++) for data generation. Post-simulation analysis and plotting are carried out with standard Python libraries (see key resources table). The code has been compiled and run successfully with the g++ version specified in the key resources table. We have not systematically evaluated compatibility across different compiler versions.

Note: All computational steps can be performed either on a high-performance computing cluster or a local workstation. The protocol includes dedicated scripts for both environments.

Downloading and installation

Timing: 5–10 min

Install required software and obtain the source code needed to run the vertex model simulations and analyses.

Note: See the key resources table for software links and versions. Command-line access on either a local workstation (macOS/Linux/Windows with WSL) or a SLURM-managed cluster is required.

We uploaded the source code to GitLab as a public repository and made it freely available. This section describes how to download the source code and install the required software.

Procedure

• 1.Open a terminal in your working directory and install required software (see key resources table).
• 2.
  Obtain the source code from GitLab or Zenodo using one of the following methods:

  • a.
    Clone using Git:
    git clone https://gitlab.com/tanmoy_jsi/cell_diminution_protocols.git
    This will create a folder named “cell_diminution_protocols” in the working directory.
  • b.
    Download as an archive:

    • i.
      Copy the project link into a browser.
    • ii.
      On the GitLab project page, click the blue “Code” button.
    • iii.
      Select “Download source code” and choose your preferred format (such as .zip or .tar.gz).

      Note: For instance, a .zip file will be downloaded as “cell_diminution_protocols-main.zip”. After extraction, this will create a folder named “cell_diminution_protocols-main” in the working directory.

  • c.
    Download from Zenodo:

    • i.
      Open the Zenodo DOI https://doi.org/10.5281/zenodo.22236021 in a web browser.
    • ii.
      Download the archive “cell_diminution_protocols.zip”.

      Note: After extracting the archive, this will create a folder named “cell_diminution_protocols” in the working directory.

      Note: The folder name differs slightly depending on whether you use cloning or downloading. For consistency, all subsequent steps in this protocol assume that the source code directory is named “cell_diminution_protocols”.

• 3.Install Python 3 from: https://www.python.org/downloads/ according to your operating system.
• 4.Install a code editor such as Visual Studio Code from: https://code.visualstudio.com/download. Visual Studio Code is cross-platform and works on Linux, macOS, and Windows.

Key resources table

REAGENT or RESOURCE	SOURCE	IDENTIFIER
Software and algorithms
Cell-diminution vertex-model code (this protocol)	This paper; Zenodo	DOI: https://doi.org/10.5281/zenodo.22236021
C++ (GNU Compiler Collection, g++); GCC 8.5.0 (Red Hat distribution)	GNU Project	https://gcc.gnu.org/
Python 3 (version: 3.10.8)	Python Software Foundation	https://www.python.org/
NumPy (Numerical Python) (version: 1.24.3)	NumPy Developers	https://numpy.org/
Matplotlib (version: 3.7.1)	Matplotlib Development Team	https://matplotlib.org/
NetworkX (Version: 3.1)	NetworkX Developers	https://networkx.org/
Bash (GNU Bourne Again Shell) (version: 3.2.57(1))	GNU Project	https://www.gnu.org/software/bash/
Visual Studio Code	Microsoft	https://code.visualstudio.com
Other
macOS Ventura	Apple	Version 13.7.8
Rocky Linux	Rocky Enterprise Software	8.8 (Green Obsidian)

Step-by-step method details

This part of the protocol describes the process of generating initial configurations, running simulations, and finally analyzing and plotting data as expected outcomes. Here, these three major steps are performed in three separate sections with clearly indicated anticipated outcomes and troubleshooting guidance.

CRITICAL: All subsequent steps in this protocol use the dimensionless form of the preferred cell perimeter (p₀). Before running simulations, ensure that any chosen dimensional value is converted to its corresponding nondimensional p₀ (see Table 1 for the mapping).

Preparation of initial configurations

Timing: Generating one initial configuration requires approximately 1 h on a single CPU core, although the exact time depends on processor performance. Thus, generating all 324 configurations for a given p₀value requires approximately 324 CPU-h (about 13.5 days) when performed serially on a single core. Because configurations are generated independently, this time can be substantially reduced by parallel execution across multiple CPU cores.

This section describes how to generate the initial configurations used in simulations of cell diminution and daughter-cell reinsertion.

Note: Starting from a pre-formed configuration, all required initial states are systematically generated using our in-house code written in C. The active-fluctuation, quench, and minimization procedure is used to reduce the dependence on the starting configuration and generate randomized initial states containing a large mitotic cell at a random location. This stage uses the in-house C/C++ vertex-model code, compiled with g++; the accompanying .sh scripts are used to set parameters and submit the computations.

Procedure

• 1.Navigate to the working directory:

Go to the folder “initial_configs_generation_multi_P0” inside the source code folder “cell_diminution_protocols”.

• 2.
  Edit the submission script:

  • a.
    Open “job_submission_script_multi_P0.sh” in any text editor and set the parameters:

    CRITICAL: This script is configured for clusters running the SLURM workload manager. By default, the script submits jobs to the batch partition:

    >#SBATCH --partition=batch

    Note: Most SLURM systems include a batch partition. Modify this setting to another available partition (e.g., short, day, or long) to achieve faster scheduling and avoid long queue times. Consult your system administrator or cluster documentation for the optimal partition.

  • b.
    Set the preferred perimeter (p₀): Choose values of p₀ according to Table 1.
    Example (to simulate tissues with p₀ = 3.70 and p₀ = 3.85):
    >P0_values=(3.70 3.85)
  • c.
    Set the large mitotic (mother) cell ID range: The initial sample contains 324 cells. To improve statistical sampling, we generate 324 independent initial configurations, each containing a large mitotic cell whose location emerges from the randomization procedure and is therefore not prescribed.

    Note: We use a relatively large ensemble to reduce statistical fluctuations in the measured quantities. The choice of 324 configurations is not intended as an optimal or formally determined sample size; the number of configurations can be increased when higher statistical precision is required, whereas fewer configurations may suffice for qualitative analyses.

    >big_mom_max=324
  • d.
    Set the random number seed: To avoid preparation bias, each configuration with a large mitotic cell is first melted (by applying fluctuating forces on cell edges; see MATERIALS AND METHODS in Ramanathan, Subramanian P., et al.¹) and then quenched. These forces are controlled by a random number generator, which generates a unique set of random numbers against a unique seed. Provide a unique seed to each configuration set by setting a base value associated with the seed.
    Example (using base seed of 1):
    >SEED_BASE_START=1

    Optional: (Local execution): If a cluster facility is unavailable, generate the initial configurations on a local machine using a modified script.

    Note: This approach can take significantly longer depending on available cores.

  • e.
    Instead of “job_submission_script_multi_P0.sh”, edit “job_submission_script_multi_P0_local.sh”, which is also available in the working directory. Follow the same editing procedure as described in sub-steps b–d above.
  • f.
    Make the script executable:
    >chmod +x job_submission_script_multi_P0_local.sh

    CRITICAL: Here, Steps 3 and 4 are not necessary because the script is intended for a local machine.

  • g.
    Run the job:
    >./job_submission_script_multi_P0_local.sh

    Note: This script includes an additional routine that detects the number of free CPU cores. It automatically launches parallel runs using one fewer than the available cores. It assumes a constant number of free cores during the entire process. If cores are available, you will see output such as:

    ………
    >[task] id=4 P0=3.70 big_mom=4 seed=104 area=1.33
    >[task] id=1 P0=3.70 big_mom=1 seed=101 area=1.33

    CRITICAL: If no cores are free, the system will exit with:

    > [error] No cores available for parallel jobs. Try again later.
    If this message appears, wait until cores become available and rerun the script.

    CRITICAL: Step 5 is identical to the cluster-based execution.

• 3.
  Copy the folder to the cluster and make the script executable:

  • a.
    Ensure that an empty folder named “cell_diminution_protocols” exists on the cluster (create it if necessary, using “>mkdir cell_diminution_protocols”).
  • b.
    Use “scp” to transfer the “initial_configs_generation_multi_P0” folder to the cluster:
    Example (copying from local machine):
    >scp -r initial_configs_generation_multi_P0 userName@cluster.institute.country:/cluster/user/ cell_diminution_protocols/

    Note: Replace “userName” with your cluster login name, “cluster.institute.country” with the cluster address, and “/cluster/user/” with the working directory path on the cluster.

  • c.
    Navigate to the “initial_configs_generation_multi_P0” directory on the cluster.
  • d.
    Make the submission script executable:
    >chmod +x job_submission_script_multi_P0.sh
• 4.Submit the job:

Run the script:

>./job_submission_script_multi_P0.sh

Terminal prints compilation and execution messages, ending with a SLURM Job ID. Example (job ID = 25159894):

>Submitted batch job 25159894

• 5.Check job status and generated configurations: After completion, navigate to the “output” folder inside “initial_configs_generation_multi_P0” and confirm files with the “.vt2d” extension.

Example (a configuration with p₀ = 3.70 and large mitotic cell ID=22):

new_P0_3.70_big_mom_22.vt2d

Note: The filename indicates both p₀ and the large mitotic cell ID. The presence of all expected files for the specified p₀ values and ID range confirms successful completion of the simulations.

Example (for p₀ = 3.70 and p₀ = 3.85 with 324 unique large mitotic cells for each):

648 distinct files are generated, each uniquely labeled by p₀ and mitotic cell ID.

CRITICAL: Even in the absence of any configuration based on the chosen values of p₀ and mitotic cells, consult problem 1 and problem 2 from the troubleshooting section.

Note: Each file with the “.vt2d” extension contains the complete geometrical and topological description of a tissue configuration used in simulating vertex models. The first line lists three integers specifying the number of vertices (N_v), edges (N_e), and polygons (N_p). The second line provides two real numbers defining the box dimensions in the x- and y-directions. These are followed by N_v lines containing the x- and y-coordinates of all vertices. The next Ne lines describe the edges, where the first two integers indicate the vertex pair forming each edge, and the third column is an unused value. The final Np lines describe the polygons: each line contains 17 columns, where the first integer gives the polygon’s sidedness (p_side), the second gives its dimensionless area, and the next p_side integers specify the signed edge IDs forming that polygon. Edges oriented counterclockwise with respect to the polygon are assigned positive signs, while those oriented clockwise carry negative signs. The remaining columns are filled with zeros. All indices are 1-based, meaning that counting begins from 1 rather than 0. Numbers are whitespace-separated, and occasional blank lines are intentionally inserted between sections (e.g., after the counts, box dimensions, vertex list, and edge list) to improve readability for users.

Performing cell diminution and daughter-cell reinsertion

Timing: 4–15 min per configuration

This section describes a step-by-step process of simulating cell diminution and daughter cell reinsertion.

Note: Starting from the configurations created in the previous section (see preparation of initial configurations), simulations are performed for different p₀ separately, and the resulting data are stored for further analysis. The default implementation simulates cell diminution in the basal region of the epithelium. Owing to the modular design of the code, the corresponding apical simulations can be performed by replacing only three header (.h) files, without modifying the remaining implementation. This enables consistent simulation of both basal and apical dynamics using essentially the same workflow. This stage uses the in-house C/C++ vertex-model code, compiled with g++, while the accompanying shell scripts are used to configure and submit the simulations.

CRITICAL: To run this step for a given p₀ value, the corresponding set of initial configurations must be generated beforehand. For example, the default setup generates initial configurations for p₀ = 3.70 and p₀ =3.85; therefore, simulations with the default setting can only be performed for these values. To analyze cell diminution at other p₀ values (e.g., p₀ = 3.75), first generate the required initial configurations by following the procedure in preparation of initial configurations before proceeding with this step.

Procedure

• 6.Navigate to the working directory:

First, perform simulations for the basal side; therefore, go to the folder “cell_diminution_with_cell_remnant_area_0_P0_3.70” inside “cell_diminution_protocols”. Here, 3.70 is the default p₀ value. To run simulations for other p₀ values, copy this folder and rename it accordingly.

Example (copying the default folder to p₀ = 3.85):

>cp -r cell_diminution_with_cell_remnant_area_0_P0_3.70 cell_diminution_with_cell_remnant_area_0_P0_3.85

• 7.
  Edit Submission Script:

  • a.
    Open “job_submission_script.sh” in any text editor and set the following parameters:

    CRITICAL: This script is configured for clusters running the SLURM workload manager. By default, the script submits jobs to the batch partition:

    >#SBATCH --partition=batch

    Note: Most SLURM systems include a batch partition. Modify this setting to another available partition (e.g., short, day, or long) to achieve faster scheduling and avoid long queue times. Consult your system administrator or cluster documentation for the optimal partition.

  • b.
    Set the preferred perimeter (p₀): Choose the p₀ value according to Table 1.
    Example (for tissues with p₀ = 3.70):
    >P0_values=(3.70)
  • c.
    Set the large mitotic (mother) cell ID range: There are 324 distinct initial configurations. For full statistics, simulate all of them.
    Example (simulation of 324 configurations):
    >num_of_cells=324
  • d.
    Set the random number seed: The cell division axis is selected randomly through the cell centroid, with its orientation sampled uniformly over 0 ≤ θ < π using a random number generator initialized with a unique seed. A unique seed is assigned per p₀ value.
    Example (initial seed is 1):
    >initial_seed=1

    Optional: (Local execution): If the availability of the local cluster is limited to the users, the Cell Diminution and Daughter Cell Reinsertion simulations can also be performed by using one modified script.

    Note: It obeys roughly the same workflow, but a few modifications are necessary to adapt the procedure for the local machines (non-SLURM environment). However, running this part of the study locally can take significantly longer depending on available cores.

  • e.
    Open the dedicated local-execution script named
    job_submission_script_local.sh, located in the same (current) directory as the standard cluster script.
  • f.
    Edit this script to set the simulation parameters as specified in sub-steps b-d above.

    Note: The “CRITICAL” note about the SLURM partition can be ignored, since the job will be executed locally without a queueing system.

    CRITICAL: In step 8, skip the file transfer step that is needed for the cluster. Instead, grant the local script the required permission for execution:

    >chmod +x ./job_submission_script_local.sh
    If the initial configurations were generated locally (see Optional: (Local execution): in preparation of initial configurations), copy them into the p₀-specific folder using the same command described in step 9 of the current section.
  • g.
    Execute the script directly from the terminal:
    >./job_submission_script_local.sh

    Note: This version of the script includes a built-in check for available CPU resources. It automatically detects the number of currently idle cores and launches parallel simulations using one fewer than the available cores. The script assumes that this level of availability remains constant throughout the run. During execution, progress messages appear in the terminal, for example:

    ………
    >task] id=1 P0=3.70 ran_angle_no=1 angle=0.000049 remnant_area=0 probable_big_mom=1 big_mom_area=1.330000
    >task] id=3 P0=3.70 ran_angle_no=3 angle=4.747608 remnant_area=0 probable_big_mom=3 big_mom_area=1.330000

    CRITICAL: If no cores are detected as free, the system will exit with a message:

    > [error] No cores available for parallel jobs. Try again later
    When this occurs, wait until system resources become available and rerun the command.

    Note: Upon completion, the outputs mirror those obtained in the cluster-based workflow (see steps 11 and 15) and can be used directly for subsequent statistical analysis and visualization in the Expected outcomes section.

    CRITICAL: When simulations are performed locally, the data are already stored on the same machine, so step 16 (Copying data from cluster to local machine) is not required. Proceed directly with post-processing by navigating to the appropriate script within the p₀-specific folder. All analysis, visualization, and troubleshooting procedures remain identical to those in the cluster-based version.

    Note: During troubleshooting, ensure that you are working within the local directory. Commands that refer to cluster operations should be omitted or replaced with equivalent local file operations. This local execution by default considers basal simulations; however, the simulations for the apical side can also be run by following a similar process described in steps 12 to 15. The analysis in the Quantification and Statistical Analysis section is also performed in the same way as the basal side.

• 8.
  Transfer to the cluster and make the script executable:

  • a.
    Copy the current p₀-specific folder into “cell_diminution_protocols” on the cluster using “scp”.
    Example (copying from local machine for p₀ = 3.70):
    >scp -r cell_diminution_with_cell_remnant_area_0_P0_3.70 userName@cluster.institute.country:/cluster/user/ cell_diminution_protocols/

    Note: Replace “userName”, “cluster.institute.country”, and “/cluster/user/” according to your cluster-specific details.

  • b.
    Navigate to the p₀-specific folder and ensure the script is executable.
    Example (for p₀ = 3.70):
    >cd cell_diminution_with_cell_remnant_area_0_P0_3.70
    >chmod +x job_submission_script.sh
• 9.Copy the initial configurations:

Copy all “.vt2d” files from “initial_configs_generation_multi_P0” into the “initial” folder of the current p₀ process.

Example (for p₀ = 3.70):

cp -R "initial_configs_generation_multi_P0/output/ " "cell_diminution_with_cell_remnant_area_0_P0_3.70/initial/"

• 10.Submit the job for basal side:

Run the script:

>./job_submission_script.sh

• 11.
  Check job status and generated data files:

  • a.
    Monitor the job status until completion.
  • b.
    After successful runs, navigate to the “output” folder inside the current p₀-specific folder which contains the output data files generated by the simulation.
  • c.
    For each mitotic cell, confirm the presence of at least the following output data files required for the analyses presented in this protocol:

    • i.
      “t1_time_not_on_0_based_on_ref_“$i”.txt” contains the occurrence times of T1 transitions associated with the diminution and reinsertion of the i-th mitotic cell, excluding T1 transitions involving edges shared with the mitotic cell. Negative values denote T1 transitions occurring before daughter-cell reinsertion, whereas positive values denote T1 transitions occurring after reinsertion.
    • ii.
      “loc_before_div_not_on_0_“$i”.txt” contains the topological distances of cells involved in T1 transitions occurring before daughter-cell reinsertion, excluding T1 transitions involving the i-th mitotic cell. When T1 transitions occur, the file contains two columns corresponding to the minimum and maximum topological distances, respectively, of the cell pairs involved in each T1 transition.
    • iii.
      “loc_after_div_not_on_0_“$i”.txt” contains the corresponding topological distances for T1 transitions occurring after daughter-cell reinsertion, with the same two-column structure as “loc_before_div_not_on_0_“$i”.txt”.

where “$i” runs from 1 to 324.

• 12.Copy the basal data files and cleaning for apical side simulation:

Run the following commands to copy the generated data from the basal-side simulation. After that, re-enter the same directory to clean and reuse it in the apical side simulation.

> cd ..

> cp -r cell_diminution_with_cell_remnant_area_0_P0_3.70 cell_diminution_with_cell_remnant_area_0_P0_3.70_basal

> cd cell_diminution_with_cell_remnant_area_0_P0_3.70

> rm -rf output

> mkdir output

• 13.
  Preparation of apical side simulations:

  • a.
    To perform the corresponding apical simulations, replace the default header files with the apical-specific versions provided in the ‘scripts_only_for_apical’ directory.
  • b.
    Make the replacement script executable:
    > chmod +x only_for_apical.sh
  • c.
    Run the replacement script:
    > ./only_for_apical.sh

    Note: The script “only_for_apical.sh” automatically replaces the three required header (.h) files while leaving the remainder of the implementation unchanged. The parameter remnant_area is retained for both basal and apical simulations to allow reuse of the same implementation. Although the parameter name is unchanged, its physical interpretation differs between the two cases. In basal simulations, it represents the remaining basal footprint of the mitotic mother cell during diminution, whereas in apical simulations, it specifies the retained apical footprint during mitotic rounding. Unlike the basal case, an apical mitotic footprint does not diminish to zero during rounding. Therefore, apical simulations use a nonzero remnant_area expressed in normalized units.

  • d.
    Open the job_submission_script.sh and set remnant_area to the value corresponding to the apical-footprint scenario to be simulated:

    • i.
      For an apical footprint reduced to one-half of the late-interphase mother-cell area, set:
      > remnant_area=0.67
    • ii.
      For an apical footprint equal to the late-interphase mother-cell area, set:
      > remnant_area=1.33
    • iii.
      For an apical footprint expanded to twice the late-interphase mother-cell area, approximating apical-area increase during mitotic rounding, set:
      > remnant_area=2.66

      Note: The remnant_area values use the same area normalization defined in the Underlying Mechanical Framework, where the preferred area of an interphase cell is $a_0$ = 1. Thus, the values 0.67, 1.33, and 2.66 correspond to approximately 0.5, 1, and 2 times the preferred area of the late-interphase mother cell (1.33 × $a_0$), respectively. For the characteristic interphase cell area of approximately 50μm², these correspond to approximately 33.5, 66.5, and 133μm². These values are representative apical footprint sizes for exploring the effect of mitotic rounding, rather than exact quantitative matches to measured apical areas; users can select the value closest to the normalized apical area measured in their experimental system.

      CRITICAL: Increasing remnant_area toward and beyond the expansion case drives cells into progressively more irregular geometries, particularly at higher p₀, and can cause simulations to fail or return distorted configurations (see limitations and the higher-p₀ troubleshooting notes like problem 4 and problem 5). The expansion case above is a modest approximation of rounding and should be treated as an orientation- and mechanism-level test, not a quantitative model of apical geometry; real apical expansion in curved or pseudostratified epithelia can substantially exceed this range, and reproducing those magnitudes lies beyond the scope of this passive 2D implementation.

  • e.
    Repeat Steps 6–9 exactly as described above.

    Note: No additional modifications are required; only the substituted header files and the chosen remnant_area value distinguish the apical simulations from the basal simulations.

• 14.Submit the job for apical side:

Run the script:

>./job_submission_script.sh

• 15.Check job status and generated data files:

Follow the same instructions as mentioned in step 11.

• 16.Copy data to the local machine:

Use “scp” to transfer the generated data of the apical and the basal side to the local computer from the cluster:

Example (copying p₀ = 3.70 from basal side):

> scp -r userName@cluster.institute.country:/cluster/user/ cell_diminution_with_cell_remnant_area_0_P0_3.70_basal.

Example (copying p₀ = 3.70 from apical side):

> scp -r userName@cluster.institute.country:/cluster/user/ cell_diminution_with_cell_remnant_area_0_P0_3.70.

Note: Replace “userName”, “cluster.institute.country”, and “cluster/user/” according to your cluster setup.

Expected outcomes

By default, the workflow described in the next section generates results for the basal region of the tissue. Equivalent analyses for the apical region can be obtained by following the same steps described in the Quantification and Statistical Analysis section, replacing the directory cell_diminution_with_cell_remnant_area_0_P0_3.70_basal with cell_diminution_with_cell_remnant_area_0_P0_3.70, which contains the corresponding simulation output. This will produce plots in the same format as those shown for the basal region. Similarly, analyses for other values of p₀ can be performed by navigating to the directory corresponding to the desired p₀ value and repeating the same workflow.

For simplicity, only the basal results are presented here. Correct analysis produces two .pdf files indicating the spatiotemporal statistics of T1 transitions: “time_distribution.pdf”, which shows the temporal distributions of T1 transitions (Figure 4), and “topological_distance.pdf”, which shows the distribution of T1 transitions according to topological distance from the mitotic cell (Figure 5).

Figure 4.

Representative temporal distribution of T1 transitions during mitosis (excluding T1 transitions involving the mitotic cell and its daughter cells), averaged over 324 initial configurations for p₀ = 3.70

Time is reported in arbitrary units (AU), with one AU corresponding to the characteristic time ${\tau }_0=\frac{\eta }{K_p}$. Error bars indicate the standard error of the mean (SEM) across the 324 configurations. Time is aligned such that $\mathrm{t}=0$ corresponds to the daughter-cell division/reinsertion event; negative times correspond to cell diminution, whereas positive times correspond to daughter-cell reinsertion. As a quantitative reference, for the basal protocol, at least 70% of the total T1 transitions occur during daughter-cell reinsertion throughout the range of p₀ values explored in this study.

Figure 5.

Representative spatial distribution of T1 transitions as a function of topological distance from the mitotic cell for p₀ = 3.70

T1 transitions involving two cells of the same topological order are plotted at integer positions (e.g., position 1 represents two first-order neighbors), whereas transitions involving cells of different topological orders are plotted at the corresponding half-integer positions (e.g., position 1.5 represents a first-order and a second-order neighbor).

Quantification and statistical analysis

Timing: 2–4 min

This section describes a step-by-step process for obtaining final plots by analyzing the data generated in the p₀ and cell-side-specific directory during the steps outlined in the previous section.

Note: Here, the default example shows a p₀ value and simulation data from the basal side. Choose the directory according to your desired p₀ value and the side of the cell tiling, i.e., apical or basal. This stage uses Python scripts for post-processing, statistical analysis, and visualization; the shell script post processing.sh is used to initiate the analysis workflow.

CRITICAL: Simulations of the basal and apical regions produce output files with the same format and directory structure. Consequently, the same analysis scripts can be used for both datasets without any modification.

• 1.It starts by navigating to the desired directory.

Example (processing data for p₀ = 3.70 and basal side):

>cd cell_diminution_with_cell_remnant_area_0_P0_3.70_basal

• 2.Make the script executable:

>chmod +x post_processing.sh

• 3.Run the script for post-processing:

>./post_processing.sh

This script performs the following analysis:

• a.
  File integrity check: ensures all the expected files are present. A successful run ends with: >post-processing: done.

  CRITICAL: Any additional texts with numbers indicate missing files. Please consult problem 3, problem 4, and problem 5 in the troubleshooting section.

• b.Grand file generation: combines simulation outputs across configurations associated with different mitotic cells.
• c.
  Statistical analysis: determines the following characteristics during cell diminution and daughter cell reinsertion:

  • i.
    Time distribution of T1 transition
  • ii.
    Distribution of T1 transition events across the topological cell-network.

Limitations

A key limitation of this protocol is related to the choice of the preferred perimeter p₀. At higher values of p₀, cells can adopt highly irregular shapes that may result in distorted geometries during different stages of the workflow, including initial configuration generation, cell diminution, and daughter-cell reinsertion. As a consequence, simulations with higher p₀ values, for instance, larger than 4.15 (in dimensionless units) may fail frequently. It is important to note that such high p₀ values are generally not relevant for the experimental contexts targeted by this protocol.

A second limitation concerns the apical configuration. Apical simulations retain a nonzero basal-plane footprint (remnant_area), which can be set below, at, or above the late-interphase mother-cell area to represent footprint reduction, retention, or modest expansion during rounding. This spans only a limited range: the expansion case approximates a roughly twofold increase, whereas apical-area expansion in strongly curved or pseudostratified epithelia can be substantially larger. The apical mode therefore captures the orientation and mechanism of apically-initiated rearrangements rather than their full magnitude, and reproducing the large apical-area increases seen in such tissues lies outside the scope of this passive two-dimensional implementation.

A further limitation is that configurations that fail during the simulation may need to be regenerated using a new random seed. Although the initial configurations are randomized through the Ornstein–Uhlenbeck fluctuation, quench, and equilibration procedure described above, retaining only configurations that lead to successful simulations could in principle introduce a selection bias if the probability of failure depends on the resulting initial configuration. Independent random seeds are used for regenerated configurations to avoid intentionally reusing a particular realization.

As a basic installation check, users can run the initial-configuration generation procedure with P0_values=(3.70) and big_mom_max=2 to generate two initial configurations. Successful completion of the procedure and generation of the two corresponding .vt2d files indicate that the code has been correctly compiled and that the initial-configuration generation workflow is functioning as expected. For a quantitative check of the complete protocol, users can reproduce the whole analysis as mentioned above based on the full ensemble of 324 initial configurations. For the basal protocol, at least 70% of the total T1 transitions should occur during daughter cells reinsertion throughout the range of p₀ values explored in this study (Figure 4).

Troubleshooting

Problem 1

Jobs exceeded wall-time during preparation of initial configurations:

Some output configurations are missing because some nodes may be slower than expected.

Potential solution

Resubmit the simulation after increasing the wall-time limit in

“job_submission_script_multi_P0.sh”.

Example (increased time limit is 5 hours):

>#SBATCH --time=5:00:00

Problem 2

Higher p₀ values can fail intermittently during preparation of initial configurations:

Higher p₀ values generate highly irregular shapes that can lead to failure of a few simulations. As a result, some output configurations are still missing even after increasing wall-time substantially.

Potential solution

Rerun the simulations using the following steps:

• •Rename the “output” folder to “output_old”:

>mv output output_old

• •Prepare the script “job_submission_script_multi_P0.sh” for resubmission associated with the problematic p₀ value by changing the base value of the random number seed.

Example (p₀ = 4.15):

>P0_values=(4.15)

Example (the base of the seed = 11):

>SEED_BASE_START=11

• •Resubmit the job:

>./job_submission_script_multi_P0.sh

• •After the rerun finishes, copy only the newly generated (previously missing) files into the archive, i.e., “output_old”:

Example (p₀ = 3.85 and the large mitotic cell ID=25 was previously missing.)

>cp -r output/new_P0_3.85_big_mom_25.vt2d output_old

If some files are still missing, change the “SEED_BASE_START” to some other value and repeat the rerun-and-merge cycle until the set is complete.

• •When done, make the consolidated “output_old” folder the fresh “output”.

>rm -rf output

>mv output_old output

Problem 3

Jobs exceeded wall-time:

Some .txt files are missing, which is observed during the post-processing process and indicated by additional texts and numbers that appear with “post-processing: done.” because some nodes are slower than expected.

Potential solution

• •Increase the wall-time limit in “job_submission_script.sh” and resubmit.

Example (increased time limit is 30 minutes):

>#SBATCH --time=00:30:00

Problem 4

Failure at higher p₀ values:

Higher p₀ values generate highly irregular shapes that can lead to failure of a few simulations. As a result, some .txt files are missing, which is observed during the post-processing process and indicated by additional texts with numbers that appear with “post-processing: done.”. These additional texts and numbers do not disappear even after increasing the wall-time substantially.

Potential solution

Rerun the simulations using the following steps:

• •Go to the p₀-specific simulation folder on the cluster and rename the “output” folder to “output_old”.

>mv output output_old

• •
  Assign a new seed in “job_submission_script.sh”.

  • Example (the new seed is 10):

>initial_seed=10

• •Resubmit the job:

>./job_submission_script.sh

• •After the completion of simulations, copy only the newly generated (previously missing) files into the “output_old” folder.

>./copy_files_output_to_output_old.sh

• •Make the consolidated “output_old” folder the fresh “output”.

>rm -rf output

>mv output_old output

• •Copy the p₀-specific folder to the local machine in the same way using “scp” as mentioned in step no 16 of Performing Cell Diminution and Daughter Cell Reinsertion and verify with post-processing. If failures persist, repeat the whole process with an updated “initial_seed”.

Problem 5

Failure due to irregular initial configurations at higher p₀:

Higher p₀ values generate highly irregular shapes during initial configuration generation that can lead to weird geometry during cell diminution and daughter cell reinsertion. As a result, simulations of specific mitotic cell IDs fail persistently even after trying with increased wall-time and various “initial_seed”.

Potential solution

• •Delete problematic “.vt2d” files associated with the failed runs during post-processing from both the “initial” and the “output” folder inside the “initial_configs_generation_multi_P0” directory.

Example (Mitotic cell ID 324 and p₀=3.70):

>rm-.f ./initial/new_P0_3.70_big_mom_324.vt2d

../initial_configs_generation_multi_P0/output/new_P0_3.70_big_mom_324.vt2d

• •Regenerate initial configurations using a new seed in “initial_configs_generation_multi_P0” folder based on troubleshooting note problem 2.

Example (Newly assigned base for the seed is 20):

>SEED_BASE_START=20

• •Copy the regenerated “.vt2d” files into the “initial” folder:

Example (Mitotic cell ID 324 and p₀ = 3.70):

>cp

../initial_configs_generation_multi_P0/output/new_P0_3.70_big_mom_324.vt2d ./initial/

• •Rerun job submission and post-processing until only the message below appears:

>post-processing: done.

Resource availability

Lead contact

Further information and clarification should be directed to and will be fulfilled by the lead contact, Subramanian P. Ramanathan (sramanathan@unmc.edu).

Technical contact

Technical questions on executing this protocol should be directed to and will be answered by the technical contact, Tanmoy Sarkar (tanmoy.sarkar@saha.ac.in).

Materials availability

This protocol did not generate any new unique materials or reagents.

Data and code availability

This study did not generate any new datasets. All original code has been deposited in Zenodo (https://doi.org/10.5281/zenodo.22236021) and is also publicly available on GitLab (https://gitlab.com/tanmoy_jsi/cell_diminution_protocols) as of the date of publication. The DOI is listed in the key resources table. Any additional information required to run or adapt this protocol is available from the lead contact and technical contact upon request.

Acknowledgments

This work was supported by funding from multiple institutions and agencies. S.P.R. acknowledges support from a UNMC startup grant and the support of the Single-Cell and Spatial Transcriptomics (SCST) Core within the Nebraska Center for Molecular Target Discovery and Development at UNMC. T.S. and M.K. were supported by the Slovenian Research and Innovation Agency through research projects J1-3009 and J1-60013, the development funding pillar RSF-0106, and research core funding P1-0055. T.S. thanks IISER Thiruvananthapuram and SINP for support.

Author contributions

T.S. designed the study, developed the code, established and tested the protocol, and wrote the manuscript. J.J.L. and R.M. tested the protocol and contributed to script editing. M.K. developed the primary code, provided mentorship, and secured funding. S.P.R. conceived and supervised the project, provided mentorship, secured funding, and edited the manuscript.

Declaration of interests

The authors declare no competing interests.