{"id":48230887,"url":"https://github.com/code-shoily/yog","last_synced_at":"2026-04-04T19:36:49.400Z","repository":{"id":340680663,"uuid":"1167125399","full_name":"code-shoily/yog","owner":"code-shoily","description":"A graph algorithm library in Gleam","archived":false,"fork":false,"pushed_at":"2026-03-23T04:18:53.000Z","size":630,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T07:18:10.178Z","etag":null,"topics":["centrality","dijkstra-algorithm","functional-programming","gleam","graph-algorithms","maxflow-mincut","mermaid","pagerank"],"latest_commit_sha":null,"homepage":"","language":"Gleam","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/code-shoily.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2026-02-26T00:57:41.000Z","updated_at":"2026-03-23T04:17:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/code-shoily/yog","commit_stats":null,"previous_names":["code-shoily/yog"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/code-shoily/yog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-shoily%2Fyog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-shoily%2Fyog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-shoily%2Fyog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-shoily%2Fyog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/code-shoily","download_url":"https://codeload.github.com/code-shoily/yog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-shoily%2Fyog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31411348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T19:29:44.979Z","status":"ssl_error","status_checked_at":"2026-04-04T19:29:11.535Z","response_time":60,"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":["centrality","dijkstra-algorithm","functional-programming","gleam","graph-algorithms","maxflow-mincut","mermaid","pagerank"],"created_at":"2026-04-04T19:36:48.423Z","updated_at":"2026-04-04T19:36:49.390Z","avatar_url":"https://github.com/code-shoily.png","language":"Gleam","readme":"# Yog\n\n```text\n                    ★\n                   /|\\\n                  / | \\\n                 /  |  \\\n                Y   |   O--------G\n               /    |    \\      /\n              /     |     \\    /\n             /      |      \\  /\n            যো------+-------গ\n           / \\      |      / \\\n          /   \\     |     /   \\\n         /     \\    |    /     \\\n        ✦       ✦   |   ✦       ✦\n                   \n```\n\n[![Package Version](https://img.shields.io/hexpm/v/yog)](https://hex.pm/packages/yog)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/yog/)\n\nA graph algorithm library for Gleam, providing implementations of classic graph algorithms with a functional API.\n\n🔷 **[F# Port](https://github.com/code-shoily/yog-fsharp)** - Also available for F# with similar functional APIs | 📊 **[Gleam vs F# Comparison](GLEAM_FSHARP_COMPARISON.md)** - Detailed feature comparison\n\n## Features\n\n- **Graph Data Structures**: Directed and undirected graphs with generic node and edge data\n- **Pathfinding Algorithms**: Dijkstra, A*, Bellman-Ford, Floyd-Warshall, Johnson's, and **Implicit Variants** (state-space search)\n- **Maximum Flow**: Highly optimized Edmonds-Karp algorithm with flat dictionary residuals\n- **Graph Generators**: Create classic patterns (complete, cycle, path, star, wheel, bipartite, trees, grids) and random graphs (Erdős-Rényi, Barabási-Albert, Watts-Strogatz)\n- **Graph Traversal**: BFS and DFS with early termination and **Implicit Variants**\n- **Graph Transformations**: Transpose (O(1)!), map, filter, merge, subgraph extraction, edge contraction\n- **Graph Visualization**: Mermaid, DOT (Graphviz), and ASCII rendering\n- **Minimum Spanning Tree**: Kruskal's and Prim's algorithms with Union-Find and Priority Queues\n- **Minimum Cut**: Stoer-Wagner algorithm for global min-cut\n- **Network Health**: Diameter, radius, eccentricity, assortativity, average path length\n- **Directed Acyclic Graphs (DAG)**: Strictly-validated `Dag(n, e)` wrapper bringing O(V+E) DP routines like `longest_path` (Critical Path), LCA, and transitive structures\n- **Topological Sorting**: Kahn's algorithm with lexicographical variant, alongside guaranteed cycle-free DAG-specific sorts\n- **Strongly Connected Components**: Tarjan's and Kosaraju's algorithms\n- **Maximum Clique**: Bron-Kerbosch algorithm for maximal and all maximal cliques\n- **Connectivity**: Bridge and articulation point detection\n- **Eulerian Paths \u0026 Circuits**: Detection and finding using Hierholzer's algorithm\n- **Bipartite Graphs**: Detection, maximum matching, and stable marriage (Gale-Shapley)\n- **Minimum Cost Flow (MCF)**: Global optimization using the robust **Network Simplex** algorithm\n- **Disjoint Set (Union-Find)**: With path compression and union by rank\n- **Efficient Data Structures**: Pairing heap for priority queues, two-list queue for BFS\n- **Property-Based Testing**: Exhaustively tested across core graph operations and invariants using `qcheck`\n\n### ⚠️ Experimental Features\n\nThe following modules are **experimental** and provide minimal, working functionality:\n\n- **Multigraphs** (`yog/multi/*`): Support for graphs with multiple edges between the same pair of nodes\n  - Multiple parallel edges with unique edge IDs\n  - Eulerian path and circuit detection for multigraphs\n  - BFS/DFS traversal adapted for parallel edges\n  - Conversion to simple graphs with configurable edge merging strategies\n- **DAG-specific operations** (`yog/dag/*`): Type-safe wrapper for directed acyclic graphs\n  - Compile-time acyclicity guarantees\n  - O(V+E) DAG-specific algorithms (longest path, shortest path)\n  - Transitive closure and reduction\n  - Lowest common ancestors (LCA)\n  - Reachability counting for ancestors/descendants\n\nThese modules are functional but may not be fully optimized for performance. Additional features, performance enhancements, and API changes are expected in future versions. Use with caution in production environments.\n\n## Installation\n\nAdd Yog to your Gleam project:\n\n```sh\ngleam add yog\n```\n\n## Quick Start\n\n```gleam\nimport gleam/int\nimport gleam/io\nimport gleam/option.{None, Some}\nimport yog\nimport yog/pathfinding/dijkstra\n\npub fn main() {\n  // Create a directed graph\n  let graph =\n    yog.directed()\n    |\u003e yog.add_node(1, \"Start\")\n    |\u003e yog.add_node(2, \"Middle\")\n    |\u003e yog.add_node(3, \"End\")\n\n  let assert Ok(graph) =\n    yog.add_edges(graph, [\n      #(1, 2, 5),\n      #(2, 3, 3),\n      #(1, 3, 10)\n    ])\n\n  // Find shortest path\n  case dijkstra.shortest_path(\n    in: graph,\n    from: 1,\n    to: 3,\n    with_zero: 0,\n    with_add: int.add,\n    with_compare: int.compare\n  ) {\n    Some(path) -\u003e {\n      io.println(\"Found path with weight: \" \u003c\u003e int.to_string(path.total_weight))\n    }\n    None -\u003e io.println(\"No path found\")\n  }\n}\n```\n\n## Examples\n\nWe have some real-world projects that use Yog for graph algorithms:\n\n- [Lustre Graph Generator](https://github.com/code-shoily/lustre_graph_generator) ([Demo](https://code-shoily.github.io/lustre_graph_generator/)) - Showcases graph generation, topological sort and shortest distance feature of Yog.\n- [Advent of Code Solutions](https://github.com/code-shoily/aocgl/blob/main/wiki/tags/graph.md) - Multiple AoC puzzles solved using Yog's graph capabilities.\n\nDetailed examples are located in the [test/examples/](https://github.com/code-shoily/yog/tree/main/test/examples) directory:\n\n- [Social Network Analysis](https://github.com/code-shoily/yog/blob/main/test/examples/social_network_analysis.gleam) - Finding communities using SCCs.\n- [Task Scheduling](https://github.com/code-shoily/yog/blob/main/test/examples/task_scheduling.gleam) - Basic topological sorting.\n- [GPS Navigation](https://github.com/code-shoily/yog/blob/main/test/examples/gps_navigation.gleam) - Shortest path using A* and heuristics.\n- [Network Cable Layout](https://github.com/code-shoily/yog/blob/main/test/examples/network_cable_layout.gleam) - Minimum Spanning Tree using Kruskal's.\n- [Network Bandwidth](https://github.com/code-shoily/yog/blob/main/test/examples/network_bandwidth.gleam) - ⭐ Max flow for bandwidth optimization with bottleneck analysis.\n- [Job Matching](https://github.com/code-shoily/yog/blob/main/test/examples/job_matching.gleam) - ⭐ Max flow for bipartite matching and assignment problems.\n- [Cave Path Counting](https://github.com/code-shoily/yog/blob/main/test/examples/cave_path_counting.gleam) - Custom DFS with backtracking.\n- [Task Ordering](https://github.com/code-shoily/yog/blob/main/test/examples/task_ordering.gleam) - Lexicographical topological sort.\n- [Bridges of Königsberg](https://github.com/code-shoily/yog/blob/main/test/examples/bridges_of_konigsberg.gleam) - Eulerian circuit and path detection.\n- [Global Minimum Cut](https://github.com/code-shoily/yog/blob/main/test/examples/global_min_cut.gleam) - Stoer-Wagner algorithm.\n- [Job Assignment](https://github.com/code-shoily/yog/blob/main/test/examples/job_assignment.gleam) - Bipartite maximum matching.\n- [Medical Residency](https://github.com/code-shoily/yog/blob/main/test/examples/medical_residency.gleam) - Stable marriage matching (Gale-Shapley algorithm).\n- [City Distance Matrix](https://github.com/code-shoily/yog/blob/main/test/examples/city_distance_matrix.gleam) - Floyd-Warshall for all-pairs shortest paths.\n- [Graph Generation Showcase](https://github.com/code-shoily/yog/blob/main/test/examples/graph_generation_showcase.gleam) - ⭐ All 9 classic graph patterns with statistics.\n- [DOT rendering](https://github.com/code-shoily/yog/blob/main/test/examples/render_dot.gleam) - Exporting graphs to Graphviz format.\n- [Mermaid rendering](https://github.com/code-shoily/yog/blob/main/test/examples/render_mermaid.gleam) - Generating Mermaid diagrams.\n- [Graph creation](https://github.com/code-shoily/yog/blob/main/test/examples/graph_creation.gleam) - Comprehensive guide to 10+ ways of creating graphs.\n\n### Running Examples Locally\n\nThe examples live in the `test/examples/` directory and can be run directly:\n\n```sh\ngleam run -m examples/gps_navigation\ngleam run -m examples/network_bandwidth\n# etc.\n```\n\n## Algorithm Selection Guide\n\nDetailed documentation for each algorithm can be found on [HexDocs](https://hexdocs.pm/yog/).\n\n| Algorithm | Use When | Time Complexity |\n| --------- | -------- | --------------- |\n| **Dijkstra** | Non-negative weights, single shortest path | O((V+E) log V) |\n| **Bidirectional Dijkstra** | Known target, weighted graphs, ~2× faster | O((V+E) log V / 2) |\n| **Bidirectional BFS** | Known target, unweighted graphs, up to 500× faster | O(b^(d/2)) |\n| **A*** | Non-negative weights + good heuristic | O((V+E) log V) |\n| **Bellman-Ford** | Negative weights OR cycle detection needed | O(VE) |\n| **Floyd-Warshall** | All-pairs shortest paths, distance matrices | O(V³) |\n| **Johnson's** | All-pairs shortest paths in sparse graphs with negative weights | O(V² log V + VE) |\n| **Edmonds-Karp** | Maximum flow, bipartite matching, network optimization | O(VE²) |\n| **BFS/DFS** | Unweighted graphs, exploring reachability | O(V+E) |\n| **Kruskal's MST** | Finding minimum spanning tree | O(E log E) |\n| **Stoer-Wagner** | Global minimum cut, graph partitioning | O(V³) |\n| **Tarjan's SCC** | Finding strongly connected components | O(V+E) |\n| **Tarjan's Connectivity** | Finding bridges and articulation points | O(V+E) |\n| **Hierholzer** | Eulerian paths/circuits, route planning | O(V+E) |\n| **DAG Longest Path** | Critical path analysis on strictly directed acyclic graphs | O(V+E) |\n| **Topological Sort** | Ordering tasks with dependencies | O(V+E) |\n| **Gale-Shapley** | Stable matching, college admissions, medical residency | O(n²) |\n| **Prim's MST** | Minimum spanning tree (starts from node) | O(E log V) |\n| **Kosaraju's SCC** | Strongly connected components (two-pass) | O(V + E) |\n| **Bron-Kerbosch** | Maximum and all maximal cliques | O(3^(n/3)) |\n| **Network Simplex** | Global minimum cost flow optimization | O(E) pivots |\n| **Implicit Search** | Pathfinding/Traversal on on-demand graphs | O((V+E) log V) |\n| **PageRank** | Link-quality node importance | O(V+E) per iter |\n| **Betweenness** | Bridge/gatekeeper detection | O(VE) or O(V³) |\n| **Closeness / Harmonic** | Distance-based importance | O(VE log V) |\n| **Eigenvector / Katz** | Influence based on neighbor centrality | O(V+E) per iter |\n| **Louvain** | Modularity optimization, large graphs | O(E log V) |\n| **Leiden** | Quality guarantee, well-connected communities | O(E log V) |\n| **Label Propagation** | Very large graphs, extreme speed | O(E) per iter |\n| **Infomap** | Information-theoretic flow tracking | O(E) per iter |\n| **Walktrap** | Random-walk structural communities | O(V² log V) |\n| **Girvan-Newman** | Hierarchical edge betweenness | O(E²V) |\n| **Clique Percolation** | Overlapping community discovery | O(3^(V/3)) |\n| **Local Community** | Massive/infinite graphs, seed expansion | O(S × E_S) |\n| **Fluid Communities** | Exact `k` partitions, fast | O(E) per iter |\n\n## Benchmarking\n\nYog includes built-in benchmarking utilities using `gleamy/bench`. Run the example benchmark:\n\n```bash\ngleam run -m bench/simple_pathfinding\n```\n\nFor detailed instructions on creating custom benchmarks, interpreting results, and comparing against reference implementations, see the [Benchmarking Guide](BENCHMARKING_GUIDE.md).\n\n## Development\n\n### Running Tests\n\nRun the full test suite:\n\n```bash\ngleam test\n```\n\nRun tests for a specific module:\n\n```bash\n./test_module.sh yog/pathfinding/bidirectional_test\n```\n\nRun a specific test function:\n\n```bash\n./test_module.sh yog/pathfinding/bidirectional_test dijkstra_complex_diamond_test\n```\n\n### Running Examples\n\nRun all examples at once:\n\n```bash\n./run_examples.sh\n```\n\nRun a specific example:\n\n```bash\ngleam run -m examples/gps_navigation\n```\n\n### Project Structure\n\n- `src/yog/` - Core graph library modules\n- `test/` - Unit tests and property-based tests\n- `test/examples/` - Real-world usage examples\n- `test/bench/` - Performance benchmarks\n\n## AI Assistance\n\nParts of this project were developed with the assistance of AI coding tools. All AI-generated code has been reviewed, tested, and validated by the maintainer.\n\n---\n\n**Yog** - Graph algorithms for Gleam\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-shoily%2Fyog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcode-shoily%2Fyog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-shoily%2Fyog/lists"}