Document IPF's two-entity-level constraint as a hard limit

Replaces the deferred-future framing ("`tax_unit_count` and `spm_unit_count`
remain outside the core household/person IPF path *in this pass*") with the
methodological reason: `surveysd::ipf` supports exactly two entity levels
natively (`conP` for row-level / person-style constraints, `conH` for
constraints aggregated by `hid`), and there is no generalised mechanism
for additional counted entities such as `tax_unit` or `spm_unit`.

Producing a single weight vector that simultaneously satisfies targets at
three or more entity levels is not possible with classical IPF. Running
IPF separately per scope and aggregating would give it more degrees of
freedom than L0 / GREG (each pass solves a smaller subproblem with its
own freedom) and would not be a like-for-like comparison. The benchmark
therefore restricts IPF to `person_count` and `household_count` —
together or alone — and drops other count families at the count check.
Those targets remain in the shared sparse system that L0 and GREG fit,
so the cross-method comparison on the IPF-feasible subset stays
apples-to-apples via `--score-on ipf_retained_authored`.

Updated the README's methodology section and the IPF inputs subsection
to articulate the constraint, and tightened the `_target_scope` error
message in `ipf_conversion.py` to match.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: juaristi22

paper-l0/benchmarking/README.md

@@ -34,9 +34,23 @@ Methodologically, the benchmark treats the methods as related but not
 identical:
 
 - `L0` and `GREG` can consume arbitrary linear calibration targets.
-- `IPF` is most natural for count-style or indicator-style targets, so the
-  current automatic conversion path supports `person_count` and
-  `household_count`.
+- `IPF` is most natural for count-style or indicator-style targets, and is
+  additionally limited to **at most two entity levels per run**. `surveysd::ipf`
+  has built-in handles only for the person/household pair via `conP` (row-level
+  constraints) and `conH` (constraints aggregated by `hid`); there is no
+  generalised mechanism for additional counted entities such as `tax_unit` or
+  `spm_unit`. The benchmark therefore restricts IPF to `person_count` and
+  `household_count` targets — together or alone — and drops other count
+  families (`tax_unit_count`, `spm_unit_count`, `family_count`,
+  `marital_unit_count`) at the count check with explicit diagnostics. Those
+  targets remain in the shared sparse system that L0 and GREG fit, so the
+  cross-method comparison on the IPF-feasible subset is still apples-to-apples
+  via `--score-on ipf_retained_authored`.
+
+  Producing a single weight vector that simultaneously satisfies targets at
+  three or more entity levels is not possible with classical IPF; running IPF
+  separately per scope and aggregating would give it more degrees of freedom
+  than L0 / GREG and would not be a like-for-like comparison.
 
 The core workflow is:
 
@@ -122,11 +136,15 @@ external overrides are supplied. It reconstructs an IPF microdata table from:
 - the selected count-like targets and their stratum constraints
 
 The generated `unit_metadata.csv` is built for `person_count` and
-`household_count` targets. It expands cloned households to a person-level table
-when person targets are present, carries a repeated household `unit_index` so
-per-person weights collapse cleanly back to per-household, and adds one
-string-valued derived category column per declared bucket schema (e.g.
-`age_bracket`, `agi_bracket_district`, `snap_positive`).
+`household_count` targets only — the two entity levels `surveysd::ipf` supports
+natively via `conP` and `conH`. It expands cloned households to a person-level
+table when person targets are present, carries a repeated household
+`unit_index` so per-person weights collapse cleanly back to per-household, and
+adds one string-valued derived category column per declared bucket schema
+(e.g. `age_bracket`, `agi_bracket_district`, `snap_positive`). Targets at
+other entity levels (e.g. `tax_unit_count`, `spm_unit_count`) are dropped at
+the count check with `non_count_style` diagnostics; they remain in the shared
+sparse target matrix that L0 and GREG fit.
 
 The generated `ipf_target_metadata.csv` contains one `categorical_margin` row
 per retained IPF cell after validation. That means:

paper-l0/benchmarking/ipf_conversion.py

@@ -353,10 +353,13 @@ def _target_scope(target_variable: str) -> str:
     except KeyError as exc:
         raise ValueError(
             f"IPF conversion does not support target variable "
-            f"'{target_variable}'. Currently supported: "
-            f"{sorted(_SCOPE_BY_VARIABLE)}. "
-            "`tax_unit_count` and `spm_unit_count` remain outside the core "
-            "household/person IPF path in this pass."
+            f"'{target_variable}'. Supported: "
+            f"{sorted(_SCOPE_BY_VARIABLE)}. Classical IPF in this benchmark "
+            "is limited to person and household scopes — the two entity "
+            "levels surveysd::ipf supports natively via `conP` and `conH`. "
+            "Other count families (e.g. `tax_unit_count`, `spm_unit_count`) "
+            "are dropped from the IPF run with explicit diagnostics; they "
+            "remain in the shared sparse system that L0 and GREG fit."
         ) from exc