red cell

Corpuscles

Introduction

Corpuscles is a C library to resolve the elastic energy and force of a membrane surface, which is represented by an unstructured triangulated mesh. It also simulates transformations between different configurations/shapes of a closed membrane by a minimization procedure under various constraints.

Various components can be switched on/off at will, such as
  1. Bending elasticity of lipip bilayer
  2. Strain (both shear and strecth) elasticity of cytoskeleton
  3. Viscosity of lipid membrane
  4. Thermal fluctuations of lipid membrane
  5. Constraint of reduced volume of a closed membrane surface
  6. Constraint of total area of a closed membrane surface
  7. Constratin of total volume of a closed membrane surface
  8. Constratin of area difference between outer- and inner-surface

For different components, variations of model/law can be selected such as Helfrich/spontaneous curvature model for bending elasticity and Skalak law for strain elasticity.

For different models/laws, variations of schemes impelemented can also be choosen such as Gompper and Kroll scheme and Juelicher scheme for the bending model of spontaneous curvature. See more details in https://cselab.github.io/corpuscles

Install

Minimal dependencies are C and Fortran 90 compilers, GNU Scientific Library, and pkg-config.

Optional dependencies geomview, maxima, and pandoc.

Adjust conf.mk if you want to change defaults

$ cat conf.mk
CC = gcc
FC = gfortran

FCFLAGS = -O2 -g
FXFLAGS = -fallow-argument-mismatch

GSL_CFLAGS = " `gsl-config --cflags `"
GSL_LDFLAGS = " `gsl-config --libs `"

CFLAGS = -O2 -g
LDFLAGS =
PREFIX = $(HOME)/.local
DATAPATH = $(HOME)/.co
MAXIMA_HOME = $(HOME)/.maxima

# prefix for commands
P = co

PREFIX/bin should be on the path, for example

$ cat $HOME/.bashrc
PATH="$HOME/.local/bin:$PATH"
Library is installed under the path PREFIX. Run
$ MAKEFLAGS=-j4 make
If you have atest you can run
$ make test

You can also use a docker containter.

Examples

Hello world

A program in example/hello computes area of a triangle.

$ cat main.c
#include <stdio.h>

#include <real.h>
#include <co/tri.h>

#define FMT CO_REAL_OUT

int
main(void)
{
    real A, a[] = { 0, 0, 0 }, b[] = { 2, 0, 0 }, c[] = { 0, 1, 0 };
    A = tri_area(a, b, c);
    printf("Area of a triangle is : " FMT "\n", A);
}

$ cat Makefile
include ../../conf.mk
PREC = d
main: main.c
    $(CC) main.c $(CFLAGS)  `co.conf --cflags --libs $(PREC) ` $(LDFLAGS) -o $@
clean:; rm -f main

$ ./main
Area of a triangle is : 0.9999999999999999

Read mesh file

Corpuscles reads OFF files. Here is a file with triangular pyramid.

triangular pyramid

This program reads an OFF file from an input stream:

$ cat main.c
#include <stdio.h>

#include <real.h>
#include <co/array.h>
#include <co/he.h>
#include <co/y.h>

int
main(void)
{
    real *x, *y, *z, hi;
    He *he;
    int nv, nt;

    y_inif(stdin, &he, &x, &y, &z);
    nv = he_nv(he);
    nt = he_nt(he);
    hi = array_max(nv, x);
    printf("number of vertices is %d\n"
           "number of triangles is %d\n"
           "maximum x coordinate is " CO_REAL_OUT "\n", nv, nt, hi);
    y_fin(he, x, y, z);
}

$ make
$ ./main < `co.path`/regular/tetra.off
number of vertices is 4
number of triangles is 4
maximum x coordinate is 1

Write mesh file

Read off, compute area of every triangle, and output off file with colors (example/off/write/area)

$ cat main.c
#include <stdio.h>

#include <real.h>
#include <co/area.h>
#include <co/err.h>
#include <co/off.h>
#include <co/he.h>
#include <co/memory.h>
#include <co/y.h>

int main(void) {
    int nt;
    real *x, *y, *z, *a;
    He *he;
    y_inif(stdin, &he, &x, &y, &z);
    nt = he_nt(he);
    CALLOC(nt, &a);
    he_area_tri(he, x, y, z, a);
    boff_tri_fwrite(he, x, y, z, a, stdout);
    y_fin(he, x, y, z);
    FREE(a);
}

$ ./main < $(co.path)/rbc/laplace/0.off > out.off

To see the results

$ co.geomview -r 55.9195 -13.672 8.69021 -f 25.0389 out.off

mesh colored by triangle area

Refine mesh

Using sqrt(3)-subdivision scheme
$ co.geomview -r 60 -40 10 -f 22 `co.path`/rbc/icosahedron/0.off
$ co.sqrt3 < `co.path`/rbc/icosahedron/0.off > a.off
$ co.geomview -r 60 -40 10 -f 22 a.off

red cell with 1280 trianglles

red cell with 3840 trianglles

Visualization

We use a wrapper to geomview.

$ co.geomview -h
co.geomview [-t x y z] [-r x y z] [-a APPEARANCE] [-o FILE] [OFF]..
he geomview wrapper
-t x y z      translation
-r x y z      rotation in degree
-f zoom       field of view (default is 40)
-a APPEARANCE load appearance from a file
-o FILE       write FILE and exit
-O            write all PPM files and exit
-OO           write all oogl files and exit
-format ppmscreen|ppm|ps|ppmosmesa|ppmosglx
-p command    process every off file by running  'command ' < IN.off > OUT.off
-n none|each|all|keep normalization status (see geomview manual)
-c command    run command on every file and write output to stderr, %f is replaced by a file name
-e command    if keys  'e ' is pressed runs
               '<OFF command -t x y z -r x y z -f zoom -i [index of a file] -n  [number of files]  ' or
               '<OFF command ' if -e  '|command ' is passed
-i command    run command on every image, %i replaced by input; %o -- by output; %b --- by basename

Keys:
    q: quit
    s: save snap.ppm
    S: save every snapshot
    e: run command on OFF file (see -e option)
    p: panel
    j/k: switch between off files
    J: dump file name
    [SPC]: dump orientation and field of view

Environment variables:
WX, WY: resolution of the snapshot (default: 800x600)
BACKGROUND: default ( '1 1 1 ')
GEOMVIEW_ARGS: pass to geomview

Examples:
co.geomview -t 0.25 0.25 0     data/rbc.off
co.geomview -a data/appearance data/rbc.off
co.geomview -o snap.ppm        data/rbc.off
co.geomview                    data/rbc.off data/sph.off
co.geomview -p co.orient       data/rbc.off data/sph.off
co.geomview -c off.volume      data/rbc.off data/sph.off

Library

Floating point precision

prec/s/real.h, prec/d/real.h, prec/l/real.h
single, double, long double

Math

vec.h, edg.h, tri.h, dih.h, ten.h
vector, edges, triangels, dihidrals, tensors
dvec.h, dedg.h, dtri.h, ddih.h
derivatives of vector edges, triagels, dihidrals
ring.h
operation on the first ring of neighbors

Utility

array.h
array related functions
argv.h
read from argv and shift
err.h
error handling
endian.h
deal with endianess
macro.h
macros
sum.h
Kahan summation
memory.h
memory related
util.h
uncategorazed

Surface properties

area.h
area
volume.h
volume
laplace.h
Laplace operator of coordinates
normal.h
normal

“Forces”

bending.h
generic interface to several bending forces
forces.h
generic interface to forces
stretch.h
stretching force

Surface transformation

equiangulate.h
equlatirate triangles
orient.h
orient surface in a direction of eigen values of momentum tensor
restore.h
restore a volume of the surface
transformation.h
translate, rotate, and and scale surface
remesh.h
“edit” surfaces

Half-edg related

read.h
read half-edg to intermediate structure HeRead, used to initialize half-edg
he.h
half edg data structure (provides half-edg API)
hash.h
stores an integer for a pair of integers

IO

gts.h, obj.h, off.h, ply.h, punto.h, stl.h, stl.h, xdmf.h : read/write GTS, OBJ, OFF, PLY, punto, STL, VTK, and XDMF files.

X and Y

x.h
simple interface for one surface
y.h
not so simple interface

Documentation

git pages docs/index.html is generated from README.md.m4. To update run

$ make html

requires pandoc.

Hacking

After adding new files to lib update depdendencies:

$ (cd lib && ./bootstrap)

Publications

Bian, X., Litvinov, S., & Koumoutsakos, P. (2020). Bending models of lipid bilayer membranes: Spontaneous curvature and area-difference elasticity. Computer Methods in Applied Mechanics and Engineering, 359, 112758. doi:10.1016/j.cma.2019.112758