sesmesh-cli 1.3.0

Command-line tool computing Solvent Excluded Surfaces (Connolly surfaces) of molecules as triangle meshes (OBJ, PLY, MSMS)
sesmesh-cli-1.3.0 is not a library.

sesmesh

crates.io docs.rs CI DOI

Fast, accurate Solvent Excluded Surface (SES, also called the Connolly or molecular surface) meshing for molecular structures, written in Rust.

website

  • 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, feature cuda): 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):

cargo install sesmesh-cli

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:

[dependencies]
sesmesh = "1"

Rust 1.89 or newer.

Quick start

sesmesh 1crn.cif -o 1crn.obj                  # SES, 0.5 Å grid
sesmesh 4hhb.cif.gz -q high --timings         # 0.25 Å grid
sesmesh ligand.xyz --radii alvarez --probe 1.2 -s 0.1 -o lig.obj
sesmesh 1crn.cif --cavities remove --vertex-colors element --stats stats.json
sesmesh 1k4r.cif.gz --assembly 1 -q draft -o capsid.ply   # 545k-atom capsid
sesmesh 1aon.cif.gz -q high --decimate 0.25 -o groel.ply.gz # fine grid, 4× fewer triangles
sesmesh *.cif.gz --output-dir meshes --keep-going          # batch
sesmesh info 1crn.pdb
sesmesh radii --set protor

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 sesmesh::export::obj::{write_obj_path, ObjOptions};
use sesmesh::{compute_surface, io, radii, Diagnostics, Selection, Sphere, SurfaceParams};

fn main() -> sesmesh::Result<()> {
    let structure = io::read_path("1crn.cif", &io::ReadOptions::default())?;
    let mut diags = Diagnostics::new();
    let atoms = structure.select(&Selection::default(), &mut diags)?;
    let radii = radii::assign(&atoms, &radii::RadiusOptions::default(), &mut diags)?;
    let spheres = Sphere::from_atoms(&atoms, &radii)?;
    let out = compute_surface(&spheres, &SurfaceParams::ses(1.4).with_spacing(0.25))?;
    println!("{} triangles, area {:.1} Ų", out.stats.triangles, out.stats.area);
    write_obj_path("1crn.obj", &out.mesh, &ObjOptions::default())
}

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.

cargo install sesmesh-cli --features hip                 # or --features cuda
sesmesh 1aon.cif.gz -q high --backend hip                # same files as the CPU (or --backend cuda)
sesmesh 1aon.cif.gz -q high --backend hip --refine fast  # preview: f32 refinement on the GPU
sesmesh 1aon.cif.gz -q high --backend auto --timings     # GPU if one works, else CPU
  • 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

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.

cargo build --release
cargo test --workspace

To download the optional test and benchmark structures from the RCSB PDB:

cargo xtask fetch --set small

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

@software{varetto_sesmesh,
  author    = {Varetto, Ugo},
  title     = {{sesmesh: Solvent Excluded Surface meshes for molecules}},
  version   = {1.1.2},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.24238837},
  url       = {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:

  1. 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
  2. M. L. Connolly, "Analytical molecular surface calculation," J. Appl. Cryst. 16(5):548–558, 1983. doi:10.1107/S0021889883010985
  3. M. L. Connolly, "Solvent-accessible surfaces of proteins and nucleic acids," Science 221:709–713, 1983.
  4. 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
  5. W. Schroeder, R. Maynard, B. Geveci, "Flying edges: a high-performance scalable isocontouring algorithm," IEEE LDAV 2015. doi:10.1109/LDAV.2015.7348069
  6. G. Taubin, "A signal processing approach to fair surface design," SIGGRAPH '95, 351–358, 1995.
  7. 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
  8. 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

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.