sesmesh
Fast, accurate Solvent Excluded Surface (SES, also called the Connolly or molecular surface) meshing for molecular structures, written in Rust.
- Reads PDB, PDBx/mmCIF, XYZ / extended XYZ and PQR files (optionally gzip-compressed), including biological assemblies.
- Computes the SES exactly via its implicit distance representation, sampled on a sparse, narrow-band brick grid; SAS and van der Waals surfaces too.
- Writes closed, consistently oriented, edge-manifold triangle meshes with
vertices on the exact surface and analytic normals: Wavefront OBJ, binary
PLY, MSMS
.vert/.face(each optionally gzip-compressed); per-vertex colours, components, cavities, per-atom areas, JSON statistics. - Controls resolution and level of detail: grid spacing, quality presets, vertex density, smoothing with exact re-projection, decimation that keeps vertices on the exact surface, and a memory limit that can coarsen the grid automatically.
- Multi-threaded (rayon) and SIMD-accelerated with runtime CPU dispatch (AVX-512 / AVX2 / SSE4.2 / NEON); output identical for any thread count.
- Optional GPU back ends for AMD GPUs (HIP / ROCm, feature
hip) and NVIDIA GPUs (CUDA, featurecuda): the same files as the CPU, or a faster preview mode. - Ships as a reusable library crate (
sesmesh) plus a command-line tool (sesmesh-cli).
Status: 1.0. Stable API under semantic versioning (docs/api-review.md). A comparison with MSMS, NanoShaper, ESES, EDTSurf, ChimeraX and sesa on the same spheres is in docs/comparison.md. Work after 1.0 (reference-machine timings, x86 kernel work, marching tetrahedra) is tracked in issue #19.
Install
Command-line tool (binary sesmesh):
Prebuilt binaries for macOS arm64 and Linux x86-64 are attached to the GitHub releases (up to 1.1.2 also Linux arm64 and Windows x86-64).
Library:
[]
= "1"
Rust 1.89 or newer.
Quick start
Run sesmesh surface --help for all options (selection, radii, surface kind,
cavities, resolution, normals, colours, side files, threads). Output formats
are described in docs/04-output-formats.md. Exit codes: 0 success, 1 runtime
error, 2 usage error, 3 input parse error, 4 resource limit, 130 interrupted
(Ctrl-C). sesmesh completions <shell> prints a completion script and
sesmesh man the manual page.
As a library:
use ;
use ;
GPU back ends (AMD HIP, NVIDIA CUDA)
Built with the feature hip or cuda, sesmesh runs the mesh stage on an
AMD GPU through ROCm or on an NVIDIA GPU through CUDA: the device classifies
the grid, gathers candidates and samples the field while the CPU threads
mesh, so the two overlap. Both use the same kernels. Building needs ROCm's
hipcc or CUDA's nvcc; the binary loads the GPU driver when it starts
and still runs (on the CPU) where it is missing.
- Exact (default): the files are the CPU back end's, byte for byte.
--refine fast: the GPU also refines the vertices, in f32. Same triangles, vertices as close to the surface, area and volume within 4·10⁻⁷ (relative) of exact mode; positions differ in the last bits.- The GPU runs f32 and integer code only.
- On a Ryzen AI Max+ 395 (16 Zen 5 cores, Radeon 8060S), 1AON at 0.25 Å takes 3.40 s on the CPU, 2.37 s exact on the GPU and 1.41 s fast; 3J3Q at 1 Å (2.4 M atoms) takes 28.9 s, 23.6 s and 12.3 s (the 10-core M4's CPU: 5.6 s and 47.6 s).
- HIP: built and tested on that integrated RDNA 3.5 GPU (gfx1151). Code objects are built for ROCm's generic RDNA 2, 3 and 4 targets; data-centre GPUs (MI250X, MI300) are not supported yet.
- CUDA: a fat binary for compute capability 7.5 (Turing) to 12.0, tested on a laptop GeForce RTX 2070 Max-Q (sm_75) with a 6-core i7-9750H. There 1AON at 0.5 Å takes 5.48 s on the CPU, 3.04 s exact and 1.70 s fast; the laptop's CPU bounds both modes.
- A Metal back end is planned.
The library takes the same choice in SurfaceParams::with_backend
(Backend::{Cpu, Auto, Hip, Cuda}) and with_refine(RefineMode::Fast).
Details: docs/05-gpu-hip.md,
docs/06-gpu-cuda.md.
Documentation
- Website: https://uvar-apps.github.io/sesmesh/ — CLI and library
guides, tutorials, gallery, live 3D viewer (source in
site/) - Product specification: requirements, literature survey, references
- Design: mathematics, architecture, algorithms
- Implementation plan: phases, tasks, milestones
- Output formats: OBJ, CSV side files, JSON statistics
- Validation report: accuracy, robustness, large inputs, performance
- CLI manual: every option, examples, exit codes
- GPU back end: design, measurements, plan (prior art and revised plan)
- Ambient occlusion: shaded surfaces by post-processing with aomesh
- Library: crate documentation (
cargo doc --open -p sesmesh) and examples - API review (semver policy) and release process
Workspace layout
| Path | Contents |
|---|---|
crates/sesmesh |
Library crate |
crates/sesmesh-cli |
sesmesh command-line tool |
crates/sesmesh-gpu |
GPU back ends (HIP FFI and kernels; an implementation detail of sesmesh) |
crates/sesmesh-testkit |
Test oracles and analytic references (development only) |
xtask |
Development automation (cargo xtask ...) |
tests/data |
Test fixtures, download sets and checksums (README) |
docs |
Specification, design and plan |
site |
Project website (GitHub Pages; tools/site/README.md) |
tools/ao |
Ambient occlusion with aomesh: ses_ao.py, tests (README) |
Building
Requires Rust 1.89 or newer.
To download the optional test and benchmark structures from the RCSB PDB:
Citing sesmesh
If you use sesmesh in published work, please cite it, giving the version you used. Each release is archived on Zenodo with its own DOI:
Varetto, U. (2026). sesmesh: Solvent Excluded Surface meshes for molecules (Version 1.1.2) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.24238837
doi:10.5281/zenodo.24238836 stands for all versions and resolves to the latest. The same metadata is in CITATION.cff (GitHub: Cite this repository). Where your work depends on a method sesmesh implements, please cite that method too (How it works).
How it works
sesmesh evaluates the exact implicit SES distance function of Quan & Stamm [1] on a sparse narrow-band grid, using the SAS arrangement (atom spheres, intersection circles and probe positions) of Connolly's analytic surface [2, 3]; it extracts the zero level set with Marching Cubes [4] (uniform face rule, Flying Edges-style row skipping [5]), places every vertex on the exact surface and takes normals from the closest point. Optional smoothing uses Taubin's λ|μ filter [6] followed by exact re-projection. The SES itself goes back to Lee & Richards [7] and Richards [8].
The methods, to cite alongside sesmesh where your work relies on them:
- C. Quan, B. Stamm, "Mathematical analysis and calculation of molecular surfaces," J. Comput. Phys. 322:760–782, 2016. doi:10.1016/j.jcp.2016.07.007
- M. L. Connolly, "Analytical molecular surface calculation," J. Appl. Cryst. 16(5):548–558, 1983. doi:10.1107/S0021889883010985
- M. L. Connolly, "Solvent-accessible surfaces of proteins and nucleic acids," Science 221:709–713, 1983.
- W. E. Lorensen, H. E. Cline, "Marching cubes: a high resolution 3D surface construction algorithm," Comput. Graph. 21(4):163–169, 1987. doi:10.1145/37402.37422
- W. Schroeder, R. Maynard, B. Geveci, "Flying edges: a high-performance scalable isocontouring algorithm," IEEE LDAV 2015. doi:10.1109/LDAV.2015.7348069
- G. Taubin, "A signal processing approach to fair surface design," SIGGRAPH '95, 351–358, 1995.
- B. Lee, F. M. Richards, "The interpretation of protein structures: estimation of static accessibility," J. Mol. Biol. 55(3):379–400, 1971. doi:10.1016/0022-2836(71)90324-X
- F. M. Richards, "Areas, volumes, packing, and protein structure," Annu. Rev. Biophys. Bioeng. 6:151–176, 1977.
Radius sets: Bondi (1964) with Mantina et al. (2009), Alvarez (2013), and ProtOr (Tsai et al. 1999, classification from FreeSASA). The full reference list is in the specification.
Licence
Copyright (c) 2026 Ugo Varetto.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT licence (LICENSE-MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work, as defined in the Apache-2.0 licence, shall be dual licensed as above, without any additional terms or conditions.