Data generation¶

Generator codes¶

All generators are integrated via the generative_models key in config/simulation.toml.

svvamp-based generators¶

Code	Generator
EUCLID	Euclidean Box
EUCLID_1D	Euclidean Box (1D)
EUCLID_2D	Euclidean Box (2D)
EUCLID_3D	Euclidean Box (3D)
EUCLID_5D	Euclidean Box (5D)
GAUSS	Gaussian Well
IANC	Impartial, Anonymous & Neutral Culture — ⚠️ known issues
IC	Impartial Culture
LADDER	Ladder
PERTURB	Perturbed Culture
SPHEROID	Spheroid
UFR	Uniform Few Rankings
UNANIMOUS	Unanimous
UNI	Cubic Uniform
VMF_HC	Von Mises-Fisher Hypercircle
VMF_HS	Von Mises-Fisher Hypersphere

R-based generators (Dirichlet Diffusion Dynamics)¶

These generators require R with the MASS and randcorr packages. They produce utility matrices using Beta-marginal Dirichlet diffusion on an opinion simplex.

Code	Description
DDD_BETA_0-05	Beta marginals with α, β ∈ (0, 0.05]
DDD_BETA_0-5	Beta marginals with α, β ∈ (0, 0.5]
DDD_BETA_1	Beta marginals with α, β ∈ (0, 1.0]
DDD_BETA_2	Beta marginals with α, β ∈ (0, 2.0]
DDD_BETA_5	Beta marginals with α, β ∈ (0, 5.0]
DDD_BETA_POLAR	Polarised Beta (α = β ∈ (0, 0.5])

Generator registry mapping short codes to svvamp GeneratorProfile factories.

Usage examples:

> from vote_simulation.models.data_generation.generator_registry import get_generator_builder
> builder = get_generator_builder("UNI")
> profile = builder(n_v=100, n_c=5, seed=42)

`GeneratorBuilder = Callable[..., Profile]` `module-attribute` ¶

Signature: (n_v, n_c, seed=0, **extra) -> svvamp.Profile

`get_generator_builder(code)` ¶

Return the generator builder for the given code.

Raises:

Type	Description
`ValueError`	If code is not registered.

Source code in src/vote_simulation/models/data_generation/generator_registry.py

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

`list_generator_codes()` ¶

Return sorted list of all registered generator codes.

Source code in src/vote_simulation/models/data_generation/generator_registry.py

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

`make_generator_builder(generator_factory, **default_kwargs)` ¶

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.

Parameters:

Name	Type	Description	Default
`generator_factory`	`Callable[..., Any]`	Callable `(n_v, n_c, **kw) -> svvamp generator` that, when called, returns an svvamp generator object.	required
`**default_kwargs`	`object`	Default keyword arguments forwarded to the factory.	`{}`

Returns:

Type	Description
`GeneratorBuilder`	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)

Source code in src/vote_simulation/models/data_generation/generator_registry.py

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

`register_generator(code, builder)` ¶

Register a generator builder under a short code.

Parameters:

Name	Type	Description	Default
`code`	`str`	Short code - case-insensitive, will be normalized.	required
`builder`	`GeneratorBuilder`	Callable `(n_v, n_c, seed=0, **extra) -> Profile`.	required

Source code in src/vote_simulation/models/data_generation/generator_registry.py

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