Expand description
§sesmesh
Solvent Excluded Surface (SES, also called the Connolly or molecular surface) meshing for molecular structures read from PDB, PDBx/mmCIF, XYZ and PQR files: closed, consistently oriented triangle meshes with exact analytic normals, multi-threaded and SIMD-accelerated.
§Quick start
use sesmesh::{compute_surface, mesh, Sphere, SurfaceParams};
let atoms = [Sphere::new([0.0, 0.0, 0.0], 1.7), Sphere::new([3.0, 0.0, 0.0], 1.7)];
let out = compute_surface(&atoms, &SurfaceParams::ses(1.4).with_spacing(0.3))?;
assert!(mesh::validate(&out.mesh).is_ok()); // closed, oriented, manifold
assert_eq!(out.stats.components, 1);From a file (readers, selection, radii):
use sesmesh::{io, radii, Diagnostics, Selection, Sphere, SurfaceParams, compute_surface};
let cif = "data_x\nloop_\n_atom_site.type_symbol\n_atom_site.Cartn_x\n\
_atom_site.Cartn_y\n_atom_site.Cartn_z\nC 0 0 0\nO 1.2 0 0\n";
let structure = io::read_bytes(cif.as_bytes(), &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)?;
assert_eq!(radii, [1.70, 1.52]);
let out = compute_surface(&Sphere::from_atoms(&atoms, &radii)?, &SurfaceParams::default())?;
assert!(out.stats.area > 0.0);More in the examples
(file → OBJ, spheres → mesh, trajectories with SurfaceEngine, custom
radii, field queries) and the
CLI manual.
§Concepts
- Surfaces (
SurfaceKind): the SES (default) is the boundary of the region a probe sphere of radiusr_p(1.4 Å for water) cannot enter; the SAS is traced by the probe centre (atom radii +r_p); the vdW surface is the union of the atom spheres. sesmesh evaluates the exact SES fieldF(x) = r_p − d(x, P)(P: positions the probe centre can reach) on a sparse grid and extracts its zero level set with Marching Cubes; every vertex is then moved onto the exact surface, so positions are exact and normals are analytic. Each vertex records its patch (PatchKind: convex, saddle, concave) and nearest atom. - Resolution (
Resolution): the grid spacinghin Å (SurfaceParams::with_spacing), a preset (Quality: draft 1.0, low 0.7, medium 0.5 (default), high 0.25, ultra 0.1 Å), or a target vertex density (SurfaceParams::with_density: about1.5 / h²vertices per Ų). Error decreases ash²: area −0.2 % and volume −0.02 % on average at 0.25 Å on a 53-entry protein corpus (validation report).SurfaceParams::with_smoothingimproves triangle shapes while keeping vertices on the surface. - Components and cavities:
SurfaceOutput::componentslists the closed components (area, signed volume, Euler characteristic, genus); internal cavities have negative volume.CavityModekeeps them (the exact SES), removes them with their content, or keeps only them; triangles are grouped by component. - Determinism: the output is bit-identical for any number of threads
and on repeated runs. Work runs in the current rayon pool (feature
parallel, default);Controladds cancellation and progress. - SIMD: the field kernel runs at the best instruction set of the CPU
(AVX-512, AVX2, SSE4.2, NEON, WASM SIMD) or a portable fallback
(
SimdLevel); all levels agree within 2·10⁻⁵ Å. - Errors and warnings: every fallible call returns
ResultwithError; non-fatal problems (unknown elements, missing radii, discarded alt-locs) are collected inDiagnostics. The library never prints.
§Modules
| Module | Content |
|---|---|
io | PDB, mmCIF, XYZ/extended XYZ, PQR readers (gzip), biological assemblies |
structure | Atoms, models, Selection |
radii | Bondi, Alvarez, ProtOr, uniform and custom radius rules |
geom | Sphere, SAS arrangement statistics |
field | Exact field queries (SesField), SurfaceKind, SimdLevel |
mesh | Mesh, validation, components, per-atom areas |
export | OBJ, binary PLY, MSMS writers |
color | Vertex colour palettes |
§Features
parallel (rayon, default), gzip (compressed input and output,
default), radii-file (TOML radius rules, default). Without default
features the crate is single-threaded and dependency-light (WASM).
hip (off by default) adds the AMD GPU back end, Backend::Hip; it
needs ROCm’s hipcc to build, and its binaries still run on machines
without ROCm (see Backend). cuda (off by default) adds the NVIDIA
GPU back end, Backend::Cuda; it needs CUDA’s nvcc to build, and its
binaries still run without the NVIDIA driver.
§Versioning
Semantic versioning. Public structs and enums that may grow are
#[non_exhaustive]: build option structs from their constructors or
Default and assign fields; match enums with a wildcard arm.
§Licence
Copyright (c) 2026 Ugo Varetto. Licensed under either of the Apache License, Version 2.0 or the MIT licence, at your option.
Re-exports§
pub use diag::Diagnostics;pub use diag::Warning;pub use diag::WarningKind;pub use error::Error;pub use error::Result;pub use field::SimdLevel;pub use field::SesField;pub use field::SurfaceKind;pub use geom::Sphere;pub use mesh::Mesh;pub use mesh::PatchKind;pub use structure::AtomRecord;pub use structure::AtomSet;pub use structure::Element;pub use structure::Model;pub use structure::Selection;pub use structure::Structure;
Modules§
- color
- Vertex colour palettes for mesh output (Spec FR-OUT-2).
- diag
- Non-fatal diagnostics (warnings) collected while reading and processing structures.
- error
- Error type shared by every fallible sesmesh operation.
- export
- Mesh output formats (Design §10): Wavefront OBJ (
obj), binary PLY (ply) and MSMS.vert/.face(msms). - field
- The surface field (Design §2) and its sampling on a sparse brick lattice with SIMD kernels and multi-threading (Design §7).
- geom
- Sphere-set geometry: the public
Sphereinput type and the internal SAS arrangement used by the surface engine (Design §6). - io
- Structure file readers: PDB, PDBx/mmCIF, XYZ / extended XYZ and PQR, optionally gzip-compressed (Spec FR-IN, Design §5).
- mesh
- Triangle meshes: the
Meshtype, isosurface extraction (Design §8), measurements, connected components and validation (Design §9.1, §9.3). - radii
- Atomic radius assignment (Spec FR-RAD, Design §5.6).
- structure
- In-memory representation of parsed molecular structures.
Structs§
- Control
- Cancellation flag and progress callback for a computation.
- Cuda
Options - Options of
Backend::Cuda. - HipOptions
- Options of
Backend::Hip. - Progress
- A progress report:
doneoftotalwork units ofstage. - Surface
Engine - A reusable surface computation (Spec FR-LIB-3), e.g. for the frames of a trajectory: parameters are validated and the back end’s device is opened once, and the per-thread field sampling buffers are kept between calls.
- Surface
Output - Result of
compute_surface. - Surface
Params - Parameters of
compute_surface. - Surface
Stats - Statistics of a computed surface.
- Timings
- Wall-clock time of each stage.
Enums§
- Backend
- Where the mesh stages run (
crate::SurfaceParams::backend). - Cavity
Mode - Which components to keep (Spec FR-SURF-4, Design §9.2).
- Normal
Mode - Which vertex normals the mesh carries (Spec FR-MESH-3).
- Quality
- Resolution presets (Spec FR-LOD-2).
- Refine
Mode - How vertices are placed on crossing grid edges (Design §8.2).
- Resolution
- How finely the surface is sampled.
- Stage
- A stage of
compute_surface_with.
Constants§
- VERSION
- Version of the
sesmeshlibrary, taken fromCargo.toml. - VERTICES_
PER_ AREA_ H2 - Mesh vertices per Ų times h²: crossing grid edges per unit area of a
surface average
1.5 / h²over orientations (Design §8.6); measured 1.50 on crambin at 0.25 Å. Calibrated on the validation set in Phase 9.
Functions§
- compute_
surface - Computes the surface of a set of spheres (Spec FR-LIB-1).
- compute_
surface_ with compute_surfacewith cancellation and progress reporting (Spec FR-LIB-5).- estimate_
memory - Estimated triangle count and peak bytes (without decimation) for
surface_brickssurface bricks ofbrick_sizecells atspacingandspheresinput spheres, a closed-form version of the memory guard’s estimate (Design §8.6, §11.3).