"""Population mixes: validation and resolution of per-area profile shares.
A spawn area may carry ``parameters.population_mix``, a list of
``{"profile": id, "share": int}`` entries referencing the top-level
``population_profiles`` map. Resolved groups are attached to each area's
parameters under :data:`GROUPS_KEY`, which is derived state and is rebuilt
on every initialisation.
"""
from __future__ import annotations
import json
import math
from importlib import resources
from typing import TypeGuard
from .agent_parameters import _area_label, _area_params, _is_number
[docs]
MIX_KEY = "population_mix"
[docs]
GROUPS_KEY = "_population_groups"
[docs]
SUPPORTED_DISTRIBUTIONS = ("constant", "gaussian")
_PROFILE_FIELDS = ("radius", "desired_speed")
[docs]
class PopulationMixError(ValueError):
"""A population mix or a referenced profile is invalid; the run does not start."""
[docs]
def load_population_presets() -> dict:
"""The packaged population presets."""
text = (
resources.files("jupedsim_scenarios")
.joinpath("assets/population_presets.json")
.read_text(encoding="utf-8")
)
return json.loads(text)
[docs]
def allocate_counts(shares: list[int], n: int) -> list[int]:
"""Split ``n`` agents by percentage shares using the largest remainder."""
counts = [n * s // 100 for s in shares]
remainders = [n * s - 100 * c for s, c in zip(shares, counts, strict=True)]
order = sorted(range(len(shares)), key=lambda i: (-remainders[i], i))
for i in order[: n - sum(counts)]:
counts[i] += 1
return counts
def _is_whole_share(share) -> TypeGuard[int]:
return isinstance(share, int) and not isinstance(share, bool)
def _finite(value) -> bool:
return _is_number(value) and math.isfinite(value)
def _check_profile_field(profile_id: str, profile: dict, field: str) -> None:
prefix = f"population profile '{profile_id}': "
spec = profile.get(field)
if not isinstance(spec, dict):
raise PopulationMixError(f"{prefix}{field} is missing")
if "mean" not in spec or spec["mean"] is None:
raise PopulationMixError(f"{prefix}{field}.mean is missing")
if not spec.get("distribution"):
raise PopulationMixError(f"{prefix}{field}.distribution is missing")
name = spec["distribution"]
if name not in SUPPORTED_DISTRIBUTIONS:
raise PopulationMixError(
f"{prefix}{field} distribution '{name}' is not supported (constant, gaussian)"
)
if not _finite(spec["mean"]) or spec["mean"] <= 0:
raise PopulationMixError(f"{prefix}{field}.mean must be a finite number above 0")
std = spec.get("std")
if name == "gaussian" and std is not None and (not _finite(std) or std < 0):
raise PopulationMixError(f"{prefix}{field}.std must be a finite number of at least 0")
def _check_profile(profile_id: str, profile) -> None:
if not isinstance(profile, dict):
raise PopulationMixError(f"population profile '{profile_id}': radius is missing")
for field in _PROFILE_FIELDS:
_check_profile_field(profile_id, profile, field)
def _check_mix(label: str, mix, profiles: dict) -> None:
if not isinstance(mix, list) or not mix:
raise PopulationMixError(
f"{label}: population_mix is empty; remove it to use the area's own radius and speed"
)
seen: set = set()
total = 0
for raw in mix:
item: dict = raw if isinstance(raw, dict) else {}
profile_id, share = item.get("profile"), item.get("share")
if not _is_whole_share(share) or share < 1:
raise PopulationMixError(
f"{label}: share for '{profile_id}' is {share}; "
"each share must be a whole number of at least 1"
)
if profile_id not in profiles:
raise PopulationMixError(f"{label}: unknown population profile '{profile_id}'")
if profile_id in seen:
raise PopulationMixError(
f"{label}: population profile '{profile_id}' is listed more than once"
)
seen.add(profile_id)
total += share
if total != 100:
raise PopulationMixError(f"{label}: population shares total {total} %, must be 100 %")
def _mixes(data: dict):
for key, entry in (data.get("distributions") or {}).items():
mix = _area_params(entry).get(MIX_KEY)
if mix is not None:
yield _area_label(key, entry), mix
[docs]
def validate_population(data: dict) -> None:
"""Reject invalid mixes and the profiles they reference before placement."""
profiles = data.get("population_profiles") or {}
checked: set = set()
for label, mix in _mixes(data):
_check_mix(label, mix, profiles)
for item in mix:
if item["profile"] in checked:
continue
_check_profile(item["profile"], profiles[item["profile"]])
checked.add(item["profile"])
def _std(spec: dict):
std = spec.get("std")
return None if std is None else float(std)
def _group(item: dict, profile: dict) -> dict:
radius, speed = profile["radius"], profile["desired_speed"]
return {
"profile": item["profile"],
"share": item["share"],
"radius": float(radius["mean"]),
"radius_distribution": radius["distribution"],
"radius_std": _std(radius),
"v0": float(speed["mean"]),
"v0_distribution": speed["distribution"],
"v0_std": _std(speed),
}
def _store_params(entry: dict, params: dict) -> None:
if isinstance(entry.get("parameters"), str):
entry["parameters"] = params
[docs]
def resolve_groups(mix: list, profiles: dict) -> list[dict]:
"""Resolved groups of a validated mix, in mix order."""
return [_group(item, profiles[item["profile"]]) for item in mix]
_OWNED_PREFIXES = ("radius", "desired_speed", "v0")
[docs]
def reject_mix_owned_params(key: str, entry: dict, kwargs: dict) -> None:
"""Refuse direct radius or speed settings on an area that has a mix."""
if not _area_params(entry).get(MIX_KEY):
return
if not any(name.startswith(_OWNED_PREFIXES) for name in kwargs):
return
raise PopulationMixError(
f"{_area_label(key, entry)}: radius and desired speed come from "
"population_mix; remove the mix to set them directly"
)
[docs]
def attach_population_groups(data: dict) -> None:
"""Rebuild :data:`GROUPS_KEY` on every area from its current mix."""
profiles = data.get("population_profiles") or {}
for entry in (data.get("distributions") or {}).values():
params = _area_params(entry)
had_stale = params.pop(GROUPS_KEY, None) is not None
mix = params.get(MIX_KEY)
if mix:
params[GROUPS_KEY] = resolve_groups(mix, profiles)
if had_stale or mix:
_store_params(entry, params)