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¶
PointCloudAtom positions, types, box, and per-atom ice labels.
neighListO/kNearestNeighbourListCutoff and k-nearest graphs.
bondGraphFromNameacceptscutoff,knn,knn-union.populateHbondsGeometric hydrogen bonds. Needs hydrogens (re-read from a dump, or an explicit H cloud). Water uses the two-hydrogen
hAtomMolListset.populateHbondsFromDonorstakes an explicit per-heavy donor-H index list.getCorrelPlus/getIceTypePlusCHILL+. Four-neighbour
c_ij, then cubic / hexagonal / interfacial / clathrate / water.cageAffiliation/seededCageAffiliationIce score on six-rings. HC = Ih, DDC = Ic, neither = water. Not the CHILL+ star. The fifth argument of
seededCageAffiliationisringAdjacentCompletion(defaultfalse;seams cages --completesets it). See Ring-adjacent completion.ringNetworkFranzblau 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.