{"id":42517917,"url":"https://github.com/rxdu/libgraph","last_synced_at":"2026-01-28T15:07:53.240Z","repository":{"id":54862234,"uuid":"73421660","full_name":"rxdu/libgraph","owner":"rxdu","description":"C++ class templates for graph construction and search","archived":false,"fork":false,"pushed_at":"2025-12-21T14:07:31.000Z","size":2203,"stargazers_count":13,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-12-23T04:58:14.049Z","etag":null,"topics":["astar","dijkstra","graph"],"latest_commit_sha":null,"homepage":"https://rdu.im/libgraph/","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/rxdu.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":"2016-11-10T21:18:48.000Z","updated_at":"2025-12-21T14:07:10.000Z","dependencies_parsed_at":"2024-09-12T14:04:43.801Z","dependency_job_id":"fc3db4c4-1fd4-4264-9bfe-68b9bd64ec37","html_url":"https://github.com/rxdu/libgraph","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/rxdu/libgraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rxdu%2Flibgraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rxdu%2Flibgraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rxdu%2Flibgraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rxdu%2Flibgraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rxdu","download_url":"https://codeload.github.com/rxdu/libgraph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rxdu%2Flibgraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28846120,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T13:02:32.985Z","status":"ssl_error","status_checked_at":"2026-01-28T13:02:04.945Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["astar","dijkstra","graph"],"created_at":"2026-01-28T15:07:52.630Z","updated_at":"2026-01-28T15:07:53.233Z","avatar_url":"https://github.com/rxdu.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libgraph: a C++ Graph Library\n\n![GitHub Workflow Status](https://github.com/rxdu/libgraph/actions/workflows/ci.yml/badge.svg)\n[![codecov](https://codecov.io/gh/rxdu/libgraph/branch/main/graph/badge.svg?token=09RJHODBCK)](https://codecov.io/gh/rxdu/libgraph)\n\nA modern, header-only C++11 library for graph construction and pathfinding algorithms. Designed for high performance with thread-safe concurrent searches and generic cost types.\n\n## Key Features\n\n- **High Performance**: O(m+n) space complexity, optimized priority queues, 35% faster search contexts\n- **Thread-Safe**: Concurrent searches using external SearchContext, no race conditions\n- **Generic**: Custom cost types, comparators, and state indexing - works with any data structure\n- **Complete Algorithm Suite**: A*, Dijkstra, BFS, DFS with unified framework\n- **Robust**: Comprehensive exception handling, structure validation, memory safety via RAII\n- **Well-Documented**: Extensive API reference, tutorials, and working examples\n\n### Generic State Types\n```cpp\nstruct GameState {\n    int x, y, health, ammo;\n    int64_t GetId() const { return y*1000 + x; }  // Auto-detected by DefaultIndexer\n};\nGraph\u003cGameState\u003e game_world;\n```\n\n### Custom Cost Types\n```cpp\nstruct TravelCost {\n    double time, distance, comfort;\n    bool operator\u003c(const TravelCost\u0026 other) const { /* lexicographic comparison */ }\n};\nGraph\u003cLocation, TravelCost\u003e multi_criteria_graph;\n```\n\n### Performance Optimization\n```cpp\ngraph.reserve(10000);           // Pre-allocate vertices\ncontext.PreAllocate(10000);     // Pre-allocate search state\ngraph.AddVertices(state_list);  // Batch operations\n```\n\n---\n\n## Architecture Highlights\n\n### Modern C++ Design Patterns\n- **CRTP Strategy Pattern**: Zero-overhead polymorphism for search algorithms\n- **RAII Memory Management**: Automatic cleanup with `std::unique_ptr`, no memory leaks\n- **Template Metaprogramming**: Compile-time optimization and type safety\n- **STL Compatibility**: Full iterator support, range-based for loops\n\n### Template System\n```cpp\ntemplate\u003ctypename State, typename Transition = double, typename StateIndexer = DefaultIndexer\u003cState\u003e\u003e\nclass Graph;\n```\n- **State**: Your vertex data (locations, game states, etc.)\n- **Transition**: Edge weights (distance, time, cost, custom types)\n- **StateIndexer**: Automatic ID generation from states\n\n### Performance Characteristics\nOptimal space complexity O(m+n) using adjacency lists:\n\n| **Operation** | **Time Complexity** | **Space** |\n|---------------|-------------------|-----------|\n| Add/Find Vertex | O(1) average | O(1) |  \n| Add Edge | O(1) | O(1) |\n| Search Algorithms | O((m+n) log n) | O(n) |\n| Thread-Safe Search | O((m+n) log n) | O(n) per context |\n\n### Thread Safety\n\n**Concurrent read-only searches** are fully supported:\n```cpp\n// Each thread gets independent search context\nvoid worker_thread(const Graph\u003cLocation\u003e* graph) {\n    SearchContext\u003cLocation\u003e context;  // Thread-local state\n    auto path = Dijkstra::Search(graph, context, start, goal);  // Thread-safe\n}\n```\n\n**Thread-Safety Model:**\n- **Graph**: Read-only access only during concurrent searches (const pointer accepted)\n- **SearchContext**: Each concurrent search requires its own instance\n- **Strategy objects**: Stateless, can be safely shared across threads\n- **Legacy API**: Overloads without SearchContext parameter are NOT thread-safe\n\n**Graph modifications** require external synchronization (by design for performance).\n\n### Production Features (v3.1.0)\n\n**Rich search results** with cost and diagnostics:\n```cpp\nauto result = SearchAlgorithm\u003c...\u003e::SearchWithResult(graph, context, start, goal, strategy);\nif (result.found) {\n    std::cout \u003c\u003c \"Cost: \" \u003c\u003c result.total_cost \u003c\u003c \", Expanded: \" \u003c\u003c result.nodes_expanded;\n}\n```\n\n**Bounded search** for real-time systems:\n```cpp\nauto limits = SearchLimits::MaxExpansions(1000);  // or SearchLimits::Timeout(50)\nauto result = SearchAlgorithm\u003c...\u003e::SearchWithLimits(graph, context, start, goal, strategy, limits);\n```\n\n**Multi-goal search** (find nearest goal):\n```cpp\nstd::vector\u003cLocation\u003e goals = {charging_station1, charging_station2, charging_station3};\nauto result = Dijkstra::SearchMultiGoal(graph, context, robot_position, goals);\n// result.goal_index tells which goal was reached\n```\n\n---\n\n## Build \u0026 Integration\n\n### Requirements\n- **C++11** compatible compiler (GCC 4.8+, Clang 3.4+, MSVC 2015+)\n- **CMake 3.10+** (for build system and examples)\n- **Optional**: Doxygen for API documentation\n\n### Integration Options\n\n#### 1. Header-Only\n```bash\ngit clone https://github.com/rxdu/libgraph.git\ncp -r libgraph/include/graph /your/project/include/\n```\n```cpp\n#include \"graph/graph.hpp\"\n#include \"graph/search/dijkstra.hpp\"  // Ready to use!\n```\n\n#### 2. CMake Submodule\n```cmake\n# Add to your CMakeLists.txt\nadd_subdirectory(third_party/libgraph)\ntarget_link_libraries(your_target PRIVATE xmotion::graph)\n```\n\n#### 3. System Installation\n```bash\nmkdir build \u0026\u0026 cd build\ncmake ..\nsudo make install\n\n# Use in your project\nfind_package(graph REQUIRED)\ntarget_link_libraries(your_app PRIVATE xmotion::graph)\n```\n\n#### 4. Debian Package Installation\n```bash\nmkdir build \u0026\u0026 cd build\ncmake -DCMAKE_BUILD_TYPE=Release .. \u0026\u0026 make -j4 \u0026\u0026 cpack\nsudo dpkg -i graph_3.1.0_amd64.deb  # Adjust version as needed\n```\n\n### Build Examples and Tests\n```bash\ngit clone --recursive https://github.com/rxdu/libgraph.git\nmkdir build \u0026\u0026 cd build\ncmake -DBUILD_TESTING=ON ..\ncmake --build .\n\n# Run examples\n./bin/simple_graph_demo\n./bin/thread_safe_search_demo\n\n# Run comprehensive tests (317 tests, 100% pass rate)\n./bin/utests\n```\n\n### Your First Graph\n```cpp\n#include \"graph/graph.hpp\"\n#include \"graph/search/dijkstra.hpp\"\n\nstruct Location { int id; std::string name; };\n\n// Create graph and add vertices\nGraph\u003cLocation\u003e map;\nmap.AddVertex({0, \"Home\"});\nmap.AddVertex({1, \"Work\"}); \nmap.AddVertex({2, \"Store\"});\n\n// Add weighted edges (distances)\nmap.AddEdge({0, \"Home\"}, {1, \"Work\"}, 5.0);\nmap.AddEdge({0, \"Home\"}, {2, \"Store\"}, 3.0);\nmap.AddEdge({2, \"Store\"}, {1, \"Work\"}, 4.0);\n\n// Find optimal path\nauto path = Dijkstra::Search(map, {0, \"Home\"}, {1, \"Work\"});\n// Result: Home -\u003e Store -\u003e Work (7km total, shorter than direct 5km route)\n```\n\n**[Complete Getting Started Guide →](docs/getting_started.md)**\n\n---\n\n## Documentation\n\n### **For New Users**\n- **[Getting Started Guide](docs/getting_started.md)** - From zero to working graph in 20 minutes\n- **[Complete API Reference](docs/api.md)** - All classes, methods, and examples\n- **[Tutorial Series](docs/tutorials/)** - Progressive learning path\n\n### **For Advanced Users**\n- **[Architecture Overview](docs/architecture.md)** - System design and template patterns\n- **[Advanced Features](docs/advanced_features.md)** - Custom costs, validation, thread safety\n- **[Search Algorithms Guide](docs/search_algorithms.md)** - Deep dive into A*, Dijkstra, BFS, DFS\n- **[Production Readiness](docs/PRODUCTION_READINESS.md)** - Robotics deployment guide\n\n### **For Contributors**\n- **[Performance Testing](docs/performance_testing.md)** - Benchmarking and optimization\n- **[Thread Safety Design](docs/thread_safety_design.md)** - Concurrent search architecture\n- **[Search Framework](docs/search_framework.md)** - Modern strategy pattern implementation\n\n---\n\n## Contributing \u0026 Support\n\n### Getting Help\n- **[Complete Documentation](docs/)** - Comprehensive guides and tutorials\n- **[Report Issues](https://github.com/rxdu/libgraph/issues)** - Bug reports and feature requests\n- **[Discussions](https://github.com/rxdu/libgraph/discussions)** - Questions and community support\n\n### Contributing\n- **Fork \u0026 Pull Request** workflow for contributions\n- **Follow existing code style** and patterns\n- **Add tests** for new functionality\n- **Update documentation** for public API changes\n\n### License \u0026 Citation\n\nThis library is distributed under **MIT License**.\n\n```bibtex\n@misc{libgraph2025,\n  title={libgraph: High-Performance C++ Graph Library},\n  author={Ruixiang Du and contributors},\n  year={2025},\n  url={https://github.com/rxdu/libgraph}\n}\n```\n\n**[→ Complete Roadmap \u0026 TODO List](TODO.md)**\n\n---\n\n**Built for the C++ community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frxdu%2Flibgraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frxdu%2Flibgraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frxdu%2Flibgraph/lists"}