aLENS (a Living ENsemble Simulator)
The motivation, algorithm and examples are discussed in this paper: aLENS: towards the cellular-scale simulation of motor-driven cytoskeletal assemblies
This file will guide you through the preparation, compilation, running, and postprocessing of using aLENS.
To use this software, the minimum requirement is a mpi c++ compiler fully supporting
openmp-4.0, for example,
mpicxx that calls
Clone the repo
First, clone this repo:
git clone https://github.com/wenyan4work/aLENS.git
This repo relies on two submodules. You need to initialize them after cloning:
cd aLENS git submodule init git submodule update
Step 1. dependencies of SimToolbox
An easier way is to use the automated compilation and installation scripts hosted at
Step 2. dependencies of KMC
KMC relies on the Gauss-Kronrod quadrature integrator in Boost.math. Make sure you have
boost>=1.70 installed. Only the boost header is necessary.
Use 'cmake' to compile things. If
make finishes successfully, now you have a usable executable called
aLENS.X reads expects 4 input files:
RunConfig.yamlspecifies configuration for system and MTs.
ProteinConfig.yamlspecifies configuration and number for proteins.
TubuleInitial.datspecifies initial configuration of MTs.
ProteinInitial.datspecifies initial configuration of proteins.
You can go to the folder
InitialConfigExample/SimplePair to see examples of these files.
Config.yaml files are necessary, but the two
Initial.dat files are optional.
There are three cases:
- Case 1. No
datfile exists. In this case MTs and proteins will be generated according to the settings in
- Case 2.
TubuleInitial.datfile exists, but
ProteinInitial.datdoes not. In this case MTs will be read from the
TubuleInitial.dat, and the MT number & length settings in
RunConfig.yamlwill be ignored. Proteins will be generated according to the settings in
- Case 3. Both
ProteinInitial.datfiles exits. In this case MTs will be read from the
TubuleInitial.dat, and the MT number & length settings in
RunConfig.yamlwill be ignored. Proteins will be read from the file
aLENSwill try to reconstruct the initial binding status according to
ProteinInitial.dat. If reconstruction fails for a certain protein, for example, if a protein is specified to bind some MT but the MT does not appear at the correct location, an error message will be printed out and this end (that an error appears) of this protein will be set to unbound and the program continues.
In general, Case 1 is good for initiating a simulation and Case 3 is good for continuing a simulation with saved data files. Case 2 is useful for some cases where the effect of protein on a given MT configuration is of interest.
The minimum set of necessary files
In the minimu case, you need only three files and a folder to run the executable:
- one executable
- two input configuration files
- one folder
resultfor saved data files.
Your first run
Use the provided example to run your first simulation:
wyan$ cp ./InitialConfigExample/PairBinding/* ./ wyan$ ./aLENS.X > ./outrun.log
aLENS.X outputs to the folder
result is at the same folder as
It first writes a file
simBox.vtk, which shows the simulation box as a simple rectangular box. For example:
wyan$ cat ./result/simBox.vtk # vtk DataFile Version 3.0 vtk file ASCII DATASET RECTILINEAR_GRID DIMENSIONS 2 2 2 X_COORDINATES 2 float 0 10 Y_COORDINATES 2 float 0 10 Z_COORDINATES 2 float 0 10 CELL_DATA 1 POINT_DATA 8
Then the executable writes 6 different sequences of data files.
Two of them are human readable ascii files:
SylinderAscii_*.datare human readable data files of MTs (Sylinder = Spherocylinder). These files can be directly used as
ProteinAscii_*.datare human readable data files of proteins. These files can be directly used as
Four of them are XML vtk format in base64 binary encoding. These are not human readable but can be conveniently loaded into
Paraview for visualization or read by VTK (either python or cpp) for data processing.
Sylinder_*.pvtpsave data for MTs.
Protein_*.pvtpsave data for proteins.
ConBlock_*.pvtpsave data for collision and protein constraint blocks.
For explanation of these
pvtp files, read the official guide of vtk file format:
https://lorensen.github.io/VTKExamples/site/VTKFileFormats/#parallel-file-formats. In short, each
pvtp file (parallel vtp) is a tiny index to a set of
vtp files (serial vtp), which holds the actual data.
aLENS.X is written such that each MPI rank writes its own set of data to a unique
vtp file. Therefore the number of
vtp files in each
pvtp file index is equal to the number of MPI ranks. The restriction is that the index
pvtp file must appear in the same location as those
vtp data files.
These sequeces of files are divided into different subfolders so each subfolder contains no more than roughly 3000 files. This is due to the limitations of parallel file systems on some mpi clusters where saving a large number of files in a single directory destroys IO performance or even crashes the executable.
The data files are saved in different folders, but for postprocessing & visualization, in some cases there are some restrictions that all files of the same sequence must appear in the same folder otherwise the postprocessing or visualization program may fail to load the entire sequence. The python script
Result2PVD.py is used to handle this situation. It creates
.pvd files, which are indices to those
.pvtp files and can be loaded by
Paraview, so that all files belong to one sequence can be found in one place. It is safe to run this script when
aLENS.X is still running and writing data.
To run this script:
wyan$ cd ./result/ wyan$ python3 ./Result2PVD.py wyan$ ls ./*.pvd ./ConBlockpvtp.pvd ./Proteinpvtp.pvd ./Sylinderpvtp.pvd
This is the actual running mode for a cluster. However, due to the inconsistency of how
mpich handles multithread mapping, you may need different environment variable settings. Here is a brief summary of things you may have to tune.
In the folder
scripts you can find
jobsub.slurm as an example of how to submit jobs to slurm with openmpi.
If you are not sure how you should setup things, consult your system administrator or play with AMASK to see how different settings affect different threading mapping and binding modes.
Environment Variable Settings
OMP_MAX_ACTIVE_LEVELS=1for new compilers.
Nto the number of cores. Hyperthreading may or may not be useful.
OMP_DISPLAY_ENV=VERBOSERecommended, helpful for debugging environment variables
OMP_PROC_BIND=spreadRecommended by Kokkos, you should check if it works for you
OMP_PLACES=threadsRecommended by Kokkos, you should check if it works for you
If using Intel MKL:
MKL_THREADING_LAYER=GNUdepending on if the compiler is
If using Intel MPI (optional):
If using OpenBLAS (optional):
Nto tune multithreading. .
The priorities are
OMP_NUM_THREADS. If you compile OpenBLAS with
USE_OPENMP=1, you should set the
OMP_NUM_THREADS environment variable; OpenBLAS ignores
GOTO_NUM_THREADS when compiled with