Quickstart

Install the engine, classify one cubic cell, then read one LAMMPS frame. Commands below are run from the repository root.

Install

The build needs a C++20 compiler, Eigen 3.4, and Rust (linkcell, minimage, and readcon). The install page pins conda-forge eigen to the 3.4 series. An unpinned eigen package on that channel currently resolves to 5.0.1, and this release builds with Eigen 3.4.

meson setup build -Dwith_tests=false
meson compile -C build
./build/seams --version

-Dwith_tests=false leaves out the test suite. The compile still writes ./build/seams, libyodaLib, libseams (include/seams.h), and libseams_lang. ./build/seams --version prints seams 2.14.0.

Source and pixi builds are on Install the engine.

The Python binding is PydSEAMSlib. import dseams is the array API below, and import pydseams is the Frame API:

pip install 'pydseamslib==2.14.0'

Every language is listed on Use a language binding.

Eight cubic molecules

The cell is the eight-atom diamond. The nearest-neighbour distance is 2.75 Å, so the cubic lattice constant is 2.75 * 4 / sqrt(3).

import dseams
a = 2.75 * 4 / 3**0.5
sites = (
    (0, 0, 0),
    (0.5, 0.5, 0),
    (0.5, 0, 0.5),
    (0, 0.5, 0.5),
    (0.25, 0.25, 0.25),
    (0.75, 0.75, 0.25),
    (0.75, 0.25, 0.75),
    (0.25, 0.75, 0.75),
)
xyz = [[x * a, y * a, z * a] for x, y, z in sites]
labels, counts = dseams.chill_plus(xyz, [a, a, a])
print(int(counts[0]))
assert counts[0] == 8

dseams.chill_plus returns one label per atom and nine counts, in the order of seams_label_name. Index 0 is cubic. The call uses the published rule and the cutoff neighbour list at 3.5 Å. The program prints 8: every atom is cubic.

The same cell is docs/examples/quickstart.c. That program prints cubic 8.

cc -I include -I build/src docs/examples/quickstart.c -L build/src -lseams -lm -Wl,-rpath,"$PWD/build/src" -o quickstart
./quickstart

-I build/src is the generated seams_version.h. The calls in that file are:

seams_system *sys = seams_system_create();
seams_system_set_ortho(sys, xyz, 8, 0, 0, 0, a, a, a, NULL, NULL);
seams_chill_plus(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, SEAMS_CHILL_PUBLISHED, labels, counts);
printf("cubic %d\n", counts[0]);
seams_system_destroy(sys);

a is the lattice constant, xyz is the 24 coordinates, labels is one int per atom, and counts is nine ints. Index 0 is SEAMS_LABEL_CUBIC.

Read a frame

input/traj/exampleTraj.lammpstrj is one frame of 750 atoms: 250 oxygens and 500 hydrogens, 250 TIP4P waters. Type 2 is oxygen. Type 1 is hydrogen.

./build/seams read input/traj/exampleTraj.lammpstrj
nop 250 frame 1 box 40 40 180.203

nop is the number of atoms kept. box is the three bound spans, in the file’s coordinate units. When --type is omitted, the reader keeps type 2 if the file contains it, and type 1 otherwise. --type 2 names oxygen. On this file it prints the same line.

CHILL+ and cages

./build/seams chill-plus input/traj/exampleTraj.lammpstrj --cutoff 3.5 --type 2
./build/seams chill-plus input/traj/exampleTraj.lammpstrj --cutoff 3.5 --type 2 --graph mutual
./build/seams cages input/traj/exampleTraj.lammpstrj --type 2
nop 250 interClathrate 9 water 241
nop 250 clathrate 1 interClathrate 7 water 242
nop 250 graph seeded hexagonal 0 cubic 0 both 0 water 250

The lines are in command order. The first CHILL+ command uses the cutoff list: every pair closer than 3.5 Å. --graph mutual keeps the mutual four nearest neighbours, with candidates inside the cutoff plus 1.5 Å. interClathrate is the three-eclipsed star. It is a different label from interfacial.

seams cages defaults to --graph seeded: mutual four-nearest seeds, then union completions. hexagonal is the hexagonal cage, cubic is the double-diamond cage, and both is an oxygen that belongs to both cages. This frame has none of those cages. Cage membership is a different score from the CHILL+ star. The walk-through is Classify ice on the mixed TIP4P example.

Other counts

./build/seams rings input/traj/exampleTraj.lammpstrj --type 2
./build/seams steinhardt input/traj/exampleTraj.lammpstrj --type 2
./build/seams symmetry input/traj/mW_cubic.lammpstrj --type 1

mW_cubic.lammpstrj is 4096 atoms of type 1.

Backends

./build/seams --features

The command prints Compile-time features: and one line per backend. The names are OpenMP, MPI, Highway SIMD, vesin cutoff fallback, linkcell pairs_within, chemfiles, readcon-core, readcon-db, IRA/SOFI, spglib, sphericart, and nauty. Each line ends with enabled or disabled. Which lines are enabled depends on the build. chemfiles is the PDB, GRO, and DCD reader. readcon-core is the CON reader.

Frame, atom type, cutoff, and graph are flags, or the variables printed by ./build/seams --print-config. The names and the precedence of ./seams.env and SEAMS_CONFIG are on the seams CLI page.