"""Population diversity entropy.

Per Research Proposal §4 controller, the population's diversity is
summarised as the **sum of per-dimension Shannon entropies** of the
histograms over each search-space coordinate. Higher entropy means the
swarm is spread out (favouring exploitation if the landscape allows);
lower entropy signals collapse onto a single basin (a cue to switch into
exploration).
"""

from __future__ import annotations

import numpy as np
from numpy.typing import NDArray

_LOG2 = np.log(2.0)


def population_entropy(
    population: NDArray[np.float64],
    *,
    bins: int = 10,
    bounds: tuple[float, float] = (0.0, 1.0),
) -> float:
    """Sum of per-dimension Shannon entropies (in bits).

    Parameters
    ----------
    population : NDArray[np.float64]
        Array of shape ``(n, d)`` with rows being individuals.
    bins : int
        Histogram bin count per dimension. Default ``10`` matches the
        controller config.
    bounds : tuple[float, float]
        Histogram range applied to every dimension. Default ``(0, 1)``
        matches the unit-cube convention used throughout the project.

    Returns
    -------
    float
        Non-negative scalar in ``[0, d * log2(bins)]``. Returns ``0.0``
        for a degenerate population (all individuals at the same point).
    """
    p = np.asarray(population, dtype=np.float64)
    if p.ndim != 2:
        raise ValueError(f"population must be 2D (n, d); got shape {p.shape}")
    n, d = p.shape
    if n == 0 or d == 0:
        return 0.0
    if bins < 2:
        raise ValueError(f"bins must be >= 2, got {bins}")

    total = 0.0
    for j in range(d):
        counts, _ = np.histogram(p[:, j], bins=bins, range=bounds)
        probs = counts.astype(np.float64) / float(n)
        nonzero = probs[probs > 0]
        if nonzero.size > 0:
            total += float(-np.sum(nonzero * np.log(nonzero)) / _LOG2)
    return total