sesmesh-cli 1.3.2

Command-line tool computing Solvent Excluded Surfaces (Connolly surfaces) of molecules as triangle meshes (OBJ, PLY, MSMS)
# sesmesh

[![crates.io](https://img.shields.io/crates/v/sesmesh.svg)](https://crates.io/crates/sesmesh)
[![docs.rs](https://docs.rs/sesmesh/badge.svg)](https://docs.rs/sesmesh)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24238836.svg)](https://doi.org/10.5281/zenodo.24238836)

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

[website](https://uvar-apps.github.io/sesmesh/)

* 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`]https://crates.io/crates/sesmesh)
  plus a command-line tool ([`sesmesh-cli`]https://crates.io/crates/sesmesh-cli).

> **Status: 1.0.** Stable API under semantic versioning
> ([docs/api-review.md]https://github.com/uvar-apps/sesmesh/blob/main/docs/api-review.md).
> A comparison with MSMS, NanoShaper, ESES, EDTSurf, ChimeraX and sesa on
> the same spheres is in
> [docs/comparison.md]https://github.com/uvar-apps/sesmesh/blob/main/docs/comparison.md.
> Work after 1.0 (reference-machine timings, x86 kernel work, marching
> tetrahedra) is tracked in
> [issue #19]https://github.com/uvar-apps/sesmesh/issues/19.

## Install

Command-line tool (binary `sesmesh`):

```bash
cargo install sesmesh-cli
```

Prebuilt binaries for macOS arm64 and Linux x86-64 are attached to the
[GitHub releases](https://github.com/uvar-apps/sesmesh/releases) (up to 1.1.2
also Linux arm64 and Windows x86-64).

Library:

```toml
[dependencies]
sesmesh = "1"
```

Rust 1.89 or newer.

## Quick start

```bash
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](https://github.com/uvar-apps/sesmesh/blob/main/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:

```rust
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.

```bash
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](https://github.com/uvar-apps/sesmesh/blob/main/docs/05-gpu-hip.md),
[docs/06-gpu-cuda.md](https://github.com/uvar-apps/sesmesh/blob/main/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]https://github.com/uvar-apps/sesmesh/blob/main/docs/01-product-specification.md: requirements,
  literature survey, references
* [Design]https://github.com/uvar-apps/sesmesh/blob/main/docs/02-design.md: mathematics, architecture, algorithms
* [Implementation plan]https://github.com/uvar-apps/sesmesh/blob/main/docs/03-implementation-plan.md: phases, tasks,
  milestones
* [Output formats]https://github.com/uvar-apps/sesmesh/blob/main/docs/04-output-formats.md: OBJ, CSV side files, JSON
  statistics
* [Validation report]https://github.com/uvar-apps/sesmesh/blob/main/docs/validation-report.md: accuracy, robustness,
  large inputs, performance
* [CLI manual]https://github.com/uvar-apps/sesmesh/blob/main/docs/cli.md: every option, examples, exit codes
* [GPU back end]https://github.com/uvar-apps/sesmesh/blob/main/docs/05-gpu-hip.md: design, measurements, plan
  ([prior art and revised plan]https://github.com/uvar-apps/sesmesh/blob/main/docs/gpu-prior-art.md)
* [Ambient occlusion]https://github.com/uvar-apps/sesmesh/blob/main/tools/ao/README.md: shaded surfaces by
  post-processing with [aomesh]https://github.com/uvar-apps/aomesh
* Library: crate documentation (`cargo doc --open -p sesmesh`) and
  [examples]https://github.com/uvar-apps/sesmesh/blob/main/crates/sesmesh/examples/
* [API review]https://github.com/uvar-apps/sesmesh/blob/main/docs/api-review.md (semver policy) and
  [release process]https://github.com/uvar-apps/sesmesh/blob/main/docs/release.md

## 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]https://github.com/uvar-apps/sesmesh/blob/main/tests/data/README.md) |
| `docs` | Specification, design and plan |
| `site` | Project website (GitHub Pages; [tools/site/README.md]https://github.com/uvar-apps/sesmesh/blob/main/tools/site/README.md) |
| `tools/ao` | Ambient occlusion with aomesh: `ses_ao.py`, tests ([README]https://github.com/uvar-apps/sesmesh/blob/main/tools/ao/README.md) |

## Building

Requires Rust 1.89 or newer.

```bash
cargo build --release
```

```bash
cargo test --workspace
```

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

```bash
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.3.2) [Computer software]. Zenodo.
> https://doi.org/10.5281/zenodo.24412360

```bibtex
@software{varetto_sesmesh,
  author    = {Varetto, Ugo},
  title     = {{sesmesh: Solvent Excluded Surface meshes for molecules}},
  version   = {1.3.2},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.24412360},
  url       = {https://doi.org/10.5281/zenodo.24412360}
}
```

[doi:10.5281/zenodo.24238836](https://doi.org/10.5281/zenodo.24238836)
stands for all versions and resolves to the latest. The same metadata is in
[CITATION.cff](https://github.com/uvar-apps/sesmesh/blob/main/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)).

## 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]https://doi.org/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]https://doi.org/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]https://doi.org/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]https://doi.org/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]https://doi.org/10.1016/0022-2836(7190324-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](https://github.com/uvar-apps/sesmesh/blob/main/docs/01-product-specification.md#12-references).

## Licence

Copyright (c) 2026 Ugo Varetto.

Licensed under either of

* Apache License, Version 2.0 ([LICENSE-APACHE]https://github.com/uvar-apps/sesmesh/blob/main/LICENSE-APACHE)
* MIT licence ([LICENSE-MIT]https://github.com/uvar-apps/sesmesh/blob/main/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.