Tensor Hierarchy Reference

Complete data dictionary for all tensor types, protocols, default implementations, and validation rules introduced in Feature 025.

For architectural context, see Tensor Hierarchy Architecture. For theory behind the math, see Input-Output Economics and the Leontief Inverse, The Imperial Rent Field: Spatial Value Extraction, and Class Mobility: Markov Chains and Stationary Distributions.

Level 1 Tensor Types 

InterIndustryFlow 

class InterIndustryFlow

BEA input-output direct requirements coefficient matrix. Level 1 tensor sourced from fact_bea_io_coefficient.

Field	Type	Description
`year`	`int`	BEA data year. Constraint: ≥ 1997.
`table_type`	`IOTableType`	Which BEA table this was derived from. Default: `USE`.
`industries`	`list[str]`	Ordered list of BEA Summary-level industry codes (~70 items).
`coefficients`	`np.ndarray`	Direct requirements matrix A, shape `(n, n)`, `float64`.

Computed property:

n_industries → int: Number of industries (length of industries).

Constraints: coefficients.shape == (n, n) where n = len(industries).

Source: DefaultInterIndustryFlowSource reads from fact_bea_io_coefficient populated by BEAIOLoader.

IOTableType 

class IOTableType

Enum for BEA I-O table classification.

Value	Description
`USE`	Use table (commodity-by-industry intermediate use). Basis for direct requirements coefficients A[i,j]. This is the primary source.
`MAKE`	Make table (industry-by-commodity output structure).
`SUPPLY`	Supply table (total supply of commodities from all sources).
`TOTAL_REQ`	Total requirements (Leontief inverse as published by BEA).

VisibilityMetric 

class VisibilityMetric

Diagonal visibility tensor for the four Marxian departments. Wraps Feature 015 gamma module output into the tensor hierarchy.

Field	Type	Description
`year`	`int`	Data year. Constraint: ≥ 2003 (ATUS availability).
`g_diagonal`	`np.ndarray`	Visibility diagonal `[g_11, g_22a, g_22b, g_33]`, shape `(4,)`.
`g_11`	`float`	Department I visibility. Range: [0.0, 1.0]. Expected: ≈ 0.97.
`g_22a`	`float`	Department IIa visibility. Range: [0.0, 1.0]. Expected: ≈ 0.97.
`g_22b`	`float`	Department IIb visibility. Range: [0.0, 1.0]. Expected: ≈ 0.97.
`g_33`	`float`	Department III visibility (care work). Range: [0.0, 1.0]. Expected: [0.20, 0.40]. Approximately 1/3 of US care work is commodified (ATUS data).
`is_estimated`	`bool`	`True` if values are estimated/MVP rather than computed from ATUS. Default: `False`.

Source: DefaultVisibilitySource wraps DefaultGammaIIICalculator.

GeographicFlow 

class GeographicFlow

BTS FAF origin-destination commodity flow matrix. Level 1 tensor sourced from fact_faf_commodity_flow.

Field	Type	Description
`year`	`int`	FAF data year. Constraint: ≥ 2012 (FAF5 data begins).
`areas`	`list[str]`	Ordered list of CFS Area codes (~130 areas).
`flow_matrix`	`np.ndarray`	O-D flow matrix, shape `(n, n)`, values in millions USD.
`commodity_code`	`str \| None`	SCTG 2-digit code for commodity-specific flow; `None` for all-commodity aggregate. Default: `None`.

Computed property:

n_areas → int: Number of CFS areas (length of areas).

Constraints: flow_matrix.shape == (n, n) where n = len(areas).

Source: DefaultGeographicFlowSource reads from fact_faf_commodity_flow populated by FAFLoader.

ReproductionRequirements 

class ReproductionRequirements

Consumption and reproductive labor requirements by social class. Level 1 tensor combining CEX consumer expenditure and ATUS time-use data.

Field	Type	Description
`year`	`int`	Data year. Constraint: ≥ 2000.
`consumption`	`dict`	Nested dict: `class → department → use_value_category → hours`. Represents use-value bundles consumed per class per Marxian department.
`reproductive_labor`	`dict`	Nested dict: `reproduced_class → laborer_class → type → hours`. Represents labor performed to reproduce each class.

Note

Production loader deferred (US4). DefaultReproductionSource returns NoDataSentinel for all queries. All tests use synthetic data.

Source: DefaultReproductionSource (stub).

ClassTransitionMatrix 

class ClassTransitionMatrix

Stochastic matrix of class mobility probabilities. Level 1 tensor from PSID panel study data.

Field	Type	Description
`period`	`tuple[int, int]`	`(start_year, end_year)` defining the transition window.
`classes`	`list[str]`	Ordered list of `SocialRole` class names.
`transition_matrix`	`np.ndarray`	Row-stochastic matrix, shape `(n, n)`. Each row sums to 1.0 (tolerance 1e-6). P[i,j] = probability of class i → class j.

Computed property:

n_classes → int: Number of classes (length of classes).

Constraints: Shape (n, n), n = len(classes). Row sums = 1.0 ± 1e-6.

Note

Production loader deferred (US5). DefaultClassTransitionSource returns NoDataSentinel. Computation engine (DefaultClassTransitionComputer) is fully implemented.

Source: DefaultClassTransitionSource (stub).

Level 2 Tensor Types 

LeontiefInverse 

class LeontiefInverse

Total requirements matrix L = (I − A)⁻¹. Level 2 tensor derived from InterIndustryFlow.

Field	Type	Description
`year`	`int`	Same as source `InterIndustryFlow` year. Constraint: ≥ 1997.
`industries`	`list[str]`	Same ordered BEA industry codes as source `InterIndustryFlow`.
`inverse_matrix`	`np.ndarray`	Total requirements matrix (I − A)⁻¹, shape `(n, n)`. All elements ≥ 0. Diagonal ≥ 1.0.

Computed property:

n_industries → int: Number of industries.

Mathematical guarantee: If Hawkins-Simon holds (all column sums of A < 1), then: all inverse_matrix elements ≥ 0, all diagonal elements ≥ 1.0.

Computed by: DefaultLeontiefComputer.

ImperialRentField 

class ImperialRentField

Net value extraction (inflow − outflow) per CFS area. Level 2 tensor derived from GeographicFlow.

Field	Type	Description
`year`	`int`	Same as source `GeographicFlow` year. Constraint: ≥ 2012.
`areas`	`list[str]`	Same ordered CFS Area codes as source `GeographicFlow`.
`phi`	`np.ndarray`	Net value extraction per area, shape `(n_areas,)`, signed, millions USD. Positive = core (net importer). Negative = periphery (net exporter). Conservation: \|Σφ\| < 0.01% of total flow.

Computed property:

n_areas → int: Number of CFS areas.

Computed by: DefaultImperialRentComputer.

ShadowSubsidyTensor 

class ShadowSubsidyTensor

Shadow subsidy from un-commodified reproductive labor. Level 2 tensor derived from VisibilityMetric.

Field	Type	Description
`year`	`int`	Reference year. Constraint: ≥ 2000.
`phi_iii_labor_hours`	`float`	Shadow subsidy in labor-hours: Dept III value × (1 − g₃₃). ≥ 0.
`phi_iii_dollars`	`float \| None`	Dollar value if MELT (Monetary Expression of Labor Time) is available, else `None`.
`melt_available`	`bool`	Whether MELT was used for the dollar conversion. Default: `False`.

Computed by: DefaultVisibilitySource.

StationaryDistribution 

class StationaryDistribution

Long-run class distribution from ClassTransitionMatrix eigenvector. Level 2 tensor derived from ClassTransitionMatrix.

Field	Type	Description
`period`	`tuple[int, int]`	Same `(start_year, end_year)` as source `ClassTransitionMatrix`.
`classes`	`list[str]`	Same ordered class names as source `ClassTransitionMatrix`.
`distribution`	`np.ndarray`	Stationary distribution π, shape `(n_classes,)`. All elements ≥ 0. Sum = 1.0 (tolerance 1e-6). Satisfies π @ P = π.

Computed property:

n_classes → int: Number of classes.

Computed by: DefaultClassTransitionComputer.

Source Protocols 

Data Source Protocols
Protocol	Methods	Returns
`InterIndustryFlowSource`	`get_direct_requirements(year)` `get_industry_codes()` `available_years()`	`InterIndustryFlow \| NoDataSentinel` `list[str]` `frozenset[int]`
`GeographicFlowSource`	`get_flows(year, commodity_code=None)` `get_cfs_areas()` `get_cfs_to_county_mapping()`	`GeographicFlow \| NoDataSentinel` `list[str]` `dict[str, list[str]]`
`VisibilitySource`	`get_visibility(year)` `get_shadow_subsidy(year, dept_iii_value, melt=None)`	`VisibilityMetric \| NoDataSentinel` `ShadowSubsidyTensor \| NoDataSentinel`
`ReproductionSource`	`get_requirements(year)` `total_reproduction_cost(social_class, year, snlt)`	`ReproductionRequirements \| NoDataSentinel` `float \| NoDataSentinel`
`ClassTransitionSource`	`get_transition_matrix(period)` `get_stationary_distribution(period)`	`ClassTransitionMatrix \| NoDataSentinel` `StationaryDistribution \| NoDataSentinel`

Computation Protocols 

Computation Protocols
Protocol	Methods	Returns
`LeontiefComputer`	`compute_inverse(flow)` `total_labor_coefficients(leontief, direct_labor)`	`LeontiefInverse` `np.ndarray` (shape: n)
`ImperialRentComputer`	`compute_rent_field(flow)` `decompose_symmetric_antisymmetric(flow)`	`ImperialRentField` `tuple[np.ndarray, np.ndarray]`
`DepartmentAggregator`	`aggregate(flow, mapping)` `get_default_mapping()`	`InterIndustryFlow` (4×4) `dict[str, str]`

All protocols use @runtime_checkable, enabling isinstance checks at runtime.

Default Implementations 

Protocol → Default Implementation Mapping
Protocol	Default Class	Module
`InterIndustryFlowSource`	`DefaultInterIndustryFlowSource`	`inter_industry`
`GeographicFlowSource`	`DefaultGeographicFlowSource`	`geographic_flow`
`VisibilitySource`	`DefaultVisibilitySource`	`visibility`
`ReproductionSource`	`DefaultReproductionSource` (stub)	`reproduction`
`ClassTransitionSource`	`DefaultClassTransitionSource` (stub)	`class_transition`
`LeontiefComputer`	`DefaultLeontiefComputer`	`inter_industry`
`ImperialRentComputer`	`DefaultImperialRentComputer`	`geographic_flow`
`DepartmentAggregator`	`DefaultDepartmentAggregator`	`inter_industry`

Additional helper classes:

DefaultGeographicAggregator — Aggregates CFS area flows to state level.
DefaultClassTransitionComputer — Computes stationary distributions and class aggregation (not a protocol implementation, a standalone computer).
DefaultReproductionRequirementsComputer — Computes reproduction requirements from synthetic data (not a protocol implementation).

All implementations are in src/babylon/economics/tensor_hierarchy/.

Validation Rules 

Three-Tier Validation Thresholds
Rule	Expected	Warning	Fail	Function
I-O col sum max	≤ 0.90	> 0.90	≥ 1.0	`validate_io_column_sums`
Individual coefficient	≤ 0.60	> 0.60	< 0 or ≥ 1.0	(inline)
Leontief elements	≥ 0	—	< −1e-10	`validate_leontief_properties`
Leontief diagonal	≥ 1.0	—	< 1.0 − 1e-10	`validate_leontief_properties`
g_33 (Dept III)	[0.20, 0.40]	[0.10, 0.50]	<0 or >1	`validate_g33`
g_11, g_22a, g_22b	[0.90, 1.0]	[0.70, 1.0]	<0 or >1	`validate_g_productive`
Rent conservation	\|Σφ\|/total < 0.01%	\|Σφ\|/total < 0.1%	\|Σφ\|/total ≥ 1%	`validate_rent_conservation`
Transition row sum	deviation ≤ 1e-6	deviation ≤ 1e-4	deviation > 1e-4	`validate_transition_matrix`
Transition diagonal	≥ 0.50	≥ 0.20	< 0	`validate_transition_matrix`

All validation functions return (bool, str | None): (True, None) = pass, (True, str) = warning, (False, str) = fail.