In-Force Implementation Notes#
Status: Draft, 2026-11-01. WholeLife_US_SEC is WholeLife_US_S taught
to project from a valuation date. Besides policies issued at that date, it takes policies
already in force there, in any month of their policy year, and policies to be written in
the ten years after it, as lifelib’s basiclife/BasicTerm_SE extends
basiclife/BasicTerm_S. The product is the one product-spec.md
specifies and technical-notes.md models; this page says what
running in force changes, and how the model compiles. The suffix adds lifelib’s letters to
S: E for in force, as in BasicTerm_SE, and C for the compiled form, as in
basiclife/BasicTerm_SC: the same formulas compile under modelx-cython, from
sample_sec.py and spec_sec.py beside the model.
This is a mechanics demonstration, not a pricing or reserving result. The model is
WholeLife_US_Son another time axis, and it readsWholeLife_US_S’s assumption tables in place, every assumption unchanged. The contractual skeleton is sourced, the final-expense rate card [S7] among it, and everything else is a std standardization, including all four guarantee-basis tables: illustrative curves calibrated to the worked example’s anchors, not the 2017 CSO / 4% tables the notes name, and not even one basis between them, asmodel.mdsets out. Replace them with company data before drawing any conclusion from the numbers.
Run it#
python products/whole_life/run_sec.py # point 1: the anchor cell, in force
python products/whole_life/run_sec.py 19 # point 19: the loan variant, mid-year
python products/whole_life/run_sec.py --block # every model point, summed row by row
python products/whole_life/run_sec.py 19 --cython # point 19 on the compiled model
--cython runs the compiled model and prints the same lines. The runner builds it beside
the model with the repository’s tools/build_sec_cy.py the first time, in about a minute
and a quarter, and again whenever the model, sample_sec.py, spec_sec.py or the tool is
newer than the build, and says so on stderr. --build DIR runs a build made elsewhere
instead (The compiled model, below). Nothing a build leaves is committed, and
.gitignore covers it.
The first prints, as rows t = 0 … 11, the twelve months run.py prints for
WholeLife_US_S’s point 1, the worked example’s policy year 10, with the counts and rates
behind them. Every column agrees with run.py’s but expenses, which are in
valuation-date dollars here, 5.00 in the first month where run.py prints 5.98, and
net_cf and liability_cf with them. Three lines to the same thing for point 19:
import modelx as mx
model = mx.read_model("products/whole_life/WholeLife_US_SEC")
model.Projection[18].result_cf() # point 19, the table's nineteenth row
Projection takes idx, the position of a point in the table, as basiclife/BasicTerm_SC
does: Projection[18] is point 19, and its point_id() says so. result_cf() has
WholeLife_US_S’s twelve columns — pols_if, premiums, rider_premiums, expenses,
premium_taxes, claims_death, claims_lapse, claims_maturity, div_cash_paid,
loan_draws, and the net flow under both signs, net_cf and liability_cf — with one
row per month from the valuation date, t = 0 … proj_len() − 1. result_pols() sets out
the counts behind it on the same rows: pols_if, pols_new_biz, then the month’s deaths
and surrenders in processing order and the maturities of the last covered month, then
WholeLife_US_S’s four decrement rates, annual and monthly, written 0 outside cover.
result_cv() has WholeLife_US_S’s values per policy, each month’s closing balances and
its two benefit amounts, with zeros before issue. result_cf_annual() sums result_cf()
into policy years, as in WholeLife_US_S, and leaves out the months before issue.
--block asks every point for its frame before it projects any, then projects each and
releases its ItemSpace once its frame is read, so the run holds the cells of one point at
a time. Deleting it, del model.Projection[idx], is not enough: an ItemSpace sits in
reference cycles, which only Python’s cyclic collector frees, so the runner collects after
each release. It freezes everything alive (gc.freeze()) once the model and its table are
read, and again once it has asked every point for its frame, so that each collection scans
only what the block has made since. It keeps the block’s sum as it goes, compensated as
pandas sums a groupby, so that the block is, bit for bit, the frames concatenated and
summed by t, as below.
Two clocks#
The model runs on two clocks, and each formula reads the one its quantity belongs to.
t, the valuation clock, counts months from the valuation date.t = 0is the valuation month for every model point, however old the policy, and the frame runst = 0 … proj_len() − 1, whereproj_len()is the number of months from the valuation date to maturity at attained age 100.duration_mth(t), the policy clock, counts the months the policy has been in force at timet:duration_mth(t) = duration_mth_init() + t, withduration_mth_init()read from the model point. It is the technical notes’ month index, and the contract runs on it:duration(t) = duration_mth(t) // 12,policy_year(t) = duration(t) + 1andage(t) = age_at_entry() + duration(t), as inWholeLife_US_S, andis_anniv(t)is true in the last month of each policy year in cover.BasicTerm_SEreaches the same numbers by adding one a month, a recursion as long as the frame; the closed form needs no such chain of calls.
anniv_mth(t), the month of the anniversary that ends the policy year containing t, is
on the valuation clock: t + 11 − duration_mth(t) % 12, where WholeLife_US_S returns the
policy month 12 × duration(t) + 11. The two are the same number only where the clocks
coincide.
Point 1 is the worked example’s anchor cell, in force 108 months. At t = 0 it is on the
anniversary that opens policy year 10, at attained age 54. Its tenth anniversary, where
the year’s dividend is credited and buys paid-up additions, falls at t = 11,
WholeLife_US_S’s month 119, and its frame has 552 rows, t = 0 … 551. Point 19 is the
loan variant in force 114 months, six months into policy year 10: its tenth anniversary
falls at t = 5, its next premium, policy year 11’s $1,800, at t = 6, and its frame has
546 rows. Point 22 is point 2 to be issued three months after the valuation date:
duration_mth(0) = −3, it is on the books from t_entry() = 3, rows 0 to 2 are zeros,
and its frame has 663 rows.
Read on the policy clock |
Read on the valuation clock |
|---|---|
the premium-paying period and the months instalments fall due, the guaranteed cash value schedule and its interpolation, the net single premiums and theirs, guaranteed mortality at the attained age and the scale and best-estimate rates built on it, the lapse schedule and its final-year zero, the dividend declaration and its first year, loan-interest capitalization, the purchases of the PUA rider and the REDUCE_PREM excess, the graded death benefit’s policy years 1–2, maturity at attained age 100 |
expense inflation, |
The interest-sensitive lapse overlay reads a constant, competitor_rate, so it is on
neither clock, and the product has no scenario table. Expense inflation alone runs on t,
so the maintenance charge is in valuation-date dollars, for every point alike.
Acquisition, 90% of the first year’s annual premium plus $250, is charged per policy
issued, in the issue month, and not inflated, as in basiclife/BasicTerm_SE.
Because row t is the same month for every point, the frames of a block line up and sum
row by row, which is what run_sec.py --block prints:
import pandas as pd
n = len(model.Data.model_point_table())
frames = [model.Projection[i].result_cf() for i in range(n)]
block = pd.concat(frames).groupby(level="t").sum()
On a point issued at t = 0 the two clocks coincide, and the model computes what
WholeLife_US_S computes, whatever the point’s count: WholeLife_US_S already charges
acquisition on the policies in force at its t = 0, which on new business are the
policies issued. On WholeLife_US_S’s fourteen new-business points every cash flow and
every count agrees, and so does every other cell the two models share but three whose
meaning changed: pols_if_init(), now the count already in force at the valuation date,
0 for new business; model_point(), a row of another table; and result_pols(), which
gains pols_new_biz.
The in-force interface#
The model point table is model_point_table_sec.csv. It carries WholeLife_US_S’s
columns, and nine of its columns are the in-force interface: basiclife/BasicTerm_SE’s
two, and seven that open an in-force policy’s state. Every amount is per policy.
Column |
Unit |
Measured at |
Meaning |
|---|---|---|---|
|
policies, not necessarily whole |
for a point in force, the start of month 0, before any month-0 event; for any other, its issue month |
the policies in force at the valuation date, for a point already in force; the policies issued, for one issued at or after it |
|
whole months |
the valuation date |
the policy’s age in months: positive in force, in any month of its policy year, 0 for a policy issued at the valuation date, |
|
dollars of paid-up face |
the start of month 0, before any month-0 event: the close of policy month |
the paid-up additions in force |
|
dollars |
the start of month 0 |
the policy loan outstanding, capitalized interest included |
|
dollars |
the start of month 0 |
the dividend accumulation balance, interest and dividends to date included; 0 unless the option is ACCUM |
|
dollars of paid-up face |
the anniversary that opened the policy year under way, on or before the valuation date: the close of policy month |
the paid-up additions entering the policy year, which its PUA-block dividend and its term-blend gap read |
|
dollars |
that anniversary |
the loan entering the policy year, on which the year’s interest capitalizes and which the dividend’s interest margin credits at the loan rate |
|
dollars |
that anniversary |
the dividend credited there, which |
|
dollars |
the start of month 0 |
the gross premium, before any dividend offset, of every instalment due from issue to policy month |
The seven state columns are 0 on a point issued at or after the valuation date, the
values at issue. In the first policy year, duration_mth 1 to 11, the three anniversary
columns hold their issue values, 0, because that year opened at issue, and
div_accum_init is 0 too, because no dividend has been credited yet. On a point valued
on an anniversary, duration_mth a multiple of 12, the two _prev_anniv_init columns
are the same instant as pua_face_init and loan_bal_init, and must equal them.
prev_anniv is WholeLife_US_S’s word, as in its div_prev_anniv: the anniversary that
opened the policy year, where anniv alone, as in is_anniv and anniv_mth, is the
one that ends it. An extract that fills the three anniversary columns from the
anniversary after the valuation date is a year out.
Everything else the projection uses is fixed at issue, in WholeLife_US_S’s columns, or
follows from the policy clock: the cash value is read from the guaranteed schedule by
policy year, the net single premiums and the mortality by attained age, and the premium
from the model point or, on final expense, from the rate table.
|
|
Why |
|---|---|---|
|
|
The count, under BasicTerm_SE’s name. |
|
|
The policy clock, in months, so that a policy can be valued in any month of its year; the S column is dropped |
|
|
Renamed in place, so that the seven state columns share one vocabulary: a column measured entering month 0 is the cell it opens with |
|
|
The same |
— |
|
|
— |
|
The same, with |
— |
|
|
— |
|
|
— |
|
|
On the twins the five new columns take what WholeLife_US_S itself assumes, so each twin
opens as its S row does: on point 1 the paid-up additions at the anniversary are its
4,100, the loan 0, the accumulation balance and last year’s dividend 0, and the premiums
paid 16,200, nine years at $1,800.
The columns carried over are read as WholeLife_US_S reads them. For a policy in force,
the facts they record are still those at issue, the dividend option and the premium mode
excepted:
Column |
Unit |
Measured at |
|---|---|---|
|
labels |
— |
|
codes, as in |
issue |
|
years, age nearest birthday |
issue, not the valuation date: |
|
dollars, level for the life of the policy |
issue |
|
dollars a year, the participating design’s |
issue |
|
|
the option in force over the frame |
|
|
the mode billed over the frame; its instalments fall on the policy clock |
|
dollars a year, level while premiums are payable |
issue |
|
dollars of target face, 0 for no blend |
issue |
|
a fraction of the guaranteed cash value |
an assumption, not a fact about the policy |
|
text: |
— |
The loan is not carried forward as a balance. WholeLife_US_S holds it at
loan_utilization × CV_t in every month of its frame, and this model does the same from
month 0 on, whatever loan_bal_init says. That column is what month 0’s advance,
loan_draw(0), is measured from, and what the death benefit of month 0 deducts, so the
advance closes any gap between the extract’s loan and the fraction: point 19 owes
2,070.00 entering month 0 and 2,098.33 at its end, an advance of 28.33.
Three more columns, row_kind, source_policy_id and source_mth, record where the
generator took each shipped row from (below). No formula reads them, and an in-force
extract need not carry them: without them the model projects the same numbers, and
run_sec.py runs.
Data.model_point_table() checks the table as it reads it, over all rows at once. The
first check that fails raises ValueError, naming the missing column or every point that
fails it:
the nine in-force columns are present;
no
point_idappears twice;policy_countis a number, zero or more, so not blank, text or infinite;duration_mthis a whole number of months;duration_mthis below2**53months, which an int64 and a float both hold exactly, so that numpy never casts it to the least int64, a policy issued2**63months on;duration_mthis −120 or more. Future new business is written over a horizon,Data.future_horizon_mth, 120 months as shipped, so that no frame runs longer than cover from issue plus ten years: 1,320 months at issue age 0, the youngest the product issues, and 780 at 45, the youngest the shipped tables carry. Set to 0, the Reference refuses future new business altogether, and a negative horizon is itself refused;each opening-state column is a number, zero or more;
a policy not yet in force,
duration_mth0 or less, has an opening state of zeros;the non-participating final-expense design has no paid-up additions,
pua_face_initandpua_face_prev_anniv_init, and no dividend,div_prev_anniv_init;only the ACCUM option has an accumulation balance, which on any other the projection would drop from every benefit;
on a point valued on an anniversary the two
_prev_anniv_initcolumns equalpua_face_initandloan_bal_init;in the first policy year, which opened at issue and has credited no dividend yet, the three anniversary columns and
div_accum_initare 0.
A row whose paid-up additions at the anniversary exceed those entering month 0 is accepted. The model never shrinks the block, so such a row records a partial surrender of additions, which the model does not implement, and it is projected from the values it gives.
A point whose cover had ended by the valuation date,
duration_mth ≥ 12 × (100 − issue_age), reads, but proj_len() refuses it, naming the
point: the end of cover is the product’s rule, not the table’s. So a loop over the block
meets such a row only when it reaches it, after projecting the points before it.
run_sec.py --block asks every point for its frame before it projects any, and stops
before it prints anything.
The model points#
No row of model_point_table_sec.csv is typed by hand. Every one is generated from
WholeLife_US_S and its table by tests/sec_support.py, from the WholeLife_US_SEC
entry in its SEC_SPECS, and the tests regenerate the table and compare, so an edit to a
WholeLife_US_S row reaches it or fails the suite. In the source repository,
python tools/gen_sec_points.py WholeLife_US_SEC writes it.
Point |
Kind |
From |
At the valuation date |
|---|---|---|---|
1 |
twin |
S point 1 |
the anchor cell in force 108 months, on the anniversary opening policy year 10, with its 4,100 of paid-up additions: the worked example’s year |
2–15 |
twin |
S points 2–15 |
issued at |
16 |
derived |
S point 5 at S month 108 |
REDUCE_PREM on the anniversary opening policy year 10, last year’s dividend 288.66 |
17 |
derived |
S point 4 at S month 108 |
ACCUM on the same anniversary, with 1,766.74 accumulated |
18 |
derived |
S point 8 at S month 78 |
the funded term blend six months into policy year 7, before its crossover: 106,074.52 of paid-up additions, 93,241.47 at the anniversary |
19 |
derived |
S point 6 at S month 114 |
the loan variant six months into policy year 10: a loan of 2,070.00, 1,900.00 at the anniversary |
20 |
derived |
S point 12 at S month 18 |
the graded final-expense plan inside its graded years, with 3,162.00 of premiums paid |
21 |
derived |
S point 5 at S month 659 |
REDUCE_PREM in its last month of cover: a one-row frame |
22 |
future |
S point 2, 3 months on |
to be issued at |
A derived row’s policy_count is the count WholeLife_US_S carries into that month, its
pols_if(d), and its opening state is what WholeLife_US_S carries into it, each column
read as WholeLife_US_S’s own formulas read it: the paid-up additions, the loan and the
accumulation balance at the close of S month d − 1; the paid-up additions and the loan
at the close of S month anniv_mth(d) − 12, the anniversary that opened the policy year
of d; S’s div_prev_anniv(d); and S’s prem_cum(d − 1). So the row continues the S
projection from there: points 16 and 17 open with 0.704576 policies, and point 21 with
0.041820. Its policy_id is the S row’s with the month appended, WLPAR-000005-M108,
and a future row’s carries the months to issue, WLPAR-000002-F3. Row t of a
generated point is month t + source_mth of its S point. All 22 are at issue age 45 on
the participating design or 65 on final expense, the only issue ages cv_table.csv
carries, so a point at any other needs the schedules extended first.
Counts and timings#
pols_if_init() is the count in force at the valuation date: policy_count for a point
already in force, 0 for any other. pols_new_biz(t) is policy_count in the issue month,
the month with duration_mth(t) = 0, and 0 in every other. pols_if_at(t, timing) has
five timings, in processing order, each an int Reference named as the string
basiclife/BasicTerm_SE or WholeLife_US_S passes, so that a timing, like every
argument, is a C number when the model compiles:
BEF_NB = 0, the count carried in from montht − 1, before montht’s new business:pols_if_init()att_entry(), the first month on the books, and the survivors of montht − 1after it;BEF_DECR = 1, that count pluspols_new_biz(t), before montht’s decrements;BEF_SURR = 2, after the month’s deaths;BEF_MAT = 3, after its surrenders;AFT_DECR = 4, after the maturities of the last covered month, the notes’l_{t+1}.
The first two are basiclife/BasicTerm_SE’s, and the other three WholeLife_US_S’s,
unchanged but for their guard outside cover and, in AFT_DECR, the last covered month
read on the policy clock. Any other timing raises. One name means two instants in the two
references: BasicTerm_SE’s "BEF_MAT" counts the policies at the start of a month,
before that month’s maturities, where WholeLife_US_S’s counts them at its end, after
the month’s surrenders. The policies here mature at the end of the last covered month, as
in WholeLife_US_S, so the name keeps the S meaning, and BasicTerm_SE’s timing is not
adopted.
The survivors carried into month t are those of month t − 1’s BEF_DECR count,
which BEF_NB forms itself, as its own value at t − 1 plus that month’s new business,
through the month’s deaths and surrenders in the order BEF_MAT takes them. So
pols_if_at(t, AFT_DECR) is pols_if_at(t + 1, BEF_NB) at every t of every frame,
and it is pols_if(t + 1) except where month t + 1 is an issue month, whose new business
joins pols_if. The chain of calls from month t back to t_entry() is one cell a month,
where WholeLife_US_S’s ran through five: on a model just read, a cold net_cf in the
last month of a 660-month frame runs 671 cells deep, against 3,304 in WholeLife_US_S, so
modelx needs a recursion limit of 670 for it. On the longest frame the shipped tables
allow, 780 months for point 2 issued 120 months on, it runs 671 deep too, because the
chain stops at the issue month, and on the longest cover the contract allows, from issue
age 0, issued now or 120 months on, 1,211 deep (The compiled model, below). Each report
evaluates its columns in ascending t, and a sweep of the committed points that way runs
under a recursion limit of 28.
pols_if(t) is pols_if_at(t, BEF_DECR), the count that weights row t, and on a point
issued at t = 0 it is exactly WholeLife_US_S’s pols_if. It is not BasicTerm_SE’s
pols_if, the count before maturity. The roll-forward closes as
pols_if(t) − pols_if_at(t + 1, BEF_NB)
= pols_death(t) + pols_lapse(t) + pols_maturity(t)
at every t of every frame, and pols_if(t + 1) adds pols_new_biz(t + 1) to the count
on the left. This is check_pols_roll_fwd_resid(t), which in WholeLife_US_S subtracts
pols_if(t + 1): here that would count the next month’s new business as a gain of month
t.
Cover is is_active(t), 0 ≤ duration_mth(t) < maturity_mth(), where
maturity_mth() = 12 × (100 − issue_age) is WholeLife_US_S’s frame from issue. Outside
it, before issue and from maturity on, every count is zero, and so every cash flow, every
value state and every dividend. No count evaluates a decrement rate there, and no table is
read at a policy year or an attained age the policy does not have: is_anniv and
prem_due are false, and premium_pp_ann, rider_premium_pp_ann, prem_cum, cv_pp,
nsp_mth, mort_rate_guar, div_prev_anniv, div_credited, oyt_face, div_to_pua,
div_accum, pua_face_offset, pua_face, pua_cv, loan_bal, loan_draw and the
death benefit are zero before any table is read. Every other value is zero through them.
The opening state#
WholeLife_US_S opens an in-force point on an anniversary, from three columns,
duration_inforce, puaf_inforce and loan_inforce, and assumes the rest: no
accumulation balance, no dividend at the anniversary before its frame, and premiums
summed from issue. That is all the worked example’s policy year 10 needs. A policy valued
at any month of its life needs all seven state columns, each what WholeLife_US_S carries
into that month, and each shows on a derived row:
div_prev_anniv_init. Point 16, on REDUCE_PREM, is valued on the anniversary opening policy year 10. It pays 1,800.00 less last year’s dividend of 288.66 att = 0, so 1,511.34 a policy, asWholeLife_US_Scollects at its month 108. With the column at 0 it would pay 1,800.00.div_accum_init. Point 17, on ACCUM, is valued on the same anniversary with 1,766.74 accumulated, which earns its monthly interest fromt = 0and reaches the death, surrender and maturity benefits. With the column at 0 the balance would be lost from every benefit, and the maturity claims of its last month alone would be 1,060.82 lower.prem_cum_init. Point 20, the graded final-expense plan valued six months into policy year 2, has paid two annual premiums of $1,581, 3,162.00. To the end of the graded years,t = 5, its death benefit is0.97 × 1.1 × 3,162.00 + 0.03 × 15,000 = 3,823.85, and fromt = 6, policy year 3, the face. With the column at 0 it would be 450.00.
A valuation off an anniversary needs the year’s opening values as well, because the annual quantities of a policy year read the balances entering it, and inside the year those have moved on:
pua_face_prev_anniv_init. Point 18 is the funded term blend six months into policy year 7. The year’s rider instalment, paid at its start, has bought 12,833.05 of additions since the anniversary, so the point holds 106,074.52 entering month 0 against 93,241.47 at the anniversary. The one-year-term layer of the year is sized on the second:200,000 − 100,000 − 93,241.47 = 6,758.53, which the year’s dividend funds in full, so the death benefit of month 0 is100,000 + 106,074.52 + 6,758.53 = 212,833.05,WholeLife_US_S’s at its month 78. On the current additions there would be no gap at all.loan_bal_prev_anniv_init. Point 19, the loan variant six months into policy year 10, owes 2,070.00 entering month 0 against 1,900.00 at the anniversary. At its tenth anniversary,t = 5, the year’s interest capitalizes on the second, 6% of 1,900.00, 114.00. The dividend’s interest margin reads the same 1,900.00, though at the shipped rates, 6.00% on the loan and on the dividend alike, the loan cancels out of it.
On a point valued on an anniversary each pair is one instant, and Data refuses a row
where they differ. Off an anniversary they differ wherever the year has moved the balance
since it opened: by the rider’s purchases, by the REDUCE_PREM excess, which buys additions
in the year’s first month, and, for the loan, every month with the cash value. Point 21,
REDUCE_PREM in its last month, holds 4,823.37 of additions against 4,544.40 at its
anniversary.
WholeLife_US_S’s goldens on its point 1 read four values from the month before its
frame: pua_face(107), loan_bal(107), cv_pp(107) and pua_cv(107). On the twin no
month comes before the frame, and each is opening state at t = 0: pua_face_init() is
the 4,100, loan_bal_init() 0, cv_pp_anniv(9) 9,500, the guaranteed cash value entering
policy year 10, and pua_face_prev_anniv_init() × nsp(54) 1,648.93, each WholeLife_US_S’s
value. The worked example’s year then runs as in WholeLife_US_S: the dividend of 326.25
credited at t = 11 brings the paid-up additions to 4,876.79, WholeLife_US_S’s
pua_face(119).
Departures from WholeLife_US_S#
Each formula that tested t against a contractual event now tests the policy clock, each
read at a policy month passed as t is a read on the policy clock or of the opening
state, and every recursion begins at t_entry(). Where WholeLife_US_S’s test would have
stayed correct on the valuation clock, it moved anyway, so that cover has one definition.
Running in force left 40 of WholeLife_US_S’s 97 cells unchanged, one of them,
dyn_lapse_factor, with a line re-wrapped, gave 9 a new docstring only and rewrote 44; it
renamed two and removed two, and added 11 cells, 106 in all. Compiling then changed how
each cell reads its inputs and spells its codes, and no number, and added 12 cells, 118 in
all (The compiled model, below); of WholeLife_US_S’s cells it changed the signature of
one, claims. The twin identity names each of the five, with its reason: a cell of
WholeLife_US_S’s that this model lacked, or took other arguments, would fail it
otherwise. Some departures come from compiling rather than from the clock: proj_len’s
second refusal and the last three rows below.
Cells |
|
|
Why |
|---|---|---|---|
|
|
|
The policy clock, opened from the model point |
|
|
|
The frame starts at the valuation date. |
|
an in-force frame opens at |
removed: every report and check runs over |
Every frame opens at |
|
the in-force point’s opening paid-up additions and loan |
renamed |
One vocabulary for the seven state columns |
|
a recursion from |
|
Policies in force at the valuation date open the count; new business joins it in its issue month |
|
open at |
open at |
Every recursion begins on the books, from the opening state |
|
a recursion back to issue |
opens at |
No cell asks for a month before the valuation date |
|
|
|
On the valuation clock month |
|
|
|
The same |
|
the cash value |
|
|
|
the balance twelve months back, or |
the same, or |
A policy year under way at the valuation date opened before it |
|
a mid-year instalment priced at |
the same straight line, written at the start of month |
At |
|
the years to maturity as |
|
|
|
acquisition, |
|
A point already in force bears none, and one issued later bears it in its issue month, per policy issued and not inflated, as in |
|
|
the same formula, |
Unit costs in valuation-date dollars |
|
|
|
Next month’s new business is no part of month |
|
the last month as |
|
One definition of cover, on the policy clock |
|
unguarded, or guarded by |
false or zero outside cover, |
A future point’s months before issue have |
|
|
|
Every frame opens at |
|
whole policy years |
the policy years in the frame, the months before issue left out |
An in-force point’s first row holds the rest of its current policy year, and its |
|
|
|
The counts behind |
|
|
|
A compiled cell takes C numbers, and |
|
|
an int, 2 as shipped, and a count below −400, −1,000 say, turns the rounding off |
|
|
a malformed value or key met, if at all, only when a projection reaches it, and a key beyond a table as |
refused by name at the first read of the array, over the whole table, and a key beyond a table refused by the cell that reads it, naming the point |
A compiled model holds numbers, not text, and computes a NaN as silently as modelx (What it refuses, below) |
The other new cells of running in force are policy_count, duration_mth_init,
t_entry, is_active, pols_new_biz and the five new opening-state accessors; those of
compiling are listed under What compiling changed, and why, below.
One read goes further ahead than the month after its own, and it is kept.
oyt_face(t) sizes the term-blend layer of the policy year containing t on the dividend
credited at the anniversary that ends it, div_credited(anniv_mth(t)), up to eleven
months ahead, because the one-year term in force through the year is bought with that
dividend. It opens no chain forward: the dividend depends on the balances entering the
year and on the schedules alone, never on the layer or on a later month, and the frame
ends on an anniversary, so the read never leaves it.
Of the cash flows, the change of clock moves the maintenance expense alone, and net_cf
and liability_cf with it. A point in force carries that expense in valuation-date
dollars, so point 1’s expenses(t) is WholeLife_US_S’s expenses(108 + t) divided by
1.02^9, about 1.195. Its other cash flows and its counts are WholeLife_US_S’s from
month 108 on. Point 22 is WholeLife_US_S’s point 2 three months on in those columns too;
its maintenance expense is 1.02^(3/12) above S’s, and its acquisition, 1,870.00, is
S’s exactly.
The compiled model#
The model compiles under modelx-cython into C-typed code, as basiclife/BasicTerm_SC does,
and modelx reads and runs the same formulas as before. Compiling changed how each cell
reads its inputs and spells its codes, and no number: what the model computed on each
committed point was frozen before the change, and it still computes it (Tests, below).
Cell by cell, at every argument a full modelx sweep evaluates, the compiled model computes
what modelx computes, bit for bit, on the committed points, on the points of the splice
grid, which take the branches they do not, on the contract’s longest frames, and on
points where the cap on mortality binds. The compile tests hold it so on x86-64, and to
1e-12 relative elsewhere, where no run has shown it yet.
Building it#
In the source repository:
python tools/build_sec_cy.py whole_life # in place, beside the model
python tools/build_sec_cy.py whole_life --out /tmp/wl # elsewhere, with the CSVs
The tool exports the model to WholeLife_US_SEC_nomx/, the Python package modelx’s
export writes, which runs without modelx. It copies the CSVs beside the export when it
builds anywhere but here, because the package reads the CSVs of the directory that holds
it. It then runs mx2cy, modelx-cython’s compiler, on the export, with sample_sec.py and
spec_sec.py (below). The result is WholeLife_US_SEC_nomx_cy/, whose spaces are C
extension types, and it is imported as the export is:
import sys
sys.path.insert(0, "products/whole_life") # the directory holding the build
from WholeLife_US_SEC_nomx_cy import mx_model as model
model.Projection[18].result_cf() # point 19, compiled
Compiled, no cache is ever cleared. An ItemSpace takes the References when it is made,
and keeps the values it computes until it is deleted; the base Projection and Data
keep theirs for good. So Projection.idx = 18 after Projection.result_cf() returns
point 1’s frame under point 19’s point_id(), and Projection.div_round_digits set to
−1,000 once Projection[0] has credited point 1’s tenth dividend leaves it rounded there,
326.25, where an ItemSpace made after computes 326.248. Set every Reference on a model
just imported, before anything is computed, where modelx would recompute; a test holds
the compiled model to this.
A build takes about a minute and a quarter with gcc, 80 s here, and needs a C compiler,
which is why requirements.txt leaves modelx-cython out:
pip install -r requirements-cython.txt. run_sec.py --cython builds in place when it
finds no build, or one older than the model, the sample, the spec or the tool, and
--build DIR runs a build made with --out DIR. Nothing a build writes is committed. All
of it derives from committed files, and an extension module is built for one operating
system, processor and Python (_mx_classes.cpython-313-x86_64-linux-gnu.so here); in
place, .gitignore covers all of it. A lifelib.create() copy of the library carries no
tools/, so it cannot build, and run_sec.py --cython says so.
What compiling changed, and why#
A compiled cell is fast when its body is C, and types alone do not make it so. Compiled by
the same tool, with a sample of its own, as it stood after running in force, the model
typed 95 of its 106 Projection cells as C numbers, but three of them still took a
timing or a kind as text, and so kept a dictionary for a cache, and it ran only 1.4 times
its own export, 18.5 ms a point on net_cf against 25.9, over the committed points. The
bodies of the typed cells still called pandas and Python: a model_point() lookup for
each attribute, a .loc on a table for each policy year’s cash value, each attained
age’s mortality and net single premium and each point’s final-expense rate and net level
premium, text compared in every formula that branched on the product, the premium
period, the premium mode or the dividend option, and a generator summed in claims. So
each input now reaches a cell as a number:
idx.Projectionis parameterized by the position of a point in the table, from 0, asBasicTerm_SCis:Projection[18]is point 19, andpoint_id()returns the label, which every refusal names. The position is what indexes the vectors below.Data’s vectors. Each model point attribute a formula uses is aDatavector of int64 or float64, one element a point, and a cell reads its point’s element:age_at_entry()isint(data.issue_age()[idx]). Compiled, the vector is a typed memoryview, and the read is a load from memory.Text, decoded once. A C cell holds no text, so
Datadecodes each text column into the number it selects, for every point at once: the product into two flags,is_parandis_graded; the premium period and the dividend option into their codes; and the premium mode into the months between instalments,prem_cycle, by whichmodal_factorselects the mode’s factor. Each decodes asWholeLife_US_Sreads the column: a dividend option that is none of the four isNONE, asWholeLife_US_Sapplies such a dividend to nothing, and what cannot be decoded is refused (below).Tables indexed by integers. The cash value schedules, keyed by premium period, sex and issue age, are numbered, each point carrying the number of its own,
cv_schedule, and held by schedule and policy year incv_array. The guaranteed mortality and the net single premiums, keyed by sex and attained age, are numbered by sex the same way and held by schedule and age inmort_table_arrayandnsp_array, padded from age 0 so that the index is the attained age. The padding holds NaN, and nothing reads it: the one cell that reads each table checks its key against the schedule’s extent first. The final-expense rates and the net level premiums are one number a point, and read by one design alone, so each is joined to the points inData, with a 0/1 flag beside it, and the one cell that reads it,premium_rateornp_guar, refuses a point the table has no key for, whereWholeLife_US_S’s.locraisedKeyError.Datarefuses neither, becauseWholeLife_US_Sprojects a participating point with no final-expense rate.Codes. A timing, a kind, a premium period or a dividend option, which
WholeLife_US_Sspells as text, is an int Reference named as the text:BEF_NB = 0toAFT_DECR = 4,DEATH = 0,LAPSE = 1andMATURITY = 2,TO_100 = 0toTO_65 = 3, andPUA = 0toNONE = 4. A call reads as before, less the quotes:pols_if_at(t, BEF_DECR),claim_pp(t, DEATH). A string argument or a string value would give the cell a dictionary for a cache, where a code indexes a C array, so codes are numbered from 0 without a gap, the timings in the order of their instants within the month and the kinds in the order the month settles them. TheProjectiondocstring’s Codes lists all seventeen.The claims, split.
WholeLife_US_S’sclaims(t, kind=None)is one kind’s claims or, withNone, the three summed by a generator: neither a C parameter nor a C loop. Here the kinds are three cells,claims_death,claims_lapseandclaims_maturity, theresult_cfcolumns, andclaims(t)is their total (Departures from WholeLife_US_S, above).One Python call kept.
div_baserounds the dividend todiv_round_digitsplaces with Python’sround, which cannot be computed ahead, since the amount is projected. Compiled it is the same call, so the dividend is the same float, andtests/us_registry.pyadmits it, by its key"python_calls", in that cell alone. The digits are an int, and a count below −400 turns the rounding off, whereWholeLife_US_StakesNone; every other count rounds asWholeLife_US_Srounds.Reporting cells stay Python.
model_point(), the label accessorsproduct(),premium_period(),sex(),risk_class(),dividend_option()andpremium_mode(), and the four reports return a table row, text and DataFrames, for a reader, forrun_sec.pyand for the comparison withWholeLife_US_S. No other cell calls them, so they cost the projection nothing. A label accessor returns its column as read, andDataaccepts a label that is blank, which pandas reads as NaN, or a number, on a point that carries no paid-up additions, dividends or rider premium, and the point’s first projection refuses it. So each of the six compiles to a Python object, as the sample traces it (below), and returns what modelx returns (precised at M26). The two checks are reporting cells too, but they return a verdict, which compiles to a Cbint.
The Data docstring lists its 42 vectors, arrays, extents and counts, each with the column
or file it comes from: 19 vectors of int64, 15 of float64, three tables of float64 and five
counts. The seven readers stay Python, returning DataFrames and a path, and no
Projection cell but model_point() reads them. Every other cell of Projection, 107 of
its 118, returns a C bint, long long or double, and caches a single value, or a C
array the spec sizes from the contract:
Compiled to |
Cells |
|---|---|
a C array of 1,322 by |
the 66 cells of |
a C array of 1,322 by 5 |
|
a C array of 102 by |
|
one |
the 36 cells without a parameter: the point’s numbers, codes, schedules and flags, its opening state, the ends of its frame, its premium rate, modal factor and net level premium, and the two checks |
a Python object |
the eleven reporting cells but the checks |
The declarations the build generates, _mx_classes.pxd in the compiled package, are the
record of it, and none of Projection’s caches there is a dictionary.
The sample and the spec#
mx2cy types each cell from the values the sample run passes it and gets back, and a cell the
run never calls compiles as a Python object. So sample_sec.py runs the four reports and
the two checks on every committed point, and then the eleven cells no report reaches, and
the one timing: model_point() and the six label accessors, which only a reader asks for;
point_id(), which only a refusal names; mec_flag() and policy_year(t), which no cell
reads; dyn_lapse_factor(t), which the lapse rate reads only with its overlay switched on,
and it ships off; and pols_if_at, a cell the reports reach, at AFT_DECR, the one timing
no formula asks for, in every month of the frame and the month after it, with the count
pols_if_at carries into that month. It runs the committed points alone: the export it runs
reads the CSVs of the directory the build is made in, which in place is the product
directory, so points of its own would have to be written there. The committed points leave
branches untaken: the semi-annual and quarterly cycles, the twenty-year and to-65 premium
periods, the three overlays and the dividend on the paid-up additions, all shipped off,
rounding switched off, the cap on mortality. That still types every cell, because every
branch of a cell returns the one type its others return, a count a float in every branch,
and on points that take those branches the compiled model computes modelx’s numbers (above).
The label accessors are typed from more than the committed points: the sample also calls
the six on a copy of the first point with every label blank and its paid-up additions,
dividends and rider premium 0, written to a temporary directory and read by a second
instance of the export, so that each compiles to a Python object (M26). The sample also
raises the recursion limit, which modelx raises and its export does not (What a compiled
run needs, below).
spec_sec.py sizes each C-array cache, by the names of the cells’ parameters, and a
compiled cache raises IndexError for an argument outside it. So each size covers the
largest argument a cell is called with on a point the contract allows, in its frame and
in the month after it, t = proj_len(), which the roll-forward reads and the compile
tests’ full sweep evaluates every monthly cell at; plus one because the index starts at
0, and one of headroom where that leaves room:
Parameters |
Size |
The largest argument |
|---|---|---|
|
1,322 |
1,321. The longest frame is a policy issued at the youngest issue age, 0, covered to 100 for 100 policy years, and issued 120 months after the valuation date, the furthest ahead |
|
1,322 by 5 |
|
|
1,322 by 5 |
|
|
102 |
100, shared by three cells: the policy year |
proj_len() refuses a point issued below 0, issue_age_min, in modelx as compiled, and
cover ends at maturity_age, 100, so no report on a point the model projects runs past
these caches. Those two References and Data.future_horizon_mth are the contract the sizes
are derived from. Lower the minimum, or raise maturity_age or the horizon past 120 months,
and a report runs past the caches in the compiled model alone: a frame longer than 1,320
months, or a policy year or an age past 101, raises IndexError, naming nothing, where
modelx projects. Each needs the sizes derived again, as spec_sec.py derives them, and a
rebuild: t raised to 12 × (maturity_age − issue_age_min) + the horizon + 2, and y,
which holds a policy year and an attained age, to the larger of their two derivations,
max(maturity_age − issue_age_min, maturity_age) + 2. The shipped tables carry
mortality and net single premiums from attained age 18 and cash values at issue ages 45 and
65 alone, so a point issued below 18 is refused today by the first table it reads, naming
it; an issue age of 0 is the contract’s, which an extended table reaches.
Two compiler directives#
tools/build_sec_cy.py marks the module mx2cy translates # cython: infer_types=True, cpow=True, and compiles it with -ffp-contract=off on every platform but Windows, as
Term_US_SEC’s Two compiler directives sets out, with what each costs and what it
was measured to change there. Here cpow reaches four powers of two doubles: the monthly
rates of both decrements, 1 − (1 − q)^(1/12) in mort_rate_mth and lapse_rate_mth,
the monthly growth of the accumulated dividends, (1 + i)^(1/12) in div_accum, and
expense inflation, (1 + r)^(t/12) in inflation_factor. Without cpow a compiler with
C99’s complex numbers, gcc among them, computes each as a complex power, which can differ
from Python’s float power in its last bits. With both directives and the flag every
compiled value agrees with modelx’s bit for bit, and the compile tests hold each, by the
module’s first line, by the compiler’s command lines and, on x86-64, by the comparison
itself. On the same platforms the tool adds -Werror=incompatible-pointer-types, so that
gcc before 14, which only warns of a pointer of the wrong type, fails the build as gcc 14
does: the error two cache widths gave (The sample and the spec, above).
What a compiled run needs#
Memory, and the release. A compiled Projection ItemSpace is a C struct of 1,194,688
bytes, about 1.2 MB, the type’s basic size, which holds every cell’s cache: 66 arrays of
1,322 months and two of 1,322 by 5 make most of it. Deleting it,
del model.Projection[idx], frees nothing by itself: an ItemSpace sits in reference
cycles, and only Python’s cyclic collector frees it. That is why run_sec.py --block
collects after each release, in its frame pass and in its projections (Run it, above),
and a compile test holds a compiled block run to one point’s ItemSpace at a time. Without
it, 506 compiled points peaked at 596 MB (Speed, below).
Stack, not recursion limit. A compiled chain of cells calls C to C, on the C stack,
which the interpreter’s recursion limit does not count, so the compiled model needs no
limit raised. What it needs is stack. The deepest call the contract allows, a cold
net_cf in the last month of the longest cover, issue age 0, issued now or 120 months on,
runs the count chain back to t_entry(), 1,211 cells deep in modelx, one cell a month
and 12 more, and compiled with gcc it needs 288 KiB of thread stack. A test runs it in a
thread of 1 MiB, the stack Windows gives a program’s main thread unless the program is
linked for more, and again on the main thread, which is where run_sec.py --cython
runs. MSVC’s frames may be larger than gcc’s, and the cython CI job, which runs the test
on Windows too, is the check on them: the test first runs the call at seven stacks, from
256 KiB to 2 MiB, and reports the smallest it ran on, so a first run there measures MSVC’s
need. A stack below the need kills its child on an overflow, by design (with gcc, 256 KiB
does); on Windows the child ends with STATUS_STACK_OVERFLOW, and should Windows Error
Reporting hold it instead, the test waits two minutes for each bracketing child, and five
for the two it asserts, rather than the job’s hour. The export recurses in Python instead:
the same call needs a recursion limit of about 2,450 there, and the four reports and the
two checks, which run in ascending t, need 128, so sample_sec.py sets 10,000, four
times the first rounded up to the thousand, and a test holds it to that derivation.
What it refuses#
The compiled model refuses what modelx refuses, with the same message. modelx raises its
FormulaError, which quotes the error; compiled, the ValueError itself propagates.
What
Datacannot decode or hold, when the array is first read, naming every point at fault, or the schedule or the table: apoint_idthat is not a whole number, a premium period other thanTO_100,PAY_10,PAY_20orTO_65, a premium mode other thanA,SA,QorM,model_point_table_sec.csv: premium_mode must be A, SA, Q or M; it is not at point_id [2, 5]; a cash value schedule whose policy years are not whole, leave a gap, repeat or start below 1,cv_table.csv: the schedule of premium_period TO_100, sex M, issue_age 45 must run in whole policy years from 1 or more, without a gap or a repeat; a mortality or net single premium schedule with an age that is not whole, a gap, a repeated or negative age; an issue-age key of the cash values, the net level premiums or the rates that is not whole; a key of the net level premiums or the rates that appears twice.WholeLife_US_Smet each only when a projection reached it. And, before it is cast to int64, a number of2**53or more in size, which numpy would cast to the least int64 past int64: a model point’s issue age,model_point_table_sec.csv: issue_age must be below 2**53 in size; it is not at point_id [3], and aduration_mth, a policy issued2**63months on. A fractional issue age is not refused: it truncates toward zero, asWholeLife_US_S’sinttruncates it, so 45.5 projects as 45, and −0.5 as 0, which is then issued, as inWholeLife_US_S. A key written as a float, a policy year9.0, is read by its value, asWholeLife_US_S’s lookups match it, and so are the keys each extent and join is taken from; a key written as text is not whole, and the table’s check refuses it.A value a cap, a
minor amaxreads that is not a number in its range, when its array is first read, naming the file, the column and every line, key or point at fault, over the whole table, so that a value no point reads is refused as one that it reads is: through the dividend and the paid-up additions those bounds reach every amount and rate the projection reads. The face, the premium of the participating design, the rider premium and the blend target, a cash value, a net level premium and a final-expense rate must each be a number, zero or more; the loan share a number from 0 to 1,model_point_table_sec.csv: loan_utilization must be a number from 0 to 1; it is not at point_id [2, 5]; a guaranteed mortality rate a number from 0 to 1,mort_table.csv: mort_rate must be a number from 0 to 1; it is not at sex M, age [21]; and a net single premium, which the purchases divide by, a number above 0.A key beyond a table, by the one cell that reads it, naming the point, where
WholeLife_US_S’s.locraisedKeyError:point_id 2: cv_table.csv has no cash value for policy year 1, fromcv_pp_anniv, on a participating point issued at 46;point_id 2: mort_table.csv has no rate at attained age 45, frommort_rate_guar_at, on a sex the table lacks; andpoint_id 11: premium_rates.csv has no rate_per_1000 for its product, sex, risk_class and issue_age, frompremium_rate.By
proj_len(), a point past its cover,point_id 2: duration_mth 660 is at or past maturity, policy month 660, and a point the contract does not issue,point_id 2: issue age -1 is below issue_age_min, 0.
An argument outside a cache raises IndexError in the compiled model alone, as above:
net_cf(1322), which modelx answers with 0, the month being outside cover;
pols_if_at(0, 5) and claim_pp(0, 5), which modelx refuses as invalid timing and
invalid kind; and cv_pp_anniv(-1), which modelx answers with 0. A kind of 3 or 4 is
inside claim_pp’s cache, and both engines refuse it as invalid kind. An idx past
the last row is refused in both, with an IndexError at the first read of a vector, and
Projection[-1] reads every vector at its last element in both, so it is the table’s
last point, under that point’s own point_id().
An annual mortality above 1 is not refused but capped, in both: mort_rate caps the
best-estimate rate at 1, min(q, 1.0), as WholeLife_US_S does. Uncapped, the monthly
rate, 1 − (1 − q)^(1/12), would be complex in modelx and NaN compiled, silently. Capped,
both compute 1. A NaN rate would stay NaN through the cap, in both, as through the
dividend’s floor and the other bounds, each of which the compiled model computes as a
comparison that keeps the value unless the bound is smaller, or larger; Data’s
refusals of a value outside its range keep any NaN from reaching them.
Speed#
python tools/bench_sec_cy.py whole_life builds the model into a temporary directory, or
takes a build with --build, and times one block run on three engines: modelx, the export
and the compiled model. Each engine runs the committed table repeated, in a process of its
own, as run_sec.py --block runs a block, each point projected and then released.
net_cf is net_cf(t) summed over the frame, the projection alone, as
basiclife/BasicTerm_SC is timed on its pv_net_cf(); result_cf is the report
run_sec.py prints, which builds a DataFrame for each point. Each time is the fastest of
three runs, with their spread in seconds:
Engine |
Points |
|
|
Peak memory |
|---|---|---|---|---|
compiled |
6,006 |
0.53 ms (3.19–3.47) |
1.22 ms (7.32–7.60) |
88 MB |
export |
616 |
7.4 ms (4.56–4.99) |
7.7 ms (4.76–5.09) |
88 MB |
modelx |
132 |
274 ms (36.1–39.6) |
271 ms (35.8–41.8) |
137 MB |
On net_cf the compiled model runs 13.9 times its export, and on result_cf, where
building the DataFrame takes most of its time, 6.3 times; it runs 515 and 223 times
modelx. A second run straight after, under a 1-minute load between 1.2 and 2.8, gave the
compiled model 0.54 and 1.18 ms and the export 7.6 ms on both, 14.1 and 6.4 times, and
modelx 254 and 262 ms. As it stood after running in force, compiled the same way, the
model ran 1.4 times its export (What compiling changed, and why, above): the
representation, not the compiler, is the gain, as it was for Term_US_SEC, whose compiled
model runs 9.5 times its export on the same measure, with a C struct of about a third of
this one’s, its frames shorter and its cells fewer. The release keeps a block flat: the
compiled model’s peak grew by less than 0.1 MB over its 6,006 points, and without the
collection after each release (--no-collect), 506 compiled points peaked at 596 MB.
Reading the six files and building every Data vector and array for those points took
0.05 s, and asking every point for its frame, the runner’s first pass, 0.13 s.
Measured on 2026-11-12 on a machine shared with other work, under load: 4 CPUs (an Intel Xeon at 2.30 GHz), a 1-minute load average between 0.7 and 4.1 as the runs started; Linux, Python 3.13.18 and gcc 13.3.0, with modelx 0.33.0, modelx-cython 0.1.0, Cython 3.3.0, numpy 2.5.3 and pandas 3.0.5. Under load the spread is wide, and the fastest run is the one to compare.
Tests#
The twin identity, in
tests/test_model_conventions.py: on points 2 to 15, issued at the valuation date, every cell ofWholeLife_US_S’s agrees at every argumentWholeLife_US_Sevaluates in its own sweep, but forpols_if_init,model_pointandresult_pols, whose meaning changed, the four cells this model renamed or removed, andclaims, whose arguments changed: each of its kinds is a column ofresult_cf, which the identity compares, and the module holds the total toWholeLife_US_S’s. So the goldenstests/test_whole_life_us.pyasserts on those points — every dividend option, the loan, the rider, the term blend funded and unfunded, limited pay, the female cell, final expense and monthly mode — hold here with no number restated. UnlikeTerm_US_SEC’s, the identity holds on any count, sinceWholeLife_US_Salready charges acquisition on the policies issued. The same suite holds the model to the conventions every_SECmodel meets: every frame starts att = 0,pols_ifis theBEF_DECRcount, new business enters once at itspolicy_count, nothing happens before issue, and the in-force columns are present.The splice, in
tests/test_whole_life_us_sec.py: eachWholeLife_US_Spoint restated in force at a month either side of its events continues the S projection, inresult_cf, inresult_pols, column by column, and in every other cell the two share, to 1e-9, but those the twin identity skips,pols_if_initandmodel_point, and those whose value is a month or a frame on the valuation clock,proj_len,anniv_mthandresult_cf_annual. The participating points are restated at months 12, 108, 115, 119, 120 and 600, the final-expense points at 12, 18, 23, 24, 115 and 400: inside the graded years, in their last month, in the first after them, and later. The funded blend is restated at 78 and 83 too, before its crossover, and ACCUM, REDUCE_PREM and final expense level in their last covered month. So does the anchor cell’s twin from S’s month 108, and S’s point 1 restated later in its life. So do three variants of S’s points, in a copy of S’s table that is never committed, for branches S’s own points do not reach: the PUA rider paid monthly, REDUCE_PREM paid semi-annually, and the graded plan paid quarterly. Inflation, the one input on the valuation clock, is set to 0 in both models. Three switches that ship off are turned on in both, the PUA-block dividend, the premium-offset overlay and the interest-sensitive lapse overlay, and the loan rate is set apart from the dividend rate, because at the shipped settings parts of the opening state show in one place alone: the additions at the anniversary in the term blend, last year’s dividend under REDUCE_PREM, and the loan at the anniversary in its interest.The core grid and the full one. By default the splice and the future business run a core of their cases, which between them reach every branch above, every opening-state column, every kind of valuation month and every premium mode, and a test asserts that they do. The other cases carry the
sec_fullmarker and show as skipped, with the reason, unlessUSLIB_SEC_FULL=1is set. ThesecCI job’s Linux leg sets it, so every CI run runs the full grid too.Future new business: issued 1 and 12 months after the valuation date, each S point is the S projection moved on, with zeros before issue in
result_cf,result_polsandresult_cvand no decrement rate evaluated there, and so is each variant issued a month on.How it computes: on every row the splice and the future business compare, the core by default and the full grid with
USLIB_SEC_FULL=1, after every report, no cell has been called at a negative month, none evaluated fromt_entry()on has read a month before it, and none evaluated at monththas read a month later thant + 1butoyt_face, which reads the year’s dividend atanniv_mth(t)and nowhere else. On a fresh read of the committed model,duration_mth(500)evaluatesduration_mthonce, because the policy clock is a closed form, and every point is swept under modelx’s recursion limit lowered to 60, which a recursion backward over the frame would exceed.Counts, validation and regeneration: the roll-forward closes,
AFT_DECRis the next month’sBEF_NB, andpols_if_atrefuses a timing it does not have;result_pols()isWholeLife_US_S’s, column for column, withpols_new_bizbeside it; doublingpolicy_countdoubles every cash flow and moves no per-policy value; each malformed row is refused naming its point, a missing, negative or misplaced opening state among them, at either end of the first policy year and on the first anniversary; the horizon is a Reference, which at 0 refuses any future business, saying so; a point past its cover is refused byproj_len(), andrun_sec.py --blockrefuses it before printing anything; a zero count, durations written as floats, balances written as whole numbers, a policy issued 120 months on, rows valued on the first anniversary and the month after, and a row whose additions at the anniversary exceed those entering month 0 are accepted; and the committed table is whatWholeLife_US_Sgenerates.The opening state and the rest: the twin of the worked example’s point opens with the four values
WholeLife_US_S’s goldens read before its frame, and at the shipped assumptions it is S’s point from month 108 on, in every cell but those expense inflation moves, which carries the walk through policy year 10 over; the derived rows carry the dividend, the accumulation balance, the premiums paid and the anniversary values as above, and with the first three zeroed they give the 1,800.00, the shortfall of 1,060.82 and the 450.00 above; expense inflation runs on the valuation clock at the shipped 2%, which only this test sees, since the splice sets the rate to 0; acquisition falls on new business alone; onWholeLife_US_S’s point 2 at an A/E of 5.0, where the product passes 1 at attained age 97, the rate is the float 1.0 in both models on four rows, three of themWholeLife_US_S’s in every cell, the capped months included, every policy in force dies in the first capped month and none is in force after it, and a NaN sent to the cap stays NaN; every guarded cell holds its value outside cover and reads no rate there, on the committed points and on the splice’s future rows, which carry the rider, the blend and each dividend option before issue; the points of a block sum row by row; an extract without the generator’s three columns projects the same numbers; andrun_sec.pyprints the model’s numbers, for a point in force, a point restated, a point to be issued and the block, line by line, and sums the block asgroupbydoes, bit for bit; and outside the repository, beside a copy of the model or at a path too shallow to hold one,run_sec.py --cythonsays it cannot build.The fingerprint (C2): before the compile step changed anything, what the model computed on each committed point was frozen in the module, each column of
result_cf()andresult_pols(), its sum, its largest value and its values at five months, and the model reproduces it to 1e-12.python tools/gen_sec_fingerprint.py WholeLife_US_SEC --checkmakes the same comparison. The tests above held through the compile step with their call syntax changed: a point’s position for its label, the codes for the text of a timing or a kind, and the three claims cells forclaims(t, kind). The extract is labelled 122 down to 101 rather than by position, and each point is named by its label, inpoint_id(), in a refusal and inrun_sec.py’s output.What compiling changed: the claims total is
WholeLife_US_S’sclaims(t)bit for bit, sign of a zero and type included, and each kind itsclaims(t, kind), on the fourteen new-business twins in every month, and in a month whose three kinds are all −0.0, set in both models, it is 0.0, asWholeLife_US_S’ssumgives; each premium period, on S point 9 at issue ages 30 and 50, decodes toWholeLife_US_S’s premium-paying years and MEC flag; a dividend option writtenPAUisNONEand the point isWholeLife_US_S’s in every cell;div_round_digitsat −1,000 and at −401 isWholeLife_US_S’sNone, and at −400, −2, −1 and 0 its own −400, −2, −1 and 0, on the anchor cell’s twin from S’s month 108; and a point issued belowissue_age_minis refused byproj_len(), naming it, issue age −1 at the shipped bound and the anchor cell’s twin, at 45, under a bound raised to 46, which projects at the shipped 0.Decoding: what cannot be decoded, a premium period or a mode, a
point_idthat is not whole, a table with a gap, a repeat, a key that is not whole or is written as text, a model point’s issue age past int64, is refused naming the points, the schedule or the table, by theDatacell that reads it and by a projection; a table whose keys are written as floats projects exactly the committed numbers, as it does inWholeLife_US_S, and a model point’s issue age of 45.5 projects asWholeLife_US_S’s point at 45, bit for bit, and −0.5 reads 0 and is issued; a key beyond a table, an age either side of the mortality and the net single premiums, a policy year past a schedule, an issue age, a sex and a final-expense key the tables lack, is refused by the one cell that reads it, naming the point; and the padding beyond each table’s extent is NaN.Values a bound reads: each amount, share, probability and price above written blank, as text, as an infinity or outside its range, one at a time and two in one column, a value of a key no point carries among them, is refused naming the file, the column and every line, key or point at fault, by the
Datacell that first reads it and by a projection; no other rule refuses the copy; and each edge of each range is accepted and projects.No pandas in
Projection(C5), intests/test_compiled_conventions.py, which holds what every_SECmodel meets once it compiles. Read from the formulas, with no compiler: no cell but the reporting ones refers to pandas, numpy or another module, reads a table with.locor the like, calls a reporting cell, holds text but in its docstring and its refusals, or holds a generator, a comprehension or a nested function; none calls anything but a cell, aDatavector and the builtins Cython turns into C, but fordiv_base’sround, which the registry admits by its cell, and a test holds every such admission to a builtin its cell does call; everyDatavector a formula reads is an int64 or float64 array, read by element; no cell is uncached; and each label accessor returns its point’s column of the same name.Compiled, where modelx-cython and a C compiler are installed, after compiling the model once into a temporary directory, never into the tree. In the same conventions module: the generated declarations give every cell but the reporting ones a C
bint,long longordoubleand a C-array cache of exactly the spec’s size, and every newDatacell but a reader a typed memoryview or a C scalar, and the generated C keeps no Python object among a projection cell’s locals, calls no Python builtin there but the one admitted, and builds no container, under both directives (C3); on the committed points, every cell at every argument a full modelx sweep caches is what modelx computes, bit for bit on x86-64, and so is every raise and everyDataarray (C4); andrun_sec.py --block, run compiled, holds one point’s ItemSpace at a time. Intests/test_whole_life_us_sec.py: the same comparison on the splice grid, the core by default and the full grid withUSLIB_SEC_FULL=1, variants included, twenty rows at a time; on the contract’s seven extremes, the five frames from issue age 0 and the oldest final-expense issue ages, with rounding off; and where the cap binds, and where a NaN reaches it; the compiled model refuses what modelx refuses, with modelx’s message, on the relabelled extract too, every value it cannot decode, every value a bound reads outside its range and everyduration_mthand issue age of2**53or more, and an argument past a cache raisesIndexError; the deepest call the contract allows runs cold on a 1 MiB stack and on the main thread, and the test reports the smallest of seven stacks, 256 KiB to 2 MiB, it ran on, waiting a bounded time for each; a Reference set after the model has computed changes no value it has cached; andrun_sec.py --cythonprints whatrun_sec.pyprints, and refuses a directory that holds no build. They are markedcython, and they skip without the toolchain, but in thecythonCI job, which installs it on Linux and on Windows and runs the core grid, a skip fails, whatever made it.
python -m pytest tests/test_whole_life_us_sec.py -q
USLIB_SEC_FULL=1 python -m pytest tests/test_whole_life_us_sec.py -q # the full grid
python -m pytest tests/test_model_conventions.py -q -k WholeLife_US_SEC
python -m pytest tests/test_compiled_conventions.py -q -k WholeLife_US_SEC
python -m pytest tests/test_whole_life_us_sec.py -q -m cython # the compiled tests alone