Add hours usage variable to extended childcare program (#1118)

* add hours usage variable

* add hours usage variable

* edit extended calculation py file

* format black

* edit max hour variable

* format

* format

* edit setup

* add tests

Author: vahid-ahmadi

changelog_entry.yaml

@@ -0,0 +1,5 @@
+- bump: patch
+  changes:
+    added:
+      - Added variable to represent partial usage of extended childcare entitlement hours
+      - Updated extended childcare entitlement calculation to account for partial hours usage

policyengine_uk/tests/policy/baseline/gov/dfe/extended_childcare_entitlement/extended_childcare_entitlement.yaml

@@ -118,11 +118,11 @@
         members: [child1]
         extended_childcare_entitlement_eligible: true
   output:
-    extended_childcare_entitlement: 4611.457  # 20 hours * 38 weeks * £6.07 per hour (2025 rate)
+    extended_childcare_entitlement: 4_611.457  # 20 hours * 38 weeks * £6.07 per hour (2025 rate)
 
 - name: Child using fewer hours than maximum entitlement - multiple children
   period: 2025
-  absolute_error_margin: 100
+  absolute_error_margin: 1
   input:
     people:
       child1:
@@ -136,4 +136,57 @@
         members: [child1, child2]
         extended_childcare_entitlement_eligible: true
   output:
-    extended_childcare_entitlement: 6705.43  # (10 hours * 38 weeks * £8.58 per hour) + (15 hours * 38 weeks * £6.07 per hour) for 2025 rates
+    extended_childcare_entitlement: 6_705.434  # Updated to match actual calculation
+
+- name: Benefit unit maximum hours cap applied
+  period: 2025
+  absolute_error_margin: 1
+  input:
+    people:
+      child1:
+        age: 3
+        max_free_entitlement_hours_used: 30
+      child2:
+        age: 3
+        max_free_entitlement_hours_used: 30
+    benunits:
+      benunit1:
+        members: [child1, child2]
+        extended_childcare_entitlement_eligible: true
+        maximum_extended_childcare_hours_usage: 40 
+  output:
+    extended_childcare_entitlement: 13_834.37  
+
+
+- name: Benefit unit without maximum hours cap applied
+  period: 2025
+  absolute_error_margin: 1
+  input:
+    people:
+      child1:
+        age: 3
+        max_free_entitlement_hours_used: 30
+    benunits:
+      benunit1:
+        members: [child1]
+        extended_childcare_entitlement_eligible: true
+        maximum_extended_childcare_hours_usage: 10 
+  output:
+    extended_childcare_entitlement: 2_306.6
+
+
+- name: Benefit unit without maximum hours cap applied with 3 years old child
+  period: 2025
+  absolute_error_margin: 1
+  input:
+    people:
+      child1:
+        age: 3
+        max_free_entitlement_hours_used: 15
+    benunits:
+      benunit1:
+        members: [child1]
+        extended_childcare_entitlement_eligible: true
+        maximum_extended_childcare_hours_usage: 18 
+  output:
+    extended_childcare_entitlement: 3_459.5

policyengine_uk/variables/gov/dfe/extended_childcare_entitlement/extended_childcare_entitlement.py

@@ -27,6 +27,16 @@ def formula(benunit, period, parameters):
         # Use the appropriate hours based on the condition
         weekly_hours_to_use = min_(max_hours_used, weekly_hours_per_child)
 
+        # Get the maximum hours usage for this benefit unit
+        maximum_hours_usage = benunit(
+            "maximum_extended_childcare_hours_usage", period
+        )
+
+        # Apply the maximum hours limit
+        weekly_hours_to_use = min_(
+            weekly_hours_to_use, benunit.project(maximum_hours_usage)
+        )
+
         # Compute weekly subsidy per child
         weekly_subsidy_per_child = (
             weekly_hours_to_use * p.childcare_funding_rate.calc(age)

policyengine_uk/variables/gov/dfe/extended_childcare_entitlement/maximum_extended_childcare_hours_usage.py

@@ -0,0 +1,10 @@
+from policyengine_uk.model_api import *
+
+
+class maximum_extended_childcare_hours_usage(Variable):
+    value_type = float
+    entity = BenUnit
+    label = "maximum extended childcare hours used"
+    documentation = "The maximum number of weekly extended childcare hours that this family uses"
+    definition_period = YEAR
+    default_value = 30  # By default, uses up to 30 hours per week

setup.py

@@ -43,6 +43,7 @@
             "sphinx-math-dollar>=1.2.1,<2",
             "wheel",
             "yaml-changelog>=0.1.7",
+            "snowballstemmer>=2,<3",
         ]
     },
     # Windows CI requires Python 3.9.