{"id":51197823,"url":"https://github.com/flatironinstitute/walnuts","last_synced_at":"2026-06-27T22:02:33.569Z","repository":{"id":302138024,"uuid":"1011217842","full_name":"flatironinstitute/walnuts","owner":"flatironinstitute","description":"Within-orbit Adaptive Leapfrog No-U-Turn Sampler","archived":false,"fork":false,"pushed_at":"2026-06-18T15:25:29.000Z","size":2104,"stargazers_count":48,"open_issues_count":13,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-06-18T15:28:33.821Z","etag":null,"topics":["hmc","mcmc","sampling","stan"],"latest_commit_sha":null,"homepage":"","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/flatironinstitute.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-30T13:32:59.000Z","updated_at":"2026-06-16T09:53:18.000Z","dependencies_parsed_at":"2025-06-30T19:46:58.171Z","dependency_job_id":"1b576f49-6296-435f-b95a-b1407606ddf4","html_url":"https://github.com/flatironinstitute/walnuts","commit_stats":null,"previous_names":["flatironinstitute/walnuts"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flatironinstitute/walnuts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatironinstitute%2Fwalnuts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatironinstitute%2Fwalnuts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatironinstitute%2Fwalnuts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatironinstitute%2Fwalnuts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flatironinstitute","download_url":"https://codeload.github.com/flatironinstitute/walnuts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatironinstitute%2Fwalnuts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34869004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["hmc","mcmc","sampling","stan"],"created_at":"2026-06-27T22:02:32.973Z","updated_at":"2026-06-27T22:02:33.564Z","avatar_url":"https://github.com/flatironinstitute.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Adaptive WALNUTS in C++\n\nThis is a C++ implementation of the following three [Hamiltonian Monte\nCarlo](https://en.wikipedia.org/wiki/Hamiltonian_Monte_Carlo) (HMC) samplers.\n\n* [NUTS](https://www.jmlr.org/papers/volume15/hoffman14a/hoffman14a.pdf)\n* [WALNUTS](https://arxiv.org/abs/2506.18746)\n* Adaptive WALNUTS (continuous form of [Nutpie](https://github.com/pymc-devs/nutpie)-style adaptation)\n\n## Licensing\n\nThe project is distributed under the following licenses.\n\n* Code: [MIT License](https://opensource.org/license/mit)\n* Documentation: [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.en)\n\n\n## Command Line Interface (CLI)\n\nBuilding `examples/stan_cli` creates a command-line interface to\nadaptive WALNUTS.  The interface uses BridgeStan to access Stan\nmodels.  To run, compile a Stan model into a shared object (`.so`\nfile) using BridgeStan (available in R, Python, Julia, Rust, and C) to\nsupply as the `model` argument to `stan_cli`.  The `data` argument\nshould be in the usual Stan JSON data format.\n\nThe mass adaptation follows a continuous form of Nutpie.  The step\nsize adaptation uses the Adam stochastic gradient descent (SGD)\noptimizer in the same way NUTS and Nutpie use dual averaging SGD.\n\nThe plan going forward is to provide wrappers along the lines of\n[TinyStan](https://github.com/WardBrian/tinystan) and\n[Nutpie](https://github.com/pymc-devs/nutpie).\n\nThe command-line options can be retrieved with the `--help` option.\n\n```bash\n:build$ examples/stan_cli --help\nRun WALNUTs on a Stan model \n\n\nexamples/stan_cli [OPTIONS] model [data]\n\n\nPOSITIONALS:\n  model TEXT:FILE REQUIRED    Path to the Stan model library (.so from CmdStan{,Py,R}) \n  data TEXT:FILE              Path to the Stan model data (.json, optional) \n\nOPTIONS:\n  --help              Print this help message and exit \n  --seed UINT [29294659]  \n                      Random seed (default randomize with clock) \n  --warmup UINT:NONNEGATIVE [128]  \n                      Number of warmup iterations \n  --samples UINT:POSITIVE [128]  \n                      Number of samples to draw \n  --max-depth UINT:POSITIVE [10]  \n                      Maximum depth for NUTS trajectory doublings \n  --max-step-depth UINT:POSITIVE [8]  \n                      Maximum depth for the step size adaptation \n  --min-micro-steps UINT:POSITIVE [1]  \n                      Minimum micro steps per macro step \n  --max-error FLOAT:POSITIVE [0.5]  \n                      Maximum error allowed in joint densities \n  --init FLOAT:NONNEGATIVE [2]  \n                      Range [-init,init] for uniform parameter initial values \n  --mass-init-count FLOAT:FLOAT in [1 - 1.79769e+308] [1.1]  \n                      Initial count for the mass matrix adaptation \n  --mass-iteration-offset FLOAT:FLOAT in [1 - 1.79769e+308] [1.1]  \n                      Offset for the mass matrix adaptation iterations \n  --mass-additive-smoothing FLOAT:POSITIVE [1e-05]  \n                      Additive smoothing for the mass matrix adaptation \n  --step-size-init FLOAT:POSITIVE [1]  \n                      Initial step size for the step size adaptation \n  --step-accept-rate-target FLOAT:FLOAT in [2.22507e-308 - 1] [0.8]  \n                      Target acceptance rate for the step size adaptation \n  --step-learning-rate FLOAT:POSITIVE [0.2]  \n                      Learning rates for step adaptation \n  --step-beta1 FLOAT:FLOAT in [2.22507e-308 - 1] [0.3]  \n                      Decay rate of gradient moving average for step adaptation \n  --step-beta2 FLOAT:FLOAT in [2.22507e-308 - 1] [0.99]  \n                      Decay rate of squared gradient moving average for step adaptation \n  --step-epsilon FLOAT:POSITIVE [0.0001]  \n                      Update stabilization term for step size adaptation \n  --output TEXT:PATH(non-existing) \n                      Output file for the draws \n```\n\nThe documentation automatically generated by `CLI11` library we use to\nparse the command line is literal about instantiated constraints and\ndefaults.  Even though the default `seed` changes each iteration, the\ndocumentation suggests the seed is constant.  In the bounds on\n`double` values, rounded scientific notation is used rather than\nproviding the semantic constraint that the value must fall in the open\ninterval (0, 1).\n\n## Dependencies\n\nThe dependencies may all be downloaded through CMake (see the next\nsection).\n\n### Required build dependencies\n\n* [Eigen C++ template library for linear algebra](https://eigen.tuxfamily.org/index.php?title=Main_Page)\n([MPLv2 licensed](https://www.mozilla.org/en-US/MPL/2.0/))\n\n### Required test dependencies\n\n* [Google test](https://github.com/google/googletest) ([BSD-3\nlicensed](https://opensource.org/license/bsd-3-clause))\n\n### Required documentation dependencies\n\n* [Doxygen](https://www.doxygen.nl/#google_vignette) ([GPLv1 licensed](https://www.gnu.org/licenses/old-licenses/gpl-1.0.html))\n\n### Optional build dependences\n\nRunning Stan models requires the BridgeStan interface.  See the BridgeStan documentation for more\ninformation on its dependencies.\n\n* [BridgeStan](https://github.com/roualdes/bridgestan)  ([BSD-3\nlicensed](https://opensource.org/license/bsd-3-clause))\n\n## Command-line tool dependency\n\nThe command-line interface is built using the following library.\n\n* [CLI11](https://github.com/CLIUtils/CLI11)  ([BSD-3\nlicensed](https://opensource.org/license/bsd-3-clause))\n\n## Using WALNUTS in a C++ project\n\nThis library is header only and only requires Eigen (also header only)\nto run (additional dependencies are required for testing and documentation).\nIf your project uses CMake, you can depend on our\n`walnuts` library target. If not, any method of adding the `include/`\nfolder of this repository to your build system's include paths should suffice\nas long as you also provide Eigen yourself.\n\n## Building the examples and tests\n\nCMake is required to build the examples and tests.\n\n### Configuring the build\n\nThe basic configuration is to run the following command from the\ntop-level `walnuts` directory.\n\n```sh\ncmake \u003coptions\u003e \u003crepo_root\u003e\n```\n\nwhere `\u003coptions\u003e` are the CMake options and `\u003crepo_root\u003e` is the root\ndirectory of the repository (where `CMakeLists.txt` is found).\n\nSome common options are:\n\n- `-B \u003cbuild_dir\u003e` - Specify the build directory where the build files will be generated. If omitted, the directory you run the command from will be used.\n- `-DCMAKE_BUILD_TYPE=Debug` - Set the build type to Debug.\n- `-DCMAKE_BUILD_TYPE=Release` - Set the build type to Release. \n- `-DWALNUTS_BUILD_TESTS=ON` - Enable building of the tests (currently on by default).\n- `-DWALNUTS_BUILD_EXAMPLES=ON` - Enable building of the examples (currently on by default).\n- `-DWALNUTS_BUILD_DOCS=ON` - Enable building of the documentation (currently on by default).\n- `-DWALNUTS_USE_MIMALLOC=ON` - Link against the [mimalloc](https://github.com/microsoft/mimalloc), a MIT licensed custom memory allocator which can improve performance.\n- `-DWALNUTS_BUILD_STAN=ON` - Enable the example program which uses Stan via [BridgeStan](github.com/roualdes/bridgestan). \n- `-DWALNUTS_USE_TSAN=ON` - Turn on the [thread sanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html)---only available if building with Clang.\n\nOther options can be found in the CMake help output or [documentation](https://cmake.org/cmake/help/latest/manual/cmake.1.html).\n\nFor example, a basic configuration which creates a `./build` directory in the repo\nroot can be done with\n\n```sh\ncmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release\n```\n\nDuring development, it's more helpful to build everything in debug mode.\n\n```sh\ncmake -S . -B ./build -DCMAKE_BUILD_TYPE=Debug -DWALNUTS_BUILD_TESTS=ON -DWALNUTS_BUILD_EXAMPLES=ON -DWALNUTS_BUILD_DOCS=ON -DWALNUTS_USE_TSAN=ON\n```\n\n`cmake` will cache its output configuration. To clear the entire build\nand start from scratch, just delete the automatically generated\n`build` subdirectory.\n\n```sh\nrm -r build\n```\n\nThe remaining instructions assume that commands are run from whatever\ndirectory you specified as the build directory (e.g., `./build` in the above command).\n\n### Building\n\nThe easiest way to build the project is with the `cmake --build`\ncommand. This will build all available executable targets by default.\n\nFor example, to build and run the `walnuts_api` example,\n\n```bash\ncd build\nmake walnuts_api\n./examples/walnuts_api\n```\n\n\n### Testing\n\nRunning the tests is easiest with the `ctest` command distributed with CMake.\n\n```bash\n# assuming you did _not_ specify -DWALNUTS_BUILD_TESTS=OFF earlier...\ncmake --build . --parallel 4\nctest\n```\n\nTo test code doverage during testing, you will have to specify the\ntop-level `cmake` call to include `DWALNUTS_COVERAGE=ON` (perhaps\nafter `rm -rf build` to remove the build directory and start over).\n\nThe steps are to first run the test, directing the summary to the named\n`.profraw` file.\n\n\n```bash\nLLVM_PROFILE_FILE=\"summary_test.profraw\" ./tests/summary_test\n```\n\nThen, (using `xcrun` on a Mac), call `llvm-profdata` to merge the data into a\n`.profdata` file.\n\n```bash\nxcrun llvm-profdata merge -sparse summary_test.profraw -o summary_test.profdata\n```\n\nNext, (also using `xcrun`), convert the generated `.profdata` file into html.\n\n```bash\nxcrun llvm-cov show ./tests/summary_test \\\n    -instr-profile=summary_test.profdata \\\n    -ignore-filename-regex='_deps|gtest' \\\n    -format=html \\\n    -output-dir=coverage_html\n```\n\nFinally, inspect the html output.\n\t\n```bash\nopen coverage_html/index.html\t\n```\n\n### Documentation\n\nTo build the C++ documentation using Doxygen:\n\n```bash\ncmake --build . --target doc\n```\n\nThe root of the generated doc will be found in\n\n* `./html/index.html`.\n\n\n### Include what you use\n\nTo run IWYU, \n\n```sh\ncd walnuts/iwyu\n./run-iwyu.sh examples/walnuts_api.cpp\n```\n\nOn Mac OS X, this requires installation of IWYU, which can be done as follows.\n\n```sh\nbrew install include-what-you-use\n```\n\n\n## Project overview\n\nThe project directory structure is as follows.\n\n```\nwalnuts/\n├── CMakeLists.txt\n├── LICENSE\n├── README.md\n├── cmake/\n│   ├── iwyu.imp\n│   ├── run-iwyu.sh\n│   └── tsan-suppressions.txt\n├── docs/\n│   └── refs.bib\n├── examples/\n│   ├── CMakeLists.txt\n│   ├── *.hpp\n│   ├── *.cpp\n├── include/\n│   ├── walnuts.hpp\n│   └── walnuts/\n│       └── *.hpp\n└── tests/\n    ├── CMakeLists.txt\n    ├── *_test.cpp\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatironinstitute%2Fwalnuts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflatironinstitute%2Fwalnuts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatironinstitute%2Fwalnuts/lists"}