d-SEAMS

August 16, 2026 · View on GitHub

Deferred Structural Elucidation Analysis for Molecular Simulations

Build Status built with nix

\brief The C++ core of d-SEAMS, a molecular dynamics trajectory analysis engine.

This repository is the C++ engine (libyodaLib) and the seams CLI.

seams read water.lammpstrj
seams chill-plus water.lammpstrj --cutoff 3.5
seams cages water.lammpstrj

Scripting front ends are separate packages:

Periodic k-nearest neighbour search is linkcell.

Build with pixi run setup && pixi run build && pixi run test, or with the Nix flake: nix build and nix develop.

Runtime configuration

Knobs that change between machines and jobs are twelve-factor: they are not compiled in. Defaults live in the binary. An optional dotenv file (SEAMS_CONFIG or ./seams.env) fills unset variables. The process environment wins over the file. CLI flags win over the environment. seams --print-config prints the resolved table.

VariableMeaningDefault
SEAMS_FRAME / SEAMS_LASTFrame range (1-based)1 / unset
SEAMS_JOBSOpenMP frame workers1
SEAMS_TYPEAtom type (0 guesses)0
SEAMS_CUTOFFNeighbour cutoff (Å)3.5
SEAMS_Kk for k-NN / seeded cages4
SEAMS_GRAPHcutoff / knn / knn-union / seededseeded
SEAMS_RESIDENTFraction of free GPU memory for a TUM batch0.80
SEAMS_CELLLink-cell hint so NPT frames share a grid (Å)3.0
SEAMS_OFFLOADOpenMP target Steinhardt (0 disables)on if devices exist
LINKCELL_TPPThreads per particle on the device k-NNoccupancy picker
LINKCELL_BLOCKCUDA block sizeoccupancy picker
YODA_FENNEL_PATH / YODA_LUA_PATHInstalled Lua/Fennel search rootsbuild paths

OMP_NUM_THREADS and CUDA_VISIBLE_DEVICES keep their usual meaning. A commented template is seams.env.example. Analysis choice (which command, which Lua script, which Python call) is not this table.

\note The related pages describe the examples and how to obtain the data-sets (trajectories) from figshare.

\warning The live builds are pixi + meson, or the Nix flake. The CMake-era yodaStruct derivation is gone. Manage compiler and library versions yourself if you do not use pixi, nix, or the conda environment.

Citation

If you use this software please cite the following:

Goswami, R., Goswami, A., & Singh, J. K. (2020). d-SEAMS: Deferred Structural Elucidation Analysis for Molecular Simulations. Journal of Chemical Information and Modeling. https://doi.org/10.1021/acs.jcim.0c00031

The corresponding bibtex entry is:

@Article{Goswami2020,
author={Goswami, Rohit and Goswami, Amrita and Singh, Jayant Kumar},
title={d-SEAMS: Deferred Structural Elucidation Analysis for Molecular Simulations},
journal={Journal of Chemical Information and Modeling},
year={2020},
month={Mar},
day={20},
publisher={American Chemical Society},
issn={1549-9596},
doi={10.1021/acs.jcim.0c00031},
url={https://doi.org/10.1021/acs.jcim.0c00031}
}

Compilation

The live builds are pixi + meson, or the Nix flake. This repository builds libyodaLib and the seams CLI. Lua is yodaStruct (require("dseams")). Python is PydSEAMSlib.

pixi run setup && pixi run build && pixi run test
./bbdir/src/seams read input/traj/exampleTraj.lammpstrj

environment.yml is a micromamba fallback (meson, Eigen, BLAS, Catch2). It does not install Lua or yaml-cpp.

Nix

The flake builds libyodaLib and the seams CLI with meson. Optional backends that meson would otherwise wrap-git (vesin, readcon-core, linkcell) or that nixpkgs does not ship (chemfiles) stay off unless a package is already in the closure.

nix build                  # ./result/bin/seams
nix run . -- read input/traj/exampleTraj.lammpstrj
nix develop                # compiler, Eigen, BLAS, Catch2, gdb
nix flake update           # refresh the nixpkgs pin
nix fmt

nix build runs the Catch2 suite. The Lua library is yodaStruct; Python is PydSEAMSlib. Those repositories have matching flakes.

The dseams Cachix cache is optional:

nix-env -iA cachix -f https://cachix.org/api/v1/install
cachix use dseams

Usage

seams read input/traj/exampleTraj.lammpstrj
seams chill-plus input/traj/exampleTraj.lammpstrj --cutoff 3.5
seams cages input/traj/exampleTraj.lammpstrj

Lua scripts live in the yodaStruct checkout (require("dseams")). Paths in those examples are relative to the directory you invoke them from.

Language Server Support

nix develop
meson setup bbdir -Dwith_tests=true
ln -s bbdir/compile_commands.json .

Do Not commit compile_commands.json.

Development

nix develop
meson setup bbdir -Dwith_tests=true
meson compile -C bbdir
meson test -C bbdir

Running

nix build
./result/bin/seams --help
./result/bin/seams --frame 1 --last 100 --jobs 8 --type 1 --graph seeded cages dump.lammpstrj
./result/bin/seams --graph cutoff cages dump.lammpstrj
./result/bin/seams --graph knn cages dump.lammpstrj

To run the sample inputs, stay in the repository root so input/ is a child directory.

Tests

nix build          # meson test is the install check
nix develop --command meson test -C bbdir

Developer Documentation

The flake pins nixpkgs. To move the pin:

nix flake update nixpkgs

Then nix build from the project root. Outputs land in ./result.

Leaks and performance

While testing for leaks, use clang (for AddressSanitizer and LeakSanitizer) and the following:

# From the developer shell
export CXX=clang++ CC=clang
meson setup bbdir -Dwith_tests=true -Db_sanitize=address
meson compile -C bbdir
meson test -C bbdir

Overview

As of Mon Jan 20 15:57:18 2020, the lines of code calculated by cloc are as follows:

Cloc Lines

Contributing

Please ensure that all contributions are formatted according to the clang-format configuration file.

Specifically, consider using the following:

Where some of the above suggestions are derived from this depreciated githook.

Also, do note that we have a CONTRIBUTING file you need to read to contribute, for certain reasons, like, common sense.

Commit Hook

Note that we expect compliance with the clang-format as mentioned above, and this may be enforced by using the provided scripts for a pre-commit hook:

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

This will ensure that new commits are in accordance to the clang-format file.

Development Builds

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

To load debugging symbols from the shared library inside gdb:

add-symbol-file bbdir/src/libyodaLib.so

Then you can set breakpoints in the C++ code; for instance:

b seams_input.cpp:408

Acknowledgements

The following tools are used in this project:

  • Meson for compilation
  • Clang because it is more descriptive with better tools
  • Doxygen for the developer API
  • clang-format for code formatting
  • lua for the yodaStruct front end
  • environment variables and seams.env for runtime knobs

Third Party Libraries

The libraries used are: