Quickstart

Build the engine, read a frame, and print what this binary linked.

The in-tree mixed TIP4P dump is input/traj/exampleTraj.lammpstrj (750 atoms, 250 waters; type 2 is oxygen).

Install the engine

Nix flake:

nix build
./result/bin/seams --help
nix develop   # compiler, Eigen, BLAS, Catch2

pixi:

pixi run setup
pixi run build
./bbdir/seams --help

Either path produces libyodaLib and the seams CLI. This repository does not install Python or Lua.

Read a frame

seams read input/traj/exampleTraj.lammpstrj

The line is nop 250 frame 1 box ... after the oxygen guess (type 2, then type 1). Pass --type 2 to skip the guess.

Features of this build

seams --features

Each line is a compile-time backend: OpenMP, MPI, Highway SIMD, vesin, chemfiles, readcon-core, IRA/SOFI, sphericart, nauty. The Nix flake turns Eigen, BLAS/LAPACK, Catch2 and Highway on when nixpkgs provides them. Optional wrap-git backends stay off unless a package is already in the closure. pixi enables what conda-forge put in the environment (Highway and chemfiles are in the default pixi lock).

Runtime knobs

Knobs that change between machines and jobs are twelve-factor. They are not compiled in and they are not conf.yaml. Defaults live in the binary. An optional dotenv file (SEAMS_CONFIG or ./seams.env) fills unset variables. The process environment wins over the file. CLI flags win over the environment.

cp seams.env.example seams.env
seams --print-config
seams --frame 1 --last 100 --jobs 8 --type 2 --graph seeded \
  cages input/traj/exampleTraj.lammpstrj

The same values can be SEAMS_FRAME, SEAMS_LAST, SEAMS_JOBS, SEAMS_TYPE, SEAMS_CUTOFF, SEAMS_K, SEAMS_GRAPH, plus SEAMS_RESIDENT, SEAMS_CELL, SEAMS_OFFLOAD, LINKCELL_TPP, LINKCELL_BLOCK. OMP_NUM_THREADS and CUDA_VISIBLE_DEVICES keep their usual meaning. Analysis choice (which seams command, which pydseams call, which require("dseams") script) is not this table.

CHILL+ and cages

seams chill-plus input/traj/exampleTraj.lammpstrj --cutoff 3.5 --type 2
seams cages input/traj/exampleTraj.lammpstrj --type 2

On this fixture the four-neighbour labels are 12 interfacial clathrate and 238 water. The default bond graph is --graph seeded (mutual four-nearest seeds, union completions). This mixed frame has no complete HC or DDC: cage membership is not the CHILL+ star.

Python and Lua

The engine CLI is not a scripting host. Install pydseams (pip install pydseamslib, compiled module yoda) or yodaStruct (require("dseams")). import pydseamslib is an alias of pydseams.

The Frame tutorial is pydseams docs. Lua is dseams docs.

The full install matrix is Install. The mixed-frame walkthrough is Classify ice on the mixed TIP4P example.