The Projection Space#
The by-contract projection of the DIA_US_SEC model.
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[18]
is an ItemSpace projecting the table’s nineteenth row, model point 19, the worked-example
anchor cell in force 241 months at the valuation date, one month into its income phase,
and point_id() is its label:
>>> Projection[18].result_cf() # one row per month from the valuation date
>>> Projection[18].result_pols() # the counts and survival behind it
>>> Projection[18].point_id() # 19, the row's point_id
>>> Projection[0].result_annual() # the worked example, issued at t = 0
>>> Projection.idx = 7 # or switch the default, before it computes
Switch the default, or set any Reference, before the model computes anything. 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, pricing_iters
or a code, truncates toward zero, and an int set on a float Reference reads as a float
(products/deferred_income_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 DIA_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. A formula of
DIA_US_S is rewritten where it depends on where the projection starts, where it
must answer for a month outside the frame, where it passed a policy month as t, where
it priced a premium off the projection’s survival, or where it branched on text; every
other is DIA_US_S’s own. products/deferred_income_annuity/model-sec.md lists
the rewritten cells with the reason for each. Making it compile changed how each cell
reads its inputs and spells its codes, and no number: every model point attribute a
projection cell uses is read as a number from a Data vector, each text column it
branches on as Data’s decoded flags, the two age tables as arrays by sex and age, the
two factor tables as row vectors and the premium schedule as a table by policy month,
every timing, kind, phase and pricing basis as an int code (Codes, below), and
DIA_US_S’s claims(t, kind=None) and claims_ann(y, kind=None), whose
None is the total of the two kinds, take the code ALL for it.
Input data
Inputs are external files: plain CSVs living in the model folder’s parent directory,
products/deferred_income_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
DIA_US_SEC folder without its parent’s CSVs produces a model that reads and then
fails on first evaluation.
Each table has a filename Reference and a reader Cells, both on
Data. The four assumption tables are the files DIA_US_S
reads, read in place; the model point table and the premium schedule are this model’s
own:
Reference |
Cells |
File |
|---|---|---|
model_point_file |
data.model_point_table() |
model_point_table_sec.csv |
premium_schedule_file |
data.premium_schedule_table() |
premium_schedule_sec.csv |
mort_table_file |
data.mort_table() |
mort_table.csv |
improvement_scale_file |
data.improvement_scale() |
improvement_scale.csv |
payout_factor_file |
data.payout_factor_table() |
payout_factor_table.csv |
rop_factor_file |
data.rop_factor_table() |
rop_factor_table.csv |
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 long the contract has been in force, 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 stop rule. Row t is the same month
for every point, so the frames of a block line up and sum row by row. Survival is indexed
by a time point on this clock rather than by a month: lives_if(t, life) and
lives_if_last(t) are survival at time t, the start of month t, so month
t opens at time t and closes at time t + 1, the deaths of month t are
l(t) - l(t + 1), and the arrears survival point is t + 1, as in
DIA_US_S.
duration_mth(t) counts policy months, the months elapsed from issue at the start
of month t: duration_mth(t) = duration_mth_init() + t, where
duration_mth_init() is read from the model point — positive for a contract already
in force at the valuation date, 0 for one issued at it, -k for one to be issued k
months later, at most ten years later. It is the technical notes’ month index, and
everything contractual reads it: the completed policy years
duration(t) = duration_mth(t) // 12, the contractual 1-based label
policy_year(t) = duration(t) + 1, the attained ages age(t, life), the premium
months, the income start month T, the three option months, the payment months, the
COLA anniversaries and the certain period. T, the premium months and the option months
stay policy months and are compared with duration_mth(t): converted to t they
would collide with the -1 that the option accessors return for “never”, and turn
negative on a contract past them. A cell keyed directly by this clock takes k, a
policy month or the time point that opens it, or y, a policy year, never t: the
pricing cells and the payout schedule are keyed by k, and the annual mortality rate by
y. The months from the income start month, the payout phase’s own count, are this
clock less T. No cell is keyed by them: is_payment_pm(), cola_factor_pm(),
certain_floor_pm() and annuity_pp_sched_pm() take a policy month k and
form k - T inside, so that the contract’s schedules, its premiums and its options share
one key. The anchor cell in force 241 months, point 19, is in policy year 21 at t = 0,
a month after its income start month T = 240, and point 18, the payment-acceleration
contract in force 59 months, pays its second premium at policy month 60, t = 1.
The stop rule ends every frame where it ends DIA_US_S’s: stop_mth() is
DIA_US_S’s frame length from issue, the month the youngest covered life attains
the limiting age or the end of the guarantee period if that is later, and is_active()
is 0 <= duration_mth(t) < stop_mth(). A contract’s own end inside the frame, its last
death or the end of its guarantee, is a probability or a floor reaching zero, and the
frame runs on with zeros, as DIA_US_S’s does.
Three inputs, and their clocks. Expense inflation reads the valuation clock,
inflation_factor(t) = (1 + inflation_rate) ** (t // 12), DIA_US_S’s annual
steps moved onto t, so that the maintenance charge is in valuation-date dollars for
every point alike. Mortality improvement stays on the policy clock, because it is
already calendar-dated: its exponent is the calendar year less mort_table_year, and the
calendar year issue_year() + duration(t) is the one the contract reaches whatever the
valuation date, so a contract in force reads the improvement of its own calendar years and
nothing is re-based. The commutation discount rate moves with the reference rate’s change
since issue, on one path every point shares: for a contract on the books at the valuation
date, the change to that date, which a contract in force carries in its opening state,
plus ref_rate_shift, a change made at the valuation date; for a contract issued later,
after that change, none.
On a point issued at the valuation date the two clocks coincide and this model computes
what DIA_US_S computes: every cell the two share agrees at every argument
DIA_US_S evaluates in its sweep, but for three whose meaning changed,
pols_if_init, now the count already in force at the valuation date, model_point, a
row of another table, and result_pols, which gains the month’s new business. That is
how the worked example carries over, and tests/test_model_conventions.py asserts it
cell by cell.
Counts
The count on the books is the number of contracts the point stands for,
policy_count(), from issue to the stop rule. Mortality decrements each life’s
survival, lives_if(), never the count: the two lives are independent, so their two
probabilities are the whole survival state, and every cash flow is the count times a
per-contract amount weighted by survival, as DIA_US_S weights every flow by its
constant pols_if_init. So pols_if_at(t, BEF_NB) is pols_if_init(), the
count already in force, at t_entry(), the first month on the books, the whole count
after it, and 0 outside the frame; and pols_if_at(t, BEF_DECR) adds
pols_new_biz(), the contracts issued in month t. The BEF_DECR count weights
every cash flow of row t. A contract in force at the valuation date opens with its
policy_count; one issued at or after it opens with none, and takes its
policy_count as new business in its issue month, duration_mth(t) = 0. New business
brings its premium schedule and no acquisition cost, as in DIA_US_S, which has
none.
pols_if() keeps DIA_US_S’s definition on that count: the contracts on the
books weighted by the probability that a covered life is alive at the start of month
t, pols_if_at(t, BEF_DECR) * lives_if_last(t), which carries the maintenance
expense. It is not the count before decrements, which mortality never moves: on point 20,
the period-certain point in force 300 months, pols_if(0) is 0.5577 against a count of
1.0, as DIA_US_S’s pols_if(300) is, and the registry marks the model
survival_pols_if for that reason. There is no lapse decrement, and no pols_lapse.
The opening state
A contract in force at the valuation date carries eight things its count and its policy clock do not say. Each is read from its model point as it stands at the start of month 0, before any month-0 event:
lives_if_init_1,lives_if_init_2each covered life’s probability of being alive at the valuation date,
lives_if_init(). On a real record it is 1 or 0, and a joint contract may carry one life already dead; on a point restated fromDIA_US_Sat its monthdit isDIA_US_S’slives_if(d, life), a probability. The lives are independent, as inDIA_US_S, so the two per-life probabilities are the whole survival state. Life 2 is 0 on a single-life contract.cum_premium_pp_init,annual_income_initCPandBentering month 0: the premiums paid before the valuation date and the guaranteed annual income their slices bought, a start-date adjustment already exercised included,cum_premium_pp_init()andannual_income_init().CPis the base of the death benefit and of the refund, andBof the income; the premiums still due are in the premium schedule, so the two columns and the schedule hold all of the premium history the projection reads.guarantee_mths_pricing_initon a cash or installment refund in force,
n_gas the pricing kernel takes it,guarantee_mths_pricing_init(): a fixed point over the whole premium schedule, the slices bought included, which prices every slice still to be bought and a start-date adjustment still to come. The schedule holds only the premiums still due, and the iteration depends on the path, so neither the schedule norCPandBcan recover it.surv_to_payout_initon a contract past its income start month, the cohort that reached the income phase,
l_last(T),surv_to_payout_init(), which weights every guaranteed instalment. It is not the probability that a life is alive: in a certain period the contract stays open after the last death, its guarantee running on to a beneficiary, so on point 20, in force 300 months, it is 0.715 whilelives_if_last(0)is 0.5577. On a real record in payout it is 1.commute_weight_initon a contract that commuted before the valuation month, the cohort that commuted,
l_last(t_c),commute_weight_init(), whose guaranteed instalments the commutation extinguished; the rest of the cohort that reached the income phase keeps its guarantee. On a real record of a commuted contract it is 1.ref_rate_shift_initthe reference rate at the valuation date less the reference rate at issue,
ref_rate_shift_init(): the part of the change since issue, which moves the commutation discount rate, that the contract has already seen. A fact of the market, the same for two contracts issued together.
At issue each covered life is 1, the premiums paid, the income bought and the change 0,
and the three other columns blank, so a point issued at or after the valuation date
carries those values. Each of the two frozen weights is blank where its instant, the income
start month or the commutation month, is at or after the valuation month: the projection
derives it there from the lives, DIA_US_S’s own l_last at that month.
Nothing else carries a path. The acceleration factor is read only in the exercise month,
and a contract valued after its exercise paid the lump sum before the valuation date,
its blackout months paying nothing. The commuted fraction follows from the policy clock:
the commutation is one exercise named on the model point, and there is no withdrawal. The
certain months left follow from duration_mth. And the instalments scheduled to date,
G, are a deterministic schedule fixed by the income at the income start month
(below).
Pricing on the policy clock
DIA_US_S uses one survival curve for two jobs: pricing each premium’s paid-up
slice at its own date, and projecting. On the valuation clock they part. The
projection’s survival, lives_if(), opens at the valuation date from the opening
state. Pricing stays anchored at issue and at the premium dates, deterministic from the
contract’s terms: lives_if_pm(), survival from issue to a policy time point k,
is one explicit loop from issue over the monthly rates, DIA_US_S’s recursion
unrolled, the same products in the same order, so every purchase rate, every pricing
factor and every guarantee period is DIA_US_S’s to the last bit. The monthly rate
comes from one place, mort_rate_py(), the annual rate of a policy year, which the
projection’s mort_rate() reads at the policy year of month t, so the two curves
use one rate, as DIA_US_S’s one curve did. So pricing shares the valuation’s
mortality basis, its A/E and its improvement, as DIA_US_S’s does: a mortality
sensitivity moves the purchase rate of every premium still due, and every twin’s and
future row’s guarantee period and income, while a contract in force keeps the guarantee
period it was priced with, guarantee_mths_pricing_init. Every pricing cell is keyed
by the premium’s or the exercise’s policy month k, DIA_US_S’s t renamed:
income_start_mth_at(), deferral_yrs(), surv_to_income_start(),
rop_factor_calc(), rop_factor(), annuity_factor_def() and
purchase_rate(). Pricing never reads the projection, so a cold net_cf(0) runs a
handful of cells deep where DIA_US_S’s recurses through survival to the payout
date.
The payout phase reads the income ahead of t: the installment refund’s search for its
certain period, the refund balance, the commuted value and the accelerated instalments.
On the valuation clock the income B and the cumulative premium CP are recursions,
and reading them far ahead would open a chain as long as the deferral. So the payout
schedule is fixed at the income start month, from annual_income_payout(),
B(T), and cum_premium_payout(), CP(T), each one loop over the policy months
from the valuation date’s to T, in DIA_US_S’s order. The schedule rests on
B being level from T on, which the product guarantees and Data checks: no
premium falls at or after T, and a start-date adjustment is exercised before its new
start month. annuity_pp_sched_pm() is the instalment of policy month k on that
schedule, and cum_annuity_pp() sums it, G, keyed by policy month and based at
the valuation date’s, so that the refund of a cash refund long in payout reads G from
there forward, recursing back to that key and no further.
Naming
Cells names follow lifelib’s basiclife.BasicTerm_S and savings.CashValue_SE
wherever those models have an analogue, and — for everything in the income phase — they
follow SPIA_US_S exactly, because the payout phase of a DIA is a single
premium immediate annuity. 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 and
BEF_DECR timings, codes here, is_active and result_pols.
duration_mth_init, the policy months completed at the valuation date, takes
UL_US_S’s name, and each opening-state column is <cell>_init, the cell it opens
with _init added, read per life by lives_if_init(life). t_entry and
stop_mth are the SEC family’s own. A cell keyed by policy month carries _pm, as in
SPIA_US_SEC, beside the _py that Term_US_SEC gives a policy-year key, a table
reader keyed by attained age carries _at, and a quantity fixed at the income start
month carries _payout. The is_*
decodes turn the model point’s text columns into the flags the projection branches on,
each reading and validating its column as DIA_US_S’s label accessor does, so that
no other projection cell compares text and none calls a label accessor (sex,
income_form, …), which is left to reporting. The technical notes use compact
actuarial symbols instead. The mapping is:
Notes symbol |
Cells |
Meaning |
|---|---|---|
t |
(the cells argument) |
Month from the valuation date, 0-based; time t opens month t |
k |
(the cells argument) |
Policy month, or the time point opening it, from issue |
y |
(the cells argument) |
Policy year, 1-based |
(month index) |
duration_mth(t) |
Months from issue at the start of month t |
(none) |
duration_mth_init() |
Months in force at the valuation date; -k if issued k months on |
y = duration + 1 |
policy_year(t) |
Policy year containing t |
(none) |
duration(t) |
Completed policy years |
(issue year) |
issue_year() |
Calendar year of issue |
(calendar year) |
calendar_year(t) |
Calendar year of the policy year containing t |
(none) |
t_entry() |
First month on the books |
(stopping rule) |
stop_mth() |
Policy month the frame stops |
(none) |
is_active(t) |
Whether month t is in frame |
(none) |
point_id() |
The point’s label, idx’s row |
x, x_2 |
age_at_entry(life) |
Issue ages (ANB), life 1 or 2 |
x(t) |
age(t, life) |
Attained age (ANB) |
(none) |
sex(life) |
Sex of each covered life |
(none) |
is_joint() |
Two covered lives |
market_type |
market_type() |
NQ / TradIRA / RothIRA / QLAC |
(none) |
is_qlac() |
market_type decoded: QLAC |
f |
income_form() |
LO / LO_ROP / CR / IR / PC |
(f, payout part) |
payout_form() |
The payout stream f implies |
(none) |
is_life_only() |
f decoded: LO or LO_ROP |
(none) |
is_cash_refund() |
f decoded: CR |
(none) |
is_installment_refund() |
f decoded: IR |
(none) |
is_period_certain() |
f decoded: PC |
db_form |
db_form() |
ROP or NONE in deferral |
(none) |
is_rop() |
db_form decoded: ROP |
n |
certain_period() |
Elected certain period, years |
T |
income_start_mth() |
Income start month in force |
(T at issue) |
income_start_mth_init() |
Income start month at issue |
(T for a premium at k) |
income_start_mth_at(k) |
Start month a premium at k is priced to |
m |
payment_freq() |
Payments per year |
pay_timing |
payment_timing() |
arrears / advance |
(none) |
is_arrears() |
timing decoded: arrears |
c |
cola_rate() |
Fixed compound COLA rate |
(1+c)^floor((t-T)/12) |
cola_factor(t) |
COLA escalation factor |
(the same, at k) |
cola_factor_pm(k) |
The same, in policy month k |
delta / survivor_pct |
survivor_pct() |
Survivor percentage |
reduction_trigger |
reduction_trigger() |
either / primary |
(none) |
is_trigger_either() |
trigger decoded: either |
P_k |
premium_pp(t) |
Premium paid in month t |
(P_k by policy month) |
premium_pm(k) |
Premium paid in policy month k |
(the schedule) |
premium_by_mth() |
{month: premium} still due |
CP(t) |
cum_premium_pp(t) |
Cumulative premiums during t, eq (7) |
CP(t_entry) |
cum_premium_pp_init() |
Premiums paid before the valuation date |
CP(T) |
cum_premium_payout() |
Cumulative premiums at the income start, the refund base |
B(t) |
annual_income(t) |
Guaranteed annual income during t, eq (8) |
B(t_entry) |
annual_income_init() |
Income bought before the valuation date |
B(T) |
annual_income_payout() |
Income at the income start |
l(t) |
lives_if(t, life) |
Survival to time t, projected |
l(t_entry) |
lives_if_init(life) |
Survival at the valuation date, or at issue if later |
l(k) (pricing) |
lives_if_pm(k, life) |
Survival from issue to policy time point k |
l_last(k) (pricing) |
lives_if_last_pm(k) |
At least one life alive, from issue to k |
q(t) |
mort_rate_mth(t, life) |
Monthly death probability |
(q by policy year) |
mort_rate_mth_py(y, life) |
The same, in policy year y |
(annual q) |
mort_rate(t, life) |
Annual rate after improvement |
(annual q by year) |
mort_rate_py(y, life) |
The same, in policy year y |
q_x (table) |
mort_rate_base(t, life) |
Base-table annual rate |
(q_x by age) |
mort_rate_base_at(x, life) |
The same, at attained age x |
(the table’s sex) |
mort_schedule(life) |
The life’s row of the table |
2012 (in q_x^(2012+n)) |
mort_table_year |
Base year of the shipped table |
G2_x |
improvement_rate(t, life) |
Generational improvement rate |
(G2_x by age) |
improvement_rate_at(x, life) |
The same, at attained age x |
(the scale’s sex) |
improvement_schedule(life) |
The life’s row of the scale |
(none) |
mort_basis() |
anchor / generational |
(none) |
is_generational() |
mort_basis decoded |
(A/E) |
mort_ae_factor |
A/E factor, 1.00 [std] |
omega |
omega_age |
Limiting age, 120 |
(stopping rule) |
horizon_mths() |
Months from issue to the age stop rule |
(none) |
proj_len() |
Months from the valuation date to the stop rule |
(d_i) |
lives_death(t, life) |
Deaths during month t |
l_last(t) |
lives_if_last(t) |
At least one life alive |
d_last(t) |
lives_death_last(t) |
Last-death density |
(none) |
policy_count() |
Contracts the point stands for |
(none) |
pols_if_init() |
Contracts in force at the valuation date |
(none) |
pols_if_at(t, timing) |
Contracts on the books at time t, BEF_NB or BEF_DECR |
(none) |
pols_new_biz(t) |
Contracts issued in month t |
(in force) |
pols_if(t) |
Contracts on the books times l_last(t) |
i_p, v |
pricing_rate |
Pricing interest rate, 4.75% |
v^d |
pricing_disc_factor(yrs) |
Pricing discount factor |
L |
expense_load |
Expense and profit load, 6.0% |
d_k = (T - t_k)/12 |
deferral_yrs(k) |
Deferral of a premium at k |
_d p_x |
surv_to_income_start(k) |
Survival over the deferral |
a^(m)_y(f; i) |
annuity_factor(…) |
Payout APV, eq (2) generalized |
(the same, by basis) |
annuity_factor_at(k, basis) |
The same from policy month k, on a basis’s arguments |
(same, at T) |
payout_factor() |
Payout factor in force |
(same, computed) |
payout_factor_calc() |
Payout factor by eq (2) |
(none) |
factor_basis() |
table / formula |
(none) |
is_formula_basis() |
factor_basis decoded |
A_rop(x, d; i) |
rop_factor(k) |
ROP factor in force, eq (3) |
(d in whole years) |
rop_deferral_yrs(k) |
d_k rounded half to even, the ROP table’s key |
(same, computed) |
rop_factor_calc(k) |
ROP factor, mid-band rule |
a_def(x, d, f; i) |
annuity_factor_def(k) |
Deferred APV, eq (1) |
pr(x, d, f) |
purchase_rate(k) |
Purchase rate, eq (4) |
(none) |
purchase_rate_dp() |
Its decimal places, -1 for all |
n_g (pricing) |
guarantee_mths_pricing() |
n_g in the kernel, eq (5) |
(n_g as priced) |
guarantee_mths_pricing_init() |
The same, carried in force |
(“three iterations”) |
pricing_iters |
Fixed points taken on eq (5) |
n_g (realized) |
guarantee_yrs() |
CP(T)/B(T), eq (5) |
n_R |
certain_mths_refund() |
Derived refund period, months |
n_eff |
certain_mths_eff() |
Effective certain months |
C(t) |
certain_floor(t) |
Certain-floor indicator |
(C by policy month) |
certain_floor_pm(k) |
The same, in policy month k |
L(t), L_pay(t) |
payment_factor_life(t) |
Life-contingent payment factor |
l_last(T) |
surv_to_payout() |
Cohort reaching the income phase |
(l_last(T) in force) |
surv_to_payout_init() |
The same, carried in force |
Phi(t) |
payment_factor(t) |
max(C(t) * l_last(T), L(t)) |
inst(t) |
annuity_pp_sched(t) |
Scheduled instalment |
(inst by policy month) |
annuity_pp_sched_pm(k) |
The same, in policy month k |
(inst as payable) |
annuity_pp(t) |
Instalment after a blackout |
(inst after commutation) |
annuity_pp_paid(t) |
inst * (1 - theta_cum * C) |
G(k) |
cum_annuity_pp(k) |
Cumulative instalments through policy month k |
RG(t) |
refund_balance(t) |
Refund balance at the start of t |
phase(t) |
phase(t) |
PRE_ISSUE / DEFERRAL / PAYOUT / TERMINATED |
(t >= T) |
is_payout(t) |
In the income phase |
T (payment dates) |
is_payment_mth(t) |
Month t is a payment date |
(by policy month) |
is_payment_pm(k) |
Policy month k is a payment date |
(payment point) |
payment_surv_mth(t) |
Time survival is measured at |
Baa(t_e) |
baa_yield |
Moody’s Baa yield at t_e |
s_adj |
adjust_spread |
Repricing spread, 100 bp |
i_e |
repricing_rate() |
Start-date repricing rate, eq (10) |
B’/B |
adjust_income_factor() |
Repricing factor, eq (11) |
t_e |
adjust_mth() |
Start-date exercise month |
T’ |
adjust_start_mth() |
New income start month |
t_a |
accel_mth() |
Acceleration exercise month |
n_a |
accel_months |
Payments accelerated, 6 |
Cost(t_a) |
accel_cost() |
Acceleration cost, eq (12) |
accel_blackout(t) |
accel_blackout(t) |
Payments suspended |
(Phi, frozen at t_a) |
accel_payment_factor(t) |
Weight on an accelerated payment |
t_c |
commute_mth() |
Commutation exercise month |
(commuted share) |
commute_frac() |
Fraction commuted at t_c |
r_ref(t) - r_ref(0) |
ref_rate_shift_init() |
Reference-rate change from issue to the valuation date |
(the change at t = 0) |
ref_rate_shift |
Reference-rate change made at the valuation date; none for a policy issued later |
i_c(t) |
commute_disc_rate(t) |
Commutation rate, eq (13) |
m_c |
commute_margin |
Commutation margin, 50 bp |
CV(t) |
commuted_value(t) |
Commuted value, eq (14) |
theta_cum(t) |
commute_frac_cum(t) |
Cumulative commuted fraction |
(l_last(t_c)) |
commute_weight(t) |
Cohort a commutation extinguishes |
(l_last(t_c) in force) |
commute_weight_init() |
The same, carried in force |
E[COMM(t)] |
commutations(t) |
Commutation paid to the owner |
Limit(year) |
qlac_premium_limit |
QLAC premium limit, $210,000 |
qlac_room(t) |
qlac_room(t) |
Remaining QLAC premium room |
(none) |
other_qlac_premium() |
Premiums to any other QLAC |
(age 85 outside date) |
qlac_max_start_age |
Latest QLAC income start age |
(QLAC conditions) |
qlac_flags() |
QLAC compliance failures |
(premium income) |
premiums(t) |
l(t) * premium paid at t |
(deferral DB) |
claims(t, DEATH) |
Return of CP(t) on death |
(refund benefit) |
claims(t, REFUND) |
Cash-refund lump sum |
(per contract) |
claim_pp(t, kind) |
Claim amount per contract |
E[income] |
annuity_payments(t) |
Expected income outgo |
e, g |
expense_maint, inflation_rate |
Maintenance expense and escalation |
(1+g)^(t//12) |
inflation_factor(t) |
Expense inflation factor, on the valuation clock |
E[EXP(t)] |
expenses(t) |
Maintenance expense |
(total outgo) |
liability_outgo(t) |
Gross liability outgo |
(none) |
liability_cf(t) |
Net stream, outgo positive |
(none) |
net_cf(t) |
Premiums less outgo |
Every input of the notes has a row above, and so do the model’s own additions, which the
notes give no symbol but which drive the in-force projection: the counts, the clocks, the
opening state and the decodes. Only the outputs and diagnostics are left out —
model_point(), premium_schedule(), the annual display cells
lives_if_ann(), claims_ann() and annuity_payments_ann(), the reports
result_cf(), result_pols() and result_annual(), and the check_*
cells — because they are not quantities the notes define.
Seven names in that table needed care.
l and L differ in the notes only by case — the survival probability versus the
life-contingent payment factor — so they become lives_if and
payment_factor_life, exactly as in SPIA_US_S. L is also the
expense and profit load in equation (4); that one is the Reference expense_load.
l is also two curves here, where the notes have one: the projection’s
lives_if(), on the valuation clock from the opening state, and the pricing kernel’s
lives_if_pm(), on the policy clock from issue. On a point issued at the valuation
date they are the same numbers at every time point.
B is the guaranteed annual income and B(t)/m is one instalment; the notes
never name the instalment, so it takes the chassis name annuity_pp_sched. Note that
annual_income(t) is indexed by month, not by policy year as in
SPIA_US_S, because a DIA’s income level changes when a premium is paid
and premiums fall on months.
n_g is three different quantities in the notes and they must not be conflated.
guarantee_mths_pricing() is the guarantee period fed into the pricing kernel by
equation (5) — a fixed point, since n_g = CP(T)/B and B depends on n_g.
guarantee_yrs() is the realized value once B is known, the 3.3891 years the
worked example quotes. And certain_mths_eff() — the projection’s certain floor —
is zero on a cash-refund contract, because a cash refund is a lump sum at death, not
a stream of guaranteed payments. Equation (5) is a pricing approximation for both refund
forms; only installment refund actually pays a certain stream.
theta appears nowhere in the DIA notes. theta_cum, the cumulative commuted
fraction, is inherited from the immediate-annuity notes that these notes incorporate by
reference for the whole income phase; the DIA notes write equations (13) and (14) with
no symbol for the fraction at all. The cells keeps the chassis name,
commute_frac_cum(), so that the two models read alike.
Two cohort weights carry no notes symbol because the notes have no need of one: a SPIA
is already in payment and its whole model point reaches the income phase together.
surv_to_payout() is l_last(T), the cohort that ever reaches the income phase
and therefore the only cohort a guarantee period can pay; commute_weight() is
l_last(t_c), the sub-cohort still alive to exercise a commutation and therefore the
only cohort whose guarantee a commutation can extinguish. They are the same idea
applied at two dates, and getting either of them wrong moves the guaranteed leg without
moving anything else. A contract valued after either date carries it in its opening
state, because the lives at the valuation date can no longer say it.
CP(T) is the DIA-specific change to the payout chassis and the notes’ own listed
pitfall: the refund base is cumulative premiums, not the initial premium. Where
SPIA_US_S writes premium_pp(), this model writes cum_premium_payout().
The self-checks follow the library-wide check_* convention, which is
CashValue_SE.check_av_roll_fwd()’s: each check takes no argument and returns a
bool covering every projected t, so one test can call the same name across every
model in the library, and each carries a companion check_*_resid(t) returning the
signed float residual at a single t for the debugging session that follows a failure.
The bool is defined in terms of the residual, never the other way round.
check_lives_roll_fwd(), check_income_roll_fwd(),
check_payment_factor() and check_commutation_value() are the four here; there
is no check_av_roll_fwd, because there is no account value to roll forward.
The state variables do not share one timing
Month t spans time t to time t + 1, and the state cells sit at three different
instants inside it.
l(t)andRG(t)are start-of-month values.lives_if(t, life)is survival to the start of montht;refund_balance()is measured before the arrears instalment due at the end of the month,CP(T) - G(m - 1)at policy monthm, which is why a death in monthTrefunds the fullCP(T). (On advance timing the instalment paid at the start of the month has been paid, so that one is netted:CP(T) - G(m).)CP(t)andB(t)are the values during montht— after the premium received at its start, which is exactly what makes the deferral death benefitCP(t) * l(t) * q(t)right and what lets a slice bought at the start oftbe guaranteed from that moment. Entering month 0 they are the opening state, the valuesDIA_US_Sholds during the month before the valuation month.G(k)is a closing balance: cumulative scheduled instalments through the end of policy monthk.GandRGare therefore exactly one month apart by construction, not by accident.
None of them is a recursion seed living before the frame: each opens at t_entry(),
from the opening state in force and from its value at issue otherwise, and nothing in this
model is indexed at a time point before it on the valuation clock.
Two pricing bases: tabulated and computed
The notes’ worked example is priced off illustrative factors it states outright —
a^(12)_80(cash refund, female; 4.75%) = 8.60, A_rop(60, 20) = 0.157900,
A_rop(65, 15) = 0.180200 — declaring them “mutually consistent illustrative values,
not table lookups”. Both readings are shipped, and which one applies is a model point
column:
factor_basis = "table"payout_factor()androp_factor()read the shipped factor tables, andannuity_factor_def()is the notes’ equation (1) literally,v^d * _d p_x * a^(m). Model points 1, 2 and 4, and the points restated from point 1, 19 and 25. This is the basis that reproduces the worked example. It is single-life only: equation (1) factorizes the deferral survival out of the payout APV, which a joint status does not permit, andDatarefuses a joint contract on it.factor_basis = "formula"payout_factor_calc()computes equation (2) androp_factor_calc()the notes’ mid-band approximation of equation (3), both off the shipped mortality table, andannuity_factor_def()values the whole deferred stream in one pass so joint forms work. Model points 3, 5 to 18, 20 to 24 and 26.
The shipped mortality table is [std], built so that the two bases agree where the
notes say they should: its rates over ages 60-84 are band-constant values reproducing
the notes’ five-year survival anchors exactly, and the geometric continuation past age
85 is calibrated so that equation (2) at the income start age returns 8.600 — the notes’
own illustrative payout factor. Where they then disagree is A_rop(60, 20); see
below.
The A_rop(60, 20) divergence is shipped, not resolved
The notes say A_rop was “computed from the same survival anchors with a mid-band
death-timing approximation”. Run that recipe and the twenty-year factor comes out at
0.161605, not the 0.157900 the notes print, while the fifteen-year factor comes
out at 0.180241 against a printed 0.180200 — agreement to four decimal places.
One of the two is arithmetically consistent with the stated recipe and the other is not.
Rather than choose, the model ships both: model point 1 takes the printed factors from
rop_factor_table.csv and reproduces the worked example, model point 3 is otherwise
identical and computes them. A test of DIA_US_S’s pins the gap open, and the twin
identity carries it here.
The purchase-rate rounding is a [std] convention, and it is worth 3.6 cents
The worked example computes B_1 = 100,000 x 0.321765 = $32,176.50 from a purchase
rate printed to six decimals. At full precision pr_1 = 0.3217647 and the same
premium buys $32,176.47; over both slices the difference is 3.6 cents on a
$44,259.65 income. The model point column purchase_rate_dp carries the
convention — 6 on point 1, blank (full precision) on point 2 — so the worked example
reproduces to the cent without the rounding being hidden.
The certain period is a floor, not a second stream
payment_factor(t) = max(certain_floor(t) * l_last(T), payment_factor_life(t)) is
inherited from the payout chassis and is the notes’ first-listed payout pitfall. During
the certain period the full, unreduced instalment is payable regardless of survival; an
additive construction would pay 1 + L and silently double the guarantee. The max
also reproduces, with no extra logic, the rule that a survivor reduction falling inside a
guarantee period is deferred to the end of that period.
There is no lapse decrement, and adding one is a defect
“Lapse and surrender: exactly zero, at all durations. Not conservatism — there is no
surrender benefit to elect [R9][R13]. A nonzero lapse assumption in a DIA model is a
defect, not a margin.” There is no lapse_rate, no pols_lapse, no surrender cash
flow row and no account value roll-forward in this model, and none should be added:
the liability is a schedule of income slices keyed on (premium, purchase date, income
start date, income option), not a balance.
Codes
What DIA_US_S spells as text, a timing, a kind or a phase, is here an int
Reference named as the text it replaces, so that every cell takes and returns C numbers;
and so is the basis annuity_factor_at() prices on, which DIA_US_S passes as
float arguments to annuity_factor. A call site reads as it did, less the quotes:
pols_if_at(t, BEF_DECR), claims(t, DEATH).
Reference |
Value |
Meaning |
|---|---|---|
BEF_NB |
0 |
|
BEF_DECR |
1 |
|
DEATH |
0 |
|
REFUND |
1 |
the same: the cash refund |
ALL |
2 |
|
PRE_ISSUE |
0 |
|
DEFERRAL |
1 |
|
PAYOUT |
2 |
|
TERMINATED |
3 |
|
PURCHASE |
0 |
|
ADJUST_OLD |
1 |
|
ADJUST_NEW |
2 |
the same, from the new income start month |
Each family is numbered densely from 0, since a code a cell takes indexes that cell’s
cache, a C array three codes wide, the width of every 2-D cache of the model, the lives’
(spec_sec.py). A code inside the cache that names nothing raises as
DIA_US_S raises on text it does not know: claim_pp(t, ALL) raises
ValueError("invalid kind"), as DIA_US_S’s claim_pp(t, None) does.
DIA_US_S’s total is the sum of its two kinds’ cells, claims(t, "DEATH") +
claims(t, "REFUND"), so claims(t, ALL) keeps it as written, and keeps its float,
the sign of a zero included. They are References, not cells, so the symbol map does not
list them. Every other Reference is named in lower case, issue_age_min and
omega_age among them, the contract’s bounds that stop_mth() checks and that the
compiled model’s caches are sized from, with Data.future_horizon_mth.
Reporting cells
model_point(), the label accessors market_type(), income_form(),
payout_form(), db_form(), payment_timing(), mort_basis(),
factor_basis(), reduction_trigger() and sex(), the reports
result_cf(), result_pols() and result_annual(), and the four checks are
written for a reader and for the comparison with DIA_US_S, which has every one
of them: a table row, text, DataFrames and verdicts. No other cell calls them: each reads
the number Data decoded from the same column instead, the decodes’ flags and the
schedules the sexes select. So the row, the text and the frames stay Python when the
model compiles. Each label returns its point’s column: the column of its own name, but
payment_timing the timing column, sex(life) the sex or joint_sex
column by life, and payout_form the income_form column with LO_ROP read as
LO, as the registry declares them. Each validates its column, as
DIA_US_S’s does, and so returns text or raises, but sex, which returns its
column as read, a blank second life on a single-life contract as NaN, and the compiled
accessor returns the same. The checks may stay Python but compile to a bint, their
verdict, as their per-month residuals, *_resid, compile to a double.
And five cells of DIA_US_S’s are kept for a reader and for the comparison, and
called by no other cell but each other, the registry’s "engine" cells: the pricing
kernel’s two of float parameters, annuity_factor() and pricing_disc_factor(),
which compile with C signatures and dict caches, their bodies Python, the projection
holding their arithmetic in annuity_factor_at() and inline; and
premium_schedule(), premium_by_mth() and qlac_flags(), which take no
parameter and return a DataFrame, a dict and a list, the projection reading the premiums
from Data’s premium table instead and nothing reading the flags. Every other cell
returns a C bint, long long or double.
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 only the label accessors read. Every projection cell reads its ownDatavector instead.
- point_id()[source]#
The label of the selected model point, its
point_id, fromData.point_id.Projectionis indexed by position,idx, asbasiclife.BasicTerm_SCis; the label is what a reader finds in the table, so every refusal names it.
- age_at_entry(life)[source]#
x: issue age (ANB) of the primary (life = 1) or joint (life = 2) annuitant.
Age nearest birthday [std]: the archetype guide states contract issue age on an ANB basis [S2], prescribed VM-22 payout mortality is ANB [R9], and the 2012 IAM Basic and Period tables were developed ANB [R15][REG-R59]. The age at issue, not at the valuation date:
age(0, life)is the attained age then.Read from
Data.issue_ageandData.joint_age,int()of the column. An ageint()cannot read, text or a blank, or one of2**53or more in size, is refused here, naming the point: a single-life contract’s blankjoint_age, which no projection reads, only by a direct call.stop_mth()refuses an issue age the contract does not cover.
- sex(life)[source]#
Sex (M / F) of the primary (life = 1) or joint (life = 2) annuitant.
A label accessor, which no projection cell calls: it returns the
sexorjoint_sexcolumn as read, a single-life contract’s blank second life as NaN. The age readers and the factor tables join on the sex throughData’s schedules instead.
- is_joint()[source]#
True when the contract covers two annuitants [S2][S4].
The
jointcolumn asDatachecked it, a flag, fromData.is_joint:DIA_US_S’sbool()of the raw value reads any text,"no"and a blank among them, asTrue.
- survivor_pct()[source]#
delta: the survivor percentage, in {0.50, 2/3, 0.75, 1.00} [S1][S2][S4].
Read from
Data.survivor_pct, a probability on every point, asDatachecks.
- reduction_trigger()[source]#
trig: whether the reduction is triggered by either death or the primary’s.
A switch, not a parameter: the two conventions coincide on the primary’s death and differ only on the secondary’s [S1][S2][S4]. A label accessor, which no projection cell calls.
- is_trigger_either()[source]#
Whether either death triggers the survivor reduction, not the primary’s alone.
A decode of the model point’s
reduction_triggercolumn,Data.is_trigger_either, validated byData.has_reduction_triggerasreduction_trigger()validates it, so thatpayment_factor_life()and the pricing kernel branch on a flag and no projection cell calls the label accessor, which is left to reporting.
- market_type()[source]#
The tax wrapper: NQ, TradIRA, RothIRA or QLAC [S2][S4].
A label accessor, which no projection cell calls.
- is_qlac()[source]#
True when the contract is intended to be a QLAC [R1 (q)(1)(vi)].
A decode of the model point’s
market_typecolumn,Data.is_qlac, validated byData.has_market_typeasmarket_type()validates it, so thatqlac_flags()branches on a flag and calls no label accessor.
- income_form()[source]#
f: the income option elected at issue and immutable thereafter [S1][S2][S4].
LOlife only;LO_ROPlife only with a 100% return-of-purchase-payments death benefit in deferral, the unbundled extended-case variant [S4];CRlife with cash refund;IRlife with installment refund;PClife with period certain. A label accessor, which no projection cell calls.
- payout_form()[source]#
The payout stream the elected form implies: LO, CR, IR or PC.
LO_ROPcollapses toLOhere because its return of premium is a deferral death benefit carried bydb_form(); after the income start date it is a pure life annuity [S4]. The unbundling of the death benefit from the payout form is the product spec’s chosen parameterization, so that the two mortality exposures move independently. A label accessor, which no projection cell calls: theincome_formcolumn’s value withLO_ROPread asLO, as the registry declares it.
- is_life_only()[source]#
Whether the payout stream is life only:
income_formLO or LO_ROP.One of four decodes of the model point’s
income_formcolumn, as are the three below it, so that no projection cell compares text or callsincome_form()orpayout_form(), the label accessors, which are left to reporting. Each readsData’s flag for its value, andData.has_income_form, which says whether the column holds one of the five valuesincome_form()accepts, compared as it compares them, so an invalid form raisesValueError("invalid income_form")wherever the projection first meets it.LO_ROPis life only in payout, aspayout_form()collapses it.
- is_cash_refund()[source]#
Whether the form is cash refund, CR: a lump sum of
CP(T) - Gon the last death.A decode of the
income_formcolumn, validated asincome_form()validates it.
- is_installment_refund()[source]#
Whether the form is installment refund, IR: a certain period derived from
CP(T).A decode of the
income_formcolumn, validated asincome_form()validates it.
- is_period_certain()[source]#
Whether the form is life with period certain, PC: an elected certain period.
A decode of the
income_formcolumn, validated asincome_form()validates it.
- db_form()[source]#
The deferral-phase death benefit:
ROPorNONE.100% of cumulative premiums, no interest, lump sum, on every option except Life Only and Joint Life Only [S1][S2][S3][S4][R13 SS3.I(1)(a)]. This is the product’s central pricing fork: setting it to
NONEremovesA_ropfrom the numerator of equation (4) and buys strictly more income for the same premium. A label accessor, which no projection cell calls.
- is_rop()[source]#
Whether the contract carries the return-of-premium death benefit in deferral.
A decode of the model point’s
db_formcolumn,Data.is_rop, validated byData.has_db_formasdb_form()validates it, so that the ROP factor and the death claim branch on a flag and no projection cell calls the label accessor.
- certain_period()[source]#
n: the elected certain period in years, 10-30 on PC forms [S2]; 0 otherwise.
Read from
Data.certain_period,int()of the column; oneint()cannot read, or of2**53or more in size, is refused here, naming the point. Only a period certain reads it.stop_mth()refuses a period ending later than the caches hold.
- payment_freq()[source]#
m: payments per year, in {12, 4, 2, 1}; fixed at issue [S1][S2].
Read from
Data.frequency,int()of the column, asDatachecked it a whole number; one of2**53or more in size is refused, naming the point, and any other number raisesDIA_US_S’sValueError("invalid frequency"). The element is compared, never held in a local, so the compiled cell keeps no Python object.
- payment_timing()[source]#
Whether instalments fall in arrears (the [std] default) or in advance.
No retrieved DIA document states the convention; arrears matches
products/immediate_annuity/product-spec.mdso that one payout chassis serves both products. A label accessor, which no projection cell calls: it returns thetimingcolumn, compared exactly, or raises.
- is_arrears()[source]#
Whether instalments fall in arrears, at the end of the month, rather than in advance.
A decode of the model point’s
timingcolumn,Data.is_arrears, validated byData.has_timingaspayment_timing()validates it, so that the payment months, the survival point, the refund balance, the refund-period search and the pricing kernel branch on a flag and no projection cell calls the label accessor.
- cola_rate()[source]#
c: the fixed compound annual increase, 0 or 1%-4%, elected at issue [S2][S3][S4].
Every observed option is a fixed compound escalator applied on each anniversary of the income start date, not a CPI adjustment - the notes list treating it as index-linked among the product’s pitfalls. Read from
Data.cola_rate, a number zero or more on every point, asDatachecks.
- issue_year()[source]#
The calendar year of issue [std]; the anchor of the generational projection.
The improvement exponent is
calendar_year(t) - mort_table_year. The chassis calls its counterpartannuity_yearbecause a SPIA’s annuity date is its issue date; here the two are twenty years apart, so the generational anchor has to be named for the one that matters. Read fromData.issue_year,int()of the column; oneint()cannot read, or of2**53or more in size, is refused here, naming the point. Only the generational basis and the calendar year read it.
- 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. It isDIA_US_S’spols_if_initcolumn, renamed, and like it a constant on the books: mortality decrements each life’s survival,lives_if(), never the count. Read fromData.policy_count.
- pols_if_init()[source]#
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, whereDIA_US_S’s is the count itself; on either model the count that weights row 0 is the same, herepols_if_at(0, BEF_DECR).
- mort_basis()[source]#
Whether mortality is the notes’ anchor curve or the generational projection.
anchor [std]: the shipped table is used as a period table, which is what reproduces the worked example - its survival anchors are a single non-generational curve. generational: the notes’ prescribed construction
q^(2012+k) = q^(2012) * (1 - G2_x)^k[R9][REG-R59] is applied with the shipped illustrative improvement scale. Both are shipped because the notes prescribe the second and verify against the first. A label accessor, which no projection cell calls.
- is_generational()[source]#
Whether mortality is the generational projection rather than the anchor curve.
A decode of the model point’s
mort_basiscolumn,Data.is_generational, validated byData.has_mort_basisasmort_basis()validates it, so thatmort_rate_py()branches on a flag and no projection cell calls the label accessor.
- factor_basis()[source]#
Whether the pricing factors are table lookups or formula computations.
table:
payout_factor()androp_factor()read the notes’ illustrative factors andannuity_factor_def()is equation (1) literally - the basis that reproduces the worked example, single-life only. formula: both are computed from the shipped mortality table by equations (2) and (3). See the Space docstring. A label accessor, which no projection cell calls.
- is_formula_basis()[source]#
Whether the pricing factors are formula computations rather than table lookups.
A decode of the model point’s
factor_basiscolumn,Data.is_formula_basis, validated byData.has_factor_basisasfactor_basis()validates it, so thatpayout_factor(),rop_factor()andannuity_factor_def()branch on a flag and no projection cell calls the label accessor.
- purchase_rate_dp()[source]#
Decimal places the purchase rate is rounded to, or -1 for full precision.
[std]. The worked example computes
Bfrom a six-decimal purchase rate; carrying full precision instead moves the anchor cell’s annual income by 3.6 cents. Blank on the model point returns -1, meaning no rounding: modelx forbids a cells returningNone, so every “not set” on this Space is a negative sentinel. Read fromData.purchase_rate_dp, which holds the blank as -1 already; a value of2**53or more in size is refused here, naming the point.
Premiums paid to any other contract intended to be a QLAC [R1 (q)(2)(ii)(B)].
The QLAC dollar limit is reduced by premiums paid to any other QLAC under any 401(a), 403(a), 403(b), 408 or governmental 457(b) arrangement; the issuer may rely on the owner’s written representation [R5 (h)(2)]. Read from
Data.other_qlac_premium.
The selected contract’s premium slices still due, ordered by payment month.
A DIA is a flexible-premium contract - “any number of premiums during the deferral period” [S2][S3][S4][R13] - so the schedule is a separate long table rather than a fixed set of model point columns. Its rows of
premium_schedule_sec.csv, which holds the premiums due at or after the valuation date: on a point issued at or after it the whole schedule, and on a point in force the premiums of policy monthsduration_mthand later, those paid before being in the opening state. Kept for a reader and for the comparison withDIA_US_S, a DataFrame, and called by no cell butpremium_by_mth(): the projection reads the premiums fromData.premium_array, throughpremium_pm()(the Space docstring’s Reporting cells).
The premium schedule still due collapsed to a
{month: amount}mapping.Keyed by policy month,
DIA_US_S’s dict, kept for a reader and for the comparison withDIA_US_S, and called by no projection cell:Data.premium_arrayholds the same sums by policy month, added in the same order, whichpremium_pm()reads, andData.premium_rowsthe months with a row, whichguarantee_mths_pricing()visits asDIA_US_Svisits this dict’s keys.
P_k: the premium per contract paid at the start of policy month k; 0 if none.
Keyed by policy month, on the policy clock, and the one cell that reads the premium schedule, so that
premium_pp()reads a premium at the policy month of month t, andannual_income_payout()andcum_premium_payout()at every policy month from the valuation date’s to the income start month, without passing a policy month ast. 0 before the valuation date on a point in force, whose premiums paid are in its opening state. Read fromData.premium_array, the schedule summed by policy month asDIA_US_S’spremium_by_mthsums it, and 0.0 past its last month, asDIA_US_S’sdict.getgives it.kis never negative: every caller reads a policy month from the valuation date’s, or from issue, on.
P_k: the premium per contract paid at the start of month t; 0 if none falls.
premium_pm(duration_mth(t)), the premium of the policy month that monthtfalls in, inside the frame, and 0 outside it.
CP at the valuation date: the premiums per contract paid before it.
The
cum_premium_pp_initcolumn, the cumulative premium entering month 0, before the premium, if any, received at its start:DIA_US_S’scum_premium_pp(d - 1)on a point restated at its monthd. The opening value ofcum_premium_pp()att_entry(), and the deferral death benefit’s and the refund’s base before the premiums still due are added. 0 at issue, and so on every point not yet in force, asDatachecks. Read fromData.cum_premium_pp_init.
CP(t): cumulative premiums paid per contract, equation (7).
CP(t) = CP(t-1) + P_kat the premiums of montht. The recursion opens att_entry(), the first month on the books, on the opening state,cum_premium_pp_init(), the premiums paid before the valuation date, which is 0 on a point issued at or after it, so thatCP(t_entry)is that plus the premium, if any, received at the start of the month. The value is the one in force during montht- it already includes the premium received at the start of that month, which is what makes the deferral death benefitCP(t) * l(t) * q(t)right. This is the deferral death benefit base; the refund base isCP(T),cum_premium_payout(), read from the income start month on. For a flexible-premium DIA the refund base is CP(T), not the initial premium, which is one of the notes’ listed pitfalls [S2][S4]. Zero outside the frame.
CP(T): cumulative premiums per contract at the income start month, the refund base.
cum_premium_pp_init()plus every premium still due, from the valuation date’s policy month to the income start monthT, in one loop over the policy months, the same additions in the same order as the recursioncum_premium_pp(), soCP(T)isDIA_US_S’scum_premium_pp(T)to the last bit. On a contract past its income start month the loop is empty andCP(T)is the opening state: no premium falls at or afterT, asDatachecks, soCPis level in payout. A static quantity, so that the refund balance, the installment refund’s search andguarantee_yrs()read the refund base without readingcum_premium_pp()far ahead of their month.
- duration_mth_init()[source]#
Months from issue to the valuation date, the
duration_mthcolumn.The policy’s age in months at
t = 0: 241 for a contract issued 241 months before the valuation date, 0 for one issued at it, and -13 for one to be issued 13 months after it, whichDataadmits up tofuture_horizon_mthmonths ahead. It is read asbasiclife.BasicTerm_SEreads it, by value, and is the one fact the policy clock takes from the model point, fromData.duration_mth; a valueint()cannot read, or of2**53or more in size, is refused here, naming the point.
- duration_mth(t)[source]#
Months elapsed from issue at the start of month t, the policy clock.
duration_mth_init() + t:tcounts months from the valuation date andduration_mth(t)months from issue, and the two move together. A closed form, wherebasiclife.BasicTerm_SEadds one a month by recursion: the same numbers, without a call chain as long as the frame. Negative before issue. Everything contractual reads this clock: the policy year, the attained ages, the premium months, the income start month, the option months, the payment months, the COLA anniversaries and the certain period.
- t_entry()[source]#
The first month the contract is on the books:
max(0, -duration_mth_init()).0 for a contract in force at the valuation date or issued at it,
kfor one issuedkmonths later. It is the base of every recursion on the valuation clock:lives_if(),cum_premium_pp()andannual_income()open there, from the opening state, and read no month before it, andpols_if_at()counts the contracts from there.
- stop_mth()[source]#
The policy month at which the projection stops: the stop rule, on the policy clock.
max(horizon_mths(), income_start_mth() + certain_mths_eff()),DIA_US_S’s frame length counted from issue: the month the youngest covered life attains the limiting age, or the end of the guarantee period if that is later. The last projected month is policy monthstop_mth() - 1;proj_len()counts the months to the stop from the valuation date instead. 720 on the anchor cell, ages 60 to 119.Before it, the contract the compiled model’s caches are sized for (
spec_sec.py), each bound a lower-case Reference, each refusal naming the point: an issue age of a covered life belowissue_age_min, 0, on every form, the primary’s and, on a joint contract, the joint annuitant’s each asked, since a frame runs to the age stop on its youngest life; an income start month, at issue or in force after a start-date adjustment, past12 * (omega_age - issue_age_min), 1,440, the latest policy month the caches hold, both asked, since the premiums before an adjustment are priced to the old month; and a certain period ending past that month. Each is checked here, before the stop rule, which reads the installment refund’s search overcum_annuity_pp()up tohorizon_mths(), and here rather than inproj_len(), so that every cell of a refused point that reads the frame, throughis_active(), refuses it asproj_len()does, in both engines.DIA_US_Sprojects every form at issue age 0, on tables starting below 20, and so does this model, the product-spec’s 22 bounding nothing; a negative issue age is outside every contract, and refused as Term’s issue ages are, a departure fromDIA_US_S, which projects it.DIA_US_Sprojects an income start month, or a certain period’s end, past 1,440 too, and those are refused as what the caches cannot hold, asSPIA_US_SECrefuses a certain period of more than 1,440 months: recorded departures. The product-spec’s income start months, 13 to 360, and certain periods, 10 to 30 years, bound nothing. The installment refund rounds its derived period up to a whole instalment, so the stop rule ends at policy month 1,441 at most.
- is_active(t)[source]#
Whether month t is inside the frame: issued, and not yet at the stop rule.
0 <= duration_mth(t) < stop_mth(). False before issue and from the stop rule on. Outside it every count is zero, and so every cash flow; no cell reads a rate, a policy year or an attained age there that the contract does not have. A contract’s own end inside the frame - its last death, or the end of its guarantee - is a probability or a floor reaching zero, not the end of the frame, which runs on with zeros asDIA_US_S’s does.
- duration(t)[source]#
Completed policy years at the start of month t:
duration_mth(t) // 12.0 throughout the first policy year from issue, and negative before issue.
- policy_year(t)[source]#
y = duration(t) + 1: the policy year containing month t, on the policy clock.
The policy year is the contract’s own 1-based label,
duration_mth(t) // 12 + 1, and is derived from the policy clock, never used to index the frame: 1 for policy months 0..11, whatevertthey fall at. It is 0 or less before issue, where no cell reads a rate by it. Used where the notes speak in policy years: the mortality rate, and the annual display grid.
- calendar_year(t)[source]#
The calendar year of the policy year containing month t, on the policy clock.
issue_year() + duration(t): calendar-dated from the issue year, so a contract in force at the valuation date reads its own calendar years whatever that date, and nothing in the improvement it dates is re-based onto the valuation clock. On a point restated fromDIA_US_Sat its monthd, monththere isDIA_US_S’s monthd + t, and so the same calendar year.mort_rate_py()computes the same year for a policy year.
- age(t, life)[source]#
x(t) = x + duration(t): the attained age (ANB) of
lifein month t.On the policy clock: the age changes on each anniversary of issue, whatever the valuation date.
- horizon_mths()[source]#
Months from issue to the limiting age of the youngest covered life.
t/12 + x_i > omega_agefor every covered life is the payout chassis’ stop rule; stopping on the primary’s age alone would truncate a younger joint annuitant’s tail. Counted from issue, on the policy clock;stop_mth()andproj_len()take it. The younger of the two ages is found by one comparison, with no list, reading the cellsDIA_US_S’sminreads, in its order.
- proj_len()[source]#
The number of months from the valuation date to the stop rule.
stop_mth() - duration_mth_init(): 720 for the anchor cell issued att = 0, 479 for it in force 241 months (point 19), 1 in its last month (point 25), and 733 for the joint point issued 13 months after the valuation date (point 26). The exclusive end of the frame:result_cf()runs overrange(proj_len()), so the last projected month isproj_len() - 1, which is policy monthstop_mth() - 1on every point.The projection stops when it reaches the mortality horizon - the month the youngest covered life attains the limiting age,
horizon_mths()- or the end of the guarantee period if that is later. Both are age- or contract-driven rather than derived from the projection they bound, so the frame never depends on the survival path.Two kinds of point have no frame, and raise here, naming the point, rather than projecting nothing: an in-force extract should not carry either. A point at or past the stop rule. And a contract that owes nothing after the valuation date: in force, with every covered life dead at the valuation date, valued at or before its income start month, whose every death fell in the deferral and whose death benefit, if any, was paid before the valuation date; or valued after it, with its certain period over or no certain period at all, the refund, if any, having been paid at the last death. This is
Term_US_SEC’s point past its cover, for a product whose cover can end with a death. The rule needs the certain period, which an installment refund derives from the payout schedule, so it is checked here rather than inData, and each message says why nothing is owed. A contract in its certain period with every life dead pays the beneficiary, and projects.And one combination of the two payout options raises here, naming the point, because neither model prices it: an acceleration on the books, at or after the valuation date, whose lump sum pulls forward instalments of a guarantee that a commutation before it has reduced. The lump sum pays each instalment it pulls forward at the payment factor, unreduced, as
DIA_US_S’s does, so the cohort that commuted would be paid those instalments again. The guarantee’s end needs the certain period, so this too is checked here.Datarefuses the two options within six months of each other, the product’s interlock; an acceleration that pulls forward only the life-contingent instalments after the guarantee projects, and so does one paid before the valuation date, whose blackout months pay nothing.Before any of these,
stop_mth()refuses a point outside the contract the compiled model’s caches are sized for, naming it.omega_ageabove 120,issue_age_minbelow 0,accel_monthsabove 6 andData.future_horizon_mthabove 120 are not refused: each needs the caches resized and the model rebuilt, and a report past them is a bareIndexErrorin the compiled model alone, where modelx projects.
- income_start_mth_init()[source]#
T at issue: the income start month elected at issue,
13 <= T <= 360[S2][S4].Tis a policy month, so the income start date is the start of policy monthT, exactlyT/12years after issue, whatever the valuation date. Under arrears the first instalment falls one payment period later - atm = 12, at the end of policy monthT. Read asDatachecked it, a whole number of months, fromData.income_start_mth, and compared withduration_mth(t), never witht; a month of2**53or more in size is refused here, naming the point, andstop_mth()refuses one later than the caches hold.
- adjust_mth()[source]#
t_e: the policy month a start-date adjustment is exercised; -1 if it never is.
One-time, deferral only, excluded on Life Only and Joint Life Only [S1][S3][S4]. The incidence of the exercise - the notes’ 1.5% p.a. take-up with its 60/40 direction split, rate multipliers and health-selection overlay - is a cohort- splitting behavioural construction and is not implemented; the exercise is named deterministically on the model point instead, and is off by default. Read as
Datachecked it, blank or a whole number of months, and compared withduration_mth(t); a contract valued after it carries its repricing inannual_income_init. Read fromData.adjust_mth, which holds the blank as -1; a month of2**53or more in size is refused here, naming the point.
- adjust_start_mth()[source]#
T’: the new income start month after an adjustment, a policy month; -1 if none.
|T' - T| <= 60months,T'at least 13 months after the last premium, and inside the maximum deferral and the maximum income start age [S1][S2][S3][S4].Datachecks that it is given exactly whereadjust_mth()is, and that it follows the exercise. Read fromData.adjust_start_mth, which holds the blank as -1; a month of2**53or more in size is refused here, naming the point.
- income_start_mth()[source]#
T in force: the adjusted start month if one is exercised, else the elected one.
- income_start_mth_at(k)[source]#
The income start month a premium paid in policy month k is priced to.
A premium bought before the adjustment was priced to the original date; one bought after it is priced to the new date [R13 SS3.B(1)(b)]. Keyed by the premium’s policy month,
DIA_US_S’strenamed: pricing stays on the policy clock.
- repricing_rate()[source]#
i_e = Baa(t_e) - s_adj: the rate a start-date adjustment is repriced at, eq (10).
The disclosed recipe keys on Moody’s Seasoned Baa Corporate Bond Yield at the request date less a contractual interest-rate-change adjustment [S1][S2]; the adjustment is named but never quantified in any retrieved source, so the 100 bp spread is [std]. The base run sets
baa_yieldso thati_e = i_p- no rate movement since issue - because the notes supply no Baa value [std]. A flat level, so it reads the same on either clock.
- accel_mth()[source]#
t_a: the policy month payment acceleration is exercised; -1 if it never is.
Payout phase, attained age 59 1/2 or over, nonqualified, monthly frequency [S1][S2][S3][S4]. The notes’ 2% p.a. take-up among eligible contracts is a cohort-splitting construction and is not implemented; the exercise is named deterministically on the model point and is off by default. Read as
Datachecked it, blank or a whole number of months at or after the income start month, and compared withduration_mth(t). Read fromData.accel_mth, which holds the blank as -1; a month of2**53or more in size is refused here, naming the point.
- commute_mth()[source]#
t_c: the policy month a commutation is exercised; -1 if never (extended case only).
Offered by one of the four composite sources [S4][S5] and prohibited on a QLAC after the required beginning date [R1 (q)(1)(iv)]. The notes’ 1.5% p.a. take-up is not implemented, for the same reason as the other two options. Read as
Datachecked it, blank or a whole number of months at or after the income start month, and compared withduration_mth(t). Read fromData.commute_mth, which holds the blank as -1; a month of2**53or more in size is refused here, naming the point.
- commute_frac()[source]#
The fraction of the remaining guaranteed payments commuted; up to 100% [S4][R13].
Read from
Data.commute_frac, which holds a blank as 0.0, none.
- mort_rate_base_at(x, life)[source]#
The base-table annual mortality rate at attained age
x, forlife’s sex.The one cell that reads
mort_table.csv, keyed by age and life, so that the rate cells call it rather than join the table themselves. The sex is the join key:mort_schedule()giveslife’s row ofData.mort_table_array, and the age is its column, and the label accessor itself is left to reporting. Called only below the limiting age:mort_rate_py()andmort_rate_base()return 1 at and above it without calling here. The schedule asksData.mort_table_countfirst, throughData.mort_sexes, which checks the table’s keys and rates, so that a projection meets the checks before it reads a rate: a blank rate would otherwise reach the cap on mortality as a missing value. The age is checked against the row’s first and last ages,Data.mort_age_firstandData.mort_age_last, before the array is read, so an age the table lacks, below its first age, 20 as shipped, or any age on a sex the table lacks, whose row 0 holds none, is refused, naming the point, the age and the life, whereDIA_US_S’s.locraisedKeyError, and the padding is never read.
- improvement_rate_at(x, life)[source]#
The generational improvement rate at attained age
x, forlife’s sex.The one cell that reads
improvement_scale.csv, keyed by age and life and joined on the sex asmort_rate_base_at()joins the mortality table, throughimprovement_schedule(), the scale’s own numbering of its sexes, and checked and refused as it is. Called only below the limiting age.
- mort_schedule(life)[source]#
The number of
life’s sex in the mortality table: its row ofData.mort_table_array.Data.mort_schedule_1for the primary (life = 1) andData.mort_schedule_2for the joint annuitant (life = 2), 0 where the table lacks the sex, whichmort_rate_base_at()refuses; any other life raises. A cell of its own, so that the reader indexes the table by a cell’s value, never by aDataarray’s.
- improvement_schedule(life)[source]#
The number of
life’s sex in the improvement scale: its row ofData.improvement_array.As
mort_schedule(), on the scale’s own numbering of its sexes, which need not be the mortality table’s.
- mort_rate_base(t, life)[source]#
The base-table annual mortality rate for
lifein the year containing month t.The shipped table is an illustrative [std] annuitant table, not the 2012 IAM Basic table the notes prescribe: licensed tables may not be embedded, and the Basic table is in any case printed in no source this library holds - A-821 prints the loaded Period Table only [REG-R153]. Its rates over ages 60-84 are band-constant values that reproduce the notes’ five-year survival anchors exactly. Rates at and above the limiting age are 1, and the table is read below it, at the attained age
age()gives, throughmort_rate_base_at(). Zero outside the frame, where the contract has no attained age to look up. The rate the projection applies is built bymort_rate_py(), which reads the same table at the same age.
- improvement_rate(t, life)[source]#
G2_x: the generational improvement rate for
lifein the year containing t.The shipped scale is an illustrative [std] stand-in for Projection Scale G2 and is read only on the generational basis. Scaling it is the notes’ first listed sensitivity: Scale G2 is fixed and dated, and the 2020-2024 payout experience study says it has over-projected improvement [R15][REG-R61]. Zero at and above the limiting age, and outside the frame; read below it through
improvement_rate_at().
- mort_rate_py(y, life)[source]#
The annual mortality rate of
lifein policy year y: the one place it is built.On the generational basis the notes’ construction
q_x^(2012+k) = q_x^(2012) * (1 - G2_x)^k[R9][REG-R59], withkthe calendar year of policy yeary,issue_year() + y - 1, lessmort_table_year, so each attained age in each future calendar year uses its own improved rate. On the anchor basis the table is used unprojected, which is what the worked example’s survival curve is. The attained age isage_at_entry(life) + y - 1, the rate 1 and the improvement 0 at and above the limiting age, and the tables are read below it throughmort_rate_base_at()andimprovement_rate_at().mort_ae_factoris the experience A/E overlay, [std] at 1.00 - the notes set the deferral-phase A/E at 1.00 and give no number for the payout phase, the 2020-2024 study being cited without a factor [R15][REG-R61].Keyed by policy year, so that the projection’s
mort_rate(), at the policy year of month t, and the pricing kernel’smort_rate_mth_py(), at any policy year from issue, read one rate. The rate is capped at 1 asDIA_US_Scaps it, the bound second,min(mort_ae_factor * q, 1.0), so that a missing input, a NaN, stays NaN, wheremin(1.0, q)would read it as 1, certain death with every flow finite.
- mort_rate_mth_py(y, life)[source]#
The monthly death probability in policy year y:
1 - (1 - q_annual)^(1/12).mort_rate_py()turned monthly, asmort_rate_mth()turnsmort_rate(), so the two give one float in the same policy year. The pricing kernel’s rate, keyed by policy year, whichlives_if_pm()andannuity_factor()read at the policy year of each month from issue.
- mort_rate(t, life)[source]#
The annual mortality rate applied to
lifein the year containing month t.mort_rate_py()at the policy year of montht, on the policy clock, so the projection’s survival and the pricing kernel’s read one rate: on the generational basis, improved to the calendar year the contract reaches, and capped at 1. Zero outside the frame, before any rate is read.
- mort_rate_mth(t, life)[source]#
q(t) = 1 - (1 - q_annual)^(1/12): the probability of death during month t [std].
Month
ton the valuation clock, the projection’s rate; 0 outside the frame.
- lives_if_init(life)[source]#
l_i at the valuation date: the probability that
lifeis alive then.The
lives_if_init_1(primary, life = 1) orlives_if_init_2(joint annuitant, life = 2) column, as the contract stands at the start of month 0, before any month-0 death: the opening value oflives_if()att_entry(). On a real record it is 1 or 0, so a joint contract may carry one life already dead; on a point restated fromDIA_US_Sat its monthdit isDIA_US_S’slives_if(d, life), a probability. The lives are independent, as inDIA_US_S, so the two per-life probabilities are the whole survival state. A contract not yet in force carries its values at issue, 1 for each covered life, andlives_if_init_2is 0 on a single-life contract;Datachecks both. Read fromData.lives_if_init_1andData.lives_if_init_2.
- lives_if(t, life)[source]#
l(t): the probability that
lifeis alive at time t, as projected.Indexed by a time point on the valuation clock, not by a period: time
tis the start of montht, so month t opens at timetand closes at timet + 1, and time 0 is the valuation date.SPIA_US_Swrites the same cells with the argument namedk; here it is the valuation clock’st.At
t_entry(), the first time point on the books, it is the opening state,lives_if_init(): the life’s status at the valuation date for a contract in force, and 1, its value at issue, for one issued at or after it. Before that it is 0: the contract is not yet on the books. After itl(t) = l(t-1) * (1 - q(t-1)), equation (9) - the only decrement in the product, at the rate of montht - 1, the month that has just closed. There is no lapse and no annuitization decrement: VM-22’s standard-projection lapse section is “not applicable” to contracts with no account value or surrender benefit, and annuitization is prescribed at 0% [R9].The projection’s survival only: the pricing kernel prices each premium on its own survival curve from issue,
lives_if_pm(). Returns 0 forlife = 2on a single-life contract.
- lives_if_pm(k, life)[source]#
The pricing survival: the probability that
lifesurvives from issue to time k.Indexed by a time point on the policy clock,
kmonths after issue,l(0) = 1. One explicit loop from issue over the monthly rates of each policy year,mort_rate_mth_py():DIA_US_S’slives_ifrecursion unrolled, the same products in the same order, so it isDIA_US_S’slives_if(k, life)to the last bit. The pricing kernel reads it at the premium months, the income start months, the five-year bands of the ROP factor and the exercise months, andannuity_factor()carries the product on from there to the horizon, so pricing is anchored at issue and at the premium dates, deterministic from the contract’s terms and the mortality basis the model is read with, whatever the valuation date, and never reads the projection or its opening state. Returns 0 forlife = 2on a single-life contract.
- lives_if_last_pm(k)[source]#
l_last on the pricing curve: the probability that a covered life survives to time k.
l_1 + l_2 - l_1*l_2onlives_if_pm(), under joint-life independence, andl_1on a single-life contract:DIA_US_S’slives_if_last(k)from issue, which the ROP factor’s exposure reads.
- lives_death(t, life)[source]#
d(t) = l(t) - l(t+1): the deaths of
lifeduring month t.Note the index. Month
tspans timetto timet + 1, so the density is a forward difference: the deaths of monthtare taken at its end, between the survival at its start and the survival at the start oft + 1. Zero outside the frame.
- lives_if_last(t)[source]#
l_last(t): the probability at least one covered life is alive at time t.
l_1 + l_2 - l_1*l_2on a joint contract, under joint-life independence [std];l_1on a single-life contract, which is why no separatel_alivecells is needed. Indexed by a time point on the valuation clock, likelives_if(), and 0 before the contract is on the books.
- lives_death_last(t)[source]#
d_last(t) = l_last(t) - l_last(t+1): the last-death density in month t.
Also the death that terminates the income stream and triggers the refund, and - on a joint contract, where the first death leaves the contract running on the option chosen at issue [S2] - the death that triggers the deferral death benefit. Zero outside the frame.
- pols_if(t)[source]#
Contracts in force at the start of month t: the count on the books times l_last(t).
The contracts on the books weighted by the probability that a covered life is alive at the start of month
t,DIA_US_S’spols_if_init * l_last(t)on the count on the books. The notes weight the maintenance expense byl(t)alone. The payout chassis instead usesmax(C(t), l_alive(t)), so that a certain-period obligation running on after the last death still carries expense; the two notes files differ here and this model follows its own. They coincide on every form without a certain floor, the anchor cell included.It is not the count that weights row
t,pols_if_at(t, BEF_DECR), which mortality never moves: on point 20, the period-certain point in force 300 months,pols_if(0)is 0.5577 against a count of 1.0. The registry marks the modelsurvival_pols_iffor that reason. Zero outside the frame.
- pols_if_at(t, timing)[source]#
Contracts on the books at time t, at the instant
timingnames.BEF_NBThe contracts carried in from month t - 1, before month t’s new business: at
t_entry(), the first month on the books,pols_if_init(), the count in force at the valuation date (0 for a point issued at or after it), and the wholepolicy_count()after it. Zero outside the frame, so the contracts leave the books at the stop rule, at the end of the last projected month.BEF_DECRBEF_NBpluspols_new_biz(): the count that weights every cash flow of month t.
These are
basiclife.BasicTerm_SE’s names, int codes here (the Space docstring’s Codes), and any other timing raises. The count is not decremented: mortality decrements each life’s survival,lives_if(), and every cash flow is this count times a per-contract amount weighted by survival, asDIA_US_Sweights its flows by the constantpols_if_init. A count weighted by survival could not carry the two lives’ independent probabilities. SoBEF_NBis a closed form, the same float that the recursionBEF_NB(t-1) + pols_new_biz(t-1)gives, with no chain of calls back tot_entry().pols_if()is notBEF_DECR: it is this count weighted by survival.
- pols_new_biz(t)[source]#
Contracts issued in month t:
policy_count()in the issue month.The month with
duration_mth(t) == 0:t = 0for a point issued at the valuation date,t = kfor one issuedkmonths later. A contract already in force at the valuation date has none. New business inbasiclife.BasicTerm_SE’s sense, a contract entering the books, which brings its premium schedule and no acquisition cost:DIA_US_Scarries none.
- pricing_disc_factor(yrs)[source]#
v^yrs on the pricing interest rate i_p [std].
Contractual, not a valuation discount: this is the kernel that turns a premium into guaranteed income. No DIA source discloses a pricing rate - the Compact relieves the insurer of disclosing the deferral-period basis altogether [R13 SS1.B(1)(a)] - so 4.75% is a modeling assumption, readable as a long-duration general-account portfolio yield net of default costs. An engine cell of float parameter, kept as
DIA_US_S’s for its tests and the twin identity, which no other cell calls: its three callers inDIA_US_S,rop_factor_calc(),annuity_factor_def()andaccel_cost(), write(1.0 + pricing_rate) ** (-yrs)inline, the same operation on the same float.
- deferral_yrs(k)[source]#
d_k = (T - k)/12: the remaining deferral in years of a premium in policy month k.
Keyed by the premium’s policy month,
DIA_US_S’strenamed.
- surv_to_income_start(k)[source]#
_d p_x(k): the primary life’s survival from policy month k to the income start month.
A ratio on the pricing survival curve anchored at issue,
lives_if_pm(), which is how the notes derive_15p_65 = _20p_60 / _5p_60 = 0.715000/0.975000 = 0.733333. Keyed by the premium’s policy month,DIA_US_S’strenamed.
- annuity_factor(start_mth, guar_mths, int_rate, from_mth)[source]#
The APV at policy month
from_mthof $1 per annum of income fromstart_mth.Equation (2) generalized. The k-th instalment is certain while
k * 12/mdoes not exceedguar_mthsand life-contingent after that, the payment factor being the samemax(C, L)the projection uses, with the survival probabilities taken conditional on being alive atfrom_mth:a = sum over k of (1/m) * v^((s_k - from_mth)/12) * max(C_k, L_k)
Called with
from_mth = start_mthit isa^(m)_y(f; i), the payout factor at the income start age; called withfrom_mth = k, a premium’s month, it isa_def(x(k), d, f; i)directly, which is what makes the joint forms work. Equation (15)’s expansiona_def^(both) + s * sum_i a_def^(only i)is algebraically this sum with the either trigger, so no separate joint kernel is needed. The convertible variant, equation (16), is not implemented; the base is non-convertible [std].The certain instalments are weighted by the probability that the income phase is reached at all - see
surv_to_payout(). Without that weight the deferred factor would treat a guarantee period as payable to an annuitant who died in the deferral, and equation (1)’sv^d * _d p_x * a^(m)would not be recovered.Every month is a policy month, and every survival probability is the pricing curve’s,
lives_if_pm(), from issue:DIA_US_S’s own sum, read at the same months. The survival at each payment point is carried forward month by month fromlives_if_pm(start_mth), in one pass, at the rates ofmort_rate_mth_py(), the same products in the same order asDIA_US_S’s recursion, so the factor isDIA_US_S’s to the last bit, with no recursion through the projection.The sum is bounded by
horizon_mths(), not by the frame.horizon_mths()is the policy month the youngest covered life attainsomega_age, which is one past the last projected month on a contract issued at the valuation date - on the anchor cell the frame ends at policy month 719 and the last instalment admitted here falls at month 720. That is deliberate: this is a pricing kernel and must be bounded by the mortality horizon, which is age-driven, rather than byproj_len(), which the pricing feeds. Do not “tidy”lastto the frame’s end; it would move golden values. A pricing engine with a float rate and guarantee, kept asDIA_US_S’s cell for its tests and the twin identity, which no other cell calls:annuity_factor_at()holds its body for the three argument setsDIA_US_S’s callers pass with the final guarantee period, andguarantee_mths_pricing()the same body inline, where the period changes each iteration.
- annuity_factor_at(k, basis)[source]#
annuity_factor()from policy monthk, on the argumentsbasisnames.DIA_US_Scallsannuity_factor()with the final guarantee periodguarantee_mths_pricing()on three sets of arguments, and this is the factor on each, keyed by the month it is valued from and an int code for the rest (the Space docstring’s Codes):PURCHASEa premium’s: from the income start month it is priced to,
income_start_mth_at(), at the pricing ratei_p, valued at its monthk,annuity_factor_def()’s call; andpayout_factor_calc()’s atk = T, whereincome_start_mth_at()isTon every pointDataadmits, an adjustment preceding the old month and the new one following it.ADJUST_OLD,ADJUST_NEWa start-date adjustment’s two factors, at the repricing rate
i_e, valued at the exercise monthk, from the old income start month and from the new one,adjust_income_factor()’s calls.
Any other code raises. The arguments are read in
DIA_US_S’s order, and the body isannuity_factor()’s, the same operations on the same floats in the same order, so the factor isDIA_US_S’s to the last bit: a cell keyed by C integers, whereannuity_factor()takes a float rate and a float guarantee period, which compile with a Python dict for a cache (R14).
- guarantee_mths_pricing_init()[source]#
n_g as the kernel prices with it, carried in force: the column of that name.
On a cash or installment refund in force at the valuation date,
DIA_US_S’sguarantee_mths_pricing(), the guarantee period in months with which every slice of the contract is priced: a fixed point over the whole premium schedule, the slices already bought included. The premium schedule holds only the premiums still due, and the fixed point depends on the path of its iterations, so neither the schedule nor the premiums paid and the income bought can recover it: it is opening state, a quantity fixed at issue and not re-derivable from static data. It prices a premium still due and a start-date adjustment still to come, andpayout_factor_calc()reports it.Datarequires it on every refund form in force, a rule a contract record meets without the schedule, though on one with nothing left to price, in payout say, onlypayout_factor_calc()reads it; it is blank, and unread, on every other point. Read fromData.guarantee_mths_pricing_init.
- guarantee_mths_pricing()[source]#
n_g in months as fed into the pricing kernel, equation (5).
n_g = CP(T) / BputsBon both sides, and the notes’ listed pitfall is “failing to iterate leaves a systematic bias in the derived guarantee period and hence in the income”. Resolved here by fixed-point iteration from a life-only start, the notes’ own prescription (“three iterations from a life-only start are ample”) -pricing_iterscarries the count. The equation (5) approximation is used for both refund forms [std]; the exact cash-refund factor of equation (6) is not implemented.The elected period on a period-certain form and 0 on a life-only form, as in
DIA_US_S. On a refund form the fixed point runs over the premium schedule, which on a point issued at or after the valuation date is the whole schedule, so it isDIA_US_S’s to the last bit; on a contract in force the schedule holds only the premiums still due, and the value is the opening state,guarantee_mths_pricing_init().DIA_US_Ssums and iterates itspremium_by_mth()dict; here the premium months are those of the point’s row ofData.premium_rowswith a row, in ascending order, the dict’s keys in its order, a month with a premium of 0.0 among them, whose ROP factor is read asDIA_US_Sreads it, and each premium ispremium_pm(), the dict’s value.CPis Python’ssumof the premiums written out, the compensated sum CPython 3.12 and later take of floats, so that it isDIA_US_S’s float to the last bit where a running sum is not. And each iteration’s annuity factor isannuity_factor()’s body at the iteration’s guarantee period, inline, since the period changes each iteration: where the premium’s life 1 has died by its month, the factor is 0, asannuity_factor()returns, and the premium is skipped, asDIA_US_Sskips it, the loops going on.
- payout_factor_calc()[source]#
a^(m) at the income start age computed from the shipped table, equation (2).
DIA_US_S’sannuity_factor(T, guarantee_mths_pricing(), pricing_rate, T), which isannuity_factor_at()atTon itsPURCHASEbasis.
- payout_factor()[source]#
a^(m)_{x+d}(f; i_p): the payout annuity factor in force.
On the table basis the notes’ illustrative value - 8.60 for the anchor cell’s
a^(12)_80(cash refund, female; 4.75%)- read from payout_factor_table.csv [std]; on the formula basispayout_factor_calc(). No insurer publishes payout factors for this product and the Compact does not require the basis to be disclosed at all [R13 SS1.B(1)(a)]. The table’s key is the primary life’s age at the income start month,age_at_entry(1) + T // 12on the policy clock, its sex, read from the model point’ssexcolumn as the join key, and the payout stream, from the form decodes, aspayout_form()names it. The join asksdata.payout_factor_count()first, which checks the table’s keys and factors, so that a projection meets the checks before it reads a factor.The table is
Data’s row vectors, the sex numbered by the table’s own sexes,Data.payout_schedule, and the form asData.payout_form_codenumbers it, LO 1, CR 2, IR 3 and PC 4; the join scans the rows for the key, the first match its only one, since the count cell refuses a key on two rows. A key no row holds, a sex the table lacks among them, is refused, naming the point and the key, whereDIA_US_S’s.locraisedKeyError.
- rop_factor_calc(k)[source]#
A_rop for a premium paid in policy month k, by the notes’ mid-band approximation.
Equation (3) is a monthly sum; the notes state their illustrative factors were “computed from the same survival anchors with a mid-band death-timing approximation”, which is what this implements: deaths in each five-year band of the deferral, discounted from the midpoint of the band. Zero when the contract carries no deferral death benefit, which is the
1{db_form = ROP}indicator of (4).The exposure is the last-death curve
l_last, not the primary life’s. Equation (3) is written on a single lifexand the notes never restate it for a joint contract, but the benefit this factor has to pay for is the oneclaims()projects, and on a joint contract that attaches to the last death - “if one annuitant dies in deferral the contract continues on the option chosen at issue” [S2], so the return of premium falls due only when the contract ends. Pricing the primary life’s death density instead would charge for an exposure 2.5 times the one projected (0.161605 against 0.064105 on the joint model point) and understate the income the premium buys by about 12.5% - the notes’ own listed pitfall that the deferral death benefit’s cost “belongs in the purchase rate (4) and in the projected cash flows”, read as requiring the same benefit in both. On a single-life contractl_lastis the primary curve, so this changes nothing on the worked example. On the pricing curve,lives_if_last_pm(), from issue; keyed by the premium’s policy month,DIA_US_S’strenamed. Each band is discounted aspricing_disc_factor()discounts, written inline.
- rop_factor(k)[source]#
A_rop(x(k), d; i_p): the return-of-premium factor of a premium in policy month k.
On the table basis the notes’ illustrative values from rop_factor_table.csv [std]; on the formula basis
rop_factor_calc(). The two disagree on the twenty-year slice - 0.157900 printed against 0.161605 computed - while agreeing to four decimals on the fifteen-year slice; both readings are shipped and a test pins the gap open. See the Space docstring. The table’s key is the primary life’s age at the premium,age_at_entry(1) + k // 12on the policy clock, its sex, read from the model point’ssexcolumn as the join key, and the deferral in whole years,rop_deferral_yrs(). The join asksdata.rop_factor_count()first, which checks the table’s keys and factors, so that a projection meets the checks before it reads a factor. It scansData’s row vectors aspayout_factor()scans its table’s, the sex numbered by the table’s own sexes,Data.rop_schedule, and a key no row holds is refused, naming the point and the key, whereDIA_US_S’s.locraisedKeyError.
- rop_deferral_yrs(k)[source]#
The deferral of a premium in policy month k in whole years: the ROP table’s key.
DIA_US_S’sint(round(deferral_yrs(k))),(T - k) / 12rounded half to even, computed on the integers: the monthsn = T - kare12q + r, and the rounding isqbelow a half year,r < 6,q + 1above it, and at a half year exactly,r = 6, the even of the two. Away from a half year the floatn / 12.0is at least a month from it, so its rounding error cannot cross it, and at a half year it isq + 0.5exactly: so this isround’s whole number at everyk, without a Python call in a compiled cell (R16).//floors on a negativenas Python’s does, compiled too. Keyed by the premium’s policy month.
- annuity_factor_def(k)[source]#
a_def(x(k), d, f; i_p): the APV at policy month k of $1 p.a. from T, equation (1).
On the table basis, equation (1) literally,
v^d * _d p_x * a^(m). That factorization is single-life only - a joint status does not separate into a deferral survival times a payout APV - so a joint model point must use the formula basis, where the whole deferred stream is valued in one pass byannuity_factor(), andDatarefuses a joint point on the table basis, naming it. Keyed by the premium’s policy month,DIA_US_S’strenamed. The discount is written aspricing_disc_factor()writes it, and each factor of the product is read inDIA_US_S’s order before the product is taken, in its order; the formula basis isannuity_factor_at()on itsPURCHASEbasis.
- purchase_rate(k)[source]#
pr(x(k), d, f): annual income bought per $1 of premium in policy month k, eq (4).
pr = [ (1 - L) - 1{ROP} * A_rop ] / a_def- the equivalence principle applied per premium, which is the core of the product: income is additive across slices, each priced at the annuitant’s attained age and the remaining deferral at its own payment date [R13 SS3.B(1)(b)][S3]. Nothing accumulates and there is no balance to roll forward. The whole kernel is [std]: no purchase-rate table was obtained and none is published.purchase_rate_dprounds the result, 6 on the worked example’s model point; see the Space docstring. Keyed by the premium’s policy month,DIA_US_S’strenamed, so a premium still due at the valuation date is priced asDIA_US_Sprices it. The rounding stays, a call of Python’sroundin a compiled cell, which the registry’s"python_calls"admits here alone: the rate is built fromProjection’s References, the pricing rate and the expense load, whichDatacannot read, so it cannot be rounded there (R16).
- adjust_income_factor()[source]#
B’/B on a start-date adjustment, equation (11).
Actuarial equivalence at the exercise month [std]:
B' = B(t_e) * a_def(x(t_e), (T - t_e)/12, f; i_e) / a_def(x(t_e), (T' - t_e)/12, f; i_e)
a_defdecreases in the deferral, so deferring the date raises the payment and advancing it lowers it, matching the extended case’s statement [S4][S5]. Two refinements the disclosed recipe does not mention are flagged rather than modeled, as the notes require: the return-of-premium exposure changes with the deferral length, andCPis unchanged so the derived guarantee period shifts. Priced at the exercise’s policy month on the pricing curve, so it isDIA_US_S’s factor; a contract valued after the exercise carries the repriced income inannual_income_init, and nothing reads the factor there. The two factors areannuity_factor_at()at the exercise month on itsADJUST_OLDandADJUST_NEWbases,DIA_US_S’s two calls ofannuity_factor().
- annual_income_init()[source]#
B at the valuation date: the guaranteed annual income per contract bought before it.
The
annual_income_initcolumn, the income entering month 0, before COLA and before the slice, if any, bought at its start:DIA_US_S’sannual_income(d - 1)on a point restated at its monthd, a start-date adjustment exercised beforedincluded. The opening value ofannual_income()att_entry(); on a contract past its income start month it is the incomeB(T), level in payout. 0 at issue, and so on every point not yet in force, asDatachecks. Read fromData.annual_income_init.
- annual_income(t)[source]#
B(t): the guaranteed annual income purchased to date, before COLA, equation (8).
B(t) = B(t-1) + sum of P_k * pr(x(t_k), (T - t_k)/12, f)at the premiums of montht, plus the repricing factor of equation (11) in the month a start-date adjustment is exercised. The recursion opens att_entry(), on the opening state,annual_income_init(), the income bought before the valuation date, which is 0 on a point issued at or after it.B(t)is the income in force during montht, including a slice bought at its start. Income is additive across slices and each slice is fully guaranteed from the moment its premium is paid [R13 SS3.H(1)]. The exercise month and the purchase rate are read at the policy month of montht. Zero outside the frame.
- annual_income_payout()[source]#
B(T): the guaranteed annual income per contract at the income start month.
annual_income_init(), then one loop over the policy months from the valuation date’s to the income start monthT, applying the repricing factor at the exercise month and adding each premium’s slice at its purchase rate, the same operations in the same order as the recursionannual_income(), soB(T)isDIA_US_S’sannual_income(T)to the last bit. On a contract past its income start month the loop is empty andB(T)is the opening state. The income is level fromTon: no premium falls at or after it and a start-date adjustment precedes its new start month, asDatachecks. So this is the income of every instalment of the payout schedule,annuity_pp_sched_pm(), which the refund, the commuted value and the accelerated payments read at policy months ahead oftwithout readingannual_income()there.
- guarantee_yrs()[source]#
n_g realized: the derived guarantee period in years, equation (5).
CP(T) / B(T)on the refund forms - 150,000/44,259.65 = 3.3891 years on the anchor cell, so its cash-refund guarantee is exhausted during the fourth payment year, at attained age about 83.4. The elected period on a PC form, zero on a life only form. Distinct fromguarantee_mths_pricing(), which is the fixed point the kernel uses beforeBis known. Read from the payout schedule’s two static quantities,cum_premium_payout()andannual_income_payout().
- is_payout(t)[source]#
Whether month t is in the income phase,
duration_mth(t) >= T, inside the frame.Deaths in months before
Tare deferral-phase deaths attracting the return of premium; deaths fromTon are payout-phase deaths attracting the form’s refund benefit.Tis a policy month, compared with the policy clock. False outside the frame.
- phase(t)[source]#
PRE_ISSUE, DEFERRAL, PAYOUT or TERMINATED in month t.
PRE_ISSUE before a point issued after the valuation date is issued; TERMINATED from the stop rule on,
t = proj_len(), the first month past the frame. Each an int code (the Space docstring’s Codes), whereDIA_US_Sreturns text.
- is_payment_pm(k)[source]#
Whether an instalment falls in policy month k: the payment schedule, by policy month.
Arrears: the n-th instalment falls at the end of policy month
T + n*(12/m) - 1, so the first lands at the end of monthTwhenm = 12- one payment period after the income start date, which is why policy year 21 of the anchor cell carries the first twelve payments. Advance: the n-th falls at the start of policy monthT + (n-1)*(12/m), one full payment period earlier. False beforeT. Keyed by policy month and counted fromTinside, so thatis_payment_mth()asks it at the policy month of month t andannuity_pp_sched_pm()at any policy month.
- is_payment_mth(t)[source]#
Whether an instalment falls in month t:
is_payment_pm(duration_mth(t)).The schedule is the contract’s, on the policy clock (
is_payment_pm()). False outside the frame.
- payment_surv_mth(t)[source]#
The time point at which survival is measured for the instalment falling in t.
Arrears: the end of month t, time
t + 1. Advance: the start of month t, timet. A time point on the valuation clock, wherelives_if()is indexed. Using end-of-period survival for advance payments understates the liability by about one period’s mortality per payment.
- cola_factor_pm(k)[source]#
(1+c)^floor((k-T)/12): the COLA escalation applying in policy month k.
Fixed compound, on each anniversary of the income start date, elected at issue and irrevocable [S2][S3][S4]. One in the deferral and in the first payout year. Keyed by policy month and counted from
Tinside, the one COLA formula, whichannuity_pp_sched_pm(),accel_cost()andannuity_payments_ann()read at policy months, andcola_factor()at the policy month of month t.
- cola_factor(t)[source]#
(1+c)^floor((t-T)/12): the COLA escalation applying in month t.
cola_factor_pm(duration_mth(t)), on the policy clock: one in the deferral and in the first payout year, whatever the valuation date. One outside the frame, a factor that moves nothing.
- annuity_pp_sched_pm(k)[source]#
inst(k) = B(T)/m * (1+c)^floor((k-T)/12): the scheduled instalment in policy month k.
Zero outside payment months. Scheduled, not paid: an acceleration blackout or a commutation may suppress it. The payout schedule, fixed at the income start month by
annual_income_payout(), on whichBis level, so it isDIA_US_S’sannual_income(k) / m * cola_factor(k)at every payment month. Keyed by policy month, on the policy clock, so thatcum_annuity_pp(),commuted_value()and the acceleration’s lump sum read the schedule at policy months after month t without passing a policy month ast;annuity_pp_sched()is this at the policy month of month t.
- annuity_pp_sched(t)[source]#
inst(t) = B/m * (1+c)^floor((t-T)/12): the scheduled instalment per contract.
annuity_pp_sched_pm(duration_mth(t))inside the frame, and 0 outside it. Zero outside payment months. Scheduled, not paid: an acceleration blackout or a commutation may suppress it.
- cum_annuity_pp(k)[source]#
G(k): cumulative scheduled instalments per contract to the end of policy month k.
A deterministic as-if-alive schedule - instalments payable while any covered life is alive follow the deterministic escalation path - so the refund balance needs no path simulation, and no opening state. A closing balance, one month ahead of the start-of-month
refund_balance()that consumes it. Keyed by policy month,DIA_US_S’strenamed, soG(k)reads as the notes write it on a contract in force as on new business; 0 before the income start month.The recursion
G(k) = G(k-1) + inst(k)isDIA_US_S’s, but it is based where the valuation date falls: at the policy month before the valuation month, or before issue on a contract issued later,max(duration_mth_init(), 0) - 1, a key fixed by the model point that reads no clock, one loop sums the instalments from the income start month to it, the same additions in the same order as the recursion, soGisDIA_US_S’s to the last bit. The refund readsGfrom there on and recurses back to it, and the installment refund’s search reads it upward from the first payment point, recursing back no further than the key it read before. Recursing from the income start month instead, the first refund of a cash refund long in payout would recurse as deep as it has been paying.
- certain_mths_refund()[source]#
n_R: the certain period an installment refund derives, in months.
Payments “continue in the same amount and frequency until they equal the purchase payments” [S2], so
n_Ris the offset of the first payment month at which cumulative instalments reachCP(T). Searched rather than closed so that a COLA path still resolves, and bounded by the mortality horizon so that it never depends onproj_len(), which depends on it - and that bound ishorizon_mths(), one month past the last projected month of a contract issued at the valuation date, for the same reason as inannuity_factor(). [std]: the month grid rounds the guarantee up to a whole instalment rather than trimming the last one, which is what the notes’ “exactly a certain-and-life annuity with n_g = CP(T)/B” framing implies; the payout chassis trims instead. A count of months fromT; the search runs over policy months on the payout schedule,cum_annuity_pp(), against the refund basecum_premium_payout(), so its result does not depend on the valuation date.
- certain_mths_eff()[source]#
n_eff: the effective certain period in months, by payout form.
12 * non a period certain form;n_Ron installment refund; zero on cash refund and life only. A cash refund is a lump-sum shortfall paid at death, not a stream of guaranteed payments - equation (5) treats it as certain-and-life for pricing only, and carrying that into the projection would pay the guarantee twice. A count of months fromT: the guarantee covers policy monthsT ... T + n_eff - 1, so a contract in forcedmonths has the months toT + n_effleft, and none onced >= T + n_eff.
- certain_floor_pm(k)[source]#
C(k) = 1{the instalment in policy month k falls inside the guarantee period}.
0 <= k - T < n_eff: keyed by policy month and counted fromTinside, so thatcertain_floor()asks it at the policy month of month t and the acceleration’s lump sum at the policy months of the instalments it pulls forward.
- certain_floor(t)[source]#
C(t) = 1{the instalment in month t falls inside the guarantee period}.
certain_floor_pm(duration_mth(t))inside the frame, and 0 outside it. The certain months left at the valuation date are therefore no opening state: they follow fromduration_mth.
- payment_factor_life(t)[source]#
L(t): the life-contingent payment factor for the instalment falling in month t.
Survival is measured at
payment_surv_mth(), not at t. By form and trigger:single life: L = l_1 joint, trig = either: L = l_1*l_2 + delta*(l_1 + l_2 - 2*l_1*l_2) joint, trig = primary: L = l_1 + delta*(1 - l_1)*l_2
The either form pays the full instalment while both are alive and delta while exactly one is; the primary form pays in full while the primary lives whatever the joint annuitant’s status. The two coincide on the primary’s death and differ only on the secondary’s, which is why the trigger is a switch and not a footnote. On a joint contract in force with one life already dead, as point 23 is, the factor is delta times the survivor’s survival from
t = 0. Zero before the income start date, and outside the frame.
- surv_to_payout_init()[source]#
l_last(T) carried in force: the cohort that reached the income phase.
The
surv_to_payout_initcolumn, on a contract whose income start month precedes the valuation month:DIA_US_S’ssurv_to_payout(), the probability, from issue, that a covered life was alive at the income start month. The lives at the valuation date cannot say it: in a certain period the contract stays open after the last death, its guarantee running on to a beneficiary, so the cohort the guarantee pays exceeds the survivors, 0.715 against 0.5577 on point 20, in force 300 months. On a real record in payout it is 1. Read only where the certain floor is positive, so on a period certain or an installment refund;Datarequires it on every contract past its income start month, a rule a contract record meets without the certain period, though on a cash refund or a life-only form nothing reads it. Blank elsewhere. Read fromData.surv_to_payout_init.
- surv_to_payout()[source]#
l_last(T): the probability that the income phase is ever reached.
The one place the payout chassis cannot be carried across unexamined. A SPIA is already in payment, so
SPIA_US_Sweights its certain floor by nothing:C(t)is a bare indicator. A DIA’s guarantee period only begins if the contract reaches the income start date - an annuitant who dies in the deferral receives the return-of-premium benefit and no instalment is ever paid - so on an expected basis the certain instalments carry this factor. Without it a period certain or installment refund contract would pay its guarantee with probability one and overstate the liability by the whole deferral mortality. The DIA notes inheritL_payand its “certain inside a guarantee period” wording from the immediate-annuity notes without adjusting for the deferral; this is that adjustment, and it is the same weight equation (1) applies through_d p_x.A frozen weight: on a contract valued after its income start month, the opening state,
surv_to_payout_init(); otherwiselives_if_lastat the income start month on the valuation clock,T - duration_mth_init(), which on a contract valued at its income start month is time 0. Read only where the certain floor is positive, from the income start month on, so never ahead of the month that reads it.
- payment_factor(t)[source]#
Phi(t) = max(C(t) * l_last(T), L(t)): the master payment factor.
The
maxmakes the certain period an annuity-certain floor rather than an additional stream: during the guarantee the full unreduced instalment is payable regardless of survival after the income start date, and themaxprevents paying1 + L. An additive construction silently doubles the guarantee - the payout chassis’ first-listed pitfall - and, because the floor pays the unreduced instalment, it also reproduces with no extra flag the rule that a survivor reduction inside a guarantee period is deferred to the end of that period [S1][S3]. Thel_last(T)weight on the floor is the DIA’s own; seesurv_to_payout(), which is read only where the floor is positive: elsewhere the floor is 0, asDIA_US_S’s0 * l_last(T)is.
- refund_balance(t)[source]#
RG(t) = max(0, CP(T) - income scheduled through the end of policy month m-1).
m = duration_mth(t). Them - 1is the arrears convention: an instalment due at the end of the death month has not been paid, so a death betweenTandT + 1/myields a cash refund of the fullCP(T). On advance timing an instalment paid at the start of the death month has been paid, so the balance is measured atmthere or the lump sum is overstated by one instalment.CP(T)iscum_premium_payout()andGthe payout schedule’scum_annuity_pp(), by policy month. Zero before the income start month and outside the frame.
- accel_blackout(t)[source]#
Whether payments are suspended in month t by a payment acceleration.
Six monthly payments are made in one sum at
t_aand no payment is made for the following five months [S1][S4]. The feature is expressly “not a liquidity feature” [S2] - a timing shift, not a withdrawal - and modelling it as a withdrawal is one of the notes’ listed pitfalls.t_a < duration_mth(t) <= t_a + 5, on the policy clock; False outside the frame.
- accel_cost()[source]#
Cost(t_a): the economic cost of a payment acceleration, equation (12).
(B/m) * sum over j = 1..n_a-1 of [ 1 - v^(j/m) * _{j/m} p_x(t_a) ]. Accelerated payments are made unconditionally, so the insurer forgoes the survivorship and interest discount on payments 2 throughn_a. Small but real, and the reason the feature is capped in uses and gated at age 59 1/2 - the gate itself being driven by the IRC SS72(q) 10% additional tax [R8][REG-R55]. Reported, not added to the cash flows: the cost is already implicit in paying them early. Only the mortality element of it surfaces in the projected cash flows, because they are undiscounted - on the anchor configuration 435.11 per exercising contract here against 153.52 of extra lifetime income outgo, the difference being the interest termv^(j/m)that an undiscounted projection has nowhere to put. Priced at the exercise’s policy month on the pricing curve,lives_if_pm(), with the instalment of the payout schedule, so it isDIA_US_S’s cost whatever the valuation date. Each instalment is discounted aspricing_disc_factor()discounts, written inline.Databounds the exercise month from below alone, and the pricing survival’s cache ends at policy month 1,446 (spec_sec.py). Past the age stop,12 * (omega_age - age_at_entry(1)), withmort_ae_factor1 or more, the rate is 1 from the limiting age on, soDIA_US_S’s survival in every later month is the one float it reaches a month after the stop, 0 on a finite curve, and its cost 0: the survival is read there, and the cost isDIA_US_S’s, compiled as in modelx, however late the exercise, which the projection never reaches (M24). Below an A/E of 1 the rate past the limiting age is the A/E, the survival positive, and it is read at the exercise month asDIA_US_Sreads it: past the cache, from an exercise at policy month 1,442, that read raisesIndexErrorin the compiled model alone, where modelx reads on asDIA_US_Sdoes (model-sec.md, What it refuses).
- accel_payment_factor(t)[source]#
Phi for an instalment scheduled in month t but paid in the acceleration lump sum.
The six instalments are paid in one sum at
t_a[S1][S4], so the five that are pulled forward are paid unconditionally: their survivorship is frozen at the date the lump sum falls -payment_factor_lifein the exercise month, the same weight the first instalment of the block carries - instead of being measured at their own scheduled dates. That frozen weight is the mortality element equation (12) prices; the interest element of (12) does not appear in an undiscounted projection.A guaranteed instalment is untouched. Its weight is already
C(t) * l_last(T), independent of survival after the income start date, so accelerating it forgoes no survivorship - which is why themaxis taken against the certain floor exactly aspayment_factor()does, and why equation (12)’s cost is zero inside a guarantee period and strictly positive outside it.DIA_US_S’s weight in a blackout month whose exercise is on the books, the exercise month at or after the valuation date, and 0 in every other month: with no acceleration, outside the blackout, and where the lump sum was paid before the valuation date, from which on nothing reads the factor.annuity_payments()computes the same weight in the exercise month itself, reading the payout schedule by policy month, so this cell isDIA_US_S’s, for its readers and for the twin identity, and no projection cell calls it.
- commute_frac_cum(t)[source]#
theta_cum(t): the cumulative commuted fraction applying in month t.
Zero before the exercise month and
commute_fracfrom it, the exercise falling at the start of the month and so reaching that month’s own instalment - the notes’ processing order puts option exercises ahead of the income payment. It multipliesC(t)inannuity_pp_paid(), so it reaches guaranteed instalments only: if the annuitant is alive when the would-be guarantee period ends, income resumes until death, the life-contingent tail not being commuted [S4]. Applying it to that tail contradicts every retrieved contract. The commutation is one exercise named on the model point, so the fraction follows from the policy clock,duration_mth(t) >= t_c, and needs no opening state. Zero outside the frame.
- commute_weight_init()[source]#
l_last(t_c) carried in force: the cohort that commuted.
The
commute_weight_initcolumn, on a contract whose commutation month precedes the valuation month:DIA_US_S’slives_if_last(t_c), the probability, from issue, that a covered life was alive to exercise the commutation, and so the cohort whose guaranteed instalments it extinguished. The lives at the valuation date cannot say it: the contracts whose annuitant died betweenTandt_ckeep their guarantee, running to the beneficiary, so the residual guaranteed stream isl_last(T) - l_last(t_c). On a real record of a commuted contract it is 1. Given exactly where the commutation precedes the valuation month, asDatarequires, and blank elsewhere. Read fromData.commute_weight_init.
- commute_weight(t)[source]#
l_last(t_c): the expected size of the cohort a commutation extinguishes in month t.
The one weight the payout chassis has no need for, and the mirror image of
surv_to_payout(). A commutation is exercised by an owner who is alive att_c[S4], so it can only extinguish the guaranteed instalments of thel_last(t_c)sub-cohort. The rest of the cohort that reached the income phase -l_last(T) - l_last(t_c), contracts whose annuitant died betweenTandt_c- keeps its guarantee running to the beneficiary and is unaffected. On the shipped commutation model point those two weights are0.715000and0.680338, andl_last(t_c)is the one this model applies: applying the commutation to all of the first would cancel 4.85% more guaranteed liability than the commuted value pays for.Zero outside a guarantee period, before the exercise month, and on a contract that never commutes. Bounded above by
payment_factor()becauset_c >= T, whichDatachecks, so the surviving expected instalment is never negative. A frozen weight: on a contract that commuted before the valuation month, the opening state,commute_weight_init(); otherwiselives_if_lastat the commutation month on the valuation clock,t_c - duration_mth_init(), read from that month on.
- ref_rate_shift_init()[source]#
The reference rate’s change from issue to the valuation date.
The
ref_rate_shift_initcolumn, a decimal, 0.005 for a rise of 50 basis points, of either sign: the reference rate at the valuation date less the reference rate at the contract’s issue, the part of the change since issue that a contract in force has already seen. The commutation discount rate moves with the change since issue, floored at 0 (commute_disc_rate()), and that change began beforet = 0, so its value there is opening state, as a rate’s value at the start of a term would be on a market path. A fact of the market, not of the contract’s own history: two contracts issued together carry one value. 0 at issue, and so on every point not yet in force, asDatachecks. The change made at the valuation date isref_rate_shift, which a contract issued later has not seen (commute_disc_rate()). Read fromData.ref_rate_shift_init.
- commute_disc_rate(t)[source]#
i_c(t) = i_p + max(0, r_ref(t) - r_ref(0)) + m_c: the commutation rate, eq (13).
One-sided by construction - it rises with rates and does not fall - implementing the Compact’s stated intent that the adjustment “reduce interest risk in the event of rising interest rate after issue” and its required disclosure that “the higher the interest rate the lower the commuted value” [R13 SS3.F(7)]. The actual contractual formula is not published anywhere [S4][S5], so this is [std] and [unverified].
Every contract of a block reads the change since its own issue on one path of the reference rate, which every point shares, as it shares every economic input. A contract on the books at the valuation date, in force or issued then,
t_entry() == 0, has seenref_rate_shift_init()by that date, from its model point, and seesref_rate_shift, the change made at the valuation date, from month 0 on, asDIA_US_S’s contract sees itsref_rate_shiftfrom issue; a contract issuedt_entry()months later is bought after that change and has seen none of it, its column being 0. The floor applies to the whole change since issue, the two parts added first,i_p + max(0, ref_rate_shift_init() + shift) + m_cin that order, so a fall before the valuation date offsets a rise at it, and on a point issued at the valuation date the rate isDIA_US_S’si_p + max(0, ref_rate_shift) + m_cto the last bit. One Reference could not hold the change since each contract’s own issue: contracts issued at different dates have seen different changes.ref_rate_shiftis a flat scalar, a path that steps once, at the valuation date, so the rate is level and reads neither clock; a reference-rate path would be another input table, read on the valuation clock.
- commuted_value(t)[source]#
CV(t): the commuted value of the remaining guaranteed payments, equation (14).
sum over j in J_g(t) of (B/m) * (1 + i_c(t))^(-(j - m)/12), whereJ_gis the set of remaining guaranteed payment months andm = duration_mth(t). Zero on a form with no guaranteed stream: a cash refund is a lump sum at death, not a schedule of payments, so there is nothing to commute. Non-zero only in the exercise month. The guaranteed instalments are read from the payout schedule by policy month,annuity_pp_sched_pm(), in one loop, so that no month of the frame ahead of t is read. Zero outside the frame.
- commutations(t)[source]#
E[COMM(t)]: the commutation payment made to the owner in month t.
CV(t) * l_last(t): the commuted value is paid to the cohort alive to exercise, which is the samel_last(t_c)weightcommute_weight()removes from the guaranteed instalments, on the contracts on the books. The two must agree, andcheck_commutation_value()asserts that they do - discounted ati_c, the value paid out equals the value suppressed. Zero in the base run - commutation exists only in the extended case [S4][S5] - and prohibited on a QLAC after the required beginning date other than a rescission period not exceeding 90 days [R1 (q)(1)(iv)][R2 SS202(a)(4)]. Zero outside the frame.
- annuity_pp(t)[source]#
The instalment per contract payable in month t, before commutation and survival.
Equal to
annuity_pp_sched()except during an acceleration blackout, where the payment has already been made in one sum at the exercise month.
- annuity_pp_paid(t)[source]#
inst(t) * (1 - theta_cum(t) * C(t)): the instalment a commuting contract gets.
A commutation reduces guaranteed instalments only; the life-contingent payments after the guarantee period are untouched, which is what makes the tail resume. Per contract, and only for a contract that actually commuted - which is a sub-cohort, not the whole model point, so
annuity_payments()applies it throughcommute_weight()rather than to the expected instalment as a whole.
- annuity_payments(t)[source]#
E[income] in month t: the instalment weighted over the cohorts entitled to it.
Two cohort splits sit on top of the chassis’
inst(t) * Phi(t), and both are weights rather than per-contract adjustments:E[income](t) = pols * [ inst(t) * (Phi(t) - w_c(t)) not commuted + inst_paid(t) * w_c(t) ] commuted
polsis the count on the books,pols_if_at(t, BEF_DECR).w_c(t)iscommute_weight(), thel_last(t_c)sub-cohort that was alive to exercise the commutation;inst_paidis that sub-cohort’s reduced instalment. Multiplyinginst_paidby the whole ofPhiinstead - the obvious reading of the chassis formula - would cancel the guarantee of contracts whose annuitant died betweenTandt_cand could not have commuted.In the exercise month of a payment acceleration the following
n_a - 1instalments are added at the survivorship frozen at the lump sum’s own date, the exercise month’spayment_factor_life, floored by the certain floor of each instalment’s own month asaccel_payment_factor()floors it - they are paid whether or not the annuitant survives to their scheduled dates, which is precisely the mortality element equation (12) measures - and the months they would have fallen in pay nothing. The instalments and their floors are read from the payout schedule by policy month, so the lump sum reads no month of the frame ahead of the exercise. The lump sum weighs no commutation: after one, it would pay the cohort that commuted its pulled-forward guaranteed instalments unreduced, asDIA_US_S’s does, soproj_len()refuses an acceleration whose lump sum pulls forward instalments of a commuted guarantee.
- claim_pp(t, kind)[source]#
The claim amount per contract in month t, by
kind.DEATH- the deferral death benefit, 100% of cumulative premiums paid without interest as a lump sum at the end of the month of death [S1][S2][S3][S4][R13 SS3.I(1)(a)], zero once the income phase starts and zero on a no-death-benefit form.REFUND- the cash-refund shortfallrefund_balance(), zero on any form other than cash refund, because installment refund and period certain deliver their guarantee as continued payments through the certain floor rather than as a lump sum. Zero outside the frame; any other kind raises,ALL, the total, among them, asDIA_US_S’sclaim_pp(t, None)does.
- claims(t, kind)[source]#
Expected claim outgo in month t, by
kind;ALLtotals the two kinds.Weighted by
lives_death_last(), the death that ends the contract: on a joint contract the first death leaves the contract running on the option chosen at issue [S2], so both the deferral death benefit and the refund attach to the last death, on the contracts on the books,pols_if_at(t, BEF_DECR). The two kinds are mutually exclusive by construction -DEATHis zero from the income start month andREFUNDis zero before it.ALLisDIA_US_S’skind=None, its total, written asDIA_US_Swrites it, the sum of the two kinds’ cells, so that it isDIA_US_S’s float, the sign of a zero included, where a sum from0.0would turn a negative zero positive.
Premium income in month t:
l(t) * sum of P_k at t, received at the start.Deterministic schedule with no attrition [std]: DIA subsequent premiums are wholly discretionary and no source publishes a distribution of them. Dump-in risk differs structurally from a fixed deferred annuity’s - each premium is priced at then-current rates, so there is no rate guarantee to select against unless the contract guarantees paid-up rates for future premiums [R13 SS1.B(1)(h)], which is off in the base [std]. On the contracts on the books,
pols_if_at(t, BEF_DECR), so a point issued after the valuation date brings its premiums as new business.
- inflation_factor(t)[source]#
The expense escalation factor in month t:
(1 + g)^(t // 12)[std].On the valuation clock:
DIA_US_S’s annual steps,(1 + g)^(y(t) - 1), moved ontot, so that the maintenance charge it inflates is in valuation-date dollars, whatever the contract’s age, and every point of a block inflates alike, stepping on each anniversary of the valuation date. On a point issued att = 0the two are the same.
- expenses(t)[source]#
E[EXP(t)] = (e/12) * (1+g)^(t//12) * pols_if(t): maintenance expense in month t.
$50 per contract per year escalated at 2.5%: VM-22 prescribes exactly that for individual Payout Annuity Reserving Category contracts, plus 7 basis points on a present-value base for contracts without an account value [R9]; adopting the prescribed figure as the best estimate is [std], and the 7 bp element is not implemented because this model computes no present-value base. The inflation runs on the valuation clock (
inflation_factor()), and the count is the contracts on the books weighted by survival,pols_if().
- liability_outgo(t)[source]#
Total gross liability outgo in month t, outgo positive.
Income payments, death and refund benefits, any commutation, and maintenance expense. There is no surrender cash flow row, and none should be added - the contract has no cash surrender value at any time before the income start date and none after [S1][S2][R13 SS3.P].
- liability_cf(t)[source]#
The net liability cash flow in month t, outgo positive:
-net_cf(t).Across this library
liability_cfis the net stream carried under the sign the notes that print one use, andnet_cfis the same stream income-positive; the invariantnet_cf(t) == -liability_cf(t)holds in every model that publishes both, and a conventions test asserts it.The distinction that matters here: the notes’ purpose statement projects “premiums in; deferral death benefits, income…”, so premium income belongs in the net stream. That makes this product differ from the
SPIA_US_Spayout chassis it otherwise follows, where the single premium is a pricing input and never a projected cash flow, so there gross outgo and the net stream coincide. The gross outgo alone isliability_outgo().
- net_cf(t)[source]#
Net cash flow to the insurer in month t: premium income less liability outgo.
The sign convention of
Term_US_S.net_cf. Unlike the immediate-annuity chassis this product does carry premium income in the projection, because premiums are flexible and fall throughout the deferral - so premium income nets here, andliability_cf()is this stream negated rather than the gross outgoliability_outgo().
- qlac_room(t)[source]#
qlac_room(t) = Limit - CP(t) - premiums paid to any other intended QLAC.
$200,000 as enacted, indexed with a base period of the calendar quarter beginning July 1 2022 and increments rounded to the next lowest multiple of $10,000; $210,000 for 2026 [R1 (q)(2)(ii), (q)(4)(ii)(A)][R2 SS202(a)(2)][R3][S4]. There is no percentage-of-account-balance limit: SECURE 2.0 SS202(a)(1) directed its elimination and the codified text has no percentage test, so a 25% rule, a $125,000 or $130,000 cap and an RMD age of 70 1/2 are all superseded arithmetic.
- qlac_flags()[source]#
The QLAC conditions this contract fails; an empty list when it complies.
The overlay generates no cash flows of its own - it caps premiums, restricts forms, constrains
T, disables features and raises compliance flags. Loss of QLAC status changes the owner’s RMD position, not the insurer’s liability cash flows. An excess premium ends QLAC status on the date paid unless returned by the end of the following calendar year; any other failure voids status retroactively to purchase [R1 (q)(4)(i)(B), (q)(4)(iii)(A)]. Empty on a contract that is not a QLAC. The premium limit is tested on the premiums paid by the last projected month, and the income start age on the policy clock,age_at_entry(1) + T // 12; the market type and the form are read through the decodes.
- check_lives_roll_fwd_resid(t)[source]#
Residual between
lives_if()and its recursion restated, over both lives.Indexed by a time point on the valuation clock, like
lives_if()itself. For each covered life the survival is restated month by month from the opening state: 0 beforet_entry(),lives_if_init()at it, andl(t-1) * (1 - q(t-1))after it; the residual is the sum of the per-life differences fromlives_if(), plus, on a joint contract, the last-survivor identityl_last(t) - [l_1 + l_2 - l_1*l_2]. Zero to floating point.Deliberately not
DIA_US_S’s telescoping identityl_i(t) - d_i(t) - l_i(t+1):lives_death()is defined as that difference, so the identity is identically zero whateverlives_if()returns and constrains nothing. Restating the recursion from the opening state, a misindexed or mis-based recursion fails it; it shares the monthly rate withlives_if(), which the twin and splice identities check againstDIA_US_S. It reads one month back, so it costs a cell a month, where a running product rebuilt at every time point would hold a dependency graph quadratic in the frame. The last-survivor term is zero by construction, likecheck_payment_factor_resid(), and exists to catch a redefinition oflives_if_last()that broke the independence construction. The signed float at a singlet, for the debugging session that follows acheck_lives_roll_fwd()failure.
- check_lives_roll_fwd()[source]#
Truewhen the in-force roll-forward closes in every projected month.No argument and a bool, the library-wide
check_*shape taken fromCashValue_SE.check_av_roll_fwd(): one call coverst = 0 .. proj_len() - 1, so the same name can be asserted across every model in the library.check_lives_roll_fwd_resid()carries the signed residual at a singlet, the survival recursion restated from the opening state. Mortality is the only decrement here, so a failure means the projection’s survival and its recursion, or the last-survivor construction and the per-life survival, have come apart.
- check_income_roll_fwd_resid(t)[source]#
B(t) - B(t-1)*adj - P_k*prin month t: the income roll-forward residual, eq (8).Zero to floating point. Non-zero would mean income appearing from somewhere other than a premium slice or the one permitted repricing - and nothing else can move it: there is no credited rate, no index, no charge and no balance in this product. The signed float at a single
t;check_income_roll_fwd()is the bool. Att_entry()the prior income is the opening state,annual_income_init(), rather than a month before the books. The exercise month and the purchase rate are read at the policy month of montht. Zero outside the frame.
- check_income_roll_fwd()[source]#
Truewhen income moves only by a premium slice or the permitted repricing.No argument and a bool over every projected
t, the library-widecheck_*shape;check_income_roll_fwd_resid()returns the signed residual at onet. The tolerance is absolute rather than relative becauseBis a currency amount that only ever steps, never accrues.
- check_payment_factor_resid(t)[source]#
Phi(t) - max(C(t)*l_last(T), L(t))in month t: the double-count residual.Zero by construction. Computed anyway because an additive floor -
C + Linstead ofmax(C, L)- is the payout chassis’ first-listed pitfall and would show up here asmin(C, L).check_payment_factor()is the bool over everyt.l_last(T)is read only where the certain floor is positive, aspayment_factor()reads it.
- check_payment_factor()[source]#
Truewhen Phi is the max of the two legs, never their sum, in every month.No argument and a bool, the library-wide
check_*shape. The comparison is exact rather than tolerant: the identity is arithmetical, so any residual at all is a defect and not a rounding artefact.
- check_commutation_value_resid(t)[source]#
PV_ic(instalments suppressed) - commutations(t_c): the exchange residual.A commutation is an exchange, not a benefit: the owner gives up guaranteed instalments and receives their present value at
i_c. On an expected basis the two legs must therefore carry the same cohort weight, and this residual is what catches it if they do not.The suppressed leg is read out of
annuity_payments()itself rather than re-derived - what the projection would have paid,inst(s) * Phi(s), less what it does pay - so weighting the suppression byl_last(T)while paying the commuted value tol_last(t_c)shows up here as a leak equal to the difference: 6,898.37 on the shipped commutation model point. The acceleration block is added back before the comparison so that the two options do not contaminate each other. It is reached where an acceleration falls in a commuted guarantee’s last month, its lump sum pulling forward life-contingent instalments alone:Datarefuses an acceleration within six months of the commutation, the product’s interlock [S4], andproj_len()one whose lump sum would pull forward instalments of the guarantee the commutation reduced, whichannuity_payments()would pay unreduced, asDIA_US_S’s does.Measured at the guarantee’s last month, policy month
T + n_eff - 1, reading back to the commutation montht_c:DIA_US_Stakes the same sum at the exercise month, reading every guaranteed month still to come, which on the valuation clock is a read far ahead of the month that makes it. Here every month read is at or before the month the residual is measured in, and the sum is the same, month by month and discounted ati_c(t_c)from the exercise month, so the residual equalsDIA_US_S’s at the exercise month. Zero to floating point there, and zero in every other month; zero too where the commutation precedes the valuation month, the exchange having closed before it, and where it falls after the guarantee, with nothing to commute.check_commutation_value()is the bool over everyt.
- check_commutation_value()[source]#
Truewhen the commutation exchange closes in every projected month.No argument and a bool, the library-wide
check_*shape;check_commutation_value_resid()returns the signed leak at onet. TriviallyTrueon a contract that never commutes, which is the base run - the residual is identically zero away from the month it is measured in.
- lives_if_ann(y)[source]#
l at the end of policy year y: the survival at the start of policy month 12y.
The annual display’s survival column. Policy year
yspans policy months12(y-1) .. 12y-1, so surviving it means being alive at the start of policy month12y, which is time12y - duration_mth_init()on the valuation clock; 0 for a year that ended before the contract was on the books.
- claims_ann(y, kind)[source]#
Expected claim outgo over policy year y, by
kind; the notes’E[DB]atDEATH.The monthly cash flows summed over the twelve months of the year, those on the books: on a contract in force the months of its valuation year from the valuation date on. Because
CPis constant through a year whose premium falls at its start, this collapses to(l(y-1) - l(y)) * CP(y)on the annual grid - which is exactly how the worked example computes it.ALL,DIA_US_S’skind=None, sums the months’ totals,claims()atALL. Each kind is a plain left-to-right sum, as at stageE, an ulp or two fromDIA_US_S’s compensatedsumin some years: atALL, in 154 of the twins’ policy years at the shipped assumptions on Windows, 152 on Linux and macOS.
- annuity_payments_ann(y)[source]#
The notes’
E[income]: expected income at the end of policy year y.An annual-payment display approximation, not the sum of the year’s monthly instalments: one year’s income
Bescalated for COLA and weighted by survival to the end of the year, on the count the point stands for. The model runs monthly; this cells exists so that the notes’ annual display table can be reproduced and asserted directly. Zero in a policy year that ends before the income start month. The income is the payout schedule’s,B(T), level from the income start month on, and the COLA is read at the year’s last policy month.
- result_cf()[source]#
Result table of monthly cashflows, one row per month
t = 0 ... proj_len() - 1.Row 0 is the valuation month for every model point, so the frames of a block line up and sum row by row; a point issued after the valuation date has zeros until its issue month. The columns are
DIA_US_S’s.
- result_pols()[source]#
Result table of the counts, survival probabilities and payment factors, by month t.
One row per projected month,
t = 0 ... proj_len() - 1, the frame ofresult_cf():pols_if, the count on the books weighted by survival, andpols_new_biz, the contracts issued in the month, asbasiclife.BasicTerm_SE’sresult_polssets its counts out first; thenDIA_US_S’s other columns inDIA_US_S’s order, the survival read at the start of each month, as inDIA_US_S, and every column 0 in the months before a point is issued. The count on the books that weights the cash flows is not a column: it is the table’spolicy_count, from issue to the stop rule.
- result_annual()[source]#
The technical notes’ annual display table, indexed by policy year.
One row per policy year with the columns the worked example prints: the attained age at the start of the year, the premium received at its start,
CP,B, the survival probability at the end of the year, the expected deferral death benefit paid during it, the expected refund, and the expected income at its end on the annual-payment display approximation. The projection itself is monthly; this is the display grid, keyed by the policy year,DIA_US_S’s key, one row per complete policy year to the stop rule, 60 on the anchor cell.A point in force at the valuation date shows the policy years from the one the valuation date falls in, whose row holds the months of that year from the valuation date on: its premium and claims are the year’s on the books, and
CP,Band the survival are the year’s closing values, which a year begun before the valuation date reaches asDIA_US_Sdoes. The years before it are left out, asTerm_US_SEC’s annual report leaves them out. A point issued later starts at policy year 1.