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

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

Commands¶

The command positional help string is read | chill | chill-plus | cages. 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`
`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`

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.

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.

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, and --features print and exit 0 before any file is opened.

--cutoff is in Angstrom. -k also applies to knn-union (the same k feeds nneigh::kNearestNeighbourList). --graph is used only by cages.

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

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

`--graph`¶

Used only by cages.

value	graph
`seeded`	mutual `k`-nearest seeds, union completions (`ring::seededCageAffiliation`)
`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.

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) always walks a LAMMPS dump through sinp::forEachLammpsFrame. Each OpenMP worker opens its own handle and seeks the shared ITEM: TIMESTEP offset table. --jobs 1 is serial. Non-LAMMPS suffixes are not walked this way.

`--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`
`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`
`2`	parse error, missing command or file, unknown command, unknown `--graph`

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

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