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 |
|---|---|
|
|
|
|
|
|
|
|
|
histogram, labels, vertices, fraction |
|
|
|
0 Ih, 1 Ic, 2 stacking, -1 other |
|
|
|
count, |
|
key text and ring census |
|
dataclasses or arrays |
|
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