a Living ENsemble Simulator -- a lens to help you watch biophysics

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

Introduction

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 c++14 and openmp-4.0, for example, mpicxx that calls gcc>=7.

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

Install dependencies

Step 1. dependencies of SimToolbox

An easier way is to use the automated compilation and installation scripts hosted at https://github.com/wenyan4work/Environment.

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.

Compiling

Use 'cmake' to compile things. If make finishes successfully, now you have a usable executable called aLENS.X.

Executable input: Config.yaml and Initial.dat

The executable aLENS.X reads expects 4 input files:

  • RunConfig.yaml specifies configuration for system and MTs.
  • ProteinConfig.yaml specifies configuration and number for proteins.
  • TubuleInitial.dat specifies initial configuration of MTs.
  • ProteinInitial.dat specifies initial configuration of proteins.

You can go to the folder InitialConfigExample/SimplePair to see examples of these files.

The two Config.yaml files are necessary, but the two Initial.dat files are optional.
There are three cases:

  • Case 1. No dat file exists. In this case MTs and proteins will be generated according to the settings in RunConfig.yaml and ProteinConfig.yaml
  • Case 2. TubuleInitial.dat file exists, but ProteinInitial.dat does not. In this case MTs will be read from the TubuleInitial.dat, and the MT number & length settings in RunConfig.yaml will be ignored. Proteins will be generated according to the settings in ProteinConfig.yaml.
  • Case 3. Both TubuleInitial.dat and ProteinInitial.dat files exits. In this case MTs will be read from the TubuleInitial.dat, and the MT number & length settings in RunConfig.yaml will be ignored. Proteins will be read from the file ProteinInitial.dat. aLENS will 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 aLENS.X.
  • two input configuration files RunConfig.yaml and ProteinConfig.yaml.
  • one folder result for saved data files.

Your first run

Use the provided example to run your first simulation:

wyan$ cp ./InitialConfigExample/PairBinding/* ./
wyan$ ./aLENS.X > ./outrun.log

Data organization

The program aLENS.X outputs to the folder result. result is at the same folder as aLENS.X itself.

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_*.dat are human readable data files of MTs (Sylinder = Spherocylinder). These files can be directly used as TubultInitial.dat by renaming.
  • ProteinAscii_*.dat are human readable data files of proteins. These files can be directly used as ProteinInitial.dat by renaming.

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_*.pvtp save data for MTs.
  • Protein_*.pvtp save data for proteins.
  • ConBlock_*.pvtp save 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

MPI+OpenMP run

This is the actual running mode for a cluster. However, due to the inconsistency of how Intel mpi, openmpi, and 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

OpenMP

  • OMP_NESTED=FALSE REQUIRED and/or OMP_MAX_ACTIVE_LEVELS=1 for new compilers.
  • OMP_NUM_THREADS=N Change N to the number of cores. Hyperthreading may or may not be useful.
  • OMP_DISPLAY_ENV=VERBOSE Recommended, helpful for debugging environment variables
  • OMP_PROC_BIND=spread Recommended by Kokkos, you should check if it works for you
  • OMP_PLACES=threads Recommended by Kokkos, you should check if it works for you

If using Intel MKL:

  • MKL_THREADING_LAYER=INTEL or MKL_THREADING_LAYER=GNU depending on if the compiler is icpc or g++
  • MKL_INTERFACE_LAYER=LP64 Never use ILP64

If using Intel MPI (optional):

  • I_MPI_ADJUST_ALLTOALLV=1
  • I_MPI_ADJUST_ALLTOALL=1

If using OpenBLAS (optional):

  • OPENBLAS_NUM_THREADS=N Change N to tune multithreading. .

The priorities are OPENBLAS_NUM_THREADS > GOTO_NUM_THREADS > OMP_NUM_THREADS. If you compile OpenBLAS with USE_OPENMP=1, you should set the OMP_NUM_THREADS environment variable; OpenBLAS ignores OPENBLAS_NUM_THREADS and GOTO_NUM_THREADS when compiled with USE_OPENMP=1.

Similar Resources

TengineFactory - Algorithm acceleration landing framework, let you complete the development of algorithm at low cost.eg: Facedetect, FaceLandmark..

TengineFactory - Algorithm acceleration landing framework, let you complete the development of algorithm at low cost.eg: Facedetect, FaceLandmark..

简介 随着人工智能的普及,深度学习算法的越来越规整,一套可以低代码并且快速落地并且有定制化解决方案的框架就是一种趋势。为了缩短算法落地周期,降低算法落地门槛是一个必然的方向。 TengineFactory 是由 OPEN AI LAB 自主研发的一套快速,低代码的算法落地框架。我们致力于打造一个完全

Dec 11, 2022

A tool to suggest github repositories based on the repositories you have shown interest in.

A tool to suggest github repositories based on the repositories you have shown interest in.

gitsuggest A tool to suggest github repositories based on the repositories you have shown interest in. Whats happening here? Programs must be written

Dec 17, 2022

A custom GEGL filter that does layer effects. It may not be non-destructive but you can make presets of your favorite text styles

A custom GEGL filter that does layer effects. It may not be non-destructive but you can make presets of your favorite text styles. Futures plans are going to include an image file overlay, and pro tip you can do a multistroke if sacrifice a shadow/glow.

Jan 2, 2023

T-Watch 2020 v1 compatible firmware providing WiFi and BLE testing tools (and also, a watch :D)

ESP-IDF template app This is a template application to be used with Espressif IoT Development Framework. Please check ESP-IDF docs for getting started

Dec 23, 2022

C64 Watch is a customized T-Watch 2020 that was inspired by the Commodore 64 computer. It features a C64 theme and a built-in BASIC interpreter.

C64 Watch is a customized T-Watch 2020 that was inspired by the Commodore 64 computer. It features a C64 theme and a built-in BASIC interpreter.

C64 Watch C64 Watch is a customized T-Watch 2020 that was inspired by the Commodore 64 computer. It features a C64 theme and a built-in BASIC interpre

Nov 26, 2022

Living off the Land Attack in Linux, load an anonymous file in memory.

Living off the Land Attack in Linux, load an anonymous file in memory.

ELFMemoryLoader Living off the Land Attack in Linux。 Linux场景下的核心载荷不落地攻击。 Loader get elf data from remote server, then use file descriptor to run elf i

Sep 24, 2022

Had a tough time playing Microsoft Wordament ? Well WORDament_Solver has your back. It suggests you meaningful words you can use while playing the game and help you top the leaderboard.

Had a tough time playing Microsoft Wordament ? Well WORDament_Solver has your back. It suggests you meaningful words you can use while playing the game and help you top the leaderboard.

WORDament_Solver Had a tough time playing Microsoft Wordament ? Well WORDament_Solver has your back. It suggests you meaningful words you can use whil

Aug 19, 2021

ORB-SLAM3 is the first real-time SLAM library able to perform Visual, Visual-Inertial and Multi-Map SLAM with monocular, stereo and RGB-D cameras, using pin-hole and fisheye lens models.

ORB-SLAM3 is the first real-time SLAM library able to perform Visual, Visual-Inertial and Multi-Map SLAM with monocular, stereo and RGB-D cameras, using pin-hole and fisheye lens models.

Just to test for my research, and I add coordinate transformation to evaluate the ORB_SLAM3. Only applied in research, and respect the authors' all work.

Jul 11, 2022

Source Code for SIGGRAPH Asia 2021 Paper "Ensemble Denoising for Monte Carlo Renderings"

Ensemble Denoising Source Code for SIGGRAPH Asia 2021 Paper Ensemble Denoising for Monte Carlo Renderings. Paper | Code | Talk Slides Dependencies A C

Nov 25, 2022

Source Code for SIGGRAPH Asia 2021 Paper "Ensemble Denoising for Monte Carlo Renderings"

Ensemble Denoising Source Code for SIGGRAPH Asia 2021 Paper Ensemble Denoising for Monte Carlo Renderings. Paper | Code | Talk Slides Dependencies A C

Nov 25, 2022

Flutter real-time magnifying glass lens widget with Barrel/Pincushion distortion

Flutter real-time magnifying glass lens widget with Barrel/Pincushion distortion

MagnifyingGlass Flutter plugin Flutter real-time magnifying glass lens widget with Barrel/Pincushion distortion. Works on Android, iOS and desktop. Do

Nov 9, 2022

This project is pretty straightforward, you have to recode printf. You will learn what is and how to implement variadic functions. Once you validate it, you will reuse this function in your future projects.

This project is pretty straightforward, you have to recode printf. You will learn what is and how to implement variadic functions. Once you validate it, you will reuse this function in your future projects.

100/100 Introduction to ft_printf This is the third project in the 1337 Curriculum #42network . This project is pretty straight forward, recode the pr

May 27, 2022

A Motorola 68K simulator based on Musashi-master 68K simulator.

cpmsim Originally referenced as http://home.earthlink.net/~schultdw/cpm68/simulator.html (now 404) This simple CP/M-68K simulator, is built around the

Oct 26, 2021

Arduino sample code to help you get started using the Soracom IoT Starter Kit!

Arduino sample code to help you get started using the Soracom IoT Starter Kit!

Soracom IoT Starter Kit The Soracom IoT Starter Kit includes everything you need to build your first connected device. It includes an Arduino MKR GSM

Jul 30, 2022

this package help you to give glassomorphic+ neomrphic both effects to a container (at a time).

this package help you to give glassomorphic+ neomrphic both effects to a container (at a time).

duomorphsim this package help you to give glassomorphic+ neomrphic both effects to a container (at a time). Usage DuoMorphicCard need four argument wh

Aug 23, 2021

A reviewer can help you memorize things

Reviewer What is a reviewer? A reviewer can help you memorize things Can't memorize things clearly? You probably need to review it everyday. When it c

Feb 11, 2022

A Repo to help, when you're stuck at a particular competitive coding problem.

Competitve Coding Solutions A Repo to help, When you're stuck at a particular competitive coding problem. Note: Before knowing the solution, it's reco

Oct 27, 2022

Examples to help you programming the MSP430FR2433 from Texas Instruments.

MSP430FR2433 examples Examples to help you programming the MSP430FR2433 from Texas Instruments. I wrote this code quite a few years ago when the code

Feb 2, 2022

Boot arbitrary iBoot on S5L8747, S5L8947X and S7002, T8002, T8004 ("watch" branch)

Example of building with a different ARM toolchain [email protected] checkm8_bootkit % TOOLCHAIN=/opt/gcc-arm-none-eabi-7-2018-q2-update/bin ARM_CC

Nov 10, 2022
Comments
  • docker files

    docker files

    I think your method is very interesting, and I would like to run my own benchmarks.

    Your "Author Response" which is visible on eLife.com says "We have also packaged the precompiled executable as a Docker image, freely available on Docker Hub (https://hub.docker.com/r/wenyan4work/alens), so that any interested users can run aLENS on any operating system, without compilation."

    However, on https://hub.docker.com/r/wenyan4work/alens/tags, I only see one architecture "linux/amd64". I am interested in running on the MacOS 12.6, Apple Silicon (ARM64) architecture. Could you provide this or clarify the situation? Thank you!

Source Code for SIGGRAPH Asia 2021 Paper "Ensemble Denoising for Monte Carlo Renderings"

Ensemble Denoising Source Code for SIGGRAPH Asia 2021 Paper Ensemble Denoising for Monte Carlo Renderings. Paper | Code | Talk Slides Dependencies A C

Nov 25, 2022
Source Code for SIGGRAPH Asia 2021 Paper "Ensemble Denoising for Monte Carlo Renderings"

Ensemble Denoising Source Code for SIGGRAPH Asia 2021 Paper Ensemble Denoising for Monte Carlo Renderings. Paper | Code | Talk Slides Dependencies A C

Nov 25, 2022
Examples to help you programming the MSP430FR2433 from Texas Instruments.

MSP430FR2433 examples Examples to help you programming the MSP430FR2433 from Texas Instruments. I wrote this code quite a few years ago when the code

Feb 2, 2022
Chunky pixel watch face for SQFMI's Watchy

pxl999 Pxl999 is a chunky pixel watch face for SQFMI's Watchy. This watch face features live weather updates every 30 minutes and NTP syncing twice a

Apr 17, 2022
Pedestrian simulator powered by the social force model
Pedestrian simulator powered by the social force model

Pedestrian simulator powered by the social force model

Dec 30, 2022
Time Series Quick Simulator - able to perform time series analysis and to setup validation experiments.

tsqsim Time Series Quick Simulator - able to perform time series analysis and to setup validation experiments. With its somewhat limited plotting capa

Dec 4, 2022
Python wrapper for Environment Simulator Minimalistic (esmini)
Python wrapper for Environment Simulator Minimalistic (esmini)

python-esmini is a python wrapper for Environment Simulator Minimalistic (esmini). Install the package python-esmini is now only available for the Lin

Aug 4, 2022
this is a repo of where you will get to see tic tac toe AI intregrated project
this is a repo of where you will get to see tic tac toe AI intregrated project

?? Tic-Tac-Toe-AI-Intregrated ?? What is the meaning of AI Intregrated ??‍♀️ ??‍♂️ ❓ ❓ You all have Played Tic Tac Toe in your life if you don't know

Dec 5, 2022
Implementation of Univaraint Linear Regresion (Supervised Machine Learning) in c++. With a data set (training set) you can predict outcomes.

Linear-Regression Implementation of Univaraint Linear Regresion (Supervised Machine Learning) in c++. With a data set (training set) you can predict o

Nov 3, 2021