d-SEAMS

Deferred Structural Elucidation Analysis for Molecular Simulations

• Check our build status here.
• The docs themselves are here and development is ongoing on GitHub
• We also have a Zenodo community for user-contributions like reviews, testimonials and tutorials
• Trajectories are hosted on figshare.
• Our wiki is here

\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:

• Python: pydseams (PydSEAMSlib)
• Lua/Fennel: dseams (yodaStruct)

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.

Variable	Meaning	Default
SEAMS_FRAME / SEAMS_LAST	Frame range (1-based)	1 / unset
SEAMS_JOBS	OpenMP frame workers	1
SEAMS_TYPE	Atom type (0 guesses)	0
SEAMS_CUTOFF	Neighbour cutoff (Å)	3.5
SEAMS_K	k for k-NN / seeded cages	4
SEAMS_GRAPH	cutoff / knn / knn-union / seeded	seeded
SEAMS_RESIDENT	Fraction of free GPU memory for a TUM batch	0.80
SEAMS_CELL	Link-cell hint so NPT frames share a grid (Å)	3.0
SEAMS_OFFLOAD	OpenMP target Steinhardt (0 disables)	on if devices exist
LINKCELL_TPP	Threads per particle on the device k-NN	occupancy picker
LINKCELL_BLOCK	CUDA block size	occupancy picker
YODA_FENNEL_PATH / YODA_LUA_PATH	Installed Lua/Fennel search roots	build 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

• This has been published at the Journal of Chemical Information and Modeling (JCIM)

• You may also read the preprint on arXiv

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:

Contributing

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

Specifically, consider using the following:

• Sublime Plugin for users of Sublime Text

• format-all for Emacs

• vim-clang-format for Vim

• Visual Studio: http://llvm.org/builds/, or use the integrated support in Visual Studio 2017

• Xcode: https://github.com/travisjeffery/ClangFormat-Xcode

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
  • clang-format-hooks for git hooks to enforce formatting
• lua for the yodaStruct front end
• environment variables and seams.env for runtime knobs

Third Party Libraries

The libraries used are:

• backward-cpp for better stacktraces without gdb
• Argum for the seams CLI (same parser as eonclient; colors, NO_COLOR)
• cxxopts for the Catch2 test harness
• rang for terminal styles (ANSI)
• sol2 for the yodaStruct Lua bindings
• Linear Algebra PACKage (LAPACK)
• Basic Linear Algebra Subprograms (BLAS)
• Spectra
• Boost Geometry for working with different coordinates
• Boost Math for spherical harmonics
• Blaze for very fast modern linear algebra
• nanoflann to calculate nearest neighbors
• icecream-cpp for pretty-printing and debugging