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.
align+noise.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 variableCCD_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 fromparams.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 theCCD_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>' -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.
- giving the entire codebase a permanent home online
- fragmentation and build automation
- replacing formatted trajectory dump with much faster and more compact unformatted and asynchronous I/O
- include a parameters input file instead of using hardcoded values
- replacing component based code with vector notation wherever possible for SIMD
- remove all GOTO statments
- making the run trajectory reproducible (at least for serial/single-threaded execution) by storing the PRNG seeds
- include real-time progress bar
- include performance calculation and dump
- establishing separate run modes using command line options
- replacing long hardcoded I/O paths with short filenames
- inclusion of logging (at stderr)
- checkpointing. Checkpoints serve dual purpose - run recovery and initialization
- command-line autocompletion
- very basic multithreading using OpenMP
- continuous integration and git-hooks
- beads are stored in rows. Store them in columns instead for much performance improvement (as fortran is column major)
- replace the overcomplicated neighborlist structure with a simple bead-based linked list for decreased overhead
- replace the array-bound-based implementation of circular boundary conditions of beads within cells for better maintainability
- building the cell-cell neighborlist and dumping it in trajectory file in the most compressed way for later analysis such as hexatic order parameter
- current initialization works only for the hardcoded system size. The fix (which would also make the system size assignable by the user) is ready for deployment but can only come after the neighborlist fix.
- consistency check for parameters while reading them in (src/mod_parameters.f90)
- linting
- performance oriented profiling and polishing
- enhancing the driver code (
ccd
) as well as the bash-completion script - compression and archiving of run results (trajectory etc.). Also provide retrieval and garbage cleaning tools.
- include -h|--help for each subcommand using
helpdoc
tool. Detailed docs - include analysis tools (legacy or new)
- include movie making tools : ccd traj_to_xy and ccd movie (gif and mp4)
- install signal handlers for dumping progress status