dseams and the C API#

Three packages call the same engine.

seams is the ctypes package in src/seams. It wraps seams-core’s include/seams.h. It is not in the wheel; put src on PYTHONPATH and set SEAMS_LIB. NumPy arrays go in and come back out. Results are frozen dataclasses. A failing call raises seams.SeamsError. status is the seams_status code and message is the Python copy of seams_handle_error.

dseams is the nanobind module over seams.h. It covers chill_plus, q4q6, neighbours, rings, and Frame. NumPy arrays are C-contiguous and are read in place. pydseamslib (import pydseams) is the trajectory package on PyPI. seams.from_pydseams(frame) copies frame.positions and frame.box into a System when an analysis lives only on the C API.

Set SEAMS_LIB to libseams.so (libseams.dylib on macOS). Importing seams does not load the library.

Quickstart#

seams#

import math

import numpy as np
from seams import PUBLISHED, System, set_num_threads

edge = 2.75 * 4.0 / math.sqrt(3.0)
fcc = ((0, 0, 0), (0.5, 0.5, 0), (0.5, 0, 0.5), (0, 0.5, 0.5))
basis = ((0, 0, 0), (0.25, 0.25, 0.25))
positions = np.array(
    [[(s + b) * edge for s, b in zip(shift, site)] for shift in fcc for site in basis]
)

set_num_threads(1)
with System() as sys:
    sys.set_ortho(positions, (edge, edge, edge))
    ice = sys.chill_plus(rule=PUBLISHED)
    order = sys.q4q6()
    print(int(ice.counts[0]), float(order.q6.mean()))
    assert int(ice.counts[0]) == 8
    assert abs(float(order.q6.mean()) - 0.628539) < 1e-6

examples/python/seams_ctypes_quick.py runs that cell. The program prints:

version 2.14.0
n 8
cubic 8
q6 0.628539
degree 4
six 0
fraction 0.0
cn 4.571429

Mean q6 is 0.628539 and each atom has four neighbours. This cell holds no primitive six-ring. It is thinner than twice the cutoff, so the cage census is refused and the script leaves that call out. A 2 by 2 by 2 supercell, which python_seams_ctypes also runs, has a six-ring fraction above 0.5. meson test python_seams_ctypes runs the pytest file and the doctests.

dseams#

The same eight sites through the nanobind module, in a box three cells wide so that the cage calls are not refused:

import math

import dseams
import numpy as np

edge = 2.75 * 4.0 / math.sqrt(3.0)
sites = (
    (0, 0, 0),
    (0.5, 0.5, 0),
    (0.5, 0, 0.5),
    (0, 0.5, 0.5),
    (0.25, 0.25, 0.25),
    (0.75, 0.75, 0.25),
    (0.75, 0.25, 0.75),
    (0.25, 0.75, 0.75),
)
positions = np.array([[x * edge, y * edge, z * edge] for x, y, z in sites])
box = (3 * edge, 3 * edge, 3 * edge)
labels, counts = dseams.chill_plus(positions, box)
q4, q6 = dseams.q4q6(positions, box)
offsets, cols = dseams.neighbours(positions, box)
sizes, symmetry, hist, fraction = dseams.rings(positions, box)
per_atom, (n_hex, n_cubic, n_water, n_both) = dseams.cages(positions, box)
n_cages, n_atoms = dseams.signature_cages(positions, box, spec="512")
shell = dseams.symmetry(positions, box)
assert len(labels) == 8 and int(counts.sum()) == 8
assert len(q4) == 8 and len(q6) == 8
assert len(offsets) == 9
assert n_hex + n_cubic + n_water + n_both == 8
assert (n_cages, n_atoms) == (0, 0)
assert len(shell) == 8

dseams.cages is the six-ring ice score from frames.cages: a per-atom code and the hexagonal, cubic, water, and both counts. dseams.signature_cages counts closed polyhedra whose ring census matches spec and returns (n_cages, n_atoms). dseams.symmetry is the shell label: 0 ice Ih, 1 ice Ic, 2 stacking-disordered, and -1 otherwise.

box is three lengths or nine LAMMPS numbers. dseams.PUBLISHED ("paper") averages q_lm over the four closest neighbours. dseams.OVITO ("ovito") averages q_lm over every neighbour inside the cutoff. dseams.CUTOFF and dseams.MUTUAL select the graph. dseams.set_num_threads and dseams.num_threads match the C calls. dseams.version is the library version. Frame.set_frame stores one cell. Frame.count is the number of points.

Ownership#

System, Neighbours, Rings, CageSet, Fingerprint, and Brine are context managers. close frees the handle. A second close does nothing. __del__ frees a handle that left the with block by an exception before close. Neighbour, ring, cage, fingerprint, and brine handles keep their own copies, so they stay valid after the System is closed. Neighbours.copy fills caller-owned NumPy arrays. seams_neighbours_csr is deprecated and is not wrapped.

Errors#

from seams import SeamsError, System

with System() as sys:
    try:
        sys.chill_plus()
    except SeamsError as err:
        print(err.status, err.message)
        assert err.status == 5

An empty frame raises status 5 (SEAMS_ERR_STATE). The message is the handle string. A box that is neither 3 nor 9 numbers raises ValueError before the library is called.

Analyses#

Call

Result

chill, chill_plus

ChillResult.labels, counts (length 9)

ql, steinhardt

OrderResult.ql, qlbar

q4q6, q6bar

Q4Q6, Q6Bar

neighbours, knn

Neighbours, then NeighbourCSR

rings

histogram, labels, vertices, fraction

cages, signature

CageCounts, Signature

symmetry

0 Ih, 1 Ic, 2 stacking, -1 other

rdf, running_cn, coordination

Radial, RunningCN, float

hbonds, density

count, Density

fingerprint

key text and ring census

contact_pairs, domains, prisms, monolayer, site_table

dataclasses or arrays

brine

fronts, rejection, profile, pockets

CUTOFF is 0, MUTUAL is 1, SEEDED is 2. PUBLISHED is 0, OVITO is 1. q4q6, q6bar, ql, and steinhardt keep their scratch per calling thread, so separate frames may run them in separate threads. set_num_threads is process-global.

Native reference#

Docstrings are numpydoc. sphinx.ext.napoleon and sphinx.ext.autodoc render seams when the package imports, the same split rgpot uses between the narrative page and the generated API. The generated page is the docstrings of src/seams. mypy --strict and pyright check src/seams. py.typed ships with the package. Doctests cover as_box9 and SeamsError.

The nanobind module and the language-binding examples stay below.

#!/usr/bin/env python3
# Copyright (c) d-SEAMS developers
"""Eight-atom cubic cell through the ctypes package."""

import math
import os
import sys

import numpy as np

from seams import PUBLISHED, System, set_num_threads, version


def diamond():
    a = 2.75 * 4.0 / math.sqrt(3.0)
    fcc = ((0, 0, 0), (0.5, 0.5, 0), (0.5, 0, 0.5), (0, 0.5, 0.5))
    basis = ((0, 0, 0), (0.25, 0.25, 0.25))
    xyz = [
        tuple((shift[i] + site[i]) * a for i in range(3))
        for shift in fcc
        for site in basis
    ]
    return np.asarray(xyz, dtype=np.float64), a


def main():
    if len(sys.argv) > 1:
        os.environ["SEAMS_LIB"] = sys.argv[1]
    pos, edge = diamond()
    set_num_threads(1)
    with System() as sys_handle:
        sys_handle.set_ortho(pos, (edge, edge, edge))
        ice = sys_handle.chill_plus(rule=PUBLISHED)
        order = sys_handle.q4q6()
        with sys_handle.neighbours() as nb:
            degree = int(np.diff(nb.copy().offsets).mean())
        with sys_handle.rings() as rings:
            six = int(rings.histogram(7)[6])
            fraction = rings.fraction(6)
        cn = sys_handle.coordination()
    print("version", version())
    print("n", pos.shape[0])
    print("cubic", int(ice.counts[0]))
    print("q6", round(float(order.q6.mean()), 6))
    print("degree", degree)
    print("six", six)
    print("fraction", round(fraction, 6))
    print("cn", round(cn, 6))


if __name__ == "__main__":
    main()

examples/python/core_counts.py is the Ice Ih and sII census. meson test docs_core_counts runs it. SEAMS_LIBDIR is the directory that holds libseams.so (libseams.dylib on macOS).

>>> import core_counts
>>> core_counts.check()
hexagonal 128
rings6 256
clathrate 136
rings5 144

examples/python/minimal_py.py reads input/traj/genice_sI.lammpstrj and calls the C API for neighbours, q6, CHILL+, and rings. meson test docs_minimal_python runs it.

#!/usr/bin/env python3
# Copyright (c) d-SEAMS developers
"""Read the GenIce sI cell, then neighbours, q6, CHILL+, and rings."""

import ctypes
import os
import sys


def read_dump(path):
    xyz = []
    edges = []
    reading = False
    with open(path) as handle:
        while True:
            line = handle.readline()
            if line == "":
                break
            if line.startswith("ITEM: BOX BOUNDS"):
                import sys
                from pathlib import Path

                root = Path(
                    os.environ.get(
                        "SEAMS_CORE_SRC",
                        Path(__file__).resolve().parents[2]
                        / "subprojects"
                        / "seams-core",
                    )
                )
                if str(root / "scripts") not in sys.path:
                    sys.path.insert(0, str(root / "scripts"))
                from lammps_box import cell_from_bounds

                rows = [handle.readline().split() for _ in range(3)]
                _origin, recovered, _tilts = cell_from_bounds(rows)
                edges.extend(recovered)
            elif line.startswith("ITEM: ATOMS"):
                reading = True
            elif reading:
                parts = line.split()
                if len(parts) < 5:
                    break
                xyz.extend(float(value) for value in parts[2:5])
    return xyz, edges


def main():
    path = sys.argv[1]
    libdir = sys.argv[2]
    xyz, edges = read_dump(path)
    n = len(xyz) // 3
    if n != 46:
        raise SystemExit(f"atom count {n}")
    name = "libseams.dylib" if sys.platform == "darwin" else "libseams.so"
    lib = ctypes.CDLL(os.path.join(libdir, name))
    lib.seams_version_string.restype = ctypes.c_char_p
    lib.seams_last_error.restype = ctypes.c_char_p
    lib.seams_set_num_threads.argtypes = [ctypes.c_int]
    lib.seams_set_num_threads.restype = ctypes.c_int
    lib.seams_system_create.restype = ctypes.c_void_p
    lib.seams_system_count.argtypes = [ctypes.c_void_p]
    lib.seams_system_count.restype = ctypes.c_int
    lib.seams_system_set_ortho.argtypes = [
        ctypes.c_void_p,
        ctypes.POINTER(ctypes.c_double),
        ctypes.c_int,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.c_void_p,
        ctypes.c_void_p,
    ]
    lib.seams_system_set_ortho.restype = ctypes.c_int
    lib.seams_neighbours_build.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_void_p),
    ]
    lib.seams_neighbours_build.restype = ctypes.c_int
    lib.seams_neighbours_count.argtypes = [ctypes.c_void_p]
    lib.seams_neighbours_count.restype = ctypes.c_int
    lib.seams_q4q6.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_double),
        ctypes.POINTER(ctypes.c_double),
    ]
    lib.seams_q4q6.restype = ctypes.c_int
    lib.seams_chill_plus.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_int),
        ctypes.POINTER(ctypes.c_int),
    ]
    lib.seams_chill_plus.restype = ctypes.c_int
    lib.seams_rings_find.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_void_p),
    ]
    lib.seams_rings_find.restype = ctypes.c_int
    lib.seams_rings_histogram.argtypes = [
        ctypes.c_void_p,
        ctypes.POINTER(ctypes.c_int),
        ctypes.c_int,
    ]
    lib.seams_rings_histogram.restype = ctypes.c_int
    lib.seams_rings_count.argtypes = [ctypes.c_void_p]
    lib.seams_rings_count.restype = ctypes.c_int
    lib.seams_neighbours_destroy.argtypes = [ctypes.c_void_p]
    lib.seams_rings_destroy.argtypes = [ctypes.c_void_p]
    lib.seams_system_destroy.argtypes = [ctypes.c_void_p]
    points = (ctypes.c_double * len(xyz))(*xyz)
    sys_handle = lib.seams_system_create()
    if lib.seams_set_num_threads(1) != 0:
        raise SystemExit("threads")
    if (
        lib.seams_system_set_ortho(
            sys_handle, points, n, 0, 0, 0, edges[0], edges[1], edges[2], None, None
        )
        != 0
    ):
        raise SystemExit("frame")
    nb = ctypes.c_void_p()
    if lib.seams_neighbours_build(sys_handle, 3.5, 0, 0, ctypes.byref(nb)) != 0:
        raise SystemExit("neighbours")
    if lib.seams_neighbours_count(nb) != 46:
        raise SystemExit("neighbour rows")
    lib.seams_neighbours_destroy(nb)
    q4 = (ctypes.c_double * n)()
    q6 = (ctypes.c_double * n)()
    if lib.seams_q4q6(sys_handle, 3.5, 0, q4, q6) != 0:
        raise SystemExit("q6")
    mean = sum(q6) / n
    labels = (ctypes.c_int * n)()
    counts = (ctypes.c_int * 9)()
    if lib.seams_chill_plus(sys_handle, 3.5, 0, 0, 0, labels, counts) != 0:
        raise SystemExit("chill+")
    rings = ctypes.c_void_p()
    if lib.seams_rings_find(sys_handle, 3.5, 0, 0, 6, ctypes.byref(rings)) != 0:
        raise SystemExit("rings")
    hist = (ctypes.c_int * 13)()
    if lib.seams_rings_histogram(rings, hist, 13) != 0:
        raise SystemExit("histogram")
    if counts[4] != 46 or hist[5] != 48 or hist[6] != 54 or mean <= 0.5:
        raise SystemExit("result")
    print(
        "python example ok",
        lib.seams_version_string().decode(),
        "rings",
        hist[5] + hist[6],
    )
    lib.seams_rings_destroy(rings)
    lib.seams_system_destroy(sys_handle)


if __name__ == "__main__":
    main()

dseams.from_ase(atoms) rotates an ASE cell into the LAMMPS frame and returns positions and the nine-number box. dseams.from_mdanalysis(universe) reads universe.dimensions (lengths and angles) and universe.atoms.positions.

# excerpt: src/dseams/__init__.py
def from_ase(atoms):
# excerpt: src/dseams/__init__.py
def from_mdanalysis(universe, select="all"):

python -m dseams labels one cubic cell.

cages, signature_cages, and symmetry load libseams_lang through frames.py. Set SEAMS_LANG_LIB to that shared library. The nanobind calls (chill_plus, q4q6, neighbours, rings, Frame) use libseams.

meson test docs_api_python runs the eight-atom program below. On that cell the ctypes path prints python call cubic 8, python call q6bar 0.628539361055, python call cages 0 0 8 0, python call cn 4.57142857143, python call hbond 0, python call sheet 0, and python call vert 4 0. The 512 signature on the sI guest frame prints python call sig 2 40. It calls dseams.chill_plus and dseams.q4q6 when the nanobind module imports. The ctypes fallback calls those two and also seams_system_read, seams_chill, seams_steinhardt, seams_cages, seams_signature_cages, seams_neighbours_knn, seams_rdf, seams_running_cn, seams_coordination, seams_hbonds, seams_density_axis, seams_fingerprint, seams_contact_pairs, seams_domains, seams_prisms, seams_monolayer, seams_rings_vertices, and seams_site_table. meson test python_dseams runs tests/dseams/test_dseams.py.

#!/usr/bin/env python3
# Copyright (c) d-SEAMS developers
"""Eight-atom CHILL+ and q4/q6 through dseams, or through libseams."""

import ctypes
import math
import os
import sys
from pathlib import Path


def diamond():
    a = 2.75 * 4.0 / math.sqrt(3.0)
    fcc = ((0, 0, 0), (0.5, 0.5, 0), (0.5, 0, 0.5), (0, 0.5, 0.5))
    basis = ((0, 0, 0), (0.25, 0.25, 0.25))
    xyz = []
    for shift in fcc:
        for site in basis:
            xyz.extend((shift[i] + site[i]) * a for i in range(3))
    return xyz, a


def via_dseams(xyz, edge):
    import numpy as np

    import dseams

    pos = np.asarray(xyz, dtype=np.float64).reshape(8, 3)
    box = np.asarray([edge, edge, edge], dtype=np.float64)
    dseams.set_num_threads(1)
    if dseams.num_threads() != 1:
        raise SystemExit("dseams thread width")
    labels, counts = dseams.chill_plus(pos, box)
    _q4, q6 = dseams.q4q6(pos, box)
    if int(counts[0]) != 8 or len(labels) != 8 or len(q6) != 8:
        raise SystemExit("dseams counts")
    if float(np.mean(q6)) <= 0.3:
        raise SystemExit("dseams q6")
    print("python api ok dseams", dseams.version())


def via_ctypes(libdir, xyz, edge):
    name = "libseams.dylib" if sys.platform == "darwin" else "libseams.so"
    lib = ctypes.CDLL(os.path.join(libdir, name))
    lib.seams_version_string.restype = ctypes.c_char_p
    lib.seams_set_num_threads.argtypes = [ctypes.c_int]
    lib.seams_set_num_threads.restype = ctypes.c_int
    lib.seams_get_num_threads.restype = ctypes.c_int
    lib.seams_system_create.restype = ctypes.c_void_p
    lib.seams_system_set_ortho.argtypes = [
        ctypes.c_void_p,
        ctypes.POINTER(ctypes.c_double),
        ctypes.c_int,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.c_void_p,
        ctypes.c_void_p,
    ]
    lib.seams_system_set_ortho.restype = ctypes.c_int
    lib.seams_chill_plus.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_int),
        ctypes.POINTER(ctypes.c_int),
    ]
    lib.seams_chill_plus.restype = ctypes.c_int
    lib.seams_q4q6.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_double),
        ctypes.POINTER(ctypes.c_double),
    ]
    lib.seams_q4q6.restype = ctypes.c_int
    lib.seams_system_destroy.argtypes = [ctypes.c_void_p]
    lib.seams_system_count.argtypes = [ctypes.c_void_p]
    lib.seams_system_count.restype = ctypes.c_int
    lib.seams_handle_error.argtypes = [ctypes.c_void_p]
    lib.seams_handle_error.restype = ctypes.c_char_p
    lib.seams_system_read.argtypes = [
        ctypes.c_void_p,
        ctypes.c_char_p,
        ctypes.c_int,
        ctypes.c_int,
    ]
    lib.seams_system_read.restype = ctypes.c_int
    lib.seams_chill.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_int),
        ctypes.c_size_t,
        ctypes.POINTER(ctypes.c_int),
    ]
    lib.seams_chill.restype = ctypes.c_int
    lib.seams_steinhardt.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_double),
        ctypes.c_size_t,
        ctypes.POINTER(ctypes.c_double),
        ctypes.c_size_t,
    ]
    lib.seams_steinhardt.restype = ctypes.c_int
    lib.seams_cages.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_void_p),
    ]
    lib.seams_cages.restype = ctypes.c_int
    lib.seams_cages_counts.argtypes = [ctypes.c_void_p] + [
        ctypes.POINTER(ctypes.c_int)
    ] * 4
    lib.seams_cages_counts.restype = ctypes.c_int
    lib.seams_cages_destroy.argtypes = [ctypes.c_void_p]
    lib.seams_signature_cages.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_char_p,
        ctypes.POINTER(ctypes.c_size_t),
        ctypes.POINTER(ctypes.c_size_t),
    ]
    lib.seams_signature_cages.restype = ctypes.c_int
    lib.seams_neighbours_knn.argtypes = [
        ctypes.c_void_p,
        ctypes.c_int,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_void_p),
    ]
    lib.seams_neighbours_knn.restype = ctypes.c_int
    lib.seams_neighbours_destroy.argtypes = [ctypes.c_void_p]
    lib.seams_rdf.restype = ctypes.c_int
    lib.seams_running_cn.restype = ctypes.c_int
    lib.seams_coordination.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_double),
    ]
    lib.seams_coordination.restype = ctypes.c_int
    lib.seams_hbonds.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_double,
        ctypes.c_double,
        ctypes.POINTER(ctypes.c_int),
    ]
    lib.seams_hbonds.restype = ctypes.c_int
    lib.seams_density_axis.restype = ctypes.c_int
    lib.seams_fingerprint.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_void_p),
    ]
    lib.seams_fingerprint.restype = ctypes.c_int
    lib.seams_fingerprint_destroy.argtypes = [ctypes.c_void_p]
    lib.seams_fingerprint_key.argtypes = [
        ctypes.c_void_p,
        ctypes.c_void_p,
        ctypes.c_size_t,
        ctypes.POINTER(ctypes.c_size_t),
    ]
    lib.seams_fingerprint_key.restype = ctypes.c_int
    lib.seams_contact_pairs.argtypes = [
        ctypes.c_void_p,
        ctypes.c_char_p,
        ctypes.POINTER(ctypes.c_size_t),
        ctypes.POINTER(ctypes.c_int),
        ctypes.POINTER(ctypes.c_int),
    ]
    lib.seams_contact_pairs.restype = ctypes.c_int
    lib.seams_domains.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_char_p,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_int),
        ctypes.POINTER(ctypes.c_int),
        ctypes.POINTER(ctypes.c_double),
    ]
    lib.seams_domains.restype = ctypes.c_int
    lib.seams_prisms.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_int),
        ctypes.POINTER(ctypes.c_int),
        ctypes.c_size_t,
    ]
    lib.seams_prisms.restype = ctypes.c_int
    lib.seams_monolayer.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_double,
        ctypes.POINTER(ctypes.c_int),
        ctypes.c_size_t,
    ]
    lib.seams_monolayer.restype = ctypes.c_int
    lib.seams_rings_find.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_void_p),
    ]
    lib.seams_rings_find.restype = ctypes.c_int
    lib.seams_rings_destroy.argtypes = [ctypes.c_void_p]
    lib.seams_rings_vertices.argtypes = [
        ctypes.c_void_p,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_int),
        ctypes.c_size_t,
        ctypes.POINTER(ctypes.c_size_t),
    ]
    lib.seams_rings_vertices.restype = ctypes.c_int
    lib.seams_site_table.argtypes = [
        ctypes.c_void_p,
        ctypes.c_char_p,
        ctypes.POINTER(ctypes.c_int),
        ctypes.c_size_t,
    ]
    lib.seams_site_table.restype = ctypes.c_int
    if lib.seams_set_num_threads(1) != 0 or lib.seams_get_num_threads() != 1:
        raise SystemExit("ctypes thread width")
    points = (ctypes.c_double * len(xyz))(*xyz)
    labels = (ctypes.c_int * 8)()
    counts = (ctypes.c_int * 9)()
    q4 = (ctypes.c_double * 8)()
    q6 = (ctypes.c_double * 8)()
    sys_handle = lib.seams_system_create()
    if (
        lib.seams_system_set_ortho(
            sys_handle, points, 8, 0, 0, 0, edge, edge, edge, None, None
        )
        != 0
    ):
        raise SystemExit("ctypes frame")
    if lib.seams_chill_plus(sys_handle, 3.5, 0, 0, 0, labels, counts) != 0:
        raise SystemExit("ctypes chill+")
    if lib.seams_q4q6(sys_handle, 3.5, 0, q4, q6) != 0:
        raise SystemExit("ctypes q4q6")
    mean = sum(q6) / 8.0
    if counts[0] != 8 or mean <= 0.3:
        raise SystemExit("ctypes result")
    exercise(lib, sys_handle)
    lib.seams_system_destroy(sys_handle)
    root = Path(
        os.environ.get(
            "SEAMS_CORE_SRC",
            Path(__file__).resolve().parents[2] / "subprojects" / "seams-core",
        )
    )
    expect = {
        "input/traj/ice1h.lammpstrj": (128, -1),
        "input/traj/genice_sI.lammpstrj": (46, 1),
        "input/xyz/configuration.xyz": (256, -1),
        "input/eon/tiny_multi_cuh2.con": (None, -1),
        "input/traj/genice_sH.lammpstrj": (136, 1),
    }
    for rel, (count, filt) in expect.items():
        got = read_count(lib, str(root / rel), filt)
        if count is not None and got != count:
            raise SystemExit(f"ctypes read {rel} {got}")
        if got <= 0:
            raise SystemExit(f"ctypes read empty {rel}")
    guest = lib.seams_system_create()
    guest_path = str(root / "input/traj/genice_sI.lammpstrj").encode()
    if lib.seams_system_read(guest, guest_path, 1, 1) != 0:
        fail(lib, guest, "sI")
    n_cages = ctypes.c_size_t()
    n_atoms = ctypes.c_size_t()
    if lib.seams_signature_cages(guest, 3.5, 0, 0, b"512", n_cages, n_atoms) != 0:
        fail(lib, guest, "signature")
    if n_cages.value != 2 or n_atoms.value != 40:
        raise SystemExit(f"ctypes signature {n_cages.value} {n_atoms.value}")
    print(f"python call sig {n_cages.value} {n_atoms.value}")
    lib.seams_system_destroy(guest)
    print("python api ok ctypes", lib.seams_version_string().decode())


def fail(lib, handle, label):
    text = lib.seams_handle_error(handle)
    detail = text.decode() if text else ""
    raise SystemExit(f"ctypes {label} {detail}")


def exercise(lib, sys_handle):
    labels = (ctypes.c_int * 8)()
    counts = (ctypes.c_int * 9)()
    if lib.seams_chill(sys_handle, 3.5, 0, 0, 0, labels, 8, counts) != 0:
        fail(lib, sys_handle, "chill")
    ql = (ctypes.c_double * 8)()
    bar = (ctypes.c_double * 8)()
    if lib.seams_steinhardt(sys_handle, 3.5, 0, 6, ql, 8, bar, 8) != 0:
        fail(lib, sys_handle, "steinhardt")
    if sum(bar) / 8.0 <= 0.0:
        raise SystemExit("ctypes lechner-dellago")
    print(f"python call q6bar {sum(bar) / 8.0:.12g}")
    print(f"python call cubic {counts[0]}")
    cages = ctypes.c_void_p()
    if lib.seams_cages(sys_handle, 3.5, 0, 2, 4, 0, ctypes.byref(cages)) != 0:
        fail(lib, sys_handle, "cages")
    n_hex = ctypes.c_int()
    n_cubic = ctypes.c_int()
    n_water = ctypes.c_int()
    n_both = ctypes.c_int()
    if lib.seams_cages_counts(cages, n_hex, n_cubic, n_water, n_both) != 0:
        fail(lib, cages, "cage counts")
    print(
        f"python call cages {n_hex.value} {n_cubic.value} {n_water.value} {n_both.value}"
    )
    lib.seams_cages_destroy(cages)
    knn = ctypes.c_void_p()
    if lib.seams_neighbours_knn(sys_handle, 4, 3.5, 0, 1, ctypes.byref(knn)) != 0:
        fail(lib, sys_handle, "knn")
    lib.seams_neighbours_destroy(knn)
    cn = ctypes.c_double()
    if lib.seams_coordination(sys_handle, 3.5, 8, 0, 0, cn) != 0:
        fail(lib, sys_handle, "coordination")
    print(f"python call cn {cn.value:.12g}")
    n_bonds = ctypes.c_int()
    if lib.seams_hbonds(sys_handle, 3.5, 1, 2, 2.42, 30.0, n_bonds) != 0:
        fail(lib, sys_handle, "hbonds")
    print(f"python call hbond {n_bonds.value}")
    n_out = ctypes.c_size_t()
    r = (ctypes.c_double * 16)()
    g = (ctypes.c_double * 16)()
    lib.seams_rdf.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_double),
        ctypes.POINTER(ctypes.c_double),
        ctypes.c_void_p,
        ctypes.c_size_t,
        ctypes.POINTER(ctypes.c_size_t),
        ctypes.POINTER(ctypes.c_double),
    ]
    volume = ctypes.c_double()
    if lib.seams_rdf(sys_handle, 6.0, 8, 0, 0, r, g, None, 16, n_out, volume) != 0:
        fail(lib, sys_handle, "rdf")
    lib.seams_running_cn.argtypes = [
        ctypes.c_void_p,
        ctypes.c_double,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_double),
        ctypes.POINTER(ctypes.c_double),
        ctypes.c_size_t,
        ctypes.POINTER(ctypes.c_size_t),
    ]
    if lib.seams_running_cn(sys_handle, 6.0, 8, 0, 0, r, g, 16, n_out) != 0:
        fail(lib, sys_handle, "running_cn")
    z = (ctypes.c_double * 8)()
    rho = (ctypes.c_double * 8)()
    lib.seams_density_axis.argtypes = [
        ctypes.c_void_p,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.c_int,
        ctypes.POINTER(ctypes.c_double),
        ctypes.POINTER(ctypes.c_double),
        ctypes.c_size_t,
        ctypes.POINTER(ctypes.c_size_t),
    ]
    if lib.seams_density_axis(sys_handle, 0, 4, 2, z, rho, 8, n_out) != 0:
        fail(lib, sys_handle, "density")
    fp = ctypes.c_void_p()
    if lib.seams_fingerprint(sys_handle, 3.5, 0, 4, 0, 2, 0, ctypes.byref(fp)) != 0:
        fail(lib, sys_handle, "fingerprint")
    if lib.seams_fingerprint_key(fp, None, 0, n_out) != 0 or n_out.value <= 0:
        fail(lib, fp, "fingerprint key")
    lib.seams_fingerprint_destroy(fp)
    n_pairs = ctypes.c_size_t()
    n_cation = ctypes.c_int()
    n_anion = ctypes.c_int()
    if (
        lib.seams_contact_pairs(sys_handle, b"1=cationHead", n_pairs, n_cation, n_anion)
        != 0
    ):
        fail(lib, sys_handle, "pairs")
    n_subset = ctypes.c_int()
    largest = ctypes.c_int()
    percolation = ctypes.c_double()
    if (
        lib.seams_domains(
            sys_handle, 3.5, b"1=waterO", 0, n_subset, largest, percolation
        )
        != 0
    ):
        fail(lib, sys_handle, "domains")
    perfect = (ctypes.c_int * 7)()
    imperfect = (ctypes.c_int * 7)()
    if lib.seams_prisms(sys_handle, 3.5, 0, perfect, imperfect, 7) != 0:
        fail(lib, sys_handle, "prisms")
    sheet = (ctypes.c_int * 7)()
    if lib.seams_monolayer(sys_handle, 3.5, 0, 6, 100.0, sheet, 7) != 0:
        fail(lib, sys_handle, "monolayer")
    print(f"python call sheet {sheet[6]}")
    rings = ctypes.c_void_p()
    if lib.seams_rings_find(sys_handle, 3.5, 0, 0, 6, ctypes.byref(rings)) != 0:
        fail(lib, sys_handle, "rings")
    atoms = (ctypes.c_int * 12)()
    if lib.seams_rings_vertices(rings, 0, atoms, 12, n_out) != 0 or n_out.value <= 0:
        fail(lib, rings, "vertices")
    print(f"python call vert {n_out.value} {atoms[0]}")
    lib.seams_rings_destroy(rings)
    kinds = (ctypes.c_int * 8)()
    if lib.seams_site_table(sys_handle, b"1=waterO", kinds, 8) != 0:
        fail(lib, sys_handle, "site")


def read_count(lib, path, type_filter):
    handle = lib.seams_system_create()
    code = lib.seams_system_read(handle, path.encode(), 1, type_filter)
    if code != 0:
        fail(lib, handle, path)
    count = lib.seams_system_count(handle)
    lib.seams_system_destroy(handle)
    return count


def main():
    xyz, edge = diamond()
    loaded = False
    try:
        via_dseams(xyz, edge)
        loaded = True
    except ImportError:
        loaded = False
    if len(sys.argv) >= 2:
        via_ctypes(sys.argv[1], xyz, edge)
    elif not loaded:
        raise SystemExit("pass the directory that holds libseams")


if __name__ == "__main__":
    main()
        dseams.set_num_threads(1)
        self.assertEqual(dseams.num_threads(), 1)
        self.assertTrue(dseams.version())
        frame = dseams.Frame()
        frame.set_frame(pos, (length, length, length))
        self.assertEqual(frame.count(), pos.shape[0])
        self.assertTrue(np.all(frame.chill_plus()[0] == 0))
        fq4, fq6 = frame.q4q6()
        self.assertEqual(fq4.shape, (pos.shape[0],))
        self.assertGreater(float(fq6.mean()), 0.3)
        foff, fcols = frame.neighbours()
        self.assertEqual(foff.shape[0], pos.shape[0] + 1)
        self.assertEqual(fcols.shape[0], int(np.diff(foff).sum()))
        fsizes, fsym, fhist, ffrac = frame.rings()
        self.assertGreater(int(fhist[6]), 0)
        self.assertEqual(fsym.shape, fsizes.shape)
        self.assertGreater(ffrac, 0.5)
        for rule in (PUBLISHED, OVITO, "paper", "ovito"):
            labels, counts = dseams.chill_plus(pos, (length, length, length), rule=rule)
            self.assertEqual(labels.shape, (pos.shape[0],))
            self.assertTrue(np.all(labels == 0))
            self.assertEqual(int(counts[0]), pos.shape[0])
        dseams.set_num_threads(1)
        paper1, _ = dseams.chill_plus(pos, (length, length, length), rule="paper")
        ovito1, _ = dseams.chill_plus(pos, (length, length, length), rule="ovito")
        dseams.set_num_threads(8)
        paper8, _ = dseams.chill_plus(pos, (length, length, length), rule="paper")
        ovito8, _ = dseams.chill_plus(pos, (length, length, length), rule="ovito")
        self.assertTrue(np.array_equal(paper1, paper8))
        self.assertTrue(np.array_equal(ovito1, ovito8))
        q4, q6 = dseams.q4q6(pos, (length, length, length))
        self.assertGreater(float(q6.mean()), 0.3)
        self.assertTrue(np.all(np.isfinite(q4)))
        offsets, cols = dseams.neighbours(pos, (length, length, length), graph=CUTOFF)
        self.assertEqual(int(np.sum(sizes == 6)), int(hist[6]))
        self.assertGreater(fraction, 0.5)
        self.assertEqual(sym.shape, sizes.shape)

    def test_ase_and_mdanalysis(self):
        pos, length = diamond()
        if Atoms is None:
            self.skipTest("ASE is not installed")
        atoms = Atoms(
            symbols=["O"] * len(pos),
            positions=pos,
            cell=[length, length, length],
            pbc=True,
        )

Symbol reference#

CUTOFF#

Purpose: Graph id of the cutoff neighbour list.

Parameters: none

Returns: The integer code.

Ownership: No allocation.

Errors: None.

Units: dimensionless

Example: examples/python/minimal_py.py

Frame#

Purpose: One stored cell and the classifiers that read it.

Parameters: none

Returns: A Frame object.

Ownership: The object owns its seams_system and frees it when the object is destroyed.

Errors: None on construction. Later methods raise RuntimeError with seams_last_error text.

Units: object

Example: examples/python/minimal_py.py

Frame.chill_plus#

Purpose: CHILL+ labels and the nine population counts for the atoms on a dseams.Frame.

Parameters: self; cutoff; graph; rule

Returns: A pair of NumPy arrays, labels and counts.

Ownership: The caller owns the returned arrays. The frame still owns the seams_system.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: examples/python/minimal_py.py

Frame.count#

Purpose: Return the number of points stored on a dseams.Frame.

Parameters: self

Returns: The atom count.

Ownership: No allocation.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: examples/python/minimal_py.py

Frame.neighbours#

Purpose: CSR neighbour list of a dseams.Frame, self entries omitted.

Parameters: self; cutoff; graph

Returns: A pair of NumPy arrays, offsets and columns.

Ownership: The caller owns the returned arrays. The temporary C neighbour list is freed inside the call.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: examples/python/minimal_py.py

Frame.q4q6#

Purpose: Local q4 and q6 on the cutoff shell of a dseams.Frame.

Parameters: self; cutoff

Returns: A pair of NumPy arrays, q4 and q6.

Ownership: The caller owns the returned arrays.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: examples/python/minimal_py.py

Frame.rings#

Purpose: Ring sizes, symmetry labels, a size histogram, and the six-ring fraction.

Parameters: self; cutoff; max_depth

Returns: Sizes, symmetry, histogram, and the six-ring fraction.

Ownership: The caller owns the returned arrays. The C ring set is freed inside the call.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: examples/python/minimal_py.py

Frame.set_frame#

Purpose: Store positions and a cell on a dseams.Frame.

Parameters: positions; box

Returns: Nothing.

Ownership: The frame copies the coordinates into the seams_system it owns.

Errors: ValueError when box is not 3 lengths or 9 LAMMPS numbers. RuntimeError with seams_last_error text when the C call fails.

Units: coordinates and cutoff in angstrom

Example: examples/python/minimal_py.py

MUTUAL#

Purpose: Graph id of the mutual neighbour list.

Parameters: none

Returns: The integer code.

Ownership: No allocation.

Errors: None.

Units: dimensionless

Example: examples/python/minimal_py.py

OVITO#

Purpose: CHILL+ definition that averages q_lm over every neighbour inside the cutoff.

Parameters: none

Returns: The integer code.

Ownership: No allocation.

Errors: None.

Units: dimensionless

Example: examples/python/minimal_py.py

PUBLISHED#

Purpose: CHILL+ definition that averages q_lm over the four closest neighbours.

Parameters: none

Returns: The integer code.

Ownership: No allocation.

Errors: None.

Units: dimensionless

Example: examples/python/minimal_py.py

cages#

Purpose: Score hexagonal and double-diamond cage membership.

Parameters: positions; box; or a Frame

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: coordinates and cutoff in angstrom; counts are dimensionless

Example: examples/python/minimal_py.py

chill_plus#

Purpose: Label each atom with CHILL+.

Parameters: positions; box; rule; graph; cutoff

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: coordinates and cutoff in angstrom

Example: examples/python/minimal_py.py

count#

Purpose: Number of points stored on a Frame.

Parameters: frame

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: dimensionless count

Example: examples/python/minimal_py.py

from_ase#

Purpose: Turn an ASE atoms object into positions and a LAMMPS cell.

Parameters: atoms

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: positions and box lengths in angstrom

Example: examples/python/minimal_py.py

from_mdanalysis#

Purpose: Turn an MDAnalysis universe into positions and a LAMMPS cell.

Parameters: universe; select

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: positions in angstrom; angles inside the universe are degrees

Example: examples/python/minimal_py.py

neighbours#

Purpose: Cutoff or mutual neighbour list as CSR.

Parameters: positions; box; cutoff; graph

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: coordinates and cutoff in angstrom

Example: examples/python/minimal_py.py

num_threads#

Purpose: OpenMP width the next call will use.

Parameters: none

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: dimensionless thread count

Example: examples/python/minimal_py.py

q4q6#

Purpose: Local q4 and q6 on the cutoff shell.

Parameters: positions; box; cutoff

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: coordinates and cutoff in angstrom; q4 and q6 are dimensionless

Example: examples/python/minimal_py.py

rings#

Purpose: Primitive-ring sizes, symmetry, histogram, and fraction.

Parameters: positions; box; cutoff; max_depth

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: coordinates and cutoff in angstrom; max_depth is a dimensionless ring size

Example: examples/python/minimal_py.py

set_frame#

Purpose: Store one cell on a Frame.

Parameters: frame; positions; box

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: coordinates and cutoff in angstrom

Example: examples/python/minimal_py.py

set_num_threads#

Purpose: Set the OpenMP width for the next call.

Parameters: n

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: dimensionless thread count; 0 restores the library default

Example: examples/python/minimal_py.py

signature_cages#

Purpose: Count closed cages matching a ring-census spec.

Parameters: positions; box; spec

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: coordinates and cutoff in angstrom; spec is text such as 512

Example: examples/python/minimal_py.py

symmetry#

Purpose: Shell label for Ih, Ic, stacking disorder, or other.

Parameters: positions; box

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: coordinates and cutoff in angstrom; labels are dimensionless codes

Example: examples/python/minimal_py.py

userframe.CageScore#

Purpose: Boolean membership of the hexagonal and double-diamond cages.

Parameters: hc; ddc

Returns: A CageScore.

Ownership: The caller owns the object.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.CageScore.n_both#

Purpose: Number of atoms in both cages.

Parameters: self

Returns: The count.

Ownership: No allocation.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.CageScore.n_ic#

Purpose: Number of atoms in the double-diamond cage.

Parameters: self

Returns: The count.

Ownership: No allocation.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.CageScore.n_ih#

Purpose: Number of atoms in the hexagonal cage.

Parameters: self

Returns: The count.

Ownership: No allocation.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.CageScore.n_water#

Purpose: Number of atoms in neither cage.

Parameters: self

Returns: The count.

Ownership: No allocation.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame#

Purpose: One configuration whose classifiers call libseams_lang.

Parameters: ptr; symbols; cutoff

Returns: A Frame.

Ownership: The object owns the seams_frame pointer. close() or deletion calls seams_frame_free.

Errors: RuntimeError when ptr is null.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.box#

Purpose: Cell stored on the frame.

Parameters: self

Returns: Three edge lengths, or nine LAMMPS numbers when a tilt is set.

Ownership: The caller owns the returned array.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.cages#

Purpose: Hexagonal and double-diamond membership from seams_frame_cages.

Parameters: self; seeded; k; ring_adjacent

Returns: A CageScore.

Ownership: The caller owns the score. The frame keeps the same object.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.cages_by_signature#

Purpose: Closed cages of one ring census.

Parameters: self; signature; max_ring_size; edge

Returns: A list whose length is the cage count. n_atoms is the vertex count.

Ownership: The caller owns the list. The C call does not return one vertex list per cage.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.chill_plus#

Purpose: Published CHILL+ histogram for this frame.

Parameters: self; graph

Returns: An IceCounts mapping of label name to population.

Ownership: The caller owns the dictionary. Labels are also stored on the frame.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.close#

Purpose: Free the libseams_lang frame.

Parameters: self

Returns: Nothing.

Ownership: Frees the pointer this Frame owns. A second call is a no-op.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.find_prisms#

Purpose: Prism census from seams_frame_prisms.

Parameters: self; output_dir; max_depth; shape_matching

Returns: A list of size, perfect, and imperfect rows.

Ownership: The caller owns the list.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.monolayer_rings#

Purpose: Quasi-2D ring counts from seams_frame_monolayer.

Parameters: self; output_dir; sheet_area; max_depth

Returns: A dictionary of size to count and coverage.

Ownership: The caller owns the dictionary. The call writes topoMonolayer under output_dir.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.n_atoms#

Purpose: Number of atoms on the frame.

Parameters: self

Returns: The count from seams_frame_nop.

Ownership: No allocation.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.positions#

Purpose: Copy of the coordinates stored on the frame.

Parameters: self

Returns: An (n, 3) NumPy array in angstrom.

Ownership: The caller owns the copy. The frame keeps its own buffer.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.rdf_2d#

Purpose: In-plane g(r) from seams_frame_rdf2d.

Parameters: self; output_dir; cutoff; binwidth

Returns: Radius and g(r) lists.

Ownership: The caller owns the lists. The call also writes under output_dir.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.ring_census#

Purpose: Primitive rings by size from seams_frame_rings.

Parameters: self; max_size

Returns: A dictionary of size to count, empty sizes omitted.

Ownership: The caller owns the dictionary.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.steinhardt#

Purpose: Local q_l and the Lechner-Dellago average from seams_frame_steinhardt.

Parameters: self; order_l

Returns: A dictionary with ql and ql_bar lists.

Ownership: The caller owns the dictionary.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.to_ase#

Purpose: ASE Atoms for this frame.

Parameters: self

Returns: An ASE Atoms object. Ice labels and cage flags are arrays when those calls have run.

Ownership: The caller owns the Atoms object.

Errors: ImportError when ASE is not installed.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.Frame.to_solvis#

Purpose: Solvis System built from to_ase.

Parameters: self; expand_box

Returns: A solvis System.

Ownership: The caller owns the System.

Errors: ImportError when solvis-tools is not installed.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.IceCounts#

Purpose: CHILL+ population counts keyed by label name.

Parameters: mapping of name to count

Returns: An IceCounts dictionary.

Ownership: The caller owns the dictionary.

Errors: None.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.from_ase#

Purpose: Frame for one ASE species. Coordinates go through seams_frame_from_arrays.

Parameters: atoms; select; cutoff; bonded

Returns: A userframe.Frame.

Ownership: The caller owns the Frame.

Errors: TypeError when atoms has no positions. ValueError when the selection matches nothing.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.read#

Purpose: Read one frame with seams_frame_read. pydseams.read is this function.

Parameters: filename; frame; atom_type; all_atoms

Returns: A userframe.Frame.

Ownership: The caller owns the Frame and frees it with close() or by dropping it.

Errors: RuntimeError whose text is seams_last_error.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

userframe.to_solvis#

Purpose: Call to_solvis on a frame.

Parameters: frame; expand_box

Returns: The solvis System returned by the frame.

Ownership: The caller owns the System.

Errors: ImportError when solvis-tools is not installed.

Units: coordinates and cutoff in angstrom

Example: docs/orgmode/reference/python-frame.org

version#

Purpose: Library version text.

Parameters: none

Returns: The arrays or counts named in the purpose. NumPy arrays are owned by the caller.

Ownership: A Frame owns its seams_system and frees it on destruction. Input arrays are read in place when they are already C-contiguous.

Errors: RuntimeError with seams_last_error text. ValueError when a box is not 3 lengths or 9 LAMMPS numbers.

Units: text

Example: examples/python/minimal_py.py