Contributing¶

This repository is the C++ engine (libyodaLib) and the seams CLI. Python bindings are PydSEAMSlib. Lua/Fennel is yodaStruct. 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, and build the Shibuya site.

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.

-Dwith_python=true and -Dwith_lua=enabled are Meson errors that name the front-end repositories.

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 -Dwith_python=false). pixi run build compiles libyodaLib and seams. pixi run test runs the Catch2 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
  input/traj/            example LAMMPS dumps
  input/xyz/             fixtures
  input/con/             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).
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.
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.

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.