MemSurfer, Version 1.1

Released: April 19, 2022

Author: Harsh Bhatia (hbhatia@llnl.gov) and Peer-Timo Bremer

MemSurfer is an efficient and versatile tool to compute and analyze membrane surfaces found in a wide variety of large-scale molecular simulations. MemSurfer works independent of the type of simulation, directly on the 3D point coordinates, and can handle a variety of membranes as well as atomic simulations. MemSurfer provides many in-built analysis tasks, such as computing the membrane curvature, density and normals of lipids, and area per lipid. More importantly, MemSurfer provides a simple-to-use Python API that may be easily used/extended to perform other types of analysis.

Dependencies

The interface to MemSurfer is provided via python 3, whereas the core functionality is written in C++ 11 with the following dependencies.

1. The Computational Geometry Algorithms Library (CGAL): v 4.13.0
2. boost: v 1.66
3. Eigen: v 3.3.9

Installing MemSurfer and its dependencies additionally require the following software.

• C++ compiler that supports C++ 11 and OpenMP (tested with GNU gcc 7.3.0 and GNU gcc 7.5.0)
  • Please use gcc@7. See known issues below.
• Python 3 interpreter (tested with 3.9.12, 3.7.11, and 3.7.2)
• Cython (tested with 0.29.10 and 0.29.24)
• Swig (tested with 3.0.12 and 4.0.2)
• CMake (tested with 3.13 and 3.20)
• gmp (tested with 6.2.1)
• mpfr (tested with 4.1.0)

All the additional packages (unnumbered) are usually available on all machines through standard package managers, for example, macports, apt-get, yum, etc. Please make use of these package managers to avail these dependencies.

The numbered dependencies may not be available, or package managers may not give full control on the version number to be installed. Here, we will discuss the installation of these major dependencies.

Installation via Spack

Currently outdated and broken. To be fixed soon.

Installation from source

MemSurfer can be downloaded using the following link.

$ git clone --recursive git@github.com:LLNL/MemSurfer.git
$ MEM_HOME=`pwd`/MemSurfer

1. Installing MemSurfer's Dependencies

The following describes the installation of cgal,, boost and eigen, whereas the rest of the dependencies are assumed to be standard and available.

1a. Eigen, Boost, and CGAL (on mac)

On macosx, the simplest way to install these is using macports. As of Jan 2019, macports installs the correct versions.

$ port install cgal           # also installs boost and eigen

1b. Eigen, Boost, and CGAL (from source)

A helper script $MEM_HOME/install_deps.sh is provided to install these dependencies. In order to use this script, you need to specify a C++ compiler that supports OpenMP.

$ export CC_COMPILER=`which gcc`
$ export CXX_COMPILER=`which g++`
$ sh install_deps.sh

This script installs all these dependencies in a folder called $MEM_HOME/external. Note that you may not need to install all four of these dependencies. Please edit the script (lines 6--8) to select which ones to install.

Once installed successfully, please add the following to your shell profile to access these dependencies.

$ export PYTHONPATH=$MEM_HOME/external/lib/python3.x/site-packages:$PYTHONPATH

# LD_LIBRARY_PATH for linux
$ export LD_LIBRARY_PATH=$MEM_HOME/external/lib:$MEM_HOME/external/lib64:$LD_LIBRARY_PATH

# DYLD_LIBRARY_PATH for mac
$ export DYLD_LIBRARY_PATH=$MEM_HOME/external/lib:$MEM_HOME/external/lib64:$DYLD_LIBRARY_PATH

2. MemSurfer

Once the dependencies have been installed, MemSurfer can be installed using distutils. However, you need to explicitly supply the path of the external dependencies.

$ export BOOST_ROOT=<path_to_boost>   # boost headers are contained in $BOOST_ROOT/include/boost
$ export CGAL_ROOT=<path_to_cgal>     # cgal headers are contained in $CGAL_ROOT/include/CGAL
$ export EIGEN_ROOT=<path_to_eigen>   # eigen headers are contained in $EIGEN_ROOT/include/eigen3

Note that, all these paths default to $MEM_HOME/external. So if you installed the dependencies using the script provided above, you do not need to specify these paths.

$ cd $MEM_HOME
$ CC=`which gcc` CXX=`which g++` LDCXXSHARED="`which g++` -bundle -undefined dynamic_lookup" \
  python setup.py install

Trobubleshooting and Known Issues

Jul 20, 2021: It appears that compilation using gcc@8 results in a segfault or a malloc error (see issue #10). The problem appears to be residing in a dependency called pypoisson. Until it is resolved, please use gcc@7.

Jan 23, 2019: If the cloning fails with the following error:

Cloning into '<your-path>/MemSurfer/pypoisson'...
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

This error means that your ssh keys are not registered with github. Please see here and here to register your ssh key and retry.

Examples

• See the example directory.

Change Log

Apr 19, 2022

• Bumped the version.
• Bug fix in Delaunay.
• Added perturbations in projected points for correct Delaunay.
• Added shell analysis.
• Added conversion of mesh properties to pandas (to support writing to csv).

Dec 06, 2021

• Removed VTK as a C++ dependency by using it directly in python. Sufficient now to install using pip install vtk.
• Updated examples to MDAnalysis 2.

Jul 22, 2021

• Upgraded to Eigen 3.3.9
• Updated pypoisson submodule to commit #94534a2.
• Added a specific guideline to use gcc@7.

Mar 23, 2020

• Correctly normalize Gaussian KDE and support 3D Gaussian kernel.
• Ported to Python3.

License

MemSurfer is released under GNU GPL-3.0 license. See the LICENSE file for details.

LLNL-CODE-763493