Collective Cell Dynamics

This software contains the simulation engine and analysis tools for the bead-spring model as presented in A. Mkrtchyan, J. Astrom, M. Karttunen, Soft Matter, 2014, 10, 4332. The model may or may not have been modified to suit our needs. Complete Equations of Motion are available here subject to availing the license-key from us.

fluid_tissue_T1.mp4

Status

Work in progress. Check TODO list below.

Dependencies

gfortran or ifort(recommended). Note: ifort is free now, doesn't require a license anymore.
fortdepend or its fork for generating dependencies during build. For Ubuntu 18.04, you may also have to install importlib-metadata with: pip3 install importlib.metadata
bash because we suck at writing fully POSIX-compliant shell scripts
pv for showing real-time progress bar
gnuplot for visualization
xz for trajectory compression
ffmpeg for movie generation
jq, curl and sponge for quotes
helpdoc for showing help/usage documentation
freud for constructing periodic Voronoi tesselations. It may be installed with: pip3 install freud-analysis. (freud uses Voro++, a C++ library, with which we may replace freud later on).

Build

Install, if non-existent, the above dependencies first
Download this project:

git clone --depth=1 https://github.com/PhyBi/Collective-Cell-Dynamics ccd

Change to the downloaded project directory: cd ccd
Compile: Use make as usual. Other uses: make rebuild, make clean.

Notes: Default compiler is gfortran. To use ifort instead, use make FC=ifort. To include OpenMP, set the OMP variable when running make, e.g. make OMP=set rebuild. Set the DEBUG variable in order to build in debug mode.

Install

make install

If you don't want to install it right away but test: . setup_test_env.sh

Uninstall

make uninstall

Command-line

ccd

Supported subcommands are available using bash-completion: ccd <TAB><TAB>

Sample Workflow

The information in this section is anything but exhaustive; the subcommands are more versatile than apparent from what follows. Use the -h option in each subcommand to see its detailed usage. For any queries, feel free to ask us.

Create and change into a new directory.
Copy and edit the params.in file. Put only those key-value pairs for the run parameters that you don't want the default for. ccd show_params lists all parameters ccd takes. For meaning and default values of the parameters, please look up src/mod_parameters.f90.
Simulations also produce/use/update two non-portable binary files: the trajectory (traj.bin) and a checkpoint (state.cpt). The checkpoint serves dual purpose: run recovery and initialization. It helps in run recovery by storing the last uncorrupted record/frame number in the trajectory file as well as the number of pending timesteps and the current timestep. Initialization is served by storing the complete memory representation of the coordinates at a timepoint (state).

# Random initialization
ccd init

# Run
ccd run > 'metadata.txt' 2> 'logfile.txt'

# State/Checkpoint(state.cpt) to XY dump(config.xy)
ccd cpt_to_xy

# Visualize config from XY dump (config.xy), highlighting the 10th cell in green
ccd visual -L -H '10@green#' # Use the GNUPLOT_PATH env variable if gnuplot is not in PATH

# To check live run progress
ccd status

# Make a movie (.mp4) of length=15 seconds out of the trajectory (traj.bin)
ccd traj_to_xy 'movie'
ccd movie -l 15 -H1# 'movie'

# To archive run results (trajectory: traj.bin and final-state/checkpoint: state.cpt)
ccd archive 'metadata.txt'

# To retrieve/restore archived run results
ccd retrieve 'metadata.txt'

# Garbage cleanup
ccd clean_archive 'metadata.txt'

Other ways to pass parameters

If you want to use another path instead of params.in for the run-parameter file, put the same in the enviroment variable CCD_PARAMS_PATH
If all (or most) of your runs use certain common non-default parameter values, provide those in the key-value file (RC file) at ${HOME}/.ccdrc. ccd reads these parameters before reading parameters from params.in or ${CCD_PARAMS_PATH}. Values read in from the latter file take precedence in case of conflicts. Non-default locations of the RC file may be passed through the CCD_RC_PATH enviroment variable.
It is also possible to pass run-time parameters using the command-line. These values take precedence over those read in from from params.in or ${CCD_PARAMS_PATH} in case of conflicts. For example,

ccd -p '<parameterA>=<valueA>; <parameterB>=<valueB>' show_params

or equivalently,

ccd -p '<parameterA>=<valueA>' -p '<parameterB>=<valueB>' show_params

Organization made easy

Redirect the stdout of ccd run to metadata files as shown above.
Archive the run results by providing the metadata file to ccd archive.
Organize the small metadata files with commit messages and branches using git, and preserve them in cloud (e.g. GitHub).
Retrieve the run results later, as necessary, by providing the corresponding metadata file to ccd retrieve.
Backup the archive (${HOME}/.ccd) from time to time, copying the new files only.

Quotes

To turn off the GROMACS-like quotes at the end of each command, set the CCD_NO_QUOTES enviroment variable. Do so if you mostly use ccd when offline.

Extensibility

User can put her own routines (source code and scripts) in the custom directory, provided the main sources and executable scripts are named as ccd_<subcmd>.f90 and ccd_<subcmd> respectively. Such sources will be automatically built (installed) when one builds (installs) the current project. Built executables and scripts can be invoked as ccd <subcmd> [<options>].

Note

If met with segmentation faults or stack-smashing error, make the stack size unlimited in the Bash session with ulimit -s unlimited; export OMP_STACKSIZE=500m. If the problem persists, rebuild with make DEBUG=set and report @ issue. Also try the -heap-arrays compiler flag (FF) for ifort in the Makefile.

License

No use of this software shall be made without written permission from the PI, Dr. Dipjyoti Das.

Disclaimer

Use this software at your own risk. We the devs or this organization/lab/institute or the PI are/is not responsible for any damage caused by the use of this software.

TODO

This software is built from a monolithic legacy code. Hence much had and still would have to be done towards enhancements in performance, maintainability, user-interface etc.

phybi / collective-cell-dynamics Goto Github PK