Add Social Security retirement benefit calculation chain

changelog.d/implement-ss-benefits-v2.added.md

@@ -0,0 +1 @@
+Add Social Security retirement benefit calculation chain with AIME, PIA, early/delayed retirement adjustment, and earnings test formulas.

policyengine_us/parameters/gov/simulation/aime_lookback_years.yaml

@@ -0,0 +1,10 @@
+description: Maximum number of years to look back for AIME calculation
+values:
+  2024-01-01: 45
+metadata:
+  unit: /1
+  period: year
+  label: AIME lookback years
+  reference:
+    - title: Social Security AIME calculation
+      href: https://www.ssa.gov/OACT/COLA/aime.html

policyengine_us/parameters/gov/simulation/reported_social_security_retirement.yaml

@@ -0,0 +1,12 @@
+description: >-
+  When true, Social Security retirement benefits use reported
+  values from survey data rather than computing from the formula
+  chain. Set to true for microsimulation with CPS data, false
+  for the household calculator.
+values:
+  2024-01-01: false
+metadata:
+  unit: bool
+  period: year
+  label: Use reported Social Security retirement benefits
+  economy: false

policyengine_us/parameters/gov/ssa/social_security/aime/indexing_age.yaml

@@ -0,0 +1,14 @@
+description: Age at which Social Security indexes wages for AIME calculation.
+values:
+  1900-01-01: 60
+metadata:
+  unit: year
+  period: year
+  label: Wage indexing age
+  reference:
+    - title: 42 U.S.C. § 415(b)(3)(A)
+      href: https://www.law.cornell.edu/uscode/text/42/415#b_3_A
+    - title: Social Security POMS RS 00605.020
+      href: https://secure.ssa.gov/poms.nsf/lnx/0300605020
+    - title: SSA AIME Calculation
+      href: https://www.ssa.gov/OACT/COLA/aime.html

policyengine_us/parameters/gov/ssa/social_security/aime/max_earnings_age.yaml

@@ -0,0 +1,14 @@
+description: Maximum age for which Social Security counts earnings toward AIME calculation.
+values:
+  1900-01-01: 62
+metadata:
+  unit: year
+  period: year
+  label: Maximum earnings age for AIME
+  reference:
+    - title: 42 U.S.C. § 415(b)(2)(A)
+      href: https://www.law.cornell.edu/uscode/text/42/415#b_2_A
+    - title: 20 CFR § 404.211(a)(1)
+      href: https://www.law.cornell.edu/cfr/text/20/404.211
+    - title: Social Security POMS RS 00605.022
+      href: https://secure.ssa.gov/poms.nsf/lnx/0300605022

policyengine_us/parameters/gov/ssa/social_security/aime/minimum_age_for_earnings.yaml

@@ -0,0 +1,14 @@
+description: Minimum age at which Social Security counts substantial earnings for AIME calculation.
+values:
+  1900-01-01: 22
+metadata:
+  unit: year
+  period: year
+  label: Minimum age for substantial earnings
+  reference:
+    - title: 42 U.S.C. § 415(b)(2)(B)(ii)
+      href: https://www.law.cornell.edu/uscode/text/42/415#b_2_B_ii
+    - title: 20 CFR § 404.211(b)
+      href: https://www.law.cornell.edu/cfr/text/20/404.211
+    - title: Social Security POMS RS 00605.022
+      href: https://secure.ssa.gov/poms.nsf/lnx/0300605022

policyengine_us/parameters/gov/ssa/social_security/aime/months_per_year.yaml

@@ -0,0 +1,12 @@
+description: Number of months per year Social Security uses for AIME calculation.
+values:
+  1900-01-01: 12
+metadata:
+  unit: month
+  period: year
+  label: Months per year
+  reference:
+    - title: 42 U.S.C. § 415(b)(1)
+      href: https://www.law.cornell.edu/uscode/text/42/415#b_1
+    - title: Social Security POMS RS 00605.005
+      href: https://secure.ssa.gov/poms.nsf/lnx/0300605005

policyengine_us/parameters/gov/ssa/social_security/aime/years_of_earnings.yaml

@@ -0,0 +1,14 @@
+description: Number of highest earning years Social Security uses in AIME calculation.
+values:
+  1900-01-01: 35
+metadata:
+  unit: year
+  period: year
+  label: Years of earnings for AIME
+  reference:
+    - title: 42 U.S.C. § 415(b)(1)
+      href: https://www.law.cornell.edu/uscode/text/42/415#b_1
+    - title: 20 CFR § 404.211(a)
+      href: https://www.law.cornell.edu/cfr/text/20/404.211
+    - title: Social Security POMS RS 00605.017
+      href: https://secure.ssa.gov/poms.nsf/lnx/0300605017

policyengine_us/parameters/gov/ssa/social_security/earnings_test/exempt_amount_under_fra.yaml

@@ -0,0 +1,66 @@
+description: The US reduces benefits if earnings exceed this amount for beneficiaries under full retirement age.
+values:
+  # Historical values from SSA.gov/OACT/COLA/rtea.html
+  1975-01-01: 2_520
+  1976-01-01: 2_760
+  1977-01-01: 3_000
+  1978-01-01: 3_240
+  1979-01-01: 3_480
+  1980-01-01: 3_720
+  1981-01-01: 4_080
+  1982-01-01: 4_440
+  1983-01-01: 4_920
+  1984-01-01: 5_160
+  1985-01-01: 5_400
+  1986-01-01: 5_760
+  1987-01-01: 6_000
+  1988-01-01: 6_120
+  1989-01-01: 6_480
+  1990-01-01: 6_840
+  1991-01-01: 7_080
+  1992-01-01: 7_440
+  1993-01-01: 7_680
+  1994-01-01: 8_040
+  1995-01-01: 8_160
+  1996-01-01: 8_280
+  1997-01-01: 8_640
+  1998-01-01: 9_120
+  1999-01-01: 9_600
+  2000-01-01: 10_080
+  2001-01-01: 10_680
+  2002-01-01: 11_280
+  2003-01-01: 11_520
+  2004-01-01: 11_640
+  2005-01-01: 12_000
+  2006-01-01: 12_480
+  2007-01-01: 12_960
+  2008-01-01: 13_560
+  2009-01-01: 14_160
+  2010-01-01: 14_160
+  2011-01-01: 14_160
+  2012-01-01: 14_640
+  2013-01-01: 15_120
+  2014-01-01: 15_480
+  2015-01-01: 15_720
+  2016-01-01: 15_720
+  2017-01-01: 16_920
+  2018-01-01: 17_040
+  2019-01-01: 17_640
+  2020-01-01: 18_240
+  2021-01-01: 18_960
+  2022-01-01: 19_560
+  2023-01-01: 21_240
+  2024-01-01: 22_320
+  2025-01-01: 23_400
+metadata:
+  unit: currency-USD
+  period: year
+  label: Earnings test exempt amount (under FRA)
+  uprating: gov.ssa.uprating
+  reference:
+    - title: 42 U.S.C. § 403(f)(8)(B)
+      href: https://www.law.cornell.edu/uscode/text/42/403#f_8_B
+    - title: 20 CFR § 404.430
+      href: https://www.law.cornell.edu/cfr/text/20/404.430
+    - title: Social Security Retirement Earnings Test Exempt Amounts
+      href: https://www.ssa.gov/OACT/COLA/rtea.html

policyengine_us/parameters/gov/ssa/social_security/earnings_test/exempt_amount_year_of_fra.yaml

@@ -0,0 +1,67 @@
+description: The US applies a higher exempt amount in the year a person reaches full retirement age.
+values:
+  # Historical values from SSA.gov/OACT/COLA/rtea.html
+  # Before 2000, the year-of-FRA threshold was the same as under-FRA
+  1975-01-01: 2_520
+  1976-01-01: 2_760
+  1977-01-01: 3_000
+  1978-01-01: 3_240
+  1979-01-01: 3_480
+  1980-01-01: 3_720
+  1981-01-01: 4_080
+  1982-01-01: 4_440
+  1983-01-01: 4_920
+  1984-01-01: 5_160
+  1985-01-01: 5_400
+  1986-01-01: 5_760
+  1987-01-01: 6_000
+  1988-01-01: 6_120
+  1989-01-01: 6_480
+  1990-01-01: 6_840
+  1991-01-01: 7_080
+  1992-01-01: 7_440
+  1993-01-01: 7_680
+  1994-01-01: 8_040
+  1995-01-01: 8_160
+  1996-01-01: 8_280
+  1997-01-01: 8_640
+  1998-01-01: 9_120
+  1999-01-01: 9_600
+  2000-01-01: 17_000
+  2001-01-01: 25_000
+  2002-01-01: 30_000
+  2003-01-01: 30_720
+  2004-01-01: 31_080
+  2005-01-01: 31_800
+  2006-01-01: 33_240
+  2007-01-01: 34_440
+  2008-01-01: 36_120
+  2009-01-01: 37_680
+  2010-01-01: 37_680
+  2011-01-01: 37_680
+  2012-01-01: 38_880
+  2013-01-01: 40_080
+  2014-01-01: 41_400
+  2015-01-01: 41_880
+  2016-01-01: 41_880
+  2017-01-01: 44_880
+  2018-01-01: 45_360
+  2019-01-01: 46_920
+  2020-01-01: 48_600
+  2021-01-01: 50_520
+  2022-01-01: 51_960
+  2023-01-01: 56_520
+  2024-01-01: 59_520
+  2025-01-01: 62_160
+metadata:
+  unit: currency-USD
+  period: year
+  label: Earnings test exempt amount (year of FRA)
+  uprating: gov.ssa.uprating
+  reference:
+    - title: 42 U.S.C. § 403(f)(8)(D)
+      href: https://www.law.cornell.edu/uscode/text/42/403#f_8_D
+    - title: 20 CFR § 404.430
+      href: https://www.law.cornell.edu/cfr/text/20/404.430
+    - title: Social Security Retirement Earnings Test Exempt Amounts
+      href: https://www.ssa.gov/OACT/COLA/rtea.html

policyengine_us/parameters/gov/ssa/social_security/earnings_test/reduction_rate_under_fra.yaml

@@ -0,0 +1,14 @@
+description: The US withholds this amount from benefits for every $2 earned above the exempt amount.
+values:
+  1940-01-01: 0.5  # $1 for every $2 over limit
+metadata:
+  unit: /1
+  period: year
+  label: Earnings test reduction rate (under FRA)
+  reference:
+    - title: 42 U.S.C. § 403(f)(3)
+      href: https://www.law.cornell.edu/uscode/text/42/403#f_3
+    - title: 20 CFR § 404.434(a)
+      href: https://www.law.cornell.edu/cfr/text/20/404.434
+    - title: Social Security POMS RS 02501.021
+      href: https://secure.ssa.gov/poms.nsf/lnx/0302501021

policyengine_us/parameters/gov/ssa/social_security/earnings_test/reduction_rate_year_of_fra.yaml

@@ -0,0 +1,14 @@
+description: The US withholds this amount from benefits for every $3 earned above the exempt amount in the year of reaching FRA.
+values:
+  1940-01-01: 0.333333  # $1 for every $3 over limit
+metadata:
+  unit: /1
+  period: year
+  label: Earnings test reduction rate (year of FRA)
+  reference:
+    - title: 42 U.S.C. § 403(f)(3)
+      href: https://www.law.cornell.edu/uscode/text/42/403#f_3
+    - title: 20 CFR § 404.434(b)
+      href: https://www.law.cornell.edu/cfr/text/20/404.434
+    - title: Social Security POMS RS 02501.021
+      href: https://secure.ssa.gov/poms.nsf/lnx/0302501021

policyengine_us/parameters/gov/ssa/social_security/full_retirement_age_by_birth_year.yaml

@@ -0,0 +1,65 @@
+description: The US determines full retirement age based on year of birth.
+metadata:
+  type: single_amount
+  threshold_unit: year
+  amount_unit: month
+  label: Full retirement age in months by birth year
+  reference:
+    - title: 42 U.S. Code § 416(l) - Retirement age
+      href: https://www.law.cornell.edu/uscode/text/42/416#l
+    - title: SSA Full Retirement Age
+      href: https://www.ssa.gov/benefits/retirement/planner/agereduction.html
+
+brackets:
+  - threshold:
+      1900-01-01: 1900
+    amount:
+      1900-01-01: 780       # 65 years for those born before 1938
+  - threshold:
+      1900-01-01: 1938
+    amount:
+      1900-01-01: 782       # 65 years 2 months
+  - threshold:
+      1900-01-01: 1939
+    amount:
+      1900-01-01: 784       # 65 years 4 months
+  - threshold:
+      1900-01-01: 1940
+    amount:
+      1900-01-01: 786       # 65 years 6 months
+  - threshold:
+      1900-01-01: 1941
+    amount:
+      1900-01-01: 788       # 65 years 8 months
+  - threshold:
+      1900-01-01: 1942
+    amount:
+      1900-01-01: 790       # 65 years 10 months
+  - threshold:
+      1900-01-01: 1943
+    amount:
+      1900-01-01: 792       # 66 years for those born 1943-1954
+  - threshold:
+      1900-01-01: 1955
+    amount:
+      1900-01-01: 794       # 66 years 2 months
+  - threshold:
+      1900-01-01: 1956
+    amount:
+      1900-01-01: 796       # 66 years 4 months
+  - threshold:
+      1900-01-01: 1957
+    amount:
+      1900-01-01: 798       # 66 years 6 months
+  - threshold:
+      1900-01-01: 1958
+    amount:
+      1900-01-01: 800       # 66 years 8 months
+  - threshold:
+      1900-01-01: 1959
+    amount:
+      1900-01-01: 802       # 66 years 10 months
+  - threshold:
+      1900-01-01: 1960
+    amount:
+      1900-01-01: 804       # 67 years for those born 1960 and later

policyengine_us/parameters/gov/ssa/social_security/minimum_retirement_age.yaml

@@ -0,0 +1,14 @@
+description: >-
+  Minimum age at which a person can claim Social Security
+  retirement benefits.
+values:
+  1956-01-01: 62
+metadata:
+  unit: year
+  period: year
+  label: Minimum retirement age
+  reference:
+    - title: 42 U.S. Code § 402(a) - Old-age insurance benefits
+      href: https://www.law.cornell.edu/uscode/text/42/402#a
+    - title: SSA Early or Late Retirement
+      href: https://www.ssa.gov/OACT/quickcalc/early_late.html