PolicyEngine-UK 2.90.0__tar.gz → 2.90.2__tar.gz

{policyengine_uk-2.90.0 → policyengine_uk-2.90.2}/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [2.90.2] - 2026-08-13
+
+No significant changes.
+
+
+## [2.90.1] - 2026-08-12
+
+No significant changes.
+
+
 ## [2.90.0] - 2026-08-12
 
 ### Added

{policyengine_uk-2.90.0 → policyengine_uk-2.90.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: policyengine-uk
-Version: 2.90.0
+Version: 2.90.2
 Summary: PolicyEngine tax and benefit system for the UK.
 Project-URL: Homepage, https://github.com/PolicyEngine/policyengine-uk
 Project-URL: Repository, https://github.com/PolicyEngine/policyengine-uk
@@ -24,7 +24,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Requires-Python: >=3.9
 Requires-Dist: microdf-python>=1.2.1
-Requires-Dist: policyengine-core>=3.26.0
+Requires-Dist: policyengine-core>=3.30.1
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: tables<3.10.2,>=3.10.0; python_version == '3.10.*'
 Requires-Dist: tables<3.10.2,>=3.9.2; python_version < '3.10'

{policyengine_uk-2.90.0 → policyengine_uk-2.90.2}/policyengine_uk/parameters/gov/hmrc/cgt/additional_rate.yaml

@@ -1,16 +1,17 @@
-description: Capital gains tax rate on additional rate taxpayers. This parameter is under active development and reforms including it should not be cited.
+description: Capital gains tax rate on additional rate taxpayers. The rates changed part-way through 2024-25, so the value for that year is the day-weighted average of the rates in force before and after 30 October 2024.
 values:
   2015-01-01:
     value: 0.2
     reference:
       - title: Finance Act 2016 s. 83
         href: https://www.legislation.gov.uk/ukpga/2016/24/section/83
-  2025-04-06:
+  2024-10-30:
     value: 0.24
     reference:
       - title: Finance Act 2025 s. 7
         href: https://www.legislation.gov.uk/ukpga/2025/8/section/7
 metadata:
+  fiscal_year_blend: true
   unit: /1
   label: Capital Gains Tax additional rate
   reference:

{policyengine_uk-2.90.0 → policyengine_uk-2.90.2}/policyengine_uk/parameters/gov/hmrc/cgt/basic_rate.yaml

@@ -1,16 +1,17 @@
-description: Capital gains tax rate on basic rate taxpayers. This parameter is under active development and reforms including it should not be cited.
+description: Capital gains tax rate on basic rate taxpayers. The rates changed part-way through 2024-25, so the value for that year is the day-weighted average of the rates in force before and after 30 October 2024.
 values:
   2015-01-01:
     value: 0.1
     reference:
       - title: Finance Act 2016 s. 83
         href: https://www.legislation.gov.uk/ukpga/2016/24/section/83
-  2025-04-06:
+  2024-10-30:
     value: 0.18
     reference:
       - title: Finance Act 2025 s. 7
         href: https://www.legislation.gov.uk/ukpga/2025/8/section/7
 metadata:
+  fiscal_year_blend: true
   unit: /1
   label: Capital Gains Tax basic rate
   reference:

{policyengine_uk-2.90.0 → policyengine_uk-2.90.2}/policyengine_uk/parameters/gov/hmrc/cgt/higher_rate.yaml

@@ -1,16 +1,17 @@
-description: Capital gains tax rate on higher rate taxpayers. This parameter is under active development and reforms including it should not be cited.
+description: Capital gains tax rate on higher rate taxpayers. The rates changed part-way through 2024-25, so the value for that year is the day-weighted average of the rates in force before and after 30 October 2024.
 values:
   2015-01-01:
     value: 0.2
     reference:
       - title: Finance Act 2016 s. 83
         href: https://www.legislation.gov.uk/ukpga/2016/24/section/83
-  2025-04-06:
+  2024-10-30:
     value: 0.24
     reference:
       - title: Finance Act 2025 s. 7
         href: https://www.legislation.gov.uk/ukpga/2025/8/section/7
 metadata:
+  fiscal_year_blend: true
   unit: /1
   label: Capital Gains Tax higher rate
   reference:

policyengine_uk-2.90.2/policyengine_uk/parameters/gov/simulation/capital_gains_responses/elasticity.yaml

@@ -0,0 +1,11 @@
+description: Elasticity of capital gains realisations with respect to the capital gains retention rate, the share of a marginal pound of gains kept after tax. Higher values mean a given rate rise reduces realisations by more. Published estimates span roughly 0.5 to 2.
+values:
+  2000-01-01: 0
+metadata:
+  unit: /1
+  label: Capital gains elasticity
+  reference:
+    - title: Agersnap and Zidar (2021), The tax elasticity of capital gains and revenue-maximizing rates
+      href: https://www.aeaweb.org/articles?id=10.1257/aeri.20200535
+    - title: Advani, Lonsdale and Summers (2024), Reforming Capital Gains Tax
+      href: https://centax.org.uk/wp-content/uploads/2024/10/AdvaniLonsdaleSummers2024_CGTReform.pdf

{policyengine_uk-2.90.0 → policyengine_uk-2.90.2}/policyengine_uk/simulation.py

@@ -16,6 +16,8 @@ from policyengine_core.simulations import Simulation as CoreSimulation
 from policyengine_core.tools.hugging_face import download_huggingface_dataset
 from policyengine_core.tracers import FullTracer, SimpleTracer
 
+from policyengine_uk.utils.parameters import uk_fiscal_year_period
+
 # PolicyEngine UK imports
 from policyengine_uk.data.dataset_schema import (
     UKMultiYearDataset,
@@ -236,10 +238,12 @@ class Simulation(CoreSimulation):
                 canonical_parameter
             )
             if isinstance(changes[parameter], dict):
-                # Time-period specific changes
+                # Time-period specific changes. A bare year names the UK
+                # fiscal year, so the override covers 6 April to 5 April and
+                # survives fiscal-year conversion at full strength.
                 for time_period in changes[parameter]:
                     p.update(
-                        period=time_period,
+                        period=uk_fiscal_year_period(time_period),
                         value=changes[parameter][time_period],
                     )
             else:

{policyengine_uk-2.90.0 → policyengine_uk-2.90.2}/policyengine_uk/tests/policy/baseline/gov/hmrc/capital_gains_tax/capital_gains_tax.yaml

@@ -1,5 +1,10 @@
+# Rate mechanics are tested in 2025-26, where one set of rates applies to the
+# whole year. The rates rose part-way through 2024-25, so that year carries a
+# day-weighted average of the rates before and after 30 October 2024, tested
+# separately at the end of this file.
+
 - name: No capital gains
-  period: 2024
+  period: 2025
   input:
     adjusted_net_income: 0
     capital_gains: 0
@@ -7,7 +12,7 @@
     capital_gains_tax: 0
 
 - name: Capital gains below annual exempt amount
-  period: 2024
+  period: 2025
   input:
     adjusted_net_income: 0
     capital_gains: 2_000
@@ -15,63 +20,66 @@
     capital_gains_tax: 0
 
 - name: Capital gains just above annual exempt amount
-  period: 2024
+  period: 2025
   input:
     adjusted_net_income: 0
     capital_gains: 3_500
   output:
-    capital_gains_tax: 50
+    capital_gains_tax: 90
 
 - name: Basic rate capital gains tax
-  period: 2024
+  period: 2025
   input:
     adjusted_net_income: 20_000
     capital_gains: 23_000
   output:
-    capital_gains_tax: 2_000
+    capital_gains_tax: 3_600
 
 - name: Higher rate capital gains tax
-  period: 2024
+  period: 2025
+  absolute_error_margin: 0.01
   input:
     adjusted_net_income: 50_000
     capital_gains: 50_000
   output:
-    capital_gains_tax: 9_373
+    capital_gains_tax: 11_263.80
 
 - name: Additional rate capital gains tax
-  period: 2024
+  period: 2025
   input:
     adjusted_net_income: 150_000
     capital_gains: 100_000
   output:
-    capital_gains_tax: 19_400
+    capital_gains_tax: 23_280
 
 - name: Mixed rates capital gains tax
-  period: 2024
+  period: 2025
+  absolute_error_margin: 0.01
   input:
     adjusted_net_income: 35_000
     capital_gains: 40_000
   output:
-    capital_gains_tax: 5_873
+    capital_gains_tax: 7_963.80
 
 - name: High capital gains, low income
-  period: 2024
+  period: 2025
   input:
     adjusted_net_income: 10_000
     capital_gains: 200_000
   output:
-    capital_gains_tax: 35_630
+    capital_gains_tax: 45_018
 
 - name: Very high capital gains and income
-  period: 2024
+  period: 2025
+  absolute_error_margin: 0.1
   input:
     adjusted_net_income: 500_000
     capital_gains: 1_000_000
   output:
-    capital_gains_tax: 199_400
+    capital_gains_tax: 239_280
 
 - name: Edge case, capital gains exactly equal to annual exempt amount
-  period: 2024
+  period: 2025
   input:
     adjusted_net_income: 0
     capital_gains: 3_000
@@ -132,3 +140,26 @@
     capital_gains: 32_942.86
   output:
     capital_gains_tax: 5_389.71
+
+# Finance Act 2025 s.7 raised the main rates for disposals from 30 October
+# 2024, part-way through 2024-25. An annual model cannot place a disposal
+# before or after that date, so the year takes the day-weighted average of the
+# two schedules: 207 days at 10% and 20%, then 158 days at 18% and 24%.
+
+- name: Case 16, the split 2024-25 year taxes basic rate gains at the blended rate.
+  period: 2024
+  absolute_error_margin: 0.01
+  input:
+    adjusted_net_income: 20_000
+    capital_gains: 23_000
+  output:
+    capital_gains_tax: 2_692.60
+
+- name: Case 17, the split 2024-25 year taxes higher rate gains at the blended rate.
+  period: 2024
+  absolute_error_margin: 0.01
+  input:
+    adjusted_net_income: 150_000
+    capital_gains: 100_000
+  output:
+    capital_gains_tax: 21_079.56

policyengine_uk-2.90.2/policyengine_uk/tests/test_capital_gains_responses.py

@@ -0,0 +1,164 @@
+"""Tests for the capital gains realisation response to CGT rate changes."""
+
+import pytest
+
+from policyengine_uk import Microsimulation
+from policyengine_uk.model_api import Scenario
+
+YEAR = 2026
+
+SITUATION = {
+    "people": {
+        "person": {
+            "age": {YEAR: 45},
+            "employment_income": {YEAR: 100_000},
+            "capital_gains": {YEAR: 200_000},
+        }
+    },
+    "benunits": {"benunit": {"members": ["person"]}},
+    "households": {"household": {"members": ["person"]}},
+}
+
+EQUALISED_RATES = {
+    "gov.hmrc.cgt.basic_rate": {str(YEAR): 0.20},
+    "gov.hmrc.cgt.higher_rate": {str(YEAR): 0.40},
+    "gov.hmrc.cgt.additional_rate": {str(YEAR): 0.45},
+}
+
+
+def simulate(elasticity: float | None = None, rates: bool = True) -> Microsimulation:
+    changes = dict(EQUALISED_RATES) if rates else {}
+    if elasticity is not None:
+        changes["gov.simulation.capital_gains_responses.elasticity"] = {
+            str(YEAR): elasticity
+        }
+    if not changes:
+        return Microsimulation(situation=SITUATION)
+    return Microsimulation(
+        situation=SITUATION, scenario=Scenario(parameter_changes=changes)
+    )
+
+
+def test_rate_rise_registers_against_the_baseline():
+    """A CGT rate rise registers as a higher rate and a lower retention rate.
+
+    Regression test for measuring the baseline against a branch of the reform
+    simulation, which reported no rate change for any reform (issue #1319).
+    """
+    sim = simulate(elasticity=1.0)
+    mtr_change = sim.calculate("relative_capital_gains_mtr_change", YEAR).values[0]
+    retention_change = sim.calculate(
+        "relative_capital_gains_retention_rate_change", YEAR
+    ).values[0]
+
+    assert mtr_change > 0, f"expected a positive log rate change, got {mtr_change}"
+    assert retention_change < 0, (
+        f"expected a negative log retention change, got {retention_change}"
+    )
+
+
+def test_realisations_fall_when_rates_rise():
+    """Gains fall under a rate rise, by more at a larger elasticity."""
+    baseline_gains = simulate(rates=False).calculate("capital_gains", YEAR).sum()
+
+    modest = simulate(elasticity=0.5).calculate("capital_gains", YEAR).sum()
+    large = simulate(elasticity=1.0).calculate("capital_gains", YEAR).sum()
+
+    assert modest < baseline_gains
+    assert large < modest
+
+
+def test_revenue_falls_short_of_the_static_estimate():
+    """The behavioural response costs revenue relative to a static costing."""
+    static = simulate(elasticity=0).calculate("capital_gains_tax", YEAR).sum()
+    dynamic = simulate(elasticity=1.0).calculate("capital_gains_tax", YEAR).sum()
+
+    assert dynamic < static
+    assert dynamic > 0
+
+
+def test_zero_elasticity_leaves_gains_unchanged():
+    """The default elasticity of zero keeps costings static."""
+    sim = simulate(elasticity=0)
+    response = sim.calculate("capital_gains_behavioural_response", YEAR).sum()
+
+    assert response == 0
+
+
+def test_no_reform_produces_no_response():
+    """A simulation with no reform reports no realisation response."""
+    sim = Microsimulation(
+        situation=SITUATION,
+        scenario=Scenario(
+            parameter_changes={
+                "gov.simulation.capital_gains_responses.elasticity": {str(YEAR): 1.0}
+            }
+        ),
+    )
+    response = sim.calculate("capital_gains_behavioural_response", YEAR).sum()
+
+    assert response == 0
+
+
+def test_measurement_leaves_the_response_variable_active():
+    """Measuring the rate change does not neutralise the response itself.
+
+    Object identity, not formula presence: a neutralised wrapper still
+    carries a formula, so the old assertion could not see the damage.
+    """
+    sim = simulate(elasticity=1.0)
+    before = sim.tax_benefit_system.variables["capital_gains_behavioural_response"]
+    sim.calculate("relative_capital_gains_mtr_change", YEAR)
+    after = sim.tax_benefit_system.variables["capital_gains_behavioural_response"]
+
+    assert after is before
+
+
+def test_pre_created_measurement_branch_cannot_poison_the_system():
+    """A branch pre-created under the measurement's name shares the parent
+    system, and get_branch returns it without honouring clone_system — so
+    neutralising there would disable the response for every later
+    recalculation. The measurement must sidestep the name instead."""
+    sim = simulate(elasticity=1.0)
+    sim.get_branch("cgr_measurement")
+    before = sim.tax_benefit_system.variables["capital_gains_behavioural_response"]
+
+    response = sim.calculate("capital_gains_behavioural_response", YEAR).sum()
+    after = sim.tax_benefit_system.variables["capital_gains_behavioural_response"]
+
+    assert response < 0
+    assert after is before
+
+
+def test_two_gainers_in_one_household_respond_symmetrically():
+    """Equal gainers get equal responses; the second adult is not dropped."""
+    situation = {
+        "people": {
+            "first": {
+                "age": {YEAR: 45},
+                "employment_income": {YEAR: 100_000},
+                "capital_gains": {YEAR: 200_000},
+            },
+            "second": {
+                "age": {YEAR: 44},
+                "employment_income": {YEAR: 100_000},
+                "capital_gains": {YEAR: 200_000},
+            },
+        },
+        "benunits": {"benunit": {"members": ["first", "second"]}},
+        "households": {"household": {"members": ["first", "second"]}},
+    }
+    sim = Microsimulation(
+        situation=situation,
+        scenario=Scenario(
+            parameter_changes={
+                **EQUALISED_RATES,
+                "gov.simulation.capital_gains_responses.elasticity": {str(YEAR): 1.0},
+            }
+        ),
+    )
+
+    responses = sim.calculate("capital_gains_behavioural_response", YEAR).values
+
+    assert responses[0] < 0
+    assert responses[0] == pytest.approx(responses[1])

{policyengine_uk-2.90.0 → policyengine_uk-2.90.2}/policyengine_uk/tests/test_fiscal_year_parameters.py

@@ -102,6 +102,121 @@ class TestFiscalYearBoundary:
         assert child_limit == 2
 
 
+class TestMidYearRateChanges:
+    """Tests for changes taking effect part-way through a fiscal year.
+
+    Sampling one date per year drops any change taking effect after it.
+    Parameters carrying `fiscal_year_blend: true` are day-weighted across
+    the year instead.
+    """
+
+    # Fiscal year 2024-25 runs 6 April 2024 to 5 April 2025: 207 days at the
+    # rates in force before 30 October 2024, then 158 days at the rates after.
+    DAYS_BEFORE = 207
+    DAYS_AFTER = 158
+    TOTAL_DAYS = DAYS_BEFORE + DAYS_AFTER
+
+    def blended(self, before, after):
+        return (before * self.DAYS_BEFORE + after * self.DAYS_AFTER) / self.TOTAL_DAYS
+
+    @pytest.mark.parametrize(
+        "rate_name, before, after",
+        [("basic_rate", 0.10, 0.18), ("higher_rate", 0.20, 0.24)],
+    )
+    def test_cgt_rates_blend_across_the_split_year(self, rate_name, before, after):
+        """2024-25 carries both statutory rates, so the year takes their average."""
+        system = CountryTaxBenefitSystem()
+        rates = {
+            year: getattr(
+                system.get_parameters_at_instant(str(year)).gov.hmrc.cgt, rate_name
+            )
+            for year in (2023, 2024, 2025)
+        }
+
+        assert rates[2023] == pytest.approx(before)
+        assert rates[2024] == pytest.approx(self.blended(before, after))
+        assert rates[2025] == pytest.approx(after)
+
+    def test_cgt_rate_rise_takes_effect_from_the_statutory_date(self):
+        """Finance Act 2025 s.7 applies to disposals from 30 October 2024.
+
+        Read before fiscal year conversion, which is what the statutory dates
+        feed. Regression test for dating the rise to 6 April 2025, which moved
+        a change the legislation makes in 2024-25 into the following year.
+        """
+        import policyengine_uk
+        from pathlib import Path
+        from policyengine_core.parameters import ParameterNode
+
+        parameters = ParameterNode(
+            directory_path=str(Path(policyengine_uk.__file__).parent / "parameters")
+        )
+        higher_rate = parameters.gov.hmrc.cgt.higher_rate
+
+        assert higher_rate("2024-10-29") == pytest.approx(0.20)
+        assert higher_rate("2024-10-30") == pytest.approx(0.24)
+
+    def test_blending_is_opt_in(self, uk_system):
+        """Parameters without the flag keep one sampled value for the year.
+
+        National Insurance rates fell part-way through 2022-23, and the year
+        still takes the rate in force at its start rather than an average.
+        Whether to blend is a decision per parameter: a transaction is taxed
+        at the rate in force on its date, not at a yearly average.
+        """
+        parameters = uk_system.get_parameters_at_instant("2022")
+        employee_rates = parameters.gov.hmrc.national_insurance.class_1.rates.employee
+
+        assert employee_rates.main == pytest.approx(0.1325)
+
+
+class TestScenarioOverrides:
+    """Annual Scenario overrides name UK fiscal years.
+
+    Written as calendar years, an override's final five months fell back to
+    prior law and fiscal-year conversion blended the two: an override of 0.5
+    on a blended CGT rate resolved to 0.42. The override now covers 6 April
+    to 5 April.
+    """
+
+    def _reformed(self):
+        from policyengine_uk import Microsimulation
+        from policyengine_uk.model_api import Scenario
+
+        return Microsimulation(
+            situation={
+                "people": {
+                    "person": {
+                        "age": {2025: 45},
+                        "adjusted_net_income": {2025: 20_000},
+                        "capital_gains": {2025: 23_000},
+                    }
+                },
+                "benunits": {"benunit": {"members": ["person"]}},
+                "households": {"household": {"members": ["person"]}},
+            },
+            scenario=Scenario(
+                parameter_changes={"gov.hmrc.cgt.basic_rate": {"2025": 0.5}}
+            ),
+        )
+
+    def test_override_applies_at_full_strength(self):
+        sim = self._reformed()
+        rate = sim.tax_benefit_system.parameters.gov.hmrc.cgt.basic_rate
+
+        assert rate("2025") == pytest.approx(0.5)
+        cgt = sim.calculate("capital_gains_tax", 2025).values[0]
+        assert cgt == pytest.approx(10_000.0)
+
+    def test_override_leaves_other_years_on_law(self):
+        """The split 2024-25 blend and the 2026 reversion both survive."""
+        sim = self._reformed()
+        rate = sim.tax_benefit_system.parameters.gov.hmrc.cgt.basic_rate
+
+        assert rate("2024") == pytest.approx((0.10 * 207 + 0.18 * 158) / 365)
+        assert rate("2026") == pytest.approx(0.18)
+
+
 class TestFiscalYearCoverage:
     """Tests to verify fiscal year conversion covers all needed years."""
 

policyengine_uk-2.90.2/policyengine_uk/utils/capital_gains.py

@@ -0,0 +1,61 @@
+"""Measurement of capital gains marginal tax rates against the baseline."""
+
+import numpy as np
+
+from policyengine_core.simulations import Simulation
+
+
+def measure_mtr(
+    simulation: Simulation,
+    branch_name: str,
+    period,
+    gains: np.ndarray,
+) -> np.ndarray:
+    """Measure the capital gains MTR in a simulation, holding gains fixed.
+
+    The branch clones the tax-benefit system because it neutralises the
+    behavioural response variable, which would otherwise recurse back into
+    this measurement. Cloning keeps that neutralisation off the simulation
+    being measured.
+    """
+    # get_branch returns an existing branch of the requested name without
+    # honouring clone_system, and neutralising on a shared system would
+    # permanently disable the response variable for the caller. Take a name
+    # nothing else holds, then require the clone before touching it.
+    while branch_name in simulation.branches:
+        branch_name += "_"
+    branch = simulation.get_branch(branch_name, clone_system=True)
+    if branch.tax_benefit_system is simulation.tax_benefit_system:
+        raise RuntimeError(
+            "Capital gains MTR measurement requires a cloned tax-benefit "
+            "system; refusing to neutralise on the simulation's own."
+        )
+    branch.tax_benefit_system.neutralize_variable("capital_gains_behavioural_response")
+    branch.set_input("capital_gains_before_response", period, gains)
+    mtr = branch.populations["person"]("marginal_tax_rate_on_capital_gains", period)
+    del simulation.branches[branch_name]
+    return mtr
+
+
+def measure_capital_gains_mtrs(person, period) -> tuple[np.ndarray, np.ndarray]:
+    """Return the reform and baseline capital gains MTRs for each person.
+
+    Both rates are measured at the same level of gains, so the difference
+    reflects the reform alone. Returns two zero arrays where the simulation
+    has no baseline to compare against.
+
+    Simulations hold their baseline as a separately constructed simulation
+    rather than a branch, so the baseline rate has to be measured there. A
+    branch of the reform simulation carries reform parameters, and reports no
+    rate change however large the reform.
+    """
+    simulation: Simulation = person.simulation
+    baseline = simulation.baseline
+    if baseline is None:
+        zeros = np.zeros(person.count)
+        return zeros, zeros
+
+    gains = person("capital_gains_before_response", period)
+    reform_mtr = measure_mtr(simulation, "cgr_measurement", period, gains)
+    baseline_mtr = measure_mtr(baseline, "baseline_cgr_measurement", period, gains)
+    return reform_mtr, baseline_mtr