babylon.engine.hydration

Hydration package for initializing simulation state from reference data.

class babylon.engine.hydration.CountyInfo(county_id, fips, county_name)[source]

Bases: object

County metadata from dim_county.

Parameters:

  • 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

county_id: int
fips: str
county_name: str
class babylon.engine.hydration.StubBEASource[source]

Bases: object

Stub BEA source that returns None, letting DepartmentMapper provide defaults.

The MarxianHydrator falls back to sector-level ratios from DepartmentMapper when the BEA source returns None.

get_cv_ratio(naics_code, year)[source]

Return None to fall back to DepartmentMapper defaults.

Return type:

float | None

Parameters:
get_sv_ratio(naics_code, year)[source]

Return None to fall back to DepartmentMapper defaults.

Return type:

float | None

Parameters:
babylon.engine.hydration.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.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.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.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.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.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.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.

Modules

reference

MVP Simulation Engine hydrator for SQLite reference data.