Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

dseams

dseams is the safe Rust crate for d-SEAMS, the ice, clathrate and ring engine for molecular simulation frames. The engine, the C API (libseams, header seams.h) and the command-line tool live in seams-core. This book documents the two crates in this repository:

CrateLibraryRole
dseams-sysseams_sysRaw declarations generated from seams.h
dseamsseamsOwned handles, options structs, iterators, Result errors

The crates.io name seams belongs to an unrelated project, so the packages are dseams-sys and dseams. Code still says use seams::System.

fn main() -> Result<(), seams::Error> {
    let (xyz, edge) = seams::diamond8();
    seams::set_num_threads(1)?;
    let mut system = seams::System::new()?;
    system.set_ortho(&xyz, edge, edge, edge)?;
    let ice = system.chill_plus(&seams::ChillOptions::default())?;
    assert_eq!(ice.counts[seams::Label::Cubic as usize], 8);
    Ok(())
}

Coordinates and cutoffs are angstroms. A cell is nine LAMMPS numbers: origin, edge lengths, then the tilts xy, xz, yz.

In this book

The layout follows the same four-part shape as the NumPy documentation.

  • Getting started installs the crate, links libseams, and classifies the eight-atom cubic cell.
  • The user guide is the tutorials and the how-to pages.
  • The API reference is the rustdoc generated from the crates.
  • Development is how to build, test, and regenerate the declarations.

The engine book, including the C API and the science tutorials, is docs.dseams.info. Its Rust page is the stable Rust guide, and the C header reference is the stable C API.

The recording runs the ice Ih census from Rust:

Cite the 2020 paper, DOI 10.1021/acs.jcim.0c00031, as recorded in CITATION.cff.

Getting started

This page installs dseams 2.14.0, points the build at libseams, and classifies one cubic cell. The recording is the Rust front on ice Ih.

Rust on ice Ih.

Add the crate

Rust 1.85 or newer builds the crates.

[dependencies]
dseams = "2.14.0"

cargo add dseams writes the same line. The library name is seams.

dseams-sys does not run bindgen. The declarations are already in the crate. The build script takes the first match:

  1. SEAMS_LIBDIR (or SEAMS_LIB_DIR): the directory that holds the shared libseams. A meson build uses bbdir/src. An install prefix uses lib. Set SEAMS_INCLUDE to the header directories when seams.h is not in the sibling include directory. For the meson tree that this repository’s CI builds, that is the seams-core include directory plus bbdir/src.
  2. Feature bundled: compile the C API and Eigen 3.4.0 with the cc crate. This needs x86_64 and a C++20 compiler with OpenMP. The shell classifier uses AVX2. The bundled copy reads LAMMPS dumps and XYZ. .con files and the chemfiles formats need a libseams that was built with those readers. Fill dseams-sys/vendor/ with python3 dseams-sys/vendor.py, or set SEAMS_SOURCE_DIR to a seams-core checkout at the commit in seams-core.env. SEAMS_LIBDIR still wins when it is set.
  3. pkg-config module seams, at least 2.14.0 and below 3.0.0. A seams_version.h from another major release, or from an older minor release, stops the build.

The link how-to has the commands for each path.

Tests and examples in this workspace receive an rpath to SEAMS_LIBDIR. A binary in another crate needs that directory on LD_LIBRARY_PATH at run time. The bundled build links a static library, so it has no rpath.

Classify the eight-atom cell

diamond8 returns the eight-atom cubic diamond and its lattice constant, 2.75 * 4 / sqrt(3) angstroms. The nearest-neighbour distance is 2.75 angstroms. ChillOptions::default uses a 3.5 angstrom cutoff, the cutoff graph, and the published CHILL+ table. Every atom is cubic:

fn main() -> Result<(), seams::Error> {
    let (xyz, edge) = seams::diamond8();
    seams::set_num_threads(1)?;
    let mut system = seams::System::new()?;
    system.set_ortho(&xyz, edge, edge, edge)?;
    let ice = system.chill_plus(&seams::ChillOptions::default())?;
    assert_eq!(ice.labels.len(), 8);
    assert_eq!(ice.counts[seams::Label::Cubic as usize], 8);
    Ok(())
}

set_num_threads is process-global. 1 makes the following call single-threaded. ice.counts[label as usize] is the population of that label. The nine labels, in count order, are Cubic, Hexagonal, Water, Interfacial, Clathrate, Interclathrate, Unclassified, Recubic, and Rehex.

From a checkout of this repository, with SEAMS_LIBDIR set:

cargo run --example ice_ih
cargo test --doc -- --test-threads=1

ice_ih reads the ice Ih dump shipped in the crate and prints

rust ice nop 128 q6 0.625855 hexagonal 128 rings 256

That line is locked by the example’s test. The ice Ih tutorial walks through it. The engine book is docs.dseams.info.

User guide

The tutorials start from a frame and end at a number the crate’s tests lock, or at a call the rustdoc examples compile. The how-to pages answer one setup question each.

The engine tutorials for the same science, with the seams command and the full trajectories, are in the d-SEAMS book.

Tutorials

  • Ice Ih reads the 128-molecule cell and prints the census every language front prints.
  • Bulk ice compares the cubic diamond with the sI clathrate cell.
  • Cages scores hexagonal and double-diamond membership.
  • Rings counts primitive rings.
  • An ice-water interface reads CHILL+ labels along a slab.
  • Brine measures a planar ice front from an ice assignment.
  • Nucleation summarises Lechner-Dellago q6-bar.

How-to

Tutorial: ice Ih

Read the ice Ih dump shipped with the crate, then print the neighbour, ring, and CHILL+ census. The same recording is the Rust front on that cell.

Rust on ice Ih.

The dump

dseams/tests/data/ice1h.lammpstrj is one frame of 128 atoms, LAMMPS type

  1. System::read takes a 1-based frame index. The type filter 1 keeps type 1. A negative filter keeps every atom; on this file both selections are the 128 waters.

From a checkout, with libseams linked:

cargo run --example ice_ih
cargo run --example lang_tasks

ice_ih prints a line the example test requires exactly:

rust ice nop 128 q6 0.625855 hexagonal 128 rings 256

nop is System::count. q6 is the mean of q4q6(3.5).q6, printed to six digits. hexagonal is counts[Label::Hexagonal as usize] from chill_plus with ChillOptions::default (cutoff 3.5 angstroms, cutoff graph, published table). rings is the number of primitive six-rings, the first element of six_ring_fraction.

The shared census

lang_tasks prints the one line every d-SEAMS language front prints for this file. The example test requires:

pairs 512 rings 0 0 0 0 0 0 256 chill 0 128 0 0 0 0 0 0 0

pairs is Neighbours::nnz for NeighbourOptions::default, which is the cutoff graph at 3.5 angstroms. Self pairs are omitted. 512 directed pairs on 128 atoms is four neighbours each.

rings is Rings::histogram(6) for RingOptions with max_size 6. The seven integers are sizes 0 through 6. Size 6 is 256. That is the same six-ring count ice_ih prints. The default ring graph is the cutoff graph.

chill is the nine Classification::counts from chill_plus, in label order: cubic, hexagonal, water, interfacial, clathrate, interfacial clathrate, unclassified, reclassified cubic, reclassified hexagonal. Hexagonal is 128. The other eight populations are 0.

The calls, with the paths the examples use, are:

#![allow(unused)]
fn main() {
use seams::{ChillOptions, Label, NeighbourOptions, RingOptions, System};

fn census(path: &str) -> Result<(), seams::Error> {
    let mut frame = System::new()?;
    frame.read(path, 1, -1)?;
    let pairs = frame.neighbours(&NeighbourOptions::default())?.nnz()?;
    let rings = frame
        .rings(&RingOptions {
            max_size: 6,
            ..RingOptions::default()
        })?
        .histogram(6)?;
    let chill = frame.chill_plus(&ChillOptions::default())?;
    assert_eq!(frame.count(), 128);
    assert_eq!(pairs, 512);
    assert_eq!(rings[6], 256);
    assert_eq!(chill.counts[Label::Hexagonal as usize], 128);
    Ok(())
}
}

Drop frees the system, the neighbour list, and the ring set when those values go out of scope.

The mean local q6 on this frame is the 0.625855 above. q4q6 returns one q4 and one q6 per atom on the cutoff shell. steinhardt with average: true also returns the Lechner-Dellago neighbour mean; the nucleation tutorial uses the q6-bar summary of that average.

The engine tutorial for primitive rings on this cell and on the mixed TIP4P frame is Primitive rings.

Tutorial: bulk ice

Classify two bulk crystals that ship with the crate. CHILL+ labels the cubic diamond cubic, and the sI cell clathrate. The mixed TIP4P dump used by the engine tutorial is not in this repository.

The recordings of the cage search and of primitive rings are on the cages and rings tutorials. The mixed TIP4P walkthrough is Classify ice on the mixed TIP4P example.

Cubic diamond

diamond8 is one conventional cell, eight atoms, edge equal to the lattice constant. chill_plus with the default options labels every atom Label::Cubic (count index 0):

fn main() -> Result<(), seams::Error> {
    let (xyz, edge) = seams::diamond8();
    let mut system = seams::System::new()?;
    system.set_ortho(&xyz, edge, edge, edge)?;
    let ice = system.chill_plus(&seams::ChillOptions::default())?;
    assert_eq!(ice.counts[seams::Label::Cubic as usize], 8);
    Ok(())
}

dseams/examples/ice.rs repeats that cell on a 2 by 2 by 2 grid, 64 atoms, and stores them with set_ortho. The integration test dseams/tests/ice.rs requires every CHILL+ label to be cubic, both for the published table on the cutoff graph and for the OVITO table on the mutual four-neighbour graph. It also requires a mean q6 above 0.3, four neighbours inside 3.5 angstroms for every atom, and a primitive six-ring fraction above one half.

cargo run --example ice

Against libseams 2.14.0 the example prints:

dseams 2.14.0 cubic 64 of 64

sI clathrate

dseams/tests/data/genice_sI.lammpstrj is the oxygen lattice of one GenIce sI cell, 46 atoms. cargo run --example minimal reads it (or the dump path given on the command line), calls set_ortho, and checks:

  • count is 46
  • chill_plus with the default options puts all 46 atoms in Label::Clathrate (count index 4)
  • six_ring_fraction(3.5) reports 54 primitive six-rings
  • the mean of q4q6(3.5).q6 is above 0.5

Against libseams 2.14.0 the example prints:

rust example ok 2.14.0 q6 0.595

The example parses the dump and calls set_ortho. System::read of the same path, frame 1, type 1, is the LAMMPS reader; every atom in the file is type 1.

What the two labels mean

CHILL+ looks at the four neighbours of each atom and marks each bond staggered or eclipsed. Four staggered bonds are cubic. Four eclipsed bonds are clathrate. The sI oxygens are clathrate on that score. Cage membership, in the next tutorial, asks a different question: whether the atom sits in a finished hexagonal cage or a finished double-diamond cage.

Tutorial: cages

Score hexagonal-cage and double-diamond-cage membership, then ask for closed cages of one ring signature.

Ice Ih hexagonal cages, cubic double-diamond cages, then the clathrate cells.

CageOptions::default uses a 3.5 angstrom cutoff, the seeded graph (mutual four-neighbour seeds plus union completions), k of 4, and complete: false. Cages::counts returns four disjoint populations: hexagonal, cubic, water, and both. On the eight-atom diamond those four numbers add up to the atom count:

fn main() -> Result<(), seams::Error> {
    let (xyz, edge) = seams::diamond8();
    let mut system = seams::System::new()?;
    system.set_ortho(&xyz, edge, edge, edge)?;
    let cages = system.cages(&seams::CageOptions::default())?;
    let counts = cages.counts()?;
    assert_eq!(
        counts.hexagonal + counts.cubic + counts.water + counts.both,
        8
    );
    let labels = cages.labels(8)?;
    assert_eq!(labels.len(), 8);
    Ok(())
}

labels is one CageLabel code per atom: Water (0), Hex (1), Cubic (2), or Both (3). Drop frees the cage set.

A signature census

signature_cages counts closed cages whose ring census matches spec. The default spec is "512". On the eight-atom diamond that spec is rejected with Status::Argument:

fn main() -> Result<(), seams::Error> {
    let (xyz, edge) = seams::diamond8();
    let mut system = seams::System::new()?;
    system.set_ortho(&xyz, edge, edge, edge)?;
    let err = system
        .signature_cages(&seams::SignatureOptions::default())
        .unwrap_err();
    assert_eq!(err.status(), Some(seams::Status::Argument));
    Ok(())
}

SignatureMatch holds cages and atoms. SignatureOptions.graph selects the neighbour graph. The default is Graph::Cutoff.

The sI guest frame in seams-core is what dseams/tests/cpp_match.rs compares with the C++ oracle when SEAMS_CPP_ORACLE and SEAMS_SOURCE_ROOT are set. The oxygen-only sI dump in this crate is the bulk ice example: 46 atoms, all CHILL+ clathrate, 54 primitive six-rings.

The engine how-to for the same cage search is Cage search.

Tutorial: rings

Count primitive rings on the ice Ih cell. The recording then shows the same count on the mixed frame and on ice Ih.

Primitive rings on the mixed frame, then on ice Ih.

RingOptions::default is a 3.5 angstrom cutoff, the cutoff graph, and max_size 6 (the largest ring size the search keeps, from 3 through 12). Rings::histogram(6) returns seven bins, index equal to ring size. Rings::fraction is the fraction of atoms that sit on a ring of one size. six_ring_fraction is that pair for size 6: the histogram entry, then the fraction.

On dseams/tests/data/ice1h.lammpstrj the size-6 bin is 256, which is the rings 256 locked by cargo run --example ice_ih and the rings field of the shared census:

pairs 512 rings 0 0 0 0 0 0 256 chill 0 128 0 0 0 0 0 0 0
fn main() -> Result<(), seams::Error> {
    let mut system = seams::System::new()?;
    system.read("dseams/tests/data/ice1h.lammpstrj", 1, 1)?;
    let rings = system.rings(&seams::RingOptions::default())?;
    let hist = rings.histogram(6)?;
    let fraction = rings.fraction(6)?;
    assert_eq!(hist[6], 256);
    assert!(fraction.is_finite());
    let first = rings.vertices(0)?;
    assert!(!first.is_empty());
    for ring in rings.iter().take(1) {
        let _vertices = ring?;
    }
    Ok(())
}

vertices(index) is the atom indices of one ring. iter yields each ring’s vertices as a Result. size is the number of rings. ring_symmetry_name turns a RingSymmetry code into its short name ("pentagon", "hexagon", and the cage-face names).

Drop frees the ring set.

The engine tutorial, including the mixed TIP4P frame this crate does not ship, is Primitive rings.

Tutorial: an ice-water interface

CHILL+ on a slab separates hexagonal ice, cubic ice, interfacial ice, and water. The basal-interface trajectory and its layer profile are in the engine tutorial. This page is the same call from Rust, on a cell the crate ships, and the recording of that basal frame.

CHILL+ on the basal interface.

ChillOptions holds the cutoff (default 3.5 angstroms), a species filter (0 keeps every atom), the neighbour Graph (Cutoff, Mutual, or Seeded), and the ChillRule (Published or Ovito). Published edges are inclusive. OVITO edges are open.

fn main() -> Result<(), seams::Error> {
    let mut system = seams::System::new()?;
    system.read("dseams/tests/data/ice1h.lammpstrj", 1, 1)?;
    let ice = system.chill_plus(&seams::ChillOptions::default())?;
    assert_eq!(ice.counts[seams::Label::Hexagonal as usize], 128);
    assert_eq!(ice.counts[seams::Label::Interfacial as usize], 0);
    let _name = seams::label_name(seams::Label::Interfacial);
    Ok(())
}

chill is the original CHILL classifier and returns the same Classification shape: labels, one code per atom, and counts, nine populations in Label order. label_name is the short name of a code. On this ice Ih frame the interfacial count is 0 because every atom is hexagonal. A mixed slab is where Label::Interfacial and Label::Water become nonzero.

set_frame stores a tilted cell. The nine numbers are origin (ox, oy, oz), edge lengths (lx, ly, lz), then tilts xy, xz, yz. Axis::Z is the default axis for the density and brine profiles when you bin that slab.

The basal frame, the layer command, and the recorded stack are in Ice-water interface.

Tutorial: brine

Measure a planar ice front from an ice assignment. The recording is the NaCl front. The ion trajectory itself is in the engine tutorial.

The brine front.

System::brine takes one integer per atom, nonzero when that atom is ice, and a BrineOptions. The slice length must equal count. The default options keep every species (water_type 0, ion_type 0), choose 20 bins when bins is 0, and use Axis::Z.

fn main() -> Result<(), seams::Error> {
    let (xyz, edge) = seams::diamond8();
    let mut system = seams::System::new()?;
    system.set_ortho(&xyz, edge, edge, edge)?;
    let front = system.brine(&[1; 8], &seams::BrineOptions::default())?;
    let _profile = front.profile()?;
    Ok(())
}

Marking every atom ice, as this call does, builds a front on the cubic cell. A trajectory with liquid and ions passes the CHILL+ crystal codes as the ice flags and sets ion_type to the ion species.

Brine owns the C object and frees it on drop. The queries are:

MethodReturns
frontsBrineFronts: enter, exit, and thickness in angstroms, and found when both crossings exist
rejectionRejection: bulk-ice and bulk-liquid molality in mol/kg, their ratio k, and defined
profileBrineProfile: bin centres in angstroms, molality in mol/kg, and a dimensionless ice fraction
pocketsPockets: pocket count, excluding the liquid reservoir, and reservoir_waters

The NaCl frame, the slab table, and the water census of that frame are in Brine and NaCl.

Tutorial: nucleation

Summarise the Lechner-Dellago q6-bar and count atoms above an ice cut. The recording follows a nucleation trajectory. The three-frame mW dump and its cluster table are in the engine tutorial.

Nucleation q6-bar.

Q6BarOptions::default uses a 3.5 angstrom cutoff, species filter 0, and ice_cut 0.36. q6bar returns one value per atom, the mean and median of the finite values, and n_ice, the count strictly above the cut.

fn main() -> Result<(), seams::Error> {
    let (xyz, edge) = seams::diamond8();
    let mut system = seams::System::new()?;
    system.set_ortho(&xyz, edge, edge, edge)?;
    let summary = system.q6bar(&seams::Q6BarOptions::default())?;
    assert_eq!(summary.values.len(), 8);
    assert!(summary.mean.is_finite());
    Ok(())
}

On the eight-atom diamond the value vector has one entry per atom and the mean is finite. n_ice depends on the cut. The same options struct is the nucleation census: raise or lower ice_cut to change n_ice without changing values.

steinhardt with SteinhardtOptions { average: true, ..Default::default() } returns the local q6 and the neighbour mean that q6-bar is built from. order is 6 by default, and may be 3, 4, 6, 8, or 12. ql is the same parameter on a named graph (OrderOptions.graph).

CHILL+ on a growing cluster is a different count from n_ice. Crystal atoms for that cluster are Label::Cubic, Label::Hexagonal, Label::Recubic, and Label::Rehex. The ice Ih tutorial shows the nine-bin counts array those labels index.

The 148-frame trajectory and the per-frame cluster sizes are in Nucleation.

How to: link libseams

dseams-sys links libseams at build time. The script in dseams-sys/build.rs stops at the first match below. A seams_version.h from another major, or from a minor older than 2.14, stops the build when that header is on the include path.

A seams-core build tree

CI builds seams-core at the commit in seams-core.env and points the crates at that library:

export SEAMS_LIBDIR="$PWD/../seams-core/bbdir/src"
export SEAMS_INCLUDE="$PWD/../seams-core/include:$SEAMS_LIBDIR"
cargo test -- --test-threads=1
cargo test --examples -- --test-threads=1

SEAMS_LIB_DIR is the same variable as SEAMS_LIBDIR. The directory must contain libseams.so (or libseams.dylib, seams.dll, or seams.lib). For a meson build the shared library is bbdir/src when the build directory is bbdir. An install prefix uses $prefix/lib, and the headers default to $prefix/include when seams.h is there.

SEAMS_INCLUDE is a path list. The meson tree keeps seams.h in the source include directory, not next to bbdir/src, so the variable has to name both.

Tests and examples of this workspace get an rpath to SEAMS_LIBDIR. Any other binary needs that directory on LD_LIBRARY_PATH.

pkg-config

Unset SEAMS_LIBDIR. Put the directory that holds seams.pc on PKG_CONFIG_PATH. For the same meson tree that file is bbdir/meson-uninstalled.

unset SEAMS_LIBDIR
export PKG_CONFIG_PATH="$PWD/../seams-core/bbdir/meson-uninstalled"
cargo test -- --test-threads=1

The accepted versions are 2.14.0 up to, and not including, 3.0.0. The installed library keeps every reader it was configured with, including .con and chemfiles when those options were on.

The bundled feature

python3 dseams-sys/vendor.py
cargo test --features bundled --test ice --examples -- --test-threads=1

vendor.py writes dseams-sys/vendor/ from the commit in seams-core.env and from the Eigen 3.4.0 tarball. vendor/ is gitignored. python3 dseams-sys/vendor.py --source ../seams-core archives that commit out of a checkout that already has it.

Without vendor/, SEAMS_SOURCE_DIR may name a checkout at the same commit. Eigen then comes from EIGEN3_INCLUDE_DIR or from pkg-config module eigen3 at 3.4.0 or newer.

The bundled build is x86_64 only, because shell_classify.cpp uses AVX2. It needs a C++20 compiler and OpenMP (GCC links gomp, Clang links omp). It reads LAMMPS dumps and XYZ. .con and chemfiles stay on the pkg-config or SEAMS_LIBDIR library. SEAMS_LIBDIR still wins when it is set, including over --features bundled.

The published crate ships a filled vendor/, so a downstream --features bundled build does not run vendor.py.

How to: read a trajectory

A System owns one frame. Four calls fill it.

CallWhat it stores
set_ortho(xyz, lx, ly, lz)Coordinates in an orthorhombic cell whose origin is zero. xyz is x, y, z triples, in angstroms.
set_frame(xyz, box9)Coordinates and a nine-number cell: ox, oy, oz, lx, ly, lz, xy, xz, yz.
set_atoms(xyz, box9, types, ids)The same cell, plus optional species and ids. Empty slices leave those columns unset.
read(path, frame, type_filter)One frame from a path. frame is 1-based. A negative type_filter keeps every atom.

count is the number of points. It is 0 until one of those calls succeeds.

fn main() -> Result<(), seams::Error> {
    let (xyz, edge) = seams::diamond8();
    let mut ortho = seams::System::new()?;
    ortho.set_ortho(&xyz, edge, edge, edge)?;
    assert_eq!(ortho.count(), 8);

    let mut box9 = [0.0; 9];
    box9[3] = edge;
    box9[4] = edge;
    box9[5] = edge;
    box9[6] = 0.3;
    let mut tilted = seams::System::new()?;
    tilted.set_frame(&xyz, &box9)?;
    assert_eq!(tilted.count(), 8);
    Ok(())
}

read accepts XYZ, CON, a chemfiles format, or a LAMMPS dump when the linked libseams was built with that reader. The bundled library reads LAMMPS dumps and XYZ. The ice dumps in this crate are LAMMPS, every atom type 1:

fn main() -> Result<(), seams::Error> {
    let mut system = seams::System::new()?;
    system.read("dseams/tests/data/ice1h.lammpstrj", 1, 1)?;
    assert_eq!(system.count(), 128);
    Ok(())
}

nframes(path) counts frames in a trajectory. A nul byte inside the path is rejected before the call reaches the library; code() is 4 (SEAMS_ERR_ARG) and message() is text contains a nul.

examples/ice_ih.rs and examples/lang_tasks.rs call read. examples/minimal.rs parses a LAMMPS dump in Rust and calls set_ortho, which is the path its test locks.

How to: handle errors

Fallible calls return Result<T, seams::Error>. Error is one of three variants.

VariantWhen
Library { status, message }The C call failed with a status this crate names. message is seams_handle_error for that handle.
Other { code, message }The library returned a status code this crate does not name.
Argument { message }The value cannot cross the C boundary, such as a nul inside a path, or a coordinate slice whose length is not a multiple of 3.

status() is Some only for Library. code() is the status integer. An Argument uses code 4. message() is the detail text. Display prints the message and the status name.

An empty system has no frame. chill_plus then returns Status::State:

fn main() -> Result<(), seams::Error> {
    let mut system = seams::System::new()?;
    let err = system
        .chill_plus(&seams::ChillOptions::default())
        .expect_err("an empty frame has no coordinates");
    assert_eq!(err.status(), Some(seams::Status::State));
    assert_eq!(err.code(), seams::Status::State as i32);
    Ok(())
}

The named statuses, and their integer values, are Ok (0), Null (1), Range (2), Cell (3), Argument (4), State (5), Memory (6), and Internal (7).

Ownership

System, Neighbours, Rings, Cages, Fingerprint, and Brine own their C pointers. Moving a handle moves that ownership. Dropping it calls the matching destroy function. The raw pointer is not part of the public API.

A handle is Send. It is not Sync: the C library requires exclusive use of one handle. Two frames on two threads may run steinhardt, ql, q4q6, or q6bar at the same time. set_num_threads is process-global. Do not call it while another thread is inside the library. Zero restores the library default. num_threads reads the width the next call will use.

API reference

The reference is rustdoc, generated from the crate source. Every public type, function, field, and enum variant in dseams and dseams-sys is in that output. This site carries the pages for seams and seams_sys. dseams denies missing documentation, and each public item carries a doctest.

Build it from this repository:

# The docs.rs build: rustdoc does not link libseams.
DOCS_RS=1 cargo doc --no-deps --open

# The same pages, linked against a library you built.
export SEAMS_LIBDIR=/path/to/seams-core/bbdir/src
export SEAMS_INCLUDE=/path/to/seams-core/include:$SEAMS_LIBDIR
cargo doc --no-deps --open

cargo doc writes target/doc/seams/index.html for the safe crate and target/doc/seams_sys/index.html for the raw declarations. The package field documentation names the docs.rs pages of the published dseams and dseams-sys crates.

seams::ffi is the re-export of seams_sys. Most programs use the safe crate. The raw names (seams_chill_plus, SEAMS_OK, and the opaque handles) are the C API, documented in the engine book at the stable C API.

docs/check_rustdoc.py reads those HTML pages after cargo doc and fails if a public symbol is absent. The development page runs it.

Safe crate

One frame and the calls that fill it.

ItemRole
SystemOne frame. new, set_ortho, set_frame, set_atoms, read, count, and every analysis.
diamond8Eight-atom cubic diamond and its lattice constant.
nframesFrame count of a trajectory path.
version, abiLibrary version text, and the ABI number (1).
set_num_threads, num_threadsProcess-global OpenMP width.

Ice labels.

ItemRole
System::chill, System::chill_plusOriginal CHILL and CHILL+. Both return Classification.
ChillOptionsCutoff, species filter, Graph, and ChillRule.
Label, label_nameNine label codes and their short names. counts[label as usize] is the population.
ChillRulePublished or Ovito.

Order parameters.

ItemRole
System::q4q6Local q4 and q6 on the cutoff shell. Returns Q4Q6.
System::steinhardtLocal q_l, and the Lechner-Dellago mean when average is set. Returns Steinhardt.
System::qlq_l on a named graph. OrderOptions.
System::q6barq6-bar, its mean and median, and the count above ice_cut. Q6BarOptions, Q6Bar.

Neighbours, rings, and cages.

ItemRole
System::neighbours, System::knn, System::neighbour_degreeCutoff or mutual list, k-nearest list, or the degree of each atom.
Neighboursnnz, degrees, and pairs, which yields NeighbourPair.
GraphCutoff, Mutual, or Seeded.
System::rings, System::six_ring_fractionPrimitive rings. Rings has size, vertices, histogram, fraction, and iter.
RingSymmetry, ring_symmetry_nameSymmetry class of a primitive ring.
System::cages, System::signature_cagesHexagonal and double-diamond membership, or closed cages of one signature.
Cages, CageCounts, CageLabelOwned membership, the four disjoint counts, and the per-atom code.
SignatureOptions, SignatureMatchSignature text such as 512, and the cage and atom totals.

Distributions, bonds, and topology.

ItemRole
System::rdf, System::running_cn, System::coordinationPartial RDF (Distribution), running coordination, and the integral to rmax.
System::densityNumber density along one Axis. DensityOptions, DensityProfile.
System::hbondsHydrogen-bond count. BondOptions.
System::site_table, System::contact_pairs, System::domainsSite kinds, unlike contacts, and the largest polar or apolar domain.
SiteKind, DomainSubset, DomainOptions, DomainReport, ContactsThe codes and the reports those calls return.
System::fingerprintTopological fingerprint. Fingerprint exposes key, atom, and rings.
System::prisms, System::monolayer, System::symmetryPrism stacks, a monolayer ring histogram, and per-atom ice-shell labels.

Brine and errors.

ItemRole
System::brinePlanar ice front from an ice assignment. BrineOptions selects species, bins, and Axis.
Brinefronts, rejection, profile, pockets.
BrineFronts, Rejection, BrineProfile, PocketsThe four reports. Lengths are angstroms. Molality is mol/kg.
Error, StatusA failed call. status, code, and message.

Handles (System, Neighbours, Rings, Cages, Fingerprint, Brine) are Send and not Sync. Drop frees the C object.

Development

The engine, the C API, and the C++ oracle live in seams-core. This repository is the Rust side: the safe crate, the generated declarations, the build script, this book, and the examples. A new analysis or a new C function lands in seams-core first. It is wrapped here after SEAMS_CORE_REF in seams-core.env moves to a commit that contains it.

Contributor conventions for this repository are in AGENTS.md at the repository root. The engine book is docs.dseams.info.

Build and test

Build seams-core at the pinned commit with tests enabled, then run the checks from the repository root. The workflow file .github/workflows/ci.yml is the same sequence.

. ./seams-core.env
git clone "$SEAMS_CORE_REPO" ../seams-core
git -C ../seams-core checkout "$SEAMS_CORE_REF"
(cd ../seams-core && pixi run meson setup bbdir -Dwith_tests=true -Dwith_cli=false \
 && pixi run ninja -C bbdir src/libseams.so bindings/binding_oracle)

export SEAMS_LIBDIR=$PWD/../seams-core/bbdir/src
export SEAMS_INCLUDE=$PWD/../seams-core/include:$SEAMS_LIBDIR
export SEAMS_CPP_ORACLE=$PWD/../seams-core/bbdir/bindings/binding_oracle
export SEAMS_SOURCE_ROOT=$PWD/../seams-core
export OMP_NUM_THREADS=1

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test -- --test-threads=1
cargo test --examples -- --test-threads=1
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

dseams/tests/ice.rs calls every safe wrapper on the cubic cell. dseams/tests/cpp_match.rs compares those analyses with the C++ oracle on ice Ih, sI, an XYZ file, a CON file, and the triclinic sH dump. It skips, and says so, when SEAMS_CPP_ORACLE or SEAMS_SOURCE_ROOT is unset. dseams/examples/ holds ice, minimal, ice_ih, lang_tasks, and binding_overhead. cargo test --examples checks their output.

Unset SEAMS_LIBDIR and set PKG_CONFIG_PATH=$PWD/../seams-core/bbdir/meson-uninstalled to test the pkg-config path against the same tree.

The bundled feature, from a filled dseams-sys/vendor/:

python3 dseams-sys/vendor.py --source ../seams-core
cargo clippy --features bundled --all-targets -- -D warnings
cargo test --features bundled --test ice --examples -- --test-threads=1
cargo +1.85.0 build --features bundled --all-targets

1.85.0 is the minimum supported compiler (rust-version in the workspace manifest).

Declarations

dseams-sys/src/lib.rs is generated. Regenerate it when seams.h changes, and do not edit it by hand:

python3 dseams-sys/gen_sys.py ../seams-core/include/seams.h dseams-sys/src/lib.rs

CI diffs that file against the generator output for the pinned header. dseams-sys/sources.txt lists the translation units the bundled feature compiles, relative to seams-core. Update it when the link closure of src/seams_api.cpp changes.

Documentation

This book is the user-facing documentation:

mdbook build docs

mdBook 0.5.4 is the version CI installs. The API reference is rustdoc, as the API page describes. After cargo doc --no-deps --workspace, the coverage check fails if a public symbol is missing from the HTML:

DOCS_RS=1 cargo doc --no-deps --workspace
python3 docs/check_rustdoc.py target/doc
python3 docs/check_book.py docs/book

check_rustdoc.py parses dseams/src/lib.rs and dseams-sys/src/lib.rs. Hiding a public item from rustdoc fails that check. check_book.py checks the built HTML: internal links, the tutorial recordings, and the engine-book links.

Changelog

User-visible changes add a fragment under changelog.d/. The names and the types are in changelog.d/README.md. Commits use Conventional Commits.

The release order, from the seams-core tag through cargo publish and the tag on this repository, is in AGENTS.md.