Skip to main content

Crate sesmesh

Crate sesmesh 

Source
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 radius r_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 field F(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 spacing h in Å (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: about 1.5 / h² vertices per Ų). Error decreases as h²: area −0.2 % and volume −0.02 % on average at 0.25 Å on a 53-entry protein corpus (validation report). SurfaceParams::with_smoothing improves triangle shapes while keeping vertices on the surface.
  • Components and cavities: SurfaceOutput::components lists the closed components (area, signed volume, Euler characteristic, genus); internal cavities have negative volume. CavityMode keeps 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); Control adds 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 Result with Error; non-fatal problems (unknown elements, missing radii, discarded alt-locs) are collected in Diagnostics. The library never prints.

§Modules

ModuleContent
ioPDB, mmCIF, XYZ/extended XYZ, PQR readers (gzip), biological assemblies
structureAtoms, models, Selection
radiiBondi, Alvarez, ProtOr, uniform and custom radius rules
geomSphere, SAS arrangement statistics
fieldExact field queries (SesField), SurfaceKind, SimdLevel
meshMesh, validation, components, per-atom areas
exportOBJ, binary PLY, MSMS writers
colorVertex 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 Sphere input 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 Mesh type, 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.
CudaOptions
Options of Backend::Cuda.
HipOptions
Options of Backend::Hip.
Progress
A progress report: done of total work units of stage.
SurfaceEngine
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.
SurfaceOutput
Result of compute_surface.
SurfaceParams
Parameters of compute_surface.
SurfaceStats
Statistics of a computed surface.
Timings
Wall-clock time of each stage.

Enums§

Backend
Where the mesh stages run (crate::SurfaceParams::backend).
CavityMode
Which components to keep (Spec FR-SURF-4, Design §9.2).
NormalMode
Which vertex normals the mesh carries (Spec FR-MESH-3).
Quality
Resolution presets (Spec FR-LOD-2).
RefineMode
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 sesmesh library, taken from Cargo.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_surface with cancellation and progress reporting (Spec FR-LIB-5).
estimate_memory
Estimated triangle count and peak bytes (without decimation) for surface_bricks surface bricks of brick_size cells at spacing and spheres input spheres, a closed-form version of the memory guard’s estimate (Design §8.6, §11.3).