{"id":13574825,"url":"https://github.com/dthuerck/mapmap_cpu","last_synced_at":"2025-04-21T11:32:50.177Z","repository":{"id":38050491,"uuid":"75747968","full_name":"dthuerck/mapmap_cpu","owner":"dthuerck","description":"A high-performance general-purpose MRF MAP solver, heavily exploiting SIMD instructions.","archived":false,"fork":false,"pushed_at":"2023-07-04T07:44:10.000Z","size":1071,"stargazers_count":105,"open_issues_count":7,"forks_count":51,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-01T12:50:50.807Z","etag":null,"topics":["algorithm","computer-vision","dynamic-programming","feedback-vertex-set","markov-random-field","massively-parallel","mrf","simd","simd-programming","vectorization"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dthuerck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-12-06T16:06:55.000Z","updated_at":"2025-03-26T04:44:30.000Z","dependencies_parsed_at":"2023-02-05T15:01:36.223Z","dependency_job_id":"6e86bb1a-a219-4e20-a071-2d169287c601","html_url":"https://github.com/dthuerck/mapmap_cpu","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dthuerck%2Fmapmap_cpu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dthuerck%2Fmapmap_cpu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dthuerck%2Fmapmap_cpu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dthuerck%2Fmapmap_cpu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dthuerck","download_url":"https://codeload.github.com/dthuerck/mapmap_cpu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250048058,"owners_count":21366167,"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":["algorithm","computer-vision","dynamic-programming","feedback-vertex-set","markov-random-field","massively-parallel","mrf","simd","simd-programming","vectorization"],"created_at":"2024-08-01T15:00:54.994Z","updated_at":"2025-04-21T11:32:49.318Z","avatar_url":"https://github.com/dthuerck.png","language":"C++","readme":"mapMAP MRF MAP Solver [![Build Status](https://github.com/dthuerck/mapmap_cpu/actions/workflows/master.yml/badge.svg)](https://github.com/dthuerck/mapmap_cpu/actions) \r\n[![tipi.build](https://github.com/dthuerck/mapmap_cpu/workflows/tipi.build/badge.svg) \u003cimg src=\"https://tipi.build/logo/tipi.build%20logo.svg\" height=\"23\" /\u003e ](https://github.com/dthuerck/mapmap_cpu/actions/workflows/tipi.yml)\r\n======\r\n\r\nOverview\r\n------\r\n\r\nCPU-implementation of out massively-parallel, generic, MRF MAP solver named\r\n*mapMAP* posing minimal assumptions to the input, allowing rapid solution\r\nof a large class of MRF problems.\r\n\r\nmapMAP's algorithmic foundation and parallelization concept has been presented\r\nat *High Performance Graphics 2016* in Dublin, Ireland. For a reprint and\r\nfurther information, please refer to our project page (see\r\nbelow).\r\n\r\nCurrently, this code implements the following modules and features:\r\n\r\n- [x] Customizable (parallel) performance\r\n  - [x] Change cost type between float and double\r\n  - [x] Templated SIMD width (1, 4, 8 for float; 1, 2, 4 for double)\r\n  - [x] Automatically setting SIMD width at compile time\r\n  - [x] Supports SSE4/AVX/AVX2, autodetected during build\r\n  - [x] Automatically using linear-time optimization for certain submodular cost functions\r\n  - [x] Novel linear-time optimization for certain supermodular cost functions\r\n  - [x] Two algorithms for parallel tree sampling\r\n- [x] Extensible interfaces for all components, providing user hooks\r\n  - [x] Cost functions (unary and pairwise)\r\n  - [x] Termination criteria\r\n  - [x] Node grouping criteria for the multilevel module\r\n  - [x] Choice of two (parallel) coordinate selection algorithms\r\n  - [x] Use of heuristics, thereby modifying the solver's structure.\r\n  - [x] User hooks for logging intermediate results.\r\n- [x] Solver modules\r\n  - [x] Acyclic (BCD) descent\r\n  - [x] Spanning tree descent\r\n  - [x] Multilevel solving\r\n- [x] Finding and exploiting connected components in the topology\r\n- [x] Test suite for each individual module\r\n\r\nWhat it lacks:\r\n- [ ] Capability to process label costs as outlined in the paper\r\n\r\nFor the license and terms of usage, please see \"License, Terms of usage \u0026 Reference\".\r\n\r\nIn addition to a \"classical\", CMake-based workflow, the great folks at [`tipi.build`](https://tipi.build/)\r\ncontributed (optional) support for their C++ build and dependency manager. With `tipi`,\r\nbuilding `mapmap` or using it as a library in your own projects just happens\r\nby a snap of your finger.\r\n\r\nPrerequisites\r\n------\r\n\r\n* CMake building system (\u003e= 3.0.2)\r\n* C++11 compatible compiler (e.g. gcc-5, MSVC 13, icc 17)\r\n* Intel OneTBB (see [Installation instructions for different package managers](https://www.intel.com/content/www/us/en/develop/documentation/installation-guide-for-intel-oneapi-toolkits-linux/top/installation/install-using-package-managers.html#install-using-package-managers))\r\n\r\nThe code has been tested (and compiles without issues) on an Ubuntu 16.04\r\nsystem with an AVX2-compliant Intel CPU\r\nusing gcc/g++ 9.3.0 and Intel OneTBB (2021.5.0). The latter is\r\nlicensed under the 3BSD-compatible Apache 2.0 licence (see\r\n[ASF legal FAQ](http://www.apache.org/legal/resolved.html#category-a)).\r\nPlease make sure to use an C++11-comptabile compiler and activate the\r\nnecessary options.\r\nIf you are a Ubuntu user, please click on `APT` on the OneTBB page linked above. \r\nGoogle Test will automatically be downloaded and built.\r\n\r\nThe provided FindTBB.cmake is taken from [justusc](https://github.com/justusc/FindTBB)\r\nand licensed under the MIT license.\r\n\r\nQuickstart\r\n------\r\n\r\nThe following instructions are provided for linux; the Windows workflow\r\nshould be somewhat similar, though GUI-based.\r\n\r\n#### The classical way\r\n\r\n*Step-by-step* instructions:\r\n\r\n1. `git clone https://github.com/dthuerck/mapmap_cpu`\r\n2. `cd mapmap_cpu \u0026\u0026 mkdir build \u0026\u0026  cd build \u0026\u0026 cmake ..`\r\n3. `ccmake .` and configure the following options (if you want to...):\r\n  * `CMAKE_C_COMPILER` - command for your C-compiler, e.g. `gcc-5`\r\n  * `CMAKE_CXX_COMPILER` - command for your C++-compiler,\r\n    e.g. `g++-5`\r\n  * `TBB_DIR` - path containing `TBBConfig.cmake`\r\n  * `BUILD_MEMSAVE` - determines if the dynamic programming should\r\n    allocate memory as needed (`ON`), saving memory but causing\r\n    slightly longer execution times or preallocate the whole table\r\n    (`OFF`)\r\n  * `BUILD_DEMO` - decides whether the demo from the\r\n    wiki is built as `mapmap_demo`\r\n  * `BUILD_TEST` - decides whether the test suite is built as\r\n    `mapmap_test`\r\n4. Configure and generate the Makefile (press `c` and `g` from\r\n   `ccmake`).\r\n5. Build the project using `make` (or `make -j` for parallel build).\r\n6. Depending on your configuration, you can now run `mapmap_test` and/or\r\n   `mapmap_demo` (assuming you activated `BUILD_TEST` and `BUILD_DEMO`).\r\n\r\n#### Using `tipi.build`\r\n\r\nAll prerequisites are provided by tipi.build and the `.tipi/deps` file, to compile this project simply run : \r\n```\r\ntipi . -t \u003cplatform\u003e\r\n```\r\nWhere platform is either one of linux, windows, macos or any of the supported environments.\r\n\r\nUsing mapMAP as a library in your own projects\r\n------\r\n\r\n#### The classical way\r\n\r\nmapMAP is implemented as a templated, header only library. A simple\r\n```\r\n#include \"mapmap/full.h\"\r\n```\r\nwill do the trick. Remember that in order to work you need to compile your\r\nwhole project with C++11 support. All functions and classes are organized\r\nin the namespace ```mapmap```.\r\n\r\nFor the users of GCC, we recommend the following options for the best\r\nperformance:\r\n```\r\n-std=c++11 -Wall -march=native -O2 -flto -mfpmath=sse -funroll-loops\r\n```\r\nAs a good starting point, we recommend studying `mapmap_demo.cc` closely,\r\nwhich is mostly self-explanatory.\r\n\r\n#### Using `tipi.build`\r\n\r\n`mapMAP` can be easily used with the [tipi.build](https://tipi.build) dependency manager, by adding the following to a `.tipi/deps`:\r\n\r\n```json\r\n{\r\n    \"dthuerck/mapmap_cpu\": { }\r\n}\r\n```\r\n\r\nDocumentation\r\n------\r\n\r\nFor extended documentation on building, using and extending mapMAP, please\r\nsee the\r\n[integrated wiki](https://github.com/dthuerck/mapmap_cpu/wiki).\r\n```\r\n\r\nAn example to start with is available in [example-mapmap_cpu](https://github.com/tipi-deps/example-mapmap_cpu) (change the target name appropriately to `linux` or `macos` or `windows`):\r\n\r\n```bash\r\ntipi . -t \u003ctarget\u003e\r\n```\r\n\r\nLicense, Terms of Usage \u0026 Reference\r\n------\r\n\r\nOur program is licensed under the liberal BSD 3-Clause license included\r\nas LICENSE.txt file.\r\n\r\nIf you decide to use our code or code based on this project in your application,\r\nplease make sure to cite our HPG 2016 paper:\r\n\r\n```\r\n@inproceedings{Thuerck2016MRF,\r\n    title = {A Fast, Massively Parallel Solver for Large, Irregular Pairwise {M}arkov Random Fields},\r\n    author = {Thuerck, Daniel and Waechter, Michael and Widmer, Sven and von Buelow, Max and Seemann, Patrick and Pfetsch, Marc E. and Goesele, Michael},\r\n    booktitle = {Proceedings of High Performance Graphics 2016},\r\n    year = {2016},\r\n}\r\n```\r\nA PDF reprint is available here: [PDF reprint](https://culip.org/files/2016_thuerck_mapmap.pdf) and\r\n[PDF Supplementary Material](https://culip.org/files/2016_thuerck_mapmap_supplemental.pdf).\r\n\r\nContact\r\n------\r\n\r\nFor any trouble with building, using or extending this software, please use\r\nthe project's integrated issue tracker. We'll be happy to help you there or\r\ndiscuss feature requests.\r\n\r\n\r\nChange Log\r\n------\r\nCompared with the development version from our HPG paper (cf. below).\r\n\r\n* v1.5 (6/25/2018):\r\n  - Added tech report for new tree selection algorithm (from v1.2) in doc/.\r\n  - Added novel envelopes for supermodular cost function types (\"Antipotts\",\r\n    \"LinearPeak\"). A tech report _may_ follow.\r\n  - Several bugfixes.\r\n* v1.4 (1/10/2018):\r\n  - Deterministic solver path with user-provided seed.\r\n  - Several bugfixes and smaller improvements.\r\n* v1.3 (10/18/2017):\r\n  - Envelope optimization for Potts, TruncatedLinear, TruncatedQuadratic.\r\n  - Ability to have individual cost functions per edge.\r\n  - Removed UNARY/PAIRWISE template parameters from solver, hiding these\r\n    internally.\r\n  - Improved multilevel performance, even in the case of individual costs.\r\n  - Added GTest for automatic built instead of a hard dependency.\r\n* v1.2 (5/29/2017):\r\n  - Introduced a new, multicoloring-based tree selection algorithm -\r\n    lock-free.\r\n* v1.1 (4/12/2017):\r\n  - Tuned the tree growing implementation for early termination and\r\n  - option for relaxing the maximality requirement.\r\n* v1.0 (2/8/2017):\r\n  - Stable release.\r\n  - Logging callbacks for use as library.\r\n  - Clean, documented interface and documentation.\r\n  - Added a demo for correct usage.\r\n* beta (12/6/2016):\r\n  - Initial release, mirrors functionality outlined in the paper.\r\n  - Automated vectorization (compile-time detection) for float/double.\r\n  - Supporting scalar/SSE2-4/AVX/AVX2.\r\n  - Added cost function instances.\r\n  - Added unit tests.\r\n","funding_links":[],"categories":["Table of Contents"],"sub_categories":["Mathematics and Science"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdthuerck%2Fmapmap_cpu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdthuerck%2Fmapmap_cpu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdthuerck%2Fmapmap_cpu/lists"}