Fundamental Tensor Primitive Reference

Technical reference for the ValueTensor4x3 — the single source of truth for all economic data in the Babylon simulation. All values are measured in labor-hours, not monetary units. The tensor layer is the only component that queries the database for economic data.

Core Data Types 

NoDataSentinel 

Non-instantiable falsy marker for missing tensor data. Enables the walrus operator pattern:

if tensor := registry.get("26163", 2020):
    print(tensor.exploitation_rate)
else:
    print(tensor.reason)  # "FIPS code not in database"

NoDataSentinel Fields
Field	Type	Description
`fips`	`str`	5-digit county FIPS code
`year`	`int`	Calendar year
`reason`	`str`	Human-readable error (format: `"{context}: {reason}"`)

bool(sentinel) returns False. Implements __eq__ and __hash__ for use in dicts and sets.

DepartmentRow 

Value composition for a single Marxian department. Frozen Pydantic model with three non-negative LaborHours fields.

DepartmentRow Fields
Field	Type	Description
`c`	`LaborHours`	Constant capital (dead labor / means of production consumed)
`v`	`LaborHours`	Variable capital (living labor / wages paid)
`s`	`LaborHours`	Surplus value (unpaid labor appropriated by capital)

Computed properties:

Property	Formula	Note
`total_value`	c + v + s	Total commodity value
`organic_composition`	c / v	Capital intensity (`inf` if v = 0)
`exploitation_rate`	s / v	Unpaid labor ratio (`inf` if v = 0)

ValueTensor4x3 

The fundamental 4×3 Marxian reproduction schema for a county-year. Frozen Pydantic model with index structure T^μ_ν[fips, year] where μ ∈ {I, IIa, IIb, III} and ν ∈ {c, v, s}.

ValueTensor4x3 Fields
Field	Type	Description
`fips_code`	`str[5]`	County FIPS code (regex validated)
`year`	`int >= 1900`	Calendar year
`dept_I`	`DepartmentRow`	Means of production (capital goods)
`dept_IIa`	`DepartmentRow`	Necessary consumption (wage goods)
`dept_IIb`	`DepartmentRow`	Luxury consumption (bourgeois goods)
`dept_III`	`DepartmentRow`	Social reproduction (care work)
`naics_granularity`	`Probability`	Data quality: fraction of wages with 6-digit NAICS
`excluded_wages`	`LaborHours`	Government/excluded sector wages (outside M-C-M’)
`visibility_g33`	`float [0, 1]`	Visibility of care work to price system (Fortunati)

Departments 

Four Marxian Departments
Code	Name	Description
I	Means of Production	Capital goods: machinery, raw materials, infrastructure
IIa	Necessary Consumption	Wage goods: food, housing, transport for workers
IIb	Luxury Consumption	Bourgeois goods: luxury housing, yachts, art
III	Social Reproduction	Care work: childcare, cooking, eldercare, emotional labor

Computed Metrics 

Aggregate Metrics 

Property	Formula	Description
`total_value`	Σ dept.total_value	Total commodity value across all departments
`total_c`	Σ dept.c	Total constant capital
`total_v`	Σ dept.v	Total variable capital (total wages in labor-hours)
`total_s`	Σ dept.s	Total surplus value

Rate Metrics 

Property	Formula	Description
`profit_rate`	s / (c + v)	Economy-wide return on capital (r)
`exploitation_rate`	s / v	Rate of surplus value extraction (e)
`organic_composition`	c / v	Capital intensity (OCC)

Imperial Rent 

\[\Phi = v - (c + v + s)\]

Positive Φ: core territory receives imperial rent (labor aristocracy). Negative Φ: periphery territory donates value.

Fortunati Visibility Metrics 

The visibility scalar g₃₃ controls what fraction of Department III (reproductive labor) the price system recognizes:

Property	Formula	Description
`monetized_value`	Σ(I,IIa,IIb) + III × g₃₃	Value visible to price system
`monetized_v`	Σ(I,IIa,IIb).v + III.v × g₃₃	Wages actually paid
`shadow_subsidy`	III.v × (1 − g₃₃)	Unpaid reproductive labor
`exploitation_rate_fortunati`	(s + shadow) / monetized_v	True exploitation including care work

When g₃₃ = 1.0, all care work is monetized (no shadow subsidy). When g₃₃ = 0.0, all care work is invisible (maximum shadow extraction).

Tensor Registry 

babylon.economics.tensor_registry.TensorRegistry is the cache and aggregation layer that provides tensor access to the simulation engine.

Access Methods 

Method	Description
`get(fips, year)`	County tensor (cache hit, no DB). Returns NoDataSentinel if missing.
`get_aggregate(level, code, year)`	Aggregated tensor (lazy compute, LRU cached)
`put(fips, year, tensor)`	Store tensor, invalidate aggregate cache
`put_sentinel(fips, year, reason)`	Mark (fips, year) as explicitly missing
`hydrate_counties(hydrator, fips_codes, years)`	Bulk load via external hydrator
`all_fips()`	frozenset of cached FIPS codes
`available_years(fips)`	frozenset of years for a county

Geographic Aggregation 

GeoLevel Enum
Level	Code Format	Description
COUNTY	5-digit FIPS	Individual county (direct cache lookup)
STATE	2-digit FIPS	Sum all counties with matching state prefix
NATION	`"US"`	Sum all available counties

Aggregation sums department values. naics_granularity and visibility_g33 are weighted averages by total_value.

Performance 

Operation	Target	Note
`get()` cache hit	< 1ms p95	Direct dict lookup
`get_aggregate()` warm	< 1ms p95	LRU cache hit
`get_aggregate()` cold	< 100ms p95	Computed, then cached
Peak RSS (full US)	< 500MB	LRU eviction at threshold

Thread-safe via RLock on both county and aggregate caches.

Hydration Pipeline 

babylon.economics.hydrator.MarxianHydrator transforms raw QCEW wage data into ValueTensor4x3 using BEA ratios and department mappings.

Pipeline Steps 

Fetch QCEW records: [(naics_code, total_wages, employment)] via QCEWDataSource.fetch_county_wages(fips, year)
Get SNLT factor: Year-specific conversion factor (default 1.0 = wage-proportional proxy)
Allocate to departments: DepartmentMapper.allocate_batch() distributes wages across I/IIa/IIb/III by NAICS-to-department weights. Excluded sectors (NAICS 92 = government) tracked as excluded_wages.
Apply BEA ratios per department:

\[s = v \times \frac{s}{v}_{\text{ratio}} \qquad c = v \times \frac{c}{v}_{\text{ratio}}\]
Convert to labor-hours: Multiply by SNLT factor
Compute naics_granularity: (6-digit wages) / (allocated wages)
Return frozen ValueTensor4x3

Ratio Lookup Hierarchy 

For both s/v and c/v ratios, the system tries three sources (most specific first):

BEA source — empirical industry-level data from fact_bea_national_industry with temporal interpolation (nearest year within ±5 years)
Sector YAML — 2-digit NAICS ratios from naics_to_dept.yaml
Department default — fallback per department (e.g., Dept I default c/v = 2.0, s/v = 1.5)

SNLT Configuration 

babylon.economics.snlt.SNLTConfig provides year-specific labor-hour conversion factors.

Factor	Meaning
1.0	Wage-proportional proxy (derived ratios exact, magnitudes uncalibrated)
< 1.0	Higher productivity (fewer labor-hours per dollar)
> 1.0	Lower productivity (more labor-hours per dollar)

Until SNLT calibration is complete, the default factor of 1.0 means tensor values are wage-proportional labor-time proxies. All derived ratios (r, e, OCC) are exact; absolute magnitudes require SNLT calibration.

Department Mapping 

babylon.economics.department_mapper.DepartmentMapper maps NAICS codes to departments with allocation weights.

NAICS lookup hierarchy (most specific first):

6-digit override (e.g., 325110 → specific chemical)
5, 4, 3-digit overrides
2-digit sector default (e.g., 44 → Retail)
Excluded set (NAICS 92 = government, outside M-C-M’)

Allocation weights sum to 1.0 per NAICS code. Example:

Agriculture (11): 62% Dept I, 33% Dept IIa, 5% Dept IIb
Wholesale (42): 85% Dept I, 15% Dept IIa
Retail (44): 72% Dept IIa, 28% Dept IIb

Configured via naics_to_dept.yaml.

Data Source Protocols 

Protocol	Method
`QCEWDataSource`	`fetch_county_wages(fips, year)` → `list[(naics, wages, employment)]`
`BEADataSource`	`get_sv_ratio(naics, year)` → `float \| None` `get_cv_ratio(naics, year)` → `float \| None`
`CountyHydrator`	`hydrate(fips, year)` → `ValueTensor4x3`

Implementations:

SQLiteQCEWSource: Queries fact_qcew_annual via 3NF joins
InterpolatingBEASource: Queries fact_bea_national_industry with linear temporal interpolation (±5 years)