API reference#

Napoleon autodoc of the Python helpers. Human lookup of Frame, IceCounts, CageScore, DensityProfile, ContactPairs, DomainStats, read(), pydseams.features, and ASE is the Python surface page.

The public constructors live on the pydseams package: from_ase(), from_arrays(), from_xyz(), from_chemfiles(), from_con(), to_solvis(). to_ase() is the inverse of from_ase().

The compiled extension is nanobind pydseams.yoda. _core and cyoda are aliases of yoda. Trajectory is an alias of Frame.

Classification (chill_plus(), cages()) does not write files. Prism, monolayer, and rdf_2d() do. rdf() does not.

d-SEAMS Python front end.

pydseams is the package. The compiled nanobind module is pydseams.yoda. Helpers (Frame, read(), ASE, solvis) sit on that surface. _core and cyoda are aliases of yoda. Trajectory is an alias of Frame.

Load a frame and ask for ice:

import pydseams as ds
frame = ds.read("water.lammpstrj")
print(frame.chill_plus())
print(frame.cages())

ASE Atoms work the same way:

frame = ds.from_ase(atoms)          # default: oxygen
atoms = frame.to_ase()
pydseams.Trajectory#

alias of Frame

pydseams.from_ase(atoms, select='O', cutoff=None, bonded='auto')#

Build a Frame from an ASE Atoms.

Parameters:

  • atoms (ase.Atoms) – Configuration with a nonsingular cell periodic in all three directions.

  • select (str, int or sequence, optional) – Chemical symbol or atomic number of the species to analyse. Default "O". None keeps every atom. A sequence such as ("O", "Na", "Cl") keeps the listed species and analyses the first, so ions stay in the cloud for pydseams.features.ion_environment().

  • cutoff (float, optional) – Neighbour cutoff in Angstroms. Default SEAMS_CUTOFF or 3.5.

  • bonded ({"auto", "hbond", "cutoff"}, optional) – Graph for rings. "auto" uses hydrogen bonds when the Atoms contain H and the selected analysis cloud excludes H; otherwise it uses the cutoff neighbour list. Explicit "hbond" also requires a heavy-atom selection.

Returns:

Analysable oxygen (or selected-species) configuration.

Return type:

Frame

Raises:

  • ImportError – If ASE is not installed (pip install 'pydseamslib[ase]').

  • TypeError – If atoms is not an ASE Atoms.

  • ValueError – If the cell is singular, is not fully periodic, or select matches no atom, or if bonded="hbond" selects hydrogen.

pydseams.from_arrays(positions, cell, numbers=None, cutoff=None, bonded='cutoff')#

Build a Frame from coordinates and box lengths.

Parameters:

  • positions (sequence of (x, y, z)) – Cartesian coordinates, shape (N, 3).

  • cell (sequence of float) – Three orthorhombic box lengths or six LAMMPS restricted-triclinic bound spans and tilts.

  • numbers (sequence of int, optional) – Per-atom type codes stored as c_type. Default 1 for every particle.

  • cutoff (float, optional) – Neighbour cutoff in Angstroms. Default SEAMS_CUTOFF or 3.5.

  • bonded ({"auto", "hbond", "cutoff"}, optional) – Graph for rings. Default "cutoff" because this constructor does not attach a hydrogen cloud.

Return type:

Frame

Raises:

ValueError – If positions is empty or cell is not three or six values.

pydseams.from_chemfiles(path, frame=1, **kwargs)#

Build a Frame through chemfiles.

Parameters:

  • path (path-like) – Trajectory chemfiles can read (PDB, GRO, DCD, …).

  • frame (int, optional) – 1-indexed frame. Default 1.

  • **kwargs – Forwarded to Frame.from_chemfiles() (cutoff, bonded, atom_type, type_filter).

Return type:

Frame

Raises:

RuntimeError – If this build of seams-core did not link chemfiles.

pydseams.from_con(path, frame=1, **kwargs)#

Build a Frame from an eOn .con file.

Parameters:

  • path (path-like) – eOn .con trajectory.

  • frame (int, optional) – 1-indexed frame. Default 1.

  • **kwargs – Forwarded to Frame.from_con() (cutoff, bonded, atom_type).

Return type:

Frame

Raises:

RuntimeError – If this build of seams-core did not link readcon-core.

pydseams.from_xyz(path, **kwargs)#

Build a Frame from an XYZ file.

Parameters:

  • path (path-like) – XYZ structure.

  • **kwargs – Forwarded to Frame.from_xyz() (cutoff, bonded, atom_type).

Return type:

Frame

Raises:

RuntimeError – If this build of seams-core has no readXYZ.

pydseams.to_solvis(frame, expand_box=True)#

Wrap a Frame as a solvis.System.

Parameters:

  • frame (Frame) – Configuration to view. Converted through Frame.to_ase().

  • expand_box (bool, optional) – Passed to solvis.system.System. Default True.

Return type:

solvis.system.System

Raises:

ImportError – If solvis is not installed (pip install 'pydseamslib[solvis]').

Frame#

User-facing one-frame handle.

Load a LAMMPS dump, an ASE Atoms, or raw arrays, then call Frame.chill_plus() or Frame.cages(). Classification does not write files. Rings use the bonded graph (hydrogen bonds when hydrogens are available, otherwise the cutoff neighbour list).

class pydseams.frame.IceCounts#

Bases: dict

CHILL / CHILL+ histogram of ice labels on one frame.

Keys are the AtomStateType names written by the classifier (cubic, hexagonal, water, interfacial, clathrate, interClathrate, unclassified, reCubic, reHex). Missing keys read as 0 via attribute access, so counts.cubic and counts['cubic'] are equivalent.

Notes

repr omits zero-count labels.

class pydseams.frame.CageScore(hc, ddc)#

Bases: object

Per-atom hexagonal-cage (HC) and double-diamond-cage (DDC) flags.

A molecule in an HC is ice Ih; a molecule in a DDC is ice Ic. Membership is a boolean per analysed atom.

Parameters:

  • hc (sequence of bool) – True when the atom belongs to at least one hexagonal cage.

  • ddc (sequence of bool) – True when the atom belongs to at least one double-diamond cage.

hc#

Per-atom HC membership.

Type:

list of bool

ddc#

Per-atom DDC membership.

Type:

list of bool

property n_ih#

Number of atoms flagged HC (ice Ih).

property n_ic#

Number of atoms flagged DDC (ice Ic).

property n_water#

Number of atoms in neither cage.

class pydseams.frame.DensityProfile(centres, rho, axis, atom_type=None, site_kind=None)#

Bases: object

Cartesian number-density profile returned by Frame.density().

Parameters:
class pydseams.frame.ContactPairs(pairs, count, n_cation, n_anion)#

Bases: object

Mutual nearest unlike ion pairs returned by Frame.pairs().

Parameters:
class pydseams.frame.DomainStats(site_kind, n, largest, percolation)#

Bases: object

Largest connected site domain returned by Frame.domain().

Parameters:
class pydseams.frame.Frame(filename=None, frame=None, atom_type=None, cutoff=None, bonded='auto', region=None, all_atoms=False, *, cloud=None, h_cloud=None, symbols=None, cell_rotation=None)#

Bases: object

One configuration: neighbours, rings, CHILL(+), and cage membership.

Load a LAMMPS dump, an ASE Atoms, or raw arrays, then call chill_plus() or cages(). Classification does not write files. Prefer pydseams.io.read(), from_ase(), or from_arrays() over constructing this class by filename.

Parameters:

  • filename (path-like, optional) – LAMMPS dump. Types 1 and 2 are treated as hydrogen and oxygen unless atom_type is set.

  • frame (int, optional) – 1-indexed frame. Default 1.

  • atom_type (int or None, optional) – Species to analyse. None picks oxygen (type 2) if that type is present, otherwise type 1 (mW-style single-site dumps).

  • cutoff (float, optional) – Neighbour cutoff in Angstroms. Default 3.5.

  • bonded ({"auto", "hbond", "cutoff"}, optional) – Graph for rings. "auto" uses hydrogen bonds when hydrogens are available, otherwise the cutoff neighbour list.

  • region (((xlo, ylo, zlo), (xhi, yhi, zhi)) or None, optional) – Rectangular slice passed to pydseams.yoda.readLammpsTrjreduced(). An axis with lo == hi is unconstrained. The cloud’s nop is the kept count.

  • all_atoms (bool, optional) – Keep every LAMMPS atom type instead of filtering to atom_type. atom_type still selects the species used by neighbour and ice analyses. Cannot be combined with region.

Raises:

  • ValueError – If bonded is not one of auto, hbond, cutoff, or if a LAMMPS dump has no atoms of type 1 or 2.

  • TypeError – If neither a filename nor a pre-built cloud is supplied.

Notes

Keyword-only cloud, h_cloud, and symbols are the constructor plumbing used by from_ase() and from_arrays().

classmethod from_file(filename, frame=None, atom_type=None, cutoff=None, bonded='auto', region=None, all_atoms=False)#

Load a LAMMPS dump.

Parameters:

  • filename (path-like) – LAMMPS dump (.lammpstrj, .dump, .lammps).

  • frame (int, optional) – 1-indexed frame. Default 1.

  • atom_type (int or None, optional) – Species to keep. None tries type 2 (oxygen) then type 1.

  • cutoff (float, optional) – Neighbour cutoff in Angstroms. Default 3.5.

  • bonded ({"auto", "hbond", "cutoff"}, optional) – Graph for rings.

  • region (((xlo, ylo, zlo), (xhi, yhi, zhi)) or None, optional) – Optional rectangular slice.

  • all_atoms (bool, optional) – Keep every LAMMPS atom type. atom_type still selects the species used by neighbour and ice analyses. Cannot be combined with region.

Return type:

Frame

classmethod from_arrays(positions, cell, numbers=None, cutoff=None, bonded='cutoff', box_low=None)#

Build a frame from (N, 3) positions and a periodic box.

Parameters:

  • positions (sequence of (x, y, z)) – Cartesian coordinates.

  • cell (sequence of float) – Orthorhombic lengths [lx, ly, lz] or LAMMPS restricted triclinic bound spans and tilts [xspan, yspan, zspan, xy, xz, yz].

  • numbers (sequence of int, optional) – Per-atom type codes stored as c_type. Default 1.

  • cutoff (float, optional) – Neighbour cutoff in Angstroms. Default 3.5.

  • bonded ({"auto", "hbond", "cutoff"}, optional) – Graph for rings. Default "cutoff".

  • box_low (sequence of float, optional) – Box origin. Default (0, 0, 0).

Return type:

Frame

Raises:

ValueError – If positions is empty or cell is not three or six values.

classmethod from_xyz(filename, cutoff=None, bonded='cutoff', atom_type=None)#

Load an XYZ file through pydseams.yoda.readXYZ().

Parameters:

  • filename (path-like) – XYZ structure.

  • cutoff (float, optional) – Neighbour cutoff in Angstroms. Default 3.5.

  • bonded ({"auto", "hbond", "cutoff"}, optional) – Graph for rings. Default "cutoff".

  • atom_type (int or None, optional) – Species to analyse. None uses the first particle’s c_type.

Return type:

Frame

Raises:

RuntimeError – If this build has no readXYZ.

classmethod from_chemfiles(filename, frame=None, type_filter=-1, cutoff=None, bonded='cutoff', atom_type=None)#

Load PDB/GRO/DCD (or any chemfiles format) when chemfiles is linked.

Parameters:

  • filename (path-like) – Trajectory chemfiles can read.

  • frame (int, optional) – 1-indexed frame. Default 1.

  • type_filter (int, optional) – Chemfiles type filter. -1 keeps every type.

  • cutoff (float, optional) – Neighbour cutoff in Angstroms. Default 3.5.

  • bonded ({"auto", "hbond", "cutoff"}, optional) – Graph for rings. Default "cutoff".

  • atom_type (int or None, optional) – Species to analyse. None uses the first particle’s c_type.

Return type:

Frame

Raises:

RuntimeError – If chemfiles is not linked in this build of seams-core.

classmethod from_con(filename, frame=None, cutoff=None, bonded='cutoff', atom_type=None)#

Load an eOn .con file when readcon-core is linked.

Parameters:

  • filename (path-like) – eOn .con trajectory.

  • frame (int, optional) – 1-indexed frame. Default 1.

  • cutoff (float, optional) – Neighbour cutoff in Angstroms. Default 3.5.

  • bonded ({"auto", "hbond", "cutoff"}, optional) – Graph for rings. Default "cutoff".

  • atom_type (int or None, optional) – Species to analyse. None uses the first particle’s c_type.

Return type:

Frame

Raises:

RuntimeError – If readcon-core is not linked in this build of seams-core.

classmethod from_ase(atoms, select='O', cutoff=None, bonded='auto')#

Load an ASE Atoms. select is a symbol, atomic number, sequence, or None.

Parameters:

  • atoms (ase.Atoms) – Configuration with a nonsingular cell periodic in all three directions.

  • select (str, int or sequence, optional) – Chemical symbol or atomic number of the species to analyse. Default "O". None keeps every atom. A sequence such as ("O", "Na", "Cl") keeps the listed species and analyses the first, so ions ride along for pydseams.features.ion_environment().

  • cutoff (float, optional) – Neighbour cutoff in Angstroms. Default 3.5.

  • bonded ({"auto", "hbond", "cutoff"}, optional) – Graph for rings. "auto" uses hydrogen bonds when the Atoms contain H and the selected analysis cloud excludes H; otherwise it uses the cutoff neighbour list. Explicit "hbond" also requires a heavy-atom selection.

Return type:

Frame

to_ase()#

ASE Atoms for this frame.

Returns:

Orthorhombic cell, pbc=True. After chill_plus() (or chill()), arrays['ice_type'] holds the labels. After cages(), arrays['hc'] and arrays['ddc'] hold the cage flags.

Return type:

ase.Atoms

to_solvis(expand_box=True)#

solvis.System for this frame.

Parameters:

expand_box (bool, optional) – Passed to solvis.system.System. Default True.

Return type:

solvis.system.System

Notes

Optional extra: pip install 'pydseamslib[solvis]'.

property n_atoms#

Number of particles in the analysed cloud (cloud.nop).

property box#

Engine box as lengths or LAMMPS restricted-triclinic values.

Orthorhombic boxes have three lengths. Triclinic boxes have dump bound spans followed by xy, xz, and yz tilts.

property positions#

List of (x, y, z) coordinates for the analysed particles.

property neighbor_list#

Cutoff neighbour list from pydseams.yoda.neighListO().

Built once per loaded frame and cached. Rows are atom IDs of neighbours within cutoff for atom_type.

property hbonds#

Hydrogen-bond neighbour list.

Uses pydseams.yoda.populateHbondsWithInputClouds() when an ASE hydrogen cloud is attached, otherwise pydseams.yoda.populateHbonds() on the LAMMPS dump.

Raises:

ValueError – If no hydrogens are available (arrays-only frame, or bonded='hbond' without H).

load_frame(frame)#

Reload a later (or earlier) frame from the same trajectory file.

Parameters:

frame (int) – 1-indexed frame to read.

Raises:

ValueError – If this Frame was built from arrays or ASE and has no trajectory path.

Notes

Clears cached neighbours, hydrogen bonds, rings, and cages.

property bonds_by_index#

Index-based bonded graph used for rings.

Hydrogen-bond list when bonded is "hbond", otherwise the cutoff neighbour list. Converted with pydseams.yoda.neighbourListByIndex().

property rings#

Primitive rings up to size 6 on bonds_by_index.

Computed by pydseams.yoda.RingUpdater and cached.

property rings_recomputed_sources#

Sources recomputed by the last RingUpdater pass.

chill_plus()#

CHILL+ labels for every analysed atom. Does not write a file.

Calls pydseams.yoda.getCorrelPlus() then pydseams.yoda.getIceTypePlusNoPrint() on neighbor_list. Mutates cloud.pts[].iceType.

Returns:

Histogram of CHILL+ labels on this frame.

Return type:

IceCounts

chill()#

CHILL labels for every analysed atom. Does not write a file.

Calls pydseams.yoda.getCorrel() then pydseams.yoda.getIceTypeNoPrint() on neighbor_list. Mutates cloud.pts[].iceType.

Returns:

Histogram of CHILL labels on this frame.

Return type:

IceCounts

classify_chill_plus()#

Alias of chill_plus().

classify_chill()#

Alias of chill().

cages(seeded=True, k=4, candidate_cutoff=None, ring_adjacent=False)#

Ice score: HC = Ih, DDC = Ic, neither = water.

Parameters:

  • seeded (bool, optional) – True (default) is the hysteresis construction: mutual four-nearest seeds, union-graph completion (seeded_affiliation()). False is cutoff-graph affiliation on this frame’s six-rings (cage_affiliation()).

  • k (int, optional) – Neighbours kept in the seeded k-nearest graphs. Default 4.

  • ring_adjacent (bool, optional) – Ring completion of the seeded assignment (fill the last vertex of a six-ring whose other vertices carry a label). Default False.

  • candidate_cutoff (float or None, optional) – Candidate-list cutoff for the k-nearest graphs. None uses cutoff + 1.5.

Returns:

Per-atom HC/DDC flags. Cached as _cages for to_ase().

Return type:

CageScore

cages_by_signature(signature, max_ring_size=None)#

Closed polyhedra matching a ring-size census.

Parameters:

  • signature (str) – Comma list (4:6,6:8) or named table entry (sodalite, alpha, 512, 51262, hc, ddc). Named hc and ddc use the TUM finders.

  • max_ring_size (int or None, optional) – Franzblau depth. None uses 8, or the largest size in a comma list.

Returns:

Each dict has signature, faces, vertices, and certificate.

Return type:

list of dict

cage_affiliation()#

Order-free per-ring HC/DDC flags on this frame’s six-rings.

Uses pydseams.yoda.AffiliationUpdater on the cutoff-or-hbond six-rings.

Returns:

six_rings (list of 6-cycles), hc and ddc (per-ring bools), and reclassified (updater delta).

Return type:

dict

seeded_affiliation(k=4, candidate_cutoff=None, ring_adjacent=False)#

Seeded (hysteresis) per-atom cage flags.

Strict-graph seeds from a mutual k-nearest list, permissive completion on the union k-nearest list. Delegates to pydseams.yoda.seededCageAffiliation().

Parameters:

  • k (int, optional) – Neighbours kept in each k-nearest graph. Default 4.

  • candidate_cutoff (float or None, optional) – Candidate-list cutoff. None uses cutoff + 1.5.

  • ring_adjacent (bool, optional) – Fill the last vertex of any union-graph six-ring whose other vertices carry a label, repeated to a fixed point. A frame with no accepted ring stays empty. Default False.

Return type:

CageScore

fingerprint(hops=2, max_ring_size=7, colour_types=False)#

Label-independent topology keys of the bonded graph.

Parameters:

  • hops (int, optional) – Bonds from the centre in each local key. Default 2.

  • max_ring_size (int, optional) – Largest primitive ring counted in the census. Default 7.

  • colour_types (bool, optional) – Colour vertices by c_type (atom type or atomic number), so species never match across types. Default False.

Returns:

key names the frame (same for any relabelling of the same bonded graph), atomKeys one class per atom, classes the histogram, ringCensus[s] the primitive rings of size s. method is "nauty" when the engine links nauty, else "wl".

Return type:

pydseams.yoda.FrameFingerprint

ion_environment(ion_types, k=4, ring_adjacent=True, cutoff=None)#

Class every ion by its first water shell against the seeded cages.

Parameters:

  • ion_types (iterable of int) – c_type codes of the ions (LAMMPS types, or atomic numbers for frames built through ASE).

  • k (int, optional) – Neighbours kept in the seeded k-nearest graphs. Default 4.

  • ring_adjacent (bool, optional) – Passed to seeded_affiliation(). Default True.

  • cutoff (float, optional) – First-shell radius in Angstrom. Default self.cutoff.

Returns:

ion (cloud indices), shell, iceFraction, state (pydseams.yoda.IonState) and the counts nIce, nFront, nLiquid.

Return type:

pydseams.yoda.IonEnvironment

hydration_shell_rings(ion_types, k=4, ring_adjacent=True, cutoff=None)#

Rings of the water network through each ion’s first shell.

Parameters:
Returns:

(env, census): the pydseams.yoda.IonEnvironment and a list with one row per ion, census[i][s] counting the primitive rings of size s (up to six, the rings rings keeps) with a vertex in ion i’s shell. An ion is not a vertex of the network, so the rings it would have closed are gone; the shell census measures how far the network survives around it.

Return type:

tuple

topology_library(label, hops=2, max_ring_size=7, colour_types=False, library=None)#

Add this frame’s local keys to a key library under label.

Returns the pydseams.yoda.KeyLibrary (a new one unless library is given). yoda.writeLibrary turns it into text.

classify_topology(library, hops=2, max_ring_size=7, colour_types=False)#

Name every analysed atom by one key library, or by several at different hop counts.

Parameters:

  • library (pydseams.yoda.KeyLibrary, str, or a sequence of them) – A library or its text form from yoda.writeLibrary. A sequence of libraries built at different hops names each atom by the deepest library that holds its key, so a molecule whose wide neighbourhood is disturbed still gets a name from its inner shells; hops is then ignored.

  • hops – As in fingerprint(); colour_types must match the colouring the libraries were built with.

  • max_ring_size – As in fingerprint(); colour_types must match the colouring the libraries were built with.

  • colour_types – As in fingerprint(); colour_types must match the colouring the libraries were built with.

Returns:

labels per atom ("" when no reference matches), counts per label, depth per atom (the hops of the library that named it, 0 when none) and matched.

Return type:

pydseams.yoda.LibraryMatch

guest_occupancy(cages, guest_types, radius=4.0)#

Place guests (methane, THF, ions) in enumerated cages.

Parameters:

  • cages (sequence of sequences of int) – Vertex indices into self.cloud.pts for each cage.

  • guest_types (iterable of int) – c_type codes of the guests (LAMMPS types, or atomic numbers for frames built through ASE).

  • radius (float, optional) – A guest belongs to the nearest cage centroid within this distance in Angstrom. Default 4.0, about the radius of a 5^12 cage.

Returns:

guestsPerCage, cageOfGuest (-1 when free), centreDistance and the counts occupied, multiply and free.

Return type:

pydseams.yoda.GuestOccupancy

find_prisms(output_dir='output/', max_depth=6, shape_matching=False)#

Identify prism blocks and write engine output under output_dir.

Parameters:

  • output_dir (path-like, optional) – Directory passed to pydseams.yoda.prismAnalysis(). Default "output/".

  • max_depth (int, optional) – Largest ring size considered. Default 6.

  • shape_matching (bool, optional) – Enable TUM shape matching inside the prism search.

Notes

This path writes files. chill_plus() and cages() do not.

monolayer_rings(output_dir, sheet_area, max_depth=4)#

Classify quasi-2D polygon rings and read coverage back.

Parameters:

  • output_dir (path-like) – Directory for pydseams.yoda.polygonRingAnalysis().

  • sheet_area (float) – Sheet area passed to the engine.

  • max_depth (int, optional) – Largest ring size. Default 4.

Returns:

{ring_size: {"count": int, "coverage_xy": float}} parsed from topoMonolayer/coverageAreaXY.dat.

Return type:

dict

rdf(type_i, type_j, cutoff=12.0, binwidth=0.05)#

Partial 3D radial distribution function.

Parameters:

  • type_i (int) – First species type code (c_type).

  • type_j (int) – Second species type code (c_type).

  • cutoff (float, optional) – RDF cutoff in Angstroms. Default 12.0.

  • binwidth (float, optional) – Histogram width. Default 0.05.

Returns:

r, g – Bin centres and g_IJ(r) from pydseams.yoda.partialRdf().

Return type:

list of float

cn(type_i, type_j, cutoff, binwidth=0.05)#

Site-site coordination number integrated to cutoff.

Uses pydseams.yoda.partialRdfHist() and pydseams.yoda.coordinationNumber() with rho_J = nJ / dumpVolume.

running_cn(type_i, type_j, cutoff=12.0, binwidth=0.05)#

Running site-site coordination number.

Parameters:

  • type_i (int) – First species type code (c_type).

  • type_j (int) – Second species type code (c_type).

  • cutoff (float, optional) – Histogram cutoff in Angstroms. Default 12.0.

  • binwidth (float, optional) – Histogram width. Default 0.05.

Returns:

Running CN at each bin outer edge from pydseams.yoda.partialRdfHist() and pydseams.yoda.runningCN() with rho_J = nJ / dumpVolume.

Return type:

list of float

density(bins=None, axis='z', atom_type=0, *, table=None, kind=None)#

Cartesian number density by particle type or mapped site kind.

Parameters:

  • bins (int or None, optional) – Number of equal-width slabs. None uses about 0.1 Angstrom spacing along the selected restricted-cell axis.

  • axis ({"x", "y", "z", 0, 1, 2}, optional) – Profile axis. Default "z".

  • atom_type (int, optional) – Particle type to count; 0 counts every particle. Ignored when table and kind are supplied.

  • table (optional) – A pydseams.yoda.SiteTable and matching pydseams.yoda.SiteKind for a chemistry-resolved profile.

  • kind (optional) – A pydseams.yoda.SiteTable and matching pydseams.yoda.SiteKind for a chemistry-resolved profile.

Return type:

DensityProfile

ion_cloud(table)#

One COM vertex per ion molecule.

Parameters:

table (pydseams.yoda.SiteTable) – Type-to-kind map. Cation molecules restamp to type 1, anions to type 2.

pairs(table)#

Mutual nearest cation-anion pairs in an ion COM cloud.

Pair indices refer to the ion cloud returned by ion_cloud().

domain(table, kind, cutoff=None)#

Largest cutoff-connected component of a mapped site subset.

hbonds_from_donors(donor_hs, h_cloud=None, dist=2.42, angle=30.0)#

Hydrogen-bond network from an explicit donor-H index list.

Parameters:

  • donor_hs (sequence of int) – hCloud indices. Each H is paired with the heavy atom that shares its molID.

  • h_cloud (PointCloudDouble, optional) – Hydrogen cloud. Defaults to the ASE hydrogen cloud.

  • dist (float, optional) – Acceptor-H distance and acceptor-centered O-O-H angle.

  • angle (float, optional) – Acceptor-H distance and acceptor-centered O-O-H angle.

rdf_2d(output_dir, cutoff=12.0, binwidth=0.05)#

2D radial distribution function for identical atom types.

Parameters:

  • output_dir (path-like) – Directory for pydseams.yoda.rdf2Danalysis_AA().

  • cutoff (float, optional) – RDF cutoff in Angstroms. Default 12.0.

  • binwidth (float, optional) – Histogram width. Default 0.05.

Returns:

r, g – Bin centres and g(r) parsed from topoMonolayer/rdf.dat.

Return type:

list of float

steinhardt(order_l=6)#

Local and neighbour-averaged Steinhardt parameters.

Parameters:

order_l (int, optional) – Degree l (3, 4, or 6). Default 6.

Returns:

ql and ql_bar lists from pydseams.yoda.steinhardtQl().

Return type:

dict

steinhardt_voronoi(order_l=6, cutoff=None)#

Voronoi facet-area weighted Steinhardt parameters.

Parameters:

  • order_l (int, optional) – Degree l. Default 6.

  • cutoff (float or None, optional) – Candidate cutoff for the Voronoi pass. None uses cutoff.

Returns:

ql and ql_bar lists from pydseams.yoda.steinhardtQlVoronoi().

Return type:

dict

classify_templates(k_neigh=12)#

IRA/Horn overlay onto FCC, HCP, BCC, and SC neighbour shells.

Parameters:

k_neigh (int, optional) – Neighbours in each template shell. Default 12.

Returns:

Each hit has name, rmsd, and kind.

Return type:

list of dict

soap(iatom=None, n_max=3, l_max=6, rcut=None)#

SOAP power spectrum of one particle, or of every particle.

Parameters:

  • iatom (int or None, optional) – Particle index. None (default) computes every particle via pydseams.yoda.soapSpectrumAll().

  • n_max (int, optional) – Radial basis size. Default 3.

  • l_max (int, optional) – Angular momentum cutoff. Default 6.

  • rcut (float or None, optional) – SOAP cutoff. None uses cutoff.

Returns:

One spectrum, or one spectrum per particle.

Return type:

list of float or list of list of float

voronoi_features(cutoff=None)#

Per-atom [q4, q6, q8] from one Voronoi-weighted pass.

Parameters:

cutoff (float or None, optional) – Candidate cutoff. None uses cutoff.

Returns:

One [q4, q6, q8] row per particle from pydseams.yoda.voronoiFeatures().

Return type:

list of list of float

fit_classifier(X, y, labels=None)#

Fit a pydseams.yoda.LinearClassifier on feature rows.

Parameters:

  • X (sequence of sequence of float) – Feature matrix.

  • y (sequence of int) – Integer class labels.

  • labels (sequence of str, optional) – Human-readable class names stored on the classifier.

Returns:

Fitted classifier, also stored on the frame.

Return type:

pydseams.yoda.LinearClassifier

predict_class(x)#

Predict a class for one feature row.

Parameters:

x (sequence of float) – Feature vector matching the last fit_classifier() fit.

Returns:

Predicted class index.

Return type:

int

Raises:

RuntimeError – If fit_classifier() has not been called.

Features#

Per-frame kinetic-model vectors and ion first-shell classes. pydseams.features is the walkthrough on the features how-to. Human lookup is the Python surface page.

I/O#

Suffix dispatch onto the compiled I/O readers.

The compiled module stays thin. This helper picks LAMMPS, XYZ, chemfiles, or readcon from the path suffix and returns a Frame.

pydseams.io.read(path, frame=1, **kwargs)#

Load one configuration. Format follows the file suffix.

Parameters:

  • path (path-like) – Trajectory or structure file.

  • frame (int, optional) – 1-indexed frame for multi-frame formats (LAMMPS, chemfiles, .con). Ignored for XYZ. Default 1.

  • **kwargs – Forwarded to the matching Frame constructor (cutoff, bonded, atom_type, region, all_atoms, …). all_atoms=True retains every LAMMPS type for mixed-site analyses such as ionic pairs and domains.

Returns:

Analysable configuration.

Return type:

Frame

Notes

Suffix dispatch:

  • .xyz – Frame.from_xyz()

  • .con – Frame.from_con()

  • .pdb, .gro, .dcd – Frame.from_chemfiles()

  • otherwise – Frame.from_file() (LAMMPS dump)

.lammpstrj, .dump, and .lammps take the LAMMPS path. Builds without chemfiles or readcon raise RuntimeError when those suffixes are used.

pydseams.io.available_readers()#

Report which compiled I/O readers this build linked.

Returns:

lammps is always True. xyz, chemfiles, and readcon are True when the matching pydseams.yoda symbol exists (readXYZ, readChemfiles, readCon).

Return type:

dict of str to bool

ASE helpers#

Implementation of from_ase() and to_ase(). Optional extra: pip install 'pydseamslib[ase]'.

ASE Atoms in and out of a Frame.

Optional extra: pip install 'pydseamslib[ase]'. The compiled engine does not import ASE; this module is the adapter.

pydseams.aseio.frame_from_ase(cls, atoms, select='O', cutoff=3.5, bonded='auto')#

Construct cls (a Frame) from ASE Atoms.

Parameters:

  • cls (type) – Frame or a subclass.

  • atoms (ase.Atoms) – Configuration with a nonsingular cell periodic in all three directions.

  • select (str, int or sequence, optional) – Chemical symbol or atomic number kept for analysis. Default "O". None keeps every atom. A sequence such as ("O", "Na", "Cl") keeps every listed species in the cloud and analyses the first; the others stay as their atomic numbers in c_type, which is what pydseams.features.ion_environment() reads.

  • cutoff (float, optional) – Neighbour cutoff in Angstroms. Default 3.5.

  • bonded ({"auto", "hbond", "cutoff"}, optional) – Graph for rings. "auto" becomes "hbond" when the Atoms contain hydrogen and the selected analysis cloud excludes hydrogen; otherwise it becomes "cutoff". Explicit "hbond" also requires a heavy-atom selection.

Returns:

Selected-species cloud plus an optional hydrogen cloud for hydrogen-bond analysis.

Return type:

Frame

Raises:

  • ImportError – If ASE is not installed.

  • TypeError – If atoms has no get_positions.

  • ValueError – If the cell is singular, is not fully periodic, or select matches no atom, or if bonded="hbond" selects hydrogen.

Notes

For a heavy-atom selection, hydrogens stay in a side cloud so the analysed species remain the CHILL / ring particles. General cells are rotated into LAMMPS restricted form for analysis and restored by frame_to_ase(). An ASE mol-id array supplies molecule ownership. Without it, each hydrogen belongs to the nearest selected atom under the minimum-image convention.

pydseams.aseio.frame_to_ase(frame)#

Build an ASE Atoms from a Frame.

Parameters:

frame (Frame) – Configuration to export.

Returns:

Periodic cell in its imported orientation. Symbols come from the ASE import when present; LAMMPS-only frames fall back to O.

Return type:

ase.Atoms

Notes

After chill_plus() (or chill()), atoms.arrays['ice_type'] holds the per-atom labels. After cages(), atoms.arrays['hc'] and atoms.arrays['ddc'] hold the cage flags. atoms.info['dseams_n_atoms'] is the analysed particle count.

solvis#

Implementation of to_solvis() and to_solvis(). Optional extra: pip install 'pydseamslib[solvis]'.

Optional solvis (PyVista) view of a Frame.

solvis takes an ASE Atoms. This helper is the same pattern as metatomic’s ASE adapter: the C++ core does not know about the viewer. Install with pip install 'pydseamslib[solvis]'.

pydseams.solvis.to_solvis(frame, expand_box=True)#

Wrap a Frame as a solvis.System.

Parameters:

  • frame (Frame) – Configuration to view. Converted through to_ase().

  • expand_box (bool, optional) – Passed to solvis.system.System. Default True.

Return type:

solvis.system.System

Raises:

ImportError – If solvis is not installed (pip install 'pydseamslib[solvis]').

Compiled module (pydseams.yoda)#

yoda is mocked in the Sphinx build (autodoc_mock_imports), so automodule cannot list live signatures. The tables below are every public name registered in src/bindings.cpp: 134 names (113 functions, 19 types, and the Kind / Family type aliases). Four functions are compile-gated and absent from builds that did not link the extra: readChemfiles (SEAMS_HAS_CHEMFILES), readCon (SEAMS_HAS_READCON), ira_match and sofi_point_group (SEAMS_HAS_IRA).

Application code uses Frame / read() / from_ase(). Call yoda directly for the raw engine.

I/O#

name

role

readXYZ

Read atom coordinates from an XYZ file.

readLammpsTrjreduced

One LAMMPS frame, one type. With isSlice, drops atoms outside (coordLow, coordHigh). nop is the kept count. An axis with lo == hi is unconstrained.

readLammpsTrjO

One LAMMPS frame, one type (the O is historical). With isSlice, sets inSlice and does not drop. nop is the type-filtered count.

readLammpsTrj

One LAMMPS frame, every atom type.

readBonds

Read bond connectivity from a formatted bond file.

atomInSlice

True when each component is in the closed interval, or that axis has lo == hi.

readChemfiles

Read any trajectory format supported by chemfiles (PDB, GRO, DCD, …). Linked when SEAMS_HAS_CHEMFILES.

readCon

Read a .con file (eOn saddle-point search trajectories). Linked when SEAMS_HAS_READCON.

writeDump

Write a LAMMPS dump file for the current point cloud.

Neighbours and hydrogen bonds#

name

role

clearNeighbourList

Free memory for a neighbour list.

getNewNeighbourListByIndex

Build a neighbour list by index using a distance cutoff.

kNearestNeighbourList

Exact k-nearest bonded graph, union- or mutually-symmetrized.

shellSeparation

Certificate pair (max k-th distance, min (k+1)-th distance) for the exact reduction of the k-nearest graph to a cutoff graph.

halfNeighList

Build a half neighbour list (each pair stored once) for one atom type.

neighbourListByIndex

Convert an atom-ID neighbour list to an index-based neighbour list.

neighList

Build a full neighbour list for two atom types within a cutoff.

neighListO

Build a full neighbour list for a single atom type within a cutoff.

neighListPair

I-J neighbour list (like-type reuses neighListO).

SiteTable / parseSiteSpec

Type-to-kind map. Type 1 is not a chemistry.

Kind / Family

Aliases of SiteKind / SiteFamily.

indicesOf

Cloud indices whose mapped site kind matches, including polar/apolar unions.

lammpsTypeOfKind

Unique LAMMPS type mapped to a site kind.

ionCloud

One COM vertex per ion molID, unwrapped with relDist. Also (src, cationType, anionType) or (src, typeToKind).

mutualNearestUnlike

Mutual nearest pairs between two particle types under periodic boundaries.

partialRdfHist

Partial 3D RDF as PartialRdf (r, g, count, volume, nI, nJ).

runningCN

Running site-site CN (rhoJ defaults to nJ/volume).

coordinationNumber

Site-site CN to rMax (rhoJ defaults to nJ/volume).

populateHbondsFromDonors

H-bond net from a flat list of hCloud indices.

donatedHydrogenBond

One donor-acceptor O-O-H test.

createBondsFromCages

Create bond connectivity from rings and cage information.

getHbondDistanceOH

Compute the O-H hydrogen bond distance between two atoms.

populateHbonds

Build the hydrogen-bond network from a trajectory and neighbour list.

populateHbondsWithInputClouds

Build hydrogen bonds from pre-loaded oxygen and hydrogen point clouds.

trimBonds

Remove duplicate bonds from a bond list.

neighListPair, SiteTable, parseSiteSpec, ionCloud, partialRdfHist, coordinationNumber, runningCN, firstMinimumBin, populateHbondsFromDonors, and donatedHydrogenBond are bound. Frame.rdf returns (r, g). Frame.cn, Frame.running_cn, Frame.ion_cloud, and Frame.hbonds_from_donors call the new symbols.

Rings and cages#

name

role

clearGraph

Free memory for a graph object.

countAllRingsFromIndex

Find all possible rings (including non-shortest-path) up to maxDepth.

ringNetwork

Find all primitive (shortest-path) rings up to maxDepth.

cageAffiliation

Order-free per-ring cage classification: (hc, ddc) flag vectors.

findBySignature

Closed polyhedra matching a ring-size census or named table entry.

seededCageAffiliation

Seeded (hysteresis) per-atom cage flags: strict-graph seeds, permissive-graph completion. ringAdjacentCompletion fills the last vertex of a six-ring whose other vertices carry a label.

RingUpdater

Exact incremental primitive rings for a neighbour list.

AffiliationUpdater

Exact incremental per-ring cage classification for one frame.

populateGraphFromIndices

Create a graph object from an index-based neighbour list.

populateGraphFromNListID

Create a graph object from an atom-ID neighbour list and point cloud.

removeNonSPrings

Remove non-shortest-path rings using the Franzblau criterion.

restoreEdgesFromIndices

Restore graph edges from an index-based neighbour list.

Ring classification#

name

role

assignPolygonType

Assign atom types based on the ring size of n-membered rings.

assignPrismType

Assign atom types for atoms belonging to prism rings.

clearRingList

Free memory for a list of rings.

compareRings

Check whether two unordered rings contain the same elements.

commonElementsInThreeRings

Check whether three rings share at least one common element.

deformedPrismTypes

Get atom type values for deformed prisms.

discardExtraTetragonBlocks

Discard duplicate 4-membered ring pairs that are parallel in one dimension.

findPrisms

Identify which rings form prism blocks.

findsCommonElements

Return the common elements shared by two rings.

findTripletInRing

Search for a triplet of atoms within a ring.

getSingleRingSize

Extract rings of a specific size from a list of all rings.

hasCommonElements

Check whether two rings share any common elements.

basalPrismConditions

Test whether two rings satisfy strict basal prism conditions.

relaxedPrismConditions

Test whether two rings satisfy relaxed prism conditions (at least one bond).

getEdgeMoleculesInRings

Select edge molecules in rings that straddle the slice boundary.

printSliceGetEdgeMoleculesInRings

Select edge molecules in rings and write slice output files.

Topology writers#

name

role

polygonRingAnalysis

Classify rings in a quasi-2D monolayer and write output.

bulkPolygonRingAnalysis

Classify rings in a bulk system and write output.

prismAnalysis

Prism identification on rings up to maxDepth; writes output.

rmAxialTranslations

Remove axial translations from an ice nanotube for visualization.

Topological unit matching#

name

role

atomsFromCages

Get atom indices belonging to cages in a given cluster.

averageRMSDatom

Average the per-atom RMSD over the number of shared cages.

buildRefDDC

Build a reference double-diamond cage from a template XYZ file.

buildRefHC

Build a reference hexagonal cage from a template XYZ file.

clusterCages

Cluster cages using Stillinger’s algorithm and write XYZ output.

shapeMatchDDC

Shape-match a target double-diamond cage against a reference.

shapeMatchHC

Shape-match a target hexagonal cage against a reference.

topoBulkCriteria

Find HCs and DDCs in a bulk system using topological criteria.

topoUnitMatchingBulk

Run full topological unit matching for bulk water.

updateRMSDatom

Update per-atom RMSD from a cage shape-matching result.

Selection#

name

role

getPointCloudOneAtomType

Extract a point cloud containing only atoms of a given type.

atomsInSingleSlice

Mark atoms inside a rectangular volume slice.

moleculesInSingleSlice

Mark whole molecules as in-slice if any atom is inside the region.

setAtomsWithSameMolID

Set the inSlice flag for all atoms sharing a given molecule ID.

CHILL / CHILL+#

name

role

BondClassifier

Bond-classification rule set (staggered / eclipsed windows).

chillRule

The CHILL water rule set.

chillPlusRule

The CHILL+ water rule set.

bondClassifier

Look up a registered bond-classification rule set by name.

registerBondClassifier

Register (or replace) a named bond-classification rule set.

bondClassifierNames

Names of every registered bond-classification rule set.

classifyBonds

Compute and classify bond correlations under an arbitrary rule set.

getCorrelPlus

Compute CHILL+ bond-order correlations and classify bond types.

getIceTypePlusNoPrint

Classify each atom’s ice type using CHILL+. Does not write a file.

getIceTypePlus

Classify each atom’s ice type using CHILL+ and write to file.

getCorrel

Compute CHILL bond-order correlations and classify bond types.

getIceTypeNoPrint

Classify each atom’s ice type using CHILL. Does not write a file.

getIceType

Classify each atom’s ice type using CHILL and write to file.

getq6

Compute the q6 bond order parameter for all atoms.

reclassifyWater

Reclassify water molecules using averaged q6 and q3 parameters.

printIceType

Print the ice type classification for the current frame.

Descriptors#

name

role

steinhardtQl

Local and neighbour-averaged Steinhardt parameters of degree orderL.

steinhardtQlVoronoi

Voronoi facet-area weighted Steinhardt parameters.

classifyTemplates

IRA/Horn overlay onto FCC, HCP, BCC, and SC neighbour shells.

soapSpectrum

SOAP power spectrum of one particle.

soapSpectrumAll

SOAP power spectrum of every particle.

voronoiFeature

Per-atom [q4, q6, q8] from the Voronoi-weighted Steinhardt path.

voronoiFeatures

[q4, q6, q8] for every particle from one Voronoi pass per order.

voronoiFacetWeights

Voronoi facet neighbours and area weights for every particle.

LinearClassifier

Linear classifier used by Frame.fit_classifier.

ira_available

True when this build linked libira (IRA/SOFI).

ira_match

IRA overlay of two n x 3 point sets. Linked when SEAMS_HAS_IRA.

sofi_point_group

SOFI point group of an n x 3 cloud. Linked when SEAMS_HAS_IRA.

lookupTableQ4Vec

Lookup table for Q4 (m=0 to m=8).

lookupTableQ4

Lookup table for Q4 at a single m (m=0 to m=8).

lookupTableQ8Vec

Lookup table for Q8 (m=0 to m=16).

lookupTableQ8

Lookup table for Q8 at a single m (m=0 to m=16).

Clustering and RDF#

name

role

clusterAnalysis

Cluster ice-like particles and return the largest ice cluster.

recenterClusterCloud

Recenter a cluster point cloud for visualization.

rdf2Danalysis_AA

2D radial distribution function for identical atom types.

partialRdf

Partial 3D RDF g_IJ(r). Returns (r, g).

runningCN

Running CN 4 pi rho_J int s^2 g ds. Returns a list.

densityZ

Cartesian number-density histogram by particle type or mapped site kind and axis.

largestDomain

Size and fraction of the largest connected component in a selected subset.

Types#

name

role

PartialRdf

Histogram from partialRdfHist: r, g, count, volume, nI, nJ.

PointCloudDouble

Collection of points for a single frame, with box dimensions.

PointDouble

Per-particle data: coordinates, type, molecule ID, ice classification.

SteinhardtQl

Per-particle Steinhardt ql and neighbour-averaged qlBar.

AtomStateType

Per-atom ice phase classification from CHILL / CHILL+ / q6.

BondType

Bond classification: staggered, eclipsed, or out_of_range.

Result

Bond correlation result: classifier (bond type) and c_value.

CrystalKind

Crystal template kind: other, sc, fcc, hcp, bcc.

TemplateHit

IRA/Horn overlay hit: kind, rmsd, name.

VoronoiWeights

Facet-sharing neighbours and facet-area weights of one particle.

DensityZ

Number-density result: bin centres z, values rho, and selected type.

Domain

Connected-domain result: subset size, largest component, and percolation fraction.