seams CLI

The engine command is seams. The parser is Argum (the same parser as eonclient). Help, errors, ice-type counts, and --features are colorized through Argum’s environmentColorStatus.

seams --help
seams --version
seams --features
seams read FILE
seams chill FILE
seams chill-plus FILE
seams cages FILE
seams rdf FILE
seams cn FILE
seams hbonds FILE
seams pairs FILE
seams density-z FILE
seams domains FILE

A positional command and a positional file are required. Missing either, an unknown command, or a parse error exits 2.

Every command accepts --format text|json. Text is the human-readable format documented below. JSON emits one JSON object per output frame on stdout, with the fields schema (dseams.cli/v1), command, frame, status, and text. The text field contains the command’s text output without changing its contents. --strict-input returns 2 when a requested frame has no atoms; without it, empty input retains the legacy text output.

Commands

The command positional help string is read | chill | chill-plus | cages | fingerprint | ions | rdf | cn | hbonds | pairs | density-z | domains. chill_plus is an accepted alias of chill-plus (not listed in that help string).

command	action	stdout
read	print the loaded cloud	nop N frame F box Lx Ly Lz and, when box.size() >= 6, xy xz yz
chill	CHILL four-neighbour labels	nop N then name count for each ice type present
chill-plus	CHILL+ four-neighbour labels	same as chill
cages	ice score on six-membered rings	nop N graph KIND hexagonal IH cubic IC water W
cages --signature SPEC	closed polyhedra whose ring-size census matches SPEC	nop N graph KIND signature S cages C atoms A and, with --guest-types, guests G occupied O multiple M free F
fingerprint	topology keys of the bonded graph	nop N graph KIND hops H method M key K classes C rings 3:a 4:b ... top key=count ...
fingerprint --emit-library LABEL	the frame’s distinct keys as library lines	# method M hops H colours C then key LABEL rows
fingerprint --library FILE[,FILE...]	atoms named by key libraries	nop N graph KIND hops H method M matched X label=count ... unmatched=U and, with several libraries, depth H1=n1 H2=n2
ions	ions classed by their first water shell against the seeded cages	nop N ice A ions I in-ice X front Y liquid Z shell S shell-ice F
rdf	partial site-site \(g_{IJ}(r)\)	# r g count then # types I J rmax R bins N volume V then one r g count row per bin
cn	site-site coordination number	# site-site then # types I J cutoff R cn X nI N nJ M volume V
cn --ions --site	cage degree on ionCloud	cage ionCloud types 1 2 cutoff R degree D nCation N nAnion M
hbonds	geometric hydrogen-bond count	nop N hbonds E
pairs --site	mutual-nearest contact pairs	contact-pair count N nCation C nAnion A
density-z	type-resolved \(\rho\) along one axis	# z rho then one z rho row per bin
domains --site --subset	polar/apolar Stoddard component	subset polar n N largest L P P_inf

chill / chill-plus call nneigh::neighListO, then chill::getCorrel / chill::getIceTypeNoPrint or chill::getCorrelPlus / chill::getIceTypePlusNoPrint. Ice names are the molSys::atom_state_type enumerators: cubic, hexagonal, water, interfacial, clathrate, interClathrate, reCubic, reHex, unclassified.

cages reports cage membership, not CHILL labels: hexagonal = HC (Ih), cubic = DDC (Ic), water = neither. The bond graph is --graph.

rdf and cn call rdf::partialRdf on LAMMPS type IDs from --types I,J (default I = J = --type). --cutoff is rmax. --bins is optional. The volume is nneigh::dumpVolume (det of dump H). cn integrates the site-site RDF to that cutoff (rdf::coordinationNumber). Help text and the cn header say site-site. There is no cage CN and no --ions.

cn --ions --site SPEC builds site::ionCloud and prints the mean unlike degree of type-1 (cation) vertices from nneigh::neighList(cutoff, ions, 1, 2). The line contains cage. pairs --site SPEC prints the size of nneigh::mutualNearestUnlike(ions, 1, 2). That line contains contact-pair, not ionicity. Both need --site.

density-z calls site::densityZ. --type 0 (default) keeps every atom; --type I keeps that LAMMPS type. --axis is x, y, or z (default z). --bins defaults to the bound span over \(0.1\). Each slab volume is \(A_\perp \times dz\), with \(A_\perp\) from dump H (recovered lx, ly, lz, not bound spans). This is not an ice score.

chill, chill-plus, and cages call site::iceScoreAllowed. When --family is not waterIce they print site::refuseIceScore (the message names the family) and exit 2. They do not fall through to atom_state_type::water. Unflagged seams chill stays waterIce. If --family is absent and the frame has more than two LAMMPS types, one stderr line names --family and the command still exits 0.

An empty cloud (nop 0) still prints. chill / chill-plus print nop 0. cages prints nop 0 graph KIND hexagonal 0 cubic 0 water 0. rdf / cn still emit their headers. hbonds prints nop 0 hbonds 0. density-z prints # z rho and zero-density bins.

hbonds loads the heavy-atom cloud with --type and the hydrogen cloud with --htype, then builds a cutoff neighbour list. Without --donors it uses the water two-hydrogen-per-molecule set (hAtomMolList). --donors passes every hydrogen index to populateHbondsFromDonors. --hdist and --hangle are the acceptor-H distance and the acceptor-centered O-O-H angle cutoffs (angle between OO and OH); the C++ defaults stay the water values and are not an ionic-liquid criterion.

Options

Names and help text are the Argum Option / Positional definitions in src/seams_cli.cpp. Defaults are the C++ initializers (Argum does not write defaults into the help).

--help, --version, --features, and --print-config print and exit 0 before any file is opened.

--tpp, --block, --resident, and --cell apply to the device TUM ice score (seams cages) only. CHILL and \(q_{lm}\) stay on the host.

--cutoff is in Angstrom. -k also applies to knn-union (the same k feeds nneigh::kNearestNeighbourList). --graph is used by cages and fingerprint; a fingerprint wants one graph, so seeded (two graphs) falls back to cutoff there. --complete is used by cages and ions: it passes true as the fifth argument of seededCageAffiliation.

--type

value	single frame (load)	--last range (forEachLammpsFrame)
0	LAMMPS: type 2, then type 1 if that cloud is empty. chemfiles: keep every atom. XYZ: every atom is type 1	LAMMPS: every atom (sinp::readLammpsTrj). Classification uses cloud.pts[0].type
I > 0	LAMMPS readLammpsTrjO / chemfiles filter I	LAMMPS readLammpsTrjO with that type. The CLI does not pass a coordinate slice.

XYZ always stores type 1. Classification still uses --type after the read (type 0 then becomes 1).

A mixed-type dump that is not the water guess needs --type I. density-z treats 0 as every atom, not the oxygen guess. See Ionic-liquid dumps.

--types

Used by rdf and cn. The Argum form is I,J (one comma). A bad string exits 2 (bad --types (want I,J)). Omit the flag to set both sides to --type. These are LAMMPS type IDs on the original cloud (site-site). cn --ions is a different path (ionCloud cage degree).

--types	single-frame load	--last range
omitted	same as --type (one species)	same as --type
I,I (like)	keep type I	keep type I
I,J with I != J	every atom (readLammpsTrj / chemfiles unfiltered)	every atom (typeFilter 0)

cmdRdf / cmdCn then call rdf::partialRdf on those two integers. typeOf still resolves a zero to the first atom (or 1).

seams read and the box

seams read prints gen::formatDumpBox: the three bound spans, then xy xz yz when box.size() >= 6. There is no separate tilt flag. seams rdf uses the same dump H (gen::periodicDist and nneigh::dumpVolume). seams density-z uses recovered lx, ly, lz for \(A_\perp\), not bound spans. The in-plane sampler remains rdf2::sampleRDF_AA; see Sheared cells.

--graph

Used only by cages.

value	graph
seeded	mutual k-nearest seeds, union completions (ring::seededCageAffiliation; --complete sets the fifth argument)
cutoff	pairs inside --cutoff (nneigh::neighListO)
knn	mutual k-nearest (nneigh::BondGraph::KnnMutual)
knn-union	union k-nearest (nneigh::BondGraph::KnnUnion)

nneigh::bondGraphFromName also accepts knn-mutual and mutual as knn, and union as knn-union. seeded is handled in the CLI and is not a BondGraph enumerator. Any other name throws std::invalid_argument (unknown bond graph 'NAME' (use cutoff, knn, knn-union)) and cages exits 2.

Candidate cutoff for the knn graphs is --cutoff + 1.5.

Runtime knobs

Defaults live in the binary. An optional dotenv (SEAMS_CONFIG or ./seams.env) fills unset keys. The process environment wins the file; CLI flags win the environment. seams --print-config dumps the table.

variable	default
SEAMS_FRAME / SEAMS_LAST	1 / 0
SEAMS_JOBS	1
SEAMS_TYPE	0
SEAMS_CUTOFF	3.5
SEAMS_K	4
SEAMS_GRAPH	seeded
SEAMS_FAMILY	waterIce
SEAMS_RESIDENT	0.80
SEAMS_CELL	3.0
SEAMS_TPP / LINKCELL_TPP	occupancy picker (0)
SEAMS_BLOCK / LINKCELL_BLOCK	occupancy picker (0)
SEAMS_OFFLOAD	false
YODA_FENNEL_PATH / YODA_LUA_PATH	empty

Analysis choice (which command) is not this table.

File suffix

seams picks a reader from the path suffix (path.find_last_of('.')):

suffix	reader	compile-time gate
xyz	sinp::readXYZ	always
con	sinp::readCon	SEAMS_HAS_READCON
pdb, gro, dcd	sinp::readChemfiles	SEAMS_HAS_CHEMFILES
anything else	LAMMPS dump (readLammpsTrjO / readLammpsTrj)	always

A build without chemfiles or readcon-core treats .pdb / .gro / .dcd / .con as LAMMPS dumps. seams --features reports those gates.

Frame ranges

Omit --last, or set it equal to --frame, for one frame. That path calls load and works for every linked suffix.

A range (--last > --frame) dispatches by suffix. LAMMPS dumps use sinp::forEachLammpsFrame, with one handle per OpenMP worker and deterministic output order. XYZ is a single-frame input and emits frame 1 at most. Chemfiles and readcon inputs are read serially until the requested range or the first missing frame. --jobs 1 is serial; non-LAMMPS readers do not use OpenMP workers.

--features

Heading Compile-time features: then one line per backend. Each line is NAME: enabled or NAME: disabled.

printed name	macro
OpenMP	SEAMS_HAS_OPENMP
MPI	SEAMS_HAS_MPI
Highway SIMD	SEAMS_HAS_HWY
vesin neighbours	SEAMS_HAS_VESIN
linkcell k-nearest	SEAMS_HAS_LINKCELL
chemfiles	SEAMS_HAS_CHEMFILES
readcon-core	SEAMS_HAS_READCON
IRA/SOFI	SEAMS_HAS_IRA
sphericart	SEAMS_HAS_SPHERICART
nauty	SEAMS_HAS_NAUTY

Colors

colorizerForFile(environmentColorStatus(), stdout). Argum’s environmentColorStatus (first match wins):

condition	result
NO_COLOR set and non-empty	off
FORCE_COLOR set and non-empty	on
CLICOLOR_FORCE set, non-empty, not 0 / false	on
CLICOLOR_FORCE is 0 or false	off
CLICOLOR is 0 or false	off
CLICOLOR set and non-empty	allowed (TTY decides)
COLORTERM set and non-empty	allowed
TERM=dumb	off
otherwise	TTY / TERM heuristics

Color roles on this binary:

role	used for
heading	d-SEAMS banner, nop, Compile-time features:
progName	seams in --version; clathrate, interClathrate
longOption	frame, graph; cubic, reCubic
shortOption	box; hexagonal, reHex
warning	usage line; interfacial; enabled
error	parse / missing-args / unknown-command; unclassified; disabled
uncolored	water

Exit status

code	when
0	success, including --help / --version / --features / --print-config
2	parse error, missing command or file, unknown command, unknown --graph, bad --types, --bins < 0, unknown --family, ice score refused by --family

Examples

seams read input/traj/exampleTraj.lammpstrj
seams chill-plus input/traj/exampleTraj.lammpstrj --cutoff 3.5 --type 2
seams cages input/traj/mW_cubic.lammpstrj --type 1 --graph seeded
seams cages dump.lammpstrj --graph cutoff
seams cages dump.lammpstrj --graph knn
seams cages dump.lammpstrj --graph knn-union
seams chill-plus dump.lammpstrj --frame 1 --last 50 --jobs 8
seams rdf dump.lammpstrj --types 1,2 --cutoff 10 --bins 100
seams cn dump.lammpstrj --types 1,2 --cutoff 4.5
seams cn dump.lammpstrj --ions --site '1=cationHead,2=anion' --cutoff 6.0
seams pairs dump.lammpstrj --site '1=cationHead,2=anion'
seams hbonds dump.lammpstrj --type 2 --htype 1
seams hbonds dump.lammpstrj --donors
seams chill dump.lammpstrj --family ionicLiquid

Lua and Python are not this binary. See yodaStruct (require("dseams")) and PydSEAMSlib (pydseams).