Sensing the shape of a cell with reaction-diffusion and energy minimization
- 1. Birla Insitute of Technology and Science, Pilani, India
- 2. University of Pennsylvania, USA
- 3. Johns Hopkins University, USA
Description
Sensing the shape of a cell with reaction-diffusion and energy minimization
This repository provides the software used for the results presented in the paper Singh, Amit R., Travis Leadbetter, and Brian A. Camley. "Sensing the shape of a cell: reaction-diffusion and energy minimization." arXiv preprint arXiv:2111.08496 (2021).
Disclaimer: This code is intended to show transparently what we have done, but it is built for internal use and not designed to be generalized without thoroughly understanding what is going on. (See CRAPL)
The following table describes the compressed files of this repository.
File name | Description |
---|---|
plain_text_perimeter_minimization.zip | The source code for perimeter minimization simulations provided as plain text files. These files can be used to check the implementation of the numerical methods explained in the appendix of the paper. |
perimeter_min.tar.gz | A Docker archive that provides a container image to execute the perimeter minimization code. It should not be extracted directly. It is meant to be used with docker-load command. |
plain_text_reaction_diffusion.zip | The source code for reaction diffusion simulations provided as plain text files. These files can be used to check the implementation of the numerical methods explained in the appendix of the paper. |
reaction_diffusion.tar.gz | A Docker archive that provides a container image to execute the reaction diffusion code. It should not be extracted directly. It is meant to be used with docker-load command. |
Each ZIP file has a README.md file that explains how to use the Docker archives. We are including the content of the README files here as well for easier access.
Perimeter-Minimization Software
The code for perimeter minimization has been provided as plain text files and a Docker archive called perimeter_min.tar.gz. To look at the implementation, one can check the plain text files. To execute the code, it is recommended to use the archive. The user should be familiar with docker
or podman
to use the archive. It should not be extracted directly.
How to use the perimeter minimization Docker archive?
- Install
docker
orpodman
. - Run the following command to recreate a Docker image from the tar ball.
docker load -i perimeter_min.tar.gz
This will create a local container image called
localhost/perimeter-minimization:stable
. You can list all the images available on your machine by runningdocker images
- Create a new container called
myContainer
based on the image created in step 2 to run an interactive bash shell in it.docker create -t -i --name myContainer localhost/perimeter-minimization:stable bash
- We can run the container we created in step 3 using the following command in the terminal.
docker start -a -i myContainer
- The command in step 4 will start a shell inside the container. The working directory of the shell is
/home/joe
. It has a file calledmove_each_time.py
. - To execute
move_each_time.py
script, an input file namedInput.txt
should be present in the current working directory. To create a sample input file you can run the following in the container shell.python3 src/generate_inputs.py
Input.txt
contains several rows of parameters for which a perimeter minimization simulation should be run. It has four columns as follows:- FolderId: The directory name in which the output file should be stored.
- Roughness: The amplitutde of high frequency ``roughness'' to add to the sinusoidal surface. It is expressed as a fraction of the amplitude of the sinsuoidal surface. See equation 7 of the paper.
- Area: The domain area value to be imposed as a constraint for perimeter minimization.
- PointId: The suffix of the output file indicating the index of the starting position in the grid.
- X: The x-coordinate of the starting position of the centroid.
- Y: The y-coordinate of the starting position of the centroid.
SLURM_ARRAY_TASK_ID
to the row number e.g. to run the simulation for row 123 ofInput.txt
, in the container shell you can enter the commandexport SLURM_ARRAY_TASK_ID=123 python3 move_each_time.py
- The
move_each_time.py
script is setup to run the simulation for 1000000 time-steps or till the steady state is attained, whichever is earlier. You can adjust these parameters in themove_each_time.py
file. With the default settings, on my machine, it takes around 4 minutes for the command to complete. - On successful completion of the example code in step 7, a HDF5 file will get created with the following path
A9/R0/detail-123.h5
in the current working directory of the container. To see the contents of the HDF5 file, run the following commands in a Python shell in the container>>> import h5py as hp >>> hfile = hp.File('A9/R0/detail-123.h5', 'r') >>> data = hfile['data'][:] >>> hfile.close() >>> data[0,:]
The
data
variable is a NumPyndarray
. Every row of this array represents the result of simulation at a specific timestep (depending on the interval at which we save the results). Each row has 202 columns. The last two columns are the x, and y coordinates of the centroid of the domain at the current time-step. First 200 columns are the radial distances ri of the boundary marker points of the domain from the centroid. (See the SI.)Note: The number of boundary points, the interval at which results are saved, and some other parameters can be configured in the
move_each_time.py
file. Please check the file for more details. - To copy the
detail-123.h5
output file from the container to the local filesystem you can run a command like the following outside the containerdocker cp myContainer:/home/joe/A9/R0/detail-123.h5 ./detail-123.h5
Reaction-Diffusion Software
The code has been provided as plain text files as well as a docker-archive named reaction_diffusion.tar.gz. One can use the plain text files to study the implementation but for running the code it is highly recommended to use the Docker archive.
How to use the reaction diffusion Docker archive?
- Install
docker
orpodman
. - Run the following command in a terminal to load a docker image from the docker-archive.
docker load -i reaction_diffusion.tar.gz
This command will create a docker image on your computer with the name
localhost/reaction-diffusion:stable
. - To create a container based on the image created in step 2, do
docker create -i -t --name myContainer localhost/reaction-diffusion:stable bash
- To start an interactive terminal in the container created in step 3, run
docker start -a -i myContainer
This command will launch a bash shell in the container with the present working directory set to
/home/fenics/reaction_diffusion
. The source code for finite element analysis is in the folder/home/fenics/reaction_diffusion/src
in the container. The directory/home/fenics/reaction_diffusion
contains some “driver” files which use the finite element analysis code to run simulations for different surfaces.- The file
sinusoid_driver.py
was used to generate results for the sinusoidal surface. - The file
ellipsoid_driver.py
was used to generate results for the ellipsoid. - The file
spherebump_driver.py
was used to generate results for the shmoo-like surface. - The file
elongated_driver.py
was used to generate results for the cone-like surface. - The file
samosa_driver.py
was used to generate results for the samosa-shaped surface.
- The file
- Each of the driver files needs an input file to specify the parameters of the simulations. The input is provided as a JSON file. For example, if we are in the
/home/fenics/reaction_diffusion
directory in the container, we can run a samosa simulation aspython3 samosa_driver.py --inputfile ./input/samosa.json
Some sample JSON files have been provided in the
/home/fenics/reaction_diffusion/input
directory of the container image. - The example command in step 5, takes about 3 minutes to complete on my machine. It will create files
SolSamosa.xdmf
andSolSamosa.h5
in the working directory of the container. TheSolSamosa.xdmf
references data stored in theSolSamosa.h5
file. To visualize the result we need to openSolSamosa.xdmf
using ParaView. We used ParaView version 5.9. ParaView is not installed in the container. To copy the result files from the container to the current directory of the local filesystem we can use the following command outside the containerdocker cp myContainer:/home/fenics/reaction_diffusion/SolSamosa.h5 ./SolSamosa.h5 docker cp myContainer:/home/fenics/reaction_diffusion/SolSamosa.xdmf ./SolSamosa.xdmf
Note: The JSON files in the
input
folder are just samples. They are configured to run for only 2 seconds of simulation time. But the simulation does not reach steady state in just 2 seconds. It needs to be run much longer (For results in the paper, we ran it for 5000 seconds in some cases). The simulation end time can be configured in using thefinalrun.endtime
field of the input JSON file. - The JSON files require the file path of a finite element mesh in XDMF format to run the simulations. Some sample meshes have also been provided in the container image in the
/home/fenics/reaction_diffusion/mesh
directory.
Files
plain_text_perimeter_minimization.zip
Additional details
References
- Singh, Amit R., Travis Leadbetter, and Brian A. Camley. "Sensing the shape of a cell: reaction-diffusion and energy minimization." arXiv preprint arXiv:2111.08496 (2021)