The Projection Space#

The by-policy projection of the WholeLife_US_SEC model; holds all formulas.

The Space is parameterized by idx, the position of a model point in the table and in every Data vector, as basiclife.BasicTerm_SC is: Projection[18] is an ItemSpace projecting the table’s nineteenth row, model point 19, the loan variant in force 114 months at the valuation date, and point_id() is its label:

>>> Projection[18].result_cf()         # one row per month from the valuation date
>>> Projection[18].result_pols()       # the counts behind it
>>> Projection[18].point_id()          # 19, 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.

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 WholeLife_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 WholeLife_US_S is rewritten where it depends on where the projection starts, where it must answer for a month outside cover, or where it passed a policy month as t; every other is WholeLife_US_S’s own. products/whole_life/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, every timing, kind, premium period and dividend option is an int code (Codes, below), and WholeLife_US_S’s claims(t, kind=None) is three cells and their total.

Input data

Inputs are external files: plain CSVs living in the model folder’s parent directory, products/whole_life/, 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 WholeLife_US_SEC folder without its parent’s CSVs produces a model that reads and then fails on first evaluation.

Each table has a filename Reference and a reader Cells, both on the Data Space, reached here through the data Reference. The five assumption tables are the files WholeLife_US_S reads, read in place; the model point table is this model’s own.

Reference

Cells

File

model_point_file

data.model_point_table()

model_point_table_sec.csv

cv_file

data.cv_table()

cv_table.csv

nsp_file

data.nsp_table()

nsp_table.csv

np_guar_file

data.np_guar_table()

np_guar_table.csv

mort_table_file

data.mort_table()

mort_table.csv

premium_rates_file

data.premium_rates()

premium_rates.csv

No cell here but model_point(), a reporting cell, reads the readers’ DataFrames, and the label accessors read through it. Every other reads Data’s vectors and arrays, one element at a time: a model point’s attribute at its position, data.issue_age()[idx], decoded already into the number the formula needs; the cash value schedule at data.cv_array()[cv_schedule(), y]; the guaranteed mortality and the net single premiums at the point’s schedule, its sex’s, and the attained age, data.mort_table_array()[mort_schedule(), y]; the final-expense rate and the net level premium joined to the point already, data.premium_rate_per_1000()[idx]. Data’s docstring lists them.

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, period t runs from time t to time t + 1, and the frame is t = 0 .. proj_len() - 1, where proj_len() counts the months from the valuation date to maturity at attained age 100. Row t is the same month for every point, so the frames of a block line up and sum row by row.

duration_mth(t) counts policy months, the months the policy has been in force at time t: duration_mth(t) = duration_mth_init() + t, where duration_mth_init() is read from the model point — positive for a 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. It is the technical notes’ month index, and everything contractual about this product reads it, all of it on an annual cycle: the guaranteed cash value schedule, the dividend declaration, the anniversary capitalization of loan interest, the premium-paying period. The policy year is therefore derived and used as a lookup key throughout — duration(t) = duration_mth(t) // 12 is the completed policy years at the start of month t, policy_year(t) = duration(t) + 1 is the contractual 1-based label (the policy_year key of cv_table.csv), age(t) = age_at_entry() + duration(t) is the attained age entering that policy year and age_anniv(t) the age at the anniversary that ends it. is_anniv(t) is true in the last month of a policy year, which is where every annual event lands, and anniv_mth() is the valuation month of that anniversary. The anchor cell, in force 108 months, is in policy year 10 at attained age 54 at t = 0 and reaches its tenth anniversary at t = 11; the loan variant in force 114 months pays its next premium at t = 6.

One input reads the valuation clock instead: expense inflation, inflation_factor(t) = (1 + inflation_rate) ** (t / 12), so that the maintenance charge is in valuation-date dollars for every point alike. Acquisition is charged per policy issued, in the issue month, and is not inflated, as in basiclife.BasicTerm_SE.

On a point issued at t = 0 the two clocks coincide and this model computes what WholeLife_US_S computes: every cell the two share agrees at every argument WholeLife_US_S evaluates in its sweep, but for three whose meaning changed, pols_if_init, now the count already in force at the valuation date, model_point, a row of another table, and result_pols, which gains the month’s new business. That is how WholeLife_US_S’s goldens on its new-business points carry over, and tests/test_model_conventions.py asserts it cell by cell. On a point in force the projection is WholeLife_US_S’s from the month the point is valued at, month for month, its expenses apart, which are in valuation-date dollars. That is how the worked example carries over: it sits on WholeLife_US_S’s point 1, in force at its month 108, and the twin of that point is WholeLife_US_S’s projection from month 108 on, which tests/test_whole_life_us_sec.py asserts.

The value state variables are closing balances at the end of month t: cv_pp(t), pua_face(t), pua_cv(t), div_accum(t) and loan_bal(t). The value entering month t is the closing balance of month t - 1, or, at t_entry(), the first month on the books, the model point’s opening state — written inline as pua_face(t - 1) if t > t_entry() else pua_face_init() wherever an opening balance is read, 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 seven columns of its row, per policy, as the policy stands at the start of month 0: the paid-up additions, the loan and the accumulation balance entering month 0 (pua_face_init(), loan_bal_init(), div_accum_init()), the paid-up additions and the loan at the anniversary that opened the policy year under way (pua_face_prev_anniv_init(), loan_bal_prev_anniv_init()), the dividend credited there (div_prev_anniv_init()), and the gross premium paid to date (prem_cum_init()). For a point issued at or after the valuation date every one of them is 0, the values at issue. Annual quantities read the balance entering the policy year instead, twelve months back, or the opening state’s anniversary values where that month is before t_entry().

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 nothing is counted outside cover (is_active()): before issue every count, and so every cash flow, is zero, and so is every value state and every dividend. Inside the month the decrements are WholeLife_US_S’s, in the notes’ order, and pols_if_at names the count between each: BEF_SURR after deaths, BEF_MAT after surrenders and AFT_DECR after the maturities of the last covered month.

What the monthly grid changes, and what it does not

Decrements run in two speeds, the library’s convention: mort_rate(t) and lapse_rate(t) are the annual rates of the policy year containing month t — the vectors the technical notes tabulate — and mort_rate_mth(t) and lapse_rate_mth(t) are the monthly rates actually applied, 1 - (1 - q)^(1/12). Twelve of those compound back to exactly the annual rate, so the in-force at every policy anniversary is what an annual-step model would carry, to floating-point.

The annual events stay annual and land on is_anniv(t): the dividend is declared and credited once a year, at the anniversary; loan interest capitalizes there; paid-up additions are bought with the dividend there. What the finer grid buys is everything that is not contractually annual — death claims settle at the end of the month of death rather than the end of the policy year, maintenance expense accrues monthly, the guaranteed cash value and the paid-up-additions cash value interpolate between anniversaries so a mid-year surrender is valued where it happens, and a modal premium is collected when it is contractually due. That last one is why the technical notes’ “premium mode modeled: annual” [std] is retired: the modal factors are sourced ([S1] for the participating design, [S7] for final expense) and the monthly grid is what makes them expressible. result_cf_annual() sums the frame into policy years so a monthly run can be laid beside an annual one.

Two interpolations are standardizations introduced here, both [std] and both exact at the anniversary so that no anniversary quantity moves:

cv_pp(t)

Straight-line between the schedule’s anniversary values, (k + 1) / 12 of the way from the value at the anniversary opening the policy year to the value at the one closing it, k = duration_mth(t) % 12. Contractual cash value tables are printed at anniversaries only [unverified]; pro-rating for elapsed time is the ordinary policy-form convention and the Standard Nonforfeiture Law requires some adjustment for it.

nsp_mth(t)

The same straight line applied to the net single premium between NSP_{x+dur} and NSP_{x+dur+1}, so the paid-up-additions block is valued on the same clock as the base cash value.

Naming

Cells names follow lifelib’s basiclife.BasicTerm_S and savings.CashValue_SE wherever those models have an analogue — pols_* for policy counts, plural nouns for cash flows, *_rate for rates, *_pp for per-policy amounts, claim_pp(t, kind) and pols_if_at(t, timing) for the argument-keyed families. What running in force adds is named as basiclife.BasicTerm_SE names it: duration_mth read from the model point, policy_count, pols_new_biz, pols_if_at with its BEF_NB timing, is_active and result_pols. duration_mth_init, the policy months completed at the valuation date, takes UL_US_S’s name. What compiling adds is named as basiclife.BasicTerm_SC names it: idx, point_id and the Data vectors under their columns’ names; a code read off a column adds _code to the column’s name, and a point’s row of a table numbered by schedule is its _schedule. A column of the opening state measured entering month 0 is the cell it opens with _init added, pua_face_init for pua_face(), and so is div_prev_anniv_init, which div_prev_anniv() returns through the policy year under way; a balance measured at the anniversary on or before the valuation date adds _prev_anniv_init instead, pua_face_prev_anniv_init. t_entry and maturity_mth are this model’s own. The technical notes use compact actuarial symbols instead. The notes’ month index is this model’s duration_mth(t). The mapping is:

Notes symbol

Cells

Meaning

x

age_at_entry

Issue age (ANB)

x + dur

age(t)

Attained age entering the policy year of month t

x + dur + 1

age_anniv(t)

Attained age at the anniversary ending it

(none)

point_id

The model point’s label in the table

(none)

policy_count

Policies the model point stands for

(none)

duration_mth_init

Completed policy months at the valuation date; -k if issued k months later

t

duration_mth(t)

The notes’ month index: completed policy months at month t

(t // 12)

duration(t)

Completed policy years

dur(t)

policy_year(t)

Policy year, duration(t) + 1

T = 12(100 - x)

maturity_mth

Policy month at which cover ends

(frame)

proj_len

Months from the valuation date to maturity; the frame ends at proj_len - 1

(none)

t_entry

First month on the books

(none)

is_active(t)

Whether month t is inside cover

(anniversary)

is_anniv(t)

Last month of a policy year

(anniversary month)

anniv_mth(t)

Valuation month of the anniversary ending the policy year of t

m

policy_term

Premium-paying period, years

(period)

premium_period_code

The premium period, as a code

F

sum_assured

Base face amount

(par design)

is_par

Whether the point participates

(graded plan)

is_graded

Whether it is graded final expense

G

premium_pp_ann(t)

Gross annual premium

(par G)

annual_premium

G on the participating design

(modal)

premium_pp(t)

Premium due in month t

(modal factor)

modal_factor

Fraction of G per instalment

(modal cycle)

prem_cycle

Months between instalments

(due month)

prem_due(t)

Whether an instalment is due

G^net_t

premium_net_pp_ann(t)

Annual premium after offset

(modal)

premium_net_pp(t)

The instalment actually collected

A_t

rider_premium_pp_ann(t)

PUA rider premium, annual

(rider)

pua_rider_premium

The model point’s A, annual

(modal)

rider_premium_pp(t)

The instalment due in month t

i_g

int_rate_guar

Guarantee interest, 4.00%

i_d

int_rate_div

Dividend interest rate, 6.00%

i_L

int_rate_loan

Policy loan rate, 6.00%

q^g_{x+t}

mort_rate_guar(t)

Guarantee mortality, annual

q^g_y

mort_rate_guar_at(y)

The same, keyed by age

(schedule)

mort_schedule

The point’s mortality schedule

q^sc_{x+t}

mort_rate_scale(t)

Dividend-scale mortality

q^e_{x+t}

mort_rate(t)

Best-estimate mortality, annual

(q^e monthly)

mort_rate_mth(t)

The monthly rate applied

w_t

lapse_rate(t)

Surrender rate, annual

(w monthly)

lapse_rate_mth(t)

The monthly rate applied

w^dyn multiplier

dyn_lapse_factor(t)

Interest-sensitive overlay

l_t

pols_if(t)

In force weighting month t: after new business, before decrements

l_{t+1}

pols_if_at(t, AFT_DECR)

In force at EOM t

l_t(1-q^e)

pols_if_at(t, timing)

In force inside month t, BEF_NB to AFT_DECR

(none)

pols_if_init

In force at the valuation date

(none)

pols_new_biz(t)

Policies issued in month t

(none)

pols_death(t)

Deaths in month t

(none)

pols_lapse(t)

Surrenders at EOM t

(none)

pols_maturity(t)

Maturities in the last covered month

CV_t

cv_pp(t)

Guaranteed cash value, EOM t

CV at anniversary

cv_pp_anniv(y)

The schedule’s own values

(schedule)

cv_schedule

The point’s cash value schedule

F - CV_t

net_amt_at_risk(t)

Guarantee net amount at risk

NSP_y

nsp(y)

Net single premium, endow 100

(schedule)

nsp_schedule

The point’s NSP schedule

(NSP monthly)

nsp_mth(t)

NSP interpolated to EOM t

NP_g

np_guar()

Nonforfeiture net level premium

D^int_t

div_int(t)

Interest margin

D^mort_t

div_mort(t)

Mortality margin

D^exp_t (e^m_t)

div_exp(t)

Expense margin

D_t

div_base(t)

Base-block dividend, floored

D^PUA_t

div_pua(t)

PUA-block dividend

D_t + D^PUA_t

div_credited(t)

Dividend credited at EOM t

D_{t-1}

div_prev_anniv(t)

Dividend at the anniversary opening the policy year of t

(option)

dividend_option_code

The dividend option, as a code

D^cash_t

div_cash(t)

Cash dividend per policy

(none)

div_to_pua(t)

Dividend applied to PUAs

dPUAF_t

pua_face_purch(t)

PUA face bought by dividend

dPUAF^rider_t

pua_face_rider(t)

PUA face bought by the rider

(none)

pua_face_offset(t)

PUA face from the RPD excess

PUAF_t

pua_face(t)

PUA face in force at EOM t

PUACV_t

pua_cv(t)

PUA cash value at EOM t

DA_t

div_accum(t)

Dividend accumulation balance

L_t

loan_bal(t)

Loan balance at EOM t

(none)

loan_int(t)

Loan interest capitalized

(none)

loan_draw(t)

Net new borrowing per policy

(opening PUAF)

pua_face_init

PUA face entering month 0

(PUAF at anniversary)

pua_face_prev_anniv_init

PUA face at the anniversary opening the year of month 0

(opening L)

loan_bal_init

Loan balance entering month 0

(L at anniversary)

loan_bal_prev_anniv_init

Loan balance at the anniversary opening the year of month 0

(opening DA)

div_accum_init

Accumulation balance entering month 0

(D_{t-1} at month 0)

div_prev_anniv_init

Dividend at the anniversary opening the year of month 0

(none)

prem_cum_init

Gross premium paid before the valuation date

TF

term_blend_target

Term-blend target face

OYT_t

oyt_face(t)

One-year-term face in the blend

(none)

oyt_cost(t)

Dividend absorbed by the OYT

DB_t

claim_pp(t, DEATH)

Death benefit per policy

CSV_t

claim_pp(t, LAPSE)

Surrender value per policy

MAT

claim_pp(t, MATURITY)

Maturity benefit per policy

(none)

prem_cum(t)

Cumulative premiums paid

E_t

expenses(t)

Acquisition + maintenance

1.02^(t/12)

inflation_factor(t)

Expense inflation, valuation clock

(none)

premium_taxes(t)

Premium tax outgo

(none)

premiums(t)

Premium income

(none)

rider_premiums(t)

PUA rider premium income

(none)

claims(t)

Benefit outgo, the three kinds

(none)

claims_death(t)

Death claims

(none)

claims_lapse(t)

Surrender claims

(none)

claims_maturity(t)

Maturity claims

(none)

div_cash_paid(t)

Cash dividend outgo

(none)

loan_draws(t)

Net loan advances

NetCF_t

liability_cf(t)

Net liability CF, outgo +

(none)

net_cf(t)

The same, income positive

(none)

result_cf_annual()

result_cf() summed into years

(none)

result_pols()

The counts and decrement rates

Eight names needed care.

mort_rate is the best-estimate rate — the one that actually decrements the block — while the guarantee and dividend-scale rates are mort_rate_guar and mort_rate_scale. All three come off the same shipped table through the References ae_best_est and ae_scale. The notes call this out as a consistency trap: the same table feeds claim outgo and the dividend’s mortality margin with opposite signs, so raising best-estimate mortality raises claims and, if the scale factor moves with it, cuts the dividend.

policy_term is the premium-paying period m in years, not the coverage period. Coverage runs to maturity_mth() in every variant; on the base pay-to-100 design the two coincide, on PAY_10 they do not. It stays in years because the contract states it in years; premium_pp compares it against duration(t).

pols_lapse counts surrenders. The notes say “surrenders”, BasicTerm_S says pols_lapse, and CashValue_SE’s kind string is "LAPSE"; the model keeps the lifelib name, as the code LAPSE, so the kind vocabulary stays intact.

The notes’ CSV_t is the cash surrender value, not a file. It is reached as claim_pp(t, LAPSE) so that all three benefit amounts share one cells and one kind vocabulary with CashValue_SE.

age(t) and age_anniv(t) are both needed: the notes index mortality at the attained age entering the policy year but price paid-up additions bought at the end of it one year later. Getting them the wrong way round shifts every dividend purchase by a year.

anniv alone means the anniversary that ends a policy year — is_anniv(t), anniv_mth(t), age_anniv(t) — and prev_anniv the one that opened it, as in div_prev_anniv(t), so the opening state’s pua_face_prev_anniv_init, loan_bal_prev_anniv_init and div_prev_anniv_init are the values at the anniversary on or before the valuation date. An extract that fills them from the anniversary after it is a year out.

pols_if(t) is the start-of-month count — the notes’ l_t, not their l_{t+1} — after the month’s new business and before its decrements, pols_if_at(t, BEF_DECR). That is the library-wide convention, the count every cash flow on the same result_cf() row is weighted by, and on a point issued at t = 0 it is WholeLife_US_S’s pols_if. The notes’ end-of-period state variable is not lost — it is pols_if_at(t, AFT_DECR), which is pols_if_at(t + 1, BEF_NB) by construction, the count carried into the next month before that month’s new business.

liability_cf(t) and net_cf(t) are the same stream with opposite signs — see the sign-convention rubric below.

Timing and kind arguments

pols_if_at(t, timing) takes five timings, in processing order: BEF_NB (the count carried in from month t - 1, before month t’s new business), BEF_DECR (start of month t, after its new business and before any decrement — the same number as pols_if(t)), BEF_SURR (after deaths, before surrenders), BEF_MAT (after surrenders, before maturity) and AFT_DECR (after every decrement, the notes’ l_{t+1}) — the notes’ end-of-period processing order, deaths then dividend then surrenders then maturity, now applied every month. BEF_NB and BEF_DECR are basiclife.BasicTerm_SE’s names, and BEF_DECR and BEF_MAT CashValue_SE’s; BEF_SURR is added because this product settles deaths and surrenders in one end-of-period step, and AFT_DECR because CashValue_SE has no name for the point past the last decrement, which is where the notes’ state variable lives. One name means two instants in the two references: basiclife.BasicTerm_SE’s BEF_MAT counts the policies at the start of a month, before that month’s maturities, where this model’s, WholeLife_US_S’s, counts them at its end, after its surrenders. The policies here mature at the end of the last covered month, as the S goldens have it, so the name keeps the S meaning and basiclife.BasicTerm_SE’s timing is not adopted. claim_pp(t, kind) takes DEATH, LAPSE and MATURITY, and claims_death(), claims_lapse() and claims_maturity() are the claims of each, claims() their total. The two raise ValueError("invalid timing") / ValueError("invalid kind") on anything else. Each is an int code, as Codes below sets out, where WholeLife_US_S passes the name as a string.

Codes

What WholeLife_US_S spells as text, a timing, a kind, a premium period or a dividend option, 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), claim_pp(t, DEATH), premium_period_code() == TO_100.

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_SURR

2

pols_if_at(): after month t’s deaths

BEF_MAT

3

pols_if_at(): after its surrenders

AFT_DECR

4

pols_if_at(): after its maturities, l_{t+1}

DEATH

0

claim_pp(): the death benefit

LAPSE

1

claim_pp(): the surrender value

MATURITY

2

claim_pp(): the maturity benefit

TO_100

0

premium_period_code(): premiums payable to maturity

PAY_10

1

premium_period_code(): ten years’ premiums

PAY_20

2

premium_period_code(): twenty years’ premiums

TO_65

3

premium_period_code(): premiums payable to attained age 65

PUA

0

dividend_option_code(): the dividend buys paid-up additions

CASH

1

dividend_option_code(): paid in cash

ACCUM

2

dividend_option_code(): left to accumulate at interest

REDUCE_PREM

3

dividend_option_code(): offsets the next year’s premium

NONE

4

dividend_option_code(): none of the four, final expense’s

A code a cell takes indexes that cell’s cache, a C array of five timings a month for pols_if_at, and as wide for claim_pp’s three kinds, since every 2-D cache of the model has one width (spec_sec.py), so codes are numbered densely from 0. Timings are numbered in the order of their instants within the month, BEF_NB before BEF_DECR, as in every SEC model, and kinds in the order the month settles them; the premium periods follow product-spec.md’s list, and the dividend options the notes’. 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 maturity_age among them, the contract’s bounds that the compiled model’s caches are sized from (proj_len()).

Reporting cells

model_point(), the label accessors product(), premium_period(), sex(), risk_class(), dividend_option() and premium_mode(), the reports result_cf(), result_pols(), result_cv() and result_cf_annual(), and the checks check_pols_roll_fwd() and check_pua_roll_fwd() are written for a reader and for the comparison with WholeLife_US_S, which has every one of them: a table row, text, DataFrames and two verdicts. No cell but these calls them: every other reads the number Data decoded from the same column instead, the product’s flags, the period’s and the option’s codes, the mode’s cycle, the schedules and the joins the keys select. So the row, the text and the frames stay Python when the model compiles, and every other cell returns a C bint, long long or double: the two checks among them, whose verdict is a bint, and their per-month residuals, *_resid. One Python call stays inside a compiled cell: div_base() rounds the dividend with Python’s round, which tests/us_registry.py admits in that cell alone.

The dividend is rounded to the cent

div_round_digits = 2 rounds the credited base dividend before it buys paid-up additions. This is [std], and it is not cosmetic: the notes’ worked example adds the displayed margins (216.00 + 85.25 + 25.00 = 326.25) and then divides 326.25 by the net single premium. Carrying the unrounded 326.248 through instead moves the purchased paid-up-additions face from 776.79 to 776.78 — a full displayed cent, because the exact value sits just under the rounding boundary. Declared dividends are credited in whole cents, so the model rounds; setting div_round_digits below -400, to -1000 say, turns it off and a test pins the size of the gap in both directions. That is a departure from WholeLife_US_S, whose div_round_digits = None turns it off: None is no C number, so here the digits are an int, and a count below -400 turns rounding off. Every other count rounds as WholeLife_US_S rounds, a negative one to tens, hundreds and so on, as Python’s round does with negative digits, and 0 to the dollar. The two part only below -400, where WholeLife_US_S’s round already gives 0.0 for every dividend a float can hold, from -309 digits down, and here the dividend is unrounded: no digit count that leaves a dividend standing turns it off.

The worked example sets the PUA-block dividend aside

The notes’ worked-example table computes steps 11-15 from the base-block dividend alone, saying so explicitly: “For clarity the PUA-block dividend D^PUA is omitted from this table; in the model it adds … to the amount in step 9.” The Reference pua_div_on ships False so the base deterministic run reproduces the worked example exactly, the same way Term_US_S ships conv_rate_base = 0. It is a reproduction switch, not a claim that paid-up additions are excluded from the dividend — they are dividend-eligible, and pua_div_on = True is the product-faithful setting. div_pua(t) implements the notes’ formula either way, and a test asserts its value on the anchor cell against the notes’ own parenthetical.

The four guarantee-basis tables are not one construction

The notes’ first “known modeling pitfall” is a mismatch between the cash value table and the NSP/annuity functions, and prescribes regenerating every guarantee-basis quantity from one 2017 CSO / 4% source. The shipped tables do not satisfy that, and no set of tables carrying the worked example’s anchors could. On any single mortality basis at interest i, endowment insurance and the annuity-due satisfy A_{x:n} = 1 - d ae_{x:n} with d = i/(1+i), so the notes’ own definition collapses to NNLP = 1000 d NSP_45 / (1 - NSP_45); the worked example’s NNLP = 13.00 then forces NSP_45 = 0.252616. But NSP_y = v(NSP_{y+1} + q_y (1 - NSP_{y+1})) >= v NSP_{y+1} for any q_y >= 0, so NSP_55 <= NSP_45 (1.04)^10 = 0.373933 — below the worked example’s NSP_55 = 0.42. Read the other way: NSP_55 = 0.42 forces NSP_45 >= 0.283737 and hence NNLP >= 15.236 per $1,000, 17% above the notes’ 13.00. The worked example’s steps 3 and 10 are mutually unreachable, whatever mortality table is used.

What the shipped tables do instead [std]: mort_table.csv is an illustrative Makeham curve pinned to q^g_54 = 0.00320; nsp_table.csv is a separate parametric curve pinned to NSP_55 = 0.42 and NSP_100 = 1; np_guar_table.csv holds 1000 NSP_x / ae_{x:(100-x)} with the annuity taken on the mortality table’s own survivorship, which is what makes NP_g = 13.00; and cv_table.csv is a monotone shape solved through its policy-year 9 and 10 rows — the worked example’s 95.00 and 112.00 per $1,000, which are cv_pp_anniv(9) and cv_pp_anniv(10) — to 1000.00 at attained age 100. Reconciling the NSP curve with the mortality table needs a guarantee interest rate that falls from 5.99% at age 45 to 0.02% at age 99, and inverting the curve for the implied q at 4% gives a negative rate at every age up to 57 and a rate above 1 from age 89 on.

The two consequences the pitfall names are nevertheless absent, and are asserted by tests: NSP_100 = 1 exactly, so pua_cv(t) == pua_face(t) in the last projected month, t = proj_len() - 1, which is the notes’ month T - 1, and the schedule reaches exactly face in that final policy month, so cv_pp(t) == sum_assured() there. Neither block leaks at maturity. What is missing is the means — one basis — not the endpoints. Swap in a licensed 2017 CSO / 4% set and all four files must be replaced together; the worked example will then no longer reproduce, which is the honest price of the notes’ own arithmetic.

Sign convention — two names, one stream

The whole-life notes print NetCF_t with outgo positive, which is the opposite of the sign the other eleven reference models in products/ carry. Rather than pick one and lose the other, the model publishes both and names them apart:

liability_cf(t)

The notes’ NetCF_t, verbatim: outgo positive. Premium and rider income enter with a minus sign; expenses, premium tax, claims, cash dividends and net loan advances enter with a plus. A positive liability_cf is money leaving the insurer. This is the number to compare against the notes.

net_cf(t)

-liability_cf(t): income positive, the sign convention every model in products/ carries, so that result_cf()["net_cf"] can be summed or compared across products. A positive net_cf is money arriving at the insurer.

Both are columns of result_cf(). The pattern is SPIA_US_S and DIA_US_S’s, which face the same clash. Nothing about the whole-life notes’ own convention is being denied — it is being kept under a name that does not collide with the library-wide one, because a sign error in a 55-year liability projection is invisible in a summary statistic.

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), 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.

product()[source]#

The product code of the selected model point: WL_PAR, WL_FE_LEVEL or WL_FE_GRADED.

A reporting cell (the Space docstring): Data decodes the column into the flags is_par() and is_graded() read, and joins the final-expense rate by it, and no projection cell reads it here.

is_par()[source]#

True for the participating design, which is the only one that pays dividends.

The product is WL_PAR, from Data.is_par, a Python bool.

is_graded()[source]#

True for the graded final-expense plan, WL_FE_GRADED, from Data.is_graded.

Its death benefit in policy years 1-2 is the graded one (claim_pp()), where WholeLife_US_S compares the product’s text with the plan’s.

premium_period()[source]#

The premium period of the selected model point: TO_100, PAY_10, PAY_20 or TO_65.

A reporting cell: premium_period_code() is the column decoded, and Data joins the cash value schedule and the net level premium by the text, so no projection cell reads it here.

premium_period_code()[source]#

The premium period as its code, from Data.premium_period_code.

TO_100, PAY_10, PAY_20 or TO_65, the int References of the names (the Space docstring’s Codes): policy_term() and mec_flag() branch on it where WholeLife_US_S compares the text. Data refuses any other period.

age_at_entry()[source]#

The issue age (ANB) of the selected model point, from Data.issue_age.

The age at issue, not at the valuation date: age(0) is the attained age then.

sex()[source]#

The sex of the selected model point; rates are sex-distinct throughout.

A reporting cell: Data numbers the mortality, net single premium and cash value schedules by it and joins the net level premium and the final-expense rate by it, so no projection cell reads it here.

risk_class()[source]#

The underwriting class of the selected model point (PREF_NT / STD_NT / TOB).

A reporting cell: Data joins the final-expense rate by it, the one table keyed by class, and no projection cell reads it here.

sum_assured()[source]#

The base face amount F of the selected model point, from Data.face_amount.

dividend_option()[source]#

The elected dividend option: PUA, CASH, ACCUM, REDUCE_PREM, or NONE for non-par.

A reporting cell: dividend_option_code() is the column decoded, which every projection cell reads instead.

dividend_option_code()[source]#

The dividend option as its code, from Data.dividend_option_code.

PUA, CASH, ACCUM, REDUCE_PREM or NONE, the int References of the names (the Space docstring’s Codes). NONE is also what Data makes of any text that is none of the four, as WholeLife_US_S reads it: such a point earns its dividend, if participating, and applies it to nothing.

premium_mode()[source]#

The premium mode of the selected model point: A, SA, Q or M.

The technical notes’ “premium mode modeled: annual” was a consequence of the annual grid, not of the contract: every design in the spec is sold on all four modes [S1] [S7]. On the monthly grid the mode is a model point attribute, and the shipped table exercises both ends of it. A reporting cell: Data.prem_cycle decodes the months between instalments from the column, and modal_factor() selects the factor by them.

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 cash value, the paid-up additions, the dividend, the loan, the opening state — is the same whatever the count, and every cash flow is a per-policy amount weighted by it. Read from Data.policy_count.

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. WholeLife_US_S’s cell of the name is 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: 108 for the anchor cell, valued on the anniversary that opens its tenth policy year, 114 for the loan variant, valued six months into its tenth year, 0 for a policy issued at the valuation date, and -3 for one to be issued 3 months after it, which Data admits up to future_horizon_mth months ahead. It is read as basiclife.BasicTerm_SE reads it, and is the one fact the policy clock takes from the model point. It replaces WholeLife_US_S’s duration_inforce, a count of whole policy years, so a policy can be valued in any month of its policy year, not on an anniversary alone. Its element of Data.duration_mth.

pua_face_init()[source]#

PUAF entering month 0: the paid-up-additions face per policy at the valuation date.

The pua_face_init column: the block in force at the close of policy month duration_mth_init() - 1, before any month-0 event, which is what WholeLife_US_S carries into that month as the closing pua_face of the month before. It is the opening balance of pua_face() at t_entry(), and the paid-up additions the death benefit of month 0 carries. For the anchor cell it is the worked example’s stipulated 4,100, WholeLife_US_S’s puaf_inforce, renamed. Zero for a point not yet in force, as at issue.

pua_face_prev_anniv_init()[source]#

PUAF at the anniversary that opened the policy year of month 0, per policy.

The pua_face_prev_anniv_init column: the block in force at the close of policy month 12 * duration(0) - 1, the anniversary on or before the valuation date. The annual quantities of a policy year read the block entering it — the PUA-block dividend (div_pua()) and the term-blend gap (oyt_face()) — and for the year already under way at the valuation date that block is this. It is pua_face_init() on a point valued on an anniversary, the same instant, which Data checks, and 0 in the first policy year, which opened at issue. In any other month the two can differ, by what the rider instalments and the REDUCE_PREM excess have bought since the anniversary.

prev_anniv as in div_prev_anniv(): the anniversary that opened the year, where is_anniv(), anniv_mth() and age_anniv() name the one that ends it. Zero for a point not yet in force.

loan_bal_init()[source]#

L entering month 0: the policy loan balance per policy at the valuation date.

The loan_bal_init column: the balance outstanding at the close of policy month duration_mth_init() - 1, capitalized interest included, before any month-0 event. loan_draw() measures month 0’s advance from it, and the death benefit of month 0 deducts it. WholeLife_US_S’s loan_inforce, renamed. Zero for a point not yet in force.

loan_bal_prev_anniv_init()[source]#

L at the anniversary that opened the policy year of month 0, per policy.

The loan_bal_prev_anniv_init column: the balance at the close of policy month 12 * duration(0) - 1. Loan interest capitalizes once a year on the balance outstanding at the previous anniversary (loan_int()), and the dividend’s interest margin credits the loaned portion at the loan rate (div_int()), so the year under way at the valuation date reads this. It is loan_bal_init() on a point valued on an anniversary, which Data checks, and 0 in the first policy year. prev_anniv as in pua_face_prev_anniv_init(). Zero for a point not yet in force.

div_accum_init()[source]#

DA entering month 0: the dividend accumulation balance per policy.

The div_accum_init column: the balance at the close of policy month duration_mth_init() - 1, interest and dividends to date included. Only the ACCUM option holds one, and Data refuses a balance on any other. div_accum() opens from it at t_entry(), and the death benefit of month 0 carries it. WholeLife_US_S opens its in-force point at 0, the notes’ DA = 0; a balance built up before the valuation date is carried here instead, so that it reaches the death, surrender and maturity benefits. Zero for a point not yet in force.

div_prev_anniv_init()[source]#

D_{t-1} at month 0: the dividend credited at the anniversary opening its year.

The div_prev_anniv_init column, per policy, named for the cell that returns it: the dividend credited at the close of policy month 12 * duration(0) - 1, the anniversary on or before the valuation date. div_prev_anniv() returns it in every month of the policy year under way at the valuation date, so the REDUCE_PREM offset, the excess it buys paid-up additions with and the premium-offset overlay all read last year’s dividend, as they do in every later year. WholeLife_US_S takes it as zero there, an anniversary before its frame. Zero in the first policy year, on the non-participating design, and for a point not yet in force.

prem_cum_init()[source]#

Cumulative gross premium paid per policy before the valuation date.

The prem_cum_init column: every instalment of premium_pp() due from issue to policy month duration_mth_init() - 1, gross of any dividend offset. Only the final-expense graded plan reads it, through prem_cum(), for the 110%-of-premiums-paid death benefit of policy years 1-2. Zero for a point not yet in force.

loan_utilization()[source]#

Fraction of the guaranteed cash value held as a policy loan [std].

0 in the base run; the notes’ variant is 0.20, maintained by borrowing and repaying as the cash value moves. Read from Data.loan_utilization, which refuses a share outside 0 to 1.

term_blend_target()[source]#

TF: the term-blend rider’s target face amount; 0 switches the rider off.

Read from Data.term_blend_target.

annual_premium()[source]#

G on the participating design: the model point’s annual_premium.

From Data.annual_premium. premium_pp_ann() reads it on the participating design alone, where WholeLife_US_S reads the model point’s column; final expense leaves it blank, NaN here, and prices its premium from premium_rates.csv.

pua_rider_premium()[source]#

The model point’s annual paid-up-additions rider premium, pua_rider_premium.

From Data.pua_rider_premium: rider_premium_pp_ann() pays it while base premiums are payable, and mec_flag() reads it, where WholeLife_US_S reads the model point’s column in both.

is_blended()[source]#

True when the term-blend rider is active on this model point [std].

The blend needs the dividend to pay the one-year-term cost, so it is modelled only under the PUA dividend option and only on the participating design.

maturity_mth()[source]#

The policy month at which cover ends: 12 * (maturity_age - age_at_entry()).

The notes’ T = 12(100 - x): the policy matures at attained age 100, so this is the duration_mth of the first month not covered, 660 at issue age 45, and the last covered month is maturity_mth() - 1, the one ending at attained age 100. It is WholeLife_US_S’s frame length, counted from issue on the policy clock; proj_len() counts from the valuation date instead.

The contract itself matures at 121, but the guaranteed cash value equals face at 100 and the paid-up-additions cash value equals paid-up-additions face there, so from 100 the policy is economically an endowment at face. Truncating at 100 is a [std] simplification that moves the age 100-121 payments from death to maturity without changing their amount per survivor.

proj_len()[source]#

The number of months from the valuation date to maturity.

maturity_mth() - duration_mth_init(): 660 for a policy issued at age 45 at the valuation date, 552 for the anchor cell in force 108 months, and 663 for point 22, issued 3 months after the valuation date. The frame is t = 0, 1, ..., proj_len() - 1; proj_len() is its exclusive end, the row count of result_cf(), and proj_len() - 1 is the last covered month, the one ending at attained age 100.

Two kinds of point raise here, naming the point, rather than project nothing or a frame the contract does not have:

  • one at or past maturity at the valuation date, which an in-force extract should not carry;

  • one issued below issue_age_min, 0, the youngest issue age product-spec.md admits (level pay from 0 to 80).

The second is refused here because spec_sec.py sizes the compiled model’s caches from the contract, cover from issue_age_min to maturity_age, 100, and the shipped future horizon, and on such a point the compiled model would run past them, where modelx reads on. Every report reads this cell first, so modelx and the compiled model refuse such a point alike. The two References are the contract the caches hold: lowering issue_age_min or raising maturity_age needs the spec’s sizes raised and the model rebuilt, as a longer Data.future_horizon_mth does. The shipped mortality and net single premium tables start at age 18, so a point issued younger is refused by the first of them it reads, naming the point and the age.

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: pols_if_at() opens there from pols_if_init(), pua_face(), div_accum() and prem_cum() open from the model point’s opening state, and every balance read a month or a year back is read from the opening state where that month is before it. No cell in cover reads a month before it.

policy_term()[source]#

m: the premium-paying period in years, from the premium period code.

This is not the coverage period, which runs to maturity_mth() in every variant. It stays in years because the contract states it in years; premium_pp_ann() compares it against duration(t). Read off premium_period_code(): TO_100 to maturity, PAY_10 and PAY_20 their years, and TO_65, the one code left, since Data refuses any other period, to attained age 65, a year at least. WholeLife_US_S raises invalid premium_period here on any other text; Data refuses it by name instead.

duration_mth(t)[source]#

Completed policy months at the start 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. Negative before issue. Everything contractual reads this clock, through duration(), policy_year(), age() and is_anniv(), and the monthly vocabulary reads the same here as in the UL family and savings.CashValue_SE.

is_active(t)[source]#

Whether month t is inside cover: issued, and not yet matured.

0 <= duration_mth(t) < maturity_mth(). False before issue and from the month after the one ending at attained age 100. Outside cover every count is zero, and so every cash flow; so is every value state and every dividend, no count cell evaluates a rate there, and no table is read at a policy year or an attained age the policy does not have.

duration(t)[source]#

Completed policy years at the start of month t, duration_mth(t) // 12.

0 throughout the first policy year, and negative before issue. Every contractual schedule in this product is annual, so this is what the attained age, the cash value schedule, the premium period and the decrement vectors are all read at.

policy_year(t)[source]#

The contractual policy year containing month t, duration(t) + 1.

A 1-based label on the policy clock, never indexed by: it is the policy_year key of cv_table.csv. It is 0 or less before issue, where nothing reads a table by it.

is_anniv(t)[source]#

True in the last month of a policy year, where every annual event lands.

The dividend is declared and credited here, loan interest capitalizes here, and paid-up additions are bought here. duration_mth(t) % 12 == 11 inside cover, and False outside it: the month before issue, policy month -1, is no anniversary.

anniv_mth(t)[source]#

The month of the anniversary that ends the policy year containing t.

A valuation month, t + 11 - duration_mth(t) % 12: t itself when is_anniv() is true, and never past the last covered month, proj_len() - 1, since the frame ends on an anniversary. It is 11 at t = 0 for the anchor cell, whose tenth anniversary is WholeLife_US_S’s month 119: WholeLife_US_S returns the policy month 12 * duration(t) + 11, the same number only where the two clocks coincide. Used by the term-blend layer, which is bought at that anniversary and is in force for the whole of the policy year it closes, and, twelve months back, by div_prev_anniv().

age(t)[source]#

The attained age x + duration(t) entering the policy year containing month t.

Mortality in that policy year is indexed here; paid-up additions bought at the anniversary that ends it are priced at age_anniv(t).

age_anniv(t)[source]#

The attained age at the anniversary that ends the policy year containing month t.

mec_flag()[source]#

True where the model point would need a Sect. 7702A test this model does not run.

The notes are explicit that the reference model does not police Sect. 7702 or Sect. 7702A limits and should flag model points that would fail rather than silently projecting them [std]. Limited-pay designs sit near the 7-pay limit and paid-up-additions rider payments consume 7-pay room, so both raise the flag.

premium_rate()[source]#

Final-expense annual premium per $1,000 of face, from premium_rates.csv [S7].

The rate Data.premium_rate_per_1000 joined to the point by its product, sex, risk_class and issue age, as WholeLife_US_S looks it up. Only final expense reads it. A point the table has no rate for is refused here, naming it, where WholeLife_US_S’s lookup raised KeyError: Data does not refuse it, since a participating point has none and reads none.

modal_factor()[source]#

The fraction of the annual premium collected per instalment [S1] [S7].

The participating design takes the [S1] scale — semi-annual 0.515, quarterly 0.26265, monthly 0.085833 — and the final-expense variant the [S7] scale printed on its own rate card — 0.52, 0.275, 0.089. Both are sourced, and both carry the modal loading inside the factor, so twelve monthly instalments come to 1.03 of the annual premium on the participating design and 1.068 on final expense. Each factor is its own Reference, so a carrier’s own scale drops in without a formula change.

The mode is read as its cycle, prem_cycle(): 12 months annual, 6 semi-annual, 3 quarterly and, the one cycle left, since Data refuses any other mode, 1 monthly. WholeLife_US_S raises invalid premium mode here on any other text; Data refuses it by name instead.

prem_cycle()[source]#

Months between premium instalments: A 12, SA 6, Q 3, M 1, from Data.prem_cycle.

Arithmetic of the mode rather than an assumption, so Data decodes it from the model point’s premium_mode rather than hold it in a Reference.

prem_due(t)[source]#

Whether a modal premium instalment falls due at the beginning of month t.

Instalments start on the policy anniversary and repeat on the mode’s own cycle on the policy clock, duration_mth(t) % prem_cycle() == 0: annual in the first month of each policy year, semi-annual every sixth month, quarterly every third, monthly every month. None falls due outside cover. A point in force mid-year pays its next instalment on that cycle, so the loan variant in force 114 months, on annual mode, pays nothing until t = 6.

premium_pp_ann(t)[source]#

G: the gross annual premium per policy for the policy year containing month t.

Level and guaranteed through the policy_term() premium-paying years duration(t) = 0 .. policy_term() - 1, zero after, and zero outside cover, where the policy has no policy year. The participating design takes G from the model point, annual_premium() ([std illustrative] — carrier rate books are not public); the final-expense variant computes it from the sourced rate table as (F / 1000) * rate(x, sex, class) + 36 [S7].

This is the notes’ G and the base for the acquisition expense, the premium offset and the paid-up-additions purchases, none of which should move with the premium mode; premium_pp() is what is actually collected in month t.

premium_net_pp_ann(t)[source]#

G^net_t: the annual premium actually charged for the policy year of month t.

Under REDUCE_PREM the dividend credited at the anniversary opening that policy year offsets the premium, max(G - D, 0), and any excess buys paid-up additions through pua_face_offset(). The dynamic premium-offset overlay ([std], off by default) applies a prem_offset_share fraction of the same offset once the dividend has grown to cover the premium. For the policy year under way at the valuation date that dividend is the model point’s div_prev_anniv_init(): point 16, the REDUCE_PREM policy valued on the anniversary that opens its tenth year, pays 1,800.00 less last year’s 288.66 at t = 0.

premium_pp(t)[source]#

The gross premium instalment per policy due at the beginning of month t.

modal_factor() * G in an instalment month, zero otherwise: what the policy is billed before any dividend offset. premium_net_pp() is what is actually collected, and the two differ only under REDUCE_PREM and the premium-offset overlay.

premium_net_pp(t)[source]#

The premium per policy actually collected at the beginning of month t.

modal_factor() * G^net in an instalment month, zero otherwise. The dividend offset is applied to the annual premium and the instalments then split what is left [std], so a mode change moves the timing of the collection and not the amount the offset absorbs. This is what premiums() is weighted from.

rider_premium_pp_ann(t)[source]#

A_t: the annual paid-up-additions rider premium for the policy year of month t.

Level while base premiums are payable [std], the model point’s pua_rider_premium(); the notes set it within limits fixed at issue and do not schedule it. Zero outside cover.

rider_premium_pp(t)[source]#

The paid-up-additions rider instalment paid at the beginning of month t.

The rider is billed with the base premium, so it follows the same modal cycle and the same factor [std].

prem_cum(t)[source]#

Cumulative gross premium paid per policy through the beginning of month t.

Only the final-expense graded plan uses it, for the 110%-of-premiums-paid death benefit in policy years 1-2 — and on the monthly grid it now grows with each instalment rather than once a year, which is what the graded benefit actually tracks [S6][S7]. That design is non-participating, so gross and net coincide there. It counts from issue: at t_entry() it opens from prem_cum_init(), the premiums paid before the valuation date, 0 for a point issued at or after it. Zero outside cover.

cv_pp_anniv(y)[source]#

The guaranteed cash value per policy at the anniversary ending policy year y.

The schedule as it is printed: cv_table.csv per $1,000 of face, keyed by the contractual 1-based policy_year. Zero for y <= 0 — there is no cash value at issue — and zero past maturity, y > maturity_mth() // 12, the years from issue to maturity.

The notes give the Standard Nonforfeiture Law adjusted-premium formula conceptually but prescribe a table input in practice, because contractual cash value tables are policy-form documents that are not public. The shipped schedule is [std], calibrated to the worked example’s CV_107 and CV_119 — the policy-year 9 and 10 rows — and reaching exactly face at attained age 100.

It is sex-distinct, as the notes require of every rate in this product: the male pay-to-100 schedule carries the worked example’s anchors, and the female schedule is that schedule’s funding-progress shape f = CV^M / (F NSP^M_{x+dur+1}) applied to the female paid-up value F NSP^F_{x+dur+1} [std]. The shape — how far along the way to paid-up status the schedule has come — is a design choice that does not depend on sex; the value it is progressing towards does, through NSP. See the guarantee-basis rubric in the Space docstring for what this construction is not.

The one reader of Data.cv_array, at the point’s schedule, cv_schedule(), and year y. A year outside the schedule’s extent, Data.cv_year_first to Data.cv_year_last, raises ValueError, naming the point and the year, where WholeLife_US_S’s lookup raised KeyError, rather than reading the array’s padding; a point whose key has no schedule, schedule 0, is refused at every year.

cv_schedule()[source]#

The point’s cash value schedule, its row of Data.cv_array, from Data.cv_schedule.

The schedule of its premium period, sex and issue age, the key WholeLife_US_S looks the cash value up by; 0 where the table has none.

cv_pp(t)[source]#

CV_t: the guaranteed cash value per policy at the end of month t.

Straight-line between the schedule’s anniversary values [std]: (k + 1) / 12 of the way from cv_pp_anniv(duration(t)) to cv_pp_anniv(duration(t) + 1), where k = duration_mth(t) % 12. Exact at the anniversary, where k = 11, so no anniversary quantity — the dividend’s interest margin, the net amount at risk, the anniversary surrender value — moves by a cent against the annual grid.

Contractual tables are printed at anniversaries only [unverified]; pro-rating for elapsed time is the ordinary policy-form convention, and it is what makes a mid-year surrender value mean anything on this grid. Zero outside cover, before the schedule is read.

net_amt_at_risk(t)[source]#

F - CV_t: the guarantee-basis net amount at risk carried by the mortality margin.

nsp(y)[source]#

NSP_y: net single premium per 1 of paid-up endowment-at-100 face at attained age y.

The purchase basis for paid-up additions, unloaded, on the guarantee basis [std]. NSP_100 = 1 by construction, which is what makes the paid-up-additions cash value equal paid-up-additions face at maturity.

The shipped curve is not the endowment-at-100 net single premium implied by mort_table.csv at 4%, and cannot be: see the guarantee-basis rubric in the Space docstring, which shows that the worked example’s own anchors rule out any single mortality basis at 4%.

The one reader of Data.nsp_array, at the point’s schedule, nsp_schedule(), and age y. An age outside the schedule’s extent, Data.nsp_age_first to Data.nsp_age_last, raises ValueError, naming the point and the age, where WholeLife_US_S’s lookup raised KeyError.

nsp_schedule()[source]#

The point’s net single premium schedule, its row of Data.nsp_array: that of its sex, 0 where the table has none, from Data.nsp_schedule.

nsp_mth(t)[source]#

The net single premium interpolated to the end of month t [std].

The same straight line cv_pp() takes, between NSP_{age(t)} and NSP_{age_anniv(t)}, so the paid-up-additions block is valued on the same clock as the base cash value. Exact at the anniversary, where it is NSP_{age_anniv(t)} — which is what keeps pua_cv equal to pua_face in the final month, where NSP_100 = 1. Zero outside cover, before the table is read at an age the policy does not reach in force.

np_guar()[source]#

NP_g: the nonforfeiture net level premium per policy, from np_guar_table.csv.

The dividend’s interest margin is credited on the guaranteed fund including the year’s net premium, so this quantity sits inside div_int() [std].

The notes define it over the endowment period, NNLP = F NSP_x / ae_{x:(100-x)}, and annotate the other nonforfeiture quantity — the adjusted premium P_adj — with “(m = premium period)”, so the (100 - x) subscript is deliberate: NNLP does not vary with the premium period. The shipped table therefore carries one value per (sex, issue age), repeated across the premium periods; the premium_period key is kept so a carrier table that does vary by m can be dropped in without a formula change.

The premium is Data.np_guar_per_1000, joined to the point by its premium period, sex and issue age, as WholeLife_US_S looks it up. Only the participating dividend reads it. A point the table has no premium for is refused here, naming it, where WholeLife_US_S’s lookup raised KeyError: Data does not refuse it, since a final-expense point reads none.

mort_rate_guar_at(y)[source]#

q^g_y: the guaranteed annual mortality rate at attained age y.

Read from mort_table.csv. The shipped table is [std] illustrative and is not the 2017 CSO the notes name; that table is licensed and cannot be shipped here.

The one reader of Data.mort_table_array, at the point’s schedule, mort_schedule(), and age y. An age outside the schedule’s extent, Data.mort_age_first to Data.mort_age_last, raises ValueError, naming the point and the age, where WholeLife_US_S’s lookup raised KeyError, rather than reading the array’s padding.

mort_schedule()[source]#

The point’s guaranteed mortality schedule, its row of Data.mort_table_array: that of its sex, 0 where the table has none, from Data.mort_schedule.

mort_rate_guar(t)[source]#

q^g: the annual guarantee rate at the age entering the policy year of month t.

Zero outside cover, before the table is read at an age the policy does not reach in force, so the scale and best-estimate rates built on it are zero there too.

mort_rate_scale(t)[source]#

q^sc: the dividend scale’s annual experience mortality, ae_scale x q^g [std].

mort_rate(t)[source]#

q^e: the annual best-estimate mortality rate of the policy year of month t.

ae_best_est x q^g [std]. The notes’ sensitivity list flags this as a consistency trap: the same table drives claim outgo here and the dividend’s mortality margin through mort_rate_scale(), with opposite signs. mort_rate_mth() is the rate actually applied in the month.

Capped at 1, written min(q, 1.0), as WholeLife_US_S caps it: past 1 the monthly rate 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. No shipped point reaches the cap.

mort_rate_mth(t)[source]#

The monthly best-estimate mortality rate applied in month t [std].

1 - (1 - q^e)^(1/12), so twelve months of it compound back to exactly the policy year’s annual rate and the in-force at every anniversary is what the annual grid carried.

dyn_lapse_factor(t)[source]#

The interest-sensitive lapse multiplier [std], for scenario runs.

min(1 + 2.0 * max(0, r_cmp - i_d - 0.01), 3.0), where r_cmp is the competitor or market rate in the scenario. Off unless dyn_lapse_on; the calibration is judgmental and the research base records no dynamic-lapse study for whole life.

lapse_rate(t)[source]#

w_t: the annual surrender rate of the policy year containing month t [std].

Participating: 5.0% in policy year 1 grading linearly to 2.0% in policy year 10, level 2.0% thereafter. Final expense (simplified issue, so heavier): 12% in year 1, 10% in year 2, grading linearly to 6% by year 5 and level after. Zero in the final policy year — the notes’ “0 through the final policy year”, the year with duration(t) = maturity_mth() // 12 - 1 — so that its survivors mature rather than surrender.

lapse_rate_mth(t)[source]#

The monthly surrender rate applied at the end of month t [std].

1 - (1 - w)^(1/12) on the policy year’s annual rate. Surrenders are now settled where they happen, against an interpolated cash value, rather than being collapsed onto the anniversary.

div_prev_anniv(t)[source]#

D_{t-1}: the dividend credited at the anniversary that opened the policy year containing month t.

That anniversary is the end of valuation month anniv_mth(t) - 12. Where that month is on the books, at or after t_entry(), the dividend is the one this projection credited there. Where it is before, the policy year opened before the projection did, and the dividend is the model point’s div_prev_anniv_init(): the one credited at the anniversary on or before the valuation date for a point in force, and 0 for a point in its first policy year or issued at or after the valuation date. Zero outside cover.

Every annual use of “last year’s dividend” — the REDUCE_PREM offset, the premium-offset overlay, the excess that buys paid-up additions — reads it here, so those rules keep working whichever month of the policy year the premium falls in.

div_int(t)[source]#

D^int_t: the dividend’s interest margin at the anniversary ending month t [std].

(i_d - i_g)(CV_{t-12} + NP_g - L_{t-12}) + (i_L - i_g) L_{t-12}, with direct recognition: the loaned portion is credited at the loan rate rather than the portfolio dividend rate. With the snapshot i_L = i_d = 6.00% the adjustment is zero, which is a coincidence of the snapshot and not a model property. Zero in every month that is not an anniversary, as the dividend it is a margin of is, so zero outside cover too, before the schedule is read.

CV_{t-12} and L_{t-12} are the balances entering the policy year that the anniversary closes. The cash value is the schedule’s own value at the anniversary that opened it, cv_pp_anniv(duration(t)), zero at issue, and the loan the closing balance of the month twelve back, or, where that month is before t_entry(), the model point’s loan_bal_prev_anniv_init(). At the anniversary that is WholeLife_US_S’s value, which reads the cash value as the closing cv_pp of the month twelve back, for a point in force a month that may precede the valuation date. WholeLife_US_S’s cell also answers in the other months, where nothing reads it, and this one is zero there.

div_mort(t)[source]#

D^mort_t: the dividend’s mortality margin, (q^g - q^sc)(F - CV_t) [std].

div_exp(t)[source]#

D^exp_t: the dividend’s expense margin, a flat per-policy amount [std].

div_base(t)[source]#

D_t: the base-block dividend credited at the anniversary ending month t.

max(D^int + D^mort + D^exp, 0), rounded to div_round_digits decimal places with Python’s round, unrounded where div_round_digits is below -400, and zero in every month that is not an anniversary — the declaration is annual [S1] — so zero outside cover too. The floor is [std]: dividends are non-negative distributions of surplus, so adverse experience does not claw back. No dividend is credited before policy year div_first_year — that is, for duration(t) < div_first_year - 1 — a real cross-carrier design split that the notes keep as a parameter, and none at all on the non-participating final-expense design.

round is the one Python call a projection cell keeps when the model compiles: rounding a projected amount cannot be precomputed, and tests/us_registry.py admits it in this cell alone (the Space docstring’s Reporting cells). Compiled, it is the same call, so the dividend is the same float.

div_pua(t)[source]#

D^PUA_t: the dividend earned by the paid-up-additions block [std].

(i_d - i_g) PUACV_{t-12} + (q^g - q^sc)(PUAF_{t-12} - PUACV_{t-12}), on the block entering the policy year this anniversary closes — the closing block of the month twelve back, or, where that month is before t_entry(), the model point’s pua_face_prev_anniv_init(), valued at NSP_{x+dur}. Paid-up additions are dividend-eligible, and the compounding this creates is the notes’ first-ranked sensitivity. Switched off by pua_div_on in the shipped base run because the worked example’s table omits it; see the Space docstring. Zero outside cover, where no month is an anniversary.

div_credited(t)[source]#

D_t + D^PUA_t: the whole dividend credited to survivors at the end of month t.

Non-zero only at an anniversary, which is where the declaration falls, and zero outside cover.

oyt_face(t)[source]#

OYT_t: the one-year-term face the term-blend rider carries through the policy year containing month t.

The layer is bought at the anniversary that closes that policy year, from that year’s dividend, and is a one-year term: it is level for the twelve months, which is why this cell is constant within the policy year rather than only defined at the anniversary. The amount is max(TF - F - PUAF_{prev}, 0), capped at what the dividend can fund [std]. Two readings had to be settled here, and both are standardizations:

The notes write the gap as TF - F - PUAF_t, which is circular — the term cost is deducted from the dividend that buys those very additions — so the model uses the paid-up-additions face entering the policy year: the closing balance of the month twelve before its anniversary, or, where that month is before t_entry(), the model point’s pua_face_prev_anniv_init().

The notes are also silent on what happens when the dividend cannot pay for the whole gap. Leaving the formula uncapped would report a term face the model never charges for and would inflate the death benefit, so the layer is capped at D_t (1 + i_g) / q^sc_{x+dur+1} — as much term as the dividend actually buys.

Whether the cap binds is a property of how the blend is funded, not of the design. On model point 8, where a $5,000 paid-up-additions rider premium funds the 2x target, it binds only in policy year 1, where no dividend is payable at all under div_first_year = 2, and the gap closes in policy year 8. On model point 14, the same 2x target with no rider premium, it binds in policy years 1-3 while the dividend is small and again in every year from the thirtieth on as q^sc outruns it, and the block never crosses over. Crossover, after which the rider is pure paid-up additions, is where the gap itself reaches zero.

So every month of a policy year reads the dividend of the anniversary that ends it, div_credited() at anniv_mth(), up to eleven months ahead: the one read this model makes further ahead than the month after its own. It opens no chain forward. That dividend depends on the balances entering the year and on the schedules alone, never on this layer or on a month after the anniversary, and the anniversary is never past the last covered month. Zero outside cover.

oyt_cost(t)[source]#

The dividend absorbed by the one-year-term layer at the anniversary [std].

q^sc_{x+dur+1} x OYT_t x v_g, charged once a year against the dividend that buys the layer, so it is zero in every month that is not an anniversary.

div_to_pua(t)[source]#

The part of the credited dividend that buys paid-up additions at the end of month t.

Under the PUA option, everything left after the term-blend cost. Under CASH it is paid out, under ACCUM it goes to div_accum(), and under REDUCE_PREM it offsets the next policy year’s premium with the excess handled by pua_face_offset() — except at the final anniversary, the last covered month, where there is no following policy year to offset. The notes are silent on that last dividend; routing it anywhere else would drop it, so the whole of it is treated as REDUCE_PREM excess and buys paid-up additions at NSP_100 = 1 [std], which is the same rule the option already applies in every year whose premium the dividend has outgrown. Zero outside cover.

div_cash(t)[source]#

D^cash_t: the cash dividend paid per surviving policy at the end of month t.

div_accum(t)[source]#

DA_t: the dividend accumulation balance at the end of month t.

DA_{t-1}(1 + i_d)^(1/12) + D_t under the ACCUM option, zero otherwise and zero outside cover. The balance entering t_entry() is the model point’s div_accum_init(): zero for a point issued at or after the valuation date — the notes’ DA = 0 initialization — and the balance built up before it for a point in force. The balance now accrues interest monthly, so twelve months of it compound to exactly the annual credit the notes state, and the dividend lands on it at the anniversary. The credit rate reuses the dividend interest rate [std]: one carrier announces its accumulation rate annually with the dividend scale [S2], and no separate figure is published. The balance adds to the death, surrender and maturity proceeds.

pua_face_purch(t)[source]#

dPUAF_t: paid-up-additions face bought by the dividend, div / NSP_{x+dur+1}.

Non-zero only at an anniversary, where the dividend is credited, and priced at the attained age reached there — the notes’ NSP_{x+dur(t)+1}.

pua_face_rider(t)[source]#

dPUAF^rider_t: paid-up-additions face bought by the rider instalment paid in month t.

A (1 - load) / NSP, a 10% load [std] chosen from the observed 7.5%-10% range on rider payments. Dividend purchases carry no load; only rider payments do. Each instalment buys additions when it is paid, priced at the net single premium where the payment falls, the start of month t — k / 12 of the way from NSP_{age(t)} to NSP_{age_anniv(t)}, k = duration_mth(t) % 12, on the straight line nsp_mth() draws, so NSP_{age(t)} itself at the anniversary — so a monthly-mode rider buys twelve small layers through the year rather than one at the anniversary. WholeLife_US_S reads the same price as nsp_mth at the month before, which for a point valued mid-year would be a month before the valuation date.

pua_face_offset(t)[source]#

Paid-up-additions face bought by the REDUCE_PREM excess, when the premium falls.

Once the prior anniversary’s dividend exceeds the annual premium it is offsetting, the excess buys paid-up additions [std] rather than being paid out. It is applied in the month the policy year’s premium is first due, and priced at the attained age entering that policy year. It carries the dividend of the anniversary that opened the policy year, so it can never carry the final one; that last dividend is routed through div_to_pua() instead — see its docstring. Zero outside cover.

pua_face(t)[source]#

PUAF_t: paid-up-additions face in force at the end of month t.

PUAF_{t-1} plus the dividend, rider and premium-offset purchases of month t. The opening balance at t_entry() is the model point’s pua_face_init(), which is what makes the worked example’s stipulated prior balance of 4,100 an input rather than a projection, and 0 for a point issued at or after the valuation date. Zero outside cover.

pua_cv(t)[source]#

PUACV_t: the cash value of the paid-up additions, PUAF_t x nsp_mth(t) [std].

Valuing the whole block at the attained-age net single premium is exact at the issue of each layer and again at age 100, and approximate in between; the monthly interpolation of NSP puts it on the same clock as the base cash value. Zero outside cover.

loan_int(t)[source]#

Loan interest capitalized at the anniversary ending month t, L_{prev anniv} x i_L.

Capitalization is contractually annual [S1], so it lands on the anniversary and is zero in every other month, and outside cover. The balance it is charged on is the one outstanding at the previous anniversary: the closing balance of the month twelve back, or, where that month is before t_entry(), the model point’s loan_bal_prev_anniv_init().

loan_bal(t)[source]#

L_t: the policy loan balance at the end of month t [std].

The notes’ variant holds the loan at loan_utilization x CV_t, maintained by borrowing and repaying as the cash value moves; the base run sets loan_utilization to zero. Because cv_pp now moves monthly, so does the balance. Loans reduce the death, surrender and maturity proceeds. A point in force at the valuation date is held at the same fraction from month 0 on, whatever its loan_bal_init(), and month 0’s loan_draw() closes any gap between the two. Zero outside cover.

loan_draw(t)[source]#

Net new borrowing per policy in month t; negative repays.

The balance change net of the interest that capitalized into it, so the cash the insurer actually advances. Summed over a policy year it is exactly the annual grid’s single advance, because the interest term lands once, at the anniversary. The balance entering t_entry() is the model point’s loan_bal_init(), 0 for a point issued at or after the valuation date. Zero outside cover.

claim_pp(t, kind)[source]#

The benefit amount per policy in month t, by kind.

DEATH

DB_t = F + PUAF_{t-1} + OYT_t + DA_{t-1} - L_{t-1}. Deaths fall at the end of the month, and at an anniversary before the dividend is credited, so the benefit carries the paid-up additions, accumulation balance and loan entering the month [std] — the closing balances of month t - 1, or the model point’s opening state at t_entry(). The one-year-term layer is the one in force through the policy year, where F + PUAF + OYT is the notes’ “target face plus excess paid-up additions” written so that it still holds when the dividend funds only part of the gap. On the final-expense graded plan, natural-cause deaths in policy years 1-2 pay 110% of cumulative premiums paid and accidental deaths pay the full face from day one [S6][S7]; the two are blended by fe_accid_share [std], since the model carries one mortality decrement. Zero outside cover.

LAPSE

CSV_t = CV_t + PUACV_t + DA_t - L_t, the surrender value at the end of month t, including any dividend just credited. Both cash value components interpolate between anniversaries, so a mid-year surrender is valued where it happens.

MATURITY

MAT = F + PUAF + DA - L at the end of the last covered month, duration_mth(t) = maturity_mth() - 1, which is t = proj_len() - 1, and zero in every other month. On the non-participating design this is F - L.

The kinds are int References, 0 to 2 (the Space docstring’s Codes), and any other raises ValueError("invalid kind").

pols_if_at(t, timing)[source]#

The number of policies in force at a point inside month t.

The timings in processing order, int References 0 to 4 (the Space docstring’s Codes):

BEF_NB

the count carried in from month t - 1, before month t’s new business: the survivors of month t - 1’s deaths and surrenders, out of month t - 1’s BEF_DECR count. At t_entry(), the first month on the books, 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. Zero outside cover, so the survivors of the last covered month leave as pols_maturity().

BEF_DECR

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

BEF_SURR

after deaths, before surrenders — the population the dividend is credited to and the one surrenders are taken from.

BEF_MAT

after surrenders, before maturity; the survivors of the month. It is WholeLife_US_S’s "BEF_MAT", at the end of the month, and not basiclife.BasicTerm_SE’s, which counts the policies at the start of a month, before that month’s maturities: the name is shared, the instant is not.

AFT_DECR

l_{t+1}, the notes’ end-of-period state variable: what is left once the month’s deaths, surrenders and — in the last covered month — the maturities have all been taken, so it is zero there and outside cover. It is pols_if_at(t + 1, BEF_NB) by construction, the count carried into the next month before that month’s new business. The name is added to CashValue_SE’s set because that model has no name for the point past the last decrement, which is where these notes keep their in-force probability.

BEF_NB and BEF_DECR are basiclife.BasicTerm_SE’s names, and any timing but these five raises ValueError("invalid timing"). BEF_NB forms the count left at the end of month t - 1 itself — month t - 1’s BEF_NB plus its pols_new_biz(), after its deaths and surrenders, the products BEF_MAT takes in the order it takes them — rather than calling for it. So the chain of calls from month t back to t_entry() is one cell a month, where WholeLife_US_S’s ran through five: a compiled model runs that chain on the C stack. Every count is zero outside cover, before any rate is read.

pols_if(t)[source]#

The number of policies in force at the start of month t, the weight of row t.

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 — the population that pays the month’s premium, carries its expenses and is exposed to its decrements, so it is the weight on every cash flow of the same result_cf() row. On a point issued at t = 0 it is exactly WholeLife_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 outside cover: before issue, and from t = proj_len() on, because everything still in force in the last covered month matures there and the contract terminates.

It is basiclife.BasicTerm_SE’s BEF_DECR count, not its pols_if, which is the count before maturity. The notes’ end-of-period l_{t+1} is pols_if_at(t, AFT_DECR).

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]#

Deaths in month t, the monthly rate applied to the policies in force at its start.

Zero outside cover.

pols_lapse(t)[source]#

Surrenders at the end of month t, the monthly rate applied to its survivors.

Zero outside cover.

pols_maturity(t)[source]#

Policies maturing at attained age 100; non-zero only in the last covered month.

That month is duration_mth(t) = maturity_mth() - 1, the frame’s last row, t = proj_len() - 1. Not a decrement — the modelled contract simply ends — but the in-force roll-forward does not close without it.

inflation_factor(t)[source]#

The expense inflation factor in month t, (1 + inflation_rate) ** (t / 12).

On the valuation clock: t counts months from the valuation date, so the maintenance charge it inflates is in valuation-date dollars, whatever the policy’s age, and every point of a block inflates alike. WholeLife_US_S inflates from issue; on a point issued at t = 0 the two are the same, and on the anchor cell, in force 108 months, this model’s charge is WholeLife_US_S’s divided by 1.02^9. Acquisition is not inflated (see expenses()). Compounded on the monthly grid rather than stepped at anniversaries: on the annual grid the factor could only move once a year, and the monthly refinement is one of the things the finer grid buys. It is still exactly 1.02^k k years after the valuation date.

premiums(t)[source]#

Premium income at the start of month t (an inflow), net of any dividend offset.

rider_premiums(t)[source]#

Paid-up-additions rider premium income at the start of month t (an inflow).

premium_taxes(t)[source]#

Premium tax at the start of month t [std], on premium and rider income.

The notes’ processing order collects it alongside the expenses; their one-line NetCF formula omits it. The model follows the processing order and keeps it as its own line, so it now falls with each instalment rather than once a year.

expenses(t)[source]#

E_t: acquisition and inflating maintenance expense in month t [std].

90% of the first year’s annual premium plus $250 per policy issued — charged in the issue month, on pols_new_biz(), and not inflated, as in basiclife.BasicTerm_SE — then $60 per policy per year inflating at 2% on the valuation clock, accruing at a twelfth a month on the policies in force at the start of the month. The acquisition charge does not move with the premium mode, and a point in force at the valuation date never sees it, because it was issued before. WholeLife_US_S charges it at t = 0 on the policies in force there, which on a point issued at t = 0 is the same charge.

claims(t)[source]#

Benefit outgo in month t: death, surrender and maturity claims together.

claims_death(), claims_lapse() and claims_maturity(), summed left to right from 0.0, the total liability_cf() carries. WholeLife_US_S’s claims(t, kind=None) is both the three kinds and their total, a generator summed by Python’s sum, which compiles to neither a C parameter nor a C loop; here the kinds are three cells, the result_cf columns, and this is their total. Python’s sum of floats is compensated, so a total written out is WholeLife_US_S’s float only where at most two of the three are non-zero, and that holds in every month: maturities fall in the last covered month alone, where lapse_rate is 0. Its 0.0 start keeps sum’s, which turns three zeros’ signs to 0.0.

claims_death(t)[source]#

Death claims in month t: pols_death() at the death benefit per policy, claim_pp(t, DEATH). The claims_death column of result_cf().

claims_lapse(t)[source]#

Surrender claims at the end of month t: pols_lapse() at the surrender value per policy, claim_pp(t, LAPSE). The claims_lapse column of result_cf().

claims_maturity(t)[source]#

Maturity claims in month t, non-zero in the last covered month alone: pols_maturity() at claim_pp(t, MATURITY). The claims_maturity column of result_cf().

div_cash_paid(t)[source]#

Cash dividends paid out at the end of month t, to the survivors of the month.

loan_draws(t)[source]#

Net policy loans advanced at the end of month t [std], an outflow.

The notes report gross liability flows plus a separate loan account rather than netting the loan into a net-amount-at-risk presentation. Advances go to the policies still in force; the balance is recovered through the death, surrender and maturity benefits, which are all net of the loan.

liability_cf(t)[source]#

NetCF_t: the net liability cash flow in month t, outgo positive.

The technical notes’ formula verbatim, and the one to compare against them: premium and rider income enter with a minus sign; expenses, premium tax, death, surrender and maturity benefits, cash dividends and net loan advances enter with a plus, so a positive value is money leaving the insurer. Internal dividend applications — paid-up additions, accumulation, premium reduction — are not cash flows when credited: they emerge later through the death benefit, the surrender value and the maturity benefit.

These notes are the only ones in the library that print the outgo-positive sign, so the stream is published twice: here under the notes’ sign, and negated as net_cf(t) under the library’s. See the sign-convention rubric in the Space docstring.

net_cf(t)[source]#

The net cash flow in month t, income positive: -liability_cf(t).

Income less outgo, the sign every model in products/ carries, so that a result_cf()["net_cf"] column can be summed or compared across products. A positive value is money arriving at the insurer. liability_cf(t) is the same stream under the technical notes’ own outgo-positive sign; both are result_cf() columns because neither reading may be lost.

result_cf()[source]#

Result table of cashflows, one row per month t = 0 .. proj_len() - 1.

Row 0 is the valuation month for every model point, so the frames of a block line up and sum row by row, and a point issued after the valuation date has zeros until its issue month. The columns are WholeLife_US_S’s. pols_if is the start-of-month count, which is the weight applied to every cash flow on the same row. Both signs of the net flow are published: net_cf is income-positive, the library-wide convention, and liability_cf is the technical notes’ outgo-positive NetCF_t; the two are negatives of each other.

result_cf_annual()[source]#

result_cf() summed into policy years, indexed by policy_year.

Every cash flow column is the total of the year’s months in the frame, and pols_if is the count in its first month in the frame. The months before issue belong to no policy year and are left out. On a point issued at t = 0 every year is whole, pols_if is the count at the start of the policy year, which is the number the annual-step model carried on the same row, and the table is WholeLife_US_S’s. A point in force at the valuation date may open part-way through a policy year, as the loan variant in force 114 months does: its first row then holds the rest of that year only, and its pols_if is the count at the valuation date. The two grids agree on pols_if exactly and on nothing else, which is the point of the finer one — see the Space docstring.

result_pols()[source]#

Result table of policy counts and decrement rates, indexed by t.

One row per month t = 0 .. proj_len() - 1. 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 surrenders in processing order, and the maturities of the last covered month. Row by row, pols_if at t + 1 is pols_if less the three outflows of month t, plus the new business of month t + 1. Then WholeLife_US_S’s four decrement rates, annual and monthly, which are 0 outside cover, where the model reads no rate.

result_cv()[source]#

Result table of the guaranteed and non-guaranteed values, indexed by t.

The account-value analogue for this product: the guaranteed cash value, the paid-up-additions block, the accumulation balance and the loan, plus the dividend that drives them and the two benefit amounts they feed. Every balance on row t is the closing value of month t. One row per month t = 0 .. proj_len() - 1, zeros before a point’s issue.

check_pols_roll_fwd_resid(t)[source]#

The in-force roll-forward residual in month t; zero everywhere.

pols_if(t) - pols_if_at(t + 1, BEF_NB) - deaths - surrenders - maturities, the notes’ l_t - l_{t+1} - ..., where l_{t+1} is the count carried into the next month before its new business, which is no part of month t’s movement. Maturities are non-zero only in the last covered month, where the survivors neither die nor surrender: their contract ends. Without that term the last month appears to lose lives with no cause.

check_pols_roll_fwd()[source]#

True when the in-force roll-forward closes in every projected month.

The library-wide form of a roll-forward check: no argument, one bool over all t, so one test can call it across every model. check_pols_roll_fwd_resid(t) gives the signed residual of the month that failed. The tolerance scales with policy_count(), since the residual is an accumulation of rounding on that many policies, in force at the valuation date or issued after it.

check_pua_roll_fwd_resid(t)[source]#

The paid-up-additions roll-forward residual in month t; zero everywhere.

PUAF_t - PUAF_{t-1} - dividend purchases - rider purchases - offset purchases, with PUAF_{t-1} the block entering the month — pua_face_init() at t_entry(). The analogue of CashValue_SE.check_av_roll_fwd for a product whose accumulating state is a face amount rather than an account value.

check_pua_roll_fwd()[source]#

True when the paid-up-additions roll-forward closes in every projected month.

No argument, one bool over all t, matching check_pols_roll_fwd(); check_pua_roll_fwd_resid(t) gives the signed residual. The tolerance is relative to the block itself, which reaches six figures of face on a compounding projection.