d-SEAMS

The C++ core of d-SEAMS, a molecular dynamics trajectory analysis engine.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.

Citation

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].

Compilation with Nix

We use a deterministic build system to generate both bug reports and uniform usage statistics. This also handles the lua scripting engine.

Build

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

# Make sure there are no artifacts
rm -rf build
# This will take a long time the first time as it builds the dependencies
nix-build . # Optional
# Install into your path
nix-env -if . # Required
# Run the command anywhere
yodaStruct -c lua_inputs/config.yml

A faster method of building the software is by using the cachix binary cache as shown:

# Install cachix
nix-env -iA cachix -f https://cachix.org/api/v1/install
# Use the binary cache
cachix use dseams
# Faster with the cache than building from scratch
nix-build . # Optional
# Install into your path
nix-env -if . # Required
# Run the command anywhere
yodaStruct -c lua_inputs/config.yml

If you're confused about how to handle the relative paths, run the command yodaStruct -c lua_inputs/config.yml in the top-level directory, and set the paths relative to the top-level directory. This is the convention used in the examples as well.

Language Server Support

To generate a compile_commands.json file for working with a language server like ccls use the following commands:

# Pure environment
nix-shell --run 'bash' --pure
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=YES ../
cp compile_commands.json ../

Note that there is no need to actually compile the project if you simply need to get the compiler database for the language server.

Do Not commit the .json file.

Development

We can simply use the nix environment:

# From the project root
nix-shell

Running

This is built completely with nix:

# Install systemwide
nix-env -if .

To run the sample inputs, simply install the software, and ensure that input/ is a child directory.

# Assuming you are in the src directory
# Check help with -h
yodaStruct -c lua_inputs/config.yml

Tests

Apart from the examples, the test-suite can be run with the yodaStruct_test binary, which will drop into the nix environment before building and executing gdb:

# Just run this
./testBuild.sh
# quit gdb with quit
# Go run the test binary
cd shellBuild
./yodaStruct_test

Do note that the regular installation via nix-env runs the tests before the installation

Developer Documentation

Test the build with nix:

nix-build .
# Outputs are in ./result
# If you get a CMake error
rm -rf build
nix-store --delete /nix/store/$whatever # $whatever is the derivation complaining
nix-collect-garbage # then try again [worst case scenario]

Leaks and performance

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

# From the developer shell
export CXX=/usr/bin/clang++ && export CC=/usr/bin/clang
cmake .. -DCMAKE_CXX_FLAGS="-pg -fsanitize=address " -DCMAKE_EXE_LINKER_FLAGS=-pg -DCMAKE_SHARED_LINKER_FLAGS=-pg

Overview

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

Image

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.

Acknowledgements

The following tools are used in this project:

Third Party Libraries

The libraries used are: