membrane-curvature 2.0.0rc1

MDAnalysis tool to calculate membrane curvature from MD simulations.

Membrane Curvature

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

Features

With MembraneCurvature you can:

• Calculate mean and Gaussian curvature from MD simulations.
• Derive 2D curvature profiles from atoms of reference with two different methods: binning or Fourier-based.
• Get per-frame or averaged results for surface, mean and Gaussian curvature.
• Live a happier life.

Installation

The main dependency in MembraneCurvature is MDAnalysis. You can find instructions to install the latest stable version of MDAnalysis in the UserGuide.

MembraneCurvature is available via pip:

pip install membrane-curvature

To install from source:

git clone https://github.com/MDAnalysis/membrane-curvature.git
cd 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

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 mean curvature
mean_upper_leaflet = curvature_upper_leaflet.results.z_surface

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

# extract average Gaussian curvature
gaussian_upper_leaflet = curvature_upper_leaflet.results.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. If you want per-frame arrays instead, use results.z_surface, results.mean, and results.gaussian.

The same example run with the binning surface 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)

# run with the binning surface_method
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()

# extract average mean curvature
mean_upper_leaflet_binning = curvature_upper_leaflet_binning.results.z_surface

# extract average mean curvature
mean_upper_leaflet_binning = curvature_upper_leaflet_binning.results.mean

# extract average Gaussian curvature
gaussian_upper_leaflet_binning = curvature_upper_leaflet_binning.results.gaussian

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!

MembraneCurvature is compatible with uv (recommended for development):

# create an environment and install the project + dev tools
uv sync --extra dev

# add test dependencies and run the test suite
uv sync --extra dev --extra tests
uv run pytest

This repository 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 set up hooks locally, with with uv:

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

Or with pip:

pip install -e ".[dev]"
pre-commit install

Interested in becoming a maintainer? We welcome your passion and expertise to help shape and grow this open-source project! Please contact [e-mail] 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.