Frequently Asked Questions#

Installation#

Where is the yodaStruct binary?#

This tree does not build one. Call require("dseams"). The engine CLI is seams in seams-core.

See: The library, not a second CLI

How do I install the library?#

Build dseams_core.so with meson, then set LUA_PATH and LUA_CPATH. Nix: nix develop.

meson setup bbdir --wrap-mode=nofallback
meson compile -C bbdir
export LUA_PATH="$PWD/lua/?.lua;;"
export LUA_CPATH="$PWD/bbdir/?.so;;"

See: Install the library

I get “module ‘dseams’ not found”#

LUA_PATH does not include the directory that holds dseams.lua.

export LUA_PATH="$PWD/lua/?.lua;;"

I get “module ‘dseams_core’ not found”#

LUA_CPATH does not include the directory that holds dseams_core.so.

export LUA_CPATH="$PWD/bbdir/?.so;;"

Usage#

What do I require?#

local dseams = require("dseams")

Fennel: (require :dseams). require("yoda") is the same table.

What is dseams.core?#

The compiled registrations from dseams_core.so (luaApi::registerAll). Helpers (read, chill_plus, cages) stay in lua/dseams.lua and call names on dseams.core.

How do I read a LAMMPS dump?#

local cloud = dseams.read("input/traj/exampleTraj.lammpstrj", {type = 2})

Pass the oxygen type. On the shipped dump that type is 2.

See: Tutorial: Read a dump and classify

Why do chill_plus and cages disagree?#

They answer different questions. chill_plus is a four-neighbour bond-order label. cages is six-ring HC / DDC membership. A cubic oxygen need not sit in a DDC.

Does chill_plus write a file?#

No. The helper calls getIceTypePlusNoPrint. The cloud is mutated. The return value is an array of state names.

Which Lua version?#

The Nix package and the meson Lua probe target Lua 5.4. The meson wrap fallback is lua-5.4.

Errors#

My cloud has nop=0#

The type filter does not match the dump, or the path does not resolve. Work from the repository root. Pass {type = 2} on the shipped example.

readCon / readChemfiles is not in this build#

Those binds exist only when seams-core was compiled with SEAMS_HAS_READCON or SEAMS_HAS_CHEMFILES. LAMMPS dumps and .xyz do not need them.

Fennel loads dseams.fnl as itself#

Do not put lua/?.fnl on fennel.path and then (require :dseams). Load kebab-case wrappers with fennel.dofile under another name. See Call dseams from Fennel.

Compatibility#

Is require(“yoda”) going away?#

lua/yoda.lua returns require("dseams"). Prefer require("dseams").

Where is the Python API?#

pydseams. Helpers stay in Python. The compiled surface is pydseams._core.

Where is the engine CLI?#

seams in seams-core. The 2020 YAML workflow (config plus globals) belongs there.

See Also#