The Projection Space#
The by-policy monthly projection of the IUL_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[6]
is an ItemSpace projecting the table’s seventh row, model point 7, IUL_US_S’s
monthly-premium point restated 65 months on, in force at the valuation date with all
twelve index segments live, and point_id() is its label:
>>> Projection[0].result_av() # the account value roll-forward
>>> Projection[6].result_seg() # the segment ladder, carried in
>>> Projection[6].point_id() # 7, the row's point_id
>>> Projection.idx = 1 # or switch the default, before it computes
Compiled, no cache is ever cleared: set idx, like every Reference, on a model just
imported, before anything is computed, or project through Projection[i]. modelx
recomputes what a Reference reaches when it is set; a compiled ItemSpace takes the
References when it is made and keeps every value it has computed until it is deleted,
and the base Projection and Data keep theirs for good. And it holds each Reference
as a C variable of its shipped value’s type: a float set on an int Reference truncates
toward zero, an int set on a float Reference reads as a float, and text set on a code,
basis or seg_credit_base_conv, is refused with TypeError at assignment, where
modelx’s cell refuses it as it reads it (products/indexed_ul/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 IUL_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
IUL_US_S is rewritten where it depends on the month its frame opens at, where it
must answer for a month outside cover, where it reads the index path, or where it reads a
table at a policy year or an attained age; every other is IUL_US_S’s own.
products/indexed_ul/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, every table as an array indexed by integers, the segment ladder among
them, every timing and kind is an int code, and so are the basis and the credit base’s
convention (Codes, below). IUL_US_S’s coi_rate_scale, a Series, is a
schedule number, coi_schedule(); its claims(t, kind=None) is two cells and
their total, claims_death(), claims_lapse() and claims(); its six
segment cells keyed by a segment’s creation month, seg_bal_pp(t, m) and its
neighbours, are keyed by the segment’s slot, its months since creation,
seg_bal_pp(t, k) (The segment ladder, below); and its crediting engine, five cells
of float arguments, is inlined into cells keyed by the month, seg_return(),
seg_credit_rate() and index_credit_pp(), the five kept for its worked example
and called by no projection cell (Reporting cells, below).
Input data
Inputs are external files: plain CSVs living in the model folder’s parent
directory, products/indexed_ul/, 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
IUL_US_SEC folder without its parent’s CSVs produces a model that reads and then
fails on first evaluation.
The readers live in the unparameterized Data Space, reached here
through the data Reference, so each file is read once per model rather than once
per model point. The six assumption tables are the files IUL_US_S reads, read
in place; the model point table and the segment ladder are this model’s own:
Reference (on Data) |
Cells |
File |
|---|---|---|
model_point_file |
data.model_point_table() |
model_point_table_sec.csv |
inforce_segments_file |
data.inforce_segments() |
inforce_segments_sec.csv |
coi_rates_file |
data.coi_rates() |
coi_rates.csv |
corridor_file |
data.corridor_factors() |
corridor_factors.csv |
mort_table_file |
data.mort_table() |
mort_table.csv |
class_factor_file |
data.class_factor_table() |
class_factor_table.csv |
lapse_table_file |
data.lapse_table() |
lapse_table.csv |
surr_charge_file |
data.surr_charge_table() |
surr_charge_table.csv |
The index path is not a file. The base deterministic run generates
index_level() from a level annual return, and a historical or simulated path is
substituted by overriding that one cell, before the model computes anything: a formula
override, which only modelx can make; compiled, the path is changed by editing the
formula and rebuilding.
Two clocks
t counts months from the valuation date, 0-based, the clock
basiclife.BasicTerm_SE runs on: t = 0 is the valuation month for every model
point, however old the policy, month t runs from the monthiversary at time t to
the next, and the frame is t = 0, 1, ..., proj_len() - 1, where proj_len()
counts the months from the valuation date to the end of the projection. Row t is the
same month for every point, so the frames of a block line up and sum row by row.
duration_mth(t) counts policy months, the notes’ own month index from issue:
duration_mth(t) = duration_mth_init() + t, where duration_mth_init() is read
from the model point – positive for a policy in force at the valuation date, in any month
of its policy year, 0 for one issued at it, -k for one issued k months later, at
most ten years later. Everything contractual reads it: the anniversary premium
(duration_mth(t) % 12 == 0), the first policy years of the withdrawal and the loan,
the maturity of a segment twelve policy months after its creation, the surrender charge’s
month, the no-lapse period and its expiry shock, the GPT and 7-pay years, the COI scale
and the lapse table by policy year, the mortality rate and the corridor factor at the
attained age, the policy-year steps of the per-unit charge and of the collateral’s
credited rate, the cessation of premiums and charges at charges_cease_age and the end
of the projection at maturity_age. The policy year is the 1-based contractual label
policy_year(t) = duration(t) + 1 and the attained age (ANB) is
age(t) = age_at_entry() + duration(t), both derived and never indexed by. Point 7,
IUL_US_S’s point 4 restated 65 months on, is in policy year 6 at attained age 50 at
t = 0, and point 12, to be issued 25 months after the valuation date, is issued at
t = 25.
IUL_US_S already counts its months from the start of its own projection rather than
from issue, but ships no point in force, and its in-force entry loses what a policy’s past
has left it: it opens the fixed account at the account value less the loan, the loan
collateral at the loan, the face at issue, both premium accumulators at 0, and no index
segment before its first month. What the valuation clock adds is that t = 0 is one
instant for every point, that a point may be issued after it, and that a point in force
brings in its whole state: the fixed account and the collateral apart from the loan, the
face in force, the premiums paid to date and the no-lapse accumulator, whether it has
failed the 7-pay test, and its live index segments.
The economic inputs read the valuation clock. The index path,
index_level(t) = index_level_init x (1 + index_return_ann)^(t / 12), is one path for
every point, whose level at the valuation date is index_level_init; IUL_US_S
reads it at duration_mth(t), a path of each point’s own from its issue. The cap in
force (index_cap_at()) and the fixed-account rate (fixed_rate_ann()) are read
at t, and are level as shipped. Expense inflation is
inflation_factor(t) = (1 + inflation_rate)^(t // 12), IUL_US_S’s step by policy
year moved onto t, so that the maintenance expense is in valuation-date dollars for
every point alike; it is 0 as shipped. Acquisition is charged per policy issued, in the
issue month, and is not inflated, as in basiclife.BasicTerm_SE. The collateral’s
credited rate and the per-unit charge step on the policy year, as terms of the contract.
A segment’s credit is a ratio of two index levels, its level at maturity over its level at
creation, so moving the path onto the valuation clock moves no credit. A segment created
in the frame, at month t - 12, reads index_level(t - 12) and the cap declared then,
index_cap_at(t - 12); a segment created before the valuation date carries its start
level on the same path, the level IUL_US_S reads at its creation rebased so that the
path’s level at the valuation date is index_level_init, and the cap declared at its
creation (seg_index_start(), seg_index_cap()). What does move is the level
itself: on a point in force d months, index_level(t) is IUL_US_S’s level at its
month t + d divided by (1 + index_return_ann)^(d / 12), and so is the
index_level column of result_seg().
On a point issued at t = 0 the two clocks coincide and this model computes what
IUL_US_S computes: every cell the two share agrees at every argument
IUL_US_S evaluates in its sweep, but for four whose meaning changed:
pols_if_init, now the count already in force at the valuation date, model_point,
a row of another table, result_pols, which gains the month’s new business, and
check_margin, whose identity this model states with the debt a surrender recovers (see
check_margin()). tests/test_model_conventions.py asserts it cell by cell.
The value state variables are closing balances at the end of month t, the notes’
X_{t+1}: av_pp(), fa_pp(), lca_pp(), loan_bal_pp(),
seg_bal_pp(t, k), sum_assured_at(), and the two premium accumulators,
cum_prem_pp() and cum_prem_net_pp(). The opening value of a month, the notes’
X_t, is the BEF_PREM timing of av_pp_at(), fa_pp_at() and
lca_pp_at(), or the previous month’s value of the others, and at t_entry(),
the first month on the books, the model point’s opening state instead, so that nothing is
ever asked for a month before the valuation date or before issue. For a point in force the
opening state is its row and its segments, per policy, as the policy stands at the start
of month 0, before any month-0 event: the account value and the loan, IUL_US_S’s own
columns (av_pp_init(), loan_bal_init()); the fixed account and the loan
collateral (fa_pp_init(), lca_pp_init()); the face in force
(sum_assured_init()); the premiums less withdrawals paid to date and the no-lapse
accumulator, premiums less withdrawals and loans (cum_prem_init(),
cum_prem_net_init()); the MEC latch (is_mec_init()); and each live segment’s
balance, deductions and draws to date, start level and cap, from the segment ladder (see
The segment ladder, below). At a mid-year valuation the current year’s anniversary
premium and loan draw are already inside them. For a point issued at or after the
valuation date every one of them is 0, and the issue values come from the formulas, as
in IUL_US_S.
Every chain is one cell a month. Each opening timing forms the previous month’s close
itself, from its own value at t - 1 and month t - 1’s premium, credit, draws,
deduction, sweep and interest, the same operations in the same order as the closing cell
IUL_US_S calls for, rather than calling for it: the account value’s, where
IUL_US_S’s chain ran through five cells a month, the fixed account’s, through six,
and the collateral’s, through two. The loan, the face, the two premium accumulators, the
MEC latch, each segment’s balance and running totals, and the count call themselves at
t - 1, one cell a month. A compiled model runs these chains on the C stack.
Within each month the notes’ monthiversary order is followed exactly:
Anniversary resets and premium. The attained age and the corridor factor move on the policy anniversary (
age(),corridor_factor()); the annual premium is received at BOM of the first month of each policy year and its load deducted (premium_pp(),prem_to_av_pp()), the net premium going to the fixed account.Segment maturity. A segment created twelve months earlier matures: its index credit is computed (
index_credit_pp()) and its whole value rolls into the fixed account (seg_roll_pp()), from which the sweep at step 7 re-enters it into a new segment under the standing instruction [std].Withdrawals and new loans are sourced fixed-account-first, then pro rata across live segments (
draw_from_fa_pp(),draw_from_seg_pp()) – the order one carrier gives for loans [S3]; for withdrawals, which that carrier takes pro rata across all unloaned accounts [S3], it is [std]; loan collateral moves intolca_pp().Death benefit and corridor on the post-premium, post-withdrawal account value (
db_pp()).Net amount at risk, the death benefit discounted one month at the guaranteed rate less the account value measured before the deduction (
net_amt_at_risk()) – the universal life base convention.Monthly deduction (
mth_deduction_pp()), sourced the same way as step 3 (mth_deduction_from_fa_pp(),mth_deduction_from_seg_pp()), then the shortfall / no-lapse test (is_shortfall()).Sweep.
w_ixtimes the remaining fixed-account balance creates the new segment of this month (sweep_pp(),seg_new_pp()).Interest, EOM. One month at the fixed-account rate on the post-sweep fixed balance and at the loan collateral rate on the collateral account (
inv_income_pp()); segments earn no interim interest [S2]; loan interest accrues (loan_bal_pp()).Decrements, EOM, death before lapse (
pols_death(),pols_lapse()).
Cash flows are undiscounted. Premiums, expenses and premium taxes fall at BOM and
are weighted by pols_if(), the count in force at the start of month t;
death claims by pols_if(t) * mort_rate_mth(t); surrender payments by
pols_if(t) * (1 - mort_rate_mth(t)) * lapse_rate_mth(t); and partial withdrawals by
pols_if(t) again, because a withdrawal is taken at BOM on the owner’s election and
is not a decrement.
Counts
pols_if(t) is the count that weights row t: pols_if_at(t, BEF_DECR), the
count carried in from t - 1 (BEF_NB) plus the month’s new business,
pols_new_biz(), before the month’s decrements. A point in force at the valuation
date opens with pols_if_init(), its policy_count; one issued at or after the
valuation date opens with none, and takes its policy_count as new business in its
issue month. The recursion’s base is t_entry(), and before issue
(is_active()) every count, and so every cash flow, is zero, and so is every value
state. IUL_US_S already names three timings, in a cell that returns pols_if(t)
for each and that nothing calls. BEF_DECR keeps that meaning, and so does
BEF_MAT, the count before any maturity, since nothing matures: the name keeps its
S model’s meaning, as in the family’s other models, and basiclife.BasicTerm_SE’s
start-of-month BEF_MAT is not adopted. BEF_NB is the one timing this model
gives a new meaning, basiclife.BasicTerm_SE’s, and it differs from IUL_US_S’s
only in the issue month, where it counts the issued policies as new business, not yet
in. Inside the month the decrements are IUL_US_S’s, in its order: death, then
surrender. No policy is terminated for insufficiency, as in IUL_US_S.
The end of the projection
The frame ends at maturity_mth(), the policy month at attained age
maturity_age, 121, the notes’ [unverified] maturity inference (spec F5), and not at an
event of the contract, which is described as continuing in force with no further charges
at 121. Premiums, withdrawals and charges stop at charges_cease_age, a Reference of
its own, 121 too as shipped; set below maturity_age, the projection runs on past the
cessation, the account value earning its interest and the segments their credits with
nothing deducted. The roll-forwards read the survivors of the last month:
check_av_roll_fwd() and av_change() read the opening account value in force
of month t + 1, which in the last month is t = proj_len(). So the two opening
values they read there, the count (the BEF_NB timing of pols_if_at(), and
through it pols_if()) and the account value (av_pp_at(t, BEF_PREM)), are
defined for 0 <= duration_mth(t) <= maturity_mth(): on the books, and in the month
after the frame, where they are the survivors of the last month and the account value they
carry. Each equals IUL_US_S’s value there exactly. Every other cell is zero or
false there, as before issue: each account inside the month and its opening value, each
segment, the loan, the face, every charge, premium, withdrawal, loan draw, credit,
decrement rate, decrement, claim and flow, and the expenses, whose maintenance would
otherwise fall on the carried count; only the two clocks, the inputs read on the valuation
clock and the neutral 1.0 of the two lapse multipliers hold values there. And nothing
reads past t = proj_len(): av_change() and the residual cells of the checks,
which read t + 1 or are read beside cells that do, are zero outside cover before they
read it.
The segment ladder
A segment is created at every monthiversary from the sweep and matures twelve months
later, so between step 2 and step 7 of any month eleven segments are live and after the
sweep twelve are – the “up to 12 segments” of [S4]. A segment is born in a policy month
m, duration_mth of the month of the sweep that created it, and in month t it
sits in slot k = duration_mth(t) - m, its months since creation, 0 in its creation
month and 11 in the last month it is live: seg_bal_pp(t, k) is the balance at the end
of month t of the segment k months old then, and is zero outside
0 <= k <= min(11, duration_mth(t)). The six cells of a segment in a month,
seg_share(), seg_wd_pp(), seg_ded_pp(), seg_bal_pp(),
seg_ded_cum_pp() and seg_wd_cum_pp(), are keyed so, by (t, k), and each
reads its own value of the month before at (t - 1, k - 1), the same segment a month
younger: IUL_US_S keys them by (t, m), which a compiled cache would hold across
every creation month of the frame, where twelve slots hold the live ones. A segment’s
creation balance, seg_new_pp(), is keyed by its creation month m, a policy month,
as in IUL_US_S: one value a segment. A parameter that holds a policy month is named
m, never t, so that what moves with the valuation clock is t alone.
A point in force at the valuation date carries its live segments in a companion of the
model point table, inforce_segments_sec.csv, one row a segment, keyed by point_id
and slot: the months since the segment’s creation at the valuation date, 1 to 12, so
that the segment in slot k is the one born in policy month duration_mth_init() - k
and the segment in slot 12 matures at t = 0. The ladder’s slot is the slot of month
0, so a segment carried in opens at t = 0 from its own row: seg_bal_pp(0, k)
from seg_bal_pp_init(k). Every month of the last
min(12, duration_mth_init()) holds a row, a month that swept nothing included, at
zero, since the credited rate of a month reads the start level and the cap of the segment
maturing then whether or not it holds a balance (cred_rate_ann()). Each row gives
the segment’s balance entering month 0 (seg_bal_pp_init()), the deductions and the
draws – withdrawals and loan transfers – charged to it since its creation
(seg_ded_cum_pp_init(), seg_wd_cum_pp_init()), which with the balance are its
credit base, the index level at its creation on the valuation-clock path
(seg_index_start_init()) and the cap declared then (seg_index_cap_init()). Its
creation balance takes no column: nothing may enter or leave a segment but a deduction, a
withdrawal or a loan transfer, so it is the three summed, which is the closure
check_seg_ladder() asserts (seg_new_pp()).
Two properties of this arrangement are worth stating because the notes list both as pitfalls.
Each segment carries its own index start level, so twelve segments a year mature at
twelve different point-to-point returns. Collapsing them into one annual segment
mis-times credits and distorts mid-segment surrender values [S3]; check_seg_ladder()
and model point 3 (indexed allocation 0%) exist so the difference is visible rather than
assumed.
Deductions and withdrawals are sourced from the fixed account first and then pro rata
across live segments on their remaining balances [std]. Because a pro-rata draw
leaves the proportions unchanged, one set of shares (seg_share()) serves both the
step-3 draw and the step-6 deduction. The two claims on the pool are ordered, not
parallel: the step-6 deduction is capped against what the step-3 draw leaves behind,
so their sum can never exceed the pool, no segment balance can go negative, and no
segment can pay a negative index credit at maturity. Capping both against the same
pre-draw pool is the easy mistake, and check_seg_ladder() asserts against it.
The credit base under the baseline convention is exactly the remaining balance –
amounts that left the segment mid-term earn no index credit [S3]. The alternative
convention the notes price, one carrier’s adjusted-beginning-value with half-weighted
deductions [S3], is the ADJ_BEGIN argument of seg_credit_base().
A segment can close a month on a rounding about zero, a balance of the order of 1e-16 of
either sign, where a draw or a deduction took exactly what it held. seg_share() and
seg_count() read such a balance by IUL_US_S’s own tests of zero, and the pool
seg_bal_active_pp() and the total seg_bal_tot_pp() sum the segments in an
explicit loop that compensates as Python’s sum() of floats does from Python 3.12, so
that each is IUL_US_S’s sum bit for bit there. Python 3.11’s sum() is a plain
fold, which can leave such a pool on the other side of zero, so the states IUL_US_S
closes on a rounding about zero depend on the interpreter it runs on.
Naming
Cell names follow UL_US_S – the chassis these notes defer to – and
through it lifelib’s basiclife.BasicTerm_S and savings.CashValue_SE: pols_*
for policy counts, av_* for account values, plural nouns for cash flows, *_rate
for rates, *_pp for per-policy amounts, timing and kind arguments.
Every concept shared with the chassis carries the chassis name. The names that are new
in IUL_US_S are the ones the indexed crediting engine needs: the fixed (holding)
account, the segment ladder, the crediting formula, and the no-lapse guarantee test.
What running in force adds is named as basiclife.BasicTerm_SE names it:
duration_mth read from the model point, policy_count, pols_new_biz,
pols_if_at with its BEF_NB timing, is_active and result_pols.
t_entry, the first month on the books, is the SEC models’ own, and maturity_mth is
named for maturity_age, where the projection ends. A column of the opening state is
the cell it opens with _init added: av_pp_init and loan_bal_init are
IUL_US_S’s own, and fa_pp_init, lca_pp_init, sum_assured_init,
cum_prem_init, cum_prem_net_init and is_mec_init open fa_pp_at(),
lca_pp_at(), sum_assured_at(), cum_prem_pp(), cum_prem_net_pp()
and is_mec() as they open theirs. A column of the segment ladder is the segment
cell it opens with _init added, keyed by the slot: seg_bal_pp_init(k),
seg_ded_cum_pp_init(k) and seg_wd_cum_pp_init(k); the start level and the cap,
which no cell of IUL_US_S holds per segment, are seg_index_start_init(k) and
seg_index_cap_init(k), and the monthly cells that read them, for the segment maturing
in month t, seg_index_start() and seg_index_cap(). A table read at an
attained age has one reader keyed by the age, <cell>_at(a), and a table read at a
policy year one keyed by the year, <cell>_py(y); the monthly cell keeps
IUL_US_S’s name and calls its reader inside cover. The surrender-charge schedule,
keyed by its ID, has one reader for each of its two columns, surr_charge_rate_max()
and surr_charge_runoff_years(). A check’s residual in month t is
<check>_resid(t). Each text column a monthly cell branches on is read through bool
decodes, one for each value, named for the value: is_db_option_a(),
is_db_option_b(), is_gpt(), is_level_premium(),
is_single_premium(), is_target_premium(), is_annual_premium() and
is_monthly_premium(). Each reads the vector Data decoded from its column, and
so does each per-point join, so no projection cell compares text or calls a label
accessor: IUL_US_S’s label accessors, sex, rate_class, db_option,
qual_test, premium_type, premium_mode and surr_charge_id, are kept as they
are, for reporting (Reporting cells, below). A segment’s cell in a month is keyed by
its slot, k, and a monthly cell of the segment maturing in month t is named for
the segment, seg_*(t): seg_return(), seg_credit_rate(),
seg_index_start() and seg_index_cap().
Notes symbol |
Cells |
Meaning |
|---|---|---|
t |
(the |
Months from the valuation date, 0-based |
(months at valuation) |
duration_mth_init |
Completed policy months at the valuation date; -k if issued k months later |
(notes’ t, from issue) |
duration_mth(t) |
Completed policy months at month t |
y |
policy_year(t) |
Policy year, 1-based,
|
(y - 1) |
duration(t) |
Completed policy years at BOM |
(model point) |
point_id() |
The point’s label |
(issue age) |
age_at_entry |
Issue age (ANB) |
Sex |
sex |
Sex, M or F |
Risk class |
rate_class |
Underwriting class, spec Table 1 |
DB option |
db_option |
Death benefit option, A or B |
(Option A) |
is_db_option_a |
Whether db_option is A |
(Option B) |
is_db_option_b |
Whether db_option is B |
Tax test |
qual_test |
IRC 7702 test; only GPT modeled |
(GPT elected) |
is_gpt |
Whether qual_test is GPT |
Premium mode |
premium_mode |
ANNUAL [std] or MONTHLY |
(annual mode) |
is_annual_premium |
Whether premium_mode is ANNUAL |
(monthly mode) |
is_monthly_premium |
Whether it is MONTHLY |
x |
age(t) |
Attained age (ANB) |
(none) |
proj_len |
Months from the valuation date to the end of the projection |
(projection end) |
maturity_mth |
Policy month the projection ends at, attained age 121 |
(none) |
t_entry |
First month on the books |
(none) |
is_active(t) |
Whether month t is in cover |
(none) |
policy_count |
Policies the model point stands for |
F |
sum_assured |
Initial face amount |
F_0 |
sum_assured_init |
Face in force entering month 0 |
F_{t+1} |
sum_assured_at(t) |
Face after reductions, end of month t |
F/1000 |
units(t) |
Face in $1,000 units |
P_t |
premium_pp(t) |
Gross premium per policy |
(planned) |
premium_pp_ann |
Planned annual premium |
(premium pattern) |
premium_type |
LEVEL, SINGLE or TARGET |
(LEVEL pattern) |
is_level_premium |
Whether premium_type is LEVEL |
(SINGLE pattern) |
is_single_premium |
Whether it is SINGLE |
(TARGET pattern) |
is_target_premium |
Whether it is TARGET |
(persistency) |
prem_persistency(t) |
Paid/planned factor 0.98^(y-1) |
l_prem |
load_prem_rate() |
Premium load rate |
NP_t |
prem_to_av_pp(t) |
Net premium to the accounts |
W_t |
wd_pp(t) |
Partial withdrawal, gross of fee |
(planned W) |
wd_pp_mth |
The wd_pp column, a month’s W |
(the $25 fee) |
wd_fee_pp(t) |
Withdrawal fee |
B_t |
loan_new_pp(t) |
New standard loan |
(planned B) |
loan_new_pp_ann |
The loan_new_pp_ann column |
W_t + B_t |
draw_pp(t) |
The whole step-3 draw |
W^FA_t + B^FA_t |
draw_from_fa_pp(t) |
Step-3 draw sourced from FA |
W^seg_{k,t} + B^seg_{k,t} |
draw_from_seg_pp(t) |
Step-3 draw sourced from segments |
(segment k’s share) |
seg_wd_pp(t, k) |
Segment k’s part of that draw |
(cumulative) |
seg_wd_cum_pp(t, k) |
Draws out of segment k to date |
FA_{t+1} |
fa_pp(t) |
Fixed (holding) account, end of month t |
FA_t |
fa_pp_at(t, BEF_PREM) |
Fixed account, start of month t |
(FA intra-month) |
fa_pp_at(t, timing) |
Fixed account by timing |
FA_0 |
fa_pp_init |
Fixed account entering month 0 |
S_{k,t+1} |
seg_bal_pp(t, k) |
Segment in slot k, end of month t |
Sweep_t |
sweep_pp(t) |
Sweep into a new segment |
S_{k,m_k} |
seg_new_pp(m) |
Segment balance at creation |
(sum of segments) |
seg_bal_tot_pp(t) |
All live segment balances |
(active pool) |
seg_bal_active_pp(t) |
Segments available to a draw |
(pro-rata share) |
seg_share(t, k) |
Segment k’s share of that pool |
(segment count) |
seg_count(t) |
Live segments, at most 12 |
k |
(the |
Slot, a segment’s months since
creation: in month t, or at
the valuation date in the
ladder’s |
S_{k,0} |
seg_bal_pp_init(k) |
Slot k’s balance entering month 0 |
(deductions to date) |
seg_ded_cum_pp_init(k) |
Deductions charged to slot k |
(draws to date) |
seg_wd_cum_pp_init(k) |
Draws out of slot k |
I(m_k) |
seg_index_start_init(k) |
Slot k’s level at creation |
c_k |
seg_index_cap_init(k) |
Cap declared at slot k’s creation |
(start level at t) |
seg_index_start(t) |
Level at creation of the segment maturing at t |
(cap at t) |
seg_index_cap(t) |
Cap of the segment maturing at t |
w_ix |
index_alloc_rate() |
Indexed allocation share |
I(t) |
index_level(t) |
Index level at monthiversary t |
r_k |
index_change(i_0, i_1) |
Point-to-point index change |
(index path) |
index_return_ann |
Level annual index return [std] |
c |
index_cap_at(t) |
Cap in force |
p |
index_par |
Participation rate |
f |
index_floor |
Floor |
cr_k |
index_credit_rate(r) |
max(f, min(c, p x r)), engine |
(the segment’s cr_k) |
seg_credit_rate(t) |
The same, of the segment maturing at t |
(credit base) |
seg_credit_base(…) |
Balance the credit applies to |
Credit_k |
index_credit(…) |
Index credit, engine form |
(matured value) |
seg_matured_value(…) |
Value rolling into the next segment |
(the segment’s r) |
seg_return(t) |
Index change of the segment maturing at t |
(credit at t) |
index_credit_pp(t) |
Credit added at BOM of month t |
Roll^FA_t |
seg_roll_pp(t) |
Matured value rolled into FA |
LCA_{t+1} |
lca_pp(t) |
Loan collateral account, end of month t |
LCA_0 |
lca_pp_init |
Collateral entering month 0 |
Existing loan balance |
loan_bal_init |
L(0), the loan entering month 0 |
L_{t+1} |
loan_bal_pp(t) |
Loan plus interest, end of month t |
i_L^c |
loan_rate_ann |
Loan charged rate |
i_L^e |
loan_credit_rate_ann(t) |
Collateral credited rate |
AV_{t+1} |
av_pp(t) |
Account value, end of month t |
AV_t |
av_pp_at(t, BEF_PREM) |
Account value, start of month t |
AV_0 |
av_pp_init |
Account value entering month 0 |
(after premium) |
av_pp_at(t, BEF_CREDIT) |
Before the maturity credit |
(after credit) |
av_pp_at(t, BEF_WD) |
Before the withdrawal |
AV’_t |
av_pp_at(t, BEF_FEE) |
After premium and withdrawal |
AV’_t - MD_t |
av_pp_at(t, BEF_INV) |
After the monthly deduction |
(aggregate AV) |
av_at(t, timing) |
Account value in force |
(change in AV) |
av_change(t) |
Change in account value |
i_fix |
fixed_rate_ann(t) |
Fixed-account annual rate |
i_g |
guar_rate_ann |
Guaranteed annual rate |
(i_fix monthly) |
inv_return_mth(t) |
Monthly fixed-account rate |
(i_g monthly) |
guar_rate_mth() |
Monthly guaranteed rate |
v_g |
naar_factor() |
1 + i_gm; DB is divided by it |
(interest credited) |
inv_income_pp(t) |
Interest on FA and LCA |
e_pol |
expense_pol_mth_at(t) |
Monthly policy fee |
e_unit |
expense_unit_mth_at(t) |
Per-unit charge per $1,000 |
(rider charges) |
rider_charge_pp(t) |
Rider charges (0) |
(e_pol + e_unit + rc) |
maint_fee_pp(t) |
Non-COI monthly charges |
coi_t |
coi_rate(t) |
Current monthly COI rate |
(guaranteed COI) |
coi_rate_guar(t) |
Guaranteed maximum COI rate |
(guaranteed COI scale) |
coi_schedule() |
The scale’s number in Data |
(scale’s last year) |
coi_rate_last_year() |
The scale’s last policy year |
(COI by policy year) |
coi_rate_guar_py(y) |
The scale’s rate in year y |
COI_t |
coi_pp(t) |
Cost of insurance charge |
NAAR_t |
net_amt_at_risk(t) |
Net amount at risk |
MD_t |
mth_deduction_pp(t) |
Monthly deduction |
MD^FA_t |
mth_deduction_from_fa_pp(t) |
Deduction sourced from FA |
MD^seg_{k,t} |
mth_deduction_from_seg_pp(t) |
Deduction sourced from segments |
(segment k’s deduction) |
seg_ded_pp(t, k) |
Segment k’s part of the deduction |
(cumulative deductions) |
seg_ded_cum_pp(t, k) |
Deductions charged to segment k |
DB_t |
db_pp(t) |
Death benefit after corridor |
kappa_x |
corridor_factor(t) |
IRC 7702(d) corridor factor |
(kappa by age) |
corridor_factor_at(a) |
The same, keyed by age |
SC_t |
surr_charge_pp(t) |
Surrender charge scheduled |
(SC per $1,000) |
surr_charge_rate(t) |
Surrender charge rate |
(initial SC per $1,000) |
surr_charge_rate_max() |
The schedule’s charge before any run-off |
(run-off period) |
surr_charge_runoff_years() |
The schedule’s run-off, years |
(AV - SC) |
csv_pp(t) |
Cash value before loan |
CSV_t |
ncsv_pp(t) |
Cash surrender value, loan netted |
(SC retained) |
surr_charge(t) |
Surrender charge collected |
CumP_{t+1} |
cum_prem_net_pp(t) |
Premiums less withdrawals and loans, end of month t |
CumP_0 |
cum_prem_net_init |
The same, entering month 0 |
(GPT/7-pay base) |
cum_prem_pp(t) |
Premiums less withdrawals, end of month t |
(GPT/7-pay base at entry) |
cum_prem_init |
The same, entering month 0 |
CumMNLP_{t+1} |
cum_mnlp_pp(t) |
Cumulative no-lapse premium through month t |
(MNLP rate) |
mnlp_rate() |
No-lapse premium per $1,000 p.a. |
(MNLP monthly) |
mnlp_pp_mth() |
Monthly no-lapse premium |
(no-lapse period) |
nlg_period_years() |
Length of the no-lapse period |
(no-lapse test) |
nlg_test_ok(t) |
CumP >= CumMNLP |
(NLG status) |
nlg_in_effect(t) |
In period and test passing |
(NLG expiry shock) |
nlg_expiry_shock(t) |
25% shock at expiry [std] |
(grace trigger) |
is_shortfall(t) |
CSV cannot cover MD, NLG failed |
(GPT limit) |
gpt_limit(t) |
max(GSP, GLP x years) |
(GPT test) |
gpt_ok(t) |
GPT compliance flag |
(7-pay limit) |
seven_pay_limit(t) |
7-pay cumulative limit |
(MEC flag) |
is_mec(t) |
7-pay failure, latched |
(MEC at entry) |
is_mec_init |
The latch entering month 0 |
q^d_t |
mort_rate_mth(t) |
Monthly mortality rate |
(annual q) |
mort_rate(t) |
Annual mortality rate, capped |
(base q by age) |
mort_rate_base_at(a) |
The base table’s rate |
(class factor) |
class_factor() |
Underwriting-class multiplier |
(base lapse) |
lapse_rate_base(t) |
Base annual lapse rate |
(base lapse by year) |
lapse_rate_base_py(y) |
The same, keyed by policy year |
(SC-expiry year) |
lapse_shock_year() |
Policy year of the spike |
(SC-expiry spike) |
lapse_rate_sc_mult(t) |
Year-11 shock multiplier |
r_cred,t |
cred_rate_ann(t) |
Trailing credited rate |
r_alt |
comp_rate_ann(t) |
Competitor / market rate |
(dynamic multiplier) |
lapse_rate_dyn_mult(t) |
Dynamic lapse multiplier |
q^w_t |
lapse_rate_mth(t) |
Monthly lapse rate |
(annual w) |
lapse_rate(t) |
Total annual lapse rate |
l_t |
pols_if(t) |
In force at BOM of month t |
(l at valuation) |
pols_if_init |
In force at the valuation date |
(carried in) |
pols_if_at(t, BEF_NB) |
Carried in from month t - 1 |
(after new business) |
pols_if_at(t, BEF_DECR) |
After new business: l_t |
(before maturity) |
pols_if_at(t, BEF_MAT) |
Before maturity: l_t |
(new business) |
pols_new_biz(t) |
Policies issued in month t |
(deaths) |
pols_death(t) |
Deaths in month t |
(lapses) |
pols_lapse(t) |
Lapses in month t |
(maturities) |
pols_maturity(t) |
Maturities: always zero |
(premium income) |
premiums(t) |
Premium income |
DB_t - L_t |
claims_death(t) |
Death claims |
CSV_t |
claims_lapse(t) |
Surrender payments |
(claims) |
claims(t) |
Death and surrender claims |
W_t - fee |
withdrawals(t) |
Withdrawal payments |
(inflation) |
inflation_factor(t) |
Expense inflation factor |
E_t |
expenses(t) |
Insurer’s own expenses |
(premium tax) |
premium_taxes(t) |
Premium tax |
(net loan cash flows) |
net_loan_cf(t) |
Loan advances and repayments |
CF_t |
net_cf(t) |
Net liability cash flow |
(AV components residual) |
check_av_components_resid(t) |
AV less its three parts |
(AV roll residual) |
check_av_roll_fwd_resid(t) |
AV roll-forward residual |
(margin residual) |
check_margin_resid(t) |
Margin identity residual |
(segments over the term) |
check_seg_count_resid(t) |
Live segments beyond 12 |
(the month’s credit) |
check_seg_credit_resid(t) |
The credit, 0 or more |
(least segment) |
check_seg_bal_resid(t) |
The least live balance |
(segment closure) |
check_seg_closure_resid(t) |
The maturing segment’s closure |
(none) |
result_pols() |
Counts and decrement rates |
Ten names needed care.
A withdrawal is not a claim. The notes write the withdrawal outflow as its own term
of CF_t, alongside the death and surrender legs, and the library follows that: the
payment is withdrawals(), published in a withdrawals column, and
WITHDRAWAL is not a kind claims() totals – it would otherwise sit in the
total and be double-counted against the standalone cells.
The per-policy amount is still claim_pp(t, WITHDRAWAL), because that is
where the W_t - $25 fee rule lives and withdrawals() weights it by
pols_if(): a withdrawal is taken at BOM by policies still in force, not by a
decrement. Surrenders keep the LAPSE kind and are published as claims_lapse,
so the column name matches the kind that produces it.
The notes’ month counts from issue; this model’s counts from the valuation date. The
notes’ t and this model’s are both 0-based and they coincide for a point issued at the
valuation date; for any other the notes’ index is duration_mth()
(t) = duration_mth_init() + t.
Every mod 12 test – the anniversary premium, the anniversary loan – is therefore
written against duration_mth(t) rather than t, a segment’s creation is a policy
month, and the surrender charge run-off uses duration_mth(t) + 1 because the notes’
schedule counts the current month.
A segment’s slot is not its creation month. IUL_US_S keys seg_bal_pp(t, m)
and the segment cells beside it by m, the policy month the segment was born in; this
model keys them by the slot, k = duration_mth(t) - m, the months since that birth in
month t, which moves with t, so that seg_bal_pp(t, k) reads
seg_bal_pp(t - 1, k - 1), and seg_new_pp() alone keeps the creation month. The
ladder’s slot is the slot of month 0, duration_mth_init() - m, which is what an
extract of a policy’s live segments knows, and what one row of
inforce_segments_sec.csv is keyed by.
The notes’ cash surrender value is the net one. Their CSV_t is ncsv_pp(),
not csv_pp(): the notes define CSV_t = AV_t - SC_t - L_t, with the loan already
netted. The chassis and
CashValue_SE split that into csv_pp() (AV - SC) and ncsv_pp()
(CSV - L). The chassis names are kept, and the notes’ symbol maps to the second.
The withdrawal fee is inside the withdrawal, not on top of it. These notes say
W_t is “gross of $25 fee” and that the “withdrawal outflow = W_t - $25 fee”. The
account is therefore debited W_t, the policyholder receives W_t - 25 and the
insurer keeps the fee. The universal life chassis reads its own notes the other way –
there the fee is charged on top of the withdrawal – so av_pp_at() deliberately
differs from the chassis at BEF_FEE. A planned withdrawal above 0 and below the fee
would debit the account less than the fee it is charged, which proj_len() refuses.
The death claim nets the loan at the end of the month. These notes write
death claim outflow = DB_t - L_t; decrements are end-of-month events, after the
loan has accrued, so claim_pp() uses loan_bal_pp() at t. The chassis
uses the opening balance because its own notes write L(t-1).
The maintenance fee is income, the expenses outgo. As on the chassis,
maint_fee_pp() is the non-COI part of the monthly deduction – a charge against
the account value – while expenses() is the insurer’s own $75 a year plus $150
at issue [std]. Confusing them double-counts.
The two cumulative premium accumulators are different. cum_prem_net_pp() is
the notes’ CumP_t, premiums less withdrawals and loans, which is what the
no-lapse test compares against CumMNLP_t. cum_prem_pp() is premiums less
withdrawals only, which is the base of the guideline premium and 7-pay tests. Using one
for the other quietly changes both answers, and so does opening either at 0 on a point in
force: each opens from a column of its own, cum_prem_init() and
cum_prem_net_init().
The MEC flag latches here, and does not in the S model. IUL_US_S’s flag is the
in-year 7-pay test alone, which stops applying in policy year 8 and so switches the flag
off exactly when the failure becomes permanent. This model latches it, as UL_US_S
does, from is_mec_init() on a point in force: under IRC 7702A a contract that fails
the test is a modified endowment contract for good [R5].
The fixed account and the collateral are not the account value less the loan.
IUL_US_S opens an in-force point with everything in the fixed account and the
collateral equal to the loan. Both part from those after the first loan: the collateral
is credited at loan_credit_rate_ann() while the loan accrues at loan_rate_ann,
and the segments hold the rest of the account value. So each opens from its own column,
fa_pp_init() and lca_pp_init(), and the segments from the ladder; Data
holds the account value to the sum of the three parts.
Codes
What IUL_US_S spells as text, a timing, a kind, the basis or the credit base’s
convention, is here an int Reference named as the text it replaces, so that every cell
takes and returns C numbers. A call site reads as it did, less the quotes:
pols_if_at(t, BEF_DECR), av_pp_at(t, BEF_FEE), claim_pp(t, DEATH),
basis = GUARANTEED.
Reference |
Value |
Meaning |
|---|---|---|
BEF_NB |
0 |
|
BEF_DECR |
1 |
|
BEF_MAT |
2 |
|
BEF_PREM |
3 |
the accounts: the value carried in, before the premium |
BEF_CREDIT |
4 |
|
BEF_WD |
5 |
|
BEF_FEE |
6 |
|
BEF_SWEEP |
7 |
|
BEF_INV |
8 |
the accounts: after the deduction and the sweep, before interest |
EOM |
9 |
|
DEATH |
0 |
|
LAPSE |
1 |
|
MATURITY |
2 |
|
WITHDRAWAL |
3 |
|
CURRENT |
0 |
|
GUARANTEED |
1 |
|
REMAINING |
0 |
|
ADJ_BEGIN |
1 |
|
The accounts are fa_pp_at(), which takes the six timings from BEF_PREM to
BEF_INV; av_pp_at(), which takes those but BEF_SWEEP, since a sweep moves
value between the account value’s parts and changes no total; lca_pp_at(), which
moves only at the loan, BEF_PREM and BEF_INV; and av_at(), the account value
in force, which takes av_pp_at()’s five and EOM.
The model has two families of timing, the count’s and the accounts’, passed to different
cells, and they are numbered as one: BEF_NB 0 and BEF_DECR 1, as in every SEC
model, then the count’s third, BEF_MAT, then the accounts’ in the order of their
instants within the month, EOM last, as UL_US_SEC numbers its own with the two
instants an indexed account adds, BEF_CREDIT and BEF_SWEEP, in their places. So no
two timings share a code, and a code of one family passed to the other’s cell,
av_pp_at(t, BEF_NB), is refused as any timing the cell does not take is,
ValueError("invalid timing"), in both engines, rather than read as a timing of the
cell’s own. Kinds are numbered in the order the month settles them, as VUL_US_SEC
numbers its own. basis and seg_credit_base_conv, the two text References
IUL_US_S switches on, are code families of their own, each holding one of its codes,
CURRENT and REMAINING as shipped: a run on the guaranteed basis sets
basis = GUARANTEED before anything computes, and in modelx a string set on either
meets its cell’s own refusal, "invalid basis" or "invalid credit base". A cell
compares its code with == alone, never by order or by membership of a tuple, so that
a text passed where a code is taken meets the cell’s own refusal in modelx too. A timing
or a kind indexes its cell’s cache, a C array of twelve codes a month, since every 2-D
cache of the model has one width, the twelve slots of a segment’s life
(spec_sec.py), so codes are numbered densely from 0. 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 issue_age_max among them, the contract’s issue ages, which
proj_len() refuses a point outside of, and the first of which the compiled model’s
caches are sized from.
Reporting cells
model_point(), the label accessors sex(), rate_class(),
db_option(), qual_test(), premium_type(), premium_mode() and
surr_charge_id(), the reports result_cf(), result_pols(),
result_av() and result_seg(), and the checks check_av_components(),
check_av_roll_fwd(), check_seg_ladder() and check_margin() are written
for a reader and for the comparison with IUL_US_S, which has every one of them: a
table row, text, DataFrames and four verdicts. No other cell calls them: each reads the
number Data decoded from the same column instead, the decodes’ flags, the schedule
numbers and the joins the keys select. So the row, the text and the frames stay Python
when the model compiles. A label accessor returns its column as read, text or not: a
blank surr_charge_id on a point without a charge reads as NaN, and the compiled
accessor returns the same. Every other cell returns a C bint, long long or
double, and so do the four checks, which may stay Python but compile to a bint,
their verdict, as their per-month residuals, *_resid, compile to a double.
The crediting engine of IUL_US_S, index_change(), index_credit_rate(),
seg_credit_base(), index_credit() and seg_matured_value(), cells of
float arguments, is kept as it is, for its worked example, which prices one segment’s
credit at the current and the guaranteed cap through it, and for the comparison with
IUL_US_S, whose projection calls it. No projection cell here calls it: the credit
of the segment maturing in month t is seg_return(), seg_credit_rate() and
index_credit_pp(), cells keyed by the month, which compute what the engine computes
in its order. Compiled, the five keep a Python dict for a cache and Python objects for
their defaulted parameters, as the registry admits them (R14).
Cells Descriptions#
- model_point()[source]#
The selected model point, its row of model_point_table_sec.csv, as a Series.
Row
idxof the table, for a reader who wants every column at once: a reporting cell (the Space docstring’s Reporting cells), which no projection cell reads. Each reads its ownDatavector instead.
- point_id()[source]#
The label of the selected model point, its
point_id, fromData.point_id.Projectionis indexed by position,idx, asbasiclife.BasicTerm_SCis; the label is what a reader finds in the table, so every refusal names it.
- age_at_entry()[source]#
The issue age (ANB) of the selected model point, from
Data.age_at_entry.The age at issue, whatever the policy’s duration at the valuation date; the attained age in month t is
age().Dataholds it to a whole number, 0 or more, andproj_len()to the ages the contract issues, 0 to 85.
- sex()[source]#
The sex of the selected model point.
A reporting cell (the Space docstring):
Datajoins the COI scale by it, throughData.coi_schedule, and no projection cell reads it here. Returned as read.
- rate_class()[source]#
The underwriting class of the selected model point (spec Table 1) [S3].
A reporting cell (the Space docstring):
Datajoins the COI scale and the class factor by it, throughData.coi_scheduleandData.class_factor, and no projection cell reads it here. Returned as read.
- sum_assured()[source]#
F: the initial face amount of the selected model point, the face at issue.
The surrender charge is quoted per $1,000 of this, the initial face, not of
sum_assured_at()[S3], and it is the face a point not yet in force is issued with. The face in force at the valuation date issum_assured_init(), and the face in force in month t issum_assured_at().
- db_option()[source]#
The death benefit option:
"A"(level) or"B"(face plus account value).The Graded and Return of Premium options are minority designs excluded from the baseline by the product spec (F3). A reporting cell (the Space docstring): the projection reads
is_db_option_a()andis_db_option_b(),Data’s decodes of the column. Returned as read.
- is_db_option_a()[source]#
Whether the death benefit is Option A, the level face.
Data.is_db_option_aat the point:db_optionis"A", the decode of the model point’s columnDatamakes once for the table, compared exactly, asIUL_US_Scompares it, so that no monthly cell branches on text;db_pp()andface_reduction_pp()read this instead. The label accessordb_option()is kept as it is, for reporting, and no projection cell calls it.
- is_db_option_b()[source]#
Whether the death benefit is Option B, the face plus the account value.
Data.is_db_option_bat the point:db_optionis"B", read bydb_pp(), which raises on a point that is neither A nor B, asIUL_US_S’s does.
- qual_test()[source]#
The IRC 7702 qualification test elected at issue; only
"GPT"is modeled.GPT is the baseline (spec F4) because the Overloan Protection Rider attaches only to GPT non-MEC policies [S3]; CVAT is documented as a variation, so
corridor_factor()raises on anything else rather than silently applying GPT corridor factors. A reporting cell (the Space docstring): the projection readsis_gpt(),Data’s decode of the column. Returned as read.
- is_gpt()[source]#
Whether the point elected the Guideline Premium Test:
qual_testis"GPT".Data.is_gptat the point, the decode of the model point’squal_testcolumn, read bycorridor_factor(), which raises on any other test, asIUL_US_S’s does: CVAT is documented as a variation, out of the baseline.
The premium pattern:
"LEVEL","SINGLE"or"TARGET"[std].A reporting cell (the Space docstring): the projection reads
is_level_premium(),is_single_premium()andis_target_premium(),Data’s decodes of the column. Returned as read.
Whether the premium pattern is LEVEL:
premium_typeis"LEVEL".Data.is_level_premiumat the point: one of the three decodes of the model point’spremium_typecolumn thatpremium_pp()branches on, each made once for the table byData, so that no monthly cell compares text;premium_pp()raises on a point that is none of the three, asIUL_US_S’s does. The label accessorpremium_type()is kept as it is, for reporting, and no projection cell calls it.
Whether the premium pattern is SINGLE:
premium_typeis"SINGLE".Data.is_single_premiumat the point, a decode of the model point’spremium_typecolumn, read bypremium_pp().
Whether the premium pattern is TARGET:
premium_typeis"TARGET".Data.is_target_premiumat the point, a decode of the model point’spremium_typecolumn, read bypremium_pp(), whose TARGET premium is capped inside the guideline premium limit.
The premium mode:
"ANNUAL"[std] baseline, or"MONTHLY".The notes fix the baseline at annual premiums paid at BOM of the first month of each policy year (
duration_mth(t) % 12 == 0) [std]; monthly mode is carried so the chassis’ level-pay pattern remains reachable. A reporting cell (the Space docstring): the projection readsis_annual_premium()andis_monthly_premium(),Data’s decodes of the column. Returned as read.
Whether premiums are paid annually:
premium_modeis"ANNUAL".Data.is_annual_premiumat the point: one of the two decodes of the model point’spremium_modecolumn thatpremium_pp()branches on, made once for the table byData, so that no monthly cell compares text;premium_pp()raises on a point that is neither, asIUL_US_S’s does. The label accessorpremium_mode()is kept as it is, for reporting, and no projection cell calls it.
Whether premiums are paid monthly:
premium_modeis"MONTHLY".Data.is_monthly_premiumat the point, a decode of the model point’spremium_modecolumn, read bypremium_pp().
The planned annual premium per policy; a billing target only, premiums flexible.
- index_alloc_rate()[source]#
w_ix: the share of the sweepable fixed-account balance moved to the indexed account.
100% in the baseline [std]. A model point at 0% never creates a segment and accumulates entirely at the fixed-account rate, which is the control run for the segment ladder.
- av_pp_init()[source]#
AV(0): the account value per policy entering month 0, the valuation month.
The
av_pp_initcolumn,IUL_US_S’s own: the balance at the close of policy monthduration_mth_init() - 1, before any month-0 event, which is whatIUL_US_Scarries into the month asav_pp_at(d, BEF_PREM)atd = duration_mth_init(). It opens the account value chain att_entry()on a point issued at or after the valuation date, 0 there. A point in force opens the chain from its parts instead, whichDataholds this column to, so that an extract whose amounts are carried to the cent opens one account (seeav_pp_at()). Zero for a point not yet in force, which is issued with no account value.The account value is the fixed account, the live segments and the loan collateral, and each of the three opens from a value of its own –
fa_pp_init(), the segment ladder andlca_pp_init()– whereIUL_US_Splaces the whole opening balance less the loan in the fixed account and starts with no live segment.Dataholds this column to their sum, to the cent. It may be negative:IUL_US_Slapses no policy for insufficiency, and charges an exhausted policy on, so its point 5’s account value closes below zero from policy month 604, and a point restated after that month carries that balance (see the model docstring).
- loan_bal_init()[source]#
L(0): the policy loan balance per policy entering month 0.
The
loan_bal_initcolumn,IUL_US_S’s own: the debt at the close of policy monthduration_mth_init() - 1, interest accrued to then included, before any month-0 event; the opening balance ofloan_bal_pp()att_entry(), and the loan month 0’s shortfall test nets. Zero for a point not yet in force.IUL_US_Salso opens its loan collateral account from it, taking the collateral equal to the debt; here the collateral opens from a column of its own,lca_pp_init(), since the two part once interest accrues.
- fa_pp_init()[source]#
FA(0): the fixed (holding) account per policy entering month 0.
The
fa_pp_initcolumn: the fixed account at the close of policy monthduration_mth_init() - 1, before any month-0 event, which is whatIUL_US_Scarries into the month asfa_pp_at(d, BEF_PREM). It is the opening balance offa_pp_at()att_entry().IUL_US_Sopens its in-force points with the account value less the loan here, everything outside the collateral in the fixed account and no live segment, which re-opening a policy restates wrongly: the segments hold most of an account value whose allocation is indexed, and the collateral is not the loan once interest accrues.It may be negative.
IUL_US_Slapses no policy for insufficiency, and its fixed account carries every deduction and draw the segments cannot cover, so an exhausted policy’s fixed account runs below zero: its point 5’s closes below zero from policy month 383.Dataholds it, with the collateral and the segments, toav_pp_init(). Zero for a point not yet in force.
- lca_pp_init()[source]#
LCA(0): the loan collateral account per policy entering month 0.
The
lca_pp_initcolumn: the collateral at the close of policy monthduration_mth_init() - 1, before any month-0 event, which is whatIUL_US_Scarries into the month aslca_pp_at(d, BEF_PREM). It is the opening balance oflca_pp_at()att_entry(), and part of the account value, as the debt is not. A standard loan moves value out of the fixed account and the segments into the collateral, so the two coincide on the loan’s first day, andIUL_US_Stakes them equal at the start of its frame [std]; after that the collateral grows at the rate credited,loan_credit_rate_mth(), and the debt at the rate charged,loan_rate_mth(), so they part.Datarefuses a collateral without a loan, or a loan without one. Zero for a point not yet in force.
- sum_assured_init()[source]#
F(0): the face amount in force per policy entering month 0.
The
sum_assured_initcolumn: the face in force at the close of policy monthduration_mth_init() - 1, after every Option A withdrawal cut to date, which is the faceIUL_US_Scarries into the month assum_assured_at(d - 1). It is the base ofsum_assured_at()att_entry(), so month 0’s own withdrawal cut, death benefit, net amount at risk and per-unit charge are measured from it. The face at issue,sum_assured(), stays the surrender charge’s base, andDatarefuses a value above it, since face increases are not modelled. It may be 0: withdrawals under Option A can cut the face to nothing while the policy stays in force, asIUL_US_Scarries it. Zero for a point not yet in force, which is issued atsum_assured().IUL_US_Sopens its in-force points at the face at issue.
- cum_prem_init()[source]#
CumPrem(0): the premiums less withdrawals per policy before the valuation date.
The
cum_prem_initcolumn: every gross premiumpremium_pp()collected from issue through policy monthduration_mth_init() - 1, less every withdrawalwd_pp()paid, which is whatIUL_US_Scarries into the month ascum_prem_pp(d - 1).cum_prem_pp()opens from it att_entry(), so the GPT test, the 7-pay test and the TARGET premium cap of month 0 all count the premiums paid before the valuation date.IUL_US_Sopens its accumulator at 0 on any point, the notes giving no opening accumulator [std], so its flags are meaningful only for points projected from issue.It may be negative. The statutory “less a portion of withdrawals” is taken as the whole withdrawal [std], so this is a tax measure, not a balance, and withdrawals can exceed the premiums paid. Zero for a point not yet in force.
- cum_prem_net_init()[source]#
CumP(0): premiums less withdrawals and loans per policy before the valuation date.
The
cum_prem_net_initcolumn, the no-lapse guarantee’s accumulator: every gross premium collected from issue through policy monthduration_mth_init() - 1, less every withdrawal and every new loan, which is whatIUL_US_Scarries into the month ascum_prem_net_pp(d - 1).cum_prem_net_pp()opens from it att_entry(), so the no-lapse test of month 0 compares every premium since issue with the cumulative minimum no-lapse premium since issue, whichcum_mnlp_pp()counts on the policy clock. Opened at 0, asIUL_US_Sopens it, a policy in force would fail that test at once and lose its guarantee.It may be negative, as loans can exceed the premiums paid net of withdrawals;
Dataholds it to at mostcum_prem_init(), to a cent and a half, since loans only lower it. Zero for a point not yet in force.
- is_mec_init()[source]#
The MEC latch entering month 0: whether the 7-pay test failed before it.
The
is_mec_initcolumn, an int code: 1 for a policy that failed the 7-pay test in some month before the valuation date, and so is a modified endowment contract for good, 0 otherwise.is_mec()latches on it att_entry(), so a policy that failed in its first seven years stays a MEC after them, where the in-year test no longer applies.IUL_US_S’s flag does not latch, so the generator reads whether its in-year test failed in any month beforeduration_mth_init().Datarefuses a 0 wherecum_prem_initalready exceeds the 7-pay limit of the month before the valuation date, inside the first seven policy years. Read as a bool, so 1.0 reads as True. Zero for a point not yet in force.
- seg_bal_pp_init(k)[source]#
S_k(0): the balance per policy entering month 0 of the segment in ladder slot k.
Data.seg_bal_pp_initat this point and slotk, theseg_bal_pp_initcolumn ofinforce_segments_sec.csv:kis the months since the segment’s creation at the valuation date, and the value is the balance at the close of policy monthduration_mth_init() - 1of the segment born in policy monthduration_mth_init() - k, which is whatIUL_US_Scarries into the month asseg_bal_pp(d - 1, d - k).seg_bal_pp()opens each live segment from it att_entry(), its slot then the ladder’s,seg_bal_active_pp()sums slots 1 to 11 into month 0’s pool, and slot 12, the segment maturing att = 0, is what month 0’s maturity rolls into the fixed account (seg_roll_pp()).Dataholds it to-1e-8or more, the tolerancecheck_seg_ladder()holds a live balance to, andproj_len()refuses a point whose ladder does not hold exactly slots 1 tomin(12, duration_mth_init()). Read only on a point in force, at1 <= k <= 12. Like the other four readers of the ladder, it asksproj_len()first, so that a ladder missing a slot is refused by name before any value of it is read, and then refuses a slot below 1 or past the point’s last, naming the point and the slot, where stageE’s.locraised pandas’KeyError, so that no read meetsData’s padding.
- seg_ded_cum_pp_init(k)[source]#
The deductions per policy charged to the segment in ladder slot k before month 0.
Data.seg_ded_cum_pp_initat the point and slotk, theseg_ded_cum_pp_initcolumn ofinforce_segments_sec.csv: every monthly deduction the segment born in policy monthduration_mth_init() - khas borne since its creation, through the close of policy monthduration_mth_init() - 1, which isIUL_US_S’sseg_ded_cum_pp(d - 1, d - k). With the balance and the draws it is the segment’s credit base:seg_ded_cum_pp()opens from it att_entry(), and in slot 12index_credit_pp()reads it att = 0, where the credit base conventionADJ_BEGINhalf-weights it. Read only on a point in force, at1 <= k <= 12, afterproj_len(), and refused, asseg_bal_pp_init()refuses it, at a slot the point does not hold.
- seg_wd_cum_pp_init(k)[source]#
The draws per policy out of the segment in ladder slot k before month 0.
Data.seg_wd_cum_pp_initat the point and slotk, theseg_wd_cum_pp_initcolumn ofinforce_segments_sec.csv: every withdrawal and loan transfer the segment born in policy monthduration_mth_init() - khas paid since its creation, through the close of policy monthduration_mth_init() - 1, which isIUL_US_S’sseg_wd_cum_pp(d - 1, d - k).seg_wd_cum_pp()opens from it att_entry(), and in slot 12index_credit_pp()reads it att = 0. Read only on a point in force, at1 <= k <= 12, afterproj_len(), and refused, asseg_bal_pp_init()refuses it, at a slot the point does not hold.
- seg_index_start_init(k)[source]#
I(m_k): the index level at the creation of the segment in ladder slot k.
Data.seg_index_start_initat the point and slotk, theseg_index_start_initcolumn ofinforce_segments_sec.csv: the index level the segment born in policy monthduration_mth_init() - kstarted from, on this model’s path, the valuation clock’s, whose level at the valuation date isindex_level_init:IUL_US_S’s level at the segment’s creation month timesindex_level_initover its level at monthduration_mth_init(). So the segment’s return at maturity, a ratio of two levels, isIUL_US_S’s. Read for the segment maturing in montht < 12byseg_index_start(), and only on a point in force, at1 <= k <= 12, afterproj_len();Dataholds it above 0, since the return divides by it, and it is refused, asseg_bal_pp_init()refuses it, at a slot the point does not hold.
- seg_index_cap_init(k)[source]#
c_k: the cap declared at the creation of the segment in ladder slot k.
Data.seg_index_cap_initat the point and slotk, theseg_index_cap_initcolumn ofinforce_segments_sec.csv: the cap in force when the segment born in policy monthduration_mth_init() - kwas created, which its credit at maturity is capped at, the cap being re-declared at every segment start [S3][S4].IUL_US_Sholds the cap level, so every segment carriesindex_cap_at()’s value; the column lets a cap re-declared at the valuation date apply to new segments only. Read for the segment maturing in montht < 12byseg_index_cap(), and only on a point in force, at1 <= k <= 12, afterproj_len();Dataholds it to 0 or more, and it is refused, asseg_bal_pp_init()refuses it, at a slot the point does not hold.
- policy_count()[source]#
The number of policies the model point stands for, its
policy_countcolumn.A point in force at the valuation date counts the policies in force then, before any month-0 event; any other point counts the policies it issues. Either way the count enters the projection once: as
pols_if_init()for the first, aspols_new_biz()in the issue month for the second. Every per-policy value – the accounts, the segments, the loan, the face, the opening state – is the same whatever the count, and every cash flow is a per-policy amount weighted by it.
- pols_if_init()[source]#
Policies 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 policies enter throughpols_new_biz()in the issue month instead, as inbasiclife.BasicTerm_SE. So on a point issued att = 0this is 0, andpols_if(0)is the issued count.IUL_US_S’s cell of the name is the notes’l(0), the count at the start of its frame, which on new business is the issued count.
- duration_mth_init()[source]#
Completed policy months at the valuation date, the
duration_mthcolumn.The policy’s age in months at
t = 0: 60 for point 6 and 888 for point 11,IUL_US_S’s point 1 on its fifth anniversary and two years before the end of its projection, 0 for a policy issued at the valuation date, and -25 for point 12, to be issued 25 months after it, whichDataadmits up tofuture_horizon_mthmonths ahead. This is the notes’ issue-date / duration offset attribute, an elapsed count and therefore already 0-based, andIUL_US_S’s cell and column of the same name, which count from the first month of its own frame; here that month is the valuation date for every point, and the count may be negative. It is the one fact the policy clock takes from the model point.
- has_surr_charge()[source]#
Whether a surrender charge schedule applies to this model point.
Data.has_surr_chargeat the point: itshas_surr_chargecolumn, whichDataholds to True or False in any case.
- surr_charge_id()[source]#
The surrender charge schedule ID, a row label of surr_charge_table.csv.
A reporting cell (the Space docstring):
Datajoins the schedule by it, throughData.surr_charge_rate_maxandData.surr_charge_runoff_years, and no projection cell reads it here. Returned as read: a blank id on a point without a charge is NaN.
- surr_charge_rate_max()[source]#
The schedule’s charge per $1,000 of initial face, before any of it runs off.
Data.surr_charge_rate_maxat the point: thesc_per_1000_initcolumn of the point’s row of surr_charge_table.csv, $25.00 on the shippedIUL10schedule;surr_charge_rate()runs it off from here.Datajoins the schedule to the points bysurr_charge_idonce it has checked the table, so that no projection cell reads the table or the id, and refuses the table, naming every point, where a point thathas_surr_charge()names an id the table lacks, whichIUL_US_S’s.locmet in every month of its cover.surr_charge_rate()reads it only wherehas_surr_charge()is true, but a point without a charge reads its schedule too, as at stageE, where the table holds its id; where it does not,Data.has_surr_charge_scheduleis 0, and this raisesValueError, naming the point, where stageE’s refused it.
- surr_charge_runoff_years()[source]#
The number of policy years over which the schedule’s charge runs off, linearly.
Data.surr_charge_runoff_yearsat the point: therunoff_yearscolumn of the point’s row of surr_charge_table.csv, 10 on the shippedIUL10schedule, read as a float, asIUL_US_Sreads it, and joined, checked and refused assurr_charge_rate_max()is.Dataholds it to a whole number of years, 1 or more, so that the division insurr_charge_rate()never meets 0 andlapse_shock_year()’sint()of it changes nothing, and to below2**53years on a point with a charge, where thatint()is exact.
- wd_first_year()[source]#
The first policy year in which a withdrawal may be taken.
2 in the shipped points: withdrawals are allowed after the free-look period [S3] and the model takes that as the first anniversary [std].
- wd_pp_mth()[source]#
The planned partial withdrawal per policy, in each month withdrawals are allowed.
The model point’s
wd_ppcolumn, a monthly amount, gross of the $25 fee and 0 in the baseline [std]; model point 5 takes $200 a month. Read once a point here, so thatwd_pp(), a monthly cell on the accounts’ chains, reads no model point column in its own formula.Dataholds it to 0 or more, andproj_len()refuses one above 0 and below the fee.
- loan_first_year()[source]#
The first policy year in which the distribution-scenario loan is drawn.
The notes’ loan utilization module borrows a level amount annually from a start age, e.g. 65 [std]; 21 for issue age 45 is that age expressed as a policy year.
- loan_new_pp_ann()[source]#
The planned standard loan per policy, drawn at each anniversary loans are taken.
The model point’s
loan_new_pp_anncolumn, 0 in the baseline – the notes set loan utilization to none – and $6,000 a year on model point 5. Read once a point here, so thatloan_new_pp(), a monthly cell on the accounts’ and the loan’s chains, reads no model point column in its own formula.Dataholds it to 0 or more.
- mnlp_rate()[source]#
The minimum monthly no-lapse premium rate per $1,000 of face, annualized [S3].
20.80 for M / Non-Tobacco / 45 / band 1 [S3]: the entry in one carrier’s base annual minimum premium rate table for faces of $25,000-$99,999, which that carrier does not label as MNLP rates, so reading it as the annualized MNLP is [std]. The 250,000 example face falls in the same carrier’s $100,000-and-up table, which gives 11.32 for the same cell [S3]; the band-1 rate stands in [std].
- gsp()[source]#
The guideline single premium (GPT compliance input) [std] placeholder.
No retrieved source gives guideline premiums for this composite, so the shipped value is a plausible placeholder, not a computed IRC 7702 figure.
- duration_mth(t)[source]#
Completed policy months at the beginning 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. It is the notes’ own month index, 0 in the issue month –t = 0for a point issued at the valuation date – and negative before issue. Anniversary events testduration_mth(t) % 12 == 0, and a segment’s creation month, themofseg_new_pp(), is a value of it, its slot in montht, thekofseg_bal_pp(),duration_mth(t) - m.
- duration(t)[source]#
Completed policy years at the beginning of month t,
duration_mth(t) // 12.0 throughout the first policy year, as in lifelib, and negative before issue.
- policy_year(t)[source]#
y: the policy year containing month t, the 1-based contractual label.
duration(t) + 1. Derived, never indexed by: it is what the policy-year-keyed schedules – the COI scale, the lapse table,wd_first_year,loan_first_year, the no-lapse period – are looked up with. It is 0 or less before issue, where no table is read by it: each reader is called inside cover only (is_active()).
- age(t)[source]#
The attained age (ANB) in month t:
age_at_entry() + duration(t).Attained age increments on the policy anniversary, not on the birthday, which is the ANB convention the whole model is built on [std] (spec Table 1, F1). It is the issue age throughout the first policy year, and below it before issue, where no table is read at it.
- maturity_mth()[source]#
The policy month at which the projection ends, the first at attained age 121.
12 * (maturity_age - age_at_entry()): 912 at issue age 45. The projection runs to attained age 121 [std], the notes’ [unverified] maturity inference (spec F5), so the last month of the frame,maturity_mth() - 1, is the last at attained age 120. It isIUL_US_S’s frame from issue, counted on the policy clock;proj_len()counts from the valuation date instead. The contract is described as continuing in force at 121 with no further charges, so the horizon truncates the run rather than terminating the policy: where lives survive the last month, the count and the account value they carry into this month are kept (seepols_if_at()). Premiums and charges cease atcharges_cease_age, a Reference of its own, 121 too as shipped, which may be set inside the frame.
- proj_len()[source]#
The number of months from the valuation date to the end of the projection.
maturity_mth() - duration_mth_init(): 912 for a policy issued at age 45 at the valuation date, 852 for point 6, in force 60 months, and 937 for point 12, issued 25 months after the valuation date. The frame ist = 0, 1, ..., proj_len() - 1;proj_len()is its exclusive end, the row count of every result table, andproj_len() - 1is the frame’s last month, the last at attained age 120. The contract is described as continuing in force at 121 with no further charges, so the horizon truncates the run rather than terminating the policy;pols_maturity()is identically zero, and the count and the account value the survivors carry intot = proj_len()are kept (seematurity_mth()).Six kinds of point raise here, naming the point, rather than projecting, each checked in this order: one to be issued at or past attained age 121, which would never be in cover,
maturity_mth() <= 0, so that a point issued past it is refused by this rule whenever it is to be issued; one at or past the end of the projection at the valuation date; one whose planned withdrawal is above 0 and below the withdrawal fee,wd_fee, which the fee would exceed – the account would be debited the withdrawal, less than the fee the insurer books, and the policyholder paid nothing, so thatIUL_US_S’s own account value roll-forward and margin identity fail on such a point; one in force whose segment ladder ininforce_segments_sec.csvdoes not hold exactly one row for each of its lastmin(seg_term_mth, duration_mth_init())months, slots 1 to that, a segment a month however little it was swept; and one issued belowissue_age_min, 0, or aboveissue_age_max, 85, the issue agesproduct-spec.mdadmits.IUL_US_Sprojects any age its tables serve, but the compiled model’s caches are sized from the youngest issue age (spec_sec.py), so a younger point, whose frame and policy years run longer, would read past them;Datarefuses an age below 0 first, so at the shipped value that rule binds only once the Reference is raised. The oldest sizes nothing, and is the contract’s. The two issue-age rules come after the four of stageE, so that every message stageEgave a point it still gives. An in-force extract should carry none of them. These are rules of the product, read from this Space’s References, whereDatachecks the tables. The ladder’s counts are compared asDataelements, not held in locals, and the file is named as shipped, so that the formula keeps no Python object compiled.
- t_entry()[source]#
The first month the policy is on the books:
max(0, -duration_mth_init()).0 for a point in force at the valuation date or issued at it,
kfor one issuedkmonths later. It is the base of every recursion: the count, the account value, the fixed account, the collateral, the loan, each live segment and its running totals, the face, the two premium accumulators and the MEC latch all open there, from the model point’s opening state and its segment ladder on a point in force and from the issue values on any other. No cell reads a month before it: a segment created before the valuation date is read from the ladder, never from a month beforet = 0.
- is_active(t)[source]#
Whether month t is inside cover: issued, and inside the projection.
0 <= duration_mth(t) < maturity_mth(), false before issue and fromt = proj_len()on. Outside cover every count, balance, segment, charge, premium, withdrawal, loan draw, credit, decrement rate, decrement, claim and flow is zero and every flag false,seg_count()the int 0, and no table is read at a policy year or an attained age the policy does not have; the clocks and the inputs read on the valuation clock and the level policy fee,expense_pol_mth_at(), keep their values, and the two lapse multipliers their neutral 1.0. The two exceptions are the opening values of the month after the frame, the count and the account value carried intot = proj_len(), which the roll-forwards read (seepols_if_at()andav_pp_at()).
- is_guaranteed_basis()[source]#
Whether the run uses class (a) contractual guarantees only.
basisisCURRENTin the base run, so the current non-guaranteed scales apply. Setting it toGUARANTEEDswitches the fixed-account rate to 1.00%, the cap to 2.00%, the premium load to 8%, the policy fee to $15, the per-unit charge to $0.40 in all years and the COI scale to its guaranteed maximum – the notes’ “guaranteed-basis projections use only this class”. Key sensitivity 1 in the notes is exactly how far apart the two runs are.basisholds a code, asIUL_US_S’s holds the text it is named for (the Space docstring’s Codes), and any other value is refused,"invalid basis", as there.
- load_prem_rate()[source]#
l_prem: the premium load rate, 5% current [std] / 8% guaranteed [std] (F12).
The current rate sits in the model point table because the load is itself a non-guaranteed element re-declarable under ASOP 2 [REG-R26]:
Data.load_prem_rateat the point.
- fixed_rate_ann(t)[source]#
i_fix: the fixed (holding) account annual effective rate.
4.50% current [S2], 1.00% guaranteed [S2]. A non-guaranteed element; the base deterministic run holds the snapshot level, as the notes prescribe. An economic input, read at month
ton the valuation clock, the same month for every point, as a re-declared rate would apply; level as shipped, so it holds its value outside cover.
- inv_return_mth(t)[source]#
The monthly fixed-account rate,
(1 + i_fix)^(1/12) - 1[std] conversion.0.0036748 at the 4.50% current rate [S2]. The name follows
CashValue_SE; only the fixed account and the loan collateral account earn it – segments earn no interim interest at all, which is what the 0% floor design buys [S2].
- guar_rate_mth()[source]#
i_gm: the monthly guaranteed rate,
(1 + i_g)^(1/12) - 1at i_g = 1.00% [S2].
- naar_factor()[source]#
1 + i_gm;v_g = 1 / naar_factor()is the notes’ one-month discount.The death benefit is discounted one month at the guaranteed rate, never the credited or index rate – the universal life base convention, carried over unchanged. 1.0008295 at the 1.00% guarantee [S2].
- loan_rate_mth()[source]#
The monthly charged loan rate,
(1 + i_L^c)^(1/12) - 1, at 3.00% [std] (F18).A Reference of the run, level in every month.
- loan_credit_rate_ann(t)[source]#
i_L^e: the rate credited on loan collateral, 2.00% years 1-10, 3.00% after [std].
The standardization keeps the universal carrier pattern of a ~1% net loan spread early grading to a 0% “wash” from year 11 [S3][S5][S7] (F18). A term of the contract, so it steps on the policy year. Zero outside cover, before the policy year is compared: before issue the valuation clock reaches policy years the policy does not have.
- index_cap_at(t)[source]#
c: the cap in force, 10.00% current [S2] / 2.00% guaranteed [S2] (F8).
The current cap is a snapshot: observed 10.00%-13.75% across carriers and print dates [S2][S3][S4][S5][S7], and re-declared at every segment start [S3][S4]. The base run holds it level; a cap re-declaration module driven by an option budget is described in the notes but not implemented, because the notes supply neither an option pricing model nor a net investment earnings rate path.
Read at month
ton the valuation clock, the cap declared then: a segment created in monthtis capped atindex_cap_at(t)at its maturity, twelve months on (seg_index_cap()), and a segment created before the valuation date at the cap its ladder row carries,seg_index_cap_init(). Level as shipped, so it holds its value outside cover.
- index_level(t)[source]#
I(t): the S&P 500 price-return index level at monthiversary t [S2][S3].
The base deterministic run grows the index at a level
index_return_anna year along the valuation clock:index_level_init * (1 + index_return_ann)^(t / 12), soindex_level_initis the level at the valuation date, one path for every point, and every segment matures at the same point-to-point return. 6.40% is the carrier-published 1988-2023 lookback for the 10%-cap account [S2].IUL_US_Sreads the path atduration_mth(t), a path of each point’s own from its issue, which is the same path on a point issued at the valuation date. Moving the path moves no credit, a ratio of two levels on one path: a segment created before the valuation date carries its start level on this path in its ladder row (seg_index_start()).This cell is the single point of substitution. Override it, a formula override, which only modelx can make (compiled, edit the formula and rebuild), with a historical or simulated path, keyed by the months from the valuation date, and every segment created in the frame follows; the ladder’s start levels are inputs, which do not follow an override, so an extract’s
seg_index_start_initmust be on the overriding path: the notes’ stochastic module (real-world lognormal, mu = 6.0%, sigma = 16% [std]) is a driver around the model, not a formula inside it. Remember what the notes say about the level rate: AG 49-A bounds what may be illustrated, not what will be credited [R1][R6], and because the cap truncates the right tail while the floor only offsets the left, a deterministic run at the illustrated rate overstates credits against a stochastic mean at matched expected index growth. A function of the clock alone, so it holds its value outside cover.
- index_change(index_start, index_end)[source]#
r = I(m+12) / I(m) - 1: the point-to-point index change over a segment term.
Price return, dividends excluded [S2][S3]. Takes the two index levels rather than a month so that the worked example’s own levels – 4,500.00 to 5,040.00 in scenario A, to 3,825.00 in scenario B – can be put through the same formula the projection uses. An engine cell of
IUL_US_S’s, kept for its worked example and for the comparison with it (the Space docstring’s Reporting cells): no projection cell calls it, andseg_return()computes the same ratio for the segment maturing in montht.
- index_credit_rate(index_return, cap=None)[source]#
cr_k = max(f, min(c, p x r)): the credited rate for one segment [S2][S3][R1].
Floor 0%, participation 100%, cap per
index_cap_at()[S2].capdefaults to the cap in force att = 0,IUL_US_S’s engine, kept unchanged for its worked example – passindex_cap_guarfor the guaranteed-basis credit; the notes price both on the worked example, at 10.00% and 2.00%. An engine cell, kept for that example and for the comparison withIUL_US_S: no projection cell calls it, andseg_credit_rate()computes the same rate, in the same order of bounds, for the segment maturing in montht, at the cap declared at its creation.This is where the two-sided truncation lives: the cap binds on the way up, the floor on the way down, and the historical frequency of a 0% credit for a single index allocation was 12.55%-23.81% in a carrier’s 2005-2017 issue-date study [S8].
- seg_credit_base(seg_bal_init, seg_deductions, conv=None)[source]#
The segment balance the index credit is applied to.
REMAINING[std], the baselineseg_bal_init - seg_deductions: the actual balance left at maturity, so amounts withdrawn, borrowed or deducted mid-segment earn no index credit (withdrawal and loan forfeiture [S3]; extension to deductions [std]).ADJ_BEGIN, the documented variationseg_bal_init - seg_deductions / 2: one carrier’s contractual adjusted beginning value, which subtracts withdrawals and loan transfers in full but one half of the monthly deductions taken during the segment [S3]. Passseg_bal_initalready net of withdrawals and loan transfers, asindex_credit_pp()takes it.
The notes list picking one and keeping the death benefit, cash value and credit formulas consistent with it among the modeling pitfalls;
seg_credit_base_convis the Reference that records the choice, a code (the Space docstring’s Codes), whichconvdefaults to. An engine cell, kept forIUL_US_S’s worked example and for the comparison with it: no projection cell calls it, andindex_credit_pp()computes the same base inline, refusing a convention neither code names with the same"invalid credit base".
- index_credit(seg_bal_init, seg_deductions, index_return, conv=None, cap=None)[source]#
Credit_k = cr_k x credit base: the index credit paid at a segment’s maturity.
The engine form, taking the segment’s opening balance (net of any withdrawals and loan transfers), the deductions charged to it over its term, and its point-to-point index change:
index_credit_rate()timesseg_credit_base(). An engine cell, kept forIUL_US_S’s worked example, which prices one segment’s credit at both caps through it, and for the comparison withIUL_US_S, whose projection calls it: no projection cell here calls it, andindex_credit_pp()computes the same product, the rate first, then the base.
- seg_matured_value(seg_bal_init, seg_deductions, index_return, conv=None, cap=None)[source]#
The matured segment value: remaining balance plus the index credit.
S_{k,m+12} x (1 + cr_k)under the baseline credit base, which is the value that rolls into the fixed account and is swept back into a new segment under the standing allocation instruction [std] (spec F11). An engine cell, kept forIUL_US_S’s worked example, which alone calls it;seg_roll_pp()is the projection’s matured value.
- prem_persistency(t)[source]#
The fraction of the planned premium actually paid in policy year y [std].
0.98^(y - 1): the notes give premium persistency in closed form rather than as a table, compounding at 98% a year. Premium persistency is the behavior dimension unique to flexible-premium products; the 2015-2021 LIMRA/SOA UL study is the recommended public calibration base [REG-R21] and the level here is a placeholder. A rule of the contract’s years, so it steps on the policy year: a policy in force pays the persistency of its own year, not of the valuation date’s.The funding-stop state the notes pair with this factor – probability 1% a year, after which the policy runs charge-only – is a second account value path the notes do not say how to blend with the first, and is not implemented. Zero outside cover, before the policy year is read.
P_t: the gross premium per policy received at BOM of month t.
Annual mode [std]: the whole planned premium falls at BOM of the first month of each policy year,
duration_mth(t) % 12 == 0, and every other month is zero. Monthly mode: a twelfth of the planned annual premium falls at BOM of every month,premium_pp_ann / 12timesprem_persistency(), as on points 4, 7 and 12.LEVELThe planned premium times
prem_persistency(), in either mode.SINGLEOne premium in the issue month, capped at the guideline single premium.
TARGETAs
LEVELbut capped so cumulative premium stays inside the guideline premium limit [std]; the cap looks at the accumulator’s opening value –cum_prem_pp(t - 1), or, in the first month on the books,t_entry(),cum_prem_init(), the premiums less withdrawals paid before the valuation date, 0 at issue – so there is no circularity, and a TARGET point in force near its limit collects only what the limit still has room for.
Zero from attained age
charges_cease_age, 121 as shipped, when charges cease and premiums are no longer accepted (spec F5), and zero outside cover. The pattern and the mode are read through their decodes,is_single_premium(),is_level_premium(),is_target_premium(),is_annual_premium()andis_monthly_premium(), not as text; a value none of them knows raises, asIUL_US_S’s does.
- prem_to_av_pp(t)[source]#
NP_t = P_t (1 - l_prem): the net premium, credited to the fixed account.
The fixed account doubles as the interim / holding account: net premium sits there at the declared fixed rate until the next monthiversary sweep moves it into a segment [S1] [std] (spec F10).
Premium income at BOM of month t, weighted by the in force at BOM.
- wd_pp(t)[source]#
W_t: the partial withdrawal per policy at BOM of month t, gross of the fee.
A constant monthly amount from
wd_first_year(),wd_pp_mth(), the model point’swd_ppcolumn, and 0 in the baseline [std]: the notes give no withdrawal utilization pattern, so the mechanics are implemented and the behaviour is left to the data. Model point 5 switches it on.The account is debited
W_t; the policyholder receivesW_t - 25and the insurer keeps the $25 fee [S3]. This differs from the universal life chassis, where the fee is charged on top of the withdrawal – these notes write the withdrawal outflow asW_t - $25 fee, so the fee is insideW_there. Zero from attained agecharges_cease_age, and zero outside cover, before the policy year is compared: before issue the valuation clock reaches policy years the policy does not have.
- wd_fee_pp(t)[source]#
The $25 withdrawal fee, charged only in a month with a withdrawal [S3].
Retained by the insurer, so it is part of
margin_expense(), not ofclaims(). It is not an extra debit to the account value: it comes out ofW_t.
- loan_new_pp(t)[source]#
B_t: a new standard loan taken at BOM of month t [std].
The notes’ distribution-scenario module borrows a level amount annually from a start age [std]; here that is
loan_new_pp_ann(), the model point’sloan_new_pp_ann, at each policy anniversary from the first month of policy yearloan_first_year(). Zero in the baseline – the notes set loan utilization to none – and switched on by model point 5.Participating (indexed) loans are a documented variation, not modeled: the baseline uses standard loans only [std] (F18), which decouples loan modeling from index scenarios. Zero outside cover, before the policy year is compared.
- face_reduction_pp(t)[source]#
The face reduction a withdrawal forces under Option A, dollar for dollar [std].
Standard universal life practice, stated in the product spec but not explicit in the retrieved brochures. Under Option B the withdrawal reduces the account value only and this is zero. Never more than the face entering the month, which is the previous month’s
sum_assured_at(), or, in the first month on the books,t_entry(), the face in force at the valuation date,sum_assured_init(), on a point in force, and the face at issue,sum_assured(), on any other. The option is read through its decode,is_db_option_a(). Zero outside cover.
- sum_assured_at(t)[source]#
F(t+1): the face amount at the end of month t, after any withdrawal-driven cuts.
A closing balance: the opening face of month
tis the previous month’s, and in the first month on the books,t_entry(), the face in force at the valuation date,sum_assured_init(), on a point in force, and the face at issue,sum_assured(), on any other, less this month’s Option A reduction. Face increases, elective decreases and option changes are not modeled, so the withdrawal reduction is the only movement; it never takes more than the opening face, so the face reaches 0 at the least and stays there. Zero outside cover.
- units(t)[source]#
The face amount in $1,000 units,
sum_assured_at(t) / 1000.The per-unit charge is quoted per $1,000 of face per month, so it multiplies this. The surrender charge is quoted per $1,000 of initial face, because face decreases do not reduce it [S3]; see
surr_charge_pp().
- corridor_factor(t)[source]#
kappa_x: the IRC 7702(d) corridor factor at the attained age [R4].
250% at ages 0-40 grading to 100% at 90-95, read at the attained age of month t by
corridor_factor_at(). Only the Guideline Premium Test is modeled (spec F4), so any otherqual_testraises rather than being treated as GPT, in whatever month, since it is a fault of the point; the test is read through its decode,is_gpt().High funding drives the corridor rather than the face amount, which raises the death benefit, the net amount at risk and hence the cost of insurance: the notes list omitting this among the pitfalls, because it overstates late-duration account values and understates charges. Zero outside cover, before the table is read.
- corridor_factor_at(a)[source]#
kappa at attained age a, from corridor_factors.csv: the table’s one reader.
Data.corridor_factor_array()at the age, the table padded from age 0, so that the age is the index. Ages outside the table take its nearest row: the first and last agesdata.corridor_age_first()anddata.corridor_age_last()give, which they read from the table’s key column once the keys and the factors are checked, before any factor is read. So the padding is never read, and no age below 0 is either:Datarefuses a table whose first age is negative. The last is asked for first, since it runs the checks and the first is counted back from it. Keyed by the attained age, so the table is read once an age rather than once a month;corridor_factor()calls it inside cover only.
- db_pp(t)[source]#
DB_t: the death benefit per policy after the corridor test [S3][R4].
max(option_db, kappa_x x AV'_t)whereoption_dbis the face amount under Option A and face plus account value under Option B, andAV'_tis the account value after premium, the maturity credit and any withdrawal, and before the monthly deduction. Measuring the account value at that point is what removes the circularity: under Option B the death benefit depends on the account value and the net amount at risk on the death benefit, but with this ordering neither depends on the deduction.During a segment the death benefit reflects the segment balance without unrealized index credit [S3]: with a 0% floor design segments simply carry no interim interest, so nothing extra is needed here.
IUL_US_S’s formula, with no floor on the account value: an exhausted account’sAV'_tbelow zero leaves the corridor’s amount at 0 or below, and the face wins, whichDatakeeps so by refusing a corridor factor below 0. The option is read through its decodes,is_db_option_a()andis_db_option_b(), not as text. Zero outside cover, before the corridor table is read.
- net_amt_at_risk(t)[source]#
NAAR_t = max(0, DB_t x v_g - AV’_t), the universal life base convention.
The death benefit is discounted one month at the guaranteed rate (
naar_factor()) and the account value is measured before the monthly deduction. Using the credited or index rate in the discount, or the post-deduction account value, makes the cost of insurance implicit and requires iteration, and produces small systematic errors.
- coi_rate_guar(t)[source]#
The guaranteed maximum monthly COI rate per $1,000 of net amount at risk.
The notes set the guaranteed basis at 2017 CSO ANB smoker-distinct ultimate [std]/[REG-R17]. That table is licensed and is not reproduced here: the shipped scale is illustrative [std], of realistic magnitude and shape, and is swapped by replacing coi_rates.csv. Read at the policy year of month t by
coi_rate_guar_py(), where policy years beyond the table take its last row; zero outside cover, before the scale is read.
- coi_schedule()[source]#
The number of this point’s guaranteed COI scale, its row of the COI array.
Data.coi_scheduleat the point: the schedules of coi_rates.csv, one for eachsex,rate_classandage_at_entryit holds, numbered from 1 in the order of those keys, and 0 where the table has no scale for the point’s own, whichcoi_rate_last_year()refuses where a rate is read. It stands forIUL_US_S’scoi_rate_scale, a Series sliced from the table, which no compiled cell can hold:coi_rate_guar_py()reads the scale at this row and the year.
- coi_rate_guar_py(y)[source]#
The guaranteed maximum monthly COI rate in policy year y, from the point’s scale.
Data.coi_rate_array()at the point’scoi_schedule()and the year, each schedule padded from year 0, so that the year is the column. Policy years beyond the scale take its last row,coi_rate_last_year(), which is asked for first, so that a projection meets the check of the table’s keys, and the refusal of a point whose cell the table lacks, before any rate is read. A year below 1, whereIUL_US_S’s slice raisedKeyError, is refused, naming the point and the year, so that the padding is never read. The scale’s one reader, keyed by the contractual policy year;coi_rate_guar()calls it inside cover only.
- coi_rate_last_year()[source]#
The last policy year of this point’s guaranteed COI scale: its extent.
Data.coi_rate_last_yearsat this point’scoi_schedule(), the last year of its scale, whichDatareads from the table’s key columns once it has checked the keys and the rates. 76 on the shipped anchor cell, whose scale runs to attained age 120. A point the table has no scale for, schedule 0, has a last year of 0, and is refused here, naming it and its issue age, whereIUL_US_Sraises pandas’KeyError: when its first COI rate is read, and not before, since a point valued at or pastcharges_cease_agenever reads one, andIUL_US_Sprojects it. StageE’s message quoted the point’ssexandrate_classtoo, which a projection formula cannot read here: each is a label, a reporting cell’s. The element is compared, andintof it returned, rather than held in a local first, which a formula that also builds a message would keep a Python object compiled.
- coi_rate(t)[source]#
coi_t: the monthly COI rate in force, per $1,000 of net amount at risk.
coi_curr_factor(65% [std]) times the guaranteed maximum on the current basis; the guaranteed maximum itself on the guaranteed basis. Carrier COI tables are not public [S3] and re-rating is governed by ASOP 2 [REG-R26], so the ratio is a pure modeling assumption and one of the notes’ dominant sensitivities.Note the units: per $1,000 of net amount at risk per month, so it is divided by 1,000 in
coi_pp(). It is not comparable withCashValue_SE.coi_rate, which is a rate per unit of account value.
- coi_pp(t)[source]#
COI_t = coi_t x NAAR_t / 1000: the cost of insurance charge per policy.
Zero from attained age
charges_cease_age, when charges cease, and zero outside cover, before the scale is read.
- rider_charge_pp(t)[source]#
Rider charges, 0 in the baseline [std].
The notes carry this term in the monthly deduction so rider modules can be added without changing the recursion; every rider in the product spec is out of the baseline.
- expense_pol_mth_at(t)[source]#
e_pol: the monthly policy fee, $10 current [S3][S5] / $15 guaranteed [std].
The notes’ F13. Level in every month, an input that holds its value outside cover, as the fixed-account rate and the cap do;
maint_fee_pp(), its one reader, is zero there.
- expense_unit_mth_at(t)[source]#
e_unit: the per-unit charge per $1,000 of face per month (F14).
$0.30 in policy years 1-10 and nothing thereafter on the current basis; $0.40 in all years on the guaranteed basis. The structure – charged for the first ten years currently, guaranteed for all years – is sourced [S3][S5]; the dollar scales live in policy data pages and are not public, so the levels are [std]. A term of the contract, so it steps on the policy year. Zero outside cover, before the policy year is compared.
- maint_fee_pp(t)[source]#
The non-COI part of the monthly deduction per policy.
e_pol + e_unit x F/1000 + rider charges. The name followsCashValue_SE.maint_fee: this is a charge against the account value and therefore insurer income. It is notexpenses(), which is the insurer’s own outgo. Zero from attained agecharges_cease_age, when charges cease, and zero outside cover. The policy fee,expense_pol_mth_at(), is level, an input that holds its value in every month; the guard here keeps it off the months outside cover.
- maint_fee(t)[source]#
Non-COI monthly charges deducted from account values, for the policies in force.
- mth_deduction_pp(t)[source]#
MD_t = e_pol + e_unit x F/1000 x 1{yr<=10} + coi_t x NAAR_t / 1000.
maint_fee_pp()pluscoi_pp(), taken at BOM. The deduction at the start of month t pays for month t’s coverage.
- draw_pp(t)[source]#
The total amount leaving the fixed account and segments at step 3 of month t.
The withdrawal (gross of its fee) plus the collateral for any new standard loan. The loan collateral does not leave the account value – it moves into
lca_pp()– but it does leave the fixed account and the segments, and it is sourced by the same rule: fixed account first, then pro rata across live segments, the order one carrier gives for loans [S3]. Applied to the withdrawal the rule is [std]: that carrier takes withdrawals pro rata across all unloaned accounts [S3].
- draw_from_seg_pp(t)[source]#
The part of the step-3 draw sourced pro rata from live segments.
Only what the fixed account cannot cover, and never more than the live segments hold (see
draw_pp()). Being step 3 it has the first claim on the pool; the step-6 deduction is capped against what is left after it (mth_deduction_from_seg_pp()). Amounts leaving a segment mid-term earn no index credit [S3], which under the baseline credit base happens automatically.
- draw_from_fa_pp(t)[source]#
The part of the step-3 draw sourced from the fixed account, taken first.
Defined as the residual of
draw_pp()so that the two sources always sum to it exactly; if neither the fixed account nor the segments can cover it, the fixed account carries the excess and goes negative rather than the draw being silently truncated.
- mth_deduction_from_seg_pp(t)[source]#
The part of the monthly deduction sourced pro rata from live segments [std].
The notes’ sourcing convention: fixed account first, shortfall pro rata across active segments. Never more than the segments still hold after the step-3 draw, which is why the cap is
seg_bal_active_pp(t) - draw_from_seg_pp(t)and not the pooldraw_from_seg_pp()was itself capped against: the withdrawal and the new loan collateral come out of the same segments earlier in the same month, so capping both against the pre-draw pool would let the two together take more than the segments hold. That drives a segment balance negative and, twelve months later, pays a negative index credit on it – a breach of the 0% floor ofcr_k = max(f, min(c, p x r))[S2][R1].check_seg_ladder()asserts both consequences away.Whatever the segments cannot cover stays with
mth_deduction_from_fa_pp(), so the fixed account carries the excess and goes negative rather than the deduction being silently truncated – the notes chargeMD_tin full and hand an uncovered deduction to the grace/lapse cascade, which is not implemented.Carrier practice differs – one carrier instead half-weights in-segment deductions in its credit base [S3] – and the notes list picking one and keeping the formulas consistent among the modeling pitfalls; see
seg_credit_base().
- mth_deduction_from_fa_pp(t)[source]#
The part of the monthly deduction sourced from the fixed account, taken first.
The residual, so the two sources always sum to
mth_deduction_pp().
- seg_bal_active_pp(t)[source]#
The live segment balances available to a draw at BOM of month t.
The segments born in policy months
duration_mth(t) - 11toduration_mth(t) - 1, valued at the end of montht - 1, where each sat in slotduration_mth(t) - 1 - m. The segment born atduration_mth(t) - 12is not in the pool: it matured at step 2 of this month and its value is already in the fixed account. The segment born this month does not exist yet – it is created by the sweep at step 7. No segment is born before issue, so the pool is empty in the issue month. In the first month on the books,t_entry(), a segment born before the valuation date is valued from the segment ladder,seg_bal_pp_init(), its balance entering month 0.The balances are summed in
IUL_US_S’s order, by creation month, in an explicit loop that compensates as Python’ssum()of floats does from Python 3.12, Neumaier’s improvement of Kahan’s summation, the compensation added at the end where it is a finite number other than zero,abs(c) <= 1.7976931348623157e308, the largest double: so the pool isIUL_US_S’ssum()bit for bit there, a segment closing on a rounding about zero included, whichseg_share()reads by its test of zero. Compiled, the loop is C on doubles, added in the order written, since nothing in the build lets the compiler reassociate (no-ffast-math), and with no multiply and add fused into one rounding, which the build forbids (-ffp-contract=off). Python 3.11’ssum()is a plain fold, which can put such a pool on the other side of zero. Zero outside cover.
The pro-rata share of a draw at BOM of month t of the segment in slot k.
Its opening balance over the live pool,
seg_bal_active_pp(), and 0 where the pool is not above zero,IUL_US_S’s own test, which a pool closing on a rounding about zero meets either way. Because a pro-rata draw leaves the proportions unchanged, the same shares serve the step-3 draw and the step-6 deduction even though they are taken at different points in the month.kis the segment’s slot in montht, its months since creation,duration_mth(t) - mfor the segment born in policy monthm. The opening balance is the segment’s at the end of montht - 1, where it sat in slotk - 1, or, in the first month on the books,t_entry(), the ladder’sseg_bal_pp_init()at slotk, read only for a slot the ladder holds,1tomin(seg_term_mth, duration_mth_init()); any other slot, slot 0, the segment born in the month itself, or one older than the ladder, has a share of 0, asIUL_US_S’s read of a balance outside its segment’s life gives. Slot 0 asks for no balance, so no cell reads a slot below 0.
- seg_wd_pp(t, k)[source]#
The draw of month t out of the segment in slot k: its share of the step-3 draw.
- seg_ded_pp(t, k)[source]#
The deduction of month t out of the segment in slot k: its share of the monthly deduction.
- sweep_pp(t)[source]#
Sweep_t = w_ix x FA balance after steps 1-6 [std] (spec F10).
The monthiversary sweep, which creates this month’s segment. Carrier practice varies – one carrier sweeps on the 15th [S1], another on the first day of a policy month [S3] – and the baseline standardizes on the monthiversary so segment dates align with monthly processing. A third carrier’s charge-holdback in the fixed strategy [S5] is a documented variation and is not modeled. Nothing is swept from a fixed account below zero. Zero outside cover.
- seg_new_pp(m)[source]#
S_{k,m_k}: the balance of the segment born in policy month m, at its creation.
mis a policy month,duration_mthof the month of the sweep that created the segment. Born in the frame, at or after the valuation date, the segment is that month’s sweep,sweep_pp()at monthm - duration_mth_init(), as inIUL_US_S. Born before the valuation date, it is in ladder slotk = duration_mth_init() - m, and its creation balance is what the ladder gives it since, its balance entering month 0 plus the deductions and the draws charged to it: nothing may enter or leave a segment but a deduction, a withdrawal or a loan transfer, which is the closurecheck_seg_ladder()asserts. Zero for a month before issue and for a segment matured before the valuation date, which nothing reads. Keyed by the creation month, as inIUL_US_S, where the six cells of a segment in a month are keyed by its slot: one value a segment, whichseg_bal_pp()reads in slot 0 andindex_credit_pp()at maturity.
- seg_bal_pp(t, k)[source]#
S_{k,t+1}: the balance at the end of month t of the segment in slot k.
S_{k,t+1} = S_{k,t} - MD^seg - W^seg - B^seg, with no interim interest: the 0% floor design credits nothing during the segment term [S2], in contrast with one carrier’s in-segment 0.75% [S3], which is a different guarantee and must not be mixed with a 0% annual floor. A closing balance: the value at the end of monthtis the notes’S_{k,t+1}.kis the segment’s slot, its months since creation in montht,duration_mth(t) - mfor the segment born in policy monthm: 0 in its creation month, where its balance is its creation balance,seg_new_pp(), and 11 in the last month it is live. Its balance a month earlier is the same segment’s in slotk - 1att - 1.Zero outside slots 0 to
min(11, duration_mth(t)): below 0, for a segment not yet born, past the policy’s months (no segment exists before issue) and past 11, and outside cover. A segment created atmis live through the end of policy monthm + 11and matures at step 2 of policy monthm + 12, before that month’s deduction – so it bears eleven in-segment deductions. The worked example stipulates twelve; seeproducts/indexed_ul/model.md. In the first month on the books,t_entry(), a segment born before the valuation date opens from the ladder,seg_bal_pp_init()at its slot, its balance entering month 0.IUL_US_Skeys the cell by the creation month,seg_bal_pp(t, m); the slot is what lets a compiled cache hold twelve segments a month rather than every creation month of the frame.
- seg_ded_cum_pp(t, k)[source]#
Deductions charged to the segment in slot k, through the end of month t.
Zero in the creation month itself, slot 0 (the segment is created after that month’s deduction), outside the segment’s life and outside cover. Its running total a month earlier is the same segment’s in slot
k - 1att - 1. In the first month on the books,t_entry(), a segment born before the valuation date opens from the ladder,seg_ded_cum_pp_init()at its slot, the deductions charged to it before month 0.
- seg_wd_cum_pp(t, k)[source]#
Withdrawals and loan transfers out of the segment in slot k, through month t.
Zero in the creation month itself, slot 0, outside the segment’s life and outside cover. Its running total a month earlier is the same segment’s in slot
k - 1att - 1. In the first month on the books,t_entry(), a segment born before the valuation date opens from the ladder,seg_wd_cum_pp_init()at its slot, the draws out of it before month 0.
- seg_bal_tot_pp(t)[source]#
The sum of every live segment balance at the end of month t.
The segments born in policy months
max(0, duration_mth(t) - 11)toduration_mth(t), each read at its slot,duration_mth(t) - m, summed inIUL_US_S’s order in the compensated loopseg_bal_active_pp()sums in, so that the total isIUL_US_S’ssum()bit for bit from Python 3.12. Zero outside cover.
- seg_count(t)[source]#
The number of segments with a positive balance at the end of month t.
At most
seg_term_mth(12), the contractual maximum [S4]; zero throughout for a model point withindex_alloc_rate() == 0. A segment counts where its balance, read at its slot, is above zero,IUL_US_S’s own test, which a balance closing on a rounding about zero meets by its sign. An int, counted in a loop, and the int 0 outside cover.
- seg_index_start(t)[source]#
I(m): the index level at the creation of the segment maturing in month t.
The segment maturing in month
twas born twelve months earlier. Born in the frame, at montht - 12, it started fromindex_level(t - 12); born before the valuation date, in ladder slot12 - t, from the start level its ladder row carries,seg_index_start_init(), on the same path.IUL_US_Sreadsindex_level(t - 12), a month of its own frame, since no segment it projects was born before its first month. Zero where nothing matures, in a policy’s first twelve policy months, and outside cover.
- seg_index_cap(t)[source]#
c_m: the cap of the segment maturing in month t, the one declared at its creation.
Born in the frame, at month
t - 12, the segment is capped at the cap in force then,index_cap_at(t - 12); born before the valuation date, in ladder slot12 - t, at the cap its ladder row carries,seg_index_cap_init(). The cap is re-declared at every segment start [S3][S4], and a segment keeps the one declared at its own.IUL_US_Sholds the cap level and its engine readsindex_cap_at(0), the cap in force at its ownt = 0, for every segment, so the two agree on every point it projects. Zero where nothing matures and outside cover.
- seg_return(t)[source]#
r_k for the segment maturing in month t: its own point-to-point index change.
index_level(t) / seg_index_start(t) - 1, the level now over the segment’s start level,seg_index_start():index_change()inlined, as no projection cell calls an engine cell (R14). Each segment carries its own index start level, which is the whole point of a monthly ladder: collapsing twelve segments into one annual segment mis-times credits and distorts mid-segment surrender values [S3]. Zero where nothing matures, in a policy’s first twelve policy months, and outside cover, whereIUL_US_Sleaves it to every caller to guard.
- seg_credit_rate(t)[source]#
cr_k for the segment maturing in month t:
max(f, min(c, p x r)).index_credit_rate()inlined for the projection (R14): the floorindex_floor, the cap declared at the segment’s creation,seg_index_cap(), and the participationindex_paron its own return,seg_return(), bounded inIUL_US_S’s order, the cap first and then the floor, so that a return that is not a number credits the cap, and a cap that is not a number the floor, in both engines alike:minandmaxkeep their first argument unless a later one compares past it, in Python as in the C two-argument form. Cached by month, where the engine cell is keyed by floats.index_credit_pp()multiplies it by the credit base, andcred_rate_ann()reads it as the policy’s credited rate. Zero where nothing matures, in a policy’s first twelve policy months, and outside cover.
- index_credit_pp(t)[source]#
The index credit added to the account value at BOM of month t.
The segment born in policy month
m = duration_mth(t) - 12matures now: its credit isIUL_US_S’sindex_creditof its creation balance net of withdrawals and loan transfers, the deductions charged to it, its own point-to-point return, the credit base conventionseg_credit_base_convand the cap declared at its creation, inlined (R14): the credited rate,seg_credit_rate(), first, then the base, the remaining balance underREMAININGand the deductions half-weighted underADJ_BEGIN, then their product,IUL_US_S’s order of operations, and a convention neither code names refused after the rate,"invalid credit base", as there. The draws and deductions to date are the segment’s at the end of montht - 1, in slot 11; in the first month on the books,t_entry(), a segment born before the valuation date is ladder slot 12, whose draws and deductions are its ladder row’s. Zero in a policy’s first twelve policy months, in every month for a model point that never creates a segment, and outside cover.
- seg_roll_pp(t)[source]#
Roll^FA_t: the matured segment value rolled into the fixed account at step 2.
Remaining balance plus index credit. Under the standing allocation instruction it is swept straight back into a new segment at step 7 [std] (spec F11); routing it through the fixed account is what makes it available to pay this month’s deduction first, which is the notes’ own sourcing rule. The remaining balance is the segment’s at the end of month
t - 1, in slot 11, or, in the first month on the books,t_entry(), ladder slot 12’s. Zero in a policy’s first twelve policy months and outside cover.
- fa_pp_at(t, timing)[source]#
FA: the fixed (holding) account balance at an intra-month point of month t.
The notes’ recursion
FA_{t+1} = [FA_t + NP_t - MD^FA - W^FA - B^FA - Sweep + Roll^FA] x (1+i_fix)^(1/12)unrolled, withtimingnaming the point just before each event:BEF_PREMThe opening balance, the notes’
FA_t: the closing balance of the previous month, formed here from montht - 1’s own opening balance and events, the same operations in the same order asfa_pp(), so that the chain back to the first month on the books is one cell a month. In that month,t_entry(), it isfa_pp_init(), the fixed account the point carries into the valuation month, 0 at issue (FA(0) = 0).IUL_US_Sopens an in-force point at the account value less the loan here, everything outside the collateral in the fixed account. Zero outside cover.BEF_CREDITAfter the net premium, before the maturing segment rolls in.
BEF_WDAfter the roll, before the withdrawal and any new loan collateral.
BEF_FEEAfter the draw, before the monthly deduction.
BEF_SWEEPAfter the deduction, before the sweep. This is the balance the sweep takes
w_ixof.BEF_INVAfter the sweep, before interest. Interest is credited on this balance; reversing the two overstates the account value by about one month’s interest on the deduction, every month.
The balance may run below zero: no policy is terminated for insufficiency, and the fixed account carries whatever the segments cannot (
draw_from_fa_pp()).
- fa_pp(t)[source]#
FA_{t+1}: the fixed (holding) account balance at the end of month t.
A closing balance: the post-sweep balance plus one month’s interest at the fixed-account rate. The opening balance of the month,
fa_pp_init()in the first month on the books, isfa_pp_at(t, BEF_PREM), which forms this cell’s value att - 1itself rather than calling for it. Zero outside cover.
- lca_pp_at(t, timing)[source]#
LCA: the loan collateral account at an intra-month point of month t.
BEF_PREMis the opening balance, the notes’LCA_t: the closing balance of the previous month, formed here from montht - 1’s own opening balance and new loan, the same operations in the same order aslca_pp(), so that the chain is one cell a month; in the first month on the books,t_entry(), it islca_pp_init(), the collateral the point carries into the valuation month, 0 at issue.IUL_US_SsetsLCA(0)equal toloan_bal_init()[std], which the collateral parts from once interest accrues.BEF_INVadds the collateral for any new loan taken at step 3, which is the balance one month’s interest is credited on. Zero outside cover.
- lca_pp(t)[source]#
LCA_{t+1}: the loan collateral account at the end of month t.
Standard loans move loaned value out of the fixed account and the segments into a collateral account credited at
loan_credit_rate_ann()while the loan itself accrues at the charged rate; the collateral remains part of the account value, so a loan advance does not reduceAV– it reduces the cash surrender value through- L_t. A closing balance; the opening value,lca_pp_init()in the first month on the books, islca_pp_at(t, BEF_PREM). Zero outside cover.
- loan_bal_pp(t)[source]#
L_{t+1}: the policy loan balance at the end of month t.
L_{t+1} = (L_t + B_t) (1 + i_L^c)^(1/12), the notes’ own recursion: new loans from step 3 are added to principal and the whole balance accrues at the charged rate. The opening balanceL_tis the previous month’s, and in the first month on the books,t_entry(),loan_bal_init(), the loan the point carries into the valuation month, 0 at issue. Repayments are not modeled – the notes give no repayment pattern. Zero outside cover.
- inv_income_pp(t)[source]#
Interest credited to the account value per policy at EOM of month t.
The post-sweep fixed-account balance at the fixed-account monthly rate plus the loan collateral account at the collateral credited rate. Segments contribute nothing: they earn no interim interest under a 0% floor design [S2], and their whole return arrives as
index_credit_pp()at maturity. Keeping the two apart is what stops the floor being confused with an in-segment guarantee, which the notes list among the pitfalls.
- inv_income(t)[source]#
Interest credited to account values, for the policies in force.
Decrements fall after the credit, so every policy in force at BOM earns a full month’s interest.
- av_pp_at(t, timing)[source]#
AV: the account value per policy at an intra-month point of month t.
The account value is the fixed account plus every live segment plus the loan collateral account;
timingnames the point just before each BOM event:BEF_PREMBefore the premium: the opening balance, the notes’
AV_t– the closing balance of the previous month, formed here from montht - 1’s own opening balance and events, the same operations in the same order asav_pp(), so that the chain is one cell a month. In the first month on the books,t_entry(), a point in force opens from its parts,fa_pp_init()pluslca_pp_init()plus the ladder’s balances,seg_bal_pp_init(), slot by slot, summed in the compensated loopseg_bal_active_pp()sums in, so that an extract carried to the cent opens one account, its parts’ sum, whichcheck_av_components()then holds; any other point opens fromav_pp_init(), 0 at issue. It is also defined in the month after the frame,t = proj_len(), where it is the account value the survivors of the last month carry, whichcheck_av_roll_fwd()reads. Zero before issue.BEF_CREDITAfter the net premium, before the maturing segment’s index credit. Zero outside cover, and so is every later timing.
BEF_WDAfter the index credit, before the withdrawal. The roll of the matured segment into the fixed account is internal and does not change this total.
BEF_FEEAfter the withdrawal, before the monthly deduction. This is the notes’
AV'_t, the balance the death benefit, the corridor test and the net amount at risk are all measured against. A new loan does not change it: the collateral moves within the account value.BEF_INVAfter the monthly deduction, before interest.
The end-of-month balance, the notes’
AV_{t+1}, isav_pp(), andcheck_av_components()asserts that it still equals the sum of its three parts.
- av_pp(t)[source]#
AV_{t+1}: the account value per policy at the end of month t.
A closing balance: the post-deduction balance plus one month’s interest. The opening balance,
av_pp_init()in the first month on the books, isav_pp_at(t, BEF_PREM), which forms this cell’s value att - 1itself. Interest is credited on the post-deduction balance, as on the universal life chassis; the index credit is not part of it – that arrives at BOM when a segment matures. Zero outside cover.
- av_at(t, timing)[source]#
Account value in force at an intra-month point of month t.
av_pp_at()times the number of policies in force, which is constant through the month because decrements are end-of-month events.timingtakes the same values asav_pp_at(), plusEOMfor the closing balance before decrements. Att = proj_len(),av_at(t, BEF_PREM)is the account value the survivors of the last month carry, whichcheck_av_roll_fwd()reads.
- av_change(t)[source]#
Change in the account value in force over month t.
av_at(t + 1, BEF_PREM) - av_at(t, BEF_PREM), followingCashValue_SE. Zero outside cover, beforet + 1is read, so that nothing reads a month pastt = proj_len(); there the change would otherwise be minus the account value the survivors of the last month carry.
- surr_charge_rate(t)[source]#
SC per $1,000 of initial face in month t [std] scale (F17).
max(0, sc_init - (sc_init / runoff_years) x m / 12)wheremis the notes’ own month indexduration_mth(t) + 1– the current month counts. With the shipped schedule of $25.00 per $1,000 running off over 10 years this is $24.79 in the issue month, declining linearly to zero in the last month of policy year 10. The ten-year period is sourced [S1][S5][S7]; the dollar scale is not public and is a placeholder of realistic magnitude. The schedule’s two values are read once a point bysurr_charge_rate_max()andsurr_charge_runoff_years(), which askDatato check the table first; the floor keepsIUL_US_S’s order,max(0.0, ...), the bound first. Zero outside cover, and where the point carries no schedule.
- surr_charge_pp(t)[source]#
SC_t: the surrender charge scheduled per policy in month t.
Quoted on the initial face amount, because face decreases do not reduce the surrender charge [S3]. This is the schedule, not the amount collected: see
surr_charge().
- csv_pp(t)[source]#
AV_t - SC_t, floored at zero: the cash value before the loan is netted.The floor is [std]: the notes write the cash surrender value without one, but a negative value would be a payment from the policyholder. In the early policy years the scheduled surrender charge exceeds the account value and the floor binds, so the charge actually collected is the whole account value.
The notes’ own
CSV_t– which already nets the loan – isncsv_pp().
- ncsv_pp(t)[source]#
CSV_t = AV_t - SC_t - L_t: the cash surrender value, floored at zero.
This is what a surrendering policyholder is paid, and the notes’ surrender outflow.
- surr_charge(t)[source]#
Surrender charge actually collected from the policies lapsing in month t.
(AV_t - csv_pp(t)) x pols_lapse(t), so it is capped by the account value where thecsv_pp()floor binds. Insurer income, and part ofmargin_expense().
- cum_prem_pp(t)[source]#
Cumulative premiums less withdrawals: the base of the GPT and 7-pay tests.
The value at the end of month
t, including montht’s own premium and withdrawal. It opens in the first month on the books,t_entry(), fromcum_prem_init(), the premiums less withdrawals paid before the valuation date on a point in force and 0 at issue, so the GPT and 7-pay flags of a point in force count every premium since issue.IUL_US_Sopens it at 0 on any point, the notes giving no opening accumulator [std]. The statutory “less a portion of withdrawals” is taken as the whole withdrawal [std]. Zero outside cover.
- cum_prem_net_pp(t)[source]#
CumP_{t+1}: cumulative premiums less withdrawals and loans, the no-lapse base.
The notes define the no-lapse accumulator this way and the guideline premium accumulator differently;
cum_prem_pp()is the other one. Using one for the other quietly changes both answers. The value at the end of montht, opening in the first month on the books,t_entry(), fromcum_prem_net_init(), the accumulator the point carries into the valuation month, 0 at issue.IUL_US_Sopens it at 0 on any point, which on a point in force would fail the no-lapse test against a minimum premium counted from issue. Zero outside cover.
- nlg_period_years()[source]#
The length of the no-lapse period in policy years, by issue age [S3] (spec F6).
0-45: 20 years; 46-60: to attained age 65; 61+: 5 years. Comparators differ – another carrier gives 20 years for issue ages 0-55,
75 - issue agefor 56-69, 5 years for 70+ [S5] – and the structure above [S3] is the one the baseline follows.
- mnlp_pp_mth()[source]#
The minimum monthly no-lapse premium per policy [S3].
mnlp_rate x F / 1000 / 12: the annual rate per $1,000 of face spread evenly over the year.
- cum_mnlp_pp(t)[source]#
CumMNLP_{t+1}: the cumulative minimum no-lapse premium through month t.
mnlp_pp_mth() x (duration_mth(t) + 1): a closed form on the policy clock, every month from issue counted, so a point in force needs no opening value for it. Zero outside cover.
- nlg_test_ok(t)[source]#
The cumulative-premium no-lapse test:
CumP_t >= CumMNLP_t[S3][S4].False outside cover.
- nlg_in_effect(t)[source]#
Whether the no-lapse guarantee is in effect: inside the period and test passing.
While it is, the policy cannot lapse for insufficiency even with no cash surrender value [S3][S4], which is why
lapse_rate()suppresses voluntary lapse in that state as well [std]. The period counts policy years, from issue. False outside cover, before the policy year is compared.
- nlg_expiry_shock(t)[source]#
Whether the 25% no-lapse-expiry shock lapse applies in month t [std].
The notes apply a 25% shock lapse to underfunded policies on no-lapse expiry; “underfunded” is taken as a non-positive cash surrender value [std], and the shock is confined to the first policy year after the no-lapse period ends. False outside cover, before the policy year is compared.
- is_shortfall(t)[source]#
The grace trigger: the cash surrender value cannot cover the monthly deduction.
AV'_t - SC_t - L_t < MD_t– withL_tthe loan balance at the start of the month, the previous month’sloan_bal_pp(), or, in the first month on the books,t_entry(),loan_bal_init()– and the no-lapse test fails [S3][S4]. A diagnostic. The grace and lapse-for-insufficiency cascade (61 days, modeled as lapse att + 2months if unfunded [std]) is not implemented: the notes leave the in-grace account value treatment and the cash flow of a cure payment undetermined, so no policy is terminated for insufficiency here. False outside cover.
- gpt_limit(t)[source]#
The guideline premium limit,
max(GSP, GLP x policy years elapsed)[R4].Zero outside cover, where the policy year is not the policy’s.
- gpt_ok(t)[source]#
Whether cumulative premium is still inside the guideline premium limit.
A compliance side-calculation with no cash flow of its own: a refused premium simply never enters the model. False outside cover.
- seven_pay_limit(t)[source]#
The 7-pay limit,
seven_pay_prem x min(7, policy years elapsed)[R5].Zero outside cover, where the policy year is not the policy’s.
- is_mec(t)[source]#
Whether the 7-pay test has failed by month t – once true, true for good [R5].
CumPrem(t) > 7-pay limitin any of the first seven policy years, latched: the flag stays set for the rest of the projection.IUL_US_S’s flag is the in-year test alone, which stops applying in policy year 8 and so would switch itself off exactly when the failure becomes permanent; under IRC 7702A a contract that fails the test is a modified endowment contract for good, so this model latches it, asUL_US_Sdoes.The in-year test comes first in every month, the first on the books included, so a policy that fails it in the valuation month is a MEC from then on. Only then does the latch look back: to month
t - 1, or, in the first month on the books,t_entry(), tois_mec_init(), so a policy that failed the test before the valuation date stays a MEC, even in a year where the in-year test no longer applies. False outside cover.A flag, not a cash flow: MEC status changes policyholder taxation, not insurer liability cash flows.
- class_factor()[source]#
The underwriting-class multiplier on the base mortality table [std].
Data.class_factorat the point: thefactorof the point’srate_classin class_factor_table.csv, joined once for the table afterdata.class_count()has checked its classes and factors, so that no projection cell reads the table or the class: a blank factor would otherwise reachmort_rate()as a missing value, which its cap keeps missing. A class the table has no row for is refused byData, naming every such point, at the first read, whereIUL_US_Sraises pandas’KeyErrorin every point’s first month in cover.
- mort_rate(t)[source]#
The annual best-estimate mortality rate in month t.
Base table times
class_factor()times the A/E factor, 100% in the base run [std] with no mortality improvement. The notes recommend 2015 VBT sex/smoker-distinct ANB validated against ILEC 2012-2019 [REG-R18][REG-R19]; those tables are licensed, so the shipped table is a small illustrative one [std]. Ages beyond the table take its last row, where the rate is 1.0; the base rate is read at the attained age of month t bymort_rate_base_at().The product is capped at 1, written
min(q, 1.0), asIUL_US_S’s is: a class factor above 1 carries the oldest ages’ rates past 1, where the monthly rate1 - (1 - q)^(1/12)has no real value, and with the bound second a missing input, a NaN, stays NaN, wheremin(1.0, q)would read it as 1. On every shipped point the product reaches 1.0, at attained age 119, and never passes it, so the cap changes no shipped number.Datarefuses a blank rate or class factor as it reads the tables (data.mort_age_last(),data.class_count()), before any rate is read. Zero outside cover, before the table is read.
- mort_rate_base_at(a)[source]#
The base table’s annual mortality rate at attained age a: the table’s one reader.
From mort_table.csv, before the class factor and the A/E factor:
Data.mort_table_array()at the age, the table padded from age 0, so that the age is the index. Ages outside the table take its nearest row, which above it is the rate of 1.0 at age 120: the first and last agesdata.mort_age_first()anddata.mort_age_last()give, which they read from the table’s key column once the keys and the rates are checked, before any rate is read, the last first, ascorridor_factor_at()asks, and which keep the read off the padding. Keyed by the attained age, so the table is read once an age rather than once a month;mort_rate()calls it inside cover only.
- lapse_rate_base(t)[source]#
The base annual lapse rate by policy year [std].
6% in policy years 1-10, 4% thereafter, read from lapse_table.csv at the policy year of month t by
lapse_rate_base_py(), where policy years beyond the table take its last row. The levels are placeholders to be calibrated to the LIMRA/SOA persistency studies [REG-R20][REG-R21], whose detailed tables are behind a paid package. Zero outside cover, before the table is read.
- lapse_rate_base_py(y)[source]#
The base annual lapse rate in policy year y, from lapse_table.csv: its one reader.
Data.lapse_rate_array()at the year, the table padded from year 0, so that the year is the index. Policy years beyond the table take its last row, the last yeardata.lapse_last_year()gives, which it reads from the table’s key column once it has checked the keys and the rates, before any rate is read, and a year below 1, whereIUL_US_S’s lookup raisedKeyError, is refused, naming the point and the year. Keyed by the contractual policy year, so the table is read once a policy year rather than once a month;lapse_rate_base()calls it inside cover only.
- lapse_shock_year()[source]#
The policy year of the surrender-charge-expiry lapse spike.
The first policy year with no surrender charge – the run-off length plus one, which is 11 for the shipped ten-year schedule – derived from the schedule’s
surr_charge_runoff_years()rather than hard-coded, so a different schedule moves the spike with it. Zero when the model point carries no surrender charge, which no policy year in cover can equal. The valuation clock reaches policy year 0 in the twelve months before issue, which is whylapse_rate_sc_mult()asksis_active()first.
- lapse_rate_sc_mult(t)[source]#
The surrender-charge-expiry spike multiplier, 2.0 in policy year 11 [std].
The ten-year surrender charge period [S1][S5][S7] creates a cliff in surrender economics; the size of the spike is a shape assumption, and UL lapse and surrender experience by duration is available in [REG-R21] for calibration. 1.0 outside cover, before the policy year is compared: in the twelve months before issue the valuation clock reaches policy year 0, the shock year
lapse_shock_year()gives a point with no surrender charge.
- cred_rate_ann(t)[source]#
r_cred,t: the policy’s trailing credited rate, driving dynamic lapse [std].
The credited rate of the segment that matured this month once the ladder is running, from policy month 12 on,
seg_credit_rate(), at the cap declared at its creation; and the fixed-account rate before that or when nothing is allocated to the indexed account. The notes say only “the policy’s trailing credited rate”; this is the reading the model uses. The ladder runs from the policy’s own twelfth month, so the test is on the policy clock,duration_mth(t), whereIUL_US_S’s comparestitself, its frame’s month, which is the same month only on a point issued at its frame’s start. A segment holding nothing still has a start level and a cap, so this reads them in every month the ladder runs. Zero outside cover.
- comp_rate_ann(t)[source]#
r_alt: the competitor / market alternative rate [std].
The base deterministic run sets it equal to the trailing credited rate, so
lapse_rate_dyn_mult()is exactly 1. Override this cell, before the model computes anything, to switch dynamic lapse on; that is a formula override, which only modelx can make. The rationale the notes give is real: caps are non-guaranteed elements and uncompetitive re-declarations – caps on one product fell from 13.75% to 12.00% between two print dates [S3][S4] – plausibly drive excess lapse.
- lapse_rate_dyn_mult(t)[source]#
The dynamic lapse multiplier [std].
min(2.0, max(0.5, 1 + 3.0 x (r_alt - r_cred,t))): a competitive credited rate halves lapse at the floor and an uncompetitive one doubles it at the cap. Equal to 1 throughout the base run. The bounds keepIUL_US_S’s order, written first. 1.0 outside cover, the neutral multiplier.
- lapse_rate(t)[source]#
The total annual lapse rate [std].
Base rate times the surrender-charge-expiry spike times the dynamic multiplier, with two no-lapse-guarantee overrides the notes specify:
while the guarantee is in effect and the cash surrender value is non-positive, lapse is suppressed – policyholders paying no-lapse-premium-level premiums persist;
in the first policy year after the no-lapse period ends, an underfunded policy takes a 25% shock lapse.
lapse_rate_capis 1.0: these notes give no cap, unlike the universal life chassis, so the Reference is present for symmetry and inert at its shipped value. The shock lapse is returned before the cap, asIUL_US_Sreturns it, so annlg_shock_lapsepast 1 is a rate past 1, whose monthly rate has no real value. Zero outside cover.
- pols_if(t)[source]#
l_t: the number of policies in force at the beginning of month t, row t’s weight.
pols_if_at(t, BEF_DECR), the notes’l_t: the count carried in from month t - 1 plus month t’s new business, before month t’s decrements. Decrements are end-of-month events, so the number in force is constant through the month and every BOM cash flow is weighted by it. On a point issued att = 0it is exactlyIUL_US_S’spols_if. A point in force at the valuation date opens withpols_if_init(), and one issued at or after it with its issued count in the issue month. Zero before issue. Att = proj_len(), the month after the frame, it is the survivors of the last month, which the roll-forwards read.It is
basiclife.BasicTerm_SE’sBEF_DECRcount, not itspols_if, which is the count before maturity.
- pols_if_at(t, timing)[source]#
Number of policies in force at a point of month t, by
timing.The three timings
IUL_US_S’s cell names:BEF_NBThe count carried in from month t - 1, before month t’s new business: month t - 1’s
BEF_DECRcount less its deaths and lapses, death applied before lapse, inIUL_US_S’s order. In the first month on the books,t_entry(), it ispols_if_init(), the count in force at the valuation date (0 for a point issued at or after it), and the recursion reads no earlier month. It is also defined in the month after the frame,t = proj_len(), where it is the survivors of the last month: the projection ends at an age horizon, not at an event of the contract, so they are kept rather than matured. Zero before issue.BEF_DECRl_t:BEF_NBpluspols_new_biz(), before any decrement; the same number aspols_if(), and the weight on that month’s cash flows.BEF_MATBefore any maturity:
IUL_US_S’s meaning, theBEF_DECRcount, which its cell gives for this timing. The contract has no maturity in the frame, so nothing matures and no event of the month separates the two.basiclife.BasicTerm_SE’sBEF_MAT, the count at the start of the month before its new business, is not adopted: the name keeps its S model’s meaning.
BEF_NBforms month t - 1’sBEF_DECRcount itself – its own value att - 1plus that month’spols_new_biz()– and takes its deaths and lapses from the month’s rates, aspols_death()andpols_lapse()do, rather than calling for any of them. So the chain of calls back tot_entry()is one cell a month, asIUL_US_S’spols_if()chain was: a compiled model runs that chain on the C stack.IUL_US_S’s cell returnspols_if()for every timing, which in the issue month counts the issued policies under all three; hereBEF_NBalone counts them as new business, not yet in. Any other timing raises.
- pols_new_biz(t)[source]#
Number of policies issued in month t:
policy_count()in the issue month.The issue month is the one with
duration_mth(t) == 0:t = 0for a point issued at the valuation date,t = kfor one issuedkmonths later. A point already in force at the valuation date has none.
- pols_death(t)[source]#
Number of deaths at the end of month t,
pols_if(t) x q^d_t.Zero outside cover, before any rate is read.
- pols_lapse(t)[source]#
Number of lapses at the end of month t.
pols_if(t) x (1 - q^d_t) x q^w_t: death is applied before lapse [std]. Zero outside cover, before any rate is read.
- pols_maturity(t)[source]#
Number of maturing policies: always zero.
At attained age 121 the policy is described as continuing in force with no further charges [unverified] (spec F5), so the projection horizon truncates the run rather than terminating the contract. The cell is kept so the in-force roll-forward identity has the same shape as in the term and annuity models of this library, where it is not zero. The survivors of the frame’s last month do not mature either: they are carried into
t = proj_len()(pols_if_at()).
- claim_pp(t, kind)[source]#
The claim amount per policy by
kind.DEATHDB_t - L_t, the death benefit less policy debt. The loan is taken at its end-of-month value because decrements follow the loan accrual, which is how these notes write it.LAPSECSV_t, the cash surrender value with the surrender charge and the loan already netted –ncsv_pp().WITHDRAWALW_t - $25 fee: the withdrawal is gross of the fee and the insurer keeps it. This kind survives here, thoughclaims()takes no kind, because the per-policy rule has to live somewhere;withdrawals()is its only caller.
- claims_from_av(t, kind)[source]#
The part of a claim released out of the account value, by
kind.Death and lapse both release the end-of-month account value
AV_t, because decrements follow the interest credit.MATURITYis zero: the contract does not mature within the projection.
- claims_over_av(t)[source]#
Death claims in excess of the account value released.
(claim_pp(t, DEATH) - AV_t) x pols_death(t). The cost of insurance charge net of this is the mortality margin.
- claims(t)[source]#
Claim outgo in month t: death and surrender claims together.
claims_death()andclaims_lapse(), summed left to right from0.0, the totalIUL_US_S’sclaims(t)computes with itskind=Nonedefault,sumover the two kinds: a fold of two terms from0.0is thatsum, the sign of a zero included, so the total isIUL_US_S’s bit for bit. Death claims are weighted bypols_death()and surrenders bypols_lapse(), both end-of-month events.WITHDRAWALis deliberately not in the total: a partial withdrawal is a payment on the owner’s election rather than a claim, so it is the standalone cellwithdrawals()and its ownresult_cf()column. Keeping it out of the total is what stops it being counted twice.
- claims_death(t)[source]#
Death claims in month t:
claim_pp()atDEATHtimespols_death().IUL_US_S’sclaims(t, "DEATH"), a cell of its own, so that each kind is a monthly cell with a C cache andclaims()their total. Theclaims_deathcolumn ofresult_cf().
- claims_lapse(t)[source]#
Surrender payments in month t:
claim_pp()atLAPSEtimespols_lapse().IUL_US_S’sclaims(t, "LAPSE"), a cell of its own, asclaims_death()is. Theclaims_lapsecolumn ofresult_cf().
- withdrawals(t)[source]#
Partial withdrawal payments in month t:
(W_t - $25 fee) x l_t.Weighted by
pols_if(), because a withdrawal is taken at BOM by policies still in force – it is not a decrement. The per-policy amount isclaim_pp(t, WITHDRAWAL), so the fee-inside-W_trule is stated once; the fee itself stays with the insurer aswd_fees().A withdrawal is not a claim, and this cell is why
claims(), the death and lapse claims, holds no withdrawal.
- wd_fees(t)[source]#
Withdrawal fees retained by the insurer, for the policies in force.
Taken out of the withdrawal, so this is the difference between what leaves the account value and what the policyholder receives; it appears in
margin_expense(), not inclaims().
- net_loan_cf(t)[source]#
Net loan cash flow in month t: advances out, repayments in.
A loan advance is cash the insurer pays out while the account value is unchanged – the collateral moves inside it – so it is a liability cash flow of its own. Repayments are not modeled: the notes give no repayment pattern.
- inflation_factor(t)[source]#
The expense inflation factor,
(1 + inflation_rate)^(t // 12).inflation_rateis 0 in the base run: these notes give per-policy maintenance and per-issue expenses as flat placeholders with no inflation assumption, unlike the universal life chassis. The cell is kept so the chassis’ shape survives and an inflation assumption can be switched on with one Reference. Switched on, it steps by year on the valuation clock: the years are counted from the valuation date,t // 12, so the expense is in valuation-date dollars whatever the policy’s age, and every point of a block steps alike, on the valuation date’s anniversaries.IUL_US_Ssteps on the policy year,(1 + inflation_rate)^(y - 1); on a point issued att = 0the two are the same. A function of the clock alone, so it holds its value outside cover. Acquisition is not inflated (seeexpenses()).
- expenses(t)[source]#
E_t: the insurer’s own expenses in month t [std].
$75a policy a year spread monthly, plus$150at issue. Placeholders: the notes have no public source for insurer expenses and say to calibrate to company studies.IUL_US_S’s formula in its order, on the policies in force at the start of the month: in the issue month those are the policies issued,pols_new_biz(), since a point issued at or after the valuation date opens with none, so acquisition is charged per policy issued, as inbasiclife.BasicTerm_SE, and a point in force never bears it. On a point issued att = 0this isIUL_US_S’s charge bit for bit.Not to be confused with
maint_fee(), which is the charge against the account value – income, not outgo. Zero outside cover, where the count carried intot = proj_len()would otherwise bear a maintenance expense.
Premium tax, 2.0% of premium [std] placeholder.
- margin_expense(t)[source]#
Expense margin: the charges the insurer keeps, net of its own outgo.
load x P + withdrawal fees + maint_fee + surrender charges - expenses - premium taxes. FollowsCashValue_SE.margin_expense; seecheck_margin()for the identity it takes part in.
- margin_mortality(t)[source]#
Mortality margin:
coi()net ofclaims_over_av().
- net_cf(t)[source]#
CF_t: the net liability cash flow in month t, undiscounted.
premiums - claims - withdrawals - expenses - premium taxes + net loan cash flows, which is the notes’ own sign convention (inflow positive) and the library-wide one.claims()is the death and surrender legs only, sowithdrawals()is a term of its own here rather than part of the claim total. Policy charges – the premium load, the monthly deduction, the surrender charge, the withdrawal fee – are internal transfers within the account value, not cash flows; they emerge in profit as the margins. Index credits and fixed-account interest are credits to the policyholder, not insurer cash flows, so they do not appear either – seecheck_margin()for how it all reconciles. Zero outside cover.
- check_av_components()[source]#
Check that the account value is still the sum of its three parts.
Returns
Truewhen, for every month of the frame,av_pp(t) == fa_pp(t) + seg_bal_tot_pp(t) + lca_pp(t)to within1e-9, relative to the larger side and 10, which is whatIUL_US_S’smath.isclosetests with its tolerances,rel_tol=1e-9andabs_tol=1e-8.av_pp()is built from the notes’ aggregate recursion while the fixed account, the segment ladder and the loan collateral account are each built from their own; this is the test that the two constructions have not drifted, and it is the strongest single check on the segment bookkeeping. On a point in force the three parts open from their own columns and the account value from their sum, so an extract carried to the cent holds it too, andDataholds theav_pp_initcolumn to the same sum. Each month’s residual ischeck_av_components_resid(), so a failure can be found by month; a residual that is not a number fails, and one that is not real raises, asIUL_US_S’s check does.
- check_av_components_resid(t)[source]#
The account value components’ relative residual in month t; zero everywhere.
av_pp(t)less the sum of the fixed account, the live segments and the loan collateral at the end of month t, over the larger of the two in magnitude and 10: one number a month, whose magnitude is within1e-9exactly wheremath.isclosewithrel_tol=1e-9andabs_tol=1e-8holds,IUL_US_S’s test. Returned as afloat, so that a value that is not real raises here, asIUL_US_S’smath.iscloseraises on it. Zero outside cover.
- check_av_roll_fwd()[source]#
Check the account value roll-forward.
Returns
Truewhen, for every month of the frame, the opening account value in force of montht + 1equals:av_at(t, BEF_PREM) + prem_to_av(t) + index_credits(t) - withdrawals(t) - wd_fees(t) - mth_deduction(t) + inv_income(t) - claims_from_av(t, DEATH) - claims_from_av(t, LAPSE)
to within
1e-9, relative to the larger of the two and 10, as forcheck_av_components(). This pins the notes’ processing order: the index credit arrives at BOM when a segment matures, interest is credited on the post-deduction balance, decrements come after both, and the withdrawal fee leaves the account value alongside the withdrawal itself. Each month’s residual ischeck_av_roll_fwd_resid(); a residual that is not a number fails, and one that is not real raises, asIUL_US_S’s check does. In the last month the opening value oft + 1is the account value the survivors carry intot = proj_len().
- check_av_roll_fwd_resid(t)[source]#
The account value roll-forward’s relative residual in month t; zero everywhere.
The opening account value in force of month
t + 1less the roll-forward of month t thatcheck_av_roll_fwd()sets out, over the larger of the two in magnitude and 10, and afloat, ascheck_av_components_resid()is: a monthly rate built from an annual one past 1,1 - (1 - q)^(1/12), is complex, and so is every count after it, and a complex residual’s magnitude would pass. Zero outside cover, beforet + 1is read, so that nothing reads a month pastt = proj_len().
- check_seg_ladder()[source]#
Check the segment ladder bookkeeping.
Returns
Truewhen, for every month of the frame, all four of the following hold:at most
seg_term_mthsegments are live (check_seg_count_resid());every segment that matured accounted for its creation balance exactly,
seg_new_pp(m) == seg_bal_pp(t - 1, 11) + deductions + withdrawals– nothing may appear in or vanish from a segment except a deduction, a withdrawal or a loan transfer, because segments earn no interim interest (check_seg_closure_resid());every live segment balance is non-negative, to within
1e-8(check_seg_bal_resid());every index credit is non-negative, to within
1e-8(check_seg_credit_resid()).
The last two are the 0% floor of
cr_k = max(f, min(c, p x r))[S2][R1] stated as an invariant. The accounting identity above closes even on a negative balance, andseg_count()counts only positive ones, so without these two an over-sourced draw could take a segment below zero and pay a negative credit on it at maturity without any check firing – seemth_deduction_from_seg_pp().IUL_US_S’s tests and tolerances, each month’s read from a residual cell; a residual that is not a number fails each test. A segment born before the valuation date that matures in month 0 closes on its creation balance by construction, since that balance is its ladder row summed (seg_new_pp()).
- check_seg_count_resid(t)[source]#
The live segments beyond
seg_term_mthat the end of month t: zero or below.seg_count(t) - seg_term_mthas afloat, whichcheck_seg_ladder()holds to 0 or below,IUL_US_S’sseg_count(t) <= seg_term_mth. Zero outside cover.
- check_seg_credit_resid(t)[source]#
The index credit of month t per policy, held by the ladder check to -1e-8 or more.
index_credit_pp(), whichcheck_seg_ladder()holds to-1e-8or more,IUL_US_S’s tolerance. Zero outside cover, where no segment matures.
- check_seg_bal_resid(t)[source]#
The least live segment balance at the end of month t, or 0 where none is below.
The smallest of 0 and the balances of the segments born in policy months
max(0, duration_mth(t) - 11)toduration_mth(t), each read at its slot, whichcheck_seg_ladder()holds to-1e-8or more,IUL_US_S’s test of each balance. A balance that is not a number, once met, is kept, so that the residual is not a number and the check fails, asIUL_US_S’s does. Zero outside cover.
- check_seg_closure_resid(t)[source]#
The closure’s relative residual for the segment maturing in month t; zero.
The creation balance of the segment born in policy month
duration_mth(t) - 12,seg_new_pp(), less its balance at the end of montht - 1, in slot 11, plus the deductions and the draws charged to it, over the larger of the two in magnitude and 10, afloat, ascheck_av_components_resid()is:math.isclosewithIUL_US_S’s tolerances. In the first month on the books,t_entry(), a segment born before the valuation date is ladder slot 12, read from its row. Zero where nothing matures and outside cover.
- check_margin()[source]#
Check the net cash flow against the expense and mortality margins.
Returns
Truewhen, for every month of the frame:net_cf(t) == margin_expense(t) + margin_mortality(t) + av_change(t) - inv_income(t) - index_credits(t) + min(loan_bal_pp(t), csv_pp(t)) * pols_lapse(t) + net_loan_cf(t)
to within
1e-9, relative to the larger side and 10, as forcheck_av_components(); each month’s residual ischeck_margin_resid(), and a residual that is not a number fails. The terms after the two margins are what separates a gross liability cash flow model fromCashValue_SE, whosenet_cfalready nets the change in account value and the investment income.index_creditsjoinsinv_incomebecause the indexed account’s whole return arrives at maturity rather than monthly; the loan terms are the debt a surrender recovers out of the cash value, which is the whole loan while the cash value covers it and the cash value once the loan exceeds it, wherencsv_pp()pays nothing, and the advance itself.IUL_US_S’s identity takes the whole loan in every month, which holds while neither thecsv_pp()nor thencsv_pp()floor binds against a policy loan, so its check fails on its point 5, whose loan overruns the cash value from policy month 383, on a projection that is right; this model states the identity asUL_US_SEC,VUL_US_SECandULSG_US_SECdo, and on every point whose loan stays within its cash value the two agree.
- check_margin_resid(t)[source]#
The margin identity’s relative residual in month t; zero everywhere.
net_cf(t)less the two margins, the change in account value, the interest and the index credits, the loan a surrender recovers and the net loan cash flow, thatcheck_margin()sets out, over the larger of the two sides in magnitude and 10, afloat, ascheck_av_components_resid()is. Zero outside cover, beforeav_change()would readt + 1.
- result_cf()[source]#
Result table of cashflows, a DataFrame indexed by month
t.One row per month
t = 0 .. proj_len() - 1from the valuation date, the same month for every model point, so the frames of a block line up and sum row by row, and a point issued after the valuation date has zeros until its issue month;len(result_cf()) == proj_len(). The columns areIUL_US_S’s.pols_ifis the number in force at the start of monthtand is the weight on that same row’s cash flows. The cash flow columns are income-positive and sum tonet_cf:premiums - claims_death - claims_lapse - withdrawals - expenses - premium_taxes + net_loan_cf. The surrender column isclaims_lapse, matching theLAPSEkind that produces it, and withdrawals are their own column because they are not claims.
- result_pols()[source]#
Result table of policy counts and decrement rates, a DataFrame indexed by
t.One row per month
t = 0 .. proj_len() - 1, as inresult_cf(). First the countsresult_cf()weights its rows by, and how they move, asbasiclife.BasicTerm_SE’sresult_polssets them out:pols_if, the count of month t;pols_new_biz, the part of it issued in month t; then month t’s deaths and lapses, inIUL_US_S’s order, and its maturities, which are always zero. Row by row,pols_ifatt + 1ispols_ifless the two outflows of month t, plus the new business of montht + 1. ThenIUL_US_S’s two monthly decrement rates, which are 0 outside cover, where the model reads no rate.
- result_av()[source]#
Result table of the per-policy account value roll-forward.
The columns follow the notes’ processing order: opening account value, net premium, the index credit of any maturing segment, the account value before the deduction, the death benefit, the net amount at risk, the cost of insurance, the monthly deduction, the post-deduction balance, the interest credited, the closing account value, and then the surrender and loan values. One row per month
t = 0 .. proj_len() - 1from the valuation date, as inresult_cf();av_pp_bef_premon rowtis the opening balance andav_ppthe closing one.
- result_seg()[source]#
Result table of the indexed segment ladder, a DataFrame indexed by
t.The index level, the fixed (holding) account, the sweep that creates this month’s segment, the total and count of live segments, the credit paid by the segment maturing this month and the return that produced it (0 in a policy’s first twelve policy months, when nothing can mature yet). One row per month
t = 0 .. proj_len() - 1from the valuation date, as inresult_cf(). The index level is the path on the valuation clock,index_level(), which on a point in force differs fromIUL_US_S’s by a constant factor; every other column is a ratio of levels or an amount, and moves with the segments, not with the path.