dseams tutorial#

The nanobind module reads a C-contiguous NumPy array in place. This is the eight-atom diamond cell (nearest-neighbour spacing 2.75 Å). Every oxygen is cubic.

meson test python_dseams runs this method. On the eight-atom cell counts[0] equals the atom count and every label is 0. examples/python/core_counts.py checks Ice Ih and sII through libseams. meson test docs_core_counts runs it.

    def test_both_rules_and_order(self):
        pos, length = diamond()
        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])

An ASE Atoms or an MDAnalysis universe becomes the same arrays:

import ase.io
import dseams

atoms = ase.io.read("tests/data/exampleTraj.lammpstrj", format="lammps-dump-text")
pos, box = dseams.from_ase(atoms)


class _Universe:
    def __init__(self, positions, dimensions):
        self.positions = positions
        self.dimensions = dimensions
        self.atoms = self

    def select_atoms(self, selection):
        return self


universe = _Universe(atoms.get_positions(), atoms.cell.cellpar())
pos, box = dseams.from_mdanalysis(universe)
labels, counts = dseams.chill_plus(pos, box, rule=dseams.OVITO)
assert len(labels) == len(atoms)
assert int(counts.sum()) == len(atoms)
python -m unittest -v tests/dseams/test_dseams.py
python -m dseams

The verbose run reports three cases: both CHILL+ rules with q4/q6 and rings, ASE and MDAnalysis frames, and a triclinic cell.

The rest of the call set#

examples/python/python_api.py is the program meson test docs_api_python runs. When the nanobind module is absent it calls libseams through ctypes. On the eight-atom cell that program prints:

python call q6bar 0.628539361055
python call cubic 8
python call cages 0 0 8 0
python call cn 4.57142857143
python call hbond 0
python call sheet 0
python call vert 4 0

q6bar is seams_steinhardt with the Lechner-Dellago buffer. cages is seams_cages (n_hex, n_cubic, n_water, n_both). cn is seams_coordination. hbond is seams_hbonds. sheet is the six-ring bin of seams_monolayer. vert is the first ring from seams_rings_vertices. The same run also calls seams_rdf, seams_running_cn, seams_density_axis, seams_fingerprint, seams_contact_pairs, seams_domains, seams_prisms, seams_neighbours_knn, and seams_site_table. On input/traj/genice_sI.lammpstrj the 512 signature prints:

python call sig 2 40