Taxes¶
Tax models compute income tax liabilities. All models implement the TaxModel protocol.
TaxModel Protocol¶
TaxModel
¶
Bases: Protocol
Protocol for tax computation.
tax_on_income(gross_income)
¶
Compute tax on earned income.
tax_rate_traditional()
¶
Effective tax rate on traditional account withdrawals.
compute_annual_tax(ordinary_income, ltcg, filing_status)
¶
Compute total annual federal tax.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ordinary_income
|
float
|
Gross ordinary income (before standard deduction). |
required |
ltcg
|
float
|
Long-term capital gains. |
required |
filing_status
|
str
|
|
required |
Returns:
| Type | Description |
|---|---|
float
|
Total tax liability. |
compute_annual_tax_vectorized(ordinary_income, ltcg, filing_status)
¶
Vectorized annual tax across all paths.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ordinary_income
|
NDArray[floating[Any]]
|
(n_paths,) ordinary income per path. |
required |
ltcg
|
NDArray[floating[Any]]
|
(n_paths,) long-term capital gains per path. |
required |
filing_status
|
str
|
|
required |
Returns:
| Type | Description |
|---|---|
NDArray[floating[Any]]
|
(n_paths,) total tax liability per path. |
marginal_rate(taxable_income, filing_status)
¶
Marginal ordinary income tax rate at given taxable income.
FlatTaxModel¶
FlatTaxModel
¶
Flat effective tax rate applied to traditional withdrawals and income.
tax_on_income(gross_income)
¶
Compute tax on earned income.
tax_rate_traditional()
¶
Effective tax rate on traditional account withdrawals.
compute_annual_tax(ordinary_income, ltcg, filing_status)
¶
Compute total annual tax at flat rate.
compute_annual_tax_vectorized(ordinary_income, ltcg, filing_status)
¶
Vectorized annual tax at flat rate across all paths.
marginal_rate(taxable_income, filing_status)
¶
Marginal rate is always the flat rate.
USFederalTaxModel¶
USFederalTaxModel
¶
US Federal income tax with progressive brackets.
Loads bracket tables from YAML data files. Supports ordinary income brackets and long-term capital gains rates.
standard_deduction(filing_status)
¶
Return standard deduction for filing status.
tax_on_income(gross_income)
¶
Compute tax on ordinary income (single filer, after standard deduction).
tax_rate_traditional()
¶
Approximate effective rate for traditional withdrawals.
Returns a moderate estimate (22% bracket) for use in gross-up calculations during the monthly loop.
compute_annual_tax(ordinary_income, ltcg, filing_status)
¶
Compute total annual federal tax.
Ordinary income is taxed at progressive rates after standard deduction. LTCG is taxed at preferential rates based on total taxable income.
compute_annual_tax_vectorized(ordinary_income, ltcg, filing_status)
¶
Vectorized annual tax across all paths.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ordinary_income
|
NDArray[floating[Any]]
|
(n_paths,) ordinary income per path. |
required |
ltcg
|
NDArray[floating[Any]]
|
(n_paths,) long-term capital gains per path. |
required |
filing_status
|
str
|
Filing status key. |
required |
Returns:
| Type | Description |
|---|---|
NDArray[floating[Any]]
|
(n_paths,) total tax liability per path. |
compute_niit_vectorized(ordinary_income, ltcg, filing_status)
¶
Compute Net Investment Income Tax (3.8% surtax).
NIIT applies to the lesser of net investment income (here approximated as LTCG) or the excess of MAGI over the threshold.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ordinary_income
|
NDArray[floating[Any]]
|
(n_paths,) ordinary income per path. |
required |
ltcg
|
NDArray[floating[Any]]
|
(n_paths,) long-term capital gains per path. |
required |
filing_status
|
str
|
Filing status key. |
required |
Returns:
| Type | Description |
|---|---|
NDArray[floating[Any]]
|
(n_paths,) NIIT liability per path. |
bracket_ceiling(target_rate, filing_status)
¶
Return the gross income ceiling for a target marginal rate.
Returns the maximum gross income (bracket upper bound + standard
deduction) at which the marginal rate is still at or below
target_rate. Used by fill_bracket Roth conversion strategy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target_rate
|
float
|
Target marginal tax rate (e.g. 0.22 for 22% bracket). |
required |
filing_status
|
str
|
Filing status key. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Maximum gross income before exceeding the target bracket. |
marginal_rate(taxable_income, filing_status)
¶
Return the marginal ordinary income tax rate at given taxable income.
RMDCalculator¶
RMDCalculator
¶
Compute Required Minimum Distributions from IRS Uniform Lifetime Table.
start_age
property
¶
Age when RMDs begin.
divisor(age)
¶
Look up the RMD divisor for a given age.
compute_rmd(age, prior_year_balance)
¶
Compute RMD amount for each path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
age
|
int
|
Current age (integer). |
required |
prior_year_balance
|
NDArray[floating[Any]]
|
(n_paths,) prior year-end traditional balance. |
required |
Returns:
| Type | Description |
|---|---|
NDArray[floating[Any]]
|
(n_paths,) RMD amounts. Zero if age < start_age. |