require(“dseams”)#

Public table from require("dseams") (lua/dseams.lua on dseams_core). require("yoda") is the same table.

Fennel call shape is in Call dseams from Fennel. Compiled names on dseams.core are in Compiled registrations.

Public names#

local dseams = require("dseams")
local cloud = dseams.read("water.lammpstrj", {type = 2})
local types = dseams.chill_plus(cloud, {cutoff = 3.5, type = 2})
local nl = dseams.core.neighListO(3.5, cloud, 2)

name

kind

role

read

function

suffix-dispatching loader

neighbors

function

cutoff neighbour list by atom ID

knn

function

k-nearest graph by atom ID

chill_plus

function

CHILL+ state names; no file

chill

function

CHILL state names; no file

cages

function

seeded HC/DDC per-atom flags

core

table

require("dseams_core"); compiled registrations

These seven names are the public surface. Locals in lua/dseams.lua (suffix, opts) are not exported. Option tables may be omitted. Defaults are those of lua/dseams.lua.

The engine CLI injects compiled names as globals. Library scripts call them on dseams.core.

Calling conventions#

PointCloud userdata#

Readers return a PointCloud userdata, not a table. The usertype is registered on the Lua state when dseams_core loads, so PointCloud.new() is a global after require. Workflow scripts pass that scratch object into the legacy readers.

member

kind

meaning

nop

field

particle count

currentFrame

field

frame index just read

box()

method

box lengths, 3-number table

boxLow()

method

box origin, 3-number table

iceTypes()

method

per-particle state name strings

Ice-state strings: cubic, hexagonal, water, interfacial, clathrate, interClathrate, reCubic, reHex, unclassified.

Tables vs userdata#

New-style compiled names take neighbour lists and ring lists by value. sol2 builds a C++ container from a plain Lua table of tables. Those names return sol::as_nested or sol::as_table, so the result is a Lua table.

Legacy names take C++ container references. They bind only container userdata (the object another C++ bind already put on the stack). A freshly written Lua table is not accepted.

style

examples

nList / rings in

result

new

neighListO, neighbourListByIndex, kNearestNeighbourList, ringNetwork, cageAffiliation, getCorrelPlus

Lua table

Lua table (or void / name table)

new, userdata out

getHbondNetwork, getHbondNetworkFromClouds

Lua table

C++ vector userdata

legacy

neighborList, bondNetworkByIndex, getPrimitiveRings, readFrame*, chillPlus_*, chill_*

userdata

userdata

sol2 does not apply C++ default arguments on a raw bind. Wrapped names spell optionals in Lua (sol::optional). Legacy names need every argument the bound C++ signature requires.

read(path[, opts])#

Suffix-dispatching loader. Returns a PointCloud.

suffix

backend

notes

.xyz

readXYZ

whole file; opts.frame unused

.con

readCon

errors if this build has no readcon

.pdb / .gro / .dcd

readChemfiles

errors if this build has no chemfiles; opts.type defaults to -1 (keep all)

other (LAMMPS dump)

readLammpsTrjO

opts.frame defaults to 1. If opts.type is nil, tries type 2 then type 1

opts.frame is the 1-based frame index (default 1). opts.type is the LAMMPS type ID to keep.

neighbors(cloud[, opts])#

Cutoff neighbour list by atom ID. Calls core.neighListO(opts.cutoff or 3.5, cloud, opts.type or 1). Returns a Lua table of rows (self ID first).

knn(cloud[, opts])#

k-nearest graph by atom ID. Calls core.kNearestNeighbourList.

  • opts.k defaults to 4

  • opts.cutoff (candidate cutoff) defaults to 5.0

  • opts.type defaults to 1

  • opts.mutual defaults to true; only the boolean false selects the union graph

chill_plus(cloud[, opts])#

Builds neighbors(cloud, opts), runs core.getCorrelPlus(cloud, nl, false), returns core.getIceTypePlusNoPrint(cloud, nl, false) (1-based array of state names). Does not write a file. Mutates cloud.

chill(cloud[, opts])#

Same pipeline with core.getCorrel and core.getIceTypeNoPrint. Mutates cloud. Does not write a file.

cages(cloud[, opts])#

Seeded HC/DDC membership. Builds mutual and union k-nearest graphs (opts.k 4, opts.cutoff 5.0, opts.type 1), converts each to an index list, keeps six-membered rings, and returns core.seededCageAffiliation(...): a table {hc = ..., ddc = ...} of per-atom flags.

core#

The table returned by require("dseams_core"). Every name from luaApi::registerAll (src/lua_api.cpp) lives here.

Usertypes (PointCloud, RingUpdater, AffiliationUpdater) are registered on the Lua state, not on this table. RingUpdater.new(6) works after require.

Signatures for every compiled name are in Compiled registrations.