Python surface#
Human lookup of Frame, IceCounts, CageScore, DensityProfile,
ContactPairs, DomainStats, read, the ASE helpers, and
pydseams.features. Napoleon autodoc of every signature is
api.md.
Frame#
pydseams.frame.Frame is the one-frame handle. Load a LAMMPS dump,
an ASE Atoms, or raw arrays, then call classification, density,
pairing, or domain methods. Classification does not write files.
Prefer pydseams.io.read,
Frame.from_ase, or Frame.from_arrays over constructing Frame
by filename.
Trajectory is an alias of Frame.
Constructors#
name |
role |
|---|---|
|
LAMMPS dump; guesses type 2 then type 1 |
|
ASE |
|
|
|
XYZ via |
|
PDB / GRO / DCD when chemfiles is linked |
|
eOn |
Package-level aliases: pydseams.from_ase, from_arrays,
from_xyz, from_chemfiles, from_con. Autodoc:
api.md.
Geometry and graphs#
name |
role |
|---|---|
|
analysed particle count ( |
|
three lengths or six LAMMPS restricted-triclinic values |
|
list of |
|
cutoff neighbour list ( |
|
hydrogen-bond neighbour list |
|
primitive rings up to size 6 |
|
reload a later frame from the same file |
box is three lengths for an orthorhombic frame. Triclinic frames use
dump bound spans followed by xy, xz, and yz tilts.
yoda.neighListPair, yoda.SiteTable, yoda.parseSiteSpec,
yoda.Kind / yoda.Family (aliases of SiteKind / SiteFamily),
yoda.ionCloud (table, cationType / anionType, or
typeToKind), yoda.partialRdfHist, yoda.coordinationNumber,
yoda.runningCN, yoda.populateHbondsFromDonors, and
yoda.donatedHydrogenBond are bound. yoda.densityZ,
yoda.mutualNearestUnlike, and yoda.largestDomain provide the raw
site-analysis primitives. Frame.rdf is (r, g);
Frame.cn integrates that histogram; Frame.running_cn is the
running integral with rho_J = nJ / volume; Frame.ion_cloud
and Frame.hbonds_from_donors wrap the site and donor-H paths.
Frame.density, Frame.pairs, and Frame.domain expose
type/site-resolved density, mutual cation–anion pairing, and the
largest connected site domain.
Classification#
name |
role |
|---|---|
|
CHILL+ ice labels; no files written |
|
CHILL ice labels; no files written |
|
alias of |
|
alias of |
|
hexagonal / double-diamond membership; seeded hysteresis; |
|
seeded flags; |
|
cutoff-graph per-ring flags |
|
first-shell ice class of every ion |
|
rings of the water network through each ion’s shell, by size |
|
guests placed in enumerated cages by periodic centroids |
|
atoms named by one key library, or by several at different hops |
cages with the seeded flag on is the hysteresis construction
(seeded_affiliation). Cutoff-graph affiliation on this frame’s
six-rings is the other path. ring_adjacent on cages or
seeded_affiliation fills the last vertex of a six-ring whose other
vertices carry a label. IceFeaturizer and Frame.ion_environment
turn that flag on by default.
Export and descriptors#
name |
role |
|---|---|
|
ASE |
|
solvis |
|
local and neighbour-averaged |
|
SOAP power spectrum |
|
per-atom |
|
in-memory partial 3D RDF ( |
|
site-site CN to a cutoff ( |
|
running site-site CN ( |
|
Cartesian number density by particle type or site kind |
|
ion COM vertices ( |
|
mutual nearest unlike ion pairs |
|
largest cutoff-connected component of a site kind |
|
H-bond net from an explicit H-index list |
Prism, monolayer, and rdf_2d write engine output. Frame.rdf
does not. See the Frame autodoc on api.md.
IceCounts#
pydseams.frame.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#
pydseams.frame.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 |
|---|---|
|
per-atom hexagonal-cage flag |
|
per-atom double-diamond-cage flag |
|
number of atoms flagged HC |
|
number of atoms flagged DDC |
|
number of atoms in neither cage |
Features#
pydseams.features turns a Trajectory into per-frame vectors and
per-molecule states for kinetic models.
name |
role |
|---|---|
|
per-frame vector and per-molecule states |
|
first-shell ice class of each ion |
|
per-frame ion summary |
|
bin |
|
time-lagged independent component analysis (TICA) |
|
register the vector with PyEMMA |
The per-frame vector comes from IceFeaturizer, which calls
Frame.seeded_affiliation with ring-adjacent completion on by
default. Walkthrough:
features how-to. Autodoc:
api.md.
Per-frame and per-molecule ice features for kinetic modelling.
IceFeaturizer walks a Trajectory and
returns what a Markov-state-model or committor pipeline consumes: one
feature vector per frame (cage counts, the largest connected cage
cluster, cubicity, CHILL+ counts, ring counts) and one integer state per
molecule per frame (water, ice Ic, ice Ih, mixed). The arrays are plain
NumPy, which is what deeptime takes directly; to_pyemma_featurizer()
registers the same per-frame vector as a custom feature with PyEMMA.
PyEMMA has been in maintenance mode since 2022 and deeptime is its
successor; both adapters are here because both still appear in the
nucleation literature.
Everything is deterministic and label-based, so a feature file from one machine equals the same file from another to the last integer.
- pydseams.features.ion_environment(frame, states, ion_types, cutoff=None)
Ice content of the first water shell of every ion.
Ions are not part of the hydrogen-bond network; the cage assignment runs on the water alone and the ions are read against it. A frame built with
all_atoms=TrueorFrame.from_arrays()carries every species in its cloud;frame.atom_typenames the water. The engine’sionEnvironmentdoes the work when the compiled module exposes it; the NumPy path below gives the same answer on older engines.- Parameters:
frame (
Frame) – Frame whose cloud holds water and ions.states (
arrayofint8) – Per-atom states fromIceFeaturizer.frame_features(); non-water entries are ignored.ion_types (
iterableofint) –c_typecodes of the ions.cutoff (
float, optional) – First-shell radius in Angstrom. Defaultframe.cutoff.
- Returns:
Cloud indices of the ions, the water count in each first shell, the fraction of that shell carrying an ice label, and one of
ION_ICE(whole shell ice),ION_LIQUID(no ice) orION_FRONTper ion. An ion with an empty shell is liquid.- Return type:
(indices,shell,fraction,ion_states)
- pydseams.features.ion_features(frame, states, ion_types, cutoff=None)
Per-frame ion summary in the order of
ION_FEATURE_NAMES.
- pydseams.features.count_frames(filename)
Stored frames in a LAMMPS dump (
ITEM: TIMESTEPheaders).
- class pydseams.features.IceFeaturizer(trajectory, k=4, ring_adjacent=True, chill=True, ion_types=())
Turn a trajectory into per-frame features and per-molecule states.
- Parameters:
trajectory (
Trajectory) – An openTrajectory; frames are visited withload_frame(), so the incremental updaters stay warm.k (
int, optional) – Neighbours in the four-nearest graphs. Default4.ring_adjacent (
bool, optional) – Ring-adjacent completion of the seeded assignment. DefaultTrue.chill (
bool, optional) – Also compute CHILL+ on the cutoff graph. DefaultTrue.ion_types (
iterableofint, optional) –c_typecodes of ions present in the cloud. When given, the vector gainsION_FEATURE_NAMESfromion_features().
- frame_features()
Feature vector and per-molecule states of the loaded frame.
- Returns:
featuresis a float array of lengthlen(self.feature_names);statesanint8array with one ofSTATE_*per molecule.- Return type:
(features,states)
- transform(frames=None)
Features and states for a range of frames.
- pydseams.features.discretize_nmax(n_max, edges)
Map a largest-cluster series onto integer states by bin edges.
- Parameters:
n_max (
array_like) – Largest cage cluster per frame (X[:, 1]).edges (
sequenceoffloat) – Increasing bin edges; stateiisedges[i] <= n_max < edges[i+1], below the first edge is state 0, at or above the last is the last.
- Returns:
A discrete trajectory for
deeptime.markov.msm.MaximumLikelihoodMSMorpyemma.msm.estimate_markov_model.- Return type:
numpy.ndarrayofint
- pydseams.features.to_pyemma_featurizer(featurizer, topology)
Register the per-frame vector as a PyEMMA custom feature.
PyEMMA’s featurizer wants a function of an
mdtrajtrajectory; this ignores the coordinates it is given and reads the frames through the engine instead, so the feature order is the one ofFEATURE_NAMES.
- pydseams.features.to_deeptime(X, lagtime, dim=None)
TICA of a per-frame feature array with deeptime.
Returns the fitted
deeptime.decomposition.TICAmodel; callmodel.transform(X)for the projection.
Site-analysis records#
DensityProfile, ContactPairs, and DomainStats are immutable
records returned by Frame.density, Frame.pairs, and Frame.domain.
record |
fields |
|---|---|
|
|
|
|
|
|
Use a site table when the analysis is chemistry-resolved:
frame = ds.read("ions.lammpstrj", all_atoms=True, atom_type=1)
sites = ds.yoda.parseSiteSpec("1=polar,2=apolar")
profile = frame.density(table=sites, kind=ds.yoda.Kind.polar)
domain = frame.domain(sites, ds.yoda.Kind.polar)
ions = ds.yoda.parseSiteSpec("1=cationHead,2=anion")
pairs = frame.pairs(ions)
read#
pydseams.io.read is the suffix-dispatching loader.
pydseams.available_readers reports which compiled readers this
build linked.
suffix |
constructor |
|---|---|
|
|
|
|
|
|
|
|
Common kwargs: frame (1-indexed), cutoff (Angstroms, default
3.5), bonded ("auto", "hbond", "cutoff"), atom_type,
region, and all_atoms. all_atoms=True retains every LAMMPS type
for mixed-site analyses; atom_type still selects the species used by
neighbour and ice methods. It cannot be combined with region. For
LAMMPS readers, bonded="auto" uses hydrogen bonds when hydrogens are
available.
region is (lo, hi) passed to yoda.readLammpsTrjreduced.
nop is the kept count. An axis with lo == hi is unconstrained,
so ([0, 0, 0], [50, 0, 0]) slices x only. yoda.readLammpsTrjO
keeps every atom of the type and only sets inSlice.
Builds without chemfiles or readcon raise RuntimeError when those
suffixes are used.
ASE#
pydseams.from_ase / Frame.from_ase build a Frame from an ASE
Atoms. Frame.to_ase is the inverse.
Install: pip install 'pydseamslib[ase]'. The cell must be
nonsingular and periodic in all three directions. General cells are
rotated into LAMMPS restricted-triclinic form for analysis;
to_ase restores the imported cell orientation and displacement.
select is a symbol, an atomic number, None (every atom), or a
sequence such as ("O", "Na", "Cl"). Default select="O". A sequence
keeps the listed species and analyses the first, so ions stay in the
cloud for pydseams.features.ion_environment.
For ASE input, bonded="auto" uses hydrogen bonds only when the
input contains H and the selected analysis cloud excludes H.
Thus select=None uses cutoff bonding. Explicit bonded="hbond"
requires a heavy-atom selection such as 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.md. Walkthrough: ASE how-to.
pydseams.to_solvis wraps the same Atoms. Install:
pip install 'pydseamslib[solvis]'.
Package names#
name |
role |
|---|---|
|
Python package |
|
compatibility alias of |
|
compiled registrations |
|
alias of |
|
alias of |
|
alias of |
|
kinetic vectors and ion environment |
Requires Python 3.11+. CPython 3.11 has a version-specific wheel; Python 3.12 and newer use the CPython 3.12 limited ABI.
yoda names (mocked in the Sphinx build) are tabulated on
api.md.