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:

  1. 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.

  2. 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].

  3. 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 into lca_pp().

  4. Death benefit and corridor on the post-premium, post-withdrawal account value (db_pp()).

  5. 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.

  6. 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()).

  7. Sweep. w_ix times the remaining fixed-account balance creates the new segment of this month (sweep_pp(), seg_new_pp()).

  8. 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()).

  9. 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 t argument)

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, duration(t) + 1

(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 k argument)

Slot, a segment’s months since creation: in month t, or at the valuation date in the ladder’s _init cells

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

pols_if_at(): the count carried in from month t - 1

BEF_DECR

1

pols_if_at(): that count plus month t’s new business

BEF_MAT

2

pols_if_at(): before any maturity, the BEF_DECR count

BEF_PREM

3

the accounts: the value carried in, before the premium

BEF_CREDIT

4

fa_pp_at(), av_pp_at(), av_at(): after the net premium, before the maturing segment’s credit

BEF_WD

5

fa_pp_at(), av_pp_at(), av_at(): after the credit, before the withdrawal and the loan

BEF_FEE

6

fa_pp_at(), av_pp_at(), av_at(): after the draws, before the monthly deduction

BEF_SWEEP

7

fa_pp_at(): after the deduction, before the sweep

BEF_INV

8

the accounts: after the deduction and the sweep, before interest

EOM

9

av_at(): after interest, before decrements

DEATH

0

claim_pp(), claims_from_av(): the death claim

LAPSE

1

claim_pp(), claims_from_av(): the surrender claim

MATURITY

2

claims_from_av(): none, the contract never matures

WITHDRAWAL

3

claim_pp(): the withdrawal, which is no claim

CURRENT

0

basis: the current, non-guaranteed scales

GUARANTEED

1

basis: the contractual guarantees alone

REMAINING

0

seg_credit_base_conv: the credit on the remaining balance

ADJ_BEGIN

1

seg_credit_base_conv: the adjusted beginning value, deductions half-weighted

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 idx of 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 own Data vector instead.

point_id()[source]#

The label of the selected model point, its point_id, from Data.point_id.

Projection is indexed by position, idx, as basiclife.BasicTerm_SC is; 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(). Data holds it to a whole number, 0 or more, and proj_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): Data joins the COI scale by it, through Data.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): Data joins the COI scale and the class factor by it, through Data.coi_schedule and Data.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 is sum_assured_init(), and the face in force in month t is sum_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() and is_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_a at the point: db_option is "A", the decode of the model point’s column Data makes once for the table, compared exactly, as IUL_US_S compares it, so that no monthly cell branches on text; db_pp() and face_reduction_pp() read this instead. The label accessor db_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_b at the point: db_option is "B", read by db_pp(), which raises on a point that is neither A nor B, as IUL_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 reads is_gpt(), Data’s decode of the column. Returned as read.

is_gpt()[source]#

Whether the point elected the Guideline Premium Test: qual_test is "GPT".

Data.is_gpt at the point, the decode of the model point’s qual_test column, read by corridor_factor(), which raises on any other test, as IUL_US_S’s does: CVAT is documented as a variation, out of the baseline.

premium_type()[source]#

The premium pattern: "LEVEL", "SINGLE" or "TARGET" [std].

A reporting cell (the Space docstring): the projection reads is_level_premium(), is_single_premium() and is_target_premium(), Data’s decodes of the column. Returned as read.

is_level_premium()[source]#

Whether the premium pattern is LEVEL: premium_type is "LEVEL".

Data.is_level_premium at the point: one of the three decodes of the model point’s premium_type column that premium_pp() branches on, each made once for the table by Data, so that no monthly cell compares text; premium_pp() raises on a point that is none of the three, as IUL_US_S’s does. The label accessor premium_type() is kept as it is, for reporting, and no projection cell calls it.

is_single_premium()[source]#

Whether the premium pattern is SINGLE: premium_type is "SINGLE".

Data.is_single_premium at the point, a decode of the model point’s premium_type column, read by premium_pp().

is_target_premium()[source]#

Whether the premium pattern is TARGET: premium_type is "TARGET".

Data.is_target_premium at the point, a decode of the model point’s premium_type column, read by premium_pp(), whose TARGET premium is capped inside the guideline premium limit.

premium_mode()[source]#

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 reads is_annual_premium() and is_monthly_premium(), Data’s decodes of the column. Returned as read.

is_annual_premium()[source]#

Whether premiums are paid annually: premium_mode is "ANNUAL".

Data.is_annual_premium at the point: one of the two decodes of the model point’s premium_mode column that premium_pp() branches on, made once for the table by Data, so that no monthly cell compares text; premium_pp() raises on a point that is neither, as IUL_US_S’s does. The label accessor premium_mode() is kept as it is, for reporting, and no projection cell calls it.

is_monthly_premium()[source]#

Whether premiums are paid monthly: premium_mode is "MONTHLY".

Data.is_monthly_premium at the point, a decode of the model point’s premium_mode column, read by premium_pp().

premium_pp_ann()[source]#

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_init column, IUL_US_S’s own: the balance at the close of policy month duration_mth_init() - 1, before any month-0 event, which is what IUL_US_S carries into the month as av_pp_at(d, BEF_PREM) at d = duration_mth_init(). It opens the account value chain at t_entry() on a point issued at or after the valuation date, 0 there. A point in force opens the chain from its parts instead, which Data holds this column to, so that an extract whose amounts are carried to the cent opens one account (see av_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 and lca_pp_init() – where IUL_US_S places the whole opening balance less the loan in the fixed account and starts with no live segment. Data holds this column to their sum, to the cent. It may be negative: IUL_US_S lapses 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_init column, IUL_US_S’s own: the debt at the close of policy month duration_mth_init() - 1, interest accrued to then included, before any month-0 event; the opening balance of loan_bal_pp() at t_entry(), and the loan month 0’s shortfall test nets. Zero for a point not yet in force. IUL_US_S also 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_init column: the fixed account at the close of policy month duration_mth_init() - 1, before any month-0 event, which is what IUL_US_S carries into the month as fa_pp_at(d, BEF_PREM). It is the opening balance of fa_pp_at() at t_entry(). IUL_US_S opens 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_S lapses 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. Data holds it, with the collateral and the segments, to av_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_init column: the collateral at the close of policy month duration_mth_init() - 1, before any month-0 event, which is what IUL_US_S carries into the month as lca_pp_at(d, BEF_PREM). It is the opening balance of lca_pp_at() at t_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, and IUL_US_S takes 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. Data refuses 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_init column: the face in force at the close of policy month duration_mth_init() - 1, after every Option A withdrawal cut to date, which is the face IUL_US_S carries into the month as sum_assured_at(d - 1). It is the base of sum_assured_at() at t_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, and Data refuses 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, as IUL_US_S carries it. Zero for a point not yet in force, which is issued at sum_assured(). IUL_US_S opens 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_init column: every gross premium premium_pp() collected from issue through policy month duration_mth_init() - 1, less every withdrawal wd_pp() paid, which is what IUL_US_S carries into the month as cum_prem_pp(d - 1). cum_prem_pp() opens from it at t_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_S opens 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_init column, the no-lapse guarantee’s accumulator: every gross premium collected from issue through policy month duration_mth_init() - 1, less every withdrawal and every new loan, which is what IUL_US_S carries into the month as cum_prem_net_pp(d - 1). cum_prem_net_pp() opens from it at t_entry(), so the no-lapse test of month 0 compares every premium since issue with the cumulative minimum no-lapse premium since issue, which cum_mnlp_pp() counts on the policy clock. Opened at 0, as IUL_US_S opens 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; Data holds it to at most cum_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_init column, 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 at t_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 before duration_mth_init(). Data refuses a 0 where cum_prem_init already 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_init at this point and slot k, the seg_bal_pp_init column of inforce_segments_sec.csv: k is the months since the segment’s creation at the valuation date, and the value is the balance at the close of policy month duration_mth_init() - 1 of the segment born in policy month duration_mth_init() - k, which is what IUL_US_S carries into the month as seg_bal_pp(d - 1, d - k). seg_bal_pp() opens each live segment from it at t_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 at t = 0, is what month 0’s maturity rolls into the fixed account (seg_roll_pp()). Data holds it to -1e-8 or more, the tolerance check_seg_ladder() holds a live balance to, and proj_len() refuses a point whose ladder does not hold exactly slots 1 to min(12, duration_mth_init()). Read only on a point in force, at 1 <= k <= 12. Like the other four readers of the ladder, it asks proj_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 stage E’s .loc raised pandas’ KeyError, so that no read meets Data’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_init at the point and slot k, the seg_ded_cum_pp_init column of inforce_segments_sec.csv: every monthly deduction the segment born in policy month duration_mth_init() - k has borne since its creation, through the close of policy month duration_mth_init() - 1, which is IUL_US_S’s seg_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 at t_entry(), and in slot 12 index_credit_pp() reads it at t = 0, where the credit base convention ADJ_BEGIN half-weights it. Read only on a point in force, at 1 <= k <= 12, after proj_len(), and refused, as seg_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_init at the point and slot k, the seg_wd_cum_pp_init column of inforce_segments_sec.csv: every withdrawal and loan transfer the segment born in policy month duration_mth_init() - k has paid since its creation, through the close of policy month duration_mth_init() - 1, which is IUL_US_S’s seg_wd_cum_pp(d - 1, d - k). seg_wd_cum_pp() opens from it at t_entry(), and in slot 12 index_credit_pp() reads it at t = 0. Read only on a point in force, at 1 <= k <= 12, after proj_len(), and refused, as seg_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_init at the point and slot k, the seg_index_start_init column of inforce_segments_sec.csv: the index level the segment born in policy month duration_mth_init() - k started from, on this model’s path, the valuation clock’s, whose level at the valuation date is index_level_init: IUL_US_S’s level at the segment’s creation month times index_level_init over its level at month duration_mth_init(). So the segment’s return at maturity, a ratio of two levels, is IUL_US_S’s. Read for the segment maturing in month t < 12 by seg_index_start(), and only on a point in force, at 1 <= k <= 12, after proj_len(); Data holds it above 0, since the return divides by it, and it is refused, as seg_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_init at the point and slot k, the seg_index_cap_init column of inforce_segments_sec.csv: the cap in force when the segment born in policy month duration_mth_init() - k was created, which its credit at maturity is capped at, the cap being re-declared at every segment start [S3][S4]. IUL_US_S holds the cap level, so every segment carries index_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 month t < 12 by seg_index_cap(), and only on a point in force, at 1 <= k <= 12, after proj_len(); Data holds it to 0 or more, and it is refused, as seg_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_count column.

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, as pols_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 at t = 0 (duration_mth_init() > 0), and 0 for one issued at or after it, whose policies enter through pols_new_biz() in the issue month instead, as in basiclife.BasicTerm_SE. So on a point issued at t = 0 this is 0, and pols_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_mth column.

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, which Data admits up to future_horizon_mth months ahead. This is the notes’ issue-date / duration offset attribute, an elapsed count and therefore already 0-based, and IUL_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_charge at the point: its has_surr_charge column, which Data holds 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): Data joins the schedule by it, through Data.surr_charge_rate_max and Data.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_max at the point: the sc_per_1000_init column of the point’s row of surr_charge_table.csv, $25.00 on the shipped IUL10 schedule; surr_charge_rate() runs it off from here. Data joins the schedule to the points by surr_charge_id once 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 that has_surr_charge() names an id the table lacks, which IUL_US_S’s .loc met in every month of its cover. surr_charge_rate() reads it only where has_surr_charge() is true, but a point without a charge reads its schedule too, as at stage E, where the table holds its id; where it does not, Data.has_surr_charge_schedule is 0, and this raises ValueError, naming the point, where stage E’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_years at the point: the runoff_years column of the point’s row of surr_charge_table.csv, 10 on the shipped IUL10 schedule, read as a float, as IUL_US_S reads it, and joined, checked and refused as surr_charge_rate_max() is. Data holds it to a whole number of years, 1 or more, so that the division in surr_charge_rate() never meets 0 and lapse_shock_year()’s int() of it changes nothing, and to below 2**53 years on a point with a charge, where that int() 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_pp column, 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 that wd_pp(), a monthly cell on the accounts’ chains, reads no model point column in its own formula. Data holds it to 0 or more, and proj_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_ann column, 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 that loan_new_pp(), a monthly cell on the accounts’ and the loan’s chains, reads no model point column in its own formula. Data holds 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.

glp()[source]#

The guideline level premium (GPT compliance input) [std] placeholder.

seven_pay_prem()[source]#

The 7-pay premium (IRC 7702A compliance input) [std] placeholder [R5].

duration_mth(t)[source]#

Completed policy months at the beginning of month t, the policy clock.

duration_mth_init() + t: t counts months from the valuation date and duration_mth(t) months from issue, and the two move together. A closed form, where basiclife.BasicTerm_SE adds 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 = 0 for a point issued at the valuation date – and negative before issue. Anniversary events test duration_mth(t) % 12 == 0, and a segment’s creation month, the m of seg_new_pp(), is a value of it, its slot in month t, the k of seg_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 is IUL_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 (see pols_if_at()). Premiums and charges cease at charges_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 is t = 0, 1, ..., proj_len() - 1; proj_len() is its exclusive end, the row count of every result table, and proj_len() - 1 is 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 into t = proj_len() are kept (see maturity_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 that IUL_US_S’s own account value roll-forward and margin identity fail on such a point; one in force whose segment ladder in inforce_segments_sec.csv does not hold exactly one row for each of its last min(seg_term_mth, duration_mth_init()) months, slots 1 to that, a segment a month however little it was swept; and one issued below issue_age_min, 0, or above issue_age_max, 85, the issue ages product-spec.md admits. IUL_US_S projects 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; Data refuses 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 stage E, so that every message stage E gave 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, where Data checks the tables. The ladder’s counts are compared as Data elements, 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, k for one issued k months 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 before t = 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 from t = 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 into t = proj_len(), which the roll-forwards read (see pols_if_at() and av_pp_at()).

is_guaranteed_basis()[source]#

Whether the run uses class (a) contractual guarantees only.

basis is CURRENT in the base run, so the current non-guaranteed scales apply. Setting it to GUARANTEED switches 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. basis holds a code, as IUL_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_rate at 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 t on 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) - 1 at 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.

loan_credit_rate_mth(t)[source]#

The monthly loan collateral credited rate, (1 + i_L^e)^(1/12) - 1.

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 t on the valuation clock, the cap declared then: a segment created in month t is capped at index_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_ann a year along the valuation clock: index_level_init * (1 + index_return_ann)^(t / 12), so index_level_init is 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_S reads the path at duration_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_init must 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, and seg_return() computes the same ratio for the segment maturing in month t.

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]. cap defaults to the cap in force at t = 0, IUL_US_S’s engine, kept unchanged for its worked example – pass index_cap_guar for 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 with IUL_US_S: no projection cell calls it, and seg_credit_rate() computes the same rate, in the same order of bounds, for the segment maturing in month t, 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 baseline

seg_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 variation

seg_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]. Pass seg_bal_init already net of withdrawals and loan transfers, as index_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_conv is the Reference that records the choice, a code (the Space docstring’s Codes), which conv defaults to. An engine cell, kept for IUL_US_S’s worked example and for the comparison with it: no projection cell calls it, and index_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() times seg_credit_base(). An engine cell, kept for IUL_US_S’s worked example, which prices one segment’s credit at both caps through it, and for the comparison with IUL_US_S, whose projection calls it: no projection cell here calls it, and index_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 for IUL_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.

premium_pp(t)[source]#

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 / 12 times prem_persistency(), as on points 4, 7 and 12.

LEVEL

The planned premium times prem_persistency(), in either mode.

SINGLE

One premium in the issue month, capped at the guideline single premium.

TARGET

As LEVEL but 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() and is_monthly_premium(), not as text; a value none of them knows raises, as IUL_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).

prem_to_av(t)[source]#

Net premium credited to account values, for the policies in force.

premiums(t)[source]#

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’s wd_pp column, 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 receives W_t - 25 and 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 as W_t - $25 fee, so the fee is inside W_t here. Zero from attained age charges_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 of claims(). It is not an extra debit to the account value: it comes out of W_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’s loan_new_pp_ann, at each policy anniversary from the first month of policy year loan_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 t is 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 other qual_test raises 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 ages data.corridor_age_first() and data.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: Data refuses 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) where option_db is the face amount under Option A and face plus account value under Option B, and AV'_t is 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’s AV'_t below zero leaves the corridor’s amount at 0 or below, and the face wins, which Data keeps so by refusing a corridor factor below 0. The option is read through its decodes, is_db_option_a() and is_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_schedule at the point: the schedules of coi_rates.csv, one for each sex, rate_class and age_at_entry it holds, numbered from 1 in the order of those keys, and 0 where the table has no scale for the point’s own, which coi_rate_last_year() refuses where a rate is read. It stands for IUL_US_S’s coi_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’s coi_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, where IUL_US_S’s slice raised KeyError, 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_years at this point’s coi_schedule(), the last year of its scale, which Data reads 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, where IUL_US_S raises pandas’ KeyError: when its first COI rate is read, and not before, since a point valued at or past charges_cease_age never reads one, and IUL_US_S projects it. Stage E’s message quoted the point’s sex and rate_class too, which a projection formula cannot read here: each is a label, a reporting cell’s. The element is compared, and int of 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 with CashValue_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.

coi(t)[source]#

Cost of insurance charges deducted from account values, for the policies in force.

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 follows CashValue_SE.maint_fee: this is a charge against the account value and therefore insurer income. It is not expenses(), which is the insurer’s own outgo. Zero from attained age charges_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() plus coi_pp(), taken at BOM. The deduction at the start of month t pays for month t’s coverage.

mth_deduction(t)[source]#

Monthly deductions taken from account values, for the policies in force.

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 pool draw_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 of cr_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 charge MD_t in 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) - 11 to duration_mth(t) - 1, valued at the end of month t - 1, where each sat in slot duration_mth(t) - 1 - m. The segment born at duration_mth(t) - 12 is 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’s sum() 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 is IUL_US_S’s sum() bit for bit there, a segment closing on a rounding about zero included, which seg_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’s sum() is a plain fold, which can put such a pool on the other side of zero. Zero outside cover.

seg_share(t, k)[source]#

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. k is the segment’s slot in month t, its months since creation, duration_mth(t) - m for the segment born in policy month m. The opening balance is the segment’s at the end of month t - 1, where it sat in slot k - 1, or, in the first month on the books, t_entry(), the ladder’s seg_bal_pp_init() at slot k, read only for a slot the ladder holds, 1 to min(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, as IUL_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.

m is a policy month, duration_mth of 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 month m - duration_mth_init(), as in IUL_US_S. Born before the valuation date, it is in ladder slot k = 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 closure check_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 in IUL_US_S, where the six cells of a segment in a month are keyed by its slot: one value a segment, which seg_bal_pp() reads in slot 0 and index_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 month t is the notes’ S_{k,t+1}. k is the segment’s slot, its months since creation in month t, duration_mth(t) - m for the segment born in policy month m: 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 slot k - 1 at t - 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 at m is live through the end of policy month m + 11 and matures at step 2 of policy month m + 12, before that month’s deduction – so it bears eleven in-segment deductions. The worked example stipulates twelve; see products/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_S keys 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 - 1 at t - 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 - 1 at t - 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) to duration_mth(t), each read at its slot, duration_mth(t) - m, summed in IUL_US_S’s order in the compensated loop seg_bal_active_pp() sums in, so that the total is IUL_US_S’s sum() 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 with index_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 t was born twelve months earlier. Born in the frame, at month t - 12, it started from index_level(t - 12); born before the valuation date, in ladder slot 12 - t, from the start level its ladder row carries, seg_index_start_init(), on the same path. IUL_US_S reads index_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 slot 12 - 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_S holds the cap level and its engine reads index_cap_at(0), the cap in force at its own t = 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, where IUL_US_S leaves 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 floor index_floor, the cap declared at the segment’s creation, seg_index_cap(), and the participation index_par on its own return, seg_return(), bounded in IUL_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: min and max keep 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, and cred_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) - 12 matures now: its credit is IUL_US_S’s index_credit of its creation balance net of withdrawals and loan transfers, the deductions charged to it, its own point-to-point return, the credit base convention seg_credit_base_conv and the cap declared at its creation, inlined (R14): the credited rate, seg_credit_rate(), first, then the base, the remaining balance under REMAINING and the deductions half-weighted under ADJ_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 month t - 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.

index_credits(t)[source]#

Index credits added to account values, for the policies in force.

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, with timing naming the point just before each event:

BEF_PREM

The opening balance, the notes’ FA_t: the closing balance of the previous month, formed here from month t - 1’s own opening balance and events, the same operations in the same order as fa_pp(), so that the chain back to the first month on the books is one cell a month. In that month, t_entry(), it is fa_pp_init(), the fixed account the point carries into the valuation month, 0 at issue (FA(0) = 0). IUL_US_S opens an in-force point at the account value less the loan here, everything outside the collateral in the fixed account. Zero outside cover.

BEF_CREDIT

After the net premium, before the maturing segment rolls in.

BEF_WD

After the roll, before the withdrawal and any new loan collateral.

BEF_FEE

After the draw, before the monthly deduction.

BEF_SWEEP

After the deduction, before the sweep. This is the balance the sweep takes w_ix of.

BEF_INV

After 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, is fa_pp_at(t, BEF_PREM), which forms this cell’s value at t - 1 itself 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_PREM is the opening balance, the notes’ LCA_t: the closing balance of the previous month, formed here from month t - 1’s own opening balance and new loan, the same operations in the same order as lca_pp(), so that the chain is one cell a month; in the first month on the books, t_entry(), it is lca_pp_init(), the collateral the point carries into the valuation month, 0 at issue. IUL_US_S sets LCA(0) equal to loan_bal_init() [std], which the collateral parts from once interest accrues. BEF_INV adds 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 reduce AV – 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, is lca_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 balance L_t is 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; timing names the point just before each BOM event:

BEF_PREM

Before the premium: the opening balance, the notes’ AV_t – the closing balance of the previous month, formed here from month t - 1’s own opening balance and events, the same operations in the same order as av_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() plus lca_pp_init() plus the ladder’s balances, seg_bal_pp_init(), slot by slot, summed in the compensated loop seg_bal_active_pp() sums in, so that an extract carried to the cent opens one account, its parts’ sum, which check_av_components() then holds; any other point opens from av_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, which check_av_roll_fwd() reads. Zero before issue.

BEF_CREDIT

After the net premium, before the maturing segment’s index credit. Zero outside cover, and so is every later timing.

BEF_WD

After 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_FEE

After 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_INV

After the monthly deduction, before interest.

The end-of-month balance, the notes’ AV_{t+1}, is av_pp(), and check_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, is av_pp_at(t, BEF_PREM), which forms this cell’s value at t - 1 itself. 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. timing takes the same values as av_pp_at(), plus EOM for the closing balance before decrements. At t = proj_len(), av_at(t, BEF_PREM) is the account value the survivors of the last month carry, which check_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), following CashValue_SE. Zero outside cover, before t + 1 is read, so that nothing reads a month past t = 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) where m is the notes’ own month index duration_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 by surr_charge_rate_max() and surr_charge_runoff_years(), which ask Data to check the table first; the floor keeps IUL_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 – is ncsv_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 the csv_pp() floor binds. Insurer income, and part of margin_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 month t’s own premium and withdrawal. It opens in the first month on the books, t_entry(), from cum_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_S opens 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 month t, opening in the first month on the books, t_entry(), from cum_prem_net_init(), the accumulator the point carries into the valuation month, 0 at issue. IUL_US_S opens 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 age for 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 – with L_t the loan balance at the start of the month, the previous month’s loan_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 at t + 2 months 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 limit in 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, as UL_US_S does.

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(), to is_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_factor at the point: the factor of the point’s rate_class in class_factor_table.csv, joined once for the table after data.class_count() has checked its classes and factors, so that no projection cell reads the table or the class: a blank factor would otherwise reach mort_rate() as a missing value, which its cap keeps missing. A class the table has no row for is refused by Data, naming every such point, at the first read, where IUL_US_S raises pandas’ KeyError in 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 by mort_rate_base_at().

The product is capped at 1, written min(q, 1.0), as IUL_US_S’s is: a class factor above 1 carries the oldest ages’ rates past 1, where the monthly rate 1 - (1 - q)^(1/12) has no real value, and with the bound second a missing input, a NaN, stays NaN, where min(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. Data refuses 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 ages data.mort_age_first() and data.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, as corridor_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.

mort_rate_mth(t)[source]#

q^d_t: the monthly mortality rate, 1 - (1 - q)^(1/12) [std] conversion.

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 year data.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, where IUL_US_S’s lookup raised KeyError, 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 why lapse_rate_sc_mult() asks is_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), where IUL_US_S’s compares t itself, 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 keep IUL_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_cap is 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, as IUL_US_S returns it, so an nlg_shock_lapse past 1 is a rate past 1, whose monthly rate has no real value. Zero outside cover.

lapse_rate_mth(t)[source]#

q^w_t: the monthly lapse rate, 1 - (1 - w)^(1/12) [std] conversion.

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 at t = 0 it is exactly IUL_US_S’s pols_if. A point in force at the valuation date opens with pols_if_init(), and one issued at or after it with its issued count in the issue month. Zero before issue. At t = 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’s BEF_DECR count, not its pols_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_NB

The count carried in from month t - 1, before month t’s new business: month t - 1’s BEF_DECR count less its deaths and lapses, death applied before lapse, in IUL_US_S’s order. In the first month on the books, t_entry(), it is pols_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_DECR

l_t: BEF_NB plus pols_new_biz(), before any decrement; the same number as pols_if(), and the weight on that month’s cash flows.

BEF_MAT

Before any maturity: IUL_US_S’s meaning, the BEF_DECR count, 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’s BEF_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_NB forms month t - 1’s BEF_DECR count itself – its own value at t - 1 plus that month’s pols_new_biz() – and takes its deaths and lapses from the month’s rates, as pols_death() and pols_lapse() do, rather than calling for any of them. So the chain of calls back to t_entry() is one cell a month, as IUL_US_S’s pols_if() chain was: a compiled model runs that chain on the C stack. IUL_US_S’s cell returns pols_if() for every timing, which in the issue month counts the issued policies under all three; here BEF_NB alone 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 = 0 for a point issued at the valuation date, t = k for one issued k months 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.

DEATH

DB_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.

LAPSE

CSV_t, the cash surrender value with the surrender charge and the loan already netted – ncsv_pp().

WITHDRAWAL

W_t - $25 fee: the withdrawal is gross of the fee and the insurer keeps it. This kind survives here, though claims() 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. MATURITY is 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() and claims_lapse(), summed left to right from 0.0, the total IUL_US_S’s claims(t) computes with its kind=None default, sum over the two kinds: a fold of two terms from 0.0 is that sum, the sign of a zero included, so the total is IUL_US_S’s bit for bit. Death claims are weighted by pols_death() and surrenders by pols_lapse(), both end-of-month events.

WITHDRAWAL is 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 cell withdrawals() and its own result_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() at DEATH times pols_death().

IUL_US_S’s claims(t, "DEATH"), a cell of its own, so that each kind is a monthly cell with a C cache and claims() their total. The claims_death column of result_cf().

claims_lapse(t)[source]#

Surrender payments in month t: claim_pp() at LAPSE times pols_lapse().

IUL_US_S’s claims(t, "LAPSE"), a cell of its own, as claims_death() is. The claims_lapse column of result_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 is claim_pp(t, WITHDRAWAL), so the fee-inside-W_t rule is stated once; the fee itself stays with the insurer as wd_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 in claims().

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_rate is 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_S steps on the policy year, (1 + inflation_rate)^(y - 1); on a point issued at t = 0 the two are the same. A function of the clock alone, so it holds its value outside cover. Acquisition is not inflated (see expenses()).

expenses(t)[source]#

E_t: the insurer’s own expenses in month t [std].

$75 a policy a year spread monthly, plus $150 at 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 in basiclife.BasicTerm_SE, and a point in force never bears it. On a point issued at t = 0 this is IUL_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 into t = proj_len() would otherwise bear a maintenance expense.

premium_taxes(t)[source]#

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. Follows CashValue_SE.margin_expense; see check_margin() for the identity it takes part in.

margin_mortality(t)[source]#

Mortality margin: coi() net of claims_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, so withdrawals() 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 – see check_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 True when, for every month of the frame, av_pp(t) == fa_pp(t) + seg_bal_tot_pp(t) + lca_pp(t) to within 1e-9, relative to the larger side and 10, which is what IUL_US_S’s math.isclose tests with its tolerances, rel_tol=1e-9 and abs_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, and Data holds the av_pp_init column to the same sum. Each month’s residual is check_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, as IUL_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 within 1e-9 exactly where math.isclose with rel_tol=1e-9 and abs_tol=1e-8 holds, IUL_US_S’s test. Returned as a float, so that a value that is not real raises here, as IUL_US_S’s math.isclose raises on it. Zero outside cover.

check_av_roll_fwd()[source]#

Check the account value roll-forward.

Returns True when, for every month of the frame, the opening account value in force of month t + 1 equals:

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 for check_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 is check_av_roll_fwd_resid(); a residual that is not a number fails, and one that is not real raises, as IUL_US_S’s check does. In the last month the opening value of t + 1 is the account value the survivors carry into t = 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 + 1 less the roll-forward of month t that check_av_roll_fwd() sets out, over the larger of the two in magnitude and 10, and a float, as check_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, before t + 1 is read, so that nothing reads a month past t = proj_len().

check_seg_ladder()[source]#

Check the segment ladder bookkeeping.

Returns True when, for every month of the frame, all four of the following hold:

  • at most seg_term_mth segments 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, and seg_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 – see mth_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_mth at the end of month t: zero or below.

seg_count(t) - seg_term_mth as a float, which check_seg_ladder() holds to 0 or below, IUL_US_S’s seg_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(), which check_seg_ladder() holds to -1e-8 or 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) to duration_mth(t), each read at its slot, which check_seg_ladder() holds to -1e-8 or 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, as IUL_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 month t - 1, in slot 11, plus the deductions and the draws charged to it, over the larger of the two in magnitude and 10, a float, as check_av_components_resid() is: math.isclose with IUL_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 True when, 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 for check_av_components(); each month’s residual is check_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 from CashValue_SE, whose net_cf already nets the change in account value and the investment income. index_credits joins inv_income because 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, where ncsv_pp() pays nothing, and the advance itself. IUL_US_S’s identity takes the whole loan in every month, which holds while neither the csv_pp() nor the ncsv_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 as UL_US_SEC, VUL_US_SEC and ULSG_US_SEC do, 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, that check_margin() sets out, over the larger of the two sides in magnitude and 10, a float, as check_av_components_resid() is. Zero outside cover, before av_change() would read t + 1.

result_cf()[source]#

Result table of cashflows, a DataFrame indexed by month t.

One row per month t = 0 .. proj_len() - 1 from 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 are IUL_US_S’s. pols_if is the number in force at the start of month t and is the weight on that same row’s cash flows. The cash flow columns are income-positive and sum to net_cf: premiums - claims_death - claims_lapse - withdrawals - expenses - premium_taxes + net_loan_cf. The surrender column is claims_lapse, matching the LAPSE kind 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 in result_cf(). First the counts result_cf() weights its rows by, and how they move, as basiclife.BasicTerm_SE’s result_pols sets 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, in IUL_US_S’s order, and its maturities, which are always zero. Row by row, pols_if at t + 1 is pols_if less the two outflows of month t, plus the new business of month t + 1. Then IUL_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() - 1 from the valuation date, as in result_cf(); av_pp_bef_prem on row t is the opening balance and av_pp the 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() - 1 from the valuation date, as in result_cf(). The index level is the path on the valuation clock, index_level(), which on a point in force differs from IUL_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.