The Projection Space#
The by-contract projection of VA_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 issued at the valuation date, and point_id() is its
label:
>>> Projection[0].result_cf() # one row per month from the valuation date
>>> 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/variable_annuity/model-sec.md).
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 VA_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 and FIA_US_SEC compiled first. A formula of VA_US_S
is rewritten where it depends on where the projection starts, where it must answer for a
month outside cover, where it read a scenario or a contractual event at the wrong clock,
where it compared a model point’s text or a timing, a kind or a phase as text, where its
recursion ran two cells a month, or where it reads a table or text the compiled model
holds as numbers; every other is VA_US_S’s own.
products/variable_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/variable_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
VA_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
VA_US_S reads, read in place; the model point table and the two scenarios are
this model’s own, generated from VA_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 cells 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 |
fund_file |
data.fund_sub_ids(), data.alloc_array(), data.fund_expense_array() |
fund_table.csv |
return_scenario_file |
data.return_array() |
return_scenario_sec.csv |
rate_scenario_file |
data.vix_sq_array(), data.cmt10_array() |
rate_scenario_sec.csv |
gawa_pct_file |
data.gawa_pct_array() |
gawa_pct_table.csv |
cdsc_file |
data.surr_charge_rate_array() |
cdsc_table.csv |
transaction_file |
data.prem_amount_array(), data.wd_amount_array() |
transaction_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_single reading data.premium()[idx];
model_point(), the whole row, is for a reader. mort_rate_base_at(),
subaccount_id() with alloc() and fund_expense_rate(),
inv_return_mth(), scenario_rate(), gawa_pct_at_age(),
surr_charge_rate_at(), and prem_scheduled_pm() with wd_scheduled_pm() are
the tables’ readers, in that order, and sa_pp_init() reads the subaccount values the
model point table carries, through Data.sa_pp_init_array. Each is keyed by an age, a
position or an id of a subaccount, a month, a count of years or a policy month, and
called by a monthly cell in cover only. The mortality, the fund set, the two scenarios,
the grid, the withdrawal charge schedule and the programme are read at the row Data
numbers the point’s sex, fund_set, scenario_id, glwb_option,
cdsc_schedule or txn_id by, mort_schedule(), fund_set_number(),
return_scenario_number() and rate_scenario_number(),
gawa_grid_number(), cdsc_number() and txn_number() (Data’s
docstring, The vectors).
A subaccount is named by its id throughout, as VA_US_S names it,
sa_pp(t, i) with i 1 or 2 as shipped: a point’s fund set picks its own ids, which
the returns and the opening columns key alike. The ids run from 1 to
subaccount_id_max, 9, the subaccount axis of every compiled cache, and a sum over the
subaccounts loops over the positions of the point’s set, 0 .. subaccount_count() - 1,
taking each id from subaccount_id(), in the file’s order, the order
VA_US_S sums in.
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. VA_US_S counts t the
same way, from the first month it projects, and enters its in-force point 2 at t = 0
26 months after issue; but it opens every recursion and keys its issue events at
t == 0. Here the frame has an edge at each end: a policy issued at or after the
valuation date pays its single premium, and bears its acquisition expense, in its issue
month, t_entry(), the month with duration_mth(t) = 0, where every recursion
opens; a policy in force at the valuation date opens at t = 0 on the state its model
point carries; and cover ends with the last month before attained age omega_age.
The policy month is duration_mth(t) = duration_mth_init() + t, the number of policy
months already elapsed at the start of month t: 0 in a contract’s issue month,
duration_mth_init() at t = 0 on a contract in force at the valuation date — the
worked example’s carried state is one, in force with 26 elapsed months — and negative
before issue on a contract issued later. The ordinal policy month — the notes’ “the
27th policy month” — is duration_mth(t) + 1. Every calendar test (Contract
Anniversary, Contract Quarterly Anniversary, contract year, attained age) is written on
duration_mth(t), never on t.
policy_year(t) = duration_mth(t) // 12 + 1 is the contract year y, a 1-based
contractual label, and contract_quarter(t) = duration_mth(t) // 3 + 1 the contract
quarter k. Contract Anniversaries fall at the end of the months where
duration_mth + 1 ≡ 0 (mod 12) and Contract Quarterly Anniversaries at the end of
those where duration_mth + 1 ≡ 0 (mod 3) [std]; on a cell issued at the valuation
date that is t = 11, 23, 35, … and t = 2, 5, 8, …. The attained age is
a(t) = x + y − 1, equivalently x + duration(t) with
duration(t) = duration_mth(t) // 12. Two months of the frame name the edges of a
contract year on the valuation clock: anniv_mth(t), the month at whose end the
anniversary closing the contract year of month t falls, and year_open_mth(t), the
month at whose end the year opened, which precedes the valuation date for the year under
way at t = 0 on a contract valued in force mid-year.
The scenario inputs read the valuation clock. The gross fund returns, the VIX-squared
averages and the CMT rate are a market path in calendar time, shared by every point of a
block, so the t of return_scenario_sec.csv and rate_scenario_sec.csv is a
valuation month, and inv_return_mth() and scenario_rate() read them at t
itself; each row of the model point table reads its own copy of VA_US_S’s path,
re-based to its months in force (Data.return_scenario). Expense inflation counts the
years from the valuation date, t // 12, so maintenance expense is in valuation-date
dollars for every point alike (inflation_factor()). The transaction programmes, the
GAWA% grid, the withdrawal charge scale and the mortality stay on the policy clock, read
at the policy month, the attained age or the contract years completed. On a point issued
at t = 0 the two clocks coincide, and the model computes what VA_US_S
computes.
Within a month the technical notes’ processing order is followed exactly. At the
beginning of the month (BOM): if the contract is already depleted, run the
post-depletion routine and skip everything else; otherwise take the premium, which buys
units at the prior unit value per alloc[i] and raises GWB, BB, NP,
RP, RB, GAWA and ADJ; then take the withdrawal, which fixes the GAWA% if
it is the first one, splits into excess and non-excess portions, computes the withdrawal
charge, cancels units pro rata and updates GWB, GAWA and BB. Then unit values
grow over the month. At the end of the month (EOM): the two rider fees are assessed at a
Contract Quarterly Anniversary and the annual contract fee at a Contract Anniversary,
both by pro-rata unit cancellation; then, at a Contract Anniversary only, the seven
guarantee events in the notes’ order — GMDB withdrawal adjustment, GMDB roll-up, GLWB
bonus, step-up, GWB Adjustment Date test, the non-For-Life GAWA = GWB floor, and the
$10,000,000 cap; then the depletion test; then decrements, death first, then
surrender [std].
Outside cover, before issue and from proj_len() on, every count, cash flow, balance
and rate is 0.0 and every flag False; the four factors that multiply a base or a rate,
gmdb_wd_factor(), gmdb_factor_acc(), lapse_dyn_mult() and
lapse_wd_factor(), are 1.0, no change; bonus_end() is 0; and the phase is
PRE_ISSUE before issue and EXPIRED from the end of cover. The clocks,
duration_mth() among them, and inflation_factor() keep their values.
is_active() is the test, made before any table or rate is read. One read reaches
ahead of the month:
lapse_wd_factor() asks whether the contract year of month t takes a withdrawal,
and reads it once, at anniv_mth(), up to 11 months later and inside the frame,
since the answer is a property of the contract year that depends on no count and on
nothing after that anniversary.
Undiscounted. Like every model in this library, this one projects gross liability cash flows only. Reserves and discounting are a separate layer: the notes’ Valuation and reserve pointers section cites VM-21’s CTE70 stochastic reserve, C-3 Phase II’s CTE(98), VM-22/VM-V §1 for the post-depletion stream and IRC §807, rather than reproducing any of them.
Naming
Cell names follow lifelib’s basiclife.BasicTerm_S and savings.CashValue_SE
wherever those models have an analogue, and MYGA_US_S — the deferred
annuity chassis of this library — wherever the two products share a concept:
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 month. 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; t_entry and maturity_mth are
MYGA_US_SEC’s, and anniv_mth and year_open_mth FIA_US_SEC’s. A
column of the opening state is the cell it opens with _init added, gwb_pp_init
for gwb_pp(); a value of the contract year to date adds _ytd_init, and a
balance at the anniversary that opened the year under way _prev_anniv_init. A reader
keyed by an age, a year count or a policy month is <cell>_at or <cell>_pm. The
is_* cells read the model point’s four switch columns as Data decodes them into
flags, so that no monthly cell compares a column’s text and none calls a label accessor
(stepup_basis, gmdb_option, scenario_id, …), which is left to reporting; a
*_number cell, and mort_schedule(), is the row Data numbers a text key by.
No cell compares text: VA_US_S’s timings, kinds, rate columns and phases are int
codes (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 (0-based) |
duration_mth(t) |
Policy months elapsed at the start of month t |
(valuation month) |
(the projection index) |
Months from the valuation date, 0-based |
(months at t = 0) |
duration_mth_init() |
Policy months elapsed 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 t is inside cover |
y = t//12 + 1 |
policy_year(t) |
Contract year containing month t (1-based) |
y - 1 |
duration(t) |
Completed contract years |
k = t//3 + 1 |
contract_quarter(t) |
Contract quarter containing month t (1-based) |
(the anniversary month) |
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 |
(policy month to t) |
t_of_month(m) |
Valuation month of policy month m |
(the row’s label) |
point_id() |
The point_id of the point at idx |
x, issue_age |
age_at_entry |
Issue age (ANB) |
a(t) = x + y - 1 |
age(t) |
Attained age during month t |
(a at the anniversary) |
age_at_anniv(t) |
Attained age just after the anniversary |
(none) |
policy_term |
Years from issue to omega_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 |
(contracts) |
policy_count |
Contracts the model point stands for |
av_initial |
av_pp_init() |
AV entering month 0, the sum of the SA_i; 0 on new business |
(SA_i at entry) |
sa_pp_init(i) |
SA_i entering month 0, the sa_pp_init_<i> column |
gwb_initial |
gwb_pp_init() |
GWB entering month 0 |
bb_initial |
bb_pp_init() |
Bonus Base entering month 0 |
rb_initial |
rb_pp_init() |
GMDB Benefit Base entering month 0 |
(GAWA at entry) |
gawa_pp_init() |
GAWA entering month 0 |
(GAWA% at entry) |
gawa_pct_init() |
GAWA% locked by the valuation date |
(withdrawn at entry) |
has_wd_init() |
Whether a withdrawal was taken before month 0 |
(NP at entry) |
np_pp_init() |
Cumulative Net Premiums entering month 0 |
(RP at entry) |
rp_pp_init() |
Remaining Premium entering month 0 |
(ADJ at entry) |
adj_pp_init() |
GWB Adjustment entering month 0 |
(bonus end at entry) |
bonus_end_init() |
Contract year the Bonus Period ends, entering month 0 |
SumW_y at entry |
sum_wd_pp_ytd_init() |
Withdrawals in the contract year before month 0 |
(allowance used at entry) |
free_wd_used_cum_pp_ytd_init() |
Free allowance used in that year before month 0 |
(accrued d-f-d at entry) |
gmdb_dfd_acc_pp_ytd_init() |
GMDB d-f-d accrued in that year before month 0 |
(accrued factor at entry) |
gmdb_factor_acc_ytd_init() |
GMDB pro-rata factor accrued in that year before month 0 |
(withdrawal year at entry) |
wd_this_year_init() |
Whether that year took a withdrawal before month 0 |
RB at the prior anniversary |
rb_pp_prev_anniv_init() |
RB at the anniversary opening the year under way |
(quarterly AVs at entry) |
stepup_base_pp_ytd_init() |
Highest AV at that year’s quarterly anniversaries before month 0 |
(prior quarter’s phi_G) |
phi_glwb_init() |
vix rule: the last quarter’s rate before month 0 |
glwb_stepup_basis |
stepup_basis() |
annual_CV or highest_quarterly_CV |
(annual step-up) |
is_stepup_annual() |
The basis is annual_CV |
(quarterly step-up) |
is_stepup_highest_quarterly() |
The basis is highest_quarterly_CV |
(roll-up GMDB) |
is_gmdb_rollup() |
gmdb_option is rollup |
(ratchet GMDB) |
is_gmdb_ratchet() |
gmdb_option is ratchet |
(return-of-premium GMDB) |
is_gmdb_basic() |
gmdb_option is basic |
(no fee reset) |
is_fee_reset_none() |
fee_reset_rule is none |
(five-yearly fee reset) |
is_fee_reset_quinquennial() |
fee_reset_rule is quinquennial |
(VIX fee reset) |
is_fee_reset_vix() |
fee_reset_rule is vix |
(fixed roll-up) |
is_rollup_fixed() |
rollup_rule is fixed |
(CMT-linked roll-up) |
is_rollup_cmt_linked() |
rollup_rule is cmt_linked |
i |
sub_ids |
Subaccount ids, a list (an engine cell) |
(the point’s fund set) |
fund_set_number() |
Data’s number for fund_set |
(subaccounts held) |
subaccount_count() |
Subaccounts the fund set holds |
(the j-th subaccount) |
subaccount_id(j) |
Its id, in file order |
alloc[i] |
alloc(i) |
Allocation of net premium to subaccount i |
e_i |
fund_expense_rate(i) |
Annual fund expense ratio |
r_i(t) |
inv_return_mth(t, i) |
Gross monthly fund return (scenario input) |
(the point’s returns) |
return_scenario_number() |
Data’s number for its scenario_id, the returns |
(the point’s rates) |
rate_scenario_number() |
The same, the rate scenarios |
(the rate scenario) |
scenario_rate(t, name) |
Level of column name in force at month t |
(VIX-squared average) |
vix_sq(k) |
Quarterly average of daily VIX^2, quarter k |
(CMT10) |
cmt10(t) |
10-year CMT rate at month t |
m |
asset_charge_me |
M&E asset charge |
alpha |
asset_charge_admin |
Administrative asset charge |
(the growth factor) |
unit_growth(t, i) |
(1+r_i)(1-e_i/12)(1-(m+a)/12) |
V_i(t) |
(inside unit_growth) |
Unit value; see the note below |
U_i(t) |
(implicit) |
Units; see the note below |
SA_i(t) |
sa_pp(t, i) |
Subaccount value at end of month t |
SA_i at a point in the month |
sa_pp_at(t, i, timing) |
BEF_PREM, BEF_WD, BEF_INV, BEF_FEE or EOM |
AV(t) |
av_pp(t) |
Contract value at end of month t |
AV at a point in the month |
av_pp_at(t, timing) |
Same timings, summed over subaccounts |
l x AV(t) |
av_at(t, timing) |
In-force weighted contract value |
w_i(t) |
sa_weight(t, i) |
Value weight, the pro-rata deduction key |
(gross fund return) |
gross_inv_income_pp(t) |
Return before any charge |
(fund’s own expense) |
fund_expense_pp(t) |
Paid to the funds, not insurer revenue |
(M&E + admin) |
asset_charge_pp(t) |
Collected inside the unit value |
(net of both) |
inv_income_pp(t) |
Change in AV from investment over month t |
P(t) |
premium_pp(t) |
Gross premium at BOM of month t |
(single premium) |
premium_single() |
The purchase payment, in the issue month |
(scheduled premium) |
prem_scheduled_pp(t) |
Premium from transaction_table.csv |
(premium at policy month) |
prem_scheduled_pm(m) |
The programme’s premium at policy month m |
(the point’s programme) |
txn_number() |
Data’s number for txn_id |
P(t)(1 - tau) |
prem_to_av_pp(t) |
Net premium buying units |
tau |
premium_tax_rate |
Premium tax rate |
W(t) |
wd_pp(t) |
Gross withdrawal, inclusive of charges |
(W before the AV cap) |
wd_pp_due(t) |
Withdrawal requested before capping at AV |
(scheduled part of W) |
wd_scheduled_pp(t) |
Withdrawal from transaction_table.csv |
(W at policy month) |
wd_scheduled_pm(m) |
The programme’s withdrawal at policy month m |
(utilization part of W) |
wd_glwb_pp(t) |
wd_intensity x L(t) once activated |
(GLWB withdrawal month) |
is_wd_month(t) |
The utilization withdrawal falls in month t |
(a withdrawal in t) |
is_wd_taken(t) |
Any withdrawal is taken in month t |
(withdrawn by t) |
has_wd_by(t) |
A withdrawal taken at or before month t |
(the first withdrawal) |
is_first_wd(t) |
Month t takes the first withdrawal |
(withdrawal year) |
is_wd_year(t) |
The contract year of t takes a withdrawal |
L(t) |
wd_limit_pp(t) |
Annual withdrawal limit max(GAWA, RMD) |
SumW_y |
sum_wd_pp(t) |
Withdrawals to date in the contract year |
E(t) |
wd_excess_pp(t) |
Excess portion of W(t) |
N(t) |
wd_nonexcess_pp(t) |
Non-excess portion of W(t) |
CV_pre |
cv_pre_excess_pp(t) |
AV after N has been deducted |
(1 - E/CV_pre) |
excess_factor(t) |
The pro-rata factor for the excess |
(charge-free amount) |
free_wd_allow(t) |
max(earnings, 10% of RP) |
(unused allowance) |
free_wd_avail(t) |
Allowance left in the contract year |
(allowance consumed) |
wd_free_pp(t) |
Allowance used by month t’s withdrawal |
(allowance used to date) |
free_wd_used_cum_pp(t) |
Allowance used in the contract year so far |
(exempt part of W) |
wd_exempt_pp(t) |
Portion of W bearing no charge |
(chargeable part of W) |
wd_chargeable_pp(t) |
Portion of W bearing the CDSC |
c(t) |
wd_charge_pp(t) |
CDSC on the withdrawal |
W(t) - c(t) |
wd_payment_pp(t) |
Cash paid on the withdrawal |
CDSC scale |
surr_charge_rate(t) |
CDSC % by completed years since receipt |
(CDSC by year count) |
surr_charge_rate_at(k) |
The schedule’s rate at k completed years |
(the point’s scale) |
cdsc_number() |
Data’s number for cdsc_schedule |
(surrender free amount) |
surr_free_pp(t) |
Charge-free amount left for a full surrender |
(surrender chargeable base) |
surr_chargeable_pp(t) |
Remaining Premium withdrawn on surrender |
(CDSC on surrender) |
surr_charge_pp(t) |
Charge on a full surrender |
AV(t) - CDSC |
surr_benefit_pp(t) |
Surrender proceeds |
RP(t) |
rp_pp(t) |
Remaining Premium, the CDSC basis |
(premium portion withdrawn) |
rp_reduction_pp(t) |
Reduction of RP by a withdrawal |
NP(t) |
np_pp(t) |
Cumulative Net Premiums |
GWB(t) |
gwb_pp(t) |
Guaranteed Withdrawal Balance |
GWB at a point in the month |
gwb_pp_at(t, timing) |
BEF_PREM / BEF_WD / BEF_ANNIV |
(GWB after the bonus) |
gwb_pp_aft_bonus(t) |
Anniversary sub-step 3 |
(GWB after the step-up) |
gwb_pp_aft_stepup(t) |
Anniversary sub-step 4 |
b x BB |
bonus_pp(t) |
GLWB bonus credited at the anniversary |
BB(t) |
bb_pp(t) |
Bonus Base |
BB before the anniversary |
bb_pp_bef_anniv(t) |
Bonus Base the bonus is computed on |
bonus_end(t) |
bonus_end(t) |
Contract year the Bonus Period ends |
(the step-up basis) |
stepup_base_pp(t) |
Annual or highest quarterly CV |
(step-up occurred) |
is_stepup(t) |
True at a step-up anniversary |
GAWA(t) |
gawa_pp(t) |
Guaranteed Annual Withdrawal Amount |
GAWA in the month |
gawa_pp_at(t, timing) |
BEF_PREM / BEF_WD / BEF_ANNIV |
g(a) |
gawa_pct_at_age(a) |
GAWA% at attained age a |
(the point’s grid) |
gawa_grid_number() |
Data’s number for glwb_option |
gawa_pct_fixed |
gawa_pct_fixed(t) |
GAWA% locked at the first withdrawal |
ADJ(t) |
adj_pp(t) |
GWB Adjustment amount |
ADJ before the anniversary |
adj_pp_bef_anniv(t) |
ADJ carried into the anniversary events |
s |
gwb_adj_pct |
GWB Adjustment percentage, 105% |
(the Adjustment year) |
gwb_adj_year() |
Contract year of the Adjustment Date |
(the Adjustment Date) |
is_gwb_adj_date(t) |
Later of anniv on/after 70 and the 12th |
RB(t) |
rb_pp(t) |
GMDB Benefit Base |
RB in the month |
rb_pp_at(t, timing) |
BEF_PREM / BEF_WD / BEF_ANNIV |
(RB opening the year) |
rb_prior_anniv_pp(t) |
RB at the anniversary preceding t |
rho |
rollup_rate(t) |
GMDB roll-up percentage in force |
(the year’s d-f-d allowance) |
gmdb_allow_pp(t) |
rho x RB at the prior anniversary |
(d-f-d part of a withdrawal) |
gmdb_wd_dfd_pp(t) |
Dollar-for-dollar portion |
(excess part) |
gmdb_wd_excess_pp(t) |
Portion above the allowance |
(its pro-rata factor) |
gmdb_wd_factor(t) |
Proportional factor of the excess |
(accrued d-f-d) |
gmdb_dfd_acc_pp(t) |
Accrued to the end of the contract year |
(accrued pro-rata factor) |
gmdb_factor_acc(t) |
Accrued to the end of the contract year |
DB(t) |
db_pp(t) |
Gross death benefit: max(AV, NP, RB) |
max(NP, RB) |
gmdb_guarantee_pp(t) |
The floor under DB; |
GuaranteeClaim |
gmdb_claim_pp(t) |
Net general-account strain on death |
phi_G |
phi_glwb(t) |
GLWB charge rate in force |
(phi_G on the vix rule) |
phi_glwb_vix(k) |
VIX-formula rate in contract quarter k |
phi_D |
phi_gmdb(t) |
GMDB charge rate in force |
Fee_G |
fee_glwb_pp(t) |
Quarterly GLWB fee, on the GWB |
Fee_D |
fee_gmdb_pp(t) |
Quarterly GMDB fee, on the RB |
f_c |
maint_fee_pp(t) |
Annual contract fee, $35 waived at $50k |
(total unit cancellation) |
charge_pp(t) |
Fee_G + Fee_D + f_c actually collected |
(fee reset formula) |
fee_rate_vix_raw(phi0, vix2) |
The VIX-squared fee formula [S4][S6] |
(fee reset clipping) |
fee_rate_vix_clip(prior, raw) |
Band and corridor clipping [S4] |
forlife_flag |
forlife_flag() |
For Life Guarantee in effect |
depleted_flag(t) |
depleted_flag(t) |
AV has reached zero with the GLWB alive |
(depleted entering t) |
depleted_open(t) |
Depleted entering month t |
(post-depletion payment) |
glwb_payment_pp(t) |
Insurer-funded GAWA payment |
phase(t) |
phase(t) |
PRE_ISSUE, ACCUM, DEPLETED or EXPIRED |
M_G(t) |
moneyness_glwb(t) |
GWB / AV |
M_D(t) |
moneyness_gmdb(t) |
max(NP, RB) / AV |
lambda(M) |
lapse_itm_mult(ratio) |
The VM-21 7.B.1 multiplier |
lambda*(t) |
lapse_dyn_mult(t) |
min of the two, per VM-21 6.C.6 |
kappa(t) |
lapse_wd_factor(t) |
0.60 in a withdrawal year |
q^w_base(y) |
lapse_rate_base(t) |
VM-21 Table 6.3 under-50%-ITM column |
q^w_annual(t) |
lapse_rate(t) |
Annual total surrender rate |
q^w(t) |
lapse_rate_mth(t) |
Monthly total surrender rate |
q^d(t) |
mort_rate_mth(t) |
Monthly mortality rate |
(annual q_x) |
mort_rate(t) |
Annual mortality at the attained age |
(the table’s q_x) |
mort_rate_base_at(x) |
Table rate at attained age x and the sex |
(the point’s sex) |
mort_schedule() |
Data’s number for sex |
l(t-1) |
pols_if(t) |
Count at the START of month t |
l(t) |
pols_if_at(t, AFT_DECR) |
In-force at the end of month t |
l(-1) |
pols_if_init |
In force at the valuation date; 0 on new business |
l(t-1), … |
pols_if_at(t, timing) |
BEF_NB, BEF_DECR, BEF_LAPSE, AFT_DECR |
(new business) |
pols_new_biz(t) |
policy_count in the issue month |
l(t-1) q^d |
pols_death(t) |
Deaths |
l(t-1)(1-q^d) q^w |
pols_lapse(t) |
Full surrenders |
(none) |
pols_maturity(t) |
Survivors at the end of cover |
Premium income |
premiums(t) |
Premium cash flow |
Charge income - M&E/admin |
asset_charges(t) |
Asset charge cash flow |
Charge income - rider fees |
fees_glwb(t), fees_gmdb(t) |
Rider fee cash flow |
Charge income - contract fee |
maint_fees(t) |
Contract fee cash flow |
Charge income - CDSC |
wd_charges(t) |
CDSC on withdrawals (memo; see below) |
Withdrawal proceeds |
withdrawals(t) |
W(t) - c(t), weighted |
Post-depletion GLWB payments |
glwb_payments(t) |
GAWA paid after depletion |
Death benefit (gross) |
claims(t, DEATH) |
DB(t) x deaths |
Death benefit (net strain) |
gmdb_claims(t) |
GuaranteeClaim x deaths (memo) |
Surrender proceeds |
claims(t, LAPSE) |
surr_benefit_pp(t) x surrenders |
(horizon benefit) |
claims(t, MATURITY) |
Survivors in the last covered month |
Maintenance expense |
expenses(t) |
VM-21 6.C.2 prescribed expense |
(expense inflation) |
inflation_factor(t) |
1.025^(years from 2015 to the valuation date plus projection years completed) |
(acquisition) |
commissions(t) |
0 in the base run [std] |
(none) |
net_cf(t) |
The notes’ ledger, summed |
(none) |
net_cf_ga(t) |
General-account view (memo) |
Model point attributes the notes and the model name identically — sex,
designated_lives, tax_status, premium_tax_rate, glwb_option,
gmdb_option, cdsc_schedule and the rate_sheet_date Reference — are not
repeated in the table above; issue_date is not carried at all, the model working in
policy months throughout.
Nine names needed care.
pols_if(t) is the count in force at the start of month t — the notes’
l(t-1) — and is the weight applied to that same row’s cash flows, so
premiums(t) / premium_pp(t) is exactly pols_if(t) and the printed in-force column
reconciles with the row it sits on. That is the library-wide convention, set by
Term_US_S and by savings.CashValue_SE. The notes’ own end-of-month l(t)
has not gone anywhere: it is pols_if_at(t, AFT_DECR), and the roll-forward
is written across it.
lapse_rate(t) is the annual total surrender rate and lapse_rate_mth() the
monthly one, matching the mort_rate / mort_rate_mth pair. Both spellings of the
notes’ q^w are present and the suffix is the only thing that tells them apart, so
read the suffix.
wd_free_pp(t) is the portion of a withdrawal covered by the free-withdrawal
allowance, which is what the same name means on the deferred annuity chassis
(MYGA_US_S, min(W, FW)). On this product a second exemption
stacks on top of it — no CDSC applies to cumulative withdrawals within L [S1] — and
the union of the two is wd_exempt_pp(), the portion of W(t) bearing no charge
at all. The two differ by exactly wd_nonexcess_pp(), and it is
wd_exempt_pp(), not wd_free_pp(), that complements
wd_chargeable_pp(). The year-to-date cumulative is
free_wd_used_cum_pp(), named for what it is rather than sharing the wd_* stem.
E(t) is the guarantee excess here — the portion of a withdrawal above the GLWB
annual limit — and wd_excess_pp() carries that meaning. In
MYGA_US_S the same cell name means the portion of a withdrawal above
the free allowance, i.e. the charge base. On this product those are two different
quantities and both exist: the charge base is wd_chargeable_pp(). Reading
wd_excess_pp across the two models without checking is the single easiest mistake to
make in this library.
E(t) in Term_US_S is expenses, which here is expenses() as usual. M
is the in-the-moneyness ratio here and the market value adjustment in
MYGA_US_S; a VA separate account has no MVA at all, so there is no
collision in the model, only in the reader’s memory. c(t) is the CDSC here and the
Model #805 contract charge in MYGA_US_S; it becomes
wd_charge_pp(). g is the GAWA% here and the monthly nonforfeiture factor there;
it becomes gawa_pct_at_age(). And b is the GLWB bonus percentage here and the
MVA distribution yield there.
Two cells the chassis has that this model deliberately does not: mgsv_pp and
surr_value_pp. NAIC Model #805 expressly excludes variable annuities and reaches a VA
only through its fixed account under Model #250 §7.B [REG-R42][REG-R43], and this
contract has no fixed account because electing the Roll-up GMDB removes the Fixed Account
Options [S1]. There is therefore no minimum guaranteed surrender value and no pre-floor
surrender value to distinguish: surr_benefit_pp() is simply AV(t) less the
CDSC. Carrying the chassis’ floor across would be the error the chassis file itself warns
against.
The unit ledger
The notes write the account value as AV = Σ_i U_i V_i and require charges assessed
per unit of value (fund expense, M&E, administrative asset charge) to live inside
V_i, while charges assessed per contract or on a benefit base (the annual contract
fee, the two rider fees) are collected by cancelling units, leaving V_i
untouched: ΔU_i = C · w_i(t) / V_i(t), so ΔAV = C.
State carried into the frame
Every state variable in this model is a closing balance of month t: av_pp(t),
sa_pp(t, i), gwb_pp(t), bb_pp(t), rb_pp(t), gawa_pp(t), np_pp(t),
rp_pp(t) and adj_pp(t) are all values at the end of month t. Their
opening value is therefore S(t - 1), and in the first month a contract is on the
books, t_entry(), it is the model point’s S_init() instead, its column of the
opening state: every recursion reads its previous month first,
S(t - 1) if t > t_entry() else S_init(), then the month’s own steps, as
MYGA_US_SEC and FIA_US_SEC write it. That single convention replaces an
entry-instant row: the premium, the guarantee-base initialization and the acquisition
expense are all beginning-of-month flows of the issue month, where the opening state is
0, and the issue values come by VA_US_S’s own rules there. No carried-in state
is read before the first month on the books, and no cell in cover reads a month before
t_entry().
A contract in force at the valuation date carries twenty columns of opening state, per
contract, as it stands at the start of month 0, before any month-0 event, each exactly
what VA_US_S carries into that month: the two subaccount values, which
VA_US_S would split from the account value by the target allocation, wrong once
the funds drift apart; the GWB, the Bonus Base, the GAWA, the GMDB Benefit Base, the
cumulative Net Premiums, the Remaining Premium and the GWB Adjustment; the locked GAWA%,
the end of the Bonus Period and whether a withdrawal has been taken. Four quantities of
the contract year restart at its start — the withdrawals to date, the free allowance
they used, the GMDB’s dollar-for-dollar reduction and its proportional factor — and the
year under way at the valuation date opened before it on a contract valued mid-year, so
each opens at t = 0 on its _ytd_init column, as does whether that year has taken
a withdrawal, wd_this_year_init(). The Benefit Base at the anniversary that opened
the year is read three ways (rb_prior_anniv_pp()): from the frame where that
anniversary is on the books, from rb_pp_prev_anniv_init() where it precedes the
valuation date, and by the issue rule in a contract’s first year. The highest quarterly
account value of the year before the valuation month and the VIX-formula rate of the last
quarter to end before it are columns too, stepup_base_pp_ytd_init() and
phi_glwb_init(). The depleted status takes none: a contract in force enters month 0
depleted exactly where its opening account value is at or below
av_depletion_threshold, and new business never does (depleted_open()).
The model carries the product SA_i = U_i V_i rather than the two factors, because
with no transfers between subaccounts the two are never needed apart, and every quantity
the notes print is a subaccount value. The distinction the ledger exists to enforce
survives intact: a per-unit charge multiplies sa_pp through unit_growth(),
while a unit cancellation multiplies it by (1 − C / AV) — which is exactly pro-rata
deduction, and which therefore leaves every w_i unchanged.
That property is necessary for the notes’ 60/40 anchor cell to still sit at exactly
60/40 twenty-six months later, but it is not sufficient, and it would be a bad
lesson to take away on its own: unequal growth moves the weights whatever the charges
do. What closes the gap is the illustrative base path, reverse-engineered so that
the two subaccounts grow at the same rate net of fund expense (see the provenance
column of return_scenario.csv) — with equal net growth and pro-rata cancellation the
weights cannot move at all. The worked-example month itself is the counter-example:
r_1 = +1.20% against r_2 = −0.30% takes w_1 from 0.600000 at the beginning of
that month to sa_weight() = 0.603519 by the time the fees are read at its end. On
the cell issued at the valuation date the month is t = 26 — the 27th policy month —
and on the carried state in force at 26 months it is t = 0.
Timing arguments
Account and subaccount values, following CashValue_SE’s av_pp_at:
BEF_PREMAV(t-1), at the start of monthtbefore the premium — the opening balance, and in the first month on the books,t_entry(), the model point’s opening state,sa_pp_init()andav_pp_init(), which are 0 on new business.BEF_WDafter the premium has bought units, before the withdrawal.
BEF_INVAV'(t), after the withdrawal, before unit value growth.BEF_FEEafter growth, before the rider fees and the contract fee. This is the point at which the notes read the pro-rata key
w_i.EOMAV(t), after every charge. Equal toav_pp().
Guarantee bases (gwb_pp_at, gawa_pp_at, rb_pp_at) take BEF_PREM,
BEF_WD and BEF_ANNIV; their end-of-month value, after the anniversary
guarantee events, is the plain cells (gwb_pp(), gawa_pp(), rb_pp()).
BEF_PREM opens on the model point’s _init column at t_entry().
Policy counts, following CashValue_SE’s pols_if_at and
basiclife.BasicTerm_SE:
BEF_NBthe count carried in from month
t - 1, before montht’s new business:pols_if_init()att_entry(), the contracts in force at the valuation date, 0 on new business.BEF_DECRl(t-1), in force at the start of montht:BEF_NBplus that month’spols_new_biz(). Equal topols_if(t).BEF_LAPSEafter deaths,
l(t-1)(1 - q^d(t)).AFT_DECRafter surrenders,
l(t)— the notes’ end-of-month count, and equal topols_if_at(t + 1, BEF_NB)except in the last covered month, where the survivors leave aspols_maturity()instead.
Benefit kind arguments are DEATH, LAPSE and MATURITY, and ALL, the
three kinds’ total, for claims() and claims_over_av(). Any other value of any
of these raises ValueError. Each is an int code (Codes, below).
pols_maturity and the projection horizon
The technical notes state no projection horizon, and this contract does not supply one:
once the account value is exhausted the For Life Guarantee is a pure life-contingent
annuity at GAWA, which the notes rank sixth in their sensitivity list precisely because
the mortality basis then becomes the whole story. The model therefore runs to attained
age omega_age = 120 [std], the terminal age of the mortality table: cover ends at
policy month maturity_mth() = 12 * policy_term(), which is
proj_len() = maturity_mth() - duration_mth_init() months from the valuation date, and
pols_maturity(t) carries the survivors out in the last covered month,
duration_mth(t) = maturity_mth() - 1, which is t = proj_len() - 1 — zero
everywhere else — 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, including the last, where the block would otherwise appear to lose
lives with no cause. The identity is written on start-of-month counts because that is
what pols_if() carries: the next month opens on what is left, before its own new
business, and in the last covered month pols_if_at(proj_len(), BEF_NB) is zero,
every survivor of that month having left as pols_maturity(). The name follows
BasicTerm_S.pols_maturity and the construction follows Term_US_S and
MYGA_US_S. It is bookkeeping determined by the horizon, not an added
assumption.
The contract’s own Latest Income Date — the Contract Anniversary at owner age 95 [S2] — is not implemented as a forced annuitization; see the model docstring’s list of what is not implemented.
Codes
What VA_US_S spells as text, a timing, a kind, a rate scenario’s column or a
phase, 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_LAPSE |
2 |
|
AFT_DECR |
3 |
|
BEF_PREM |
4 |
the account value and the bases: the opening balance |
BEF_WD |
5 |
the account value and the bases: after the premium |
BEF_INV |
6 |
the account value: after the withdrawal, before the growth |
BEF_FEE |
7 |
the account value: after the growth, before the charges |
EOM |
8 |
the account value: closing the month |
BEF_ANNIV |
9 |
the bases: after the withdrawal, before the anniversary |
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 |
|
VIX_SQ |
0 |
|
CMT10 |
1 |
|
PRE_ISSUE |
0 |
|
ACCUM |
1 |
|
DEPLETED |
2 |
|
EXPIRED |
3 |
|
The model has three families of timing, the count’s, the account value’s and the bases’,
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
bases’ own one, each family in the order of its instants. The bases share BEF_PREM
and BEF_WD with the account value, where VA_US_S spells them alike, so each
is one Reference. 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
VA_US_S adds them in its total, and ALL, its kind=None, after them;
claims() and claims_over_av() answer ALL with VA_US_S’s chain of
+, so that the total is VA_US_S’s bit for bit, and the other claim cells
refuse it, ValueError("invalid kind"). The columns are VA_US_S’s names
upper-cased. A code a cell takes indexes that cell’s cache, a C array of ten codes a
month, since every 2-D cache of the model has one width, the timings’ count, which is the
subaccount axis’s too (spec_sec.py), so codes are numbered densely from 0, and a code
a cell does not take but below 10 is refused inside the cache; a code from 10 raises
IndexError, compiled alone. Codes are References, not cells, so the symbol map does
not list them. Every other Reference is named in lower case, the contract’s bounds among
them: issue_age_min, issue_age_max, glwb_issue_age_max and
gmdb_issue_age_max, the product’s issue ages, 35, 85, 80 and 79, and
subaccount_id_max, 9, the largest subaccount id a fund set may hold, which
proj_len() checks, the first and the last of which, with omega_age, the compiled
model’s caches are sized from.
Reporting cells
model_point(), the thirteen label accessors policy_id(), sex(),
designated_lives(), tax_status(), fund_set(), glwb_option(),
stepup_basis(), gmdb_option(), cdsc_schedule(), fee_reset_rule(),
rollup_rule(), scenario_id() and txn_id(), the reports
result_cf(), result_pols(), result_av() and result_bases(), and the
checks check_av_roll_fwd(), check_pols_roll_fwd() and
check_charge_split() are written for a reader and for the comparison with
VA_US_S, which has every one of them: a table row, text, DataFrames and three
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,
designated_lives or tax_status is blank or a number, which no cell reads, whose
glwb_stepup_basis, gmdb_option, fee_reset_rule or rollup_rule is blank,
which its decodes answer False to, or whose sex, fund_set, glwb_option,
cdsc_schedule, scenario_id or txn_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 three checks,
which may stay Python but compile to a bint, their verdict, as their per-month
residuals, *_resid, compile to a double.
Four cells compile with C signatures and dict caches, or stay Python, the engine cells
lapse_itm_mult(), fee_rate_vix_raw() and fee_rate_vix_clip(), keyed by
floats, and sub_ids(), a list: VA_US_S’s own, kept for its tests, for T1,
which compares them at the arguments VA_US_S’s tests use, and for a reader. No
projection cell calls them, and a cell keyed by a float compiles with a Python dict for a
cache, so the registry admits them by name. The projection writes the three float
engines inline in the cells that call them, lapse_dyn_mult() and
phi_glwb_vix(), in VA_US_S’s order of evaluation, and loops over the
subaccounts by position itself.
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.
- sex()[source]#
The sex of the Designated Life, M or F.
A label for reporting: the projection reads the mortality at
mort_schedule().
- mort_schedule()[source]#
The number
Datagives the point’ssex, by which its mortality is read.The row of
Data.mort_table_array. The join on the text key, made once inData(R7), whereVA_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.
- designated_lives()[source]#
singleorjoint.Reported only: the joint-life election of the modeled GLWB is out of scope in the product spec, so the GAWA% grid and the For Life test are the single-life ones [std].
- tax_status()[source]#
NQorQ.Reported only. The base run is non-qualified [std], which keeps the RMD term of
L = max(GAWA, RMD)disclosed but inactive; no RMD module is implemented.
- 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 subaccount values, the guarantee bases, the GAWA, the opening state — is the same whatever the count, and every cash flow is a per-contract amount weighted by it.VA_US_S’spols_if_initcolumn, renamed, asbasiclife.BasicTerm_SEnames it.
- pols_if_init()[source]#
l(-1): 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.VA_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.
tau: premium tax deducted from the purchase payment, 0% [std], 0-3.5% [S2].
Set to zero so that GWB at issue equals gross premium and the worked example is checkable; premium tax is contractually deducted from the amounts that initialize the guarantee bases [S1].
The single purchase payment, paid at the beginning of the issue month.
The month with
duration_mth(t) = 0, which ist_entry()on a contract issued at or after the valuation date;premium_pp()takes it there. A contract in force at the valuation date paid it before the frame, and its opening state carries what it bought.
- fund_set()[source]#
The key into fund_table.csv naming this contract’s subaccount allocation.
A label for reporting: the projection reads the set at
fund_set_number().
- fund_set_number()[source]#
The number
Datagives the point’sfund_set, by which its funds are read.The row of
Data’s fund arrays,fund_sub_ids,fund_held,alloc_arrayandfund_expense_array, the join on the text key made once inData(R7).
- subaccount_id(j)[source]#
The id of the subaccount at position
jof the point’s fund set, in file order.jruns from 0 tosubaccount_count() - 1, in the orderVA_US_S’ssub_idsreturns the ids and its sums run in, so that a loop over the positions, taking each id from here, sums the subaccounts asVA_US_Sdoes. A position outside the set raisesValueError, naming the point, and so does any position of a set holding an id pastData.read_last_sub_id, whichDatadoes not hold andproj_len()refuses first.
- sub_ids()[source]#
The subaccount ids of the model point’s allocation set, in file order, as a list.
Two subaccounts [std] — the minimum that exercises pro-rata charge allocation and unit accounting. Real contracts offer far more; one carrier’s build-your-own menu lists 76 options across 12 asset classes [S4].
VA_US_S’s cell, kept for a reader and for the comparison withVA_US_S: a list, which no C type holds, so it is an engine cell (the Space docstring’s Reporting cells), built by an explicit loop oversubaccount_id(), and no other cell calls it. Every sum over the subaccounts loops over the positions itself.
- alloc(i)[source]#
alloc[i]: the share of net premium allocated to subaccount i, no rebalancing.
Data.alloc_arrayat the point’sfund_set_number()and the subaccount idi. An id outside 1 toData.read_last_sub_id, or one the set does not hold, raisesValueError, naming the point, whereVA_US_S’s lookup raisedKeyError.
- fund_expense_rate(i)[source]#
e_i: the annual fund expense ratio of subaccount i, paid to the fund [S2].
Data.fund_expense_arrayat the point’sfund_set_number()andi, refused asalloc()refuses.
- glwb_option()[source]#
The GLWB election, and the key into the GAWA% grid;
s3_single[S3].A label for reporting: the projection reads the grid at
gawa_grid_number().
- gawa_grid_number()[source]#
The number
Datagives the point’sglwb_option, the row of its GAWA% grid.The row of
Data.gawa_pct_array, the join made once inData(R7), whichgawa_pct_at_age()reads.
- stepup_basis()[source]#
annual_CVorhighest_quarterly_CV[S1][S3].annual_CVis the representative election: the step-up test uses the Contract Value at the anniversary.highest_quarterly_CVuses the highest contract value over the four most recent Contract Quarterly Anniversaries; the source also adjusts each of those for subsequent premiums and withdrawals under the same dollar-for-dollar / proportional rule, which is not implemented — see the model docstring.A label accessor, called by no projection cell:
is_stepup_annual()andis_stepup_highest_quarterly()decode the model point’sglwb_stepup_basiscolumn, andstepup_base_pp()branches on them.
- is_stepup_annual()[source]#
Whether the step-up basis is
annual_CV, the column decoded once a point.Data.is_stepup_annual,glwb_stepup_basiscompared with"annual_CV"asVA_US_Scompares it, element by element, read at the point. Read bystepup_base_pp()whereVA_US_Scomparesstepup_basis()with the text.
- is_stepup_highest_quarterly()[source]#
Whether the step-up basis is
highest_quarterly_CV, the column decoded.Data.is_stepup_highest_quarterly,glwb_stepup_basiscompared with"highest_quarterly_CV"asVA_US_Scompares it, element by element, read at the point. Read bystepup_base_pp(); a basis that is neither of the two raisesVA_US_S’s message there.
- gmdb_option()[source]#
rollup,ratchetorbasic.rollupis the representative election:RB(t) = RB(t-1)(1 + rho)at each anniversary to the age cutoff, with a dollar-for-dollar withdrawal allowance applied at Contract Year end [S1][S3].ratchetis the annual ratchetmax(RB, AV)at each anniversary with proportional withdrawal treatment [S1][S4][S7].basicis the included no-charge proportional return of premium [S1][S2]; on that election the base is the return of premium, sonp_pp()is not floored under it as well — seegmdb_guarantee_pp(). The notes’ fourth form,combination, is not implemented — see the model docstring.A label accessor, called by no projection cell:
is_gmdb_rollup(),is_gmdb_ratchet()andis_gmdb_basic()decode the model point’sgmdb_optioncolumn, and the cells that branch on the election read them.
- is_gmdb_rollup()[source]#
Whether the GMDB election is
rollup, the column decoded once a point.Data.is_gmdb_rollup,gmdb_optioncompared with"rollup"asVA_US_Scompares it, element by element, read at the point. Read byrb_pp(),rb_pp_at(),gmdb_wd_dfd_pp()andgmdb_wd_excess_pp(), whereVA_US_Scomparesgmdb_option()with the text.
- is_gmdb_ratchet()[source]#
Whether the GMDB election is
ratchet, the annual ratchet, the column decoded.Data.is_gmdb_ratchet,gmdb_optioncompared with"ratchet"asVA_US_Scompares it, element by element, read at the point. Read byrb_pp().
- is_gmdb_basic()[source]#
Whether the GMDB election is
basic, the return of premium, the column decoded.Data.is_gmdb_basic,gmdb_optioncompared with"basic"asVA_US_Scompares it, element by element, read at the point. Read byrb_pp(),gmdb_guarantee_pp()andphi_gmdb(); an election that is none of the three raisesVA_US_S’s message inrb_pp().
- cdsc_schedule()[source]#
The key into cdsc_table.csv naming this contract’s withdrawal charge scale.
A label for reporting: the projection reads the scale at
cdsc_number().
- cdsc_number()[source]#
The number
Datagives the point’scdsc_schedule, the row of its scale.The row of
Data.surr_charge_rate_array, the join made once inData(R7), whichsurr_charge_rate_at()reads.
- fee_reset_rule()[source]#
none,quinquennialorvix.noneis the base run [std]: the insurer does not increase the rider charge and the owner does not opt out.quinquennialapplies the maximum single increase of +0.25% at each fifth Contract Anniversary up to the guaranteed maximum [S1].vixapplies a second carrier’s non-discretionary VIX-squared formula [S4][S6].A label accessor, called by no projection cell:
is_fee_reset_none(),is_fee_reset_quinquennial()andis_fee_reset_vix()decode the model point’sfee_reset_rulecolumn, andphi_glwb()branches on them.
- is_fee_reset_none()[source]#
Whether the GLWB fee reset rule is
none, the column decoded once a point.Data.is_fee_reset_none,fee_reset_rulecompared with"none"asVA_US_Scompares it, element by element, read at the point. Read byphi_glwb(), whereVA_US_Scomparesfee_reset_rule()with the text.
- is_fee_reset_quinquennial()[source]#
Whether the GLWB fee reset rule is
quinquennial, the column decoded.Data.is_fee_reset_quinquennial,fee_reset_rulecompared with"quinquennial"asVA_US_Scompares it, element by element, read at the point. Read byphi_glwb().
- is_fee_reset_vix()[source]#
Whether the GLWB fee reset rule is
vix, the column decoded once a point.Data.is_fee_reset_vix,fee_reset_rulecompared with"vix"asVA_US_Scompares it, element by element, read at the point. Read byphi_glwb(); a rule that is none of the three raisesVA_US_S’s message there.
- rollup_rule()[source]#
fixedorcmt_linked.fixedis the base run [std]: 6.00% at election ages up to 69 and 5.00% from 70 [S3].cmt_linkedis a third carrier’s formula rate, a 20-day average 10-year CMT plus 1.00% (1.50% before the first withdrawal), rounded to 0.10%, floored at 4% and capped at 8% [S7].A label accessor, called by no projection cell:
is_rollup_fixed()andis_rollup_cmt_linked()decode the model point’srollup_rulecolumn, androllup_rate()branches on them.
- is_rollup_fixed()[source]#
Whether the GMDB roll-up rule is
fixed, the column decoded once a point.Data.is_rollup_fixed,rollup_rulecompared with"fixed"asVA_US_Scompares it, element by element, read at the point. Read byrollup_rate(), whereVA_US_Scomparesrollup_rule()with the text.
- is_rollup_cmt_linked()[source]#
Whether the GMDB roll-up rule is
cmt_linked, the column decoded once a point.Data.is_rollup_cmt_linked,rollup_rulecompared with"cmt_linked"asVA_US_Scompares it, element by element, read at the point. Read byrollup_rate(); a rule that is neither of the two raisesVA_US_S’s message there.
- wd_start_age()[source]#
The attained age at which GLWB withdrawals begin; 70 in the base run [std].
Zero means the contract never withdraws. The base-run value rests on the finding that activation clusters at the RMD age [REG-R64 [unverified]][REG-R57][REG-R58]. The prescribed alternative is VM-21’s Withdrawal Delay Cohort Method, which is not implemented.
- wd_intensity()[source]#
The fraction of the annual limit withdrawn once activated; 100% [std].
100% matches VM-21 §6.C.3’s Guarantee Actuarial Present Value construction [R1]. The prescribed partial-withdrawal assumption is 90% for lifetime GMWBs and 70% for non-lifetime ones [R1].
- scenario_id()[source]#
The scenario the model point runs on, a key into the two scenario tables.
The row’s own copy of a
VA_US_Sscenario, on the valuation clock:VA_US_S’s id for a contract issued at the valuation date, and{id}-M{m}or{id}-F{k}for one in force at policy monthmor issuedkmonths later (Data.return_scenario). A label accessor, called by no projection cell:inv_return_mth()andscenario_rate()read the scenarios atreturn_scenario_number()andrate_scenario_number().
- return_scenario_number()[source]#
The number
Datagives the point’sscenario_idin the return scenarios.The row of
Data.return_array, the join made once inData(R7), whichinv_return_mth()reads.
- rate_scenario_number()[source]#
The number
Datagives the point’sscenario_idin the rate scenarios.The row of
Data.vix_sq_arrayandData.cmt10_array, whichscenario_rate()reads; 0 where the rate scenarios lack the id, whichDataaccepts on a point no level is read for andscenario_rate()refuses.
- txn_id()[source]#
The scheduled transaction programme, a key into transaction_table.csv.
A label for reporting: the projection reads the programme at
txn_number().
- txn_number()[source]#
The number
Datagives the point’stxn_id, the row of its programme.The row of
Data.prem_amount_arrayandData.wd_amount_array, the join made once inData(R7), whichprem_scheduled_pm()andwd_scheduled_pm()read.
- duration_mth_init()[source]#
Completed policy months at the valuation date, the
duration_mthcolumn.The contract’s age in months at
t = 0: 26 for the worked example’s carried state, in force at the beginning of its 27th policy month, 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.VA_US_S’sduration_mth_initcolumn, renamed;VA_US_Scan take it as 0 or as a month in force, never as a month to come.
- is_inforce()[source]#
True when the model point is in force at the valuation date, not issued at or after.
duration_mth_init() > 0: a contract issued at the valuation date, or after it, is not, and opens with no state at all. Read whereVA_US_Sreads it, to choose the Bonus Period’s end opening the frame.
- av_pp_init()[source]#
AV entering month 0, per contract: the sum of the subaccount values carried in.
sum_i sa_pp_init(i)over the set’s subaccounts, an explicit loop over the positions taking each id fromsubaccount_id(), so 0 on a contract issued at or after the valuation date.VA_US_Scarries one account value,av_init, and splits it across the subaccounts by the target allocation [std], which holds for its in-force point, exactly at its 60/40 target, and fails wherever the funds have grown apart since issue: the subaccount values are therefore the opening state here, and the account value their sum. Read byav_change()for the block’s opening value and bydepleted_open(), which reads a contract in force whose sum is at or belowav_depletion_thresholdas depleted from month 0.
- sa_pp_init(i)[source]#
SA_i entering month 0, per contract: the model point’s
sa_pp_init_<i>column.The value of subaccount
iat the start of month 0, before any month-0 event, read fromData.sa_pp_init_arrayat the point’s position and the subaccount id; 0 on a contract issued at or after the valuation date, whose premium buys its units in the issue month, and 0 for an id the point’s set does not hold.sa_pp_at()andsa_pp()open on it att_entry(), whereVA_US_Sopens onalloc(i) x av_pp_init(). An id outside 1 toData.read_last_sub_idraisesValueError, naming the point.
- gwb_pp_init()[source]#
GWB entering month 0, the
gwb_pp_initcolumn.0 on a contract issued at or after the valuation date, where the premium creates it in the issue month [S1];
VA_US_S’sgwb_initcolumn, renamed.
- gawa_pp_init()[source]#
GAWA entering month 0, the
gawa_pp_initcolumn.0 until the first withdrawal fixes it [S1], or depletion;
VA_US_S’sgawa_initcolumn, renamed. On a contract depleted at the valuation date it is the amount the GLWB pays at each contract year’s start, read byglwb_payment_pp()att = 0.
- gawa_pct_init()[source]#
The GAWA% locked by the valuation date; 0 when none has been locked.
The percentage is locked at the first withdrawal, or at depletion where the account value runs out first [S1], so a contract that depleted without withdrawing carries a percentage above 0 here with
has_wd_init()False. The column of the name, as inVA_US_S, which infers its withdrawal status from it.
- has_wd_init()[source]#
Whether a withdrawal was taken before the valuation date, the
has_wd_initcolumn.VA_US_Sinfers it fromgawa_pct_init(), which is non-zero once the GAWA% has been locked. That holds until a contract’s account value runs out before its first withdrawal: the GAWA% locks at depletion too, andVA_US_S’s own frame then keepshas_wd_byFalse. Once the account is exhausted no cash flow reads the status, but the GWB Adjustment does, to its date, voided by a withdrawal and not by a depletion, so the status is a column of its own here.Datareads it by value and ties it to the GWB Adjustment, to the year’s withdrawal flag and to the GAWA%.
- bb_pp_init()[source]#
Bonus Base entering month 0, the
bb_pp_initcolumn; it initializes at GWB [S1].VA_US_S’sbb_initcolumn, renamed; 0 on new business.
- rb_pp_init()[source]#
GMDB Benefit Base entering month 0, the
rb_pp_initcolumn.VA_US_S’srb_initcolumn, renamed; 0 on new business.
- np_pp_init()[source]#
Cumulative Net Premiums entering month 0, the
np_pp_initcolumn.VA_US_S’snp_initcolumn, renamed; 0 on new business.
- rp_pp_init()[source]#
Remaining Premium entering month 0, the
rp_pp_initcolumn; the CDSC basis [S2].VA_US_S’srp_initcolumn, renamed; 0 on new business.
- adj_pp_init()[source]#
GWB Adjustment entering month 0, the
adj_pp_initcolumn.105% of net premium at endorsement [S3], credited in the issue month, so 0 on a contract issued at or after the valuation date; 0 too once any withdrawal has voided it or its date has passed.
VA_US_S’sadj_initcolumn, renamed.
- bonus_end_init()[source]#
The contract year the Bonus Period ends, carried into the frame.
1 or more on a contract in force at the valuation date, which
Datarequires, and 0 on one issued at or after it, whose Bonus Period opens atbonus_period_years= 10 [S1] in its issue month (bonus_end()).
- sum_wd_pp_ytd_init()[source]#
SumW_y entering month 0: the withdrawals of the contract year to date, per contract.
The gross withdrawals taken in the contract year under way at the valuation date, in its months before month 0; 0 at a year’s start, where
sum_wd_pp()restarts, and on new business.sum_wd_pp()opens on it att = 0where that year opened before the valuation date;VA_US_Srestarts the sum att = 0as though every valuation were a year’s start.
- free_wd_used_cum_pp_ytd_init()[source]#
The free allowance used in the contract year to date, entering month 0.
The opening of
free_wd_used_cum_pp(), read by it and byfree_wd_avail()att = 0where the year under way opened before the valuation date; 0 at a year’s start and on new business. Part ofsum_wd_pp_ytd_init(), and it may exceed the allowance month 0 allows, which is recomputed every month from the earnings and the Remaining Premium.
- gmdb_dfd_acc_pp_ytd_init()[source]#
The GMDB dollar-for-dollar reduction accrued in the contract year to date.
Entering month 0, the opening of
gmdb_dfd_acc_pp(), read by it and bygmdb_wd_dfd_pp()att = 0where the year under way opened before the valuation date; 0 at a year’s start, off therollupelection and on new business. Part ofsum_wd_pp_ytd_init().
- gmdb_factor_acc_ytd_init()[source]#
The GMDB proportional factor accrued in the contract year to date, entering month 0.
The opening of
gmdb_factor_acc()att = 0where the year under way opened before the valuation date: the product of the year’s withdrawal factors so far, 1 at a year’s start and below 1 only after an excess withdrawal in the year. 0 on new business, which has no opening state and opens the factor at 1 in its issue month, a year’s start.
- wd_this_year_init()[source]#
Whether the contract year under way took a withdrawal before the valuation month.
The
wd_this_year_initcolumn.is_wd_year()answers True for that year from it, the months beforet = 0being off the books, and scans the months on the books for the rest;VA_US_S’s scan starts att = 0. False at a year’s start and on new business.
- rb_pp_prev_anniv_init()[source]#
RB at the anniversary that opened the contract year under way at the valuation date.
The GMDB Benefit Base at the close of month
year_open_mth(0), before the valuation date, the base of the year’s dollar-for-dollar allowance, whichrb_prior_anniv_pp()reads where that anniversary precedes the books. In the first policy year it is the issue value, the premium credited at issue, and at a year’s start it equalsrb_pp_init(), the two being one instant;Datachecks both.VA_US_Sreadsrb_pp_at(0, BEF_WD)there instead, wrong wherever a premium was credited after the anniversary and before the valuation month. 0 on new business.
- stepup_base_pp_ytd_init()[source]#
The highest account value at the year’s quarterly anniversaries before month 0.
The largest of the account values at the ends of the contract year’s quarterly anniversary months that closed before the valuation month, 0 where none has, on any step-up basis, as the generator writes it; only
stepup_base_pp()reads it, on thehighest_quarterly_CVbasis alone, taking it into the step-up base at the anniversary closing the year under way, and at no other.VA_US_Sleaves out every quarter beforet = 0. 0 before the year’s first quarterly anniversary and on new business; on the highest-quarterly basis aboveav_depletion_thresholdfrom it on a contract not depleted, whichproj_len()checks.
- phi_glwb_init()[source]#
The VIX-formula GLWB charge rate of the last contract quarter before month 0.
On the
vixfee rule, the rate of the quarter before the one under way at the valuation date, the clip’s prior for that quarter’s rate, whichphi_glwb_vix()reads;VA_US_Srecurses the rate from the first quarter instead, through VIX fixings before the frame. 0 in the first contract quarter, off the rule and on new business.
- maturity_mth()[source]#
The policy month at which cover ends:
12 * policy_term().The first policy month past cover, at attained age
omega_age= 120 [std], so the last covered month ismaturity_mth() - 1, 719 at issue age 60. It isVA_US_S’s 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(): 720 for a contract issued att = 0at issue age 60, 694 for the worked example’s carried state in force at 26 months, 1 for a contract valued in its last policy month, and 735 for one to be issued 15 months after the valuation date. The frame ist = 0, 1, ..., proj_len() - 1, soproj_len()is the exclusive end of the projection andlen(result_cf()) == proj_len().VA_US_Scomputes the same number,12 * policy_term() - duration_mth_init(), on every point it can project.First the contract’s bounds, each a Reference, set before the model computes anything, and each refusal naming the point, its value and the Reference that would admit it, in this order: an issue age below
issue_age_min, 35, the GLWB’s youngest (product-spec.md, Eligible ages), from which the compiled model’s caches are sized (spec_sec.py), so that lowering it needs the spec recomputed and the model rebuilt; aboveissue_age_max, 85, the base contract’s oldest; aboveglwb_issue_age_max, 80, the GLWB’s oldest, which every point carries; abovegmdb_issue_age_max, 79, the add-on GMDB’s oldest, on the two elected forms,rollupandratchet, thebasicform, included at no charge, having none; and a fund set holding a subaccount id abovesubaccount_id_max, 9, the subaccount axis of every compiled cache, which needsData.read_last_sub_idraised with it, the spec recomputed and the model rebuilt. Each sizes nothing else.VA_US_Sprojects a point past each bound, given the tables to read it with, so each is a refusalVA_US_Slacks.Then a point at or past the end of cover at the valuation date has no frame, and raises here, naming the point, rather than projecting nothing: an in-force extract should not carry it. So does a point issued at or past
omega_age, whose cover from issue is empty, which the ages refuse first unlessissue_age_maxis raised past it.And so, on a contract in force, does an opening state that no contract can be in by a rule needing a Reference of this Space, which
Datacannot read, each refusal naming the point, in this order:depleted, its account value carried in,
av_pp_init(), at or belowav_depletion_threshold, that account value is 0 to within 1e-8: a contract that opens depleted has its account released in month 0 with no flow, socheck_av_roll_fwd(), atcheck_tol_ava contract, would miss by any more;VA_US_S’s depletions close on roundings of the order of 1e-14;not depleted, its account value carried in,
av_pp_init(), aboveav_depletion_threshold, a contract that has not withdrawn has no GAWA% locked: the percentage locks at the first withdrawal or at depletion, and before either the GAWA is 0 too, whichDataties to it;depleted without a withdrawal, it has one above 0, the grid’s at the age it ran out at, unless its grid gave 0% at an attained age it reached before the valuation month,
Data.gawa_pct_zero_by_point()at the point, read here and nowhere else;on the
highest_quarterly_CVbasis, not depleted and three months or more into its contract year, its step-up history,stepup_base_pp_ytd_init(), is above the threshold: depletion is absorbing, so every quarter end of the year before the valuation month closed above it;on the
vixfee rule, in its second contract quarter,duration_mth3 to 5, the VIX prior,phi_glwb_init(), is the first quarter’s rate,phi_glwb_curr; and from the third the prior is at mostvix_corridor_hiand, wherephi_glwb_curris at or abovevix_corridor_loand the corridor runs upward, at leastvix_corridor_lo, sincefee_rate_vix_clip()holds every rate after the first at most at the corridor’s top, and, from a first rate at or above its foot, at least at the foot.
The other refusals of the opening state are
Data’s, as the table is read.
- duration_mth(t)[source]#
Policy months already elapsed at the start of month t.
duration_mth_init() + t, 0-based liketitself:duration_mth(t) = 0is the first policy month, the issue month. The ordinal policy month — the notes’ “the 27th policy month” — isduration_mth(t) + 1. Negative before issue on a contract issued after the valuation date.
- 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 subaccount values, the guarantee bases, the statuses and the year to date from the model point’s opening state, which is 0 on new business; and the year’s quarterly history, its opening Benefit Base and the VIX fee’s prior read the frame only where it is at or after this month. 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 balance, every charge and every rate, every flag isFalse, and no table is read at a policy month, a contract year or an attained age the contract does not have.
- age_at_anniv(t)[source]#
The attained age just after the Contract Anniversary at the end of month t.
x + y, one more thanage(), and the age the GMDB growth cutoff and the Bonus Period restart cutoff are stated against [S1].
- contract_quarter(t)[source]#
k(t): the contract quarter containing month t, 1-based: 1 in months 0 to 2.
- is_anniv(t)[source]#
True at the end of a Contract Anniversary month.
The anniversary falls at the end of month t, when
duration_mth(t) + 1elapsed policy months is a whole number of years. False outside cover, tested first, whereVA_US_Steststagainst its frame.
- is_quarterly_anniv(t)[source]#
True at a Contract Quarterly Anniversary, at the end of month t [std].
False outside cover, tested first, where
VA_US_Steststagainst its frame.
- is_year_start(t)[source]#
True in the first month of a contract year, where SumW_y resets [S1].
False outside cover, tested first, where
VA_US_Stestst >= 0.
- 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, at whose end the anniversary falls;titself whereis_anniv()is true. It lies at most 11 months aftert, inside the frame, since cover ends at the close of a contract year.lapse_wd_factor()reads the withdrawal year there, the one read in the model that reaches pastt + 1.
- 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 precedes the year,t - 1in a year’s first month. Beforet = 0for the year under way at the valuation date on a contract valued in force mid-year, and before the issue month in a contract’s first year, sorb_prior_anniv_pp()andstepup_base_pp()read the frame at it only where it is at or aftert_entry().
- t_of_month(m)[source]#
The projection index t of the policy month with m months elapsed.
mis 0-based, likeduration_mth():t_of_month(0)is the first policy month, the issue month. It is negative for a policy month before the valuation date, and no cell reads a month it gives beforet_entry():is_wd_year()takes the year’s first month as the lower bound of its scan, clipped att_entry(), andvix_sq()is read only for quarters on the books.
- phase(t)[source]#
The phase at month t, a code: PRE_ISSUE, ACCUM, DEPLETED or EXPIRED.
PRE_ISSUEbefore issue andEXPIREDfrom the end of cover, outside cover; in coverDEPLETEDonce the account value has run out with the GLWB alive andACCUMbefore.VA_US_S’s labels, each an int Reference here (R10, the Space docstring’s Codes), and a leaf: no cell, report or check reads it, the projection’s state beingdepleted_flag().
- inv_return_mth(t, i)[source]#
r_i(t): the gross monthly fund return of subaccount i, a scenario input.
Read from return_scenario_sec.csv as a step function of
t, the valuation month, so a flat path is one row per subaccount: the return is the last row of the point’s scenario at or beforetfor subaccounti. A market path runs in calendar time, shared by every point of a block, so each row of the model point table reads its own copy ofVA_US_S’s path, re-based to its months in force (Data.return_scenario), and the copy of a contract issued at the valuation date isVA_US_S’s own, its policy month beingt. VM-21 requires each variable subaccount to be mapped to a crafted proxy fund, normally a linear combination of recognized market indices [R1]; the model takes the return series as an input rather than hard-coding one.Dataholds the scenarios step-filled by valuation month,Data.return_array, at the rowreturn_scenario_number()gives the point’sscenario_id, the column of subaccount idiand the month, toData.read_last_mth, 1,141, the last a read reaches; a month past it, which no projection reads, raises, naming the point, and so does an id outside 1 toData.read_last_sub_id.VA_US_Sreads a month before the scenario’s first row at its issue month,max(duration_mth(t), 0). Here a month with no row at or before it raises, naming the point (Data.return_first_mths):Datarefuses a point whose scenario sets no return for a subaccount of its fund set by its first month on the books, and no cell reads the return outside cover, so the raise is the guard behind that refusal.
- scenario_rate(t, name)[source]#
Step-function lookup of column
namein the model point’s rate scenario.Each row of rate_scenario_sec.csv states the level that holds from its own valuation month — the file’s 0-based
tcolumn — until the next row of the same scenario, so a flat path is one row, keyedt = 0for a contract on the books at the valuation date. Each row of the model point table reads its own copy ofVA_US_S’s path, re-based to its months in force, asinv_return_mth()reads the returns.Dataholds the scenarios step-filled by valuation month,Data.vix_sq_arrayandData.cmt10_array, at the rowrate_scenario_number()gives the point’sscenario_id, toData.read_last_mth; a month past it, which no projection reads, raises, naming the point. A month with no row at or before it raises, naming the point (Data.rate_first_mths):Datarefuses a point on thevixfee or thecmt_linkedroll-up whose scenario sets no level by its first month on the books, and only those read it.nameis the column’s code,VIX_SQorCMT10,VA_US_S’s"vix_sq"and"cmt10"upper-cased; any other raisesValueError("invalid name").
- vix_sq(k)[source]#
The quarterly average of daily VIX-squared for contract quarter k [S4][S6].
Read at the last month of the quarter, which is the month with
3k - 1elapsed policy months. Used only by thevixfee reset rule.
- cmt10(t)[source]#
The 20-day average 10-year Constant Maturity Treasury rate at month t [S7].
Used only by the
cmt_linkedroll-up rule.
- unit_growth(t, i)[source]#
The monthly unit value factor of subaccount i.
(1 + r_i(t)) x (1 - e_i/12) x (1 - (m + alpha)/12)— a monthly discretization of a daily accrual [std] [S2]. The fund’s own expense and the base contract asset charge live inside the unit value; charges assessed per contract or on a benefit base do not, and are collected by cancelling units instead. Do not additionally compound daily: pick one discretization and document it, because reconciling to an admin system requires knowing which was used.
- sa_pp_at(t, i, timing)[source]#
SA_i at month t read at the point given by
timing; see the Space docstring.A withdrawal and a unit cancellation both scale the subaccount by
(1 - amount / AV)— pro-rata deduction — so neither moves the value weights.BEF_PREMis the opening balance of month t: the model point’ssa_pp_init()in the first month on the books,t_entry(), andsa_pp(t - 1, i)after it.EOMissa_pp()itself, which carries the month’s steps one cell a month. 0.0 outside cover and once the contract is depleted entering the month,depleted_open().
- sa_pp(t, i)[source]#
SA_i(t): the value of subaccount i per contract at the end of month t.
The chain of the subaccount, one cell a month: the opening balance,
sa_pp(t - 1, i), orsa_pp_init()att_entry(), read first, then the month’s steps in the notes’ order — the premium bought atalloc(i), the withdrawal and the charges cancelling units pro rata, the growth in between — each assa_pp_at()computes it.VA_US_Sreadssa_pp_at(t, i, EOM), which readssa_pp(t - 1, i), two cells a month. 0.0 outside cover and once the contract is depleted entering the month.
- av_pp_at(t, timing)[source]#
AV at month t read at the point given by
timing: the sum over subaccounts.An explicit loop over the positions of the point’s set, each id from
subaccount_id(), whereVA_US_Ssums a generator oversub_ids: the same sum, in the same order.
- av_pp(t)[source]#
AV(t): the contract value per contract at the end of month t.
The sum of
sa_pp()over the set’s subaccounts, an explicit loop over the positions, asav_pp_at()sums, which isav_pp_at(t, EOM); 0.0 outside cover.
- sa_weight(t, i)[source]#
w_i(t): the value weight of subaccount i, the pro-rata deduction key [S2].
Read at
BEF_FEE, where the notes read it: after the month’s growth and before the charges that cancel units.
- gross_inv_income_pp(t)[source]#
The gross fund return over month t, before any charge.
An explicit loop over the positions, as
av_pp_at()sums; 0.0 outside cover and once the contract is depleted entering the month.
- fund_expense_pp(t)[source]#
The funds’ own expense collected inside the unit value.
Σ_i SA_i(1 + r_i) e_i/12. Not insurer revenue — it is paid to the underlying funds — so it never enterscharge_income()ornet_cf(). An explicit loop over the positions; 0.0 outside cover and once the contract is depleted entering the month.
- asset_charge_pp(t)[source]#
The M&E and administrative asset charge collected inside the unit value.
Σ_i SA_i^{pre-charge}(t) (m + alpha)/12where the pre-charge value is net of the fund’s own expense, which is deducted first insideunit_growth(). This is insurer charge income. An explicit loop over the positions; 0.0 outside cover and once the contract is depleted entering the month.
- inv_income_pp(t)[source]#
The change in AV over month t from investment, net of both per-unit charges.
AV(BEF_FEE) - AV(BEF_INV), and identicallygross_inv_income_pp - fund_expense_pp - asset_charge_pp. 0.0 outside cover.
- prem_scheduled_pm(m)[source]#
The gross premium the point’s programme schedules at policy month
m, else 0.Data.prem_amount_arrayat the rowtxn_number()gives the point’stxn_idand policy monthm, 0.0 at a month the programme has no row for, asVA_US_S’s exact-key lookup answers it: a month with no row takes nothing. The key is the elapsed policy month, on the policy clock, as transaction_table.csv states it. The table’s one reader of the premium;prem_scheduled_pp()calls it in cover only. A month below 0 is no row, 0.0, before the array is read; one pastData.read_last_mth, which no projection reads, raises, naming the point.
- prem_scheduled_pp(t)[source]#
The gross premium scheduled for month t in transaction_table.csv, else zero.
The file’s
tcolumn is the elapsed policy month, so the key isduration_mth(t), read throughprem_scheduled_pm(); the programme stays on the policy clock. 0.0 outside cover.
P(t): the gross premium paid at BOM of month t.
The model point’s single purchase payment falls at the beginning of the issue month, the one with
duration_mth(t) = 0, together with anything scheduled for that month in transaction_table.csv. The chassis is flexible-premium [S1][S2] and premium receipt is retained as an active term in every guarantee-base recursion, so a subsequent payment is a data change rather than a formula change.VA_US_Stakes the single premium att == 0, which is the issue month of its new business; a contract in force at the valuation date paid it before the frame. 0.0 outside cover and once the contract is depleted entering the month.
- prem_to_av_pp(t)[source]#
P(t)(1 - tau): the net premium that buys units and raises the guarantee bases.
The per-contract counterpart of
prem_to_av(), and the name every account-value model in this library uses for the premium credited to the account value. Not to be confused withWholeLife_US_S.premium_net_pp, which is a gross premium net of the dividend offset — a different concept entirely.
- wd_scheduled_pm(m)[source]#
The gross withdrawal the point’s programme schedules at policy month
m, else 0.Data.wd_amount_arrayat the rowtxn_number()gives the point’stxn_idand policy monthm, asprem_scheduled_pm()reads the premium: the elapsed policy month, on the policy clock. The table’s one reader of the withdrawal;wd_scheduled_pp()calls it in cover only.
- wd_scheduled_pp(t)[source]#
The gross withdrawal scheduled for month t in transaction_table.csv, else zero.
Keyed on the elapsed policy month
duration_mth(t), asprem_scheduled_pp()is, throughwd_scheduled_pm(). 0.0 outside cover.
- is_wd_month(t)[source]#
True when the GLWB utilization withdrawal falls in month t.
Base run [std]: the contract activates in the first month of the contract year in which the attained age reaches
wd_start_age(), and withdraws in the first month of every contract year thereafter.wd_start_age = 0never withdraws. False outside cover and once the contract is depleted entering the month.
- is_wd_taken(t)[source]#
True when any withdrawal is taken in month t, before its amount is known.
Stated as a predicate rather than
wd_pp(t) > 0so that the first-withdrawal test can run before the GAWA% is fixed, which is what the amount itself depends on. False outside cover and once the contract is depleted entering the month.
- has_wd_by(t)[source]#
True when a withdrawal has been taken at or before month t.
The value carried into month t is
has_wd_init()in the first month on the books,t_entry(), the model point’s own status, andhas_wd_by(t - 1)after it. False outside cover.
- is_first_wd(t)[source]#
True in the month of the contract’s first withdrawal.
The notes are explicit that this test must run before the annual limit
Lis formed: a first withdrawal tested againstGAWA = 0would score entirely as excess and wreck both benefit bases [S1]. The status carried in is read ashas_wd_by()reads it, fromhas_wd_init()att_entry().
- is_wd_year(t)[source]#
True when any withdrawal falls in the contract year containing month t.
Drives the VM-21 withdrawal-year surrender factor
kappa[R1] and the rule that any withdrawal in a Contract Year kills that year’s bonus [S1].The year’s months on the books are scanned by an explicit loop, from its first month, or
t_entry()if later, to its last inside the frame; where the year opened before the valuation date, its months beforet = 0are the model point’swd_this_year_init(), which answers True for the year by itself.VA_US_Sscans fromt = 0, as though no year had begun before its frame. It is read at a year’s last month only, bybonus_pp()at the anniversary and bylapse_wd_factor()atanniv_mth(), so the scan reaches no month after its own. Called at another month of the year, as C4’s full sweep calls every cell at every month, it answers the same and scans the year’s months after it, inside the frame: a read pastt + 1that no cell of the model makes. False outside cover.
- gawa_pct_at_age(a)[source]#
g(a): the GAWA% for attained age a, from gawa_pct_table.csv [S3].
The band starting at the largest
age_fromat or belowa,Data.gawa_pct_arrayat the rowgawa_grid_number()gives the point’sglwb_optionand the age; 0.0 below the grid’s first band,VA_US_S’s value there, and at a negative age, before the array is read. Called in cover only, atage(). The array holds ages toData.read_last_age, 120; an older age reads the rate there where the grid’s last band starts at or below it, since every age from that band on reads its rate, and raises, naming the point, where the last band starts past it, which no projection reads.
- wd_limit_pp(t)[source]#
L(t) = max(GAWA, RMD): the annual withdrawal limit governing month t [S1].
At the first withdrawal the GAWA is fixed on the pre-withdrawal GWB, so the limit is formed from that. The RMD term is disclosed but inactive: the base run is non-qualified and no RMD module is implemented. 0.0 outside cover.
- wd_pp_due(t)[source]#
The gross withdrawal requested at BOM of month t, before capping at AV.
Scheduled withdrawals add to the utilization withdrawal, which is how a model point exercises the excess algebra without disturbing the base run. 0.0 outside cover and once the contract is depleted entering the month.
- wd_pp(t)[source]#
W(t): the gross amount removed from the contract value at BOM of month t.
Measured inclusive of withdrawal charges, MVAs, advisory fees and every other charge for all guarantee calculations [S1]; using net proceeds would understate the benefit-base reduction. Capped at the available contract value [std].
Each operand of the
minthat calls a cell is a local, assigned inVA_US_S’s order of evaluation, left to right, since a compiledminormaxevaluates its arguments right to left: so a point that reaches two refusals raisesVA_US_S’s first in both engines.
- sum_wd_pp(t)[source]#
SumW_y: cumulative withdrawals in the current contract year, including W(t) [S1].
Restarts at 0 in a contract year’s first month. Where the year under way at the valuation date opened before it, the sum carried into
t = 0is the model point’ssum_wd_pp_ytd_init();VA_US_Srestarts the sum att == 0as though a year began there. 0.0 outside cover.
- wd_excess_pp(t)[source]#
E(t) = min(W, SumW_y - L) if SumW_y > L else 0: the excess withdrawal [S1].
This is the guarantee excess, not the charge base — see the Space docstring’s note on the divergence from
MYGA_US_S.
- cv_pre_excess_pp(t)[source]#
CV_pre: the contract value after the non-excess portion has been deducted [S1].
The order is decisive: the non-excess portion reduces the base dollar-for-dollar first, and the proportional factor for the excess is computed against the contract value after that reduction. Reversing it changes both GWB and GAWA.
- free_wd_allow(t)[source]#
The charge-free amount at month t: earnings first, then 10% of Remaining Premium.
The notes state it as
max(0, AV - RP)plusmax(0, 0.10 RP - earnings), which ismax(earnings, 0.10 x RP)[S1]. Aged-out premium is free too, which the CDSC scale delivers by reaching 0.0% at seven completed years [S2]. The Remaining Premium carried into the month isrp_pp_init()att_entry(). 0.0 outside cover.
- free_wd_avail(t)[source]#
The free-withdrawal allowance still unused in the contract year at BOM of month t.
The allowance used before the month is 0 in a contract year’s first month,
free_wd_used_cum_pp(t - 1)after it, and att = 0, where the year under way opened before the valuation date, the model point’sfree_wd_used_cum_pp_ytd_init();VA_US_Stakes 0 att == 0. 0.0 outside cover.
- wd_free_pp(t)[source]#
The free-allowance portion of month t’s withdrawal:
min(FW, E(t)).The chassis name for the same thing —
MYGA_US_Shasmin(W, FW)— differing only in that here the allowance is applied to the guarantee excess rather than to the whole withdrawal, because the non-excess portion is already exempt from the CDSC under the within-Lrule [S1]. The portion ofW(t)bearing no charge at all is therefore the widerwd_exempt_pp(), not this cell.Each operand of the
minthat calls a cell is a local, assigned inVA_US_S’s order of evaluation, left to right, since a compiledminormaxevaluates its arguments right to left: so a point that reaches two refusals raisesVA_US_S’s first in both engines.
- free_wd_used_cum_pp(t)[source]#
The free allowance consumed so far in the contract year, including month t.
The year-to-date cumulative of
wd_free_pp(), reset at each contract year start; it is whatfree_wd_avail()andsurr_free_pp()net off. Where the year under way at the valuation date opened before it, the cumulative carried intot = 0is the model point’sfree_wd_used_cum_pp_ytd_init(). 0.0 outside cover.
- wd_exempt_pp(t)[source]#
The portion of W(t) bearing no withdrawal charge at all.
Two exemptions stack: no CDSC applies to cumulative withdrawals within L [S1], which covers the non-excess portion outright, and the free-withdrawal allowance covers part of what is left. So this is identically
wd_nonexcess_pp(t) + wd_free_pp(t), and it — notwd_free_pp()— is what complementswd_chargeable_pp().Each operand of the
minthat calls a cell is a local, assigned inVA_US_S’s order of evaluation, left to right, since a compiledminormaxevaluates its arguments right to left: so a point that reaches two refusals raisesVA_US_S’s first in both engines.
- wd_chargeable_pp(t)[source]#
The portion of W(t) exposed to the CDSC:
max(0, E(t) - free allowance).
- surr_charge_rate_at(k)[source]#
The withdrawal charge rate of the point’s schedule at
kcompleted years.Data.surr_charge_rate_arrayat the rowcdsc_number()gives the point’scdsc_scheduleandmin(k, last), wherelastis the schedule’s last year,Data.cdsc_last_years: the last row holds for every later year, asVA_US_Scaps the year at the table’s largest. The table’s one reader;surr_charge_rate()calls it in cover only, atduration(). A count below 0 raisesValueError, naming the point, whereVA_US_S’s lookup raisedKeyError; so does a year past the 95 the array holds,Data.read_last_mth // 12, which no projection reads.
- surr_charge_rate(t)[source]#
The CDSC rate at month t, read off the contract duration [S2].
The scale runs 8.5% down to 0.0% at seven completed years and is read from cdsc_table.csv, keyed by
duration(), throughsurr_charge_rate_at().The notes key it on completed years since receipt of the premium being withdrawn [S2], which coincides with the contract duration only while the contract is single premium. It is not implemented by premium tranche:
rp_pp()carries Remaining Premium as one undifferentiated pool, so a subsequent premium does not restart its own charge clock — model point 4 pays a second premium in its 73rd policy month, with 72 elapsed, and is read at that contract’s 6-completed-year band rather than at the new tranche’s 8.5%. Named in the model docstring’s and the README’s not implemented lists and pinned by a test; splitting the pool needs a withdrawal-ordering rule across tranches that no retrieved source states. 0.0 outside cover.
- surr_chargeable_pp(t)[source]#
The Remaining Premium withdrawn on a full surrender, net of the free amount [S2].
Each operand of the outer
minthat calls a cell is a local, assigned inVA_US_S’s order of evaluation, left to right, since a compiledminormaxevaluates its arguments right to left: so a point that reaches two refusals raisesVA_US_S’s first in both engines.
- surr_benefit_pp(t)[source]#
Surrender proceeds:
AV(t)less the CDSC.There is no nonforfeiture floor under this value. NAIC Model #805 expressly excludes variable annuities and reaches a VA only through its fixed account under Model #250 §7.B [REG-R42][REG-R43], and electing the Roll-up GMDB removes the Fixed Account Options [S1]. Contrast
MYGA_US_S, wheremax(SV, MGSV)is the whole point.
- phi_glwb(t)[source]#
phi_G: the annual GLWB rider charge rate in force in month t.
1.25% of the GWB currently [S3], guaranteed maximum 3.00% [std] within an observed 1.20%-3.00% band by option and vintage [S1].
fee_reset_ruleselects the reset mechanism; the base run does not increase the charge and the owner does not opt out [std], because opting out forfeits bonus, step-up and GWB Adjustment and blocks future premium [S1], so a rational opt-out is a joint decision rather than an independent lapse-style rate. The rule is read through its decodes,is_fee_reset_none(),is_fee_reset_quinquennial()andis_fee_reset_vix(), inVA_US_S’s order. 0.0 outside cover.
- fee_rate_vix_raw(phi_0, vix_sq_avg)[source]#
The unclipped VIX-squared fee formula [S4][S6].
phi_0 + 0.05% x [ QuarterlyAverage(daily VIX^2) / 33 - 10 ]. The disclosed examples are an initial 1.45% with a quarterly average of 204.42 giving 1.26%, and 602.30 giving an unclipped 1.86%.VA_US_S’s cell, an engine cell (the Space docstring’s Reporting cells), called by no other:phi_glwb_vix()writes it inline.
- fee_rate_vix_clip(prior, raw)[source]#
Clip a VIX-formula rate to the movement band and the absolute corridor [S4].
The band is +/-0.40% annualized against the prior quarter’s rate (advisory class) and the corridor is [0.60%, 2.50%]. The second disclosed example clips to 1.82% against a prior rate of 1.42%.
VA_US_S’s cell, an engine cell, called by no other:phi_glwb_vix()writes it inline.
- phi_glwb_vix(k)[source]#
The VIX-formula GLWB charge rate in contract quarter k [S4][S6].
phi_glwb_currin the first quarter; after it, the formula’s rate for the quarter’s VIX-squared average, clipped against the prior quarter’s rate. The prior isphi_glwb_vix(k - 1), one cell a quarter, except in the quarter under way at the first month on the books, where it is the model point’sphi_glwb_init(): the quarters before it are off the books, andVA_US_Srecurses through them from the first. That quarter ismax(duration_mth_init(), 0) // 3 + 1, a key the model point fixes, which iscontract_quarter(t_entry())read without a clock (R2). No quarter before it is read.VA_US_S’sfee_rate_vix_raw()andfee_rate_vix_clip(), written inline (R14), in the orderVA_US_S’s call evaluates them: the prior, then the quarter’s VIX-squared average, then the raw rate, then the clip, eachminandmaxwith its operands asfee_rate_vix_clip()writes them. Avix_divisorof 0 raises Python’sZeroDivisionError("float division by zero")after the average is read, whereVA_US_S’s division raises it, since a compiled division by 0 raises with another message.
- phi_gmdb(t)[source]#
phi_D: the annual GMDB rider charge rate in force in month t.
0.90% of the GMDB Benefit Base currently, guaranteed maximum 1.80% [S2][S3]. The
basicdeath benefit is included at no charge [S1][S2], so the rate is zero there, read throughis_gmdb_basic(). 0.0 outside cover.
- rollup_rate(t)[source]#
rho(t): the GMDB roll-up percentage credited at the anniversary ending month t.
fixedis the base run [S3].cmt_linkedis a third carrier’s formula rate: the 10-year CMT plus 1.00%, or 1.50% before the first withdrawal, rounded to 0.10%, floored at 4% and capped at 8% [S7]. The rule is read through its decodes,is_rollup_fixed()andis_rollup_cmt_linked(). 0.0 outside cover.VA_US_Srounds withmath.floor(raw / step + 0.5) * step. Here the floor is the float floor division by 1.0,v // 1.0, which ismath.floor(v)as a float for every finitevin both engines, exactly, so no number moves and no module is read;VA_US_S’s three refusals are written out in its order, acmt_round_stepof 0,ZeroDivisionError("float division by zero"), then avthat is NaN,ValueError("cannot convert float NaN to integer"), or infinite,OverflowError("cannot convert float infinity to integer"), each with Python’s message.
- fee_glwb_pp_due(t)[source]#
Fee_G = (phi_G/4) x GWB at a Contract Quarterly Anniversary [S1][S3].
The base is the benefit base, not the account value — putting the rider fee on account value is the most common and most consequential error on this product. The fee therefore rises as markets fall, until the account reaches zero, at which point it stops [S4]. 0.0 outside cover and once the contract is depleted entering the month.
- fee_gmdb_pp_due(t)[source]#
Fee_D = (phi_D/4) x RB at a Contract Quarterly Anniversary [S2][S3].
The charge base is the GMDB Benefit Base; the quarterly frequency aligns it with the GLWB fee [std], the research file recording quarterly for the GMWB family only. 0.0 outside cover and once the contract is depleted entering the month.
- maint_fee_pp_due(t)[source]#
f_c: the $35 annual contract fee, waived at a contract value of $50,000 or more.
Assessed at the Contract Anniversary and deducted proportionally across investment divisions [S2]. The waiver is tested on the contract value after the rider fees [std], the notes placing the contract fee after them in the processing order. 0.0 outside cover and once the contract is depleted entering the month.
- charge_pp_due(t)[source]#
The total unit cancellation due at EOM before capping at the contract value.
- charge_scale(t)[source]#
The fraction of the charges due that the contract value can actually pay [std].
Charges are collected only up to the available contract value; the shortfall is not carried forward. This binds in at most one month per contract, the one in which the account is exhausted, and it is what makes
check_av_roll_fwd()close there.
- charge_income_pp(t)[source]#
Insurer charge income per contract in month t.
The asset charge collected inside the unit value plus the charges collected by unit cancellation. The funds’ own expense is not included — it is paid to the funds.
- gwb_pp_at(t, timing)[source]#
GWB at month t read at
BEF_PREM,BEF_WDorBEF_ANNIV[S1].BEF_PREMis the opening balance of month t: the model point’sgwb_pp_init()in the first month on the books,t_entry(), andgwb_pp(t - 1)afterwards. Once the contract is depleted entering the month every timing is that opening balance. 0.0 outside cover.
- bb_pp_bef_anniv(t)[source]#
The Bonus Base carried into the anniversary events of month t [S1].
Increased by net premium, set to
min(GWB_after, BB_before)on an excess withdrawal, and otherwise unaffected by withdrawals. Applying the bonus does not change it. The base carried into the month isbb_pp_init()att_entry(). 0.0 outside cover.
- bonus_pp(t)[source]#
The GLWB bonus credited at the Contract Anniversary ending month t.
b x BBif no withdrawal was taken in the contract year and the year is within the Bonus Period [S1]. Any withdrawal kills the whole year’s bonus, including an automatic withdrawal or an RMD; pro-rating it for a partial year is wrong. The Bonus Period’s end carried into the first month on the books is the model point’sbonus_end_init()on a contract in force at the valuation date, andbonus_period_yearson one issued at or after it.
- stepup_base_pp(t)[source]#
The contract value the step-up test is made against [S1][S3].
annual_CV: the Contract Value at the anniversary.highest_quarterly_CV: the highest contract value over the four most recent Contract Quarterly Anniversaries, the anniversary month itself and the three quarter ends before it.On the highest-quarterly basis the quarter ends on the books, at or after
t_entry(), are read from the frame by an explicit loop, and at the anniversary closing the contract year under way at the valuation date — the one whose year opened beforet_entry(),year_open_mth(t) < t_entry()— the quarter ends before the valuation month are the model point’sstepup_base_pp_ytd_init(), their largest account value.VA_US_Sleaves out every quarter end beforet = 0. The basis is read through its decodes,is_stepup_annual()andis_stepup_highest_quarterly(). 0.0 outside cover.
- is_stepup(t)[source]#
True when the anniversary step-up fires: the contract value exceeds the GWB [S1].
- gwb_pp_aft_stepup(t)[source]#
GWB after anniversary sub-step 4, the step-up.
The [std] order — bonus first, then step-up — gives
max(GWB_old + bonus, AV); the reverse givesmax(GWB_old, AV) + bonus, which is strictly more generous. The research file does not settle the interaction, and the choice made here follows the one design in the set that states it explicitly [S8]. Treat the alternative as a first-order sensitivity, not a rounding issue.Each operand of the
maxthat calls a cell is a local, assigned inVA_US_S’s order of evaluation, left to right, since a compiledminormaxevaluates its arguments right to left: so a point that reaches two refusals raisesVA_US_S’s first in both engines.
- gwb_adj_year()[source]#
The contract year of the GWB Adjustment Date [S1].
The later of the anniversary on or after the Designated Life’s 70th birthday and the 12th Contract Anniversary.
- adj_pp_bef_anniv(t)[source]#
ADJ carried into the anniversary events of month t [S1][S3].
Initialized at 105% of net premium at endorsement, increased by
s x P(1-tau)for premiums before the first anniversary after endorsement and byP(1-tau)for later ones, and voided without value by any earlier partial withdrawal.“Before the first anniversary after endorsement” is the first twelve policy months,
duration_mth(t) < 12. The Adjustment carried into the first month on the books is the model point’sadj_pp_init(). 0.0 outside cover.
- adj_pp(t)[source]#
ADJ(t): the GWB Adjustment amount at the end of month t; 0 once it terminates.
The chain of the Adjustment, one cell a month: the Adjustment carried in,
adj_pp(t - 1)oradj_pp_init()att_entry(), read first, thenadj_pp_bef_anniv()’s steps inline, whereVA_US_Sreads that cell, which readsadj_pp(t - 1), two cells a month. 0.0 outside cover.
- gwb_pp(t)[source]#
GWB(t): the Guaranteed Withdrawal Balance at the end of month t [S1].
Anniversary sub-steps 5 to 7 finish here: the GWB Adjustment Date test, which raises the GWB to the Adjustment only if no withdrawal has ever been taken, and the $10,000,000 cap. In the depleted state the balance is run down by each payment when the For Life Guarantee is not in effect, and is left alone when it is. The balance carried in,
gwb_pp(t - 1)orgwb_pp_init()att_entry(), is read first, so a cold call walks the chain one cell a month. 0.0 outside cover.
- bb_pp(t)[source]#
BB(t): the Bonus Base at the end of month t [S1].
A step-up sets it to
max(GWB_after_step-up, BB_before); the bonus itself never changes it. The base carried in,bb_pp(t - 1)orbb_pp_init()att_entry(), is read first. 0.0 outside cover.
- bonus_end(t)[source]#
The contract year in which the Bonus Period ends [S1].
Ten Contract Years from the endorsement effective date, restarting on each Bonus-Base-increasing step-up occurring on or before the anniversary following the Designated Life’s 80th birthday. A hard-coded 10-year window from issue materially understates the guarantee in rising markets. The end carried into the first month on the books is
bonus_end_init()on a contract in force at the valuation date andbonus_period_yearson one issued at or after it. The int 0 outside cover.
- gawa_pct_fixed(t)[source]#
The GAWA% locked at the first withdrawal; 0 until then [S1].
If the contract value reaches zero with the percentage not yet fixed, it is fixed at the percentage for the attained age at that moment [S1]. The percentage carried into the first month on the books is the model point’s
gawa_pct_init(). 0.0 outside cover.
- gawa_pp_at(t, timing)[source]#
GAWA at month t read at
BEF_PREM,BEF_WDorBEF_ANNIV[S1].BEF_PREMis the opening balance of month t: the model point’sgawa_pp_init()in the first month on the books,t_entry(), andgawa_pp(t - 1)after it; the withdrawal status and the GAWA% carried in are read the same way, fromhas_wd_init()andgawa_pct_init()there. 0.0 outside cover.Each operand of the excess’s
minthat calls a cell is a local, assigned inVA_US_S’s order of evaluation, left to right, since a compiledminormaxevaluates its arguments right to left: so a point that reaches two refusals raisesVA_US_S’s first in both engines.
- gawa_pp(t)[source]#
GAWA(t): the Guaranteed Annual Withdrawal Amount at the end of month t [S1].
After the first withdrawal, both the bonus and the step-up raise it to
max(g x GWB, GAWA). If the For Life Guarantee is not in effect andGWB < GAWAat a Contract Year end, GAWA is set equal to GWB. The amount carried in,gawa_pp(t - 1)orgawa_pp_init()att_entry(), is read first. 0.0 outside cover.
- np_pp(t)[source]#
NP(t): cumulative Net Premiums, a floor under the death benefit [S1].
Updated by premium only, as the notes’ state table has it: it is never reduced for a withdrawal. Under the
rollupandratchetelections it is therefore an unreduced floor beneathDB. Undergmdb_option = "basic"the elected form is itself the proportional return of premium — carried onrb_pp(), which does fall with a withdrawal — and this cell is not layered over it, or the election would have no effect at all. Seegmdb_guarantee_pp(). The amount carried into the first month on the books is the model point’snp_pp_init(). 0.0 outside cover.
- rp_reduction_pp(t)[source]#
The premium portion of month t’s withdrawal, earnings coming out first [std].
The sources state that Remaining Premium falls by “withdrawals of premium including withdrawal charges” [S2] and that earnings come out free first [S1], but give no algebra; this is the reading that makes the two consistent. The Remaining Premium carried into the month is
rp_pp_init()att_entry(). 0.0 outside cover.
- rp_pp(t)[source]#
RP(t): Remaining Premium, the basis the CDSC is charged on [S2].
The amount carried in,
rp_pp(t - 1)orrp_pp_init()att_entry(), is read first. 0.0 outside cover.
- rb_prior_anniv_pp(t)[source]#
RB at the Contract Anniversary preceding month t, the d-f-d allowance base [S1].
That anniversary is the end of the month with
12(y - 1) - 1elapsed policy months,year_open_mth(t)on the valuation clock, and the base is read three ways. From the frame,rb_pp()there, where that month is on the books, at or aftert_entry(). On a contract in force at the valuation date whose year under way opened before it, from the model point’srb_pp_prev_anniv_init(). And in the first contract year of a contract issued at or after the valuation date, byVA_US_S’s issue rule: the Benefit Base after the premium taken at the beginning of the issue month,rb_pp_at(t_entry(), BEF_WD).VA_US_Sreads that last value wherever the anniversary precedes its frame, which is wrong on a contract in force once a premium has been credited after the anniversary and before the valuation month. 0.0 outside cover.
- gmdb_allow_pp(t)[source]#
The contract year’s dollar-for-dollar GMDB withdrawal allowance [S1].
rho x RBat the previous anniversary. Withdrawals inside it reduce the Benefit Base dollar for dollar; anything above it reduces it proportionally.
- gmdb_wd_dfd_pp(t)[source]#
The dollar-for-dollar portion of month t’s withdrawal against the allowance [S1].
The allowance already used in the year is 0 in its first month,
gmdb_dfd_acc_pp(t - 1)after it, and att = 0, where the year under way opened before the valuation date, the model point’sgmdb_dfd_acc_pp_ytd_init();VA_US_Stakes 0 att == 0. Only therollupelection,is_gmdb_rollup(), reduces dollar for dollar. 0.0 outside cover.Each operand of the outer
minthat calls a cell is a local, assigned inVA_US_S’s order of evaluation, left to right, since a compiledminormaxevaluates its arguments right to left: so a point that reaches two refusals raisesVA_US_S’s first in both engines.
- gmdb_wd_excess_pp(t)[source]#
The portion of month t’s withdrawal above the GMDB d-f-d allowance [S1].
On the
rollupelection,is_gmdb_rollup(); 0.0 on the others and outside cover.
- gmdb_wd_factor(t)[source]#
The proportional factor month t’s excess GMDB withdrawal accrues [std].
The notes say the adjustment above the allowance is “proportional to the contract value reduction from the excess” but leave the base unstated. The model measures it the same way the GLWB does: against the contract value after the dollar-for-dollar portion has been deducted.
- gmdb_dfd_acc_pp(t)[source]#
The dollar-for-dollar reduction accrued so far in the contract year [S1].
GMDB withdrawal adjustments are applied at Contract Year end, not at the withdrawal; applying them immediately changes the base the roll-up compounds on. Restarts at 0 in a contract year’s first month; where the year under way at the valuation date opened before it, the accrual carried into
t = 0is the model point’sgmdb_dfd_acc_pp_ytd_init(). 0.0 outside cover.
- gmdb_factor_acc(t)[source]#
The proportional factor accrued so far in the contract year [std].
Restarts at 1 in a contract year’s first month; where the year under way at the valuation date opened before it, the factor carried into
t = 0is the model point’sgmdb_factor_acc_ytd_init(). 1.0 outside cover, no change.
- rb_pp_at(t, timing)[source]#
RB at month t read at
BEF_PREM,BEF_WDorBEF_ANNIV.The
rollupform accrues its withdrawal adjustment and applies it at the Contract Year end; theratchetandbasicforms reduce the base proportionally at the withdrawal itself [S1].BEF_PREMis the opening balance, the model point’srb_pp_init()att_entry()andrb_pp(t - 1)after it. 0.0 outside cover.
- rb_pp(t)[source]#
RB(t): the GMDB Benefit Base at the end of month t.
Growth cutoffs are age-based, not duration-based: roll-up and ratchet growth stop at the Contract Anniversary preceding the oldest Covered Life’s 81st birthday [S1], so an issue-age-60 cell gets 20 roll-up credits and an issue-age-75 cell gets 5. The base carried in,
rb_pp(t - 1)orrb_pp_init()att_entry(), is read first, and the election through its decodes,is_gmdb_rollup(),is_gmdb_ratchet()andis_gmdb_basic(), inVA_US_S’s order. 0.0 outside cover.
- gmdb_guarantee_pp(t)[source]#
The guarantee actually floored under the death benefit [S1].
max(NP(t), RB(t))under therollupandratchetelections, exactly as the notes’DB = max(AV, NP, RB)reads: thereNPis the included return of premium andRBthe separately elected base, and the two are different guarantees.Under
basicthey are the same guarantee — the elected form is the return of premium — and the notes’ two tables then contradict each other. The GMDB form table reduces itG <- G x (1 - W/AV_pre), “proportional, not dollar-for-dollar”, while the state table updatesNPby premium alone. Layering the unreducedNPover the reduced base would make the emphasized rule unreachable and the election a dead switch, so on that election the elected form governs alone [std]. The README section The basic GMDB election and the unreduced NP floor sets out the conflict and the choice;np_pp()still carries cumulative net premiums, and a test pins the difference on model point 9. The election is read throughis_gmdb_basic().Each operand of the
maxthat calls a cell is a local, assigned inVA_US_S’s order of evaluation, left to right, since a compiledminormaxevaluates its arguments right to left: so a point that reaches two refusals raisesVA_US_S’s first in both engines.
- db_pp(t)[source]#
DB(t) = max(AV(t), NP(t), RB(t)): the gross death benefit outflow [S1].
Zero once the contract value has reached zero with the GLWB in force: all other endorsements terminate without value and no death benefit is payable on subsequent death [S1].
Each operand of the
maxthat calls a cell is a local, assigned inVA_US_S’s order of evaluation, left to right, since a compiledminormaxevaluates its arguments right to left: so a point that reaches two refusals raisesVA_US_S’s first in both engines.
- gmdb_claim_pp(t)[source]#
max(0, max(NP, RB) - AV): the net general-account strain on death [S1].Project
DB(t)as the outflow and derive this as the strain — never the reverse, never both. Projecting only the guarantee excess understates gross benefit outgo and breaks reconciliation with statutory exhibits; projecting both double counts.
- forlife_flag()[source]#
Whether the For Life Guarantee is in effect from issue [S1].
True when the Designated Life is 59 1/2 or older. On an age-nearest-birthday basis an ANB of 60 is exactly an actual age of 59 1/2 or more, so the test is
age_at_entry() >= 60with no approximation [std].
- depleted_open(t)[source]#
Whether the contract enters month t depleted: the status at the start of the month.
depleted_flag(t - 1)after the first month on the books, and in it, att_entry(), derived from the opening state: a contract in force at the valuation date enters month 0 depleted exactly where its account value carried in,av_pp_init(), is at or belowav_depletion_threshold, and new business never does. The status is exact so:depleted_flag()is absorbing, and from the month after it is set every subaccount is held at 0, so at each month end the flag is set exactly where the account value is at or below the threshold.VA_US_Sreadsdepleted_flag(t - 1)wherever this is read, belowt = 0in its first month. False outside cover.
- depleted_flag(t)[source]#
True once the contract value has reached zero with the GLWB in force [S1].
Absorbing: once set it never clears. The threshold is half a cent [std] — the charge cap in
charge_scale()and the withdrawal cap inwd_pp()both drive the account to zero, or to a rounding of either sign about it, of the order of 1e-14, so the threshold only guards floating point. In the first month on the books the status carried in isdepleted_open(), read from the opening account value, the threshold’s test, which reads such a rounding as depleted. False outside cover.
- glwb_payment_pp(t)[source]#
The insurer-funded GLWB payment in month t once the contract is depleted [S1].
With the For Life Guarantee in effect, GAWA is paid for the life of the Designated Life. Without it, payments continue until the earlier of death and GWB depletion, the final one truncated to the remaining GWB. The notes place the routine at BOM and the payment “at each Contract Anniversary”; the model pays it at the BOM of the first month of each contract year [std], the instant just after the anniversary, which keeps it on the same clock as the pre-depletion withdrawals.
The GAWA and the GWB paid on are those carried into the month:
gawa_pp(t - 1)andgwb_pp(t - 1), and att_entry()the model point’sgawa_pp_init()andgwb_pp_init(), which is where a contract in force and depleted at the valuation date, valued at a contract year’s start, takes its first payment.VA_US_Sreadst - 1there, below its frame. 0.0 outside cover.
- mort_rate_base_at(x)[source]#
The table’s annual mortality rate at attained age
xand the model point’s sex.Data.mort_table_arrayat the rowmort_schedule()gives the point’ssexand the column of agemin(x, top), wheretopis the table’s last age,mort_last_age(), asVA_US_Scaps the age at the table’s largest. 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. An age outside the sex’s rates, which no projection reads, raisesValueErrornaming the point, whereVA_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, 120.
- mort_rate(t)[source]#
The annual mortality rate at the attained age and sex, from mort_table.csv.
The shipped table is an illustrative annuitant curve [std], not a published basis. The prescribed basis is the 2012 IAM Basic Table improved to December 31, 2017 on Projection Scale G2, generational, with no further improvement in the projection [R1][REG-R59]; it may not be redistributed here, so swap it in by repointing
Data.mort_table_filebefore the model computes anything. Do not use CSO or VBT life tables — annuitant mortality is a different and generally lighter basis [REG-R59].The rate is the table’s, read at
mort_rate_base_at(), with no factor applied, as inVA_US_S, so no rate past 1 can arise and none is capped;Datarefuses a rate outside 0 to 1, a blank or text one among them. 0.0 outside cover, before the table is read.
- lapse_rate_base(t)[source]#
q^w_base(y): VM-21 Table 6.3’s “under 50% ITM” column [std] [R1].
4.0% p.a. during the surrender-charge period (contract years 1 to 7 here [S2]), 25.0% in the first year after it, 15.0% thereafter. 0.0 outside cover.
- moneyness_gmdb(t)[source]#
M_D(t) = max(NP(t), RB(t)) / AV(t): the death-benefit moneyness ratio [R1].
Measured on the guarantee actually floored under
DB, not onRBalone.
- lapse_itm_mult(ratio)[source]#
lambda(M): the VM-21 §7.B.1 Alternative Methodology multiplier [R1].
min[U, max(L, 1 - Mult (M - D))]with U = 1.00, L = 0.50, Mult = 1.25, D = 1.10 — the only closed-form dynamic lapse formula the Valuation Manual publishes for VAs. Note that it floors suppression at 50% while Table 6.3’s own ITM grading implies an 84% suppression; compose one or the other, never both.VA_US_S’s cell, an engine cell, called by no other:lapse_dyn_mult()writes it inline. Its parameter isratio,VA_US_S’sm, sincespec_sec.pysizes a cache bym, a policy month, and a parameter it sizes would compile to C.
- lapse_dyn_mult(t)[source]#
lambda*(t) = min(lambda(M_G), lambda(M_D)) [R1].
The contract carries both a VAGLB and a GMDB, and VM-21 §6.C.6 directs that such contracts use the lower of the two ITM-based rates. 1.0 outside cover, no adjustment;
VA_US_Sreads the multiplier there of an empty account’s moneyness.VA_US_S’slapse_itm_mult()of each moneyness, written inline (R14), its operands inVA_US_S’s order: the GLWB’s moneyness and its multiplier first, asVA_US_S’s call evaluates its first argument first, then the GMDB’s, each clampmin(lapse_itm_upper, max(lapse_itm_lower, raw))aslapse_itm_mult()writes it, so that a NaN meets the bound it meets there. So no compiled cell calls the engine cell, keyed by a float.
- lapse_wd_factor(t)[source]#
kappa(t): 0.60 in any contract year with a projected withdrawal, else 1.00 [R1].
Whether the contract year takes a withdrawal is a property of the year, so it is read once, at the month closing the year,
is_wd_year(anniv_mth(t)), up to 11 months aftertand inside the frame: the same value asVA_US_S’sis_wd_year(t), which scans the whole year fromton, a read the model admits only at the anniversary. The year’s answer there rests on no count, no decrement and no later month. 1.0 outside cover, no adjustment.
- lapse_rate(t)[source]#
q^w_annual(t) = min[1, base x lambda* x kappa] [std] composition [R1].
The annual total surrender rate;
lapse_rate_mth()is the monthly one, the pair matchingmort_rate()/mort_rate_mth(). Zero whenever the contract value is zero: the prescribed surrender assumption for a GMWB contract atAV = 0is 0% [R1]. This is the single most important behavioural assumption on the product, because it determines how many deeply in-the-money contracts persist to become claims. The bound of 1 isVA_US_S’s, written first as there, and binds only where a base rate is set above 1, the two multipliers being at most 1. 0.0 outside cover.
- pols_if(t)[source]#
The in-force count at the start of projection month t, after its new business.
pols_if_at(t, BEF_DECR): the notes’l(t-1), and the weight applied to montht’s cash flows, so that thepols_ifcolumn ofresult_cf()reconciles with the row it sits on:premiums(t) / premium_pp(t)is exactlypols_if(t). This is the library-wide convention, set byTerm_US_Sand bysavings.CashValue_SE. In the issue month it is the count issued,pols_new_biz(), and on a contract in force at the valuation date it opens month 0 atpols_if_init().The notes’ own end-of-month
l(t)ispols_if_at(t, AFT_DECR). The two coincide —pols_if_at(t + 1, BEF_NB) == pols_if_at(t, AFT_DECR)— everywhere but the last covered month, where the survivors leave aspols_maturity()and nothing is in force at the start of the month after it.
- pols_if_at(t, timing)[source]#
In-force at month t read at
BEF_NB,BEF_DECR,BEF_LAPSEorAFT_DECR.BEF_NBis the count carried in from montht - 1, before montht’s new business, the chain of the count, one cell a month:pols_if_init()att_entry(), and(BEF_NB(t-1) + pols_new_biz(t-1)) x (1 - q^d) x (1 - q^w)after it, asbasiclife.BasicTerm_SErolls it.BEF_DECRadds the month’s new business and ispols_if(t). Then the order is the notes’l(t) = l(t-1)(1 - q^d(t))(1 - q^w(t))— death first, then surrender [std] — andAFT_DECRis the notes’l(t), the end-of-month count.VA_US_Srollspols_if(t)throughpols_if_at(t - 1, AFT_DECR), two cells a month. 0.0 outside cover at every timing.
- pols_new_biz(t)[source]#
New business in month t:
policy_count()in the issue month, else 0.The month with
duration_mth(t) == 0, which ist_entry()on a contract issued at or after the valuation date; a contract in force at it has no new business, its count entering aspols_if_init()instead. Asbasiclife.BasicTerm_SEtakes it, the issued count joinsBEF_NBto makeBEF_DECR, before the month’s decrements.
- pols_death(t)[source]#
Deaths in month t, on the contracts in force at the start of it.
0.0 outside cover.
- pols_lapse(t)[source]#
Full surrenders in month t, on the survivors of mortality; 0.0 outside cover.
- pols_maturity(t)[source]#
Survivors carried out at the end of cover; zero in every other month.
Not a decrement — the projection runs out — but needed for the in-force roll-forward to close; see the Space docstring. The month is the last covered one,
duration_mth(t) == maturity_mth() - 1, a test on the policy clock, whereVA_US_Stestst == proj_len() - 1.
- claim_pp(t, kind)[source]#
The benefit paid per contract in month t by
kind.DEATHis the gross death benefitdb_pp().LAPSEis the surrender proceedssurr_benefit_pp().MATURITYis the surrender value of the survivors at the projection horizon.
- claim_from_av_pp(t, kind)[source]#
The contract value released per contract by a claim of
kind.Always
AV(t): the separate account gives up the account value, and whatever the guarantee adds on top is general-account money, reported asclaims_over_av(). The kind is tested by a chain of==, whereVA_US_Stests it in a tuple.
Premium income in month t, weighted by the contracts in force at the start of it.
In the issue month
pols_if(t)is the count issued,pols_new_biz(), so the purchase payment on that row needs no special case; a later scheduled premium falls on every contract still in force. 0.0 outside cover.
- prem_to_av(t)[source]#
Net premium credited to the block’s contract value in month t; 0.0 outside cover.
- asset_charges(t)[source]#
Charge income from the M&E and administrative asset charge, in-force weighted.
0.0 outside cover.
- maint_fees(t)[source]#
Charge income from the annual contract fee, in-force weighted; 0.0 outside cover.
- wd_charges(t)[source]#
The CDSC collected on withdrawals, in-force weighted — a memo line.
The notes’ ledger lists the withdrawal charge twice: once as charge income
c(t)and once as a deduction inside withdrawal proceedsW(t) - c(t). Counting both double-counts it.withdrawals()carries the net proceeds intonet_cf()and this line reports the charge separately. 0.0 outside cover.
- charge_income(t)[source]#
Total insurer charge income in month t, excluding the double-counted CDSC.
- glwb_payments(t)[source]#
Insurer-funded post-depletion GLWB payments, weighted by
pols_if(t).0.0 outside cover.
- claims(t, kind)[source]#
Benefit outgo in month t, for one
kindor, withALL, all three.ALLisVA_US_S’skind=None, its totalVA_US_S’s chain of+in its order, so that the total isVA_US_S’s bit for bit (the Space docstring’s Codes).
- claims_over_av(t, kind)[source]#
Benefit paid less the contract value released,
claims - claims_from_av.On death this is exactly the GMDB guarantee claim — the general-account strain. On a surrender it is negative by the withdrawal charge, which the separate account keeps. A reconciliation quantity, never a ledger line of its own.
ALL,VA_US_S’skind=None, is the three kinds’ total,VA_US_S’s chain of+.
- gmdb_claims(t)[source]#
The net general-account strain on death,
GuaranteeClaim x deaths— a memo.0.0 outside cover.
- commissions(t)[source]#
Acquisition commission; 0 in the base run [std], the notes not modelling it.
Premium tax deducted from the purchase payment, 0% [std] [S2].
- inflation_factor(t)[source]#
The VM-21 §6.C.2 expense inflation factor for the projection year containing t.
1.025^(valuation year - 2015 + t // 12)[R1]: the years from the expense base year to the valuation date, then the whole years of the projection, so that every point’s maintenance expense in monthtis in the same valuation-date dollars, however old the contract.VA_US_Scounts the contract’s own years instead,duration(t), which ist // 12on a contract issued at the valuation date and mixes the two clocks on any other.The exponent is an int, so a base below 0 gives a real power in both engines. Where Python’s float power raises, the cell raises Python’s message, which a compiled
powwould not: a base of 0 to a negative power,inflation_rate-1 and a valuation year before the base year,ZeroDivisionError; and a power past the largest float from a finite base,OverflowError. That last is Python’s own float power, called where the compiledpowgives an infinity, so that its message is the platform’s,Numerical result out of rangeon Linux andResult too largeon Windows, as Python’s is; modelx never reaches it, its own power raising first.
- expenses(t)[source]#
VM-21 §6.C.2 prescribed maintenance expense [R1].
[100 x 1.025^(valuation year - 2015)]/12per contract per month, inflating 2.5% a year, plus 7 basis points of projected account value for a company-administered block. Acquisition expense is not modelled in the base run [std]; when it is, it falls at the beginning of the issue month, the one withduration_mth(t) = 0, alongside the purchase payment, per contract issued.VA_US_Scharges it att == 0, which on its point in force at the valuation date is not the issue month. 0.0 outside cover.
- net_cf(t)[source]#
The technical notes’ cash flow ledger, summed with the notes’ own signs.
Premium income and every charge income line are positive; the gross death benefit, surrender and horizon proceeds, withdrawal proceeds, post-depletion GLWB payments and maintenance expense are negative. Note what this is not: because a VA’s separate account is legally segregated, this line mixes separate-account movements (premium in, benefits out) with transfers into the general account (the charges), and it omits investment return entirely, so it does not reconcile to the account value.
net_cf_ga()is the insurer’s own view;check_av_roll_fwd()is the account-value identity.
- net_cf_ga(t)[source]#
The general-account view: charge income less guarantee strain and expenses.
The notes require both the gross death benefit and the net general-account strain and say they are not interchangeable. This line assembles the net one: charge income, less the GMDB guarantee claim, less insurer-funded post-depletion GLWB payments, less expenses, commissions and premium tax. It is the memo, not the ledger.
- av_at(t, timing)[source]#
The in-force weighted contract value at month t; see
av_pp_at().Every timing inside the month is weighted by the contracts in force at the start of it,
pols_if(t).EOMis weighted bypols_if_at(t + 1, BEF_NB)— the count still in force once the month’s decrements have gone, before the next month’s new business — which is zero in the last covered month, where the survivors leave aspols_maturity()and their contract value is released throughclaims_from_av().The contract value carried into the frame,
av_pp_init() x pols_if_init(), is not a row of this cell: it is the opening valueav_change()uses in the first month on the books, which is what makescheck_av_roll_fwd_resid()close there. 0.0 outside cover, beforet + 1is read.
- inv_income(t)[source]#
Investment income credited to the block’s contract value in month t.
0.0 outside cover.
- wd_from_av(t)[source]#
The contract value released by month t’s withdrawals, gross of the charge.
0.0 outside cover.
- charges_from_av(t)[source]#
The contract value cancelled by month t’s per-contract and benefit-base charges.
0.0 outside cover.
- av_change(t)[source]#
The change in the block’s contract value over month t.
The opening value is the carried-in
av_pp_init() x pols_if_init()in the first month on the books,t_entry()— 0 on new business, whose purchase payment is the month’s net premium in — andav_at(t - 1, EOM)after it. 0.0 outside cover.
- check_av_roll_fwd_resid(t)[source]#
Contract value roll-forward residual; zero to floating point in every covered month.
AV(t) - AV(t-1) = net premium in - withdrawals out + investment income net of the per-unit charges - the charges collected by unit cancellation - the contract value released by each claim kind. The cash paid on a death may exceed the contract value released; that excess isclaims_over_av()and is not part of this identity. In the first month on the booksAV(t-1)is the carried-inav_pp_init(), so a purchase payment appears on that row as net premium in.The signed residual, for a debugging session that wants to know where the identity fails;
check_av_roll_fwd()is the library-wide boolean over allt. 0.0 outside cover.
- check_av_roll_fwd()[source]#
True when the contract value roll-forward closes at every projected month.
No argument and a
boolreturn, followingsavings.CashValue_SEand the library-wide convention, so one test can call the same check across every model. The per-month signed residual 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 isVA_US_S’s 1e-6 of a currency unit on a contract value of order 1e5. A loop that stops at the first month out of bounds; a residual that is not a number fails, as it failsVA_US_S’s strict bound, since no comparison with NaN is true.
- check_pols_roll_fwd_resid(t)[source]#
In-force roll-forward residual; zero to floating point in every covered month.
pols_if(t) - pols_if_at(t + 1, BEF_NB) = deaths + surrenders + horizon survivors, written on the start-of-month countspols_if()carries: the next month opens on what is left, before its own new business. In the last covered month the next month’s count is zero andpols_maturity()absorbs the survivors. 0.0 outside cover, beforet + 1is read;VA_US_Sguards only belowt = 0.
- check_pols_roll_fwd()[source]#
True when the in-force roll-forward closes at every projected month.
No argument and a
boolreturn;check_pols_roll_fwd_resid()is the signed per-month residual. In-force is a probability of order 1 per contract, so the tolerance ischeck_tol_pols, 1e-12, timesmax(policy_count(), 1). A loop that fails a residual that is not a number, ascheck_av_roll_fwd()does.
- check_charge_split_resid(t)[source]#
Residual of the investment identity; zero to floating point in every covered month.
gross fund return = fund expense + asset charge + the change in AV from investment. It is the guard against the charge-base confusion the notes call the most consequential error on this product: M&E and admin are on account value, the rider fees on benefit bases, the contract fee per contract and the CDSC on Remaining Premium — four bases in one stack. 0.0 outside cover.
- check_charge_split()[source]#
True when the investment identity closes at every projected month.
No argument and a
boolreturn;check_charge_split_resid()is the signed per-month residual, measured per contract, so the tolerance,check_tol_charge, 1e-8, does not scale with the count. A loop that fails a residual that is not a number, ascheck_av_roll_fwd()does.
- result_cf()[source]#
Result table of cashflows, indexed by valuation month
t = 0 .. proj_len() - 1.Row
t = 0is the valuation month, the same month for every model point, so the frames of a block sum row by row. A contract issued at or after the valuation date carries its purchase payment at the beginning of its issue month,t_entry(), and zeros before it; every row carries its month’s own growth, charges and decrements. Thepols_ifcolumn is the count in force at the start of each month and is the weight carried by every cash flow on that row, so the two reconcile.
- result_pols()[source]#
Result table of in-force movements, indexed by valuation month t.
pols_ifopens the month, after its new business, whichpols_new_bizshows beside it, the count issued in the issue month; the three decrement columns take contracts out of it, andpols_if_aft_decr— the notes’l(t)— closes it. Rows therefore read across:pols_if - pols_death - pols_lapse - pols_maturityis the next row’spols_if, less that row’s new business.