The Projection Space#
The by-contract projection of FIA_US_SEC.
The Space is parameterized by idx, the position of a model point in the table and in
every Data vector, as basiclife.BasicTerm_SC is:
Projection[0] is an ItemSpace projecting the table’s first row, model point 1, the
worked example’s anchor cell in force at anniversary 7, and point_id() is its
label:
>>> Projection[0].result_cf() # one row per month from the valuation date
>>> Projection[0].result_cf_annual() # the same, summed into contract years
>>> Projection[0].point_id() # 1, the row's point_id
>>> Projection.idx = 1 # or switch the default, before it computes
Compiled, no cache is ever cleared: set idx, like every Reference, on a model just
imported, before anything is computed, or project through Projection[i]. modelx
recomputes what a Reference reaches when it is set; a compiled ItemSpace takes the
References when it is made and keeps every value it has computed until it is deleted,
and the base Projection and Data keep theirs for good. And it holds each Reference
as a C variable of its shipped value’s type: a float set on an int Reference truncates
toward zero, and an int set on a float Reference reads as a float
(products/fixed_indexed_annuity/model-sec.md, What it refuses).
Any idx makes an ItemSpace, and none is refused here. Projection[-1] reads every
vector at its last element, as numpy and a compiled memoryview both do, so it is the
table’s last point, under that point’s own point_id(); an idx past the last
row raises IndexError at its first read of a vector, which modelx reports inside its
FormulaError.
This is FIA_US_S taught to run in force at a valuation date, as lifelib’s
basiclife.BasicTerm_SE extends basiclife.BasicTerm_S, and then made to compile, as
basiclife.BasicTerm_SC is made from basiclife.BasicTerm_S, on the chassis
MYGA_US_SEC compiled first. A formula of FIA_US_S is rewritten where it
depends on where the projection starts, where it must answer for a month outside cover,
where it passed a policy month as t, where it compared a phase or a switch as text, or
where it reads a table or text the compiled model holds as numbers; every other is
FIA_US_S’s own.
products/fixed_indexed_annuity/model-sec.md lists the rewritten cells with the
reason for each.
Input data
Inputs are external files: plain CSVs living in the model folder’s parent directory,
products/fixed_indexed_annuity/, read at run time rather than stored inside the
model. The model folder therefore holds nothing but formulas — no _data/, no IOSpec,
no embedded values — so a diff of the model shows logic changes only, and an input can be
edited or swapped without rewriting the model. This follows annuallife.TradLife_A;
contrast basiclife.BasicTerm_S, which keeps its inputs inside the model through
modelx’s IOSpec machinery.
The consequence worth knowing: the model is not portable on its own. Copying the
FIA_US_SEC folder without its parent’s CSVs produces a model that reads and then
fails on first evaluation.
The readers and the filename References live on the sibling Data
Space, reached here through the data Reference, so each file is read once per model
rather than once per model point. Five assumption tables are the files
FIA_US_S reads, read in place; the model point table and the rate scenarios are
this model’s own, generated from FIA_US_S and its inputs. The projection reads
each table as Data holds it in arrays, built from the table checked, its keys read by
value, and through one cell of its own:
Reference (on Data) |
Arrays the projection reads |
File |
|---|---|---|
model_point_file |
data.premium() and the vectors |
model_point_table_sec.csv |
mort_table_file |
data.mort_table_array() |
mort_table.csv |
surr_charge_file |
data.surr_charge_rate_array(), data.vest_rate_array() |
surr_charge_table.csv |
rollup_file |
data.rollup_rate_array() |
rollup_table.csv |
payout_rate_file |
data.payout_rate_array() |
payout_rate_table.csv |
rate_scenario_file |
data.index_level_array(), data.mva_ref_yield_array() |
rate_scenario_sec.csv |
withdrawal_file |
data.wd_amount_array() |
withdrawal_table.csv |
The model point’s attributes are each one element of a Data vector, read by an
accessor of the column’s name, premium_pp reading data.premium()[idx];
model_point(), the whole row, is for a reader. mort_rate_base_at(),
surr_charge_rate_py() with vest_rate_py(), rollup_rate_py(),
payout_rate_at(), scenario_value() and wd_scheduled_at() are the
tables’ readers, in that order, each keyed by an age, a contract year, a count of years
or an anniversary rather than by the month, and called by a monthly cell in cover only.
The mortality, the rollup schedule, the scenario and the withdrawal programme are read at
the row Data numbers the point’s sex, rollup_id, scenario_id or
wd_schedule_id by, mort_schedule(), rollup_number(),
scenario_number() or wd_schedule_number() (Data’s docstring, The
vectors).
Projection basis
Monthly steps on two clocks. t counts months from the valuation date, 0-based,
the clock basiclife.BasicTerm_SE runs on: t = 0 is the valuation month for every
model point, however old the contract, month t runs from time t to time
t + 1, and the frame is t = 0 .. proj_len() - 1, where proj_len() counts
the months from the valuation date to the end of cover,
maturity_mth() - duration_mth_init(). Row t is the same month for every point,
so the frames of a block line up and sum row by row.
duration_mth(t) counts policy months, the months the contract has been in force
at time t: duration_mth(t) = duration_mth_init() + t, where
duration_mth_init() is read from the model point — positive for a contract in
force at the valuation date, in any month of its contract year, 0 for one issued at it,
-k for one issued k months later, at most ten years later. It is
FIA_US_S’s t, the notes’ month index, and everything contractual reads it:
duration(t) = duration_mth(t) // 12 is the completed contract years at the start of
month t, the contractual label is policy_year(t) = duration(t) + 1, and the
anniversary month, where every annual event lands, is the one with
duration_mth(t) % 12 == 11. The grid matches MYGA_US_S, Term_US_S and
the rest of the library, and it is what the product assignment table records for this
product.
Two inputs read the valuation clock instead. The rate scenario — the index level and
the MVA reference yield — is a path in calendar time, shared by every point of a block,
so the t of rate_scenario_sec.csv is a valuation month; each anniversary’s level is
read at the valuation month that anniversary falls in, through scenario_value(),
and the level at the anniversary that opened the year under way, where that anniversary
precedes the valuation date, is the model point’s index_level_prev_anniv_init().
And expense inflation, inflation_factor(t) = (1 + inflation_rate) ** (t / 12),
keeps FIA_US_S’s formula on t, so maintenance expense is in valuation-date
dollars for every point alike. The surrender charge, the vesting, the rollup schedule, the
growth window, the shock-lapse year, the MVA term, the withdrawal programme, the payout
bands and the mortality stay on the policy clock, read at the contract year, the elapsed
year count or the age. On a point issued at t = 0 the two clocks coincide, and the
model computes what FIA_US_S computes.
The monthly grid does not make the product monthly. The technical notes make the
anniversary the single event date — “All transactions occur at the anniversary and are
processed as the last events of the contract year ending there” [std] — and that is
still true here: every contractual event is an annual event landing in the anniversary
month, is_anniv(t), the last month of each contract year. What the finer grid buys is
everything that is not a contractual event: mortality and surrender now fall in the month
they happen rather than all at the anniversary, the Model #805 floor and the fixed account
accrue month by month so a mid-year death or surrender is valued on the balance it actually
has, and maintenance expense accrues where it is incurred. Because the monthly decrement
rates compound to the annual ones and every contractual step still happens once a year,
every state value at an anniversary is identical to the annual grid’s — account value,
benefit base, rollup base, lifetime withdrawal, Model #805 floor, phase and pols_if in
the month opening each contract year. What changes is the timing and the weighting of the
cash, which is the point.
Three vocabulary cells carry the split, and the whole model is written in terms of them:
duration() for anything keyed by contract year, is_anniv() for anything that
happens once a year, and year_open_mth() for the month whose closing value opens the
contract year — because on a monthly grid the previous month is no longer the previous
year, and reaching for t - 1 where a year is meant is the mistake this conversion
exists to prevent. year_open_mth() and anniv_mth() are months of the frame,
on the valuation clock, computed from duration_mth(t) % 12.
age(t) = age_at_entry() + duration(t) is the attained age opening the contract year
of month t, so mortality over that year reads age(t) itself — the library
convention of Term_US_S and MYGA_US_S. Age changes on the anniversary, not
on the birthday and not monthly. The transactions at the closing anniversary are one year
older, and that age is exercise_age(), covered_age(t) + 1: it is what reads the
lifetime-withdrawal percentage table and what clears the contractual minimum exercise age.
There is no issue-instant row. The single premium, the premium bonus and the
acquisition expense are beginning-of-month flows of the issue month, the one with
duration_mth(t) = 0, t_entry() on a point issued at or after the valuation
date, alongside that month’s own activity, and the issue values are credited there by
FIA_US_S’s rules: P x (1 + b) to the account value through
prem_to_av_pp(), its fixed share to the fixed account, and 87.5% of the premium,
the bonus excluded, to the Model #805 floor through prem_to_mgsv_pp(); the benefit
base and the rollup base open the first contract year at P under the rider. A model
point may instead be in force at the valuation date, in any month of its contract year,
on the opening state its row carries, per contract, as the contract stands at the start of
month 0, before any month-0 event: the account value, the fixed account, the benefit
base, the rollup base, the lifetime withdrawal, the Model #805 floor and the withdrawals
to date entering month 0; and, at the anniversary on or before the valuation date, the
account value and the fixed account, the phase as a code, the locked payout percentage and
the index level. Each is exactly what FIA_US_S carries into the month the point
is valued at. Every recursion opens at t_entry(): a monthly balance on its _init
column, 0 on new business, and a quantity of the year — the opening account value and
fixed account, the benefit base, the rollup base, the lifetime withdrawal, the phase and
the locked percentage — is read at the anniversary that opened the year three ways: from
the frame where that anniversary is at or after t_entry(), from the model point’s
_prev_anniv_init or _init column where the year opened before the valuation date,
and by the issue rule in the first year of a contract issued at or after it. The rider
state opening the year has no column: it is read from the frame, or from glwb_elected()
where that anniversary precedes t_entry(), a contract in force with the rider elected
having it alive (rider_in_force_open()). result_cf() has exactly proj_len()
rows, t = 0 .. proj_len() - 1.
The anniversary’s eight processing steps are the notes’ own, all eight still annual and all
eight landing in the anniversary month, and each intermediate value is reachable through a
timing argument rather than being buried inside one formula:
index credit and fixed interest —
index_credit_pp(),fixed_interest_ann_pp()rider charge on the opening benefit base —
rider_charge_pp()benefit base: rollup, stack, step-up —
rollup_pp(),stack_pp()lifetime and excess withdrawal —
lw_pp_at(),wd_pp()charges on the excess and the proportional reduction —
wd_reduction_rate()guaranteed minimum value roll —
mgsv_pp()phase transition including the depletion test —
phase()decrements —
pols_if_at()atAFT_DECR
Steps 1–3 are skipped in DEPLETED, steps 1–7 in TERMINATED. Step 8 is the one
that is not annual: it runs every month, on mort_rate_mth() and
lapse_rate_mth(). Steps 1 and 6 keep a monthly component — the fixed account accrues
at (1 + i_F)^(1/12) - 1 and the Model #805 floor at (1 + i_nf)^(1/12) — while their
annual figures, fixed_interest_ann_pp() and the anniversary deduction, stay whole.
Between anniversaries the contract is quiet: no withdrawal, no rider charge, no index credit, no rollup and no step-up. The indexed account is therefore flat between anniversaries, because the annual point-to-point segment locks only at maturity and “the credit … cannot be lost to later declines” [S1] is a statement about a credit that has not yet been earned. That is the sourced rule “withdrawals are not credited with index interest in the year they are taken” [S1] carried to mid-year deaths and surrenders [std]; crediting a part year would be the daily interim value variant the notes exclude.
Outside cover, before issue and from proj_len() on, every count, cash flow,
balance and rate is 0.0, every flag is False, the phase is PRE_ISSUE before issue
and MATURED after cover, and lapse_moneyness_factor() is 1.0, no adjustment;
is_active() is the test, made before any table is read. One read reaches ahead of
the month: lapse_rate() reads the phase, and lapse_moneyness_factor() the
account value and the benefit base, at the anniversary closing the contract year,
anniv_mth(), up to 11 months later and inside the frame, a state that depends on
no count and on nothing after that anniversary.
Naming
Cell names follow MYGA_US_S — the deferred annuity chassis this
product sits on — and through it lifelib’s basiclife.BasicTerm_S and
savings.CashValue_SE: pols_* for policy counts, av_* for account values,
plural nouns for cash flows, *_rate for rates, *_pp for per-contract amounts,
*_at(t, timing) for a quantity read at a point inside the anniversary. What running in
force adds is named as basiclife.BasicTerm_SE names it: duration_mth read from the
model point, policy_count, pols_new_biz, pols_if_at with its BEF_NB
timing, is_active and result_pols. duration_mth_init, the policy months
completed at the valuation date, takes UL_US_S’s name, and t_entry and
maturity_mth are MYGA_US_SEC’s. A column of the opening state is the cell it
opens with _init added, av_pp_init for av_pp(); a balance at the anniversary
on or before the valuation date adds _prev_anniv_init instead,
av_pp_prev_anniv_init. A reader keyed by a contract year is <cell>_py and one keyed
by an age or a year count <cell>_at, as in MYGA_US_SEC, and a cell that reads
the anniversary opening the year is <cell>_year_open, as FIA_US_S’s
av_pp_year_open. The is_* cells decode the model point’s text columns, read in
Data, and the three switches, int codes here, into the flags the projection branches
on, so that no cell compares text and none calls a label accessor (credit_method,
glwb_basis, scenario_id, …), which is left to reporting. FIA_US_S’s
timing, kind and scenario column strings are int codes, named as the strings (Codes,
below). The technical notes use compact actuarial symbols instead.
The notes’ month index is this model’s duration_mth(t), so the notes’ t in the
left-hand column is duration_mth(t) throughout. The mapping is:
Notes symbol |
Cells |
Meaning |
|---|---|---|
t |
duration_mth(t) |
The notes’ month index: completed policy months at the start of month t |
(valuation month) |
(the projection index) |
Months from the valuation date, 0-based |
(elapsed years) |
duration(t) |
Completed contract years at month t |
(the anniversary month) |
is_anniv(t) |
Last month of a contract year |
(that month’s index) |
anniv_mth(t) |
Month closing t’s contract year, valuation clock |
(year-opening month) |
year_open_mth(t) |
Month whose close opened it, valuation clock |
(contract year) |
policy_year(t) |
Contract year containing t; duration + 1 |
x |
age_at_entry |
Issue age (ANB) |
x + duration(t) |
age(t) |
Attained age opening month t’s contract year |
(younger covered life) |
covered_age(t) |
Younger covered age opening that year |
x + duration(t) + 1 |
exercise_age(t) |
Covered age at the closing anniversary |
(none) |
policy_term |
Contract years from issue to maturity_age |
(cover from issue) |
maturity_mth |
Policy month cover ends; 12 x policy_term |
(none) |
proj_len |
Months from the valuation date to the end of cover |
(months at t = 0) |
duration_mth_init |
Completed policy months at the valuation date; -k if issued k months later |
(first month on books) |
t_entry |
max(0, -duration_mth_init) |
(in cover) |
is_active(t) |
Whether month t is inside cover |
(contracts) |
policy_count |
Contracts the model point stands for |
(the point’s label) |
point_id |
Its point_id, from Data; the Space is keyed by idx |
(the joins on text keys) |
mort_schedule, rollup_number, scenario_number, wd_schedule_number |
The row Data numbers the point’s sex, rollup_id, scenario_id and wd_schedule_id by, in their arrays |
av_initial |
av_pp_init |
AV entering month 0; 0 on new business |
(F entering month 0) |
av_fixed_pp_init |
Fixed account entering month 0 |
AV(0) at entry |
av_pp_prev_anniv_init |
AV at the anniversary on or before the valuation date |
F(0) at entry |
av_fixed_pp_prev_anniv_init |
F at that anniversary |
bb_initial |
benefit_base_pp_init |
BB entering month 0 |
mgv_initial |
mgsv_pp_init |
MGV entering month 0 |
(RB at entry) |
rollup_base_pp_init |
RB entering month 0 |
(LW at entry) |
lw_pp_init |
LW entering month 0, 0 before exercise |
(pi at entry) |
payout_rate_locked_prev_anniv_init |
Payout percentage locked at that anniversary |
(phase at entry) |
phase_prev_anniv_init |
Phase code at that anniversary |
I(y) at entry |
index_level_prev_anniv_init |
Index level at that anniversary |
Wcum at entry |
wd_cum_pp_init |
Withdrawals from issue to the valuation date |
P |
premium_pp |
Single premium |
b |
bonus_rate |
Premium bonus rate (7% [S5]) |
b/(1+b) |
bonus_factor |
Clawback factor – not b [S10] |
v(t) |
vest_rate(t) |
Vested bonus percentage [S5] |
v(y) |
vest_rate_py(y) |
The same, by contract year |
(allocation) |
alloc_indexed / alloc_fixed |
Account allocation at issue |
I(y) |
index_level(y) |
Index level at anniversary number y |
(the level by month) |
scenario_value(y, name) |
Scenario level at anniversary y’s valuation month |
R(t) |
index_return(t) |
I(y+1)/I(y) - 1 over month t’s year |
c |
cap_rate |
Declared annual cap (5.25% [S2]) |
c_min |
cap_rate_min |
Guaranteed minimum cap (0.25% [S4]) |
c(t) |
cap_rate_in_force() |
Cap actually applied |
f |
floor_rate |
Index credit floor (0%) |
p, s, d |
par_rate, spread_rate, trigger_rate |
Participation rate [R1]; spread and trigger, levels [std] |
(crediting method) |
is_credit_cap, is_credit_par, is_credit_par_cap, is_credit_spread, is_credit_trigger |
The crediting method, decoded |
cr(t) |
credit_rate(t) |
Credit rate for month t’s contract year |
(cr on a return) |
credit_rate_on(r, method) |
The crediting engine itself |
IC(t) |
index_credit_pp(t) |
Index credit, in the anniversary month |
FI(t) monthly |
fixed_interest_pp(t) |
Fixed account interest for month t |
FI(t) annual |
fixed_interest_ann_pp(t) |
The contract year’s, for the stack |
i_F, i_F,min |
fixed_rate, fixed_rate_min |
Declared / guaranteed fixed rate |
kappa |
av_int_factor |
Share of IC reaching the AV [S3] |
(IC x kappa + FI) |
inv_income_pp(t) |
Interest credited to the AV |
A(t) |
av_indexed_pp(t) |
Indexed account balance |
F(t) |
av_fixed_pp(t) |
Fixed account balance |
AV(t) |
av_pp(t) |
Account value closing month t |
AV(0), AV(1), AV(2) |
av_pp_at(t, timing) |
BEF_INV / BEF_FEE / BEF_WD; EOY is AV(t); BEF_PREM opens the month |
AV(0) of the year |
av_pp_year_open(t) |
Balance opening month t’s contract year |
F(0), A(0) of the year |
av_fixed_pp_year_open(t), av_indexed_pp_year_open(t) |
The fixed and indexed openings: the credit base and the fixed-interest base |
(premium credited) |
prem_to_av_pp(t) |
P x (1 + b), in the issue month |
l(t) x AV(t) |
av_at(t, timing) |
In-force weighted account value |
(AV shortfall) |
av_depletion_pp(t) |
Withdrawal the AV could not fund |
phi |
rider_charge_rate |
Rider charge rate (0.95% [S9]) |
Phi(t) |
rider_charge_pp(t) |
Rider charge amount |
BB(t) |
benefit_base_pp(t) |
GLWB benefit base, closing |
BB(3), BB(4) |
benefit_base_pp_at(t, timing) |
BEF_ROLLUP / BEF_STEP_UP / BEF_WD / EOY |
RB(t) |
rollup_base_pp(t) |
Rollup base |
RB(0) of the year |
rollup_base_pp_year_open(t) |
Rollup base opening the year |
(RB on a withdrawal) |
is_rb_pro_rata, is_rb_dollar |
rb_wd_convention, decoded |
g(t) |
rollup_rate(t) |
Guaranteed simple rollup rate [S2] |
g(y) |
rollup_rate_py(y) |
The same, by contract year |
rollup(t) |
rollup_pp(t) |
Rollup dollar increment |
m |
stack_factor |
Stacking factor (1.50 [S8][S9]) |
stack(t) |
stack_pp(t) |
Stacking credit |
T_g |
in_growth_period(t) |
Benefit base still growing |
(the step-up) |
step_up_applies(t) |
Whether the ratchet is tested |
(step-up mode) |
is_step_up_annual, is_step_up_at_exercise |
step_up_mode, decoded |
LW(t) |
lw_pp(t) |
Lifetime withdrawal amount, closing |
LW before/after step 5 |
lw_pp_at(t, timing) |
BEF_WD / EOY |
pi(a, basis) |
payout_rate(a, basis) |
Payout percentage by age band [S3] |
pi(a) |
payout_rate_at(a) |
The same, on the point’s basis |
(the basis) |
is_single_basis, is_joint_basis |
glwb_basis, decoded |
(pi locked at exercise) |
payout_rate_locked(t) |
The percentage actually in force |
h(a) |
activation_rate(a) |
Activation incidence, reported only |
G(t) |
wd_pp(t) |
Gross withdrawal requested |
(scheduled G) |
wd_scheduled_pp(t) |
Ad hoc withdrawal at the anniversary |
(G by year count) |
wd_scheduled_at(k) |
The same, by elapsed contract year |
min(G, LW) |
wd_guar_pp(t) |
Guaranteed portion |
E(t) |
wd_excess_pp(t) |
Excess above the guaranteed amount |
(unpayable withdrawal) |
wd_unfunded_pp(t) |
Requested but neither funded nor guaranteed, on TERMINATED |
(guaranteed part paid) |
wd_guar_paid_pp(t) |
min(G, LW) less its share of it |
(excess portion paid) |
wd_excess_paid_pp(t) |
E(t) less its share of it |
FW(t) |
free_wd_allow(t) |
Free withdrawal amount |
0.10 x AV(0)(t) |
free_wd_base(t) |
Base of the free amount |
(FW consumed) |
wd_free_pp(t) |
Free-allowance portion of the withdrawal |
(FW remaining) |
free_wd_remain(t) |
Free amount left for the excess |
X(t) on a withdrawal |
wd_charge_base_pp(t) |
Amount exposed to charge and MVA |
X(t) on a surrender |
surr_charge_base_pp(t) |
Same, at a full surrender |
sc(t) |
surr_charge_rate(t) |
Surrender charge percentage [S5] |
sc(y) |
surr_charge_rate_py(y) |
The same, by contract year |
SC(t) on a withdrawal |
wd_charge_pp(t) |
Surrender charge on the excess |
SC(t) on a surrender |
surr_charge_pp(t) |
Surrender charge on a surrender |
CB(t) on a withdrawal |
wd_clawback_pp(t) |
Non-vested bonus recovery |
CB(t) on a surrender |
surr_clawback_pp(t) |
Same, at a full surrender |
MVA(t) on a withdrawal |
wd_mva_pp(t) |
Collared MVA on the excess |
MVA(t) on a surrender |
mva_pp(t) |
Collared MVA on a surrender |
(the collar’s basis) |
is_collar_gross is_collar_surrender_value |
mva_collar_basis, decoded |
(the MVA rate) |
mva_rate(t) |
[(1+i0)/(1+it)]^(n/12) - 1 [S10] |
i0 |
mva_ref_yield_at_issue |
Reference index at issue |
i_y |
mva_ref_yield(y) |
Reference index at anniversary number y |
n/12 |
mva_term(t) |
Years left in the MVA period |
(MVA applies at all) |
mva_in_force(t) |
Inside the MVA period |
rho(t) |
wd_reduction_rate(t) |
Proportional reduction factor |
Wcum(t) |
wd_cum_pp(t) |
Cumulative gross withdrawals |
G - SC - CB + MVA |
wd_payment_pp(t) |
Cash paid on the withdrawal |
(SV before the floor) |
surr_value_pp(t) |
AV - SC - CB + MVA |
CSV(t) |
surr_benefit_pp(t) |
Surrender benefit paid |
MGV(t) |
mgsv_pp(t) |
Model #805 guaranteed minimum |
(0.875 x P) |
prem_to_mgsv_pp(t) |
The floor’s issue value, in the issue month |
i_nf |
mgsv_rate |
Nonforfeiture accumulation rate |
(the $50 charge) |
mgsv_charge_pp(t) |
Annual contract charge, 0 [std] |
(statutory i_nf) |
mgsv_rate_statutory(…) |
Model #805 4B/4C indexed rate |
phase(t) |
phase(t) |
Closing phase code, ACCUM .. TERMINATED |
(phase opening a year) |
phase_year_open(t) |
Phase code at the anniversary opening t’s year |
(phase during the year) |
phase_open(t) |
Phase steps 1-7 are processed under |
(first exercise) |
is_exercise(t) |
The first lifetime withdrawal |
rider_in_force(t) |
rider_in_force(t) |
Rider still alive closing month t [S9] |
rider_in_force(k-1) |
rider_in_force_open(t) |
Rider alive opening the contract year |
depletion_cause(t) |
depletion_cause(t) |
Excess / charge / negative MVA flag |
q(t) |
mort_rate(t) |
Annual mortality of month t’s contract year, capped at 1 |
q at age a |
mort_rate_base_at(a) |
The table’s rate at age a |
1 - (1-q)^(1/12) |
mort_rate_mth(t) |
The monthly rate actually applied |
(A/E deviation) |
mort_ae_factor |
Mortality A/E factor, 100% [std] |
w(t) |
lapse_rate(t) |
Annual surrender rate of that year |
1 - (1-w)^(1/12) |
lapse_rate_mth(t) |
The monthly rate actually applied |
w_base(t) |
lapse_rate_base(t) |
Base surrender table |
w_shock |
shock_lapse_rate(t) |
33% / 10% / 5% by rider state [R8] |
M_money(t) |
lapse_moneyness_factor(t) |
Moneyness suppression [std] |
l(k), opening a year |
pols_if(t) |
In force opening month t, after its new business |
(closing the month) |
pols_if_at(t, AFT_DECR) |
In force at the end of month t |
l(0) |
pols_if_init |
In force at the valuation date; 0 for new business |
(new business) |
pols_new_biz(t) |
Contracts issued in month t |
(the five readings) |
pols_if_at(t, timing) |
BEF_NB / BEF_DECR / BEF_MORT / BEF_LAPSE / AFT_DECR |
l q_m |
pols_death(t) |
Deaths in the month |
l (1-q_m) w_m |
pols_lapse(t) |
Full surrenders in the month |
(none) |
pols_maturity(t) |
Survivors at the horizon |
P on new business |
premiums(t) |
Premium income, in the issue month |
(premium credited) |
prem_to_av(t) |
The same, in-force weighted |
min(G, LW) x l(t) |
wd_guar(t) |
Guaranteed withdrawal outgo, paid |
(E - SC - CB + MVA) l(t) |
wd_excess(t) |
Excess withdrawal outgo, paid |
LW while DEPLETED |
income_payments(t) |
Post-depletion income outgo |
(all three together) |
withdrawals(t) |
Total withdrawal outgo |
(ledger benefit lines) |
claims(t, kind) |
Benefit outgo by kind |
(benefit per contract) |
claim_pp(t, kind) |
Benefit per contract by kind |
(AV released) |
claims_from_av(t, kind) |
Account value released by a claim |
(paid above AV) |
claims_over_av(t, kind) |
Benefit paid above the account value |
(no separate commission) |
commissions(t) |
Acquisition commission, 0 [std] |
(80/12) x 1.025^(t/12) |
expenses(t) |
Monthly maintenance, valuation clock, plus 0.06 P on issue |
1.025^(t/12) |
inflation_factor(t) |
Expense inflation, valuation clock |
premium tax |
premium_taxes(t) |
Premium tax, 0% [std] |
NetCF(t) |
net_cf(t) |
Net cash flow for the month |
(the annual summary) |
result_cf_annual() |
result_cf() summed into contract years |
(none) |
result_pols() |
The counts behind result_cf |
(the model point) |
model_point() |
The point’s row of the table |
Six names needed care.
pols_if(t) is the notes’ l(k) in the month opening each contract year. Across this
library pols_if(t) is the number in force at the start of t and is the weight
carried by that same row’s cash flows — Term_US_S has pols_if(0) the count
issued and savings.CashValue_SE has pols_if(t) equal to
pols_if_at(t, "BEF_MAT"). Here it is pols_if_at(t, BEF_DECR), the count carried
in plus the month’s new business, before the month’s decrements. The notes define
l(k) as the in-force probability at the end of contract year k, which is
anniversary k, which is where contract year k + 1 opens: on the monthly grid that
is the month with duration_mth(t) = 12k, so pols_if there is l(k), and in the
issue month of a contract issued at or after the valuation date it is l(0), its
policy_count. Because the monthly rates compound to the annual ones this equality is
exact, not approximate.
The one place the finer grid changes an answer rather than its resolution is the weight
on the anniversary’s own cash. A withdrawal, a rider charge or a surrender charge falls in
the anniversary month and is weighted by pols_if there — the contracts that actually
reach the anniversary — where the annual grid weighted it by l(k), the contracts that
entered the year. The second is an approximation the annual grid could not avoid: it pays a
full year’s guaranteed withdrawal to a contract that died in month three. The
reconciliation the convention buys is unchanged, and now holds row by row on the finer
grid: the pols_if column of result_cf() is the divisor of the cash flows on its
own row — result_cf()["wd_guar"][t] / wd_guar_paid_pp(t) is pols_if(t).
MGV is MGSV. The Model #805 floor is called MGV in these notes, after [S10], and
MGSV in products/fixed_deferred_annuity/, after its own specimen. Both source
files say in terms that this is one quantity under two labels and must not be modeled
as two. The chassis name mgsv_pp() is used here, so the two annuity models share it.
The recursion, however, is not the chassis’s: this product accretes and then deducts,
MGV(t) = max(0, MGV(t-1) x (1 + i_nf) - G(t)), while the chassis deducts and then
accretes, MGSV(t) = [MGSV(t-1) - d(t) - c(t)] x g. The worked example pins the FIA
ordering — 93,811.84 x 1.01 - 10,144.16 = 84,605.80 — and the chassis notes explicitly
warn against carrying their recursions across unexamined. Same name, same concept,
different arithmetic, on purpose.
E(t) is not the chassis’s E(t). On the chassis E(t) is the amount exposed to the
surrender charge and the MVA, and is named wd_excess_pp / surr_excess_pp. Here
E(t) is the notes’ excess withdrawal — the part of a gross withdrawal above the
guaranteed lifetime amount, the quantity that permanently reduces the guarantee and, at
exhaustion, destroys it. That is the product’s headline concept and it keeps the name
wd_excess_pp(). The chargeable amount, the notes’ X(t), becomes
wd_charge_base_pp() on the withdrawal path and surr_charge_base_pp() on the
surrender path. Reading a chassis formula across without renaming would silently charge a
surrender charge on the wrong base.
age(t) opens the contract year; exercise_age(t) closes it.
age(t) = age_at_entry() + duration(t) is the attained age at the anniversary that opens
month t’s contract year, exactly as in Term_US_S and MYGA_US_S, and
mort_rate() reads it directly — the annual rate it returns is then converted for the
month by mort_rate_mth(). Every transaction, however, falls at the closing
anniversary, one year older, and the payout percentage depends on that age: the anchor
cell’s first lifetime withdrawal, in contract year 8 from an issue age of 62, is taken at
attained age 70 and reads pi(70, single) = 5.20%. exercise_age() carries that age
— covered_age(t) + 1 — so the + 1 is named once rather than spelled at each use.
M_shock is absorbed into lapse_rate_base. The notes write
w(t) = min(0.35, w_base(t) x M_shock(t) x M_money(t)) but state the shock as three
absolute rates (33% / 10% / 5%) rather than as multipliers on the 6% ultimate. Carrying
M_shock as a separate factor would require inventing a denominator, so
lapse_rate_base() returns shock_lapse_rate() in the shock year and
lapse_rate() multiplies only by lapse_moneyness_factor(). The name
shock_lapse_rate follows Term_US_S — but the timing does not, and the
contrast is worth stating. There the notes put the shock “in full at the end of the final
level-period month”, a contractual date, so Term_US_S drops the whole shock in that
one month. Here the notes state it as the surrender rate of contract year 11, a year that
carries no surrender charge in any of its months, so there is no date inside the year for
the decision to cluster on and lapse_rate_mth() spreads it like any other annual
rate. The one surrender that is not spread is the deemed full surrender at termination,
which is a contractual event and lands whole on the anniversary.
d and c collide across the library. d is the performance-trigger rate in these
notes, deaths in Term_US_S and the floor’s withdrawal deduction on the chassis;
c is the declared cap here and the floor’s contract charge on the chassis. The names
trigger_rate, pols_death(), mgsv_charge_pp() and cap_rate()
keep the four apart.
One name is reused deliberately and reads across cleanly. credit_rate() is the
chassis’s declared effective annual rate i_cr(t) and here the index credit rate
cr(t) = max(f, min(c, R(t))). Different formulas, but the same concept — the rate at
which interest is credited for the contract year — so the name is kept rather than split.
Timing arguments
Account value, following CashValue_SE’s av_pp_at and named for the processing step
each precedes:
BEF_PREMthe balance carried into month
tbefore the single premium: att_entry(),av_pp_init(), the account value of a contract in force at the valuation date and zero on new business, andAV(t-1)after it. It exists so that the account-value roll-forward closes on the issue month too, the premium being a beginning-of-month flow rather than a row of its own.BEF_INVthe balance opening month
tafter the premium:BEF_PREMplusprem_to_av_pp(), which isP x (1 + b)in the issue month and zero in every other. In an anniversary month this is the notes’AV(0)only when the fixed allocation is zero; in general the notes’AV(0)of the contract year isav_pp_year_open(), eleven months earlier.BEF_FEEAV(1), after the month’s interest — the fixed accrual every month, plus the index credit in an anniversary month — and before the rider charge.BEF_WDAV(2), after the rider charge, before the withdrawal. Not floored at zero — the 0% floor is on the index credit, not on the account value [S7].EOYAV(t), after the withdrawal, floored at zero. Equal toav_pp().
Away from an anniversary the last three coincide, at the opening balance plus the month’s fixed accrual, because no contractual transaction falls there.
Benefit base, named for the same steps: BEF_ROLLUP is the base opening the contract
year, BEF_STEP_UP is BB(3) after rollup and stack, BEF_WD is BB(4)
after the annual step-up, and EOY is BB(t) after the proportional reduction. All
four steps are annual, so away from an anniversary every timing returns the opening base.
Lifetime withdrawal: BEF_WD is the amount payable at the contract year’s anniversary,
EOY the closing value after the same reduction; away from an anniversary both carry
the amount set at the last one, which is the income in force.
Policy counts, following the chassis and basiclife.BasicTerm_SE: BEF_NB is the
count carried in from month t - 1, before month t’s new business, which is
pols_if_init() at t_entry(); BEF_DECR adds pols_new_biz() and
therefore equals pols_if() itself; BEF_MORT is the same (this product has no
annuitization decrement); BEF_LAPSE is after that month’s deaths; and AFT_DECR
is the closing count, which is also pols_if_at(t + 1, BEF_NB) in every month but
the last covered one. Both decrements are the monthly rates. BEF_NB is the one
timing running in force adds; basiclife.BasicTerm_SE’s "BEF_MAT" is not adopted,
since the survivors leave at the end of the last covered month, as the S goldens have it.
Benefit kind arguments are DEATH, LAPSE and MATURITY, and ALL for the
total of claims() and claims_over_av(). Any other value of any of these raises
ValueError.
The four phases, and why the cause of depletion matters
ACCUM is deferral. INCOME starts at the first lifetime withdrawal and lasts while
an account value remains. DEPLETED is what the product is sold for: the account value
is gone, the insurer pays LW from its own funds for the rest of the covered life, no
rider charge is deducted, no index credit is computed, the surrender value and the death
benefit are zero, and lapse is impossible, so lapse_rate() returns zero and
l(t+1) = l(t)(1 - q_m(t)). TERMINATED is the same exhaustion with the guarantee
destroyed — reached when the account value is driven to zero by an excess withdrawal, a
surrender charge or a negative MVA rather than by guaranteed withdrawals and rider charges
[S1][S5][S9]. depletion_cause() carries the attribution and is evaluated before
the depletion test, exactly as the notes require. A model testing only AV <= 0 would
either give the guarantee away after an excess withdrawal or destroy it after a legitimate
one. When the contract terminates, the survivors leave as a deemed full surrender —
lapse_rate() returns 1.0 for that contract year, and lapse_rate_mth() puts the
whole of it in the anniversary month rather than spreading it, because the contract “as
well as the rider will be considered Surrendered” [S5] on that date — so the in-force
roll-forward still closes.
The transition itself is annual and is tested only at the anniversary, which costs nothing:
the account value can reach zero only where a withdrawal or a charge is taken, and both
fall there. Between anniversaries phase() simply carries phase_open().
Each phase is an int code, named by a Reference of the phase’s name: ACCUM 1,
INCOME 2, DEPLETED 3 and TERMINATED 4, so that every comparison of a phase is
a comparison of numbers. Two more codes answer outside cover: PRE_ISSUE 0 before
issue and MATURED 5 from proj_len() on, which no cell in cover reads.
result_glwb(), a report, decodes the codes back into the labels, and the model point
carries the phase at the anniversary on or before the valuation date as its code,
phase_prev_anniv_init(). Data refuses TERMINATED in force, a deemed
surrender of every contract.
The asymmetry reaches the cash, not only the phase label. On the exhaustion
anniversary itself the withdrawal requested exceeds what the account value can meet. In
DEPLETED the insurer funds the whole shortfall, because that is the guarantee. On the
TERMINATED branch it funds none of it: the balance is gone and the rider that would
have covered the rest is destroyed by the very withdrawal being paid, and [S5] treats the
contract as surrendered at that point. wd_unfunded_pp() is that unpayable part, and
wd_payment_pp(), wd_guar() and wd_excess() are all net of it. The cap is
on the payment only — wd_pp() still carries the amount requested, so the excess
still sets depletion_cause(), still drives rho to 1 and still takes the benefit
base to zero.
pols_maturity and the projection horizon
The technical notes state no projection horizon; the DEPLETED liability is a life
annuity, so the model runs through the final month of the contract year entered at
attained age maturity_age = 120 [std], the terminal age of the shipped mortality
table — policy month maturity_mth() = 12 * policy_term(), which is
proj_len() = maturity_mth() - duration_mth_init() months from the valuation date. The
survivors of the last covered month, duration_mth(t) = maturity_mth() - 1, which is
t = proj_len() - 1, leave through pols_maturity(), zero at every other t,
so that:
pols_if(t) - pols_if_at(t + 1, BEF_NB) = pols_death(t) + pols_lapse(t)
+ pols_maturity(t)
holds for every t — the start-of-month count opens the row, the exits are taken
during it and the next month opens on what is left, before its own new business —
including the last, where pols_if_at(proj_len(), BEF_NB) is zero. Under the shipped
table q reaches 1.000000 at age 120, hence a monthly rate of 1.0 in the first month of
that contract year, so the projection closes itself and the term is numerically zero; it
is kept because a substituted table with no terminal age would make it bite, and because
without it the last month would appear to lose lives with no cause. The name follows
BasicTerm_S.pols_maturity and the construction follows Term_US_S.
Codes
What FIA_US_S spells as text, a timing, a kind, a scenario column or a switch’s
setting, is here an int Reference named as the text it replaces, so that every cell takes
and returns C numbers. A call site reads as it did, less the quotes:
pols_if_at(t, BEF_DECR), av_pp_at(t, BEF_WD), claims(t, DEATH).
Reference |
Value |
Meaning |
|---|---|---|
BEF_NB |
0 |
|
BEF_DECR |
1 |
|
BEF_MORT |
2 |
|
BEF_LAPSE |
3 |
|
AFT_DECR |
4 |
|
BEF_PREM |
5 |
the account value cells: before the single premium |
BEF_INV |
6 |
the account value cells: after it, before the month’s interest |
BEF_FEE |
7 |
the account value cells: after the interest, before the fee |
BEF_WD |
8 |
the account value, benefit base and withdrawal cells: before the withdrawal |
EOY |
9 |
the same cells: closing the month |
BEF_ROLLUP |
10 |
|
BEF_STEP_UP |
11 |
|
DEATH |
0 |
the claim cells: the death claim |
LAPSE |
1 |
the claim cells: the surrender claim |
MATURITY |
2 |
the claim cells: the survivors at the horizon |
ALL |
3 |
|
INDEX_LEVEL |
0 |
|
MVA_REF_YIELD |
1 |
|
ANNUAL |
0 |
|
AT_EXERCISE |
1 |
|
PRO_RATA |
0 |
|
DOLLAR |
1 |
|
GROSS |
0 |
|
SURRENDER_VALUE |
1 |
|
The model has three families of timing, the count’s, the account value’s and the benefit
base’s, passed to different cells, and they are numbered as one: BEF_NB 0 and
BEF_DECR 1, as in every SEC model, then the count’s others, then the account value’s,
then the benefit base’s own two, each family in the order of its instants. The benefit
base and the lifetime withdrawal share BEF_WD and EOY with the account value,
where FIA_US_S spells them alike, so each is one Reference. BEF_MORT keeps a
code of its own, though pols_if_at() reads it at BEF_DECR’s instant, so that
each string is one code. So a code of one family passed to another’s cell,
av_pp_at(t, BEF_NB), is refused as any timing the cell does not take is,
ValueError("invalid timing"), in both engines, rather than read as a timing of the
cell’s own. Kinds are numbered in result_cf’s order, which is the order
FIA_US_S adds them in its total, and ALL, its kind=None, after them; the
claim cells but claims() and claims_over_av() refuse it, ValueError("invalid
kind"), claim_pp() outside a DEPLETED month, where it answers 0.0 before it
reads the kind, as FIA_US_S’s does. A code a cell takes indexes that cell’s cache,
a C array of twelve codes a month for each of the thirteen cells that take a timing or a
kind, and twelve an anniversary for scenario_value(), since every 2-D cache of the
model has one width (spec_sec.py), so codes are numbered densely from 0, and a code a
cell does not take but below 12 is refused inside the cache. The three switches,
step_up_mode, rb_wd_convention and mva_collar_basis, hold a code, ANNUAL,
PRO_RATA and GROSS as shipped, and are read through their decodes; a text set on
one is no code, and the cell that asks raises FIA_US_S’s message, invalid
step_up_mode among them. Codes are References, not cells, so the symbol map does not
list them. Every other Reference is named in lower case, issue_age_min and
issue_age_max among them, the product’s issue ages, 40 and 80, the first of which,
with maturity_age, the compiled model’s caches are sized from (proj_len()).
Reporting cells
model_point(), the label accessors policy_id(), sex(),
tax_status(), glwb_basis(), credit_method(), rollup_id(),
scenario_id() and wd_schedule_id(), the reports result_cf(),
result_pols(), result_av(), result_glwb() and result_cf_annual(),
and the checks check_av_roll_fwd() and check_pols_roll_fwd() are written for a
reader and for the comparison with FIA_US_S, which has every one of them: a table
row, text, DataFrames and two verdicts. No other cell calls them: each reads the number
Data decoded from the same column instead, the decodes’ flags and the rows the keys
select. So the row, the text and the frames stay Python when the model compiles. A label
accessor returns its column as read, text or not: Data accepts, and the model
projects, a point whose policy_id or tax_status is blank or a number, which no
cell reads, whose glwb_basis or credit_method is, which its decodes answer False
to, or whose sex, rollup_id, scenario_id or wd_schedule_id is a number,
where its table’s keys are numbers, and the compiled accessor returns what modelx
returns, NaN or an int. Every other cell returns a C bint, long long or
double, and so do the two checks, which may stay Python but compile to a bint,
their verdict, as their per-month residuals, *_resid, compile to a double.
Four cells of float or text parameters compile with C signatures and dict caches, their
bodies Python, the engine cells credit_rate_on(), payout_rate(),
mgsv_rate_statutory() and mgsv_rate_is_compliant(): FIA_US_S’s own,
math and its walk of the payout bands included, kept for its tests, for T1, which
compares them at the arguments FIA_US_S’s tests use, and for a reader. No
projection cell calls them, and a cell keyed by a float or a text compiles with a Python
dict for a cache, so the registry admits them by name. The three others of
FIA_US_S’s float-parameter cells, bonus_clawback_on, mva_pp_on and
wd_reduction_rate_on, which the projection does call, are written inline in the cells
that call them: wd_clawback_pp() and surr_clawback_pp(), wd_mva_pp()
and mva_pp(), and wd_reduction_rate().
Cells Descriptions#
- model_point()[source]#
The selected model point, its row of
model_point_table_sec.csv, as a Series.Row
idxof the table, for a reader who wants every column at once: a reporting cell (the Space docstring’s Reporting cells), which no projection cell reads. Each accessor reads its ownDatavector instead.
- point_id()[source]#
The label of the selected model point, its
point_id, fromData.point_id.Projectionis indexed by position,idx, asbasiclife.BasicTerm_SCis; the label is what a reader finds in the table, so every refusal names it.
- age_at_entry()[source]#
x: the issue age (ANB) of the selected model point.
The age at issue, not at the valuation date:
age(0)is the attained age then.
- mort_schedule()[source]#
The number
Datagives the point’ssex, by which its table is read.The row of
Data.mort_table_array. The join on the text key, made once inData(R7), whereFIA_US_S’s reader selects its rows by the key itself:mort_rate_base_at()reads the table at this number, so no projection cell compares the key or calls the label accessor.
- tax_status()[source]#
Tax status of the contract, NQ or Q.
Reported only. The base run is non-qualified [std]; no RMD module is implemented, though the notes make the RMD age a behavioural input through
activation_rate()and thermd_ageReference.
P: the single premium per contract.
- policy_count()[source]#
The number of contracts the model point stands for, its
policy_countcolumn.A point in force at the valuation date counts the contracts in force then, before any month-0 event; any other point counts the contracts it issues. Either way the count enters the projection once: as
pols_if_init()for the first, aspols_new_biz()in the issue month for the second. Every per-contract value — the account value, the benefit base, the lifetime withdrawal, the floor, the opening state — is the same whatever the count, and every cash flow is a per-contract amount weighted by it.FIA_US_S’spols_if_initcolumn, renamed, asbasiclife.BasicTerm_SEnames it.
- pols_if_init()[source]#
l(0): contracts in force at the valuation date, before any month-0 event.
policy_count()for a point already in force att = 0(duration_mth_init() > 0), and 0 for one issued at or after it, whose contracts enter throughpols_new_biz()in the issue month instead, as inbasiclife.BasicTerm_SE. So on a point issued att = 0this is 0, andpols_if(0)is the issued count.FIA_US_S’s cell of the name is the count at its entry, 1 for a single-contract model point, whether entered at issue or in force.
- alloc_indexed()[source]#
The share of the account value allocated to the indexed account; 100% [std].
- glwb_basis()[source]#
singleorjoint.The joint column of the payout table is the single column less 0.50%, read on the younger covered person [S1][S3]. Joint-life survivorship is not implemented: the notes specify the joint payout percentage but no second-life mortality basis.
A label for reporting: the projection reads the basis through its decodes,
is_single_basis()andis_joint_basis(), and no projection cell calls this.
- is_single_basis()[source]#
Whether the rider is on the single-life basis,
glwb_basissingle.A decode of the model point’s column, made in
Data(Data.is_single_basis), as eachis_*cell of a column is, so that the projection branches on a flag and no projection cell compares the column’s text or calls the label accessor,glwb_basis(), which is left to reporting.payout_rate_at()reads it, for the single-life column of the payout bands.
- is_joint_basis()[source]#
Whether the rider is on the joint-life basis,
glwb_basisjoint.The other decode of the column (
is_single_basis()).covered_age()reads it, for the younger covered life, andpayout_rate_at()for the joint column. A basis that is neither is read as single bycovered_age()and raises inpayout_rate_at(), asFIA_US_Sanswers it in itscovered_ageand itspayout_rate().
- joint_age()[source]#
The issue age (ANB) of the joint covered person; the annuitant’s own if blank.
Decoded in
Data(Data.joint_age), element by element, byFIA_US_S’s rule: a blank readsage_at_entry().
- income_start_age()[source]#
The attained age at which the base run takes its first lifetime withdrawal.
The deterministic run activates here rather than on the
h(a)incidence table, which the notes say clusters at the RMD age but which cannot be applied to a single deterministic cell; seeactivation_rate().
- utilization_intensity()[source]#
The fraction of
LWactually withdrawn once income starts.1.00 in the base run [std]; the majority of users withdraw 95%-105% of the maximum [R1]. The 1.05 case is an excess withdrawal and routes through the proportional reduction of step 5, which is why efficiency and excess-withdrawal assumptions cannot be set independently.
- credit_method()[source]#
The crediting method:
cap,par,par_cap,spreadortrigger.All five are implemented in
credit_rate(), which branches on the decodesis_credit_cap()tois_credit_trigger(), and incredit_rate_on(), the engineFIA_US_Scalls, kept for its tests. This accessor is a label for reporting: no projection cell calls it. The notes’ sixth variant, monthly sum with a monthly cap, is not implemented: it needs a monthly grid, which the notes exclude, and its floor convention is itself flagged as ambiguous [S4][R1].
- is_credit_cap()[source]#
Whether the indexed account credits
max(f, min(c, R)),credit_methodcap.A decode of the model point’s column, made in
Data(Data.is_credit_cap), as eachis_*cell of a column is, so thatcredit_rate()branches on flags and no projection cell compares the column’s text or callscredit_method(), which is left to reporting. The composite’s baseline [S2][S4][S10][R1].
- is_credit_par()[source]#
Whether the indexed account credits
max(f, p x R),credit_methodpar.A decode of the column, as
is_credit_cap()is [S4][S10][R1].
- is_credit_par_cap()[source]#
Whether the account credits
max(f, min(c, p x R)),credit_methodpar_cap.A decode of the column, as
is_credit_cap()is; [R1]’s worked case.
- is_credit_spread()[source]#
Whether the account credits
max(f, p x R - s),credit_methodspread.A decode of the column, as
is_credit_cap()is; the index-margin form [R1][S8].
- is_credit_trigger()[source]#
Whether the account credits
dwhenR >= 0andfotherwise,trigger.The last decode of
credit_method, asis_credit_cap()is: a method that is none of the five raises incredit_rate(), asFIA_US_S’scredit_rate_on()raises.
- cap_rate()[source]#
c: the declared annual cap, 5.25% [S2].
A non-guaranteed element captured as of 07/01/2022, revisable under ASOP No. 2 [R6][REG-R26]. Holding it constant for forty years is a strong implicit assumption; re-declaration against the option budget is not implemented because the notes give the target but no option-pricing function.
- stack_factor()[source]#
m: the stacking factor on realised dollar credits, 150% [S8][S9].
Zero gives the pure-rollup design (a); with
rollup_ratezero it gives the pure stacking design (b), where one carrier’s 250% election credits 250% to the benefit base [S3][S4].
- av_int_factor()[source]#
kappa: the share of the index credit that reaches the account value [S3][S4].
1.00 on the blended baseline. 0.50 is the 250% election documented at one carrier, which credits 250% of index interest to the benefit base but only 50% to the account value, deliberately starving the account value. The stacking factor
mapplies to the gross index credit, not tokappa x IC.
- rollup_number()[source]#
The number
Datagives the point’srollup_id, by which its table is read.The row of
Data.rollup_rate_array. The join on the text key, made once inData(R7), whereFIA_US_S’s reader selects its rows by the key itself:rollup_rate_py()reads the table at this number, so no projection cell compares the key or calls the label accessor.
- scenario_id()[source]#
The index and reference-yield scenario, a key into rate_scenario_sec.csv.
The row’s own copy of a
FIA_US_Sscenario on the valuation clock:FIA_US_S’s id on a contract issued at the valuation date,{id}-M{d}on one valued in force at policy monthdand{id}-F{k}on one issuedkmonths after the valuation date (Data.rate_scenario). A label for reporting:scenario_value(), the scenario’s one reader, reads the scenario atscenario_number(), the numberDatajoins the column to, and no projection cell calls this.
- scenario_number()[source]#
The number
Datagives the point’sscenario_id, by which its table is read.The row of
Data.index_level_arrayandData.mva_ref_yield_array. The join on the text key, made once inData(R7), whereFIA_US_S’s reader selects its rows by the key itself:scenario_value()reads the table at this number, so no projection cell compares the key or calls the label accessor.
- wd_schedule_number()[source]#
The number
Datagives the point’swd_schedule_id, by which its table is read.The row of
Data.wd_amount_array. The join on the text key, made once inData(R7), whereFIA_US_S’s reader selects its rows by the key itself:wd_scheduled_at()reads the table at this number, so no projection cell compares the key or calls the label accessor.
- av_pp_init()[source]#
AV entering month 0: the account value of a contract in force at the valuation date.
The model point’s
av_pp_initcolumn,FIA_US_S’sav_initial, per contract, at the start of month 0, before any month-0 event; 0 on a contract issued at or after the valuation date, which opens with no account value.FIA_US_S’s cell computes the issue valueP x (1 + b)[S5] when its column is blank; here that rule credits the issue month, throughprem_to_av_pp(). The bonus is credited to the account value at issue and earns index credits from day one [S5]; it does not enter the benefit base [S9] or the nonforfeiture base [S10].
- av_fixed_pp_init()[source]#
F entering month 0: the fixed account within
av_pp_init(), a column of its own.The model point’s
av_fixed_pp_initcolumn, per contract; 0 on a contract issued at or after the valuation date, whose fixed share of the premium and bonus,alloc_fixed() x P x (1 + b), is credited in the issue month.FIA_US_Sderives the fixed account at entry asalloc_fixed() x AV, the split at issue, which holds at issue only: the fixed account accrues its own interest month by month and takes the rider charge first, so after issue the two accounts drift from that split, and a contract re-entered in force from its own state needs the fixed account it actually holds.
- av_pp_prev_anniv_init()[source]#
AV(0) of the year under way: the account value at the anniversary on or before the valuation date.
The model point’s
av_pp_prev_anniv_initcolumn, per contract: the account value at the anniversary that opened the contract year under way at the valuation date, the base of that year’s index credit, through its indexed part, and of its free withdrawal allowance.av_pp_year_open()reads it wherever the year under way opened before the first month on the books, on a contract valued in force, mid-year or on its anniversary. On a contract valued on an anniversary the two instants are one, andDataholds it equal toav_pp_init(); in the first policy year it is the issue value,P x (1 + b), whichDataholds to a cent. 0 on a contract not yet in force.
- av_fixed_pp_prev_anniv_init()[source]#
F(0) of the year under way: the fixed account at the anniversary on or before the valuation date.
The model point’s
av_fixed_pp_prev_anniv_initcolumn, per contract, read byav_fixed_pp_year_open()asav_pp_prev_anniv_init()is byav_pp_year_open(): the base of the year’s annual fixed interest, which the stack reads, and the part of the account value outside the year’s index segment.Dataholds it equal toav_fixed_pp_init()on an anniversary, to the issue value’s fixed share in the first policy year, and, off an anniversary, the indexed account,av_pp_init - av_fixed_pp_init, equal to its value at the anniversary, since that account moves only there. 0 on a contract not yet in force.
- benefit_base_pp_init()[source]#
BB entering month 0: the benefit base of a contract in force at the valuation date.
The model point’s
benefit_base_pp_initcolumn,FIA_US_S’sbb_initial, per contract. The base is flat between anniversaries, so it is also the base at the anniversary on or before the valuation date, which that year’s rollup and stack build on and its rider charge is taken on. 0 without the rider, and 0 on a contract issued at or after the valuation date, whose issue base,P— the bonus stays out [S9] — opens its first contract year inbenefit_base_pp_at().
- rollup_base_pp_init()[source]#
RB entering month 0: the rollup base of a contract in force at the valuation date.
The model point’s
rollup_base_pp_initcolumn,FIA_US_S’srb_initial, per contract, flat between anniversaries like the benefit base, so it is also the base the year’s rollup is computed on. 0 without the rider, and 0 on a contract issued at or after the valuation date, whose issue value,Punder the rider [S2][S9], opens its first contract year inrollup_base_pp_year_open().
- mgsv_pp_init()[source]#
MGV entering month 0: the Model #805 floor of a contract in force.
The model point’s
mgsv_pp_initcolumn,FIA_US_S’smgv_initial, per contract; 0 on a contract issued at or after the valuation date.FIA_US_S’s cell computes the issue value, 87.5% of the single premium excluding the bonus [S10][R2], when its column is blank; here that rule credits the issue month, throughprem_to_mgsv_pp(). The worked example’s93,811.84 = 87,500 x 1.01^7is that value rolled forward seven years.
- lw_pp_init()[source]#
LW entering month 0: the lifetime withdrawal amount of a contract in force.
The model point’s
lw_pp_initcolumn,FIA_US_S’slw_initial, per contract, 0 before exercise. Flat between anniversaries, so it is also the amount set at the anniversary on or before the valuation date, the income in force, whichlw_pp_at()carries until the next anniversary. 0 on a contract issued at or after the valuation date.
- payout_rate_locked_prev_anniv_init()[source]#
The payout percentage locked at the anniversary on or before the valuation date.
The model point’s column,
FIA_US_S’spayout_rate_initial: the percentage locked at the first lifetime withdrawal, 0 before it, whichpayout_rate_locked()carries where the contract year under way opened before the valuation date.Dataholds it to 0 inACCUM, and inINCOMEandDEPLETEDto 0 exactly wherelw_pp_init()is 0: a contract that exercised below the first age band, or in a band at 0%, locked 0. 0 on a contract not yet in force.
- phase_prev_anniv_init()[source]#
The phase at the anniversary on or before the valuation date, as a code.
The model point’s column,
FIA_US_S’sphase_initialas an int: 1ACCUM, 2INCOMEor 3DEPLETEDon a contract in force, 0 on one not yet in force.TERMINATED, 4, is a deemed surrender of every contract, soDatarefuses it in force.phase_year_open()reads it where the contract year under way opened before the valuation date: the phase that year’s annual steps are processed under, unless the year is the exercise year.FIA_US_Sreads its column as text.
- index_level_prev_anniv_init()[source]#
I(y) of the year under way: the index level at the anniversary on or before the valuation date.
The model point’s column: the level at which the contract year’s index segment started, the base of its point-to-point credit. Once that anniversary precedes the valuation date it is history, which the scenario, on the valuation clock, cannot give, so
index_level()reads it for that anniversary alone, on a contract valued mid-year. On a contract valued on an anniversary the scenario sets the level att = 0, andDataholds this equal to it. 0 on a contract not yet in force.
- wd_cum_pp_init()[source]#
Wcum entering month 0: the gross withdrawals from issue to the valuation date.
The model point’s column, per contract, which
wd_cum_pp()opens on. 0 on a contract not yet in force, and in the first policy year, before the first anniversary’s withdrawal.FIA_US_Scounts its running total from the month it enters a contract, from 0.
- policy_term()[source]#
Contract term in years [std]: through the year entered at
maturity_age.maturity_age= 120 is the terminal age of the mortality basis, where the annual rate is 1.000000, so the projection closes itself rather than being truncated: the last contract year is the one entered at that age, hence the+ 1. The notes state no horizon, and theDEPLETEDliability is a life annuity, so stopping earlier would silently drop the tail the product is sold for.
- maturity_mth()[source]#
The policy month at which cover ends:
12 * policy_term().The first policy month past the contract year entered at attained age
maturity_age= 120 [std], so the last covered month ismaturity_mth() - 1, 707 at issue age 62. It isFIA_US_S’sproj_len(), its frame from issue on the policy clock;proj_len()counts from the valuation date instead.
- proj_len()[source]#
The number of months from the valuation date to the end of cover.
maturity_mth() - duration_mth_init(): 708 for a contract issued att = 0at issue age 62, 624 for the anchor in force at anniversary 7, 12 for a contract valued in its last policy year, at policy month 696, and 723 for one to be issued 15 months after the valuation date. The frame ist = 0, 1, ..., proj_len() - 1;proj_len()is its exclusive end and the row count ofresult_cf(), andproj_len() - 1is the last covered month.It refuses, naming the point, in this order: a point issued below
issue_age_min, 40, the youngest issue age of the product, from which the compiled model’s caches are sized (spec_sec.py); one issued aboveissue_age_max, 80, the oldest, which sizes nothing but is the product’s; a point whose cover from issue is empty, issued pastmaturity_age, which would otherwise project a frame of zeros and never be issued, and which the ages refuse first unlessissue_age_maxis raised past it; a point at or past maturity at the valuation date, which has no frame and would otherwise project nothing: an in-force extract should not carry it; and a point whose sex’s mortality stops belowmaturity_age, the age the last contract year is entered at and the lastmort_rate_base_at()reads (Data.mort_age_lasts), sinceData, which checks the age of the point’s first month on the books, cannot readmaturity_age. Each bound is a Reference, set before the model computes anything.
- policy_year(t)[source]#
The contract year month
tfalls in:duration(t) + 1, the 1-based label.Derived from
duration_mth(t), the policy clock, never indexed by; it is 0 or less before issue, where every reader is guarded byis_active(). It is the key that reads the surrender charge, the vesting vector and the rollup schedule, all of which the sources state by contract year, and it is the year whose annual decrement ratesmort_rate()andlapse_rate()return.
- duration_mth_init()[source]#
Completed policy months at the valuation date, the
duration_mthcolumn.The contract’s age in months at
t = 0: 84 for the anchor in force at anniversary 7, 95 for it valued in the last month of contract year 8, 0 for a contract issued at the valuation date, and -15 for one to be issued 15 months after it, whichDataadmits up tofuture_horizon_mthmonths ahead. It is read asbasiclife.BasicTerm_SEreads it, as a whole number whatever the column’s type, and is the one fact the policy clock takes from the model point. It replacesFIA_US_S’sentry_year, a count of whole years, which is whyFIA_US_Scan enter a contract in force on an anniversary only.
- duration_mth(t)[source]#
Completed policy months at the start of month
t, the policy clock.duration_mth_init() + t:tcounts months from the valuation date andduration_mth(t)months from issue, and the two move together. A closed form, wherebasiclife.BasicTerm_SEadds one a month by recursion: the same numbers, without a call chain as long as the frame. Negative before issue. It isFIA_US_S’st, the notes’ month index, and everything contractual reads it, throughduration(),policy_year(),is_anniv()andage().FIA_US_Senters a contract in force by opening its frame late, at the policy month it has reached; here the frame opens at the valuation date and the policy clock starts where the contract stands.
- t_entry()[source]#
The first month the contract is on the books:
max(0, -duration_mth_init()).0 for a point in force at the valuation date or issued at it,
kfor one issuedkmonths later. It is the base of every recursion:pols_if_at()opens there frompols_if_init(); the account value, the fixed account, the Model #805 floor and the withdrawals to date from the model point’s opening state; and the state of the year — the benefit base, the rollup base, the lifetime withdrawal, the phase, the locked percentage and the rider — reads the anniversary that opened the year from the frame only where that anniversary is at or after it, and from the opening state, or by the issue rule, where it is not. No cell in cover reads a month before it.
- is_active(t)[source]#
Whether month
tis inside cover: issued, and not past the last covered month.0 <= duration_mth(t) < maturity_mth(). False before issue and fromproj_len()on. Outside cover every count is zero, and so every cash flow; so is every value state and every contractual rate, every flag isFalse, the phase isPRE_ISSUEorMATURED, no count cell evaluates a rate there, and no table is read at a contract year or an attained age the contract does not have.
- duration(t)[source]#
Completed contract years at the start of month
t,duration_mth(t) // 12.Every contractual schedule in this product is annual, so this is what the attained age, the surrender charge, the vesting vector, the rollup schedule and the scenario tables are read at.
- is_anniv(t)[source]#
True in the last month of a contract year, where every annual event lands.
duration_mth(t) % 12 == 11. All eight of the notes’ processing steps are contractually annual — the point-to-point index credit [S2][S4][S10], the rider charge [S9], the benefit base rollup, stack and step-up [S9], the lifetime withdrawal, the charges and the phase transition — so all eight happen here and nowhere else. What the finer grid carries between anniversaries is the fixed-account accrual, the Model #805 roll, the decrements and the maintenance expense.
- anniv_mth(t)[source]#
The month that closes the contract year of month
t, on the valuation clock.t + 11 - duration_mth(t) % 12: the month of the frame whose policy month is the year’s last,12 * duration(t) + 11, which isFIA_US_S’sanniv_mthand itst; here the two clocks differ, so the month is counted fromt. Equal totitself whenis_anniv()is true. It is where the annual quantities of that contract year are evaluated — which is what makeslapse_rate()a property of the year rather than of the month — and it lies at most 11 months aftert, inside the frame, since cover ends at the close of a contract year.
- year_open_mth(t)[source]#
The month whose closing value opens the contract year of month
t.t - 1 - duration_mth(t) % 12, on the valuation clock: the anniversary month that closed the previous contract year, policy month12 * duration(t) - 1, which isFIA_US_S’syear_open_mth. It falls belowt_entry()in the first contract year on the books — att = -1or earlier on a contract valued in force, mid-year or on its anniversary, and before issue on new business — where the opening state stands in, the model point’s_prev_anniv_initor_initcolumn or the issue rule: which is the test every annual state cell makes.
- age(t)[source]#
x + duration(t): the attained age (ANB) opening the contract year of month t.
The library convention of
Term_US_SandMYGA_US_S, somort_rate()reads this age directly for the contract year of mortality it covers. Age changes on the anniversary, not on the birthday and not monthly. The transactions of that contract year fall at its closing anniversary and are one year older: that age isexercise_age(), which is what reads the lifetime withdrawal percentage table.
- covered_age(t)[source]#
The attained age of the covered life opening the contract year of month t.
The annuitant’s own age on a single-life basis; the younger covered person’s on a joint-life basis [S1][S3]. Timed like
age(), at the opening anniversary; the payout percentage and the minimum exercise age are read atexercise_age().It branches on
is_joint_basis(), the decode ofglwb_basis.
- exercise_age(t)[source]#
covered_age(t) + 1: the covered age at the anniversary closing the contract year.All transactions occur at the anniversary and are processed as the last events of the contract year ending there [std], so a lifetime withdrawal taken in the contract year of month
tis taken one year older than the age opening it. This is the age that reads the payout percentage band and that clears the contractual minimum exercise age of 50: the anchor cell’s exercise in contract year 8, from issue age 62, is at attained age 70 and reads the 70-79 band.
- scenario_value(y, name)[source]#
The level of column
namethe model point’s scenario sets at anniversaryy.The argument is an anniversary number, from issue, not a month. Callers pass
duration(t)for the anniversary opening the contract year of monthtandduration(t) + 1for the one closing it, as inFIA_US_S. The scenario is on the valuation clock (Data.rate_scenario), so the anniversary is turned into the valuation month it falls in,m = 12 * y - duration_mth_init(), here and nowhere else, and the level is the last row of the point’s scenario at or beforem: each row holds from its month until the next row of the same scenario, so a flat path is one row.Dataholds the scenarios step-filled by valuation month,index_level_arrayandmva_ref_yield_array, at the rowscenario_number()gives the point’sscenario_id, andnameis the column’s code,INDEX_LEVELorMVA_REF_YIELD; any other raisesValueError("invalid name").The arrays hold every month to
Data.read_last_mth, 1,093, the last a read reaches, the last row of a scenario holding to there; a month past it, which no projection reads, raises, naming the point, rather than reading a row the array does not hold.FIA_US_Sreads an anniversary before the scenario’s first row at the first row’s level. Here a month with no row at or before it raises, naming the point (Data.scenario_first_mths):Datarefuses a point whose scenario sets no level by its first month on the books, and no cell asks for an anniversary before that month —index_level()reads the one before the valuation date from the model point — so the raise is the guard behind that refusal.
- index_level(y)[source]#
I(y): the index level at anniversary
y, an anniversary number from issue.Keyed by anniversary number, not by a month — a time-point reading, so the return over a contract year differences this level against the next anniversary’s. The S&P 500 price index in the composite; dividends are excluded [S2][S6][R1].
An anniversary at or after the first month the contract is on the books is read from the scenario,
scenario_value(). One before it, on a contract valued mid-year, is the anniversary that opened the contract year under way, whose level is history the scenario on the valuation clock cannot give: the model point’sindex_level_prev_anniv_init(), where the year’s segment started. On a contract valued on an anniversary the scenario sets that level att = 0, andDataholds the column to it.
- index_return(t)[source]#
R(t) = I(y+1)/I(y) - 1 with
y = duration(t): the return over the contract year.The point-to-point segment runs from the anniversary opening the contract year of month
tto the one closing it, where it matures. The return is a property of the contract year, not of the month, and is the same for every month inside it.0.0 outside cover, where no contract year is the contract’s.
- cap_rate_in_force()[source]#
c(t): the annual cap actually applied.
The declared 5.25% snapshot held level [std], never below the guaranteed minimum cap of 0.25% [S4]. Set
use_guaranteed_scale = True, before the model computes anything, to run the contract on its guaranteed minimums instead — the notes insist the guaranteed and current scales are different assumption classes and “must not be mixed in the code”.
- fixed_rate_in_force()[source]#
i_F: the fixed account rate applied, 2.30% declared over a 1.00% guarantee.
Declared [S2] and guaranteed minimum [S10];
use_guaranteed_scaleswitches to the guarantee, as for the cap.
- credit_rate_on(r, method)[source]#
cr: the credit rate for an index return
rundermethod.The engine the notes require, all branches floored at
f= 0%:cap[std]max(f, min(c, R))[S2][S4][S10][R1] — the composite’s baseline.parmax(f, p x R)[S4][S10][R1].par_capmax(f, min(c, p x R)), worked at [R1] asmin(80% x 10%, 6%) = 6%— which is wherepar_rate= 80% comes from, and the casetest_crediting_engine_reproduces_the_R1_worked_caseasserts.spreadmax(f, p x R - s), the spread form [R1]; one carrier names its methods “with Index Margin” [S8].triggerd x 1{R >= 0}, a declared rate credited whenever the return is non-negative [R1]; the floor applies when it is not.
The notes declare the two levels these last branches need nowhere, so both are [std]. They print the forms —
san index margin,da performance-trigger rate — and neithertechnical-notes.mdnorproduct-spec.mdstates a value for either, unlike the cap (5.25% [S2]) and the participation rate (80% [R1]). The shippedspread_rate= 2.00% [std] andtrigger_rate= 4.50% [std] are illustrative levels chosen only to exercise the branch, and must not be read as sourced parameters of the composite.index_cost_rateis deducted fromRbefore any cap or participation rate, which is where a volatility-controlled index’s embedded servicing cost belongs [S2][S10]; it is 0 in the base run [std]. The monthly-sum method is not implemented — seecredit_method().Kept as
FIA_US_S’s engine, for its tests and its own callers: no projection cell calls it.credit_rate()computes the same arithmetic inline, in the same order, on the decodes ofcredit_method, so that no projection cell passes a float or a text argument to a cell. An engine cell (the Space docstring’s Reporting cells): compiled, it keeps a Python dict for a cache and typesmethodasstr, so amethodthat is not text raisesTypeErrorthere, where modelx raisesinvalid credit_method.
- credit_rate(t)[source]#
cr(t): the credit rate the segment of month t’s contract year matures at.
A property of the contract year, like
index_return(); it is applied once, at the anniversary where the segment matures.FIA_US_S’s engine,credit_rate_on(), computed inline here, in its order, on the decodesis_credit_cap()tois_credit_trigger()rather than on the text ofcredit_method:max(f, raw), whererawis the method’s form of the return net ofindex_cost_rate, each documented atcredit_rate_on(). A method that is none of the five raises, as inFIA_US_S. 0.0 outside cover.
- index_credit_pp(t)[source]#
IC(t) = A(0) x cr(t): the index credit on the segment maturing at month t.
One annual segment per indexed account, created at the anniversary opening the contract year with the balance opening it and maturing at the anniversary closing it; the credit locks at maturity and cannot be lost to later declines [S1], and it is not earned before then — which is why this is zero in every month but the anniversary, and why the indexed balance is flat between anniversaries. That is the sourced rule “withdrawals are not credited with index interest in the year they are taken” [S1], carried to mid-year deaths and surrenders [std]; crediting a part year would be the daily interim value variant the notes exclude.
The credit base is the segment’s opening balance less withdrawals from that account during the segment — the “Interest Credit Basis” [S6] — which collapses to the opening balance here because every transaction happens at an anniversary [std]. Zero in
DEPLETEDandTERMINATED, where steps 1-3 are skipped.Zero outside cover.
- fixed_interest_pp(t)[source]#
FI(t): interest credited to the fixed account in month t.
The declared rate is an annual effective one, so the month accrues at
(1 + i_F)^(1/12) - 1and twelve of them compound back to exactlyi_F— nothing else touches the fixed account between anniversaries, because every contractual transaction falls at one.fixed_interest_ann_pp()is the annual figure the benefit-base stack is computed on.Zero outside cover, and once the account value is exhausted, in
DEPLETEDandTERMINATED. A rate in force below -1,fixed_rate_minset below -100% (withfixed_rate, or under the guaranteed scale), raises, naming the point: its power has a negative base, a complex number in Python, whichFIA_US_Sprojects or refuses at the nextmax, and NaN in C. At exactly -1 the base is 0 and the account accrues nothing.
- fixed_interest_ann_pp(t)[source]#
FI over the contract year closing at the anniversary in month
t:F(0) x i_F.On the balance opening that contract year. The twelve monthly accruals of
fixed_interest_pp()compound to exactly this, so the annual figure is computed directly rather than accumulated — which is what keeps the benefit-base stack, and through it the whole guarantee, identical to the annual grid’s.Zero outside cover.
- inv_income_pp(t)[source]#
Interest credited to one contract’s account value in month t.
kappa x IC(t) + FI(t): the fixed accrual every month, and the index credit only in the anniversary month where the segment matures.kappastarves the account value in the pure-stacking design [S3]; the benefit-base stack instack_pp()uses the gross index credit, which is the whole point of that design.
- rider_charge_pp(t)[source]#
Phi(t) = phi x BB(0): the GLWB rider charge, deducted once a year [S9].
On the benefit base, not the account value, and taken after index credits are added — the notes’ ordering, which is why the base in the formula is the opening base. In the worked example the base closes at 1.59 times the account value, so charging on the account value would understate the deduction by a growing margin. Deducted from the fixed account first and then proportionately across indexed accounts [S9].
phiis fixed for fifteen contract years and never exceeds 1.50% [S9]; re-declaration after that is not implemented. Once the account value is exhausted the charge stops — there is nothing to deduct it from and income continues [S9].The charge is annual by contract [S9], so on the monthly grid it lands whole on the anniversary rather than being spread over the year; the monthly deduction documented at one carrier is a variant this composite does not adopt [std].
Zero outside cover.
- av_pp_at(t, timing)[source]#
AV per contract in month t, read at the point given by
timing.BEF_PREMis the balance carried into the month before the single premium:av_pp_init()att_entry(), the account value of a contract in force at the valuation date and zero on new business, andAV(t-1)after it;BEF_INVis the balance opening the month after the premium, which addsprem_to_av_pp(),P x (1 + b)in the issue month and zero in every other;BEF_FEEis after the month’s interest — the fixed accrual every month, plus the index credit in an anniversary month;BEF_WDis after the rider charge;EOYis after the withdrawal, the closing balanceav_pp(). In a month that is not an anniversary the last three coincide, at the opening balance plus the fixed accrual, because every contractual transaction falls at an anniversary.Only
EOYis floored at zero: the 0% floor is on the index credit, not on the account value [S7], soBEF_WDmay legitimately sit below the opening balance or below zero when the rider charge exceeds the credit. Flooring it would silently remove the charge drag that produces depletion.Each timing is built from the month’s opening in one formula, in
FIA_US_S’s order, so that reading any timing adds one cell to the chain beneath it; the chain itself isav_pp(), one cell a month. 0.0 outside cover, at every timing.
- av_pp(t)[source]#
AV(t): the account value per contract closing month t, after all processing.
max(0, AV(t-1) + premium + interest - rider charge - withdrawal), the steps ofav_pp_at()in its order, with the opening written inline —av_pp_init()att_entry()andav_pp(t - 1)after it — so that the account value’s chain runs one cell a month back tot_entry(), whereFIA_US_S’s runs through two, this cell andav_pp_at(). 0.0 outside cover.
- av_pp_year_open(t)[source]#
AV(0): the account value opening the contract year containing month
t.The balance the annual index credit and the free withdrawal allowance are computed on, read three ways. Where the anniversary that opened the year,
year_open_mth(), is at or aftert_entry(), it is that anniversary’s closing value, from the frame. Where it is before, on a contract in force at the valuation date, valued mid-year or on its anniversary, the year opened before the first month on the books, and it is the model point’sav_pp_prev_anniv_init(). And on a contract issued at or after the valuation date the year is its first, and it is the issue value,prem_to_av_pp()of the issue month, the notes’ Initialisation value. On an annual grid this would simply be the previous row’s close; on the monthly grid the previous month is not the previous year, which is what this cell exists to keep straight. 0.0 outside cover.
- av_fixed_pp_year_open(t)[source]#
F(0): the fixed account balance opening the contract year containing month
t.Read the three ways
av_pp_year_open()is: from the frame; from the model point’sav_fixed_pp_prev_anniv_init()where the year opened before the valuation date; or, in the first year of a contract issued at or after it, by the issue rule, the fixed share of the premium and bonus,alloc_fixed() x P x (1 + b). 0.0 outside cover.
- av_indexed_pp_year_open(t)[source]#
A(0): the indexed balance opening the contract year — the segment’s credit base.
- av_fixed_pp_at(t, timing)[source]#
F per contract in month t; see
av_pp_at()fortiming.The fixed account is the one balance that moves between anniversaries: it accrues at
(1 + i_F)^(1/12) - 1every month. The rider charge comes out of it first and only then proportionately across the indexed accounts [S9]. The notes give no allocation rule for withdrawals, so they are taken pro rata across the two accounts [std]; with the baseline 100% indexed allocation neither rule is visible.At
t_entry()the fixed account opens onav_fixed_pp_init(), the fixed account in force at the valuation date, and in the issue month the premium’s fixed share,alloc_fixed()timesprem_to_av_pp(), comes on top. Each timing is built from the month’s opening in one formula; the chain itself isav_fixed_pp(), one cell a month. 0.0 outside cover, at every timing.
- av_fixed_pp(t)[source]#
F(t): the fixed account balance per contract closing month t.
The steps of
av_fixed_pp_at()in its order: the opening written inline,av_fixed_pp(t - 1), orav_fixed_pp_init()att_entry(), plus the premium’s fixed share in the issue month; the month’s accrual; the rider charge, floored at zero; and the withdrawal’s pro rata share. So the fixed account’s chain runs one cell a month back tot_entry(). 0.0 outside cover.
- av_indexed_pp_at(t, timing)[source]#
A per contract in month t:
AV - Fat the same timing, by construction.
- av_indexed_pp(t)[source]#
A(t): the indexed account balance per contract closing month t.
Flat between anniversaries — the segment credits only at maturity — and stepped at each anniversary by that year’s index credit net of its share of the charge and the withdrawal.
- av_depletion_pp(t)[source]#
The part of month t’s withdrawal the account value could not fund.
Zero until the account value runs out, then the shortfall between the withdrawal requested and the balance available to meet it. It is the term that makes the account value roll-forward close across the depletion anniversary, where
AV(t)is floored at zero.It is not the same thing as an amount paid. Whether the shortfall is a payment depends on which exhaustion branch the anniversary closes on: in
DEPLETEDthe guarantee is alive and the insurer funds it from its own funds [S1][S3][S9][R1], on theTERMINATEDbranch there is neither balance nor promise behind it and it is not paid at all.wd_unfunded_pp()carries that half, and only that half is kept out of the ledger.Zero outside cover.
- surr_charge_rate_py(y)[source]#
sc(y): the surrender charge percentage of contract year
y[S5].9.1, 9, 8, 7, 6, 5, 4, 3, 2, 1% over the ten-year charge period and zero thereafter; the last row of the table holds for every later year. The reader of the schedule’s charge column, keyed by the contractual 1-based contract year, from
Data.surr_charge_rate_array, held by year from the checked schedule to its last year,Data.surr_charge_last_year;surr_charge_rate()calls it in cover only. A year below 1, which no projection reads, raisesValueErrornaming the point, whereFIA_US_S’s lookup raisedKeyError.
- vest_rate_py(y)[source]#
v(y): the vested percentage of the premium bonus in contract year
y[S5].0, 10, …, 100% over eleven contract years; the last row holds for every later year. The reader of the schedule’s vesting column,
Data.vest_rate_array, assurr_charge_rate_py()is of its charge;vest_rate()calls it in cover only.
- surr_charge_rate(t)[source]#
sc(t): the surrender charge percentage of month t’s contract year [S5].
9.1, 9, 8, 7, 6, 5, 4, 3, 2, 1% over the ten-year charge period and zero thereafter; the last row of the table holds for every later year. The schedule is keyed by the contractual 1-based contract year and read at
policy_year(t), throughsurr_charge_rate_py(), so the rate is the same in every month of a year. 0.0 outside cover, before the schedule is read.
- vest_rate(t)[source]#
v(t): the vested percentage of the premium bonus in month t’s contract year [S5].
0, 10, …, 100% over eleven contract years, read at
policy_year(t). On death 100% vests immediately [S5], which is why the death benefit carries no clawback.Read from
vest_rate_py(). 0.0 outside cover, before the schedule is read.
- rollup_rate_py(y)[source]#
g(y): the guaranteed simple rollup rate of contract year
y[S2][S9].The model point’s schedule read as a step function of the contract year: the rate of the schedule’s last row at or before
y, or 0 before its first. The table’s one reader, ofData.rollup_rate_array, which holds each schedule step-filled by contract year, 0.0 before its first row, at the rowrollup_number()gives the point’srollup_id;rollup_rate()calls it in cover only. A year past the array’s last,Data.rollup_last_year, which no projection reads, raises, naming the point.
- rollup_rate(t)[source]#
g(t): the guaranteed simple rollup rate of month t’s contract year [S2][S9].
Read as a step function of the contract year
policy_year(t)from the model point’s schedule: the blended baseline is 5.00% in years 1-10, 2.00% in years 11-20 and zero after [S2]; another documented design is a flat 3.00% over fifteen anniversaries [S9].Read at
policy_year(t)fromrollup_rate_py(). 0.0 outside cover.
- payout_rate(a, basis)[source]#
pi(a, basis): the lifetime withdrawal percentage at attained age
a[S3].Five inclusive attained-age bands; the joint column is the single column less 0.50% [S1][S3]. Zero below the first band, because no lifetime withdrawal is permitted there; the last band holds above its upper age.
Kept as
FIA_US_S’s cell, for its tests: no projection cell calls it, and it still walkspayout_rate_table()row by row.payout_rate_locked()readspayout_rate_at(), the same percentages from the checked bands, on the decoded basis. An engine cell (the Space docstring’s Reporting cells): compiled, it keeps a Python dict for a cache and typesbasisasstr, so abasisthat is not text raisesTypeErrorthere, where modelx raisesinvalid glwb_basis.
- payout_rate_at(a)[source]#
pi(a): the lifetime withdrawal percentage at attained age
aon the point’s basis.payout_rate()onData.payout_rate_array, the checked bands held one row an age from the first band’s age [S3]: the single-life column onis_single_basis()and the joint-life column onis_joint_basis(), a basis that is neither raising, aspayout_rate()raises; 0 below the first band’s age, because no lifetime withdrawal is permitted there; and the last band’s percentage above its last age. The table’s one reader, keyed by the age;payout_rate_locked()calls it in cover only, at the exercise age. The array holds ages toData.read_last_age, 122, past any exercise age; an age past it, which no projection reads, raises, naming the point.
- payout_rate_locked(t)[source]#
The payout percentage in force in the contract year of month t.
Locked at the attained age of the first lifetime withdrawal,
exercise_age(), and not re-read afterwards [std].is_exercise()is a property of the contract year, so the lock holds for every month of the year it is set in and is then carried from anniversary to anniversary. Documented alternatives: one carrier reads the band from the age at the most recent anniversary, letting it step up [S3]; another makes it depend on both issue age and the youngest covered person’s age at exercise [S9]; a third uses sex-distinct factors [S5].It is carried from the anniversary that opened the year: from the frame, or, where that anniversary precedes the first month on the books, from the model point’s
payout_rate_locked_prev_anniv_init()on a contract in force and 0 on new business; in the exercise year it ispayout_rate_at()the exercise age. 0.0 outside cover.
- activation_rate(a)[source]#
h(a): the GLWB activation incidence at attained age
a[std].0below 60, 5% from 60 to the RMD age, 40% at it and 15% above [R1][REG-R64].rmd_ageis a configurable Reference and must not be hard-coded: the statutory age is set by IRC 401(a)(9) as amended by SECURE 2.0 and finalized in T.D. 10001 [REG-R57][REG-R58] and is not printed in the retrieved research material.Reported only. A single deterministic cell cannot activate a fraction of itself, so the base run exercises at the model point’s
income_start_ageinstead; this cell exists so the incidence assumption is visible and testable rather than implied.
- phase_year_open(t)[source]#
The phase opening the contract year of month
t, as a code.The phase at the anniversary that opened the year, read three ways, as
av_pp_year_open()is: the closingphase()there, from the frame; the model point’sphase_prev_anniv_init()where that anniversary precedes the valuation date on a contract in force; andACCUMon a contract issued at or after it, whose first year opens in deferral.FIA_US_Swrites this read inline in each of its readers; here it is a cell of its own, read byis_exercise(),phase_open()andin_growth_period().PRE_ISSUEbefore issue andMATUREDfromproj_len()on.
- is_exercise(t)[source]#
True through the contract year whose closing anniversary carries the first LW.
Requires an in-force rider, the
ACCUMphase opening the year and anexercise_age()at or above both the contractual minimum of 50 [S2][S3][S9] and the model point’sincome_start_age. It depends only on the state opening the contract year, which is what lets the phase, the benefit base and the withdrawal be evaluated without a circular reference — and what makes it constant across the year, so every month of the exercise year reads the same phase and the same locked payout percentage.The phase opening the year is
phase_year_open(). False outside cover.
- phase_open(t)[source]#
The phase the annual steps of month t’s contract year are processed under.
The phase opening the contract year,
phase_year_open(), promoted toINCOMEwhen the first lifetime withdrawal falls in this year. Constant across the twelve months, because every one of the eight steps belongs to the year rather than to the month. Steps 1-3 are skipped when this isDEPLETEDand steps 1-7 when it isTERMINATED. A code, as every phase cell returns:PRE_ISSUEbefore issue andMATUREDfromproj_len()on, which no cell in cover reads.
- depletion_cause(t)[source]#
True when a charge, an excess withdrawal or a negative MVA touched the AV in month t.
The attribution test of step 5, evaluated before the depletion test: an account value run to zero by an excess withdrawal, a surrender charge or a market value adjustment loses the guarantee entirely, while one run to zero by guaranteed withdrawals and rider charges keeps it [S1][S5][S9]. One carrier’s confinement and terminal illness waivers are themselves excess withdrawals that terminate the income rider [S1] — a trap if waivers are added.
False outside cover.
- phase(t)[source]#
The phase closing month t, after step 7’s transition at the anniversary.
Step 7 is annual and the account value can only reach zero at an anniversary — nothing between them takes a withdrawal or a charge — so away from one this simply carries
phase_open(), and the transition is tested at the anniversary itself.ACCUM -> INCOMEat the first lifetime withdrawal;INCOME -> DEPLETEDwhen the account value reaches zero with nodepletion_cause(), which is where the economic value of the guarantee sits;INCOME -> TERMINATEDwhen it reaches zero with one; andany -> TERMINATEDwhen the benefit base reaches zero [S9]. An account value exhausted inACCUMterminates rather than depletes [std]: the notes define the depleted state only out ofINCOME, and before exercise there is noLWto pay.The phase is an int code, named by the References
ACCUMtoTERMINATED, andresult_glwb()decodes it back to the label.PRE_ISSUEbefore issue andMATUREDfromproj_len()on.
- rider_in_force_open(t)[source]#
Whether the GLWB rider is alive opening the contract year of month t.
rider_in_force()at the previous anniversary where that anniversary is at or aftert_entry(), andglwb_elected()where it is before: in the first contract year of a contract issued at or after the valuation date, and in the year under way on one in force. The model point carries no rider status, because a contract in force with the rider elected has the rider alive:DatarefusesTERMINATEDin force and a benefit base of 0 under the rider, the two ways the rider dies short of death. Kept as a cell of its own, likephase_open(), because five formulas need the opening rider state and none of them may reach for a closing one. False outside cover.
- rider_in_force(t)[source]#
Whether the GLWB rider is still alive at the end of month t [S9].
It terminates on the earliest of death of the covered person, the benefit base reduced to zero, termination of the base contract, assignment, owner cancellation on or after the earliest cancellation date, or a change in a covered person — with no refund of past charges [S9]. Death is a decrement here, and cancellation and assignment are not modelled, so what survives is the base-reaching-zero and contract-termination legs.
False outside cover.
- in_growth_period(t)[source]#
T_g: whether the benefit base still rolls up and stacks in month t’s contract year.
To the earlier of the first lifetime withdrawal and contract year 20 [S1][S2]. The year of exercise itself is still inside the window — the worked example credits both the rollup and the stack in contract year 8, the year income starts — which is why the test is on the phase opening the year.
The phase opening the year is
phase_year_open(). False outside cover.
- is_step_up_annual()[source]#
Whether the step-up is tested at every anniversary,
step_up_modeANNUAL.A decode of the Reference, an int code,
ANNUAL0 orAT_EXERCISE1, whereFIA_US_Sholds the text"annual"or"at_exercise", so thatstep_up_applies()branches on a flag and no projection cell reads text. Setstep_up_modebefore the model computes anything. A text set on it is no code: both decodes answer False, andstep_up_applies()raisesFIA_US_S’s message.
- is_step_up_at_exercise()[source]#
Whether the step-up is tested at the first exercise only,
step_up_modeAT_EXERCISE.The other decode of the Reference (
is_step_up_annual()): a mode that is neither raises instep_up_applies(), as inFIA_US_S.
- step_up_applies(t)[source]#
Whether the annual step-up
BB <- max(BB, AV)is tested at month t.Annual by construction, so it is tested only at the anniversary.
A [std] generalisation. No retrieved document describes an automatic annual ratchet during deferral; documented instead are an at-exercise step-up to the contract value [S5], an annual benefit amount computed on the greater of base and account value at exercise [S9], and a never-decreasing income amount once withdrawals begin [S3].
step_up_mode = AT_EXERCISEreduces the model to those designs;ANNUALis the superset and the baseline. Under the blended baseline it rarely binds — a dollar of credit adds $1 to the account value and $1.50 to the base — but rarely is not never: on a new issue the bonus opens contract year 1 with an account value of107,000against a benefit base of100,000, so a first contract year with a zero index credit gives an account value of106,050against a base of105,000and the step-up binds.The mode is read through its decodes,
is_step_up_annual()andis_step_up_at_exercise(), a mode that is neither raising. False outside cover.
- rollup_base_pp_year_open(t)[source]#
RB(0): the rollup base opening the contract year of month
t.Read three ways, as
av_pp_year_open()is:rollup_base_pp()at the anniversary that opened the year, from the frame; the model point’srollup_base_pp_init()where that anniversary precedes the valuation date on a contract in force, the rollup base being flat between anniversaries; and the issue value on a contract issued at or after it,Punder the rider and 0 without it [S2][S9].FIA_US_Swrites this read inline inrollup_pp()androllup_base_pp(); here it is a cell of its own, which both read. 0.0 outside cover.
- rollup_pp(t)[source]#
rollup(t) = g(t) x RB(0): the guaranteed rollup increment, once a year.
A flat dollar increment, not simple interest on the grown base. One carrier computes it on premium less withdrawals [S2] and another on the adjusted initial base [S9]; the latter’s fifteen-year table confirms a constant $3,000 a year on a $100,000 adjusted initial base [S9]. Compounding it inflates the base and every downstream charge and payment.
Computed on the rollup base opening the year,
rollup_base_pp_year_open().
- stack_pp(t)[source]#
stack(t) = m x max(0, IC(t) + FI(t)): the stacking credit at the anniversary.
On realised dollar credits [S8] [S9], net of any strategy fee (zero here) and floored at zero [S9] — one specimen’s separately named stacking credit. The gross index credit is used, so the pure stacking design can credit 250% to the base while
kappasends only 50% to the account value [S3][S4].FIhere is the annual fixed interest of the contract year,fixed_interest_ann_pp(), not the anniversary month’s own accrual.
- benefit_base_pp_at(t, timing)[source]#
BB per contract in month t, read at the point given by
timing.BEF_ROLLUPis the base opening the contract year;BEF_STEP_UPis after the rollup and the stack;BEF_WDis after the annual step-up and is the base the lifetime withdrawal is computed on;EOYis after step 5’s proportional reduction. All four steps are annual, so away from an anniversary every timing returns the opening base and the benefit base is flat.The opening base is read three ways, as
av_pp_year_open()is: the base at the previous anniversary, from the frame; the model point’sbenefit_base_pp_init(), flat since the anniversary on or before the valuation date, where the year opened before it; and the premiumP, the bonus kept out [S9], in the first year of a contract issued at or after it.The base is notional: it has no cash value, cannot be withdrawn and cannot be taken as a lump sum [S1][S9]. 0.0 outside cover, at every timing, and 0.0 without the rider or once it has died.
- is_rb_pro_rata()[source]#
Whether a withdrawal reduces the rollup base pro rata,
rb_wd_conventionPRO_RATA.A decode of the Reference, an int code,
PRO_RATA0 orDOLLAR1, whereFIA_US_Sholds"pro_rata"or"dollar", asis_step_up_annual()is, read byrollup_base_pp().
- is_rb_dollar()[source]#
Whether a withdrawal reduces the rollup base dollar for dollar,
rb_wd_conventionDOLLAR.The other decode of the Reference (
is_rb_pro_rata()): a convention that is neither raises inrollup_base_pp(), as inFIA_US_S.
- rollup_base_pp(t)[source]#
RB(t): the rollup base closing month t.
Reduced in the same proportion as the benefit base under the baseline [std] convention [S9], and only at an anniversary, where the reduction happens. Set
rb_wd_convention = DOLLAR, before the model computes anything, for the alternative documented at another carrier,RB(t) = max(0, RB(0) - G(t))— “Premium minus Withdrawals” [S2].It opens the year on
rollup_base_pp_year_open(), and reads the convention through its decodes,is_rb_pro_rata()andis_rb_dollar(), a convention that is neither raising. 0.0 outside cover.
- lw_pp_at(t, timing)[source]#
LW per contract in month t, read at the point given by
timing.BEF_WDis the amount payable at this contract year’s anniversary, after step 4’s ratchet;EOYis the closing value, after step 5’s proportional reduction. The ratchet is annual, so away from an anniversary this carries the amount set at the last one — the income in force, which is what a mid-year reading of the rider state means.At exercise
LW = pi x BB(4); afterwards the ratchetLW = max(LW(0), pi x BB(4))applies so income never decreases [S3]. UnusedLWdoes not carry forward [S9]; one carrier is the exception, accumulating the shortfall without interest [S3]. InDEPLETEDthe amount is simply carried: there is no base to recompute it from.The amount carried from the anniversary that opened the year is
lw_pp()there, from the frame, or, where that anniversary precedes the first month on the books, the model point’slw_pp_init()on a contract in force and 0 on new business. 0.0 outside cover, at both timings; any other timing raises in cover.
- wd_scheduled_at(k)[source]#
The ad hoc withdrawal the point’s programme schedules at contract year count
k.FIA_US_Slooks up(wd_schedule_id, k), an exact key, else zero: a contract year with no row takes nothing. The key is an elapsed contract year count, on the policy clock — a row keyedkis a withdrawal at the anniversary closing contract yeark + 1. The table’s one reader, ofData.wd_amount_array, which holds each programme by count, 0.0 where it has no row, at the rowwd_schedule_number()gives the point’swd_schedule_id;wd_scheduled_pp()calls it in cover only, in the anniversary month. A count below 0 is no row, 0.0; one past the array’s last,Data.wd_last_year, which no projection reads, raises, naming the point.
- wd_scheduled_pp(t)[source]#
The ad hoc gross withdrawal at the anniversary closing month t’s contract year.
Read from withdrawal_table.csv, which is not a step function: a contract year with no row takes nothing. Its key column is an elapsed contract year count, not a month — a row keyed
kis a withdrawal at the anniversary closing contract yeark + 1— so it is read atduration(t), throughwd_scheduled_at(), on the policy clock. Lifetime withdrawals are generated by the rider, not scheduled here. Zero in every other month, and outside cover.
- wd_pp(t)[source]#
G(t): the gross withdrawal taken at the anniversary in month t.
Zero in every other month: both the lifetime withdrawal and the ad hoc schedule are contractually annual, so the finer grid moves no cash between anniversaries. In
INCOME,utilization_intensity() x LWplus any scheduled ad hoc amount; inDEPLETED, exactlyLW, paid by the insurer from its own funds; inACCUM, only the scheduled amount. Gross by construction: a contract promising a stated net check would need a gross-up solve, which is not implemented.Zero outside cover.
- wd_guar_pp(t)[source]#
min(G(t), LW(t)): the guaranteed portion of month t’s withdrawal.
A withdrawal is applied first against the guaranteed annual amount; that portion reduces the account value dollar for dollar and leaves the benefit base and the income amount unchanged [S9]. The two operands are read in
FIA_US_S’s order, each into a local first, so that compiled, where a two-argumentminevaluates right to left, a point both refuse raises the first’s message, as in modelx.
- wd_excess_pp(t)[source]#
E(t) = max(0, G(t) - LW(t)): the excess withdrawal in month t.
The quantity that permanently reduces the guarantee, and that destroys it entirely if it exhausts the account value [S1][S5][S9]. Note this is not the chassis’s
wd_excess_pp, which is the amount exposed to the surrender charge; that iswd_charge_base_pp()here. Before exerciseLWis zero, so the whole withdrawal is an excess.
- wd_unfunded_pp(t)[source]#
The part of G(t) that neither the account value nor the guarantee pays.
G(t) - min(G(t), max(0, AV(2)(t)))in a month whose closing phase isTERMINATED; zero everywhere else. The two exhaustion branches are not symmetric, and this is where they part. InDEPLETEDthe account value is gone but the guarantee is alive, so the insurer paysLWfrom its own funds for the rest of the covered life [S1][S3][S9][R1] and nothing is unfunded. On theTERMINATEDbranch the account value is driven to zero by an excess withdrawal, a surrender charge or a negative MVA, and “an account value run to zero by an excess withdrawal loses the guarantee entirely” [S1][S5][S9] — [S5] is explicit that the contract “as well as the rider will be considered Surrendered”. Beyond the account value there is then nothing to pay from: no balance and no promise. Paying the requested amount in full would honour the guarantee in the very year the withdrawal destroys it, which is the trap the notes’ attribution test exists to avoid.The notes write step 4 as
AV(5)(t) = AV(2)(t) - G(t)with no cap because they write it for the funded case. The cap here is on the payment, not on the withdrawal:wd_pp()still carries the amount requested, so the excess still setsdepletion_cause()and still drivesrhoto 1 and the benefit base to zero. Onlywd_payment_pp()and the three ledger lines are reduced.G(t)andAV(2)(t)are read inFIA_US_S’s order, each into a local first (wd_guar_pp()).Zero outside cover.
- wd_guar_paid_pp(t)[source]#
The guaranteed portion of month t’s withdrawal that is actually paid.
min(G, LW)less whatever ofwd_unfunded_pp()the excess could not absorb. The account value funds the withdrawal in the order the notes compose it — the firstLWdollars are the guaranteed portion and the remainder is the excess [S9] — so an under-funded withdrawal leaves the excess unpaid first and eats into the guaranteed portion only after that [std], the notes being silent on a withdrawal the account value cannot fund. Equal towd_guar_pp()in every month except a terminating anniversary.
- wd_excess_paid_pp(t)[source]#
The excess portion of month t’s withdrawal that is actually paid.
max(0, E(t) - wd_unfunded_pp(t)): the excess is the first thing an under-funded withdrawal loses, being the part with no promise behind it. Equal towd_excess_pp()in every month except a terminating anniversary.
- wd_cum_pp(t)[source]#
Wcum(t): cumulative gross withdrawals from issue to the end of month t.
A running total over months, though only the anniversary months add to it. It opens at
t_entry()on the model point’swd_cum_pp_init(), the withdrawals taken before the valuation date, 0 on new business;FIA_US_S’s counts from the month it enters a contract, from 0. 0.0 outside cover.
- free_wd_base(t)[source]#
The base of the free withdrawal amount: the AV opening the contract year of month t.
10% of the account value at the anniversary that opens the contract year, available from contract year 1 and with no carry-forward [S1][S3][S5][S6][S9][S10]; the combination is [std]. Fixing the base at a known prior value is what lets the chargeable amount be evaluated without a fixed point, and it is what makes the allowance a property of the contract year rather than of the month.
- free_wd_allow(t)[source]#
FW(t) = 0.10 x AV(0): the free withdrawal amount for month t’s contract year.
- wd_free_pp(t)[source]#
The free-allowance portion of the anniversary’s withdrawal, the part of FW it uses.
The chassis name for this quantity (
MYGA_US_S,UL_US_S,RILA_US_S), so the library spells the free-allowance portion of a withdrawal one way everywhere. Zero away from the anniversary, where no withdrawal is taken and the whole allowance therefore remains against a mid-year surrender.A [std] choice the notes flag as open. [S9] says only that withdrawals up to the annual benefit amount carry no charge “even if greater than the Free Withdrawal Amount”; it does not say whether they exhaust it. The convention here — the guaranteed amount consumes the free amount — is the insurer-favourable reading and is what the worked example uses, leaving
12,800.00 - 10,144.16 = 2,655.84against the surrender. The alternative leaves the wholeFW(t)available against the excess. The free amount and the withdrawal are read inFIA_US_S’s order, each into a local first (wd_guar_pp()).Zero outside cover.
- free_wd_remain(t)[source]#
The free withdrawal amount left after the contract year’s guaranteed withdrawal.
The whole allowance away from an anniversary, where no withdrawal has been taken yet — which is what a mid-year surrender is charged against.
- wd_charge_base_pp(t)[source]#
X(t): the part of month t’s withdrawal exposed to charge, clawback and MVA.
max(0, G(t) - FW(t))before exercise andmax(0, E(t) - remaining free)after it [std] — withdrawals up toLWcarry no surrender charge, no MVA and no bonus clawback even when LW exceeds the free withdrawal amount [S9]. Zero once the account value is gone: post-depletion income is not a chargeable withdrawal.Zero outside cover.
- surr_charge_base_pp(t)[source]#
X(t) at a full surrender in month t:
AV(t)less the free amount left.The chassis calls this
surr_excess_pp; renamed here only for symmetry withwd_charge_base_pp(), becauseE(t)already names a different quantity in these notes. The construction is the chassis’s and the source is the same [S10].Zero outside cover.
- bonus_factor()[source]#
b/(1+b): the factor that strips the bonus out of a bonus-inclusive account value.
The clawback factor is b/(1+b), not b [S10] — the account value already contains the bonus, so using
bover-recovers by(1+b).
- mva_ref_yield(y)[source]#
i_y: the MVA reference index level at anniversary
y, from the scenario table.Keyed by anniversary number, like
index_level(), so the level in force at a transaction closing the contract year of monthtismva_ref_yield(duration(t) + 1). A declared investment-grade corporate bond yield index; generic here [std], and named as Barclays US Credit Index in the linear-form products [S6][S7].
- mva_term(t)[source]#
n/12: the years remaining in the MVA period at the end of month t.
The MVA period is the ten-year surrender charge period [S7][S10], and the notes state the term in months — which is what the monthly grid can now say exactly:
surr_charge_period - (duration_mth(t) + 1)/12, on the policy clock, a transaction in monthtbeing settled at its end. At the worked example’s anniversary 8 — policy month 95, the close of contract year 8, which ist = 11on the anchor in force at anniversary 7 — that is10 - 96/12 = 2years, then = 24months the notes quote, so every anniversary value is the annual grid’s; a surrender six months earlier now carries the 30 months it actually has instead of being rounded to the anniversary. The remaining term reaches zero at anniversary 10, so a transaction carries a live adjustment through contract year 9, and none at anniversary 10 itself; a surrender earlier in contract year 10 carries the months left.0.0 outside cover.
FIA_US_Swrites(t + 1)/12, itstbeing the policy month.
- mva_in_force(t)[source]#
Whether an MVA applies to a transaction in month t.
MVA = 0outside the MVA period and on the death benefit [S5][S6][S7][S10]; the second is handled where the death benefit is valued.
- mva_rate(t)[source]#
The market value adjustment rate,
[(1+i0)/(1+it)]^(n/12) - 1[S10].Signed, and negative when the reference yield has risen [S10]. This is the ratio-of-yield-factors family, which is naturally bounded; the linear family
(i0 - it) x Tadopted by the fixed-deferred chassis [S6][S7] is unbounded and must be collared separately. The FIA composite restates the MVA rather than inheriting it, which is why the chassis’smva_familyswitch is absent here.The reference yield is read at the anniversary closing the contract year of month
t,duration(t) + 1, which is the transaction date the adjustment applies at.
- is_collar_gross()[source]#
Whether the MVA collar is measured on the gross withdrawal,
mva_collar_basisGROSS.A decode of the Reference, an int code,
GROSS0 orSURRENDER_VALUE1, whereFIA_US_Sholds"gross"or"surrender_value", asis_step_up_annual()is, read bywd_mva_pp()andmva_pp(). Setmva_collar_basisbefore the model computes anything.
- is_collar_surrender_value()[source]#
Whether the MVA collar is measured on the account value,
mva_collar_basisSURRENDER_VALUE.The other decode of the Reference (
is_collar_gross()): a basis that is neither raises inwd_mva_pp()andmva_pp(), as inFIA_US_S’smva_pp_on.
- wd_clawback_pp(t)[source]#
CB(t) on month t’s withdrawal [S10].
(1 - v(t)) x [b/(1+b)] x X(t)on the chargeable amount,wd_charge_base_pp():FIA_US_S’sbonus_clawback_on, a cell of float parameters, written inline here, with its arguments evaluated in its order and its expression unchanged, so that the value is its bit for bit and no projection cell passes a float to a cell (R14).
- wd_mva_pp(t)[source]#
MVA(t) on month t’s withdrawal, collared [S10].
The raw adjustment
mva_rate(t) x X(t)on the chargeable amount,wd_charge_base_pp(), collared to+/- max(0, R - SC - CB - MGV), whereRis the collar’s reference, the gross withdrawal,wd_pp(), undermva_collar_basisGROSSand the account value underSURRENDER_VALUE(is_collar_gross(),is_collar_surrender_value()), a basis that is neither raising: the MVA can neither take the payment below the guaranteed minimum nor lift it above what the contract holds.FIA_US_S’smva_pp_onand the clawback inside it, cells of float parameters, written inline here, their cells evaluated in their order and their arithmetic in its association, so that the value is theirs bit for bit and no projection cell passes a float to a cell (R14).
- wd_payment_pp(t)[source]#
The cash paid on month t’s withdrawal,
G - unfunded - SC - CB + MVA.The surrender charge and the clawback are internal transfers within the account value, not fee income: the account value falls by the gross
G(t)while the holder receives this. Reporting them as income while also projecting the account value net of them double-counts.wd_unfunded_pp()is zero in every month except a terminating anniversary, where it strips out the part of the request the account value could not fund and the destroyed guarantee does not cover. On theDEPLETEDbranch it stays zero and the whole ofLWis paid, which is the guarantee.
- wd_reduction_rate(t)[source]#
rho(t): the proportional reduction applied to BB, LW and RB in month t.
Pre-exercise the denominator is the gross account value after the rider charge; post-exercise it is that value net of the guaranteed amount [S9]. Zero when there is no excess: a withdrawal inside
LWleaves the guarantee untouched, and 1 where the denominator is 0 or less.FIA_US_S’swd_reduction_rate_on, a cell of float parameters, written inline, its arguments read in its order, so that the value is its bit for bit and no projection cell passes a float to a cell (R14). Zero outside cover.
- surr_clawback_pp(t)[source]#
CB(t) on a full surrender closing month t [S10].
(1 - v(t)) x [b/(1+b)] x X(t)on the chargeable amount,surr_charge_base_pp():FIA_US_S’sbonus_clawback_on, a cell of float parameters, written inline here, with its arguments evaluated in its order and its expression unchanged, so that the value is its bit for bit and no projection cell passes a float to a cell (R14).
- mva_pp(t)[source]#
MVA(t) on a full surrender closing month t, collared [S10].
The raw adjustment
mva_rate(t) x X(t)on the chargeable amount,surr_charge_base_pp(), collared to+/- max(0, R - SC - CB - MGV), whereRis the collar’s reference, the account value,av_pp(), under eithermva_collar_basis,GROSSorSURRENDER_VALUE, the gross amount of a surrender being the account value (is_collar_gross(),is_collar_surrender_value()), a basis that is neither raising: the MVA can neither take the payment below the guaranteed minimum nor lift it above what the contract holds.FIA_US_S’smva_pp_onand the clawback inside it, cells of float parameters, written inline here, their cells evaluated in their order and their arithmetic in its association, so that the value is theirs bit for bit and no projection cell passes a float to a cell (R14).
- surr_value_pp(t)[source]#
The surrender value before the nonforfeiture floor,
AV - SC - CB + MVA.The composition order is account value, then charge and clawback and MVA computed on the pre-deduction excess, then the floor — the chassis’s order, and the one contractual element the FIA notes inherit rather than restate.
- surr_benefit_pp(t)[source]#
CSV(t) = max(AV - SC - CB + MVA, MGV): the surrender benefit paid [S1][S6][S10].
Zero in
DEPLETED: there is no account value and no surrender value [S1][S9]. A binding floor is not a separate cash flow — it raises the benefit, andMGV - SVis a reconciliation quantity only. The two operands are read inFIA_US_S’s order, each into a local first (wd_guar_pp()).
- mgsv_charge_pp(t)[source]#
The annual contract charge deducted from the Model #805 floor, at the anniversary.
Model #805 4.A permits $50 a year, accumulated at the nonforfeiture rate, together with premium tax actually paid and indebtedness [R2]. All are zero here [std] because no retrieved product declares an actual annual policy fee, which makes the modeled floor slightly conservative.
Zero outside cover.
- prem_to_mgsv_pp(t)[source]#
The consideration credited to the Model #805 floor per contract, in the issue month.
87.5% of the single premium excluding the bonus [S10][R2],
net_consideration_ratio x P, in the month whoseduration_mth(t)is 0, and 0 in every other: the floor’s issue value, whichFIA_US_S’smgsv_pp_init()computes when its column is blank, credited in the issue month instead, asprem_to_av_pp()credits the account value’s.mgsv_pp()adds it to the opening before the month’s accrual.
- mgsv_pp(t)[source]#
MGV(t): the Model #805 guaranteed minimum value closing month t.
The floor accretes every month at
(1 + i_nf)^(1/12) - 1, so twelve months compound to exactly the annual nonforfeiture rate and the anniversary values are the annual grid’s; the withdrawal is deducted at the anniversary, where it is taken. Accrete, then deduct — the worked example pins the ordering at93,811.84 x 1.01 - 10,144.16 = 84,605.80. The fixed-deferred chassis deducts and then accretes; the two are different arithmetic on the same concept, which is exactly what that file warns against carrying across.Accruing monthly rather than once at the anniversary is what makes the floor mean something for a mid-year death or surrender, which is where it most often binds. It opens at
t_entry()onmgsv_pp_init(), the floor in force at the valuation date, and in the issue month the considerationprem_to_mgsv_pp(),0.875 x Pexcluding the bonus [S10][R2], comes on top, both written inline, so that the floor’s chain runs one cell a month.rider_charge_from_mgsvswitches on the treatment documented at two carriers, one deducting the rider charge from the floor and the other its allocation charge [S1][S2][S3][S4]; the composite does not [std].0.0 outside cover. A
mgsv_ratebelow -1 raises, naming the point: its power has a negative base, a complex number in Python, whereFIA_US_SraisesTypeErrorat the floor’smax, and NaN in C, where thatmaxwould answer 0. At exactly -1 the floor accretes to 0.
- mgsv_rate_statutory(cmt5, option_cost)[source]#
The Model #805 4.B/4.C indexed nonforfeiture rate [R2][R3].
max(0.0015, min(0.03, round(CMT5 to 1/20 of 1%) - 0.0125 - delta))wheredeltais the equity-index reduction of 4.C: available only when the annualized option cost of the guaranteed index features is at least 25 basis points, and then equal tomin(100 bp, option cost), certified annually [R3].Two traps the notes name. The 4.B floor is 15 basis points, not 1% — the composite’s 1.00% is a [std] pick inside the 0.15%-3% corridor, not the statutory floor. And whether the 15 bp floor survives the 4.C reduction is not stated in the retrieved text [unverified]; the specimen contract language, “the interest rates will range between 0.15% and 3%”, suggests it does [S10], which is the reading implemented. The statute defines the minimum: the contract rate must satisfy
mgsv_rate >= mgsv_rate_statutory(...), which is whatmgsv_rate_is_compliant()tests, not the reverse inequality.FIA_US_S’s formula,math.floorincluded, kept for a user checking a contract rate against the statute and for the comparison withFIA_US_S: an engine cell (the Space docstring’s Reporting cells), which no projection cell calls. A step of 0 is refused before it divides, with Python’s own message,float division by zero, which compiled code would otherwise word differently.
- mgsv_rate_is_compliant(cmt5, option_cost)[source]#
True when the contract nonforfeiture rate meets the statutory minimum [R2][R3].
An engine cell, as
mgsv_rate_statutory()is, its one caller.
- mort_rate_base_at(a)[source]#
The table’s annual mortality rate at attained age
aand the model point’s sex.Data.mort_table_arrayat the rowmort_schedule()gives the point’ssexand the column of agea, the table’s one reader, keyed by the age;mort_rate()calls it in cover only, atage().Datarefuses a point whose sex the table lacks, or whose attained age in its first month on the books it gives no rate at, andproj_len()one whose sex’s rates stop belowmaturity_age. An age outside the sex’s rates, which no projection reads, raisesValueErrornaming the point, whereFIA_US_S’s lookup raisedKeyError; so does one outside the ages the array holds, from the table’s first, or 0 if that is lower, toData.read_last_age, 122.
- mort_rate(t)[source]#
q(t): the annual mortality rate of the contract year containing month t.
Read at
age(t), the attained age opening that contract year — the library convention ofTerm_US_SandMYGA_US_S. The rate actually applied to a month ismort_rate_mth(); this cell stays annual so the table is read the way it is published and so the assumption is visible at the frequency it is set at.The shipped table is the same illustrative Makeham annuitant curve as
products/fixed_deferred_annuity[std], not a published basis. The prescribed basis is the 2012 IAM Basic / 2012 IAR generational family with Projection Scale G2,q_x^(2012+n) = q_x^(2012) x (1 - G2_x)^n, rounding applied from the 2012 period rate each time and never by compounding an already rounded rate [REG-R59][REG-R60]; it may not be redistributed here, so swap it in by repointingData.mort_table_filebefore the model computes anything. Generational projection is not implemented for the same reason.mort_ae_factorcarries the A/E deviation, 100% [std] against the 2020-2024 payout experience study [REG-R61]; the spelling is the library’s shared one, so the A/E factor reads the same in every model that has one.The table’s rate is read at
mort_rate_base_at(), and capped at 1 asFIA_US_Scaps it, the bound second,min(q, 1.0), so that a NaN stays NaN rather than reading as certain death.Datarefuses a blank rate in any case. At the shipped A/E of 100% the capped rate is the table’s at every age, 1.0 at 120. 0.0 outside cover, before the table is read.
- mort_rate_mth(t)[source]#
The monthly mortality rate,
1 - (1 - q)^(1/12).The uniform-force conversion the library uses everywhere: twelve of these compound to exactly the annual rate of the contract year, so the anniversary in-force numbers are the annual grid’s and only their distribution through the year changes. Dividing by twelve instead would overstate the decrement, and the error grows with the rate.
- shock_lapse_rate(t)[source]#
w_shock: the surrender rate in the year the surrender charge expires [R8].
The single most important behavioral fact in the product. 33% without a GLWB rider against 10% with one in force but not activated, and 5% [std] once it is activated, extrapolated from the finding that contracts with GLWBs lapse less than those without and that activated GLWBs lapse least [R1][R8]. Applying a plain fixed-deferred shock lapse — roughly 52%-56% for fixed-rate deferred annuities [REG-R63, unverified] — to an FIA with an in-force rider materially understates the tail the product is sold for.
Zero outside cover.
- lapse_rate_base(t)[source]#
w_base(t): the base annual surrender rate of month t’s contract year [std].
2% in years 1-3, 3% in 4-6, 4% in 7-9, 5% in year 10, the shock in the year the surrender charge expires, and 6% thereafter — the shape [R1] describes: low early, rising through the charge period, spiking at expiry, then falling back but staying above pre-shock levels. The notes’ separate
M_shockmultiplier is absorbed here, because the shock is stated as an absolute rate rather than as a factor on the ultimate; see the Space docstring.Zero outside cover, where no contract year is the contract’s.
- lapse_moneyness_factor(t)[source]#
M_money(t) = clamp(1 - 0.6 max(0, BB/AV - 1), 0.2, 1.0) [std].
Surrender is suppressed when the guarantee is in the money, because a rational surrender destroys a guarantee worth
BB - AVin benefit-base terms. The observed direction is documented [R1][R8]; the functional form is not.Evaluated on the state closing the contract year, at
anniv_mth(), so the factor is a property of the year like the base rate it multiplies. Reading it month by month would let the fixed-account accrual drift the ratio within the year and make the annual surrender assumption depend on where in the year it is sampled.anniv_mth()lies at most 11 months aftert, inside the frame, and the account value and the benefit base read there depend on no count and on nothing after that anniversary, so the read opens no chain past it. 1.0 outside cover, no adjustment, whereFIA_US_Shas no guard and would read a month past the frame.
- lapse_rate(t)[source]#
w(t): the annual surrender rate of the contract year containing month t.
min(0.35, w_base(t) x M_money(t)), and zero in DEPLETED — with no account value there is nothing to surrender, so lapse is impossible [S1][S9] and leaving the decrement on would silently truncate the most expensive part of the liability. In the contract year the contract terminates, the survivors leave as a deemed full surrender [S5][S9], so this returns 1.0 there and the in-force roll-forward closes.Evaluated on the phase closing the contract year, at
anniv_mth(), so it is one rate for the whole year;lapse_rate_mth()is what a month actually applies.anniv_mth()lies at most 11 months aftert, inside the frame; the phase read there depends on no count and on nothing after that anniversary. 0.0 outside cover.
- lapse_rate_mth(t)[source]#
The monthly surrender rate,
1 - (1 - w)^(1/12).The same uniform-force conversion as
mort_rate_mth(), so twelve months compound to exactly the contract year’s annual rate — including the shock in the year the surrender charge expires, which is spread. That is deliberate and is the opposite ofTerm_US_S, where the notes state the shock as a rate “applied in full at the end of the final level-period month”: here the notes state it as the surrender rate of contract year 11, a year that carries no surrender charge in any month, so there is no contractual date inside it for the decision to cluster on.The one rate that is not spread is the deemed full surrender at termination. That is a contractual event, not a behavioral assumption: the contract “as well as the rider will be considered Surrendered” [S5] at the anniversary the account value is destroyed, so the survivors leave in that month and not before.
- pols_if(t)[source]#
The in-force count at the start of month t, the weight of row t.
pols_if_at(t, BEF_DECR): the count carried in from month t - 1 plus month t’s new business, before month t’s decrements. The library convention, set byTerm_US_Sandsavings.CashValue_SE: it is the weight carried by every cash flow reported on the same row ofresult_cf(). At an anniversary month it is the count that reaches the anniversary and therefore the weight the year’s withdrawal and charges carry — on the annual grid that weight was the count entering the year, which is the one place the finer grid changes the answer rather than only the resolution.A point in force at the valuation date opens with
pols_if_init(), and one issued at or after it with its issued count in the issue month; on a point issued att = 0this is exactlyFIA_US_S’spols_if. Death comes before surrender [std]. Zero outside cover: before issue, and fromt = proj_len()on, where the survivors of the last covered month have left throughpols_maturity(). Because the monthly rates compound to the annual ones,pols_ifin the month opening a contract year is exactly the annual-grid model’s count there: the notes’l(k). It isbasiclife.BasicTerm_SE’sBEF_DECRcount, not itspols_if, which is the count before maturity.
- pols_new_biz(t)[source]#
Number of contracts issued in month t:
policy_count()in the issue month.The issue month is the one with
duration_mth(t) == 0:t = 0for a point issued at the valuation date,t = kfor one issuedkmonths later. A point already in force at the valuation date has none.
- pols_if_at(t, timing)[source]#
In-force in month t read at the point given by
timing.The timings in processing order:
BEF_NBthe count carried in from month t - 1, before month t’s new business: the survivors of month t - 1’s deaths and surrenders, out of month t - 1’s
BEF_DECRcount. Att_entry(), the first month on the books, it ispols_if_init(), the count in force at the valuation date (0 for a point issued at or after it), and the recursion reads no earlier month. Zero outside cover, so the survivors of the last covered month leave aspols_maturity().BEF_DECRBEF_NBpluspols_new_biz(), before any decrement; the same number aspols_if(), and the weight on that month’s cash flows.BEF_MORTthe same count: this product has no annuitization decrement, so the chassis’s two timings coincide.
BEF_LAPSEafter that month’s deaths.
AFT_DECRafter its surrenders, the count at the end of month t, which is
pols_if_at(t + 1, BEF_NB)in every month but the last covered one, wherepols_maturity()takes it out.
Both decrements are the monthly rates, death before surrender [std].
BEF_NBandBEF_DECRarebasiclife.BasicTerm_SE’s names, and any timing but these five raises.BEF_NBforms the count left at the end of month t - 1 itself — month t - 1’sBEF_NBplus itspols_new_biz(), after its two decrements, the productsAFT_DECRtakes in the order it takes them — rather than calling for it. So the chain of calls from month t back tot_entry()is one cell a month, whereFIA_US_S’s ran through two. Every count is zero outside cover, before any rate is read.
- pols_lapse(t)[source]#
Full surrenders in month t, on the survivors of that month’s mortality.
Zero outside cover.
- pols_maturity(t)[source]#
Survivors leaving at the projection horizon, non-zero only in the last covered month.
That month is
duration_mth(t) = maturity_mth() - 1, the frame’s last row,t = proj_len() - 1. Not a decrement — the horizon runs out — but needed for the in-force roll-forward to close. Numerically zero under the shipped mortality table, whose annual rate reaches 1.000000 at age 120, hence a monthly rate of 1.0, so the projection closes itself; see the Space docstring.
- claim_pp(t, kind)[source]#
The benefit paid per contract at the end of month t by
kind.DEATHismax(AV(t), MGV(t))with 100% bonus vesting, no surrender charge and no MVA [S1][S2][S5][S10], and is never below the cash surrender benefit [R2 6]. Its two operands are read inFIA_US_S’s order, each into a local first (wd_guar_pp()). Note the FIA composite restates this rather than inheriting the chassis’s full account value floored at the surrender benefit.LAPSEis the surrender benefit.MATURITYis the account value floored at the guaranteed minimum at the horizon. All three are zero in DEPLETED: there is no account value, no surrender value and no death benefit, and the only exit is death [S1][S9]. Any otherkind,ALLamong them, raisesValueError("invalid kind")outside aDEPLETEDmonth: the phase is read before the kind, as inFIA_US_S, so inDEPLETEDit answers 0.0.
- claim_from_av_pp(t, kind)[source]#
The account value released per contract by a claim of
kind.AV(t)for all three kinds; the difference fromclaim_pp()isclaims_over_av(), positive when the Model #805 floor binds and negative when the surrender charge and a negative MVA bite. Any otherkind,ALLamong them, raisesValueError("invalid kind"), each kind compared by==.
Premium income: the single premium, at the start of the issue month.
premium_pp() x pols_new_biz(t): there is no issue-instant row, so the premium is a beginning-of-month flow of the issue month, the one withduration_mth(t) = 0, rather than a row of its own, and it is paid per contract issued. A point in force at the valuation date paid its premium before it, so this is zero throughout for it — as are the acquisition expense and the premium tax that key off it.
- prem_to_av_pp(t)[source]#
Premium and bonus credited to the account value per contract, in the issue month.
P x (1 + b)[S5] in the month whoseduration_mth(t)is 0, and 0 in every other: the issue valueFIA_US_S’sav_pp_init()computes when its column is blank, credited in the issue month instead, whereav_pp_at()adds it atBEF_INV. Zero outside cover by its terms, no month outside cover being the issue month.
- prem_to_av(t)[source]#
Premium and bonus credited to the block’s account value, in the issue month only.
prem_to_av_pp()per contract issued, weighted bypols_new_biz().
- wd_guar(t)[source]#
Guaranteed withdrawal outgo in month t, weighted by
pols_if(t).The count entering the month, which is the in-force number reported on the same row of
result_cf(); at an anniversary that is the count which reaches it. Onwd_guar_paid_pp(), not on the amount requested, so a terminating anniversary cannot pay a guaranteed withdrawal the account value could not fund and the destroyed rider no longer covers. Zero inDEPLETED, where the same payment is reported asincome_payments()so the two lines partition the total rather than overlap.Zero outside cover.
- wd_excess(t)[source]#
Excess withdrawal outgo in month t:
E - unfunded - SC - CB + MVA.Weighted by
pols_if(t), the count entering the month, and onwd_excess_paid_pp(): the excess is the first part of an under-funded withdrawal to go unpaid.Zero outside cover.
- income_payments(t)[source]#
Post-depletion income outgo:
LWat the anniversary whilephase = DEPLETED.This is the guarantee. There is no account value behind it, no rider charge is deducted, and it runs for the rest of the covered life [S1][S3][S9][R1].
Annual like every other withdrawal, so it falls in the anniversary month and is weighted by the contracts that reach it. Paying it in each of the twelve months would multiply the guarantee twelvefold and break the partition
withdrawals = wd_guar + wd_excess + income_paymentsthatresult_cf()documents.Zero outside cover.
- withdrawals(t)[source]#
Total withdrawal outgo in month t,
wd_payment_pp(t) x pols_if(t).Equal to
wd_guar()+wd_excess()+income_payments()in every month, the three lines partitioning it by the notes’ ledger categories. All four are published byresult_cf(), so summing every column of that frame double-counts the withdrawal; the ledger identity is on the total, and the split is there because the notes report the three categories separately.Zero outside cover.
- claims(t, kind)[source]#
Benefit outgo in month t, for one
kindor, withkindALL, all three.ALLisFIA_US_S’skind=None: the three kinds added in its order, by its chain of+, so that the total is its bit for bit, the sign of a zero included.
- claims_over_av(t, kind)[source]#
Benefit paid less the account value released,
claims - claims_from_av.Signed and a reconciliation quantity only: positive exactly when the Model #805 floor binds, negative when the surrender charge, the clawback and a negative MVA bite. A binding floor does not add a top-up cash flow — it raises the benefit.
ALLis the three kinds’ total, as inclaims().
- commissions(t)[source]#
Acquisition commission, zero [std].
The technical notes fold the whole acquisition cost into a single 6.0%-of-premium acquisition expense and give no separate commission, so
comm_rate_acqis 0 and this line exists for shape only. It is kept rather than dropped because every model in the library carries the same cash flow vocabulary.
Premium tax on the single premium, 0% on the composite state basis [std].
- inflation_factor(t)[source]#
The expense inflation factor in month t,
1.025^(t/12), on the valuation clock.tcounts months from the valuation date, so the factor is 1 at the valuation date for every point, and maintenance expense is in valuation-date dollars, asbasiclife.BasicTerm_SEinflates it: a contract issued later inflates from the valuation date, not from its issue, and one in force carries none of its years before it.FIA_US_Sinflates from issue on its policy clock, so its in-force points, entered at policy month 84, carry1.025^7that this model’s twins of them do not. A fractional power of the annual rate, so twelve months of it compound to exactly one year of inflation. Aninflation_ratebelow -1 raises, naming the point: its power has a negative base, a complex number in Python, whichFIA_US_Sprojects, and NaN in C.
- expenses(t)[source]#
Insurer expenses: acquisition at issue and inflating maintenance monthly [std].
6.0% of the single premium in the issue month, per contract issued and uninflated, as
basiclife.BasicTerm_SEcharges acquisition, and $80 per contract per year inflating at 2.5% from the valuation date — one twelfth of it a month, weighted by the in-force at the start of the month. Spreading the maintenance charge is the point of the finer grid for this line: it is an insurer cost accruing continuously, not a contractual event tied to the anniversary, so it now falls where it is incurred and is weighted by survivors who have not yet left.premiums(t)is zero everywhere but the issue month, so the acquisition term simply drops out elsewhere. Both are standardizations: no retrieved document discloses FIA acquisition cost or per-contract maintenance.Zero outside cover.
- net_cf(t)[source]#
Net cash flow in month t.
The index credit, the rider charge, the surrender charge, the bonus clawback and the movement of the Model #805 floor are internal accounting entries: they drive the account value, the benefit base and the benefit amount but are never ledger lines of their own. Only amounts paid to or received from the contract holder, and the insurer’s own expenses, appear here.
- av_at(t, timing)[source]#
The in-force weighted account value in month t; see
av_pp_at().Every timing inside the month carries
pols_if(t)— the count entering it — because all processing happens before the decrements.EOYcarries the count leaving the month,pols_if_at(t + 1, BEF_NB), the next month’s count before its new business: zero at the horizon, wherepols_maturity()has taken the survivors out.Zero outside cover.
- rider_charges(t)[source]#
Rider charges deducted from the whole block’s account value in month t.
Zero outside cover.
- wd_from_av(t)[source]#
The account value released by month t’s withdrawals, gross of charge and MVA.
Zero outside cover.
- av_depletion(t)[source]#
The block’s withdrawal outgo the account value could not fund in month t.
Zero outside cover.
- av_change(t)[source]#
The change in the block’s account value over month t.
Closing less opening, the opening being read at
BEF_PREMso that the single premium of the issue month is a movement rather than part of the balance brought in; on a point in force at the valuation date the opening att = 0is its block’s account value entering month 0. Away fromt_entry(),av_at(t, BEF_PREM)is exactly the previous month’s closing value.
- check_av_roll_fwd_resid(t)[source]#
Account value roll-forward residual for month t; the signed float.
AV(t) - AV(0)(t) = premium in + interest credited - rider charges - withdrawals + the part of a withdrawal the account value could not fund - the account value released by each claim kind. The cash paid on a surrender may differ from the account value released — by the charge, the clawback, the MVA and any binding Model #805 floor — and that difference isclaims_over_av(), deliberately not part of this identity. It closes month by month on the finer grid, where the interest term is the month’s accrual and the claim terms are that month’s exits.The per-
tresidual is kept because it is what a debugging session wants whencheck_av_roll_fwd()returnsFalse; the boolean is defined in terms of it.Zero outside cover.
- check_av_roll_fwd()[source]#
Check the account value roll-forward:
Truewhen it closes in every month.No argument and a bool, following
savings.CashValue_SEand the rest of this library, so one test can call the same check across every model. The signed residual for a single month ischeck_av_roll_fwd_resid(), and this isabs(resid) <= check_tol_av x max(policy_count(), 1)overt = 0 .. proj_len() - 1: the tolerance scales with the count, since the residual is rounding on that many contracts. On a point counting one contract it isFIA_US_S’s absolute 1e-6, loose enough for an account value of order $100,000 accumulated over a century of months; it is not a modelling assumption. A residual that is not a number fails, asFIA_US_S’smath.isclosefails it: the test is that the residual is within the tolerance, which no comparison with NaN is.
- check_pols_roll_fwd_resid(t)[source]#
In-force roll-forward residual for month t; the signed float.
pols_if(t) - pols_if_at(t + 1, BEF_NB) = deaths + surrenders + horizon exits: the start-of-month count opens the row, the exits are taken during it, and the next month opens on what is left, before its own new business. Zero to floating point for everyt, including the last,t = proj_len() - 1, where the next month’s count is zero andpols_maturity()carries the survivors out.Zero outside cover, before
t + 1is read, asFIA_US_Sguards it before its frame: so att = proj_len()nothing reads a month past it.
- check_pols_roll_fwd()[source]#
Check the in-force roll-forward:
Truewhen it closes in every month.No argument and a bool, as for
check_av_roll_fwd(); the signed residual for a single month ischeck_pols_roll_fwd_resid(). The tolerance ischeck_tol_pols x max(policy_count(), 1), 1e-12 on a point counting one contract, scaling with the count as the residual does. A residual that is not a number fails, as incheck_av_roll_fwd().
- result_cf()[source]#
Result table of cashflows, one row per month
t = 0 .. proj_len() - 1.Row 0 is the valuation month for every model point, so the frames of a block line up and sum row by row, and a point issued after the valuation date has zeros until its issue month. There is no issue-instant row: the issue month’s row carries the premium and the acquisition expense as beginning-of-month flows alongside that month’s own activity.
result_cf_annual()sums it into contract years.pols_ifis the in-force count at the start of montht, which is the weight every cash flow on the same row carries — dividing a row’s cash flow by its per-contract amount returns this column exactly. Every withdrawal and benefit driven by the contract falls in an anniversary month, so those columns are zero in eleven rows out of twelve; deaths, surrenders and maintenance expense fall in every row.withdrawalsis the library-wide column for partial withdrawal payments and is the total; the three columns after it —wd_guar,wd_excessandincome_payments— partition that total into the notes’ own ledger categories. They are published alongside it, not instead of it, so summing every column of the frame double-counts the withdrawal. The columns areFIA_US_S’s.net_cfis income-positive, as everywhere in this library.
- result_pols()[source]#
Result table of in-force movements, one row per month
t = 0 .. proj_len() - 1.pols_ifopens the row andpols_if_aft_decrcloses it;pols_new_biz, second, is the month’s new business, whichpols_ifholds. The two decrement columns are the monthly rates actually applied; the annual rates they are converted from aremort_rate()andlapse_rate(), constant across each contract year, and all four are 0 outside cover. The closing column is the next row’s count before its new business in every month but the last, wherepols_maturity()takes the survivors out and the projection stops. The identitycheck_pols_roll_fwd_residasserts is thereforepols_if(t) - pols_if_at(t + 1, BEF_NB) = pols_death + pols_lapse + pols_maturity.FIA_US_S’s report, withpols_new_bizadded.
- result_av()[source]#
Result table of the per-contract account value and surrender trace, by month.
The first eight columns walk the worked example’s account value rows, now month by month:
fixed_interest_ppaccrues in every row,index_credit_pp,rider_charge_ppandwd_pponly in anniversary rows. The rest are the surrender trace, available in every month rather than only at the anniversaries the notes tabulate — which is the reading a mid-year surrender needs.One row per month
t = 0 .. proj_len() - 1, with zeros outside cover.
- result_glwb()[source]#
Result table of the GLWB rider state per contract, indexed by the month t.
The benefit base is notional — no cash value, not withdrawable, not payable as a lump sum [S1][S9] — so none of these columns is a cash flow. They are the drivers of the rider charge, the lifetime withdrawal and, in the end, the post-depletion income. Every one of them is annual: the rider state is flat between anniversaries and steps at each one, so the rows of interest are the anniversary rows, those with
duration_mth(t) % 12 == 11.One row per month
t = 0 .. proj_len() - 1. Thephasecolumn holds the label of each month’s phase code,ACCUM,INCOME,DEPLETEDandTERMINATEDas inFIA_US_S, andPRE_ISSUEbefore issue: a report may hold text where every projection cell holds the code.
- result_cf_annual()[source]#
result_cf()summed into contract years, indexed bypolicy_year.Every cash flow column is the total of its months in cover;
pols_ifis the count in the first month of the contract year in the frame. Months outside cover are left out, so a point issued after the valuation date starts at policy year 1, and a point in force mid-year starts at the year under way, whose first row is that part of the year from the valuation date on. On a point issued at the valuation date it isFIA_US_S’s report.Against the annual grid this agrees exactly on
pols_if,premiums,commissionsandpremium_taxes, the last three being the single premium and two rates on it. It does not agree on the withdrawal columns, the claims or the expenses, and so not onnet_cf: a withdrawal taken at the anniversary is now weighted by the contracts that reach it rather than by those that entered the year, claims fall in the month of exit, and maintenance expense accrues monthly. That gap is the point of the finer grid — see the Space docstring.