babylon.engine.hydration.reference

MVP Simulation Engine hydrator for SQLite reference data.

This module provides hydration functions to initialize simulation state from the reference database (marxist-data-3NF.sqlite). It bridges the gap between raw federal statistical data and simulation-ready TerritoryState objects.

Key Functions:

  • query_counties: Fetch county metadata from dim_county

  • query_hex_claims: Fetch H3 cells from bridge_county_h3

  • compute_initial_profit_rate: Calculate profit_rate from QCEW/BEA data

  • hydrate_territories: Create TerritoryState objects from database

See also

  • research.md#3. SQLite Reference Database Schema

  • research.md#4. Economics Hydrator

  • plan.md#Hydration Flow

Functions

compute_initial_profit_rate(fips, year)

Compute initial profit_rate from QCEW/BEA data.

hydrate_class_shares(fips, year)

Derive class distribution shares from QCEW employment data.

hydrate_economy_constants(fips, year)

Derive economy constants from QCEW/BEA data.

hydrate_industry_hyperedges(fips_codes[, year])

Hydrate industry hyperedges from SQLite reference database.

hydrate_reserve_army(fips, year)

Derive reserve army parameters from QCEW employment data.

hydrate_territories(fips_codes[, year])

Hydrate territories from SQLite reference database.

query_counties(fips_codes[, session])

Fetch county metadata from dim_county.

query_hex_claims(county_ids[, session])

Fetch H3 cells from bridge_county_h3 for given counties.

Classes

CountyInfo(county_id, fips, county_name)

County metadata from dim_county.

StubBEASource()

Stub BEA source that returns None, letting DepartmentMapper provide defaults.
class babylon.engine.hydration.reference.CountyInfo(county_id, fips, county_name)[source]

Bases: object

County metadata from dim_county.

Parameters:

  • county_id (int)

  • fips (str)

  • county_name (str)

county_id: int
fips: str
county_name: str
__init__(county_id, fips, county_name)
Parameters:

  • county_id (int)

  • fips (str)

  • county_name (str)

Return type:

None

babylon.engine.hydration.reference.compute_initial_profit_rate(fips, year)[source]

Compute initial profit_rate from QCEW/BEA data.

Uses MarxianHydrator to compute c, v, s, then derives profit_rate.

profit_rate = s / (c + v)

Where:

s = surplus value (total across departments) c = constant capital (total across departments) v = variable capital (total across departments)

Parameters:

  • fips (str) – 5-digit FIPS code.

  • year (int) – Data year.

Return type:

float

Returns:

Profit rate in range [0.0, 1.0] (clamped if necessary).

Raises:

ValueError – If QCEW data is missing for the county.

babylon.engine.hydration.reference.hydrate_class_shares(fips, year)[source]

Derive class distribution shares from QCEW employment data.

Uses wage percentile analysis of QCEW data to estimate the class structure for a given county. Falls back to GameDefines defaults if data is unavailable.

Parameters:

  • fips (str) – 5-digit FIPS code.

  • year (int) – Data year.

Returns:

bourgeoisie, petit_bourgeoisie, labor_aristocracy, proletariat, lumpenproletariat, unemployment_rate, median_wage.

Return type:

Dict with keys

babylon.engine.hydration.reference.hydrate_economy_constants(fips, year)[source]

Derive economy constants from QCEW/BEA data.

Computes extraction_efficiency (s/(c+v)) and related constants from the MarxianHydrator tensor decomposition.

Parameters:

  • fips (str) – 5-digit FIPS code.

  • year (int) – Data year.

Returns:

extraction_efficiency, shadow_wage_hourly, base_subsistence. Missing values omitted (caller uses defaults).

Return type:

Dict with keys

babylon.engine.hydration.reference.hydrate_industry_hyperedges(fips_codes, year=2022)[source]

Hydrate industry hyperedges from SQLite reference database.

Parameters:

  • fips_codes (list[str]) – List of 5-digit FIPS codes for counties.

  • year (int) – Data year for QCEW/BEA data (default 2022).

Return type:

dict[str, IndustryHyperedge]

Returns:

Dict mapping industry ID (e.g. ind_62) to IndustryHyperedge.

babylon.engine.hydration.reference.hydrate_reserve_army(fips, year)[source]

Derive reserve army parameters from QCEW employment data.

Uses county-level employment data to estimate the baseline unemployment rate for the sigmoid_r0 parameter.

Parameters:

  • fips (str) – 5-digit FIPS code.

  • year (int) – Data year.

Return type:

dict[str, float]

Returns:

Dict with key sigmoid_r0 if derivable. Empty dict otherwise.

babylon.engine.hydration.reference.hydrate_territories(fips_codes, year=2022)[source]

Hydrate territories from SQLite reference database.

This is the main entry point for initializing simulation state from the reference database.

Parameters:

  • fips_codes (list[str]) – List of 5-digit FIPS codes for counties to hydrate.

  • year (int) – Data year for QCEW/BEA data (default 2022).

Returns:

  • territories: Dict mapping territory_id (FIPS) to TerritoryState

  • hexes: Dict mapping h3_index to HexState

Return type:

Tuple of (territories, hexes)

Raises:

ValueError – If fips_codes is empty or any county is not found.

babylon.engine.hydration.reference.query_counties(fips_codes, session=None)[source]

Fetch county metadata from dim_county.

Parameters:

  • fips_codes (list[str]) – List of 5-digit FIPS codes to fetch.

  • session (Session | None) – Optional existing session. If None, creates a new one.

Return type:

dict[str, CountyInfo]

Returns:

Dict mapping FIPS code to CountyInfo.

Raises:

ValueError – If any requested FIPS code is not found.

babylon.engine.hydration.reference.query_hex_claims(county_ids, session=None)[source]

Fetch H3 cells from bridge_county_h3 for given counties.

Parameters:

  • county_ids (list[int]) – List of county_id values from dim_county.

  • session (Session | None) – Optional existing session.

Return type:

dict[int, set[str]]

Returns:

Dict mapping county_id to set of H3 index strings. Counties with no H3 cells will have empty sets.