babylon.engine.systems.distribution

Distribution system: Vol III Pt IV-VI surplus split at county scale.

Spec 062 T059 / FR-032 / FR-033. At county scale, surplus value s is split into four components:

s = p + i + r + t

where:

  • p = retained profit (residual)

  • i = interest (FRED Fed Funds Rate * county capital stock)

  • r = rent (BEA REIS county rent series)

  • t = taxes (effective tax rate × s)

Conservation: p + i + r + t MUST equal s exactly per FR-032/FR-033.

For the MVP the split coefficients come from GameDefines fallback constants (0.05 / 0.10 / 0.30) so unit tests can exercise the conservation property without the full Postgres-backed reference series in place. When the live runtime is wired up via the lookup helper, the constants are replaced by year-scoped ImmutableReferenceLookup queries.

See also

specs/062-cross-scale-integration/spec.md FR-032/FR-033. babylon.kernel.system_protocol: System Protocol.

Functions

split_surplus_to_pirt(*, s[, interest_rate, ...])

Distribute county-scale s into (p, i, r, t).

Classes

DistributionSplit(s, p, i, r, t)

Result of splitting county surplus value into the four components.
babylon.engine.systems.distribution.split_surplus_to_pirt(*, s, interest_rate=0.05, rent_rate=0.10, tax_rate=0.30)[source]

Distribute county-scale s into (p, i, r, t).

Parameters:

  • s (float) – Surplus value at the county scale this tick.

  • interest_rate (float) – Fraction of s paid as interest (FR-032 — derived from FRED Fed Funds in production, constant here for testing). Must satisfy 0 <= interest_rate <= 1.

  • rent_rate (float) – Fraction of s paid as rent (FR-032 — derived from BEA REIS in production). Must satisfy 0 <= rent_rate <= 1.

  • tax_rate (float) – Fraction of s paid as taxes. Must satisfy 0 <= tax_rate <= 1.

Return type:

DistributionSplit

Returns:

DistributionSplit with p as residual, guaranteeing exact conservation per FR-032/FR-033.

Raises:

ValueError – If any rate is outside [0, 1] or if the sum of rates exceeds 1.0 (which would force negative residual profit).

Example

>>> split = split_surplus_to_pirt(s=100.0, interest_rate=0.1, rent_rate=0.2, tax_rate=0.3)
>>> split.t == 30.0
True
>>> split.r == 20.0
True
>>> split.i == 10.0
True
>>> split.p == 40.0
True
class babylon.engine.systems.distribution.DistributionSplit(s, p, i, r, t)[source]

Bases: object

Result of splitting county surplus value into the four components.

p + i + r + t == s exactly (FR-032 / FR-033). The split is sign-preserving: negative surplus (rare; signals data drift) is not distributed and the entire amount is recorded as p so the conservation identity holds.

Parameters:
s: float
p: float
i: float
r: float
t: float
__init__(s, p, i, r, t)
Parameters:
Return type:

None