A lipid-resolution molecular dynamics simulator of human red blood cells
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
example-large
installer
src
util
README.md

README.md

Quick Start Guide for: OpenRBC - A Fast Simulator of Red Blood Cells at Protein-Resolution

Compilation

x86 processor, recent Linux distribution, g++ newer than 5.3.0:

cd <working_copy>/src
make

To override the compiler used

make CXX=path_to_compiler

For IBM Power 8 architecture

make ARCH=power8

For older Linux systems whose glibc do not provide an std::aligned_alloc function.

make AALLOC=1

A summary of arguments to make:

  • ARCH=[power8|x86] compilation target architecture
  • CXX=[g++|xlC_r|icpc] compiler
  • DEBUG=[0|1] whether to turn on 'optimization for debug'
  • AALLOC=[0|1] fall-back option for older linux kernels that do not provide the std::aligned_alloc function.

Small example

cd <working_copy>
mkdir example-small
cd example-small
ln -s ../src/openrbc
OMP_NUM_THREADS=... ./openrbc -E 100 -t 10

To see a list of command line options:

./openrbc --help

OpenMP thread binding is vital to achieve optimal performance acorss multiple NUMA domains. This can be done by setting the environment variables:

Compiler/Runtime Environment variable
Generic, OpenMP 4.5+ OMP_PROC_BIND
G++/GOMP GOMP_CPU_AFFINITY
Intel/IOMP KMP_AFFINITY

In most cases placing consecutive threads on adjacent core/hardware threads would be optimal, however it is highly recommended that you test and tune thread binding before performing production runs. To figure out your socket/core topology refer to the lstopo, hwloc-ls, hwloc-info commnands from the hwloc package.

Full-size example

cd <working_copy>/example-large
ln -s ../src/openrbc
OMP_NUM_THREADS=... ./openrbc -i trimesh -m rbc -E 100 -t ...

where -i instruct the program to initialize using mesh files specified by the -m argument.

Visualization

The initial structure file can be visualized with VMD using the following TCL command.

topo readlammpsdata cell.data bond

The trajectory can be convert to a LAMMPS trajectory format by

cd <working_copy>/src
make orbc-util
cd <working_copy>/<case_directory>
../orbc-util convert cell.orbc cell.lammpstrj

which can then be appended to the initial structure in VMD by

mol addfile cell.lammpstrj autobonds 0

The LAMMPS trajectory file, however, is text-based and works poorly for whole-cell simulations containing millions of particles. In this case a binary format can be generated and appended in vmd:

../orbc-util convert cell.orbc cell.%06d.namdbin
% adjust iteration bound and increment accordingly
for {set i 0} {$i < 1000000} {set i [expr $i + 100]} {
	mol addfile cell.[format "%06d" $i].namdbin type namdbin
}

Video on YouTube