Data generation¶

def get_generator_builder(code: str) -> GeneratorBuilder:
    """Return the generator builder for the given code.

    Raises:
        ValueError: If code is not registered.
    """
    normalized = code.strip().upper()
    try:
        return _GENERATOR_BUILDERS[normalized]
    except KeyError as exc:
        available = ", ".join(sorted(_GENERATOR_BUILDERS))
        raise ValueError(f"Unknown generator code: '{code}'. Available: {available}") from exc

def list_generator_codes() -> list[str]:
    """Return sorted list of all registered generator codes."""
    return sorted(_GENERATOR_BUILDERS)

def make_generator_builder(
    generator_factory: Callable[..., Any],
    **default_kwargs: object,
) -> GeneratorBuilder:
    """Create a public `GeneratorBuilder` from a generator factory.

    This helper is intended for external users who want to register custom
    generators while reusing the registry's seeding and relabeling logic.

    Args:
        generator_factory: Callable ``(n_v, n_c, **kw) -> svvamp generator``
            that, when called, returns an svvamp generator object.
        **default_kwargs: Default keyword arguments forwarded to the factory.

    Returns:
        A `GeneratorBuilder` that can be registered in the registry.

    Example::

        from svvamp import GeneratorProfileEuclideanBox
        builder = make_generator_builder(
            GeneratorProfileEuclideanBox,
            box_dimensions=[1.0, 1.0, 1.0],
        )
        register_generator("MY_EUCLID_3D", builder)
    """

    def _builder(
        n_v: int,
        n_c: int,
        *,
        seed: int = 0,
        iteration: int = 0,
        **kw: object,
    ) -> Profile:
        _seed(seed, iteration)
        merged = {**default_kwargs, **kw}
        gen = generator_factory(n_v=n_v, n_c=n_c, **merged)
        return _relabel(gen(), n_c)

    return _builder

def normalize_between_0_and_1(profile: Profile) -> Profile:
    """Return a new Profile with utilities normalized to [0, 1]."""
    ut = profile.preferences_ut
    min_ut = np.min(ut)
    max_ut = np.max(ut)
    if max_ut > min_ut:
        normalized_ut = (ut - min_ut) / (max_ut - min_ut)
    else:
        normalized_ut = np.zeros_like(ut)
    return Profile(preferences_ut=normalized_ut, labels_candidates=profile.labels_candidates)

def register_generator(code: str, builder: GeneratorBuilder) -> None:
    """Register a generator builder under a short code.

    Args:
        code: Short code - case-insensitive, will be normalized.
        builder: Callable ``(n_v, n_c, seed=0, **extra) -> Profile``.
    """
    _GENERATOR_BUILDERS[code.strip().upper()] = builder