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.