Yog.Community.FluidCommunities (YogEx v0.97.0)

Copy Markdown View Source

Asynchronous Fluid Communities detection algorithm.

This algorithm is based on the simple idea of fluids interacting and expanding in a graph environment. It is unique in that it allows specifying exactly the number of communities k to find.

The algorithm starts with k randomly placed fluids (seeds). Each fluid has a density that decreases as the community grows. Nodes iteratively update their community to match the fluid with the highest density in their neighborhood. The process completes when no node changes its community.

Algorithm

  1. Initialize k random seed nodes as community centers
  2. Iterate until convergence or max iterations:
    • Shuffle nodes randomly
    • For each node: join the community with highest fluid density in neighborhood
    • Density decreases as community size increases (density = weight / size)
  3. Normalize community IDs to be contiguous

When to Use

Use CaseRecommendation
Known number of communities (k)✓ Excellent
Fast detection✓ Good performance
Large graphs✓ Scalable
Unknown kUse Louvain/Leiden instead

Complexity

  • Time: O(k × m × E) where k is communities, m is max iterations
  • Space: O(V + E)

Example

# Find exactly 4 communities
communities = Yog.Community.FluidCommunities.detect_with_options(graph,
  target_communities: 4,
  max_iterations: 100,
  seed: 42
)

# Default: 2 communities
communities = Yog.Community.FluidCommunities.detect(graph)

References

  • Parés, F., et al. (2017). Fluid Communities: A Competitive, Scalable and Diverse Community Detection Algorithm.

Summary

Types

fluid_options()

Options for Fluid Communities algorithm

Functions

default_options()

Returns default options for Fluid Communities.

detect(graph)

Detects communities using Fluid Communities with default options.

detect_with_options(graph, opts)

Detects communities using Fluid Communities with custom options.

Types

fluid_options()

@type fluid_options() :: %{
  target_communities: integer(),
  max_iterations: integer(),
  seed: integer()
}

Options for Fluid Communities algorithm

Functions

default_options()

@spec default_options() :: fluid_options()

Returns default options for Fluid Communities.

Defaults

  • target_communities: 2 - Number of communities to find
  • max_iterations: 100 - Maximum propagation iterations
  • seed: 42 - Random seed for reproducibility

detect(graph)

@spec detect(Yog.graph()) :: Yog.Community.Result.t()

Detects communities using Fluid Communities with default options.

Example

communities = Yog.Community.FluidCommunities.detect(graph)
IO.inspect(communities.num_communities)

detect_with_options(graph, opts)

@spec detect_with_options(Yog.graph(), keyword() | map()) :: Yog.Community.Result.t()

Detects communities using Fluid Communities with custom options.

Options

  • :target_communities - Number of communities to find (default: 2)
  • :max_iterations - Maximum iterations (default: 100)
  • :seed - Random seed (default: 42)

Example

communities = Yog.Community.FluidCommunities.detect_with_options(graph,
  target_communities: 5,
  max_iterations: 150,
  seed: 123
)