Repository navigation
Add firm entity and firm-side tax rules - #2940
Draft
vahid-ahmadi wants to merge 9 commits into
Draft
vahid-ahmadi wants to merge 9 commits into
vahid-ahmadi wants to merge 9 commits into
Conversation
Adds a Firm entity beside person, benunit and household as a root population (no person membership), with firm-level rules for employer NICs and the Employment Allowance, the apprenticeship levy, corporation tax with capital allowances, R&D relief and the bank surcharge, England business rates, firm-side VAT and auto-enrolment. Incidence variables are added but not wired into gov_tax or household_tax. Refs #2939 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…yment Allowance out of firm-only tax Employer NI rate reforms raised the Employment Allowance of firms under the cap, which leaked into firm_tax_change_total and double counted with ni_employer. firm_only_tax now leaves the allowance out, and firm_tax_change_total adds only the change from the allowance's own rules at baseline liabilities. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
Aggregate impact on certified data: FAILThe report did not run, so this change has no report. See the workflow run. |
…redits from firm aggregates - Core Simulation.clone (used by the YAML runner and by formulas that clone, such as marginal tax rates) now keeps root populations; this fixes KeyError: 'firm' in 26 YAML tests. - Later-year firm tables must hold the same firms as the first year; tables without firm_id are numbered; filter_dataset keeps the firm table; validate rejects non-firm columns in the firm table. - firm_tax and firm_only_tax subtract R&D credits paid out (excess RDEC and the ERIS payable credit). - Sentence-case labels on corporation tax variables. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Core marks firm as a person-like entity, so the app would otherwise offer the 52 firm inputs as person variables in the household builder. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolves the remaining UNVERIFIED notes, backfills auto-enrolment thresholds for 2012-2018, adds missing references, and records the Finance Bill 2026-27 stage for announced-not-enacted values. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d gate, single firm clone - firm_tax_change_total holds last year's employer NI liabilities at baseline too, so a rate reform cannot flip eligibility under the 2020-21 to 2024-25 prior-year limit; mismatched baseline firm tables raise. - Replace the frozen regression fixture with structural checks (no firm variable in gov_tax or the budget totals) and live checks that firms and firm-only reforms leave household results unchanged. - The UK Simulation.clone reuses the root population the patched core clone already made. - Corporation tax verified_start_year 2026; docs wording. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
vahid-ahmadi
added a commit
to PolicyEngine/microcosm
that referenced
this pull request
Nov 22, 2026
…ates Draw region (ONS UK Business 2025 Table 8) and legal status (Table 13) per firm after calibration, with Table 15 held out, and export them as policyengine-uk's firm_region, firm_in_england, firm_legal_form and firm_is_public_body. Record the status of all 52 policyengine-uk firm inputs, check the export against an ast snapshot of policyengine-uk's firm variables, and declare value-free M2 target candidates. The 8-target uk_firms_targets.json contract is unchanged. Refs #1705, PolicyEngine/policyengine-uk#2940. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…; pay-distribution inputs; source checks - Toy-frame microsimulation test (200 firms) checking each programme against an independent calculation, and a contract test for the columns microcosm reads and writes. - Worked firm reform examples page, every figure asserted in a test. - Optional inputs for staff below the secondary threshold and outside the auto-enrolment band, identical results when absent. - Remaining parameter values confirmed against sources; SBRR boundary cases; firm_in_freeport documented as not yet read. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Clip the optional pay-distribution inputs to the firm's headcount and paybill, and document it. - A baseline without the same firm table raises in firm_tax_change_total. - Parity test between the Employment Allowance rule-change helper and employment_allowance; keep-in-step notes on both sides. - Docs describe the optional inputs and the earnings trigger; wording 'at or below' the threshold and trigger. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
vahid-ahmadi
added a commit
to PolicyEngine/microcosm
that referenced
this pull request
Nov 22, 2026
tools/build_uk_firms.py runs generation, attribute draws and the policyengine-uk table export to uk_firms.parquet with a JSON receipt (no publish path, required --rules). PolicyEngineUKFirmRules runs policyengine-uk's firm entity on the candidate table and reads firm_vat_liability_if_registered; it imports policyengine-uk lazily and is tested engine-free with a fake simulation, and was checked locally against PolicyEngine/policyengine-uk#2940. Refs #1705. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #2939
What and why
Adds a firm entity to policyengine-uk beside person, benefit unit and household, and firm-level rules for the main business taxes. Today the model only spreads national totals of firm taxes over households (business rates, corporate SDLT,
corporate_incident_tax_change). Corporation tax and the apprenticeship levy are listed underuncovered_receipts, and the Employment Allowance is not modelled.Part of #1320 (firm-level VAT and a Firm entity): this PR adds the entity and firm-side VAT, but not the sector-driven supply split or a calibrated firm dataset, so #1320 stays open.
The PR is a draft and still in progress. The design notes and the decisions behind them are below. The firm dataset itself is being built in microcosm (PolicyEngine/microcosm#1706).
Entity design
firm_weight), which come from business data rather than FRS households. No person is a member of a firm.Firmis built. It is a plain coreEntitylisted afterPerson([Person, BenUnit, Household, Firm]), so core treats it as neither the person entity nor a group entity.TaxBenefitSystem.instantiate_entities(intax_benefit_system.py) gives it aRootPopulation. This also covers coreReformsystems built by the YAML runner.RootPopulationraises on cross-entity shortcuts such asfirm.household._bind_to_tax_benefit_system(reforms and baselines),cloneandget_branch.map_resultraises when asked to map firm values to or from another entity.build_from_situationaccepts an optionalfirms: {name: {variable: value}}block.build_from_idstakes an optionalfirm_id.UKSingleYearDatasetandUKMultiYearDatasettake an optionalfirm=table.tablesstays three long, so uprating and subsampling are unchanged.subsampleraisesNotImplementedErrorwhen firms are present.Programs
All new variables use
entity = Firm. Every parameter has a legislation or GOV.UK reference. Values that have been announced but not yet enacted are marked in their YAML files.firm_employer_ni,firm_employer_ni_before_allowancegov.hmrc.national_insurance.class_1rate and threshold nodes. Earnings above the secondary threshold can be given as an input; by default they are approximated from paybill and employees.employment_allowance,employment_allowance_eligibleapprenticeship_levyfirm_auto_enrolment_employer_contributioncorporation_tax,firm_taxable_profit,firm_marginal_relief,firm_losses_used, …firm_capital_allowances+ componentsfirm_rd_expenditure_credit,firm_rd_additional_deduction,firm_rd_payable_creditbank_surchargefirm_business_rates+ reliefsfirm_vat,firm_vat_registered,firm_output_vat, …Aggregates and incidence (not wired into totals)
firm_tax: total statutory liability, less R&D tax credits paid out to the firm (RDEC in excess of corporation tax, and the ERIS payable credit).firm_only_tax: the liability set by rules only the firm side models: CT, bank surcharge, levy and business rates, less R&D credits paid out. Employer NIC and VAT rates are left out, because they already reach households throughni_employerandvat. The Employment Allowance is left out too, because it moves with employer NIC liability.firm_tax_change_total: the reform less baseline change infirm_only_tax, weighted byfirm_weight, less the change in the Employment Allowance from its own rules (amount and eligibility). Each firm's employer NIC liabilities are held at their baseline values: this year's, and last year's for the 2020-21 to 2024-25 prior-year limit. Without this, an employer NIC rate reform would count twice; tests cover a 2026 rate reform and a 2024 eligibility flip.firm_tax_incidence: splitsfirm_tax_change_totalbetween households by capital, consumption and labour shares. The shares come from newgov.contrib.policyengine.firm_incidenceparameters, which default to capital 1.GOV_TAX_VARIABLES,household_tax,programs.yamlbudget lists orfiscal_partition.yaml. That waits for a calibrated firm dataset from microcosm. Household outputs are therefore unchanged by construction. A regression gate checks that adding firms, or a firm-only reform, leaves household results exactly unchanged.Downstream changes needed before release
Core marks
firmasis_person=True, because a plainEntityis the only non-group entity core accepts. Downstream code that readsis_personsees two person entities. Read-only research found these consequences:tests/test_model_entities.py:90asserts that the person entities are exactly["person"], so the UK release certification run would fail. The fix is insrc/policyengine/tax_benefit_models/common/model_version.py:213: deriveis_personby comparing against the system's person entity key, then update the pinned entities.policyengine_api/data/v2/catalog/extraction.py:281raises unless there is exactly one person entity.policyengine_api/country.py:413reportsis_person: truefor firm in v1 metadata.VariableResolver.ts:55would offer firm inputs as person inputs. This PR setshidden_input = Trueon all 58 firm inputs, so they stay out of the household builder until a firm builder exists.Household calculations without firms work unchanged in the API. These downstream PRs are not yet opened: they wait for a maintainer's go-ahead. Patches are prepared locally for policyengine.py (key-based
is_personand entity pins; 76 tests pass on the pinned UK version and on this branch) and policyengine-api (v1 metadata). This PR should not be released until the policyengine.py fix is released.Compatibility with policyengine-core
TaxBenefitSystem.instantiate_entitiesandSimulation.cloneso they keep root populations. Both patches are guarded and idempotent. The clone patch is what lets the YAML runner, and formulas that clone the simulation (such as marginal tax rates), see firms.Known simplifications
firm_zero_rated_class_1_earnings.firm_in_freeportis recorded but no rule reads it yet. Freeport capital allowances and business rates relief are not modelled.firm_idcomes back as int32.Test plan
policyengine_uk/tests/policy/baseline/gov/hmrc/{corporation_tax,bank_surcharge,apprenticeship_levy,vat/firm,business_rates/firm,national_insurance/employer,national_insurance/employment_allowance}and.../gov/dwp/auto_enrolment.test_firm_entity.py,test_firm_incidence.py,test_supplied_inputs.py: 119 passed.test_entity_ids,test_input_dataframe_export,test_dataframe_dataset,test_build_metadata,test_variable_units,test_parameter_metadata,test_subsample,test_household_subset,test_supplied_inputs, and the code_health tests.test_firm_regression_gate.py, 34 passed):GOV_TAX_VARIABLESmember or a budget term.70014b3exactly (35 passed). It was dropped so that later changes to household rules don't break this test.test_firm_incidence.py), thefirms:guard for YAML (test_firm_yaml_guard.py), and 3 integration cases (tests/policy/integration/firm/).test_firm_microsimulation.py): a seeded 200-firm frame checks weighted CT, levy, employer NIC, business rates and VAT against an independent numpy calculation. It also checks thefirm_taxidentity, that every firm variable is finite, and that household totals are unchanged whether or not the dataset has a firm table. The totals are toy numbers, not estimates.test_firm_microcosm_contract.py): checks the 10 firm columns and outputs the microcosm frame (UK firm data: paper-parity port and policyengine-uk rules seam microcosm#1706) reads or writes.docs/book/usage/firm-reforms.md): every figure on it is asserted intest_firm_docs_examples.py.UNVERIFIEDnotes remain.programs.yamlregisters 8 firm programmes aspartial(test_program_registryand the budget tests pass). New docs page:docs/book/usage/firms.md.main, the same shards took 82 to 90 minutes in the last successful run, and a local benchmark shows no slowdown in household simulations from this branch. Rerunning at 1b320d8.make format(ruff format + ruff check).changelog.d/firm-entity-engine.added.md.Reproducer
Reproducer: policyengine_uk/tests/test_firm_entity.py
axiom: needed (new firm-side programmes. The rulespec-uk parity issues are not yet opened and are left for a maintainer's decision.)
🤖 Generated with Claude Code