# ExLeiden
[](https://hex.pm/packages/ex_leiden) [](https://hexdocs.pm/ex_leiden/)
A pure Elixir implementation of the Leiden algorithm for community detection in networks.
The Leiden algorithm improves upon the Louvain method by addressing the resolution limit problem and ensuring communities that are well-connected internally.
> **Note:** For the best reading experience with properly rendered mathematical formulas, view this README on [GitHub](https://github.com/smartepsh/ex_leiden#readme).
## Installation
Add `ex_leiden` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:ex_leiden, "~> 0.1"}
]
end
```
## Leiden Algorithm Overview
The Leiden algorithm consists of three main phases:
1. **Local moving phase** - Moves nodes between communities to optimize the quality function
2. **Refinement phase** - Splits disconnected communities to ensure well-connected communities
3. **Aggregation phase** - Creates aggregate networks for the next iteration
This approach guarantees well-connected communities and addresses the resolution limit problem found in the Louvain method.
**References: From Louvain to Leiden: guaranteeing well-connected communities**
- [arXiv](https://arxiv.org/abs/1810.08473)
- [DOI](https://doi.org/10.1038/s41598-019-41695-z)
### Quality Functions
ExLeiden supports two quality functions for community detection:
#### Modularity
$$H = \frac{1}{2m} \sum_c \left( e_c - \gamma \frac{K_c^2}{2m} \right)$$
#### Constant Potts Model (CPM)
$$H = \sum_c \left( e_c - \gamma \binom{n_c}{2} \right)$$
**Where:**
- $e_c$ = actual number of edges in community $c$
- $K_c$ = sum of the degrees of the nodes in community $c$
- $m$ = total number of edges in the network
- $\gamma$ = resolution parameter (γ > 0)
- $n_c$ = number of nodes in community $c$
## Usage
```elixir
# TODO
```
### Options
The algorithm behavior can be customized using various options:
- `:quality_function` - Quality function to optimize (`:modularity` or `:cpm`, default: `:modularity`)
- `:modularity` - See [Modularity](#modularity) section for mathematical details
- `:cpm` - See [Constant Potts Model (CPM)](#constant-potts-model-cpm) section for mathematical details
- `:resolution` - Resolution parameter γ controlling community granularity (default: 1.0)
- Higher values (> 1.0) favor smaller, tighter communities
- Lower values (< 1.0) favor larger, looser communities
- Higher γ → smaller communities
- Lower γ → larger communities
- `:max_level` - Maximum hierarchical levels to create (default: 5)
- Controls depth of community hierarchy
- Higher values allow more fine-grained community structure
- Algorithm may stop early if no further improvements can be made, even before reaching max_level
## Error Handling
The only source of errors is option validation. The Leiden algorithm itself cannot fail - it always produces a valid community detection result. Invalid options return `{:error, reason}` tuples:
```elixir
# Invalid options - returns map of option -> reason
{:error, %{
resolution: "must be a positive number",
quality_function: "must be :modularity or :cpm"
}}
```
