# `Yog.Community.FluidCommunities`
[🔗](https://github.com/code-shoily/yog_ex/blob/v0.97.0/lib/yog/community/fluid_communities.ex#L1)

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 Case | Recommendation |
|----------|----------------|
| Known number of communities (k) | ✓ Excellent |
| Fast detection | ✓ Good performance |
| Large graphs | ✓ Scalable |
| Unknown k | Use 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.

# `fluid_options`

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

Options for Fluid Communities algorithm

# `default_options`

```elixir
@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`

```elixir
@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`

```elixir
@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
    )

---

*Consult [api-reference.md](api-reference.md) for complete listing*