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:
| Crate | Library | Role |
|---|---|---|
dseams-sys | seams_sys | Raw declarations generated from seams.h |
dseams | seams | Owned 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.
Link libseams
dseams-sys does not run bindgen. The declarations are already in the
crate. The build script takes the first match:
SEAMS_LIBDIR(orSEAMS_LIB_DIR): the directory that holds the sharedlibseams. A meson build usesbbdir/src. An install prefix useslib. SetSEAMS_INCLUDEto the header directories whenseams.his not in the siblingincludedirectory. For the meson tree that this repository’s CI builds, that is the seams-coreincludedirectory plusbbdir/src.- Feature
bundled: compile the C API and Eigen 3.4.0 with thecccrate. This needs x86_64 and a C++20 compiler with OpenMP. The shell classifier uses AVX2. The bundled copy reads LAMMPS dumps and XYZ..confiles and the chemfiles formats need alibseamsthat was built with those readers. Filldseams-sys/vendor/withpython3 dseams-sys/vendor.py, or setSEAMS_SOURCE_DIRto a seams-core checkout at the commit inseams-core.env.SEAMS_LIBDIRstill wins when it is set. - pkg-config module
seams, at least 2.14.0 and below 3.0.0. Aseams_version.hfrom 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
System::readtakes a 1-based frame index. The type filter1keeps 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:
countis 46chill_pluswith the default options puts all 46 atoms inLabel::Clathrate(count index 4)six_ring_fraction(3.5)reports 54 primitive six-rings- the mean of
q4q6(3.5).q6is 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:
| Method | Returns |
|---|---|
fronts | BrineFronts: enter, exit, and thickness in angstroms, and found when both crossings exist |
rejection | Rejection: bulk-ice and bulk-liquid molality in mol/kg, their ratio k, and defined |
profile | BrineProfile: bin centres in angstroms, molality in mol/kg, and a dimensionless ice fraction |
pockets | Pockets: 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.
| Call | What 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.
| Variant | When |
|---|---|
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.
| Item | Role |
|---|---|
System | One frame. new, set_ortho, set_frame, set_atoms, read, count, and every analysis. |
diamond8 | Eight-atom cubic diamond and its lattice constant. |
nframes | Frame count of a trajectory path. |
version, abi | Library version text, and the ABI number (1). |
set_num_threads, num_threads | Process-global OpenMP width. |
Ice labels.
| Item | Role |
|---|---|
System::chill, System::chill_plus | Original CHILL and CHILL+. Both return Classification. |
ChillOptions | Cutoff, species filter, Graph, and ChillRule. |
Label, label_name | Nine label codes and their short names. counts[label as usize] is the population. |
ChillRule | Published or Ovito. |
Order parameters.
| Item | Role |
|---|---|
System::q4q6 | Local q4 and q6 on the cutoff shell. Returns Q4Q6. |
System::steinhardt | Local q_l, and the Lechner-Dellago mean when average is set. Returns Steinhardt. |
System::ql | q_l on a named graph. OrderOptions. |
System::q6bar | q6-bar, its mean and median, and the count above ice_cut. Q6BarOptions, Q6Bar. |
Neighbours, rings, and cages.
| Item | Role |
|---|---|
System::neighbours, System::knn, System::neighbour_degree | Cutoff or mutual list, k-nearest list, or the degree of each atom. |
Neighbours | nnz, degrees, and pairs, which yields NeighbourPair. |
Graph | Cutoff, Mutual, or Seeded. |
System::rings, System::six_ring_fraction | Primitive rings. Rings has size, vertices, histogram, fraction, and iter. |
RingSymmetry, ring_symmetry_name | Symmetry class of a primitive ring. |
System::cages, System::signature_cages | Hexagonal and double-diamond membership, or closed cages of one signature. |
Cages, CageCounts, CageLabel | Owned membership, the four disjoint counts, and the per-atom code. |
SignatureOptions, SignatureMatch | Signature text such as 512, and the cage and atom totals. |
Distributions, bonds, and topology.
| Item | Role |
|---|---|
System::rdf, System::running_cn, System::coordination | Partial RDF (Distribution), running coordination, and the integral to rmax. |
System::density | Number density along one Axis. DensityOptions, DensityProfile. |
System::hbonds | Hydrogen-bond count. BondOptions. |
System::site_table, System::contact_pairs, System::domains | Site kinds, unlike contacts, and the largest polar or apolar domain. |
SiteKind, DomainSubset, DomainOptions, DomainReport, Contacts | The codes and the reports those calls return. |
System::fingerprint | Topological fingerprint. Fingerprint exposes key, atom, and rings. |
System::prisms, System::monolayer, System::symmetry | Prism stacks, a monolayer ring histogram, and per-atom ice-shell labels. |
Brine and errors.
| Item | Role |
|---|---|
System::brine | Planar ice front from an ice assignment. BrineOptions selects species, bins, and Axis. |
Brine | fronts, rejection, profile, pockets. |
BrineFronts, Rejection, BrineProfile, Pockets | The four reports. Lengths are angstroms. Molality is mol/kg. |
Error, Status | A 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.