SLIMED (Subdivision-limit membrane dynamics) model is established with triangular mesh and optimized using an energy function. The installation instructions and dependencies are provided in the Installation section below. The first step requires setting up the triangular mesh model to approximate the membrane's geometry applying Loop's subdivision method. The lowest energy search model minimizes the membrane energy evaluated by the energy function. The Brownian Dynamics model simulates the moving membrane's surface with a displacement equation, performed on the limit surface with the help of a conversion matrix. Three types of boundary conditions are available: Fixed, Periodic, and Free, all defined for "ghost vertices" on the boundary of the triangular mesh.
Installation
To install the model, follow these steps:
- Clone this repository to your local machine. You can use
gitas follows or download zip from github webpage.
- Install dependencies (GSL and OpenMP)
This project depends on:
- CMake 3.16 or newer
- GSL (GNU Scientific Library)
- OpenMP – required for the parallel build; its headers are needed even for a serial build, because several headers include
<omp.h>unconditionally - GoogleTest (optional, for the unit tests)
Ubuntu (apt)
macOS (Homebrew)
Using Homebrew LLVM for OpenMP (recommended):
Compile with CMake
SLIMED builds with CMake. Executables are present in the respective bin directory.
| Program | Old target | What it does |
|---|---|---|
continuum_membrane | make serial / make omp | Lowest-energy conformation search |
continuum_membrane_multithreading | make multi | Same, embarrassingly parallel over parameter sets |
membrane_dynamics | make dyna / make dyna_omp | Membrane Brownian dynamics |
membrane_dynamics_multithreading | make dyna_multi | Same, embarrassingly parallel |
Configure and build separately
Configure once into a build directory, then build:
cmake locates GSL, sets the C++14 standard, resolves OpenMP, and prints a summary of what it found. The executables are written to build/bin/.
To rebuild after editing code, only the second command is needed:
The configure step re-runs itself when CMakeLists.txt changes, and sources are globbed with CONFIGURE_DEPENDS, so adding or removing a .cpp under src/ is picked up automatically.
Build options
Options are cached in the build directory, so they are set once rather than on every invocation.
| Option | Default | Effect |
|---|---|---|
-DSLIMED_ENABLE_OPENMP | OFF | Compile the OpenMP code paths (-fopenmp and -DOMP together). |
-DSLIMED_ENABLE_COVERAGE | OFF | Instrument for gcov/lcov. |
-DSLIMED_BUILD_TESTS | ON | Build the GoogleTest suite. |
Standard CMake variables work as usual:
CMAKE_BUILD_TYPE defaults to Release (-O3), matching the hand-written Makefile. To inspect what a build directory is currently set to:
Presets (quick way to build and switch between serial and OpenMP)
Because serial and OpenMP builds are both used routinely, CMakePresets.json defines them as named presets, each with its own build directory:
| Preset | Build directory | Builds | Equivalent to |
|---|---|---|---|
serial | build/ | simulation programs | make serial / make dyna |
omp | build-omp/ | simulation programs | make omp / make dyna_omp |
coverage | build-cov/ | programs + unit tests | make test COVERAGE=1 |
serial and omp build the four simulation programs only. They set SLIMED_BUILD_TESTS=OFF, so GoogleTest is never looked for and does not need to be installed to use them.
Configure and build in one command:
Or drive the steps separately:
To run the unit tests, either use the coverage preset or configure a build directory by hand – SLIMED_BUILD_TESTS defaults to ON, so a plain configure includes them:
Because each preset owns a separate build directory, switching back and forth recompiles nothing – both trees persist side by side. Setting -DSLIMED_ENABLE_OPENMP on a single build directory works too, but changes the -DOMP define for every target and so triggers a full rebuild each time you flip it.
To list what is available:
Presets require CMake 3.25 or newer. With an older CMake, use the -D options below instead – they are exactly what the presets set. For personal presets that are not shared, create a CMakeUserPresets.json; it is gitignored.
The four programs
One build produces all four; each replaces one goal of the hand-written Makefile.
| Program | Old target | What it does |
|---|---|---|
continuum_membrane | make serial / make omp | Lowest-energy conformation search |
continuum_membrane_multithreading | make multi | Same, embarrassingly parallel over parameter sets |
membrane_dynamics | make dyna / make dyna_omp | Membrane Brownian dynamics |
membrane_dynamics_multithreading | make dyna_multi | Same, embarrassingly parallel |
Serial and OpenMP are no longer separate targets. OpenMP is a configure-time choice, so the same program name covers both:
These two are what the serial and omp presets above do, so cmake --workflow --preset omp is the shorter equivalent.
Flipping SLIMED_ENABLE_OPENMP on an existing build directory also works, but it recompiles everything – keeping two build directories avoids that.
To build a single program instead of all four:
Running the programs
The programs read input.params from the current working directory, so run them from the top of the source tree rather than from the build directory:
Running them from inside build/bin prints There was a problem opening the parameter file! and silently falls back to built-in defaults.
OpenMP notes
-fopenmp and -DOMP are always enabled together and never separately. Most #pragma omp parallel for directives in src/ are unguarded, but the loop bodies that need a thread id read it from omp_get_thread_num() only under #ifdef OMP and otherwise hard-code 0, so enabling the flag without the define would race on the per-thread accumulation buffers.
Serial builds still need omp.h on the include path, because Mesh.hpp, Dynamics.hpp, Force.hpp and Gauss_quadrature.hpp include it unconditionally. CMake attaches the OpenMP include directories without the -fopenmp flag to cover this.
On macOS, Apple Clang has no bundled OpenMP runtime and Homebrew keeps libomp keg-only. CMake retries a failed probe against brew --prefix libomp automatically, so brew install libomp is normally all that is required. Homebrew GCC also works for the simulation programs:
Note that the compiler cannot be changed in an existing build directory – delete it and configure again. Under Homebrew GCC the unit tests will not link, because Homebrew's libgtest.a is built against libc++ while GCC uses libstdc++; use the default Apple Clang when you need the tests.
Tests
SLIMED_BUILD_TESTS defaults to ON, so any build directory configured by hand includes the unit tests:
Note that the serial and omp presets deliberately set it to OFF, so build/ and build-omp/ contain no tests; use a separate directory as above, or the coverage preset.
Each GoogleTest case is registered with CTest individually. Several tests open fixture files by paths relative to the working directory, so CTest runs test_main from the top of the source tree automatically. The binary can also be run directly, from the source root:
If GoogleTest is not installed, CMake prints a warning and skips the test target; the simulation programs build either way. Configure with -DSLIMED_BUILD_TESTS=OFF to silence the warning.
For coverage:
or simply cmake --workflow --preset coverage.
.gcda/.gcno files are left in the build tree for lcov or gcov to collect. There is no packaged coverage-html target yet.
Cleaning
The previous Makefile
The hand-written Makefile is still in the tree as Makefile.legacy and still works; CMake neither uses nor interferes with it:
Its mpi target is not carried over to the CMake build: it only added -DMPI, which no source file tests, and its MPCC variable was never used by any rule.
There are no install or packaging targets in the CMake build yet – the programs are run from the build tree, as they were with the Makefile.
Input Parameters
The input file is continuum_membrane/input.params. Parameters are broken down into geometric parameters, physical properties, insertion mode, and advanced parameters.
| Category | Subcategory / Parameter | Name / Key | Description |
|---|---|---|---|
| Geometric Parameters | — | lMeshSide | Target side length of the triangular mesh (nm). This only serves as a reference scale. The mesh side length set up by the algorithm may vary. |
| Sphere model | isSphere | Set true to enable sphere mode. | |
rSphere | Target radius of sphere (nm). This is the radius of spherical frame to set up the triangular mesh. The radius of the resulting membrane represented by the triangular mesh may vary. | ||
| Physical Properties | — | c0Insertion | Curvature of the membrane at the insertion area. |
| — | c0Membrane | Spontaneous curvature of the membrane. | |
| — | kcMembraneBending | Membrane bending constant in the energy function (pN·nm). | |
| — | usMembraneStretching | Membrane stretching modulus in the energy function (pN/nm). | |
| — | uvVolumeConstraint | Volume constraint coefficient in the energy function (pN/nm²). | |
| Insertion Mode | — | isInsertionIncluded | Set true to include insertion. |
| — | sigma | 2·sigma (nm) is the length scale of decaying insertion curvature, or in other words expansion of non-spontaneous curvature due to insertion. | |
| Advanced Parameters | Optimization | numMaxIterations | Number of maximum iterations allowed. |
criterionForce | Force criteria to determine if adequate optimization is accomplished (pN). | ||
| Algorithm | gaussQuadratureN | Default Gauss Quadrature used in integral approximation. |
Energy Function and Lowest Energy Search
The goal for the lowest energy search model is to minimize the membrane energy evaluated by the energy function, which is the sum of membrane bending energy, area constraint energy (or elastic area change energy), and volume constraint energy:
$$ E = E_B + E_S + E_V = \int_S \frac{1}{2}\kappa (2H-C_0)^2 dS + \frac{1}{2} \mu_S \frac{(S-S_0)^2}{S_0} + \frac{1}{2} \mu_V \frac{(V-V_0)^2}{V_0} $$
where:
- $\kappa$ : membrane bending constant
kcMembraneBending - $H$ : mean membrane culvature
- $C_0$ : spontaneous curvature of the membrane
c0Membrane - $\mu_S$ : membrane streching modulus
usMembraneStretching - $S$ : global membrane area
- $S_0$ : target membrane area
- $\mu_V$ : volume constraint coefficient
uvVolumeConstraint - $V$ : global volume
- $V_0$ : target volume
Membrane Brownian Dynamics
Membrane Brownian Dynamics model runs a step-wise simulation of the moving membrane surface with the following equation:
$$ \Delta X = -\frac{D\Delta t}{k_b T} \nabla E + \sqrt{2D\Delta t} (N(0,1)) $$
where:
- $\Delta X$: displacement of point on limit surface
- $D$: diffusion constant of the membrane
- $\Delta t$: time step
- $N(0,1)$: standard normal distribution
Note that the displacement of membrane according to the equation above is performed on the limit surface, not the control mesh. In this case, a conversion matrix helps to convert between triangular mesh and limit surface, as currently the points on the limit surface represented by the mesh point are chosen to represent the surface.
$$ M_{s} = C M_{m} $$
$$ M_{m} = C^{-1} M_{s} $$
Boundary Conditions
Three types of boundary conditions are provided currently in both models. Note that "ghost vertices" are defined as points on the boundary of the triangular mesh that only serve to provide reference when calculating limit surface on the boundary, as calculating position of a point on the limit surface require the coordinates of 12 neighboring vertices (if regular). However, the "ghost vertices" themselves do not correspond to real points on the surface.
- Fixed: 2 rings of ghost vertices are fixed in space
- Periodic: 3 rings of ghost vertices that mimics the movement of the vertices on the opposite side of the membrane.
- Free: 2 rings of ghost vertices are generated after movement by forming parallelogram extend from the real points on the control mesh
For Developers
A detailed doxygen style documentation is available in SLIMED developer's documentation.
Cite Continuum Membrane
If you use or modify continuum membrane model, in addition to citing NERDSS, please be kind and cite us:
- For continuum Membrane Implementation: Fu, Y., Yogurtcu, O.N., Kothari, R., Thorkelsdottir, G., Sodt, A.J. & Johnson, M.E. (2019) An implicit lipid model for efficient reaction-diffusion simulations of protein binding to surfaces of arbitrary topology. J Chem Phys. 151 (12), 124115. doi:10.1063/5.0045867
- For membrane energies and insertion: Fu, Y., Zeno, W., Stachowiak, J. & Johnson, M.E. A continuum membrane model predicts curvature sensing by helix insertion. Soft Matter. 2021 Dec 8;17(47):10649–10663 doi:10.1039/d1sm01333e
License
This project is licensed under the GPL License - see the LICENSE file for details.
Reference
- Helfrich, W. (1973). Elastic properties of lipid bilayers: theory and possible experiments. Zeitschrift fur Naturforschung C, 28(11), 693-703.
