{"id":15282026,"url":"https://github.com/d-seams/seams-core","last_synced_at":"2026-03-14T05:34:46.771Z","repository":{"id":35991538,"uuid":"164746444","full_name":"d-SEAMS/seams-core","owner":"d-SEAMS","description":"The d-SEAMS C++ core engine","archived":false,"fork":false,"pushed_at":"2024-08-26T03:56:43.000Z","size":9417,"stargazers_count":36,"open_issues_count":16,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-13T09:05:49.723Z","etag":null,"topics":["analysis-framework","d-seams","lua","molecular-dynamics","molecular-dynamics-simulation","nix","trajectories","trajectory-analysis"],"latest_commit_sha":null,"homepage":"https://dseams.info","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d-SEAMS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-01-08T22:50:43.000Z","updated_at":"2025-04-07T02:49:48.000Z","dependencies_parsed_at":"2024-01-31T09:02:21.917Z","dependency_job_id":"2647424d-7b96-417a-97a3-698ac5998e28","html_url":"https://github.com/d-SEAMS/seams-core","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-SEAMS%2Fseams-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-SEAMS%2Fseams-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-SEAMS%2Fseams-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-SEAMS%2Fseams-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d-SEAMS","download_url":"https://codeload.github.com/d-SEAMS/seams-core/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248688573,"owners_count":21145766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analysis-framework","d-seams","lua","molecular-dynamics","molecular-dynamics-simulation","nix","trajectories","trajectory-analysis"],"created_at":"2024-09-30T14:05:19.628Z","updated_at":"2026-03-14T05:34:46.680Z","avatar_url":"https://github.com/d-SEAMS.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# d-SEAMS\n\n**Deferred Structural Elucidation Analysis for Molecular Simulations**\n\n[![Build Status](https://github.com/d-SEAMS/seams-core/actions/workflows/build_pkg.yml/badge.svg)](https://github.com/d-SEAMS/seams-core/actions/workflows/build_pkg.yml)\n\n[![built with nix](https://builtwithnix.org/badge.svg)](https://builtwithnix.org)\n\n- Check our build status [here](https://github.com/d-SEAMS/seams-core/actions/workflows/).\n- The docs themselves are [here](https://docs.dseams.info) and development is\n  ongoing [on GitHub](https://github.com/d-SEAMS/seams-core)\n- We also have [a Zenodo community](https://zenodo.org/communities/d-seams/) for user-contributions like reviews, testimonials\n  and tutorials\n- Trajectories are hosted [on\n  figshare](https://figshare.com/projects/d-SEAMS_Datasets/73545).\n- Our [wiki is here](https://wiki.dseams.info)\n\n\\brief The C++ core of d-SEAMS, a molecular dynamics trajectory analysis engine.\n\n\\note The \u003ca href=\"pages.html\"\u003erelated pages\u003c/a\u003e describe the examples and how to obtain\nthe data-sets (trajectories) \u003ca\nhref=\"https://figshare.com/projects/d-SEAMS_Datasets/73545\"\u003efrom figshare\u003c/a\u003e.\n\n\\warning **If** you are unwilling to use the `nix` build system, then **please note** that you must manage the dependencies MANUALLY, including the compiler versions. Optionally, use the provided `conda` environment.\n\n# Citation\n\n- This has been published at the [Journal of Chemical Information and Modeling\n  (JCIM)](https://doi.org/10.1021/acs.jcim.0c00031)\n\n- You may also read [the preprint on arXiv](https://arxiv.org/abs/1909.09830)\n\nIf you use this software please cite the following:\n\n    Goswami, R., Goswami, A., \u0026 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\n\nThe corresponding `bibtex` entry is:\n\n    @Article{Goswami2020,\n    author={Goswami, Rohit and Goswami, Amrita and Singh, Jayant Kumar},\n    title={d-SEAMS: Deferred Structural Elucidation Analysis for Molecular Simulations},\n    journal={Journal of Chemical Information and Modeling},\n    year={2020},\n    month={Mar},\n    day={20},\n    publisher={American Chemical Society},\n    issn={1549-9596},\n    doi={10.1021/acs.jcim.0c00031},\n    url={https://doi.org/10.1021/acs.jcim.0c00031}\n    }\n\n# Compilation\n\nWe use a deterministic build system to generate both bug reports and uniform\nusage statistics. This also handles the `lua` scripting engine.\n\n\\note The lua functions are documented on the [on the API Docs](https://docs.dseams.info/md_markdown_luafunctions)\n\nWe also provide a `conda` environment as a fallback, which is also recommended for MacOS users.\n\n## Build\n\n### Conda (working now)\n\nAlthough we strongly suggest using `nix`, for MacOS systems, the following\ninstructions may be more suitable. We will assume the presence of [micromamba](https://mamba.readthedocs.io/en/latest/installation.html):\n\n```bash\ncd ~/seams-core\nmicromamba create -f environment.yml\nmicromamba activate dseams\nluarocks install luafilesystem\n```\n\nNow the installation can proceed.\n\n\\note we do not install `lua-luafilesystem` within the `conda` environment because it is outdated on `osx`\n\n```bash\nmkdir build\ncd build\nexport EIGEN3_INCLUDE_DIR=$CONDA_PREFIX/include/eigen3\ncmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=YES -DCMAKE_INSTALL_PREFIX:PATH=$CONDA_PREFIX ../\nmake -j$(nproc)\nmake install\nLD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CONDA_PREFIX/lib $CONDA_PREFIX/bin/yodaStruct -c lua_inputs/config.yml\n```\n\nWe have opted to install into the `conda` environment, if this is not the\nintended behavior, use `/usr/local` instead.\n\n### Spack (not working at the moment)\n\nManually this can be done in a painful way as follows:\n\n```bash\nspack install eigen@3.3.9 lua@5.2\nspack install catch2 fmt yaml-cpp openblas boost cmake ninja meson\nspack load catch2 fmt yaml-cpp openblas boost cmake ninja meson eigen@3.3.9 lua@5.2\nluarocks install luafilesystem\n```\n\nOr better:\n\n```bash\nspack env activate $(pwd)\n# After loading the packages\nluarocks install luafilesystem\n```\n\nNow we can build and install as usual.\n\n```bash\ncmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo \\\n -DCMAKE_EXPORT_COMPILE_COMMANDS=YES -GNinja \\\n -DCMAKE_INSTALL_PREFIX=$HOME/.local \\\n -DCMAKE_CXX_FLAGS=\"-pg -fsanitize=address \" \\\n -DCMAKE_EXE_LINKER_FLAGS=-pg -DCMAKE_SHARED_LINKER_FLAGS=-pg \\\n -DBUILD_TESTING=NO\ncmake --build build\n```\n\nOr more reasonably:\n\n```bash\nexport INST_DIR=$HOME/.local\ncd src\nmeson setup bbdir --prefix $INST_DIR\nmeson compile -C bbdir\nmeson install -C bbdir\n# if not done\nexport PATH=$PATH:$INST_DIR/bin\nexport LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$INST_DIR/lib\ncd ../\nyodaStruct -c lua_inputs/config.yml\n```\n\n### Nix (not working at the moment)\n\nSince this project is built with `nix`, we can simply do the following from the\nroot directory (longer method):\n\n```sh\n# Make sure there are no artifacts\nrm -rf build\n# This will take a long time the first time as it builds the dependencies\nnix-build . # Optional\n# Install into your path\nnix-env -if . # Required\n# Run the command anywhere\nyodaStruct -c lua_inputs/config.yml\n```\n\nA faster method of building the software is by using the [cachix binary cache](https://dseams.cachix.org/) as shown:\n\n```bash\n# Install cachix\nnix-env -iA cachix -f https://cachix.org/api/v1/install\n# Use the binary cache\ncachix use dseams\n# Faster with the cache than building from scratch\nnix-build . # Optional\n# Install into your path\nnix-env -if . # Required\n# Run the command anywhere\nyodaStruct -c lua_inputs/config.yml\n```\n\n### Usage\n\nHaving installed the `yodaStruct` binary and library, we can now use it.\n\n```bash\nyodaStruct -c lua_inputs/config.yml\n```\n\n\\note The paths in the `.yml` should be **relative to the folder from which the binary is called**.\n\nIf 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.\n\n### Language Server Support\n\nTo generate a `compile_commands.json` file for working with a language server\nlike [ccls](https://github.com/MaskRay/ccls) use the following commands:\n\n```sh\n# Pure environment\nnix-shell --pure\nmkdir -p build \u0026\u0026 cd build\ncmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=YES ../\ncp compile_commands.json ../\n```\n\nNote that there is no need to actually compile the project if you simply need to\nget the compiler database for the language server.\n\n**Do Not** commit the `.json` file.\n\n## Development\n\nWe can simply use the `nix` environment:\n\n```sh\n# From the project root\nnix-shell --pure\n```\n\n# Running\n\nThis is built completely with nix:\n\n```{bash}\n# Install systemwide\nnix-env -if .\n```\n\nTo run the sample inputs, simply install the software, and ensure that `input/` is a child directory.\n\n```{bash}\n# Assuming you are in the src directory\n# Check help with -h\nyodaStruct -c lua_inputs/config.yml\n```\n\n## Tests\n\nApart from the [examples](https://docs.dseams.info/pages.html), the test-suite\ncan be run with the `yodaStruct_test` binary, which will drop into the\n`nix` environment before building and executing `gdb`:\n\n```{bash}\n# Just run this\n./testBuild.sh\n# At this point the binary and library are copied into the root\n# One might, in a foolhardy attempt, use gdb at this point\n# Here be dragons :)\n# USE NIX\n# Anyway\ngdb --args ./yodaStruct -c lua_inputs/config.yml\n# quit gdb with quit\n# Go run the test binary\ncd shellBuild\n./yodaStruct_test\n```\n\nDo note that the regular installation via `nix-env` runs the tests before the installation\n\n# Developer Documentation\n\n\u003c!-- TODO: Move this to some other location. --\u003e\n\nWhile developing, it is sometimes expedient to update the packages used. It is\nthen useful to note that we use [niv](https://github.com/nmattia/niv/) to handle our pinned packages (apart from\nthe ones built from Github). Thus, one might need, say:\n\n```bash\nniv update nixpkgs -b nixpkgs-unstable\n```\n\nTest the build with nix:\n\n```bash\nnix-build .\n# Outputs are in ./result\n# If you get a CMake error\nrm -rf build\nnix-store --delete /nix/store/$whatever # $whatever is the derivation complaining\nnix-collect-garbage # then try again [worst case scenario]\n```\n\n## Leaks and performance\n\nWhile testing for leaks, use `clang` (for\n[AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer)\nand\n[LeakSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer))\nand the following:\n\n```{bash}\n# From the developer shell\nexport CXX=/usr/bin/clang++ \u0026\u0026 export CC=/usr/bin/clang\ncmake .. -DCMAKE_CXX_FLAGS=\"-pg -fsanitize=address \" -DCMAKE_EXE_LINKER_FLAGS=-pg -DCMAKE_SHARED_LINKER_FLAGS=-pg\n```\n\n# Overview\n\nAs of Mon Jan 20 15:57:18 2020, the lines of code calculated by\n[cloc](http://cloc.sourceforge.net/) are as follows:\n\n![Cloc Lines](images/cloc-2020-01-20_15-56.png)\n\n# Contributing\n\nPlease ensure that all contributions are formatted according to the\n[clang-format](./clang-format) configuration file.\n\nSpecifically, consider using the following:\n\n- [Sublime Plugin](https://github.com/rosshemsley/SublimeClangFormat) for users\n  of Sublime Text\n\n- [format-all](https://github.com/lassik/emacs-format-all-the-code) for Emacs\n- [vim-clang-format](https://github.com/rhysd/vim-clang-format) for Vim\n- Visual Studio: http://llvm.org/builds/, or use the [integrated support in Visual Studio 2017](https://blogs.msdn.microsoft.com/vcblog/2018/03/13/clangformat-support-in-visual-studio-2017-15-7-preview-1/)\n- Xcode: https://github.com/travisjeffery/ClangFormat-Xcode\n\nWhere some of the above suggestions are derived from [this depreciated githook](https://github.com/andrewseidl/githook-clang-format).\n\nAlso, do note that we have a `CONTRIBUTING` file you **need to read** to\ncontribute, for certain reasons, like, common sense.\n\n## Commit Hook\nNote 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:\n```bash\n./scripts/git-pre-commit-format install\n```\n\nThis will ensure that new commits are in accordance to the `clang-format` file.\n\n## Development Builds\n\nThe general idea is to drop into an interactive shell with the dependencies and then use `cmake` as usual.\n\n```bash\nnix-shell --pure --run bash --show-trace --verbose\ncd build\ncmake .. -DCMAKE_BUILD_TYPE=Debug -DNO_WARN=TRUE \\\n -DFIND_EIGEN=TRUE \\\n -DCMAKE_EXPORT_COMPILE_COMMANDS=1 \\\n -G \"Ninja\"\nninja\n# Test\ncd ../\nyodaStruct -c lua_inputs/config.yml\n# Debug\ngdb --args yodaStruct -c lua_inputs/config.yml\n```\nTo load debugging symbols from the shared library, when you are inside `gdb` (from the top-level directory, for instance), use the following command:\n\n```bash\nadd-symbol-file build/libyodaLib.so\n```\nThen you can set breakpoints in the C++ code; for instance: \n\n```bash\nb seams_input.cpp:408\n```\n\n# Acknowledgements\n\nThe following tools are used in this project:\n\n- [CMake](https://cmake.org/) for compilation ([cmake-init](https://github.com/cginternals/cmake-init) was used as a reference)\n- [Clang](https://clang.llvm.org/) because it is more descriptive with better tools\n- [Doxygen](https://www.doxygen.org) for the developer API\n- [clang-format](https://clang.llvm.org/docs/ClangFormat.html) for code formatting\n  - [clang-format-hooks](https://github.com/barisione/clang-format-hooks) for `git` hooks to enforce formatting\n- [lua](https://www.lua.org) for the scripting engine\n- [yaml](http://yaml.org/) for the configuration\n\n## Third Party Libraries\n\nThe libraries used are:\n\n- [backward-cpp](https://github.com/bombela/backward-cpp) for better stacktraces without `gdb`\n- [cxxopts](https://github.com/jarro2783/cxxopts) for parsing command line options\n- [rang](https://github.com/agauniyal/rang) for terminal styles (ANSI)\n- [sol2](https://github.com/ThePhD/sol2) for interfacing with lua\n- [yaml-cpp](https://github.com/jbeder/yaml-cpp) for working with `yaml`\n- [fmt](https://github.com/fmtlib/fmt) for safe and fast formatting\n- [Linear Algebra PACKage (LAPACK)](http://www.netlib.org/lapack/)\n- [Basic Linear Algebra Subprograms (BLAS)](http://www.netlib.org/blas/)\n- [Spectra](https://github.com/yixuan/spectra/)\n- [Boost Geometry](https://www.boost.org/doc/libs/1_68_0/libs/geometry/doc/html/index.html) for working with different coordinates\n- [Boost Math](https://www.boost.org/doc/libs/?view=category_math) for spherical harmonics\n- [Blaze](https://bitbucket.org/blaze-lib/blaze/) for very fast modern linear algebra\n- [nanoflann](https://github.com/jlblancoc/nanoflann) to calculate nearest neighbors\n- [icecream-cpp](https://github.com/renatoGarcia/icecream-cpp) for pretty-printing and debugging\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-seams%2Fseams-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd-seams%2Fseams-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-seams%2Fseams-core/lists"}