Frequently asked questions#

Names#

Why is the package pydseams and the module yoda?#

pydseams is the Python package. yoda is the compiled nanobind extension inside it. That is the 2020 compiled surface name (libyodaLib in seams-core). Helpers sit on yoda the way application code sits on a C API.

See The yoda surface.

What is pydseamslib?#

The PyPI project (pip install pydseamslib). import pydseamslib is a compatibility alias of pydseams. New code imports pydseams.

What are _core and cyoda?#

Aliases of pydseams.yoda. assert ds._core is ds.yoda and assert ds.cyoda is ds.yoda. New code imports yoda. pydseams.Trajectory is an alias of Frame.

Do I compile yoda to use the package?#

No. pip install pydseamslib installs a wheel that already links the engine. Compile only if you develop the bindings from a checkout (nix build / nix develop).

Usage#

Which formats does ds.read accept?#

Suffix dispatch:

suffix

constructor

.xyz

Frame.from_xyz

.con

Frame.from_con

.pdb, .gro, .dcd

Frame.from_chemfiles

.lammpstrj, .dump, .lammps, other

Frame.from_file

available_readers() reports which optional C++ readers this build linked (xyz, chemfiles, readcon). lammps is always present.

Does classification write files?#

chill_plus, chill, and cages do not write files. Prism, monolayer, and RDF helpers do.

Can the ASE cell be triclinic?#

Yes. from_ase rotates any nonsingular, fully periodic ASE cell into the engine’s LAMMPS restricted-triclinic representation. to_ase restores the imported cell orientation, positions, and cell displacement. Partially periodic and singular cells are rejected.

How do I keep every atom, not just oxygen?#

frame = ds.from_ase(atoms, select=None)

Default select="O". A symbol or an atomic number keeps that species. A sequence such as ("O", "Na", "Cl") keeps the listed species and analyses the first. A mixed selection containing H uses cutoff bonding; hydrogen-bond topology requires a heavy-atom selection such as select="O".

How do I view a classified frame?#

solvis. pip install 'pydseamslib[solvis]', then frame.to_solvis(). That is the visualization path. See View a frame in solvis. OVITO is not required.

How do I cite this?#

Cite the 2020 d-SEAMS paper. See How to cite.

Compatibility#

Which Python versions are supported?#

Python 3.12+. Wheels are the CPython 3.12 limited ABI. Free-threaded CPython has no limited ABI and is not a target.

How is this different from seams and Lua dseams?#

Same engine, different front end. seams is the CLI in seams-core. require("dseams") is the Lua / Fennel module in yodaStruct. pydseams is the Python Frame API.

See also#