MembraneCurvature

MembraneCurvature is an MDAnalysis MDAKit to calculate membrane curvature from Molecular Dynamics simulations.

Features

With MembraneCurvature you can:

• Derive 2D surface profiles from MD simulations using an atom selection as reference with two different methods: binning or Fourier.
  • Optional periodic edge padding to reduce finite difference artifacts (binning method only).
  • Optional brick-wall FFT filter on averaged surface maps (binning method only).
• Calculate the mean and Gaussian curvatures of the derived surfaces.
• Get per-frame or averaged results for surface, mean and Gaussian curvature.
• Live a happier life.

Installation

MembraneCurvature is available via pip and conda. Please refer to the Installation section in the Getting Started Documentation page for detailed installation instructions.

With pip

MembraneCurvature is available via pip:

pip install membrane-curvature

Or to install from source:

git clone https://github.com/MDAnalysis/membrane-curvature.git
cd membrane-curvature
python -m pip install -e .

With conda

MembraneCurvature is available via conda:

conda install -c conda-forge membrane-curvature

Or to install from source:

git clone https://github.com/MDAnalysis/membrane-curvature.git
cd membrane-curvature
conda env create -f devtools/conda-envs/environment.yaml
conda activate membrane-curvature
python -m pip install -e .

Some of the examples included in the MembraneCurvature documentation use test data from MDAnalysisTests and MDAnalysisData. To install these dependencies with conda, run:

conda install -c conda-forge MDAnalysisTests MDAnalysisData

or via pip:

pip install --upgrade MDAnalysisTests MDAnalysisData

Usage

With the Fourier method

This is a quick example on how to run MembraneCurvature with the default surface method (Fourier):

import MDAnalysis as mda
from membrane_curvature import MembraneCurvature
from MDAnalysis.tests.datafiles import Martini_membrane_gro

universe = mda.Universe(Martini_membrane_gro)

# run with the default surface_method - Fourier
curvature_upper_leaflet = MembraneCurvature(universe,
                                            select='resid 1-225 and name PO4'
                                            ).run()

# extract average surface
average_surface = curvature_upper_leaflet.results.average_z_surface

# extract average mean curvature
mean_upper_leaflet = curvature_upper_leaflet.results.average_mean

# extract average Gaussian curvature
gaussian_upper_leaflet = curvature_upper_leaflet.results.average_gaussian

In this example, we use the PO4 beads in the upper leaflet as reference to derive a surface and calculate its respective mean and Gaussian curvature.

To access the per-frame arrays for the example above, use results.z_surface[<frame_id>], results.mean[<frame_id>], and results.gaussian[<frame_id>]:

# to access the surface for the first frame
surface_first_frame = curvature_upper_leaflet.results.z_surface[0]

# access the mean curvature for the last frame
mean_last_frame = curvature_upper_leaflet.results.mean[-1]

# access the Gaussian curvature for the frame 10
gaussian_frame_10 = curvature_upper_leaflet.results.gaussian[10]

With the binning method

The same example run with the binning method looks like:

import MDAnalysis as mda
from membrane_curvature import MembraneCurvature
from MDAnalysis.tests.datafiles import Martini_membrane_gro

universe = mda.Universe(Martini_membrane_gro)

curvature_upper_leaflet_binning = MembraneCurvature(universe,
                                                   select='resid 1-225 and name PO4',
                                                   surface_method='binning',
                                                   n_x_bins=8,
                                                   n_y_bins=8,
                                                   wrap=True
                                                   ).run()

surface_upper_leaflet_binning = curvature_upper_leaflet_binning.results.average_z_surface

mean_upper_leaflet_binning = curvature_upper_leaflet_binning.results.average_mean

gaussian_upper_leaflet_binning = curvature_upper_leaflet_binning.results.average_gaussian

Binning with padding

[!WARNING] Padding is only available with surface_method='binning' and requires orthorhombic boxes.

To reduce finite difference edge artifacts, you can enable padding with the padding argument:

import MDAnalysis as mda
from membrane_curvature import MembraneCurvature
from MDAnalysis.tests.datafiles import Martini_membrane_gro

universe = mda.Universe(Martini_membrane_gro)

# run with padding to reduce finite difference artifacts
curvature_upper_leaflet_padded = MembraneCurvature(universe,
                                                   select='resid 1-225 and name PO4',
                                                   surface_method='binning',
                                                   n_x_bins=8,
                                                   n_y_bins=8,
                                                   padding=True).run()

surface_upper_leaflet_padded = curvature_upper_leaflet_padded.results.average_z_surface

mean_upper_leaflet_padded = curvature_upper_leaflet_padded.results.average_mean

gaussian_upper_leaflet_padded = curvature_upper_leaflet_padded.results.average_gaussian

Binning with FFT filtering

FFT filtering is disabled by default with fft_filter=None. To enable automatic filtering, pass fft_filter='auto':

import MDAnalysis as mda
from membrane_curvature import MembraneCurvature
from MDAnalysis.tests.datafiles import Martini_membrane_gro

universe = mda.Universe(Martini_membrane_gro)

# run with the binning surface_method with automatic FFT filtering
curvature_upper_leaflet_filtered = MembraneCurvature(universe,
                                                     surface_method='binning',
                                                     select='resid 1-225 and name PO4',
                                                     n_x_bins=8,
                                                     n_y_bins=8,
                                                     fft_filter='auto',
                                                     ).run()

surface_upper_leaflet_filtered = curvature_upper_leaflet_filtered.results.average_z_surface

mean_upper_leaflet_filtered = curvature_upper_leaflet_filtered.results.average_mean

gaussian_upper_leaflet_filtered = curvature_upper_leaflet_filtered.results.average_gaussian

[!NOTE]

FFT filtering is only available with surface_method='binning'. Per-frame results.z_surface, results.mean, and results.gaussian are not FFT-filtered. With filtering enabled, results.average_z_surface contains the filtered average height. results.average_mean and results.average_gaussian are calculated from that filtered height.

You can find more examples on how to run MembraneCurvature in the Usage page. To plot results from MembraneCurvature please check the Visualization page.

Documentation

To help you get the most out of MembraneCurvature, we have documentation available where you can find:

• The standard API documentation.
• Quick examples of how to run MembraneCurvature in the Usage page.
• Detailed explanation of the Algorithm implemented in MembraneCurvature.
• Examples on how to plot the results obtained from MembraneCurvature in the Visualization page.
• Detailed Tutorials to run MembraneCurvature in membrane-only and membrane-protein systems.

Contributing

Contributions are very welcome!

If you are interested in contributing to MembraneCurvature, installation of the development dependencies is required.

There are three dependency groups defined in pyproject.toml:

• dev: development tools (includes tests and docs).
• tests: testing dependencies.
• docs: documentation build dependencies (e.g. Sphinx, themes).

Note that by installing the dev group, the tests and docs dependency groups are also installed.

We recommend using uv as a development environment for MembraneCurvature. To set up a uv dev environment, clone the repository and move to the root directory:

git clone https://github.com/MDAnalysis/membrane-curvature.git
cd membrane-curvature

To create a new uv environment and install the dependencies included in the dev group, run:

uv sync --group dev
uv run pre-commit install

By syncing the dev group with uv, all the development dependencies are installed. MembraneCurvature uses pre-commit hooks to run quick checks before commits such as whitespace cleanup, TOML/YAML validation, and Ruff linting/formatting. Using these hooks is highly encouraged because it helps catch common issues early and keeps pull requests easier to review.

To run the hooks manually without committing:

uv run pre-commit run --all-files

For instructions on how to create a development environment with pip, see the Installing development dependencies with pip page.

For more information on how to contribute to MembraneCurvature, see the Contributing page.

Interested in becoming a maintainer? We welcome your passion and expertise to help shape and grow this open-source project! Please contact estefania@ojeda-e.com for more details.

License

Source code included in this project is available in the GitHub repository https://github.com/MDAnalysis/membrane-curvature under the GNU General Public License v3 (see LICENSE).

MembraneCurvature was developed as a Google Summer of Code 2021 project with MDAnalysis and it is linked to a Code of Conduct.