Use a language binding

This repository builds the engine, the C API libseams (include/seams.h), the C ABI libseams_lang (bindings/cxx/seams_lang.h), and the seams command.

C and C++ document those libraries.

Every other language is its own repository, with its own documentation, tests, and releases. A binding’s version is the seams-core version it was built against. The Python release for this engine is pydseamslib 2.14.0. Each repository’s README has the install command.

Languages

Language

Repository

Package

Links

Python

d-SEAMS/PydSEAMSlib

pydseamslib

libseams, libseams_lang

Lua, Fennel

d-SEAMS/yodaStruct

Git source, require("dseams")

libseams

R

d-SEAMS/dseams-r

dseams

libseams_lang

Julia

d-SEAMS/Dseams.jl

Dseams, engine from libseams_jll

libseams_lang, libseams

Rust

d-SEAMS/dseams-rs

crates dseams-sys, dseams

libseams

Fortran

d-SEAMS/dseams-fortran

fpm Git dependency dseams

libseams

import dseams is the array API over libseams: dseams.Frame, chill_plus, q4q6, neighbours, rings, and from_ase. import pydseams and import pydseamslib are the trajectory package. pydseams.read opens a dump. dseams.userframe is the Frame over libseams_lang, documented on the Python Frame page. Dseams calls libseams_lang for a frame and libseams for the re-exported seams_* functions. libseams_jll supplies the engine binary. The same repository includes Seams, an example of the libseams C API. The R package compiles the engine it ships, and the calls in its README use libseams_lang.

Ice Ih

input/traj/ice1h.lammpstrj is one orthorhombic frame of ice Ih: 128 oxygens, every atom LAMMPS type 1. The path is relative to a seams-core checkout. dseams.Frame stores the coordinates and the three edge lengths. Published CHILL+ labels every oxygen hexagonal, so counts[1] is 128. The ring histogram holds 256 six-rings, so histogram[6] is 256. The mean local q6 at 3.5 Å is 0.625855. The cutoff neighbour list holds 512 directed pairs, four per oxygen, so offsets[-1] is 512.

>>> import numpy as np
>>> import dseams
>>> def ice():
...     xyz, edges, reading = [], [], False
...     handle = open("input/traj/ice1h.lammpstrj")
...     try:
...         while True:
...             line = handle.readline()
...             if line == "":
...                 break
...             if line.startswith("ITEM: BOX BOUNDS"):
...                 edges = []
...                 for _ in range(3):
...                     lo, hi = handle.readline().split()[:2]
...                     edges.append(float(hi) - float(lo))
...             elif line.startswith("ITEM: ATOMS"):
...                 reading = True
...             elif reading:
...                 parts = line.split()
...                 if len(parts) < 5:
...                     break
...                 xyz.append([float(v) for v in parts[2:5]])
...     finally:
...         handle.close()
...     return xyz, edges
>>> xyz, edges = ice()
>>> len(xyz)
128
>>> frame = dseams.Frame()
>>> frame.set_frame(np.asarray(xyz), np.asarray(edges))
>>> frame.count()
128
>>> offsets, columns = frame.neighbours(3.5)
>>> int(offsets[-1])
512
>>> sizes, symmetry, histogram, fraction = frame.rings(3.5, 6)
>>> int(histogram[6])
256
>>> q4, q6 = frame.q4q6(3.5)
>>> round(float(q6.mean()), 6)
0.625855
>>> labels, counts = frame.chill_plus()
>>> int(counts[1])
128

These four commands print that census. seams rings prints two lines, and the other three commands print one line each. seams steinhardt also prints the Lechner-Dellago q6-bar. seams cn with this cutoff and type prints nI 128, the number of atoms in the coordination sum.

seams read input/traj/ice1h.lammpstrj
seams rings input/traj/ice1h.lammpstrj --cutoff 3.5 --type 1
seams steinhardt input/traj/ice1h.lammpstrj --cutoff 3.5 --l 6 --type 1
seams chill-plus input/traj/ice1h.lammpstrj --cutoff 3.5 --type 1
nop 128 frame 1 box 15.6457 14.7071 18.073
nop 128 rings 256
6 256
nop 128 q6 0.625855 q6bar 0.562449
nop 128 hexagonal 128

dseams.from_ase returns positions and a nine-number LAMMPS cell for set_frame. The Python Frame page runs that round trip on this file.

What the bindings share

The classifiers run in the engine, and every binding calls those functions. seams_q4q6 in include/seams.h and seams_frame_q4_q6 in bindings/cxx/seams_lang.h compute cutoff-shell q4 and q6. seams steinhardt prints the local mean and the Lechner-Dellago average for each degree named by --l. The default is 4,6. The accepted degrees are 3, 4, 6, 8, and 12. Degrees 3 and 12 are the Zeron hydrate pair. Local q4 and q6 is that command.

Recordings

Each binding below has a short screencast. The full set is on the videos page.

C

C++

Fortran

Python

Rust

Julia

R

Lua and Fennel