sesmesh 1.3.2
Guide · command line

The CLI

One binary, sesmesh. Give it structures, get meshes. This page walks through the option groups with working examples; the CLI manual lists every option, and sesmesh surface --help prints them.

01

Install

With a Rust toolchain (1.89 or newer):

Shell
$ cargo install sesmesh-cli

Or download a prebuilt binary for macOS arm64 or Linux x86-64 (up to 1.1.2 also Linux arm64 and Windows x86-64) from the GitHub releases and check it against SHA256SUMS. Each archive also holds the manual page and shell completions; with cargo install, generate them:

Shell
$ sesmesh completions zsh > ~/.zfunc/_sesmesh      # bash, zsh, fish, powershell, elvish
$ sesmesh man > ~/.local/share/man/man1/sesmesh.1
02

First mesh

Shell
$ sesmesh 1crn.cif
sesmesh: 1crn.cif: 327 atoms (model 1), ses surface, probe 1.40 Å, grid 0.500 Å
sesmesh: 13812 vertices, 27616 triangles, 2 component(s) (1 cavity), area 2301.63 Ų, volume 4655.90 ų
sesmesh: wrote 1crn.obj in 0.02 s

The default is the SES with a 1.4 Å probe on a 0.5 Å grid, written as OBJ with normals next to the input (1crn.obj). sesmesh 1crn.cif is short for sesmesh surface 1crn.cif; the other commands are info (models, chains, element counts, assemblies, radius coverage) and radii (print a radius table).

Every mesh is closed, consistently oriented (normals into the solvent, faces counter-clockwise seen from outside) and edge-manifold, with each vertex on the exact surface. Output is byte-identical for any number of threads.
03

Inputs & selection

PDB (fixed columns, hybrid-36), PDBx/mmCIF, XYZ / extended XYZ and PQR, optionally gzip-compressed; the format comes from the file name, then the content (--format overrides). By default the first model is used, waters and hydrogens are dropped, and for alternate locations the highest-occupancy conformer is kept.

Shell
# chains A and B only, ligands removed
$ sesmesh 4hhb.cif.gz --chains A,B --no-hetatm
# model 3 of an NMR ensemble; frame 120 of an XYZ trajectory
$ sesmesh ensemble.pdb --model 3
$ sesmesh traj.xyz --frame 120
# the biological assembly instead of the deposited chains
$ sesmesh info 1k4r.cif.gz                 # lists assemblies and their copy counts
$ sesmesh 1k4r.cif.gz --assembly 1 -q draft  # 60-copy capsid, 545 040 atoms
OptionEffect
--model N / --frame IModel number, or 0-based model position (trajectories)
--block NAMEmmCIF data block
--assembly IDExpand a biological assembly (mmCIF pdbx_struct_*, PDB REMARK 350)
--altloc highest|first|all|AAlternate locations
--hydrogens, --waters, --no-hetatmKeep hydrogens, keep waters, drop hetero atoms
--chains A,B + --chain-ids auth|labelKeep chains, by author or label IDs
--exclude-resn SO4,GOLDrop residues by name
04

Surface & radii

Three surfaces from the same machinery: the SES (where a probe sphere cannot reach), the SAS (traced by the probe centre) and the vdW surface (union of the atom spheres).

Shell
$ sesmesh 1crn.cif --surface sas -o 1crn-sas.obj
$ sesmesh 1crn.cif --surface vdw -o 1crn-vdw.obj
$ sesmesh ligand.xyz --probe 1.2 --radii alvarez
$ sesmesh model.pqr                         # PQR radii are used as given
$ sesmesh 1crn.cif --radii file:my-radii.toml --strict-radii

Radius sets: bondi (default, with Mantina's extension), alvarez, protor (united-atom protein radii), uniform:<r>, or rules from a TOML file. Atoms a set does not cover get --unknown-radius (1.8 Å) and a warning; --strict-radii makes that an error. sesmesh radii --set protor prints a table.

05

Resolution

The grid spacing h sets the detail. Errors fall as h², triangle counts grow as 1/h². Mean errors below are measured on 53 PDB entries against each entry's h → 0 limit (validation report).

Preset -qSpacingArea errorVolume errorTriangles per Ų
draft1.0 Å−2.7 %−0.34 %3
low0.7 Å−1.5 %−0.16 %6
medium (default)0.5 Å−0.82 %−0.08 %12
high0.25 Å−0.20 %−0.02 %48
ultra0.1 Å≈ −0.03 % (h² law)—300
Shell
$ sesmesh 4hhb.cif.gz -q high          # preset
$ sesmesh 4hhb.cif.gz -s 0.3           # any spacing in Å
$ sesmesh 4hhb.cif.gz --density 10     # ≈ 10 vertices per Ų, MSMS-like

--refine linear interpolates vertices instead of solving them onto the surface: faster, less exact.

06

Smoothing & decimation

--smooth N runs N rounds of Taubin smoothing for better-shaped triangles, then projects every vertex back onto the exact surface. Decimation collapses edges by quadric error; it only ever removes vertices, so the ones that stay keep their exact positions, analytic normals and atoms, and the mesh stays closed and manifold.

Shell
# fine grid, then keep a quarter of the triangles
$ sesmesh 1aon.cif.gz -q high --decimate 0.25 -o groel.ply
# at most 200 000 triangles, never moving the surface by more than 0.05 Å
$ sesmesh 1aon.cif.gz -q high --max-triangles 200000 --decimate-error 0.05
# smoother triangles on a coarse grid
$ sesmesh 1crn.cif -q low --smooth 3
A fine grid decimated keeps small features (narrow grooves, pocket mouths) far better than a coarse grid with the same number of triangles.
07

Output

The format follows the -o extension: .obj (default), .ply (binary PLY), .vert/.face (MSMS). A .gz suffix compresses any of them; -o - writes to standard output.

Shell
$ sesmesh 4hhb.cif.gz -o hb.ply.gz --vertex-colors chain
$ sesmesh 4hhb.cif.gz -o hb.vert          # writes hb.vert and hb.face
$ sesmesh 1crn.cif --vertex-colors element --palette atom-colors.json
$ sesmesh 1crn.cif --group-components --vertex-colors patch
$ sesmesh 1crn.cif --atom-areas areas.csv --vertex-data verts.csv --stats stats.json
$ sesmesh 1crn.cif --stats - -o /dev/null | jq .mesh   # numbers only
OptionEffect
--vertex-colors element|chain|patch|componentPer-vertex RGB (OBJ v x y z r g b, PLY uchar)
--palette FILEElement colours (JSON, atom-colors.json format)
--group-componentsOBJ groups component_N / cavity_N
--no-normals, --face-normalsOmit normals, or area-weighted face normals instead of analytic ones
--precision NOBJ decimals (default 4)
--atom-areas, --vertex-dataCSV: SES area per atom; nearest atom, patch, component per vertex
--stats FILE|-JSON: input, parameters, mesh, components, timings

Layouts of every file: output formats.

08

Cavities

The exact SES includes closed internal cavities (negative signed volume). Keep them (default), remove them together with anything inside them (what MSMS reports), or keep only them to study packing defects and pockets.

Shell
$ sesmesh 1aon.cif.gz --cavities remove
$ sesmesh 1aon.cif.gz --cavities only --min-cavity-volume 10 -o pockets.obj
$ sesmesh 2ptn.pdb --min-component-area 5
$ sesmesh 4hhb.cif.gz -q high --drop-fragments      # since 1.1

--drop-fragments removes sub-grid fragments: tiny solid components without a convex atom patch that the grid cuts off from re-entrant sheets thinner than the spacing (4HHB at 0.25 Å: 32 components instead of 33). It is off by default, so default output is unchanged.

09

Large structures

Memory grows with surface area. Before any mesh exists, sesmesh estimates the peak memory of the whole run; --max-memory refuses inputs whose estimate exceeds the limit, and --auto-coarsen coarsens the grid until it fits instead. The estimate is deliberately conservative and is printed in the summary.

Shell
$ sesmesh 3j3q.cif.gz -q draft --progress --timings     # 2.44 M atoms
$ sesmesh 3j3q.cif.gz -q high --max-memory 8G           # exit code 4 if too big
$ sesmesh 3j3q.cif.gz -q high --max-memory 8G --auto-coarsen
$ sesmesh 4v6x.cif.gz -j 4 --simd scalar                # threads, kernel

Ctrl-C stops a run within about 100 ms (exit code 130). -j sets the worker threads; --simd forces a kernel (auto picks the best the CPU supports).

10

GPU

A binary built with the feature hip (ROCm's hipcc at build time) or cuda (CUDA's nvcc) runs the mesh stage on an AMD or NVIDIA GPU: the device samples the field while the CPU threads mesh. The default --refine exact writes the same files as the CPU; --refine fast also refines the vertices on the GPU, in f32, for previews (same triangles, vertices as close to the surface, last bits different).

Shell
$ cargo install sesmesh-cli --features hip                  # or cuda
$ sesmesh 1aon.cif.gz -q high --backend hip                 # same files as the CPU
$ sesmesh 1aon.cif.gz -q high --backend hip --refine fast   # preview
$ sesmesh 1aon.cif.gz -q high --backend auto --timings      # GPU if one works
InputCPU, 16 Zen 5 coresGPU exactGPU fast
4HHB, 0.25 Å0.24 s0.19 s0.12 s
1AON, 0.5 Å1.38 s1.02 s0.56 s
1AON, 0.25 Å3.40 s2.37 s1.41 s
3J3Q, 1 Å (2.4 M atoms)28.9 s23.6 s12.3 s

Complete runs on a Ryzen AI Max+ 395 with its integrated Radeon 8060S (SES, OBJ written; on the 10-core M4's CPU the same runs take 0.38, 2.14, 5.62 and 47.6 s). On a laptop GeForce RTX 2070 Max-Q, whose 6-core i7 bounds both modes, 1AON at 0.5 Å takes 5.48 s on the CPU, 3.04 s exact and 1.70 s fast with --backend cuda. --backend hip and cuda fail if the GPU cannot be used; --backend auto tries HIP, then CUDA, then falls back to the CPU. --gpu-device N picks a GPU; --timings names the device used.

11

Batch mode

Several inputs write <stem>.<ext> into --output-dir; side files go to directories of the same name.

Shell
$ sesmesh pdb/*.cif.gz --output-dir meshes --output-format ply \
      --keep-going --stats stats --atom-areas areas
In batch mode -o is a usage error; use --output-dir and --output-format instead. Missing directories are created. Without --keep-going the batch stops at the first failure.
12

Exit codes

CodeMeaning
0Success (also when a reader closes standard output early)
1Runtime error: I/O, empty selection, invalid input data, batch failure
2Usage error: unknown option, invalid value, conflicting options
3Parse error: malformed file, unknown format, invalid palette
4Resource limit: --max-memory, decompression or assembly size
130Interrupted (Ctrl-C)
Full CLI manual ↗