The C++ core of d-SEAMS, a molecular dynamics trajectory analysis engine.Deferred Structural Elucidation Analysis for Molecular Simulations

Check our docs 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.


This software is being actively developed and written up. If you do use it in an academic capacity, for now please cite the following preprint:

Goswami, R.; Goswami, A.; Singh, J. K. (2019). "d-SEAMS: Deferred Structural Elucidation Analysis for Molecular Simulations". arXiv:1909.09830 [physics.comp-ph].


Dependency Management


Lua v5.3 is used for the scripting engine. It needs to be installed via the operating system's normal packaging system for now. If possible, install a version compiled with c++, not c.

# Ubuntu and derivatives
sudo apt install lua5.3 liblua5.3
# ArchLinux
sudo pacman -S lua

Lua Modules

Since a major portion of the frontend is in lua, the following modules are required.LuaRocks is the recommended package manager and they are to be installed as root.

# For cross-OS filesystem operations
sudo luarocks install luafilesystem

Nix Usage

We use a deterministic build system to generate both bug reports and uniform usage statistics.


Since this project is built with nix, we can simply do the following from the root directory:

# This will take a long time the first time since it builds sharkML
nix-build .
# Install into your path
nix-env -if .
# Use anywhere
cd lua_inputs/
yodaStruct -c config.yml
# Use with lua modules
nix-shell --run 'bash' --pure


Though the build itself is guaranteed to be reproducible as the nixpkgs are also pinned to a particular commit, the luarocks dependencies are still local, since they are determined at runtime. This means, for example, to use the sample file, you need to ensure you have the luarocks modules installled in your system.

The above caveats are not relevant when you run it in the shell environment defined by shell.nix

Reproducible Lua

For reproducing lua we use luas. Note that this is still an imperfect method and the best way to run this is via the `nix-shell –run 'bash' –pure` environment.

luas init 5.2.4
luas use 5.2.4
luarocks install luafilesystem


We can simply use the nix environment:

# From the project root
# Sanitize and fix the shell
stty sane
export TERM="xterm-256color"


To run the sample inputs, simply move the binary to the project root, or to a directory where input/ is a child directory.

# Assuming you are in the build directory
# Check help with -h
# --script and --file are optional now
./yodaStruct --script ../lua_inputs/transition_diff.lua -f ../lua_inputs/parameter.txt -c ../lua_inputs/config.yml

Developer Documentation

For updates to any of the bundled external libraries change the commit number and use:

$ cd src/external
# Sol2
 wget https://raw.githubusercontent.com/ThePhD/sol2/develop/single/sol/sol_forward.hpp
 wget https://raw.githubusercontent.com/ThePhD/sol2/develop/single/sol/sol.hpp
# cxxopts
 wget https://raw.githubusercontent.com/jarro2783/cxxopts/master/include/cxxopts.hpp

Leaks and performance

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

export CXX=/usr/bin/clang++ && export CC=/usr/bin/clang


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

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.


The following tools are used in this project:

Third Party Libraries

The libraries used are: