Published June 25, 2022 | Version v1.0.0
Software Open

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?

  1. Install docker or podman.
  2. 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 running

    docker images
  3. 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
  4. We can run the container we created in step 3 using the following command in the terminal.
    docker start -a -i myContainer
  5. 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 called move_each_time.py.
  6. To execute move_each_time.py script, an input file named Input.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
  7. 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.
    To select a specific row from `Input.txt` for simulation, set the environment variable SLURM_ARRAY_TASK_ID to the row number e.g. to run the simulation for row 123 of Input.txt, in the container shell you can enter the command
    export SLURM_ARRAY_TASK_ID=123
    python3 move_each_time.py
  8. 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 the move_each_time.py file. With the default settings, on my machine, it takes around 4 minutes for the command to complete.
  9. 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 NumPy ndarray. 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.

  10. 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 container
    docker 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?

  1. Install docker or podman.
  2. 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.

  3. To create a container based on the image created in step 2, do
    docker create -i -t --name myContainer localhost/reaction-diffusion:stable bash
  4. 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.
  5. 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 as
    python3 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.

  6. The example command in step 5, takes about 3 minutes to complete on my machine. It will create files SolSamosa.xdmf and SolSamosa.h5 in the working directory of the container. The SolSamosa.xdmf references data stored in the SolSamosa.h5 file. To visualize the result we need to open SolSamosa.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 container
    docker 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 the finalrun.endtime field of the input JSON file.

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

Files (860.2 MB)

Name Size Download all
md5:00d98533c6bd0054f895151feeb8fbbb
192.3 MB Download
md5:c623bcba295269aa560ae9e4c8ca711a
11.7 kB Preview Download
md5:69496aa2426c21926ffd0af81b4bdc7d
5.8 MB Preview Download
md5:aa64d13c87c0cc350a6ad6c1b1f681e3
662.1 MB Download

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)