Contributing

This repository is the C++ engine (libyodaLib), the C API libseams, the C ABI libseams_lang, the seams CLI and the engine drivers. Each language binding (Python, Lua and Fennel, R, Julia, Rust, Fortran) is its own repository. The repository map says what lives where, how each binding pins and tests against a seams-core tag, the release order, and how to develop seams-core and a binding together. Do not add a language binding here.

Documentation is authored in docs/orgmode/ and exported with docs/export.el (ox-rst) before Sphinx. Run pixi run -e docs docbld to export, run doxyrest, build the Shibuya site, and write the sibling doxyYoda C++ tree to docs/build/api-cpp/. That command is also what publishes the site. The Deployment section below names the two Docs jobs.

Prerequisites

Two supported compiler shells:

  • pixi (locked conda-forge toolchain)

  • nix develop (flake inputs: compiler, Eigen, BLAS, Catch2, gdb)

curl -fsSL https://pixi.sh/install.sh | bash

pixi provides a compiler, Eigen, BLAS/LAPACK, Catch2, Meson, Ninja, Highway and chemfiles. Optional pixi features add IRA, sphericart, nauty, MPI, the docs stack, and the Coq/SymPy proofs.

Clone and build

git clone https://github.com/d-SEAMS/seams-core.git
cd seams-core

pixi:

pixi run setup
pixi run build
pixi run test

pixi run setup configures bbdir/ with tests and the seams CLI (-Dwith_tests=true). pixi run build compiles libyodaLib, libseams, and seams. pixi run test runs the suite.

Nix:

nix develop
meson setup bbdir -Dwith_tests=true
meson compile -C bbdir
meson test -C bbdir
./bbdir/seams read input/traj/exampleTraj.lammpstrj

nix build is the same package plus the install check.

Project structure

seams-core/
  src/                   C++ engine
    seams_cli.cpp        seams (Argum)
    include/internal/    engine headers
    include/external/    vendored headers (argum, backward, ...)
    mol_sys.cpp          PointCloud
    neighbours.cpp       cutoff / knn / knn-union lists
    bond.cpp             hydrogen bonds
    bop.cpp              CHILL / CHILL+
    ring.cpp             ring classification
    franzblau.cpp        Franzblau shortest-path rings
    cage_affiliation.cpp HC / DDC ice score
    bulkTUM.cpp          topological unit matching
    topo_one_dim.cpp     nanotubes
    topo_two_dim.cpp     sheets
  tests/                 Catch2 binaries and walk_compare
  lean/                  Lean 4 model of ringAdjacentCompletion
  input/traj/            example LAMMPS dumps
  input/xyz/             fixtures
  input/eon/             eOn .con fixture
  meson.build            Meson project
  meson_options.txt      with_tests, with_cli, optional backends
  flake.nix              nix build / nix develop
  pixi.toml              pixi workspace

Core concepts

PointCloud

Atom positions, types, box, and per-atom ice labels.

neighListO / kNearestNeighbourList

Cutoff and k-nearest graphs. bondGraphFromName accepts cutoff, knn, knn-union.

populateHbonds

Geometric hydrogen bonds. Needs hydrogens (re-read from a dump, or an explicit H cloud). Water uses the two-hydrogen hAtomMolList set. populateHbondsFromDonors takes an explicit per-heavy donor-H index list.

getCorrelPlus / getIceTypePlus

CHILL+. Four-neighbour c_ij, then cubic / hexagonal / interfacial / clathrate / water.

cageAffiliation / seededCageAffiliation

Ice score on six-rings. HC = Ih, DDC = Ic, neither = water. Not the CHILL+ star. The fifth argument of seededCageAffiliation is ringAdjacentCompletion (default false; seams cages --complete sets it). See Ring-adjacent completion.

ringNetwork

Franzblau primitive rings up to a depth.

Tests

pixi run test
nix develop --command meson test -C bbdir

C++ tests are Catch2. Python tests live in PydSEAMSlib.

tests/walk_compare is a Meson executable. Inputs and columns live on walk_compare.

Lean 4 statements about ring::ringAdjacentCompletion live in lean/. See Lean proofs.

Optional pixi environments: pixi run -e ira ..., sphericart, nauty, mpi, docs, formalanalysis, repro.

Style

Install the clang-format hook:

./scripts/git-pre-commit-format install

Commit subjects follow fileName: description of change. See CONTRIBUTING.md in the repository root.

Releases

The three-repo cut (libyodaLib / seams, then the PydSEAMSlib and yodaStruct wraps) is Release process. The checked statements are Lean proofs.

Deployment

Docs deploy from d-SEAMS/seams-core main to gh-pages, which Netlify serves at https://docs.dseams.info. .github/workflows/ci_docs.yml has two jobs. build-deploy checks out the tree, builds libseams and seams, installs pydseamslib from the matching PydSEAMSlib tag, and runs DOCS_CI=1 pixi run -e docs docbld. That build draws the molecule stills and the science gallery and copies llms.txt to the site root. Mermaid, lychee, and the sitemap check read docs/build. Those three are what stand in front of the publish. The job then pushes docs/build with GITHUB_TOKEN on that upstream main push. A fork push does not publish the site. The tutorial, C and C++, snippet, linkcheck, and doctest commands run in verify, with the Python snippets against the installed pydseamslib. They still fail the workflow when they fail. They do not block the publish.