Repositories¶

d-SEAMS 2 is not a monolith. The classifier is one C++ library. Cutoff neighbour lists are optional vesin (brute-force fallback). Periodic k-nearest graphs are optional linkcell. Each language ships its own package against that library.

repository	product	role
seams-core	`libyodaLib`, `seams`	C++ engine and CLI
PydSEAMSlib	`pydseams`	Python helpers on `yoda`
yodaStruct	`dseams`	Lua/Fennel library
linkcell	`lc_*`	Periodic linked-cell k-nearest neighbours

The front ends take seams-core as a Meson subproject (libyodaLib) or as a flake input. They do not vendor a second engine.

A language binding that lived in the engine tree would force every C++ user to take that language’s toolchain, and every wheel or rock to rebuild the same library. Splitting the repos keeps the Catch2 suite, the seams CLI, and the optional backends on one Meson project, while Python and Lua version and release on their own schedules.

        flowchart TB
  subgraph engine["seams-core"]
    LIB[libyodaLib]
    CLI[seams CLI]
  end
  subgraph fronts["Front ends"]
    PY[pydseams Frame]
    LUA["require(\"dseams\")"]
  end
  LC["linkcell k-NN"]
  VE["vesin cutoff"]
  GPU["gpulite TUM batch"]
  DUMP["LAMMPS / XYZ / chemfiles / con"] --> LIB
  LC --> LIB
  VE --> LIB
  GPU --> LIB
  LIB --> CLI
  LIB --> PY
  LIB --> LUA

Why `yoda`¶

The 2020 product was a single executable named yodaStruct. That binary is gone. The compiled C++ surface kept the name so existing registrations stay findable: the Python module is pydseams.yoda (_core and cyoda are aliases of yoda). Lua helpers are require("dseams"); require("yoda") still resolves to that table. There is no yodaStruct executable in any of the three repositories.

Builds¶

Nix flake: nix build / nix develop in each repo. Optional wrap-git backends stay off unless nixpkgs already provides them.
pixi: locked conda-forge toolchain in seams-core.
Wheels: cibuildwheel on PydSEAMSlib, CPython 3.12 limited ABI.

The 2020 CMake Nix derivation of yodaStruct is gone. -Dwith_python=true and -Dwith_lua=enabled are Meson errors that name PydSEAMSlib and yodaStruct.

Neighbour backends¶

vesin (optional, SEAMS_HAS_VESIN): cutoff pair lists (neighList, neighListO). Brute force if the wrap is off.
linkcell (optional, SEAMS_HAS_LINKCELL): periodic k-NN for knn / knn-union / seeded graphs and the device TUM walk. Not a drop-in for vesin cutoff lists.

seams --features prints both.

Device paths¶

Optional CUDA via gpulite (-Dwith_gpulite) runs the TUM ice score only: linkcell k-NN, mutual four-nearest graph, primitive six-rings, HC/DDC. CHILL and \(q_{lm}\) stay on the host.

OpenMP target offload is a second GPU path, Steinhardt-only, meson off by default (-Dwith_openmp_offload, SEAMS_OFFLOAD). It is not gpulite.

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. Keys: SEAMS_FRAME / LAST / JOBS / TYPE / CUTOFF / K / GRAPH / RESIDENT / CELL / OFFLOAD, LINKCELL_TPP / BLOCK, YODA_FENNEL_PATH / YODA_LUA_PATH. Analysis choice is not this table.

Ice score and the CHILL+ star¶

Two classifiers live in libyodaLib. They answer different questions and they do not imply each other. The argument is CHILL+ versus cages.

seams cages --graph chooses the bond graph the six-rings are found on: cutoff, knn, knn-union, or seeded (CLI default). On a perfect cubic crystal the four graphs coincide. On a mixed nucleation dump they do not.