Python surface#

Human lookup of Frame, IceCounts, CageScore, read(), and the ASE helpers. Napoleon autodoc of every signature is the API reference page.

Frame#

Frame is the one-frame handle. Load a LAMMPS dump, an ASE Atoms, or raw arrays, then call chill_plus() or cages(). Classification does not write files. Prefer read(), from_ase(), or from_arrays() over constructing Frame by filename.

Trajectory is an alias of Frame.

Constructors#

name	role
`from_file()`	LAMMPS dump; guesses type 2 then type 1
`from_ase()`	ASE `Atoms`; `select="O"`
`from_arrays()`	`(N, 3)` positions and three box lengths
`from_xyz()`	XYZ via `yoda.readXYZ`
`from_chemfiles()`	PDB / GRO / DCD when chemfiles is linked
`from_con()`	eOn `.con` when readcon-core is linked

Package-level aliases: from_ase(), from_arrays(), from_xyz(), from_chemfiles(), from_con().

Geometry and graphs#

name	role
`n_atoms`	analysed particle count (`cloud.nop`)
`box`	orthorhombic box lengths `[lx, ly, lz]`
`positions`	list of `(x, y, z)`
`neighbor_list`	cutoff neighbour list (`yoda.neighListO`)
`hbonds`	hydrogen-bond neighbour list
`rings`	primitive rings up to size 6
`load_frame()`	reload a later frame from the same file

Classification#

name	role
`chill_plus()`	CHILL+ ice labels; no files written
`chill()`	CHILL ice labels; no files written
`classify_chill_plus()`	alias of `chill_plus`
`classify_chill()`	alias of `chill`
`cages()`	HC / DDC membership (`seeded=True`, `k=4`)

cages() with seeded=True is the hysteresis construction. seeded=False is cutoff-graph affiliation on this frame’s six-rings.

Export and descriptors#

name	role
`to_ase()`	ASE `Atoms`; needs `pydseams[ase]`
`to_solvis()`	solvis `System`; needs `pydseams[solvis]`
`steinhardt()`	local and neighbour-averaged `ql`
`soap()`	SOAP power spectrum
`voronoi_features()`	per-atom `[q4, q6, q8]`

Prism, monolayer, and RDF helpers write engine output. See the Frame autodoc on API reference.

IceCounts#

IceCounts is the histogram returned by chill_plus() and chill().

Keys are the AtomStateType names (cubic, hexagonal, water, interfacial, clathrate, interClathrate, unclassified, reCubic, reHex). Missing keys read as 0 via attribute access, so counts.cubic and counts["hexagonal"] are equivalent. repr omits zero-count labels.

CageScore#

CageScore is the per-atom score returned by cages().

A molecule in an HC is ice Ih; a molecule in a DDC is ice Ic.

name	role
`hc`	per-atom hexagonal-cage flag
`ddc`	per-atom double-diamond-cage flag
`n_ih`	number of atoms flagged HC
`n_ic`	number of atoms flagged DDC
`n_water`	number of atoms in neither cage

read#

read() is the suffix-dispatching loader. available_readers() reports which compiled readers this build linked.

suffix	constructor
`.xyz`	`from_xyz()`
`.con`	`from_con()`
`.pdb`, `.gro`, `.dcd`	`from_chemfiles()`
`.lammpstrj`, `.dump`, `.lammps`, other	`from_file()`

Common kwargs: frame (1-indexed), cutoff (Angstroms, default 3.5), bonded ("auto", "hbond", "cutoff"), atom_type, region. bonded="auto" uses hydrogen bonds when hydrogens are available.

Builds without chemfiles or readcon raise RuntimeError when those suffixes are used.

ASE#

from_ase() / from_ase() build a Frame from an ASE Atoms. to_ase() is the inverse.

Install: pip install 'pydseams[ase]'. The cell must be orthorhombic. select is a symbol, an atomic number, or None (every atom). Default select="O".

to_ase writes arrays["ice_type"] after CHILL and arrays["hc"] / arrays["ddc"] after cages(). A frame loaded from a LAMMPS dump (no ASE symbols) uses O as the fallback species.

Implementation autodoc is the ASE helpers section of API reference. Walkthrough: Classify ASE Atoms.

to_solvis() wraps the same Atoms. Install: pip install 'pydseams[solvis]'.

Package names#

name	role
`pydseams`	Python package
`pydseamslib`	compatibility alias of `pydseams`
`pydseams.yoda`	compiled registrations
`pydseams._core`	alias of `yoda`
`pydseams.cyoda`	alias of `yoda`
`pydseams.Trajectory`	alias of `Frame`

Requires Python 3.12+. Wheels are the CPython 3.12 limited ABI.

yoda names (mocked in the Sphinx build) are tabulated on the API reference page.