babylon.engine.systems.territory_diagnostics

Hex-county-state diagnostics for TerritorySystem (Spec 062 T053).

Constitution II.6: state is data, engine is transformation. Aggregation is a read operation on the graph — never a write — so this module provides pure functions that compute county/state/national rollups for diagnostic display. Primary state remains hex-level (FR-018).

These helpers are the in-memory complement to the Postgres v_*_aggregate views. The view is authoritative; this module covers the case where the engine wants to report per-county production rates inside the same tick, before the envelope commits to Postgres.

See also

babylon.persistence.postgres_aggregation: persisted variant.

Functions

aggregate_counties_by_state(county_rollups)	Aggregate county rollups into state-level rollups.
aggregate_hexes_by_county(graph)	Compute per-county totals from in-memory hex nodes.

Classes

HexCountyRollup(county_fips, c_sum, v_sum, ...)

Per-county aggregation of hex-level c/v/s/k + substrate stocks.

class babylon.engine.systems.territory_diagnostics.HexCountyRollup(county_fips, c_sum, v_sum, s_sum, k_sum, biocapacity_sum, hex_count)

Bases: object

Per-county aggregation of hex-level c/v/s/k + substrate stocks.

Parameters:

• county_fips (str)

• c_sum (float)

• v_sum (float)

• s_sum (float)

• k_sum (float)

• biocapacity_sum (float)

• hex_count (int)

county_fips: str

c_sum: float

v_sum: float

s_sum: float

k_sum: float

biocapacity_sum: float

hex_count: int

__init__(county_fips, c_sum, v_sum, s_sum, k_sum, biocapacity_sum, hex_count)

Parameters:

• county_fips (str)

• c_sum (float)

• v_sum (float)

• s_sum (float)

• k_sum (float)

• biocapacity_sum (float)

• hex_count (int)

Return type:

None

babylon.engine.systems.territory_diagnostics.aggregate_hexes_by_county(graph)

Compute per-county totals from in-memory hex nodes.

Only nodes with _node_type == "hex" AND a county_fips attribute are counted. Other node types (external, county, state) are skipped.

Parameters:

graph (GraphProtocol) – World graph with hex nodes carrying c/v/s/k.

Return type:

dict[str, HexCountyRollup]

Returns:

{county_fips: HexCountyRollup} map. Empty when no hex nodes carry county_fips attributes (e.g., a fresh empty graph).

babylon.engine.systems.territory_diagnostics.aggregate_counties_by_state(county_rollups, county_to_state=None)

Aggregate county rollups into state-level rollups.

Parameters:

• county_rollups (Iterable[HexCountyRollup]) – Iterable of per-county totals.

• county_to_state (dict[str, str] | None) – Optional {county_fips: state_fips} map. When None, the canonical Census rule state_fips = county_fips[:2] applies per FR-023.

Return type:

dict[str, HexCountyRollup]

Returns:

{state_fips: HexCountyRollup} where county_fips field carries the 2-digit state FIPS (the model is reused; the field is polymorphic for diagnostic display).