Skip to main content

PydSEAMSlib

Open in Colab

pydseams

built with nix

Python bindings for the d-SEAMS C++ engine (seams-core).

This repository builds the PyPI distribution pydseamslib. One wheel holds three import names over the same engine:

Import What it is
pydseams The Frame package: read, from_ase, features, band, solvis, and the compiled pydseams.yoda surface over libyodaLib
pydseamslib Re-exports pydseams (pydseamslib.Frame is pydseams.Frame)
dseams The 2.14 API over the stable C API (seams.h): chill_plus, q4q6, neighbours, rings, cages, symmetry, dseams.Frame, and dseams.userframe

The C++ engine and seams CLI live in seams-core, built here as a Meson subproject; libseams and libseams_lang ship inside the wheel. src/seams is the ctypes package over libseams (not in the wheel). Lua/Fennel is dseams in yodaStruct. Neighbour search is linkcell. Do not grow a second engine here.

Released versions live in CHANGELOG.md (Keep a Changelog). Unreleased notes are files under changelog.d/. The cut is towncrier build --version X.Y.Z.

python -m pip install 'pydseamslib==2.14.0'
python -m pip install 'pydseamslib[ase]==2.14.0'      # ASE Atoms
python -m pip install 'pydseamslib[solvis]==2.14.0'   # solvis / PyVista

Each command installs a wheel containing the bundled engine and all three import names: dseams, pydseams, and pydseamslib. No separate seams-core installation is needed.

Nix flake:

nix build
nix develop

Docs: docs/orgmode/ (ox-rst) and docs/source/ (Shibuya). Site: https://d-seams.github.io/PydSEAMSlib/.

import pydseams as ds

frame = ds.read("water.lammpstrj")  # release wheels also read .xyz and .con
print(frame.chill_plus())
print(frame.cages())
print(frame.density(bins=100, axis="z"))

mixed = ds.read("ions.lammpstrj", all_atoms=True, atom_type=1)
sites = ds.yoda.parseSiteSpec("1=polar,2=apolar")
print(mixed.domain(sites, ds.yoda.Kind.polar))

ions = ds.yoda.parseSiteSpec("1=cationHead,2=anion")
print(mixed.pairs(ions))

frame = ds.from_ase(atoms)
atoms = frame.to_ase()
system = frame.to_solvis()  # optional extra

ds.read picks the engine reader from the suffix. yoda is the compiled surface. Helpers (Frame, io, ASE, solvis) stay in Python. _core and cyoda still name the same module. ds.available_readers() reports the readers compiled into a wheel. The 2.14.0 PyPI wheels do not link chemfiles, so .pdb, .gro, and .dcd inputs raise RuntimeError.

Frame.density, Frame.pairs, and Frame.domain expose the same site-resolved density, ion-pair, and connected-domain analyses as the CLI. Use ds.read(..., all_atoms=True) when a site analysis needs every LAMMPS type. A file with more than one element symbol gives each symbol its own c_type, and the cutoff graph contains like and unlike pairs. Pass periodic=False for a molecule so pairs are not wrapped across the bounding span. atom_type is the species single-type ice routines still receive. pydseams.band.band_rows names the pairs that enter or leave that graph from one frame to the next. ASE adapters accept nonsingular cells periodic in all three directions and preserve cell orientation and displacement on roundtrip. Hydrogen donors use an ASE mol-id array when present and periodic nearest-atom ownership otherwise. All-atom ASE imports (select=None) use cutoff bonding; hydrogen-bond topology requires a heavy-atom selection such as select="O".

Cutoff, frame, and k follow the same twelve-factor table as seams: SEAMS_CONFIG or ./seams.env, then the environment, then the function argument. pydseams.config is the reader.

import dseams

a = 2.75 * 4 / 3**0.5
sites = (
    (0, 0, 0),
    (0.5, 0.5, 0),
    (0.5, 0, 0.5),
    (0, 0.5, 0.5),
    (0.25, 0.25, 0.25),
    (0.75, 0.75, 0.25),
    (0.75, 0.25, 0.75),
    (0.25, 0.75, 0.75),
)
xyz = [[x * a, y * a, z * a] for x, y, z in sites]
assert dseams.chill_plus(xyz, [a, a, a])[1][0] == 8

dseams reads C-contiguous NumPy arrays in place. box is three edge lengths or the nine LAMMPS numbers ox, oy, oz, lx, ly, lz, xy, xz, yz. cages, signature_cages, and symmetry go through libseams_lang.

Upgrading from 2.11

  • import pydseams and import pydseamslib keep the 2.11 API, including pydseams.yoda, cyoda, and _core.
  • CHILL+ on a cutoff list follows the seams-core 2.14 shell-count fix. On tests/data/exampleTraj.lammpstrj (oxygen, type 2) Frame.chill_plus() reports 9 interClathrate and 241 water, where 2.11 reported 12 and 238.
  • FrameFingerprint and KeyLibrary also expose colored; coloured still works.
  • dseams is new. dseams.userframe.Frame is a second Frame over libseams_lang with a graph argument on chill_plus; it is not pydseams.Frame.

Development

The engine is seams-core, a Meson subproject here. subprojects/seams-core.wrap pins tag v2.14.0, and the other wraps carry the revisions that tag pins. Engine changes go to d-SEAMS/seams-core, not to this repository. The contributing guide at the repository root has the layout, the test commands and the commit conventions.

The build needs a C++20 compiler and cargo with Rust 1.88 or newer (linkcell, minimage and readcon are Rust crates; readcon-core and readcon-db declare rust-version = "1.88"). Installing the sdist builds the same tree, so it needs them too:

meson setup bbdir --force-fallback-for=eigen3
meson compile -C bbdir
meson test -C bbdir --suite pydseamslib

To build against a local seams-core checkout, put it where the wrap would: Meson uses an existing subprojects/seams-core directory and does not fetch the pinned revision.

ln -s /path/to/seams-core subprojects/seams-core
meson setup --wipe bbdir --force-fallback-for=eigen3

The tests that read seams-core inputs (input/traj/...) take them from SEAMS_CORE_SRC, else subprojects/seams-core.

Release order:

  1. d-SEAMS/seams-core tags vX.Y.Z.
  2. subprojects/seams-core.wrap moves to that tag, and the version in pyproject.toml, meson.build, src/pydseams/__init__.py, tests/python/test_bindings.py and CITATION.cff becomes X.Y.Z.
  3. towncrier build --version X.Y.Z, then tag vX.Y.Z on d-SEAMS/PydSEAMSlib.
  4. build_wheels.yml builds the sdist and the wheels and publishes them to PyPI through trusted publishing from d-SEAMS/PydSEAMSlib.

llms.txt at the repository root, also served at the docs site root, lists the documentation pages.

Primary author: Ruhila S. The project started as PSF GSoC 2023 (pyseams).

Requires Python 3.11+. CPython 3.11 has a version-specific wheel. Python 3.12 and newer use the CPython 3.12 stable ABI (one abi3 wheel per platform). Free-threaded CPython has no limited ABI and is not a target.

License

MIT.

Metadata

Release files for pydseamslib 2.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pydseamslib 2.14.0
File Size Uploaded Provenance Actions
pydseamslib-2.14.0.tar.gz 12.9 MB With provenance Details for pydseamslib-2.14.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for pydseamslib 2.14.0
File Actions
pydseamslib-2.14.0-cp312-abi3-manylinux_2_28_x86_64.whl CPython 3.12 abi3 Linux glibc 2.28+ x86-64 Details for pydseamslib-2.14.0-cp312-abi3-manylinux_2_28_x86_64.whl
pydseamslib-2.14.0-cp312-abi3-manylinux_2_28_aarch64.whl CPython 3.12 abi3 Linux glibc 2.28+ ARM64 Details for pydseamslib-2.14.0-cp312-abi3-manylinux_2_28_aarch64.whl
pydseamslib-2.14.0-cp312-abi3-macosx_14_0_x86_64.whl CPython 3.12 abi3 macOS 14.0+ x86-64 Details for pydseamslib-2.14.0-cp312-abi3-macosx_14_0_x86_64.whl
pydseamslib-2.14.0-cp312-abi3-macosx_14_0_arm64.whl CPython 3.12 abi3 macOS 14.0+ ARM64 Details for pydseamslib-2.14.0-cp312-abi3-macosx_14_0_arm64.whl
pydseamslib-2.14.0-cp311-cp311-manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64 Details for pydseamslib-2.14.0-cp311-cp311-manylinux_2_28_x86_64.whl
pydseamslib-2.14.0-cp311-cp311-manylinux_2_28_aarch64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ ARM64 Details for pydseamslib-2.14.0-cp311-cp311-manylinux_2_28_aarch64.whl
pydseamslib-2.14.0-cp311-cp311-macosx_14_0_x86_64.whl CPython 3.11 CPython 3.11 macOS 14.0+ x86-64 Details for pydseamslib-2.14.0-cp311-cp311-macosx_14_0_x86_64.whl
pydseamslib-2.14.0-cp311-cp311-macosx_14_0_arm64.whl CPython 3.11 CPython 3.11 macOS 14.0+ ARM64 Details for pydseamslib-2.14.0-cp311-cp311-macosx_14_0_arm64.whl

Total release size: 123.9 MB

Release files / pydseamslib-2.14.0.tar.gz

Download URL pydseamslib-2.14.0.tar.gz
Size 12.9 MB
Tags Source
SHA-256 checksum
How to use checksums
ae57974456f97a81dbcae13196a16237f554690cdf852723b878716e2d83d319
BLAKE2b-256 checksum
How to use checksums
b7994c95981c9188264ab5dc73ab2447f0bf2970f6fc5571b41bbe0339048ae5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pydseamslib-2.14.0-cp312-abi3-manylinux_2_28_x86_64.whl

Download URL pydseamslib-2.14.0-cp312-abi3-manylinux_2_28_x86_64.whl
Size 18.8 MB
Tags CPython 3.12 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
eed58a1383105cbe875e2c06fb2500a49624a2d101ec1f9f34e788f2fe4c9bac
BLAKE2b-256 checksum
How to use checksums
18d61535faefaae1858c5c3d6acf45c614602d4c5255b5f484e5a6362c9ef4f0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pydseamslib-2.14.0-cp312-abi3-manylinux_2_28_aarch64.whl

Download URL pydseamslib-2.14.0-cp312-abi3-manylinux_2_28_aarch64.whl
Size 16.7 MB
Tags CPython 3.12 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
f4fe0e0270ec02f13080b21fa5f05ac56ce0888a2ea71ced5a66dcb3a03516b7
BLAKE2b-256 checksum
How to use checksums
1a894ea632f26652782c972e68001823bb8f67eeb96141ce35f4c9e8f14b36f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pydseamslib-2.14.0-cp312-abi3-macosx_14_0_x86_64.whl

Download URL pydseamslib-2.14.0-cp312-abi3-macosx_14_0_x86_64.whl
Size 10.8 MB
Tags CPython 3.12 abi3 macOS 14.0+ x86-64
SHA-256 checksum
How to use checksums
ccb7219438959bd5d347d1c60a24b4c0052bc554bc50f0f79a6e97877a79ccde
BLAKE2b-256 checksum
How to use checksums
5e85bcb071f1e5010822ab1ec36cf63d8e0dd6ecb22454bda536c2e76e2ee464
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pydseamslib-2.14.0-cp312-abi3-macosx_14_0_arm64.whl

Download URL pydseamslib-2.14.0-cp312-abi3-macosx_14_0_arm64.whl
Size 9.1 MB
Tags CPython 3.12 abi3 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
5458e955248935367e75d7adc45bce917c9b42001cd49ee9246ad701f7d2e6e0
BLAKE2b-256 checksum
How to use checksums
7124f9d4a8ed93c46a87a6e3306df5e7c07dc0499a427cc335ceb0541b8561a3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pydseamslib-2.14.0-cp311-cp311-manylinux_2_28_x86_64.whl

Download URL pydseamslib-2.14.0-cp311-cp311-manylinux_2_28_x86_64.whl
Size 18.8 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
4ff5041080240d9aa70f07eda13099ce428a6f9884a44e26f1079d96e1f6be79
BLAKE2b-256 checksum
How to use checksums
c69025219d06c3fe1765dc2e5c3ce013cdae0a5fba66b235a1656c5e0dc1f3ed
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pydseamslib-2.14.0-cp311-cp311-manylinux_2_28_aarch64.whl

Download URL pydseamslib-2.14.0-cp311-cp311-manylinux_2_28_aarch64.whl
Size 16.7 MB
Tags CPython 3.11 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
b8a16d06dde7114fab7a3c7df035e8c0ecf2be0711e764fe22e284d8725fe2af
BLAKE2b-256 checksum
How to use checksums
b940cb351c3b5b64ab719d47670a8c432173a873a9c65f7e91479dc83714ace6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pydseamslib-2.14.0-cp311-cp311-macosx_14_0_x86_64.whl

Download URL pydseamslib-2.14.0-cp311-cp311-macosx_14_0_x86_64.whl
Size 10.8 MB
Tags CPython 3.11 macOS 14.0+ x86-64
SHA-256 checksum
How to use checksums
e95e54da207ac2fe288ddffdb5ec5fb866e9c729882832a1b572dd925ff420cc
BLAKE2b-256 checksum
How to use checksums
c259c17dc7dcf16372574aecb423cd12275ee6dc3c7f999e3860b3a053eade57
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pydseamslib-2.14.0-cp311-cp311-macosx_14_0_arm64.whl

Download URL pydseamslib-2.14.0-cp311-cp311-macosx_14_0_arm64.whl
Size 9.1 MB
Tags CPython 3.11 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
8a580af29c4ecc56606591e288c1d232ddcaf2b06eb1a83277c63c6d8d4ba1b6
BLAKE2b-256 checksum
How to use checksums
8dbb23fc51b22cdd2d4a5dcb7fc127b2db2b2c715b6d23239edb58f195ff8cd7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for pydseamslib 2.14.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 9 files in this release have been uploaded with provenance metadata.

Select from 9 files

Attestation for pydseamslib-2.14.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page