In-Force Implementation Notes#
Status: Draft, 2026-11-03. VUL_US_SEC is VUL_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
VUL_US_Son another time axis, and it readsVUL_US_S’s assumption tables in place, every assumption unchanged. The contractual elements come from four registered prospectuses [S1] [S2] [S3] [S4]. The separate-account return scenario, the dominant assumption for this product, is std in full, and so are the current COI scale, the mortality table, the lapse vector and every expense. Replace them with company data before drawing any conclusion from the numbers.
Run it#
python products/variable_ul/run_sec.py # point 1: the anchor cell, in force
python products/variable_ul/run_sec.py 6 # point 6: the loan cell, six months on
python products/variable_ul/run_sec.py --block # every model point, summed row by row
python products/variable_ul/run_sec.py 6 --cython # point 6 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 three
minutes, 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 account value roll-forward and the cash flows
run.py prints for VUL_US_S’s point 1, the worked example’s month at t = 0 among
them, each table line for line the same, and then the counts and rates behind them. Point
1 is in force 24 months at the valuation date, as it is at the start of VUL_US_S’s own
projection, so its row t = 0 is the worked example’s month here as there. Three lines to
the same thing for point 6:
import modelx as mx
model = mx.read_model("products/variable_ul/VUL_US_SEC")
model.Projection[5].result_cf() # point 6, the table's sixth row
Projection takes idx, the position of a point in the table, as basiclife/BasicTerm_SC
does: Projection[5] is point 6, and its point_id() says so. Its four result tables are
indexed by t, with one row per month from the valuation date, t = 0 … proj_len() − 1:
Cells |
What it shows |
|---|---|
|
|
|
|
|
|
|
The counts behind |
VUL_US_S’s three self-checks, check_av_roll_fwd(), check_margin() and
check_net_view(), run over the same frame.
--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 prints where each point stands at the valuation
date, then the block’s first twelve rows and the block summed into projection years. 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 the end of the projection, the last month at attained age 121.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 from issue,duration_inforce + t, 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 inVUL_US_S.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.
VUL_US_S already runs this policy clock, from the first month of its own projection, and
opens its in-force points there: points 1 and 2 at 24 months and point 4 at 120, with
their subaccounts, their fixed option and their loan. What the valuation clock adds is
that t = 0 is one instant for every point, that a point may be issued after it, and that
a point in force brings in what its past has left it: the loan account, which has grown
apart from the debt since the loan was taken, and the face its withdrawals have left.
Point 4 is VUL_US_S’s in-force cell with a loan, in force 120 months. At t = 0 it is
on the anniversary that opens policy year 11, at attained age 55, with a fixed-option
balance and an $8,000 loan at the preferred loan rate, and its frame has 804 rows,
t = 0 … 803. Point 6 is the same policy six months on, in force 126 months: policy year
12 begins at t = 6, where the attained age steps to 56, and its frame has 798 rows.
Point 9 is VUL_US_S’s point 3 to be issued 25 months after the valuation date:
duration_mth(0) = −25, it is on the books from t_entry() = 25, rows 0 to 24 are zeros,
its first premium of $500.00 falls at t = 25, and its frame has 949 rows.
Read on the policy clock |
Read on the valuation clock |
|---|---|
the surrender charge by policy year and the lapse spike at its cliff, policy month |
the separate-account return scenario, |
The return scenario is an economic input. VUL_US_S keys scenario_table.csv by its
projected month t already, so the table is on the valuation clock as it stands: a
scenario is a path of the economy from the valuation date, the same month for every point
of a block, however old the policy. On VUL_US_S’s own in-force points the two models
read the same months, because VUL_US_S opens them at its own t = 0. A point restated
at a later month reads the path from its own valuation date instead. VUL_US_S’s point 1
restated in force at its month 12 reads month 0 of WE as shipped, the worked example’s
month, +1.00% on its first subaccount, where VUL_US_S in its month 12 reads the level
path, 0.4868% a month. Its first subaccount closes month 0 at 34,396.04 against
VUL_US_S’s 34,221.25, 174.79 above, its account value 46.71 below, and its net_cf is
0.152 above in month 0 and 0.129 above in month 100. On a copy of WE re-based to month
12 the row is VUL_US_S’s projection exactly. That is the clock at work, not a fault: a
restated row continues the S projection only on a scenario re-based to its own valuation
date, so the tests give every restated or future row a re-based copy of its own
(Tests, below). The committed derived rows all read the flat LEVEL6, on which the
month makes no difference.
Expense inflation keeps VUL_US_S’s step by year and moves it onto t, so the
maintenance expense steps on the valuation anniversaries, in valuation-date dollars, for
every point alike. It ships at 0, as in VUL_US_S, since the variable-UL notes give the
$75 a year no inflation, so the clock shows in no number. The declared fixed rate is an
economic input too, read at t, and ships flat at 1.0%. Acquisition is charged per policy
issued, in the issue month, and not inflated, as in basiclife/BasicTerm_SE; it ships at
zero, as in VUL_US_S.
The two first-month pins, corridor_override_m1 and coi_rate_override_m1, apply at
t == 0, as in VUL_US_S, and here t = 0 is the valuation month. Point 1, the worked
example’s anchor cell, is in force there, so its corridor_factor(0) is the pinned 2.15
and its coi_rate(0) the pinned 0.04, where the rule, which takes over at t = 1, gives
2.03 and 0.1297335 in policy year 3; point 2, the same cell with both pins blank, takes
the rule from t = 0. Data refuses a pin on a point issued after the valuation date,
where t = 0 falls before issue and the pin would never apply, and the generator leaves
the pins blank on every row it restates at a later month.
The pricing path behind the funding ratio, the notes’ AV*, is a projection made at
issue: the account value under the level 6% pricing return, current charges and planned
premiums, with no decrements, loans or withdrawals, from zero at issue. It is keyed by the
policy month from issue, m = duration_mth(t), so it is on the policy clock, and it reads
no state: a point in force reads it from issue, with no opening value. Beyond its chain of
calls, one cell a month here (Counts and timings, below), it parts from VUL_US_S’s in
two places. funding_ratio(t) is 1.0 outside cover before it computes m: before issue
m is negative, and the path, based at m = 0, would recurse without end. And the path
credits its fixed option at pricing_fixed_return_mth(), one rate for
every policy month, the declared rate’s level, which is
(1 + max(guar_rate_ann, crediting_rate_curr))^(1/12) − 1, where VUL_US_S credits it at
fixed_return_mth(m), the projection’s rate read at a policy month as though it were a
month of the projection. As shipped the two are one float. Under a declared rate that
moves with t they part: VUL_US_S’s pricing path moves with it, a different rate for
each point, and this model’s does not, since no declaration after issue moves a projection
made at issue. The behaviour module ships off, dyn_behavior_on = False, so no shipped run
reads the path at all.
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
VUL_US_S computes, whatever the point’s count: VUL_US_S charges acquisition on the
policies in force in the issue month, which on new business are the policies issued. On
point 3, the twin of VUL_US_S’s one new-business point, every cash flow and every count
agrees, and so does every other cell the two models share, at every argument VUL_US_S’s
own sweep evaluates, 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. On points 1, 2 and 4,
VUL_US_S’s in-force points, which both models open at the valuation date, the projection
is VUL_US_S’s from t = 0 on, in every report and every cell the two share but
model_point(), the expenses included, since inflation ships at 0.
The in-force interface#
The model point table is model_point_table_sec.csv. It carries VUL_US_S’s columns,
pols_if_init renamed policy_count, and ten of its columns are the in-force interface,
with the shipped lineup of two subaccounts: basiclife/BasicTerm_SE’s two, six that open
an in-force policy’s state, one of them for each subaccount, and VUL_US_S’s two
first-month pins, which apply in the valuation month. 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 |
the start of month 0, before any month-0 event: the close of policy month |
subaccount |
|
dollars |
the start of month 0 |
the fixed option’s value |
|
dollars |
the start of month 0 |
the loan account: the collateral a loan has moved out of the investment options, part of the account value |
|
dollars |
the start of month 0 |
the policy debt, the interest accrued to then included |
|
dollars of face |
the start of month 0: after policy month |
the face in force, after every Option A withdrawal cut to date; at most |
|
a corridor factor, and a current COI rate per $1,000 a month, or blank |
the valuation month, |
the worked example’s two pins, which apply at |
The six state columns are 0 on a point issued at or after the valuation date: it is issued
with no account value and no loan, at the face sum_assured. sa_pp_init_<i>,
fa_pp_init and loan_bal_init are VUL_US_S’s own columns: they already measure the
accounts and the debt entering VUL_US_S’s first month, so they keep their names. Each new
column is named for the cell it opens, on VUL_US_S’s stem: la_pp_init for the loan
account, la_pp_at, beside VUL_US_S’s sa_pp_init and fa_pp_init, and
sum_assured_init for sum_assured_at, under UL_US_SEC’s name for the face in force.
UL_US_SEC’s other three state columns would open no cell here. The product tracks no free
withdrawal allowance, since the variable-UL notes cut the face proportionately with no free
amount, and neither the premiums paid nor a MEC latch, since the notes do not enforce the
guideline premium or 7-pay limits in the baseline: so there is no wd_used_year_init,
cum_prem_init or is_mec_init. No quantity of the product is read at the last
anniversary, so none needs a column at a second instant.
|
|
Why |
|---|---|---|
|
|
The count, under BasicTerm_SE’s name. |
|
|
The same column, now at the valuation date, and negative for a policy to be issued after it |
|
the same |
|
— |
|
|
— |
|
|
|
the same |
Applied at |
On the twins the two new columns take what VUL_US_S itself assumes, so each twin opens as
its S row does: on point 4 a collateral equal to its debt, 8,000.00, and on points 1, 2
and 4 the face at issue, 500,000.
The columns carried over are read as VUL_US_S reads them. For a policy in force, the
facts they record are still those at issue, the option, the premium, its load, the
allocation, the withdrawal and the scenario excepted:
Column |
Unit |
Measured at |
|---|---|---|
|
labels |
— |
|
years, age nearest birthday |
issue, not the valuation date: |
|
codes, as in |
issue |
|
dollars of face |
issue: the base of the $0.20 per $1,000 charge and of the surrender charge, whatever later withdrawals cut the face to |
|
|
the option in force over the frame |
|
|
issue |
|
|
the pattern over the frame; a single premium falls in the issue month alone |
|
dollars a year, the planned premium, or the single premium on |
the plan over the frame, paid monthly on |
|
a fraction of each premium |
the current load over the frame |
|
fractions of each net premium |
the allocation over the frame |
|
dollars a month |
the withdrawal taken in every month of cover until attained age 121; 0 on every shipped point |
|
a flag and a schedule ID, a row of |
issue |
|
a scenario ID, rows of |
the path read from the valuation date on |
|
text: |
— |
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 in-force columns are present,
sa_pp_init_<i>for each subaccountData.subaccounts()lists, and so areage_at_entry,has_surr_charge, every amount the projection reads as a number,sum_assured,premium_pp_annandwd_pp, and every share it reads,load_prem_rate, eachalloc_<i>andalloc_fixed;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 −120 or more: “model_point_table_sec.csv: duration_mth must be -120 or more, a policy issued at most 120 months after the valuation date; it is not at point_id [9]”. Future new business is written over a horizon,Data.future_horizon_mth, 120 months as shipped, so that no frame runs longer than the projection from issue plus ten years: 1,584 months at issue age 0, the youngest the product issues, and 1,044 at 45, the only issue age the shipped COI scale carries. Set to 0, the Reference refuses future new business altogether, and a negative horizon is itself refused;age_at_entryis a whole number of years, 0 or more: the projection takes itsint()and counts its frame and every attained age on it;sum_assuredis a number above 0, the face every policy holds at issue, and each ofpremium_pp_annandwd_ppis a number, zero or more. Each reaches the account value, the face or the death benefit, whereVUL_US_Sreads a blank as a missing value;load_prem_rate, eachalloc_<i>andalloc_fixed, the share of each premium the load takes and the shares of each net premium the accounts take, is a number from 0 to 1: “model_point_table_sec.csv: load_prem_rate must be a number from 0 to 1; it is not at point_id [3]”. A load past 1 would credit the accounts a net premium below 0, every check passing: at 1.5, point 3’s accounts would take −250.00 of its 500.00 premium in month 0. Allocations past 1 would credit them more than the net premium;has_surr_chargeisTrueorFalse, as pandas reads those words. A blank, a number or any other text is refused, naming only the points at fault: one text value turns the whole column into text, where"False"is a true string, so that every point would read as carrying a surrender charge;each subaccount, the fixed option, the loan account, the debt and the face in force is a number, zero or more. A balance is never negative in force.
VUL_US_Slets a subaccount fall below zero once the point is in permanent shortfall, because it does not implement the grace cascade that would end such a policy, so the message for the accounts says what to do: restate a point in permanent shortfall no later than the last month its account value is still zero or more, as point 7 is;a policy not yet in force,
duration_mth0 or less, has an opening state of zeros;sum_assured_initis above 0 on a policy in force, which holds a face, so an extract that leaves the column at zero is refused, rather than projected on the corridor alone;sum_assured_initis at mostsum_assured, since face increases are not modelled. A face below it is accepted, whether withdrawals cut it or an elective decrease the model does not implement, and it is projected from the value given;the loan account is above 0 exactly where the debt is: “model_point_table_sec.csv: la_pp_init must be above 0 where loan_bal_init is, and 0 where it is 0: the loan account holds a loan’s collateral while the loan is outstanding; it is not at point_id [1]”. A loan moves value out of the investment options into the loan account, and the model takes no new loan and no repayment, so the two are held together from the loan’s first day, each growing at its own rate;
each pin is blank, or a number, zero or more;
each pin is blank on a policy issued after the valuation date: a pin applies in the valuation month,
t = 0, before such a policy is issued, so it would never apply.
A point at or past the end of the projection at the valuation date,
duration_mth ≥ 12 × (122 − age_at_entry), reads, but proj_len() refuses it, naming the
point: “point_id 4: duration_mth 924 is at or past the end of the projection, policy month
924, attained age 122”. The end of the projection is the model’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 assumption tables are checked too, each once, in the Data cell its reader in
Projection takes its extent, its count or its lineup from. The tables read at a policy
year or an attained age take their extents from prem_persistency_last_year(),
lapse_last_year(), corridor_age_first() and corridor_age_last(), and
mort_age_first() and mort_age_last(), beyond which each reads its nearest row, and from
coi_schedules(), which checks coi_rates.csv and numbers its issue-age cells, each with
its last policy year. The key column is read by value, so a year written 5.0 is 5, and a
key that is blank, text or not a whole number is refused, naming the file, the column and
the lines it is on. So are keys that do not run one row a year or an age, without a gap or a
repeat, policy years from 1, the message naming each key that repeats, with its lines, and
each that is missing: “lapse_table.csv: the policy years must run from 1, one row a year,
without a gap or a repeat; no line holds policy_year 5”. So is a blank sex or class in the
COI scale, and a rate that is blank, text or infinite. A lapse or mortality rate is a
probability, held to 0 to 1, since past 1 the monthly rate 1 − (1 − q)^(1/12) has no real
value: “lapse_table.csv: lapse_rate_ann must be a number from 0 to 1; it is not on line
[6]”. A class factor, a guaranteed COI rate, a fund expense, a premium persistency factor
and a corridor factor are held to 0 or more, since below it each projects negative deaths, a
credit, a negative premium or a death benefit past the option’s amount, every check passing.
A COI rate is a charge per $1,000 of net amount at risk, not a decrement, and the current
scale passes 1 from attained age 72, as it should. class_count() and surr_charge_count()
check the class factors and the surrender-charge schedules, for the per-point joins that
read them, the same way: a class or a schedule blank or on two rows, and a factor or a
charge that is not a number, or is below 0. A charge below 0 is none to VUL_US_S’s max
through the schedule’s years, and after them a charge that rises each policy year: written
at −18.00, the shipped schedule charges $1.29 per $1,000 in policy year 16, every check
passing. surr_charge_count() also refuses a run-off that is not a whole number of years, 1
or more: “surr_charge_table.csv: runoff_years must be a whole number of years, 1 or more; it
is not on line [2]”. The projection divides the charge by the run-off and counts policy
years on it, where VUL_US_S truncates a fraction with int() and divides by zero at 0.
Two tables are checked in cells of their own, because their keys do more than find a row.
subaccount_count() checks the subaccount lineup, read by value, and subaccounts() holds
its ids in the file’s order, the one copy of them, whose positions Projection reads a
subaccount’s inputs at. Its ids name the
model point table’s columns, sa_pp_init_<i> and alloc_<i>, so an id written 1.0 must
still name sa_pp_init_1: here it does, and VUL_US_S, which names the column from the
id as pandas reads it, asks for sa_pp_init_1.0 and raises KeyError. An id that is
blank, text or not whole, a lineup with no subaccount, an id on two rows and a fund
expense that is not a number, or is below 0, are refused. scenario_count() checks the
return scenario, which scenario_rows() reads once, in the file’s order, so that a
refusal can name lines, and scenario_last_mths() gives the last month of each scenario
and subaccount. A blank
scenario_id, a subaccount_id or t that is not whole and a return that is not a
number are refused, and so are months that do not run one row a month, from 0 or later,
without a gap or a repeat, each clause naming its scenario and subaccount:
“scenario_table.csv: the months of each scenario_id and subaccount_id must run one row a
month, from 0 or later, without a gap or a repeat; at (‘WE’, 1), no line holds t 2”. A
path may start after month 0: one re-based to a policy issued after the valuation date
holds nothing before its issue month, and a read there raises.
Each reader asks for its extent, the count or the lineup before it reads a value, so a
projection meets the checks first. VUL_US_S takes each extent from the key column as
pandas reads it, where a blank key is a missing value the extent skips: the table is cut
short, and every later year reads the last good row, without a word. A blank value is a
missing value to it too, which shows in its flows or is lost in a min or a max: a
blank corridor factor reads as no corridor and a blank surrender charge as none. Here the
cap on the mortality rate, min(q, 1.0), keeps a blank base rate or class factor missing,
as VUL_US_S’s own does, and each of them is refused before any rate is read.
The model points#
No row of model_point_table_sec.csv is typed by hand. Every one is generated from
VUL_US_S and its table by tests/sec_support.py, from the VUL_US_SEC entry in its
SEC_SPECS, and the tests regenerate the table and compare, so an edit to a VUL_US_S
row reaches it or fails the suite. In the source repository,
python tools/gen_sec_points.py VUL_US_SEC writes it.
Point |
Kind |
From |
At the valuation date |
|---|---|---|---|
1, 2 |
twin |
S points 1 and 2 |
in force 24 months, in policy year 3 at attained age 47, with 30,000.00 and 20,000.00 in the two subaccounts on the |
3 |
twin |
S point 3 |
issued at |
4 |
twin |
S point 4 |
|
5 |
derived |
S point 3 at S month 12 |
on its first anniversary, inside the surrender-charge period: 3,877.96 of account value |
6 |
derived |
S point 4 at S month 6 |
the in-force cell six months on, in force 126 months, mid-year: 86,248.90 of account value, its collateral 8,039.90 and its debt 8,041.89 |
7 |
derived |
S point 3 at S month 593 |
Option B in the month its permanent shortfall begins, policy year 50, attained age 94, with 26.59 of account value |
8 |
derived |
S point 4 at S month 768 |
the first month at attained age 119, where the mortality rate reaches 1.0: every survivor dies at |
9 |
future |
S point 3, 25 months on |
to be issued at |
A derived row’s policy_count is the count VUL_US_S carries into that month, its
pols_if(d), and its opening state is what VUL_US_S carries into it, each column read as
VUL_US_S’s own formulas read it: each subaccount as sa_pp_at(d, i, "BEF_PREM"), the
fixed option as fa_pp_at(d, "BEF_PREM"), the collateral as la_pp_at(d, "BEF_PREM"), the
debt as loan_bal_pp_at(d, "BEF_PREM") and the face as sum_assured_at(d − 1). So the row
continues the S projection from there: point 5 opens with 0.938584 policies, and point 8
with 4.006e-10. Its two pins are blank, since VUL_US_S applies a pin at its own t = 0
only, before month d, and so are a future row’s, copied from its S point’s, which are
blank. A derived row’s policy_id is the S row’s with the month appended,
VUL-000003-M12, and a future row’s carries the months to issue, VUL-000003-F25. Row t
of a generated point is month t + source_mth of its S point. The derived rows restate S
points 3 and 4, which read the flat LEVEL6, so they need no scenario of their own. All
nine are on the anchor configuration M45 / StdNT / $500,000, because the notes disclose a
COI anchor for that cell alone [S4], so a point on any other issue age, sex or class needs
coi_rates.csv 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
the three timings that VUL_US_S already names, each an int Reference named as the string
VUL_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_MAT = 2, the count before any maturity,VUL_US_S’s meaning: theBEF_DECRcount, since the contract never matures and no event of the month separates the two.
Any other timing raises, the account value’s six among them, which follow in the same
numbering, BEF_PREM = 3 to EOM = 8 (The compiled model, below). VUL_US_S’s cell of
the name returns pols_if(t) for every timing, and nothing calls it. BEF_NB is the one
timing this model gives a meaning of its own, basiclife/BasicTerm_SE’s, and the two models
differ in it alone, in the issue month: there VUL_US_S counts the issued policies, and
this model counts them as new business, not yet in. As in UL_US_SEC,
basiclife/BasicTerm_SE’s "BEF_MAT", the count at the start of the month before its new
business, is not adopted: the name keeps its S model’s meaning.
The account value keeps VUL_US_S’s timings, codes too, which name the points of the
month in the notes’ processing order: BEF_PREM, the opening balance; BEF_WD, after the
net premium; BEF_FEE, after the withdrawal and its fee, the post-premium value the death
benefit and the net amount at risk are measured on; BEF_INV, after the monthly
deduction; and BEF_ME, after the gross return and the fund expense, before the M&E
charge. av_at adds EOM, the closing balance before the decrements.
Every chain of calls from month t back to t_entry() is one cell a month. BEF_NB
forms the survivors of month t − 1 itself, as its own value at t − 1 plus that month’s
new business, less that month’s deaths and lapses in the order pols_death and
pols_lapse take them. Each account’s opening balance forms the previous month’s close the
same way, the same products in the same order as the closing cell VUL_US_S calls for:
sa_pp_at(t, i, BEF_PREM) from its own value at t − 1 and month t − 1’s net premium
share, withdrawal share, deduction share and unit-value growth, where VUL_US_S’s
subaccount ran through six cells a month; fa_pp_at(t, BEF_PREM) likewise, where
VUL_US_S’s fixed option ran through five; and the loan account’s and the debt’s,
la_pp_at and loan_bal_pp_at, a month’s credited or charged interest on their own value
at t − 1, where VUL_US_S’s ran through two. The subaccounts and the fixed option share
each month’s withdrawal and deduction pro rata, so whichever is called first runs the
others alongside it, a month at a time. The face, sum_assured_at, calls itself at
t − 1 before anything else. The account value’s opening balance,
av_pp_at(t, BEF_PREM), is not a chain of its own: it is av_pp(t − 1), which sums its
parts’ closes.
On a model just read, a cold net_cf in the last month of point 1’s 900-month frame runs
920 cells deep, against 5,411 for VUL_US_S’s point 1: 21 cells above the chain back to
t_entry(). Point 3’s and point 4’s run 21 above theirs too, 944 and 824 cells. At the
longest cover the contract allows, issue age 0 and 1,464 months, it runs 1,484 deep,
whether the policy is issued at the valuation date or 120 months after it, because every
chain stops at the issue month: compiled, about 350 KiB of C stack with gcc (What a
compiled run needs, below). Each
chain’s head called alone, the loan’s, the collateral’s, the face’s, a subaccount’s and the
count’s, runs at most 10 cells above its chain. Each report evaluates its columns in
ascending t, and on a model just read the committed points’ four reports and three
checks run that way under a recursion limit of 17, and VUL_US_S’s under 16. That is
with the behaviour module off, as shipped.
With the behaviour module on, the funding ratio reads the pricing path at the policy month
from issue, and the path is a chain of its own, one cell a month, based at issue: each
opening balance of the path forms the previous month’s close itself, where VUL_US_S’s ran
through four cells a month. So a cold net_cf on a point in force runs back to issue, not
to the valuation date: 939 cells on points 1 and 4, the 923 months of the frame’s last
month from issue and 16 more. At the longest cover it runs 1,484 deep, module on or off.
The path stays based at issue. Its state is its own balances, the subaccounts’ and the
fixed option’s, which the pro-rata deduction couples month by month, so a form based at the
valuation date would have to carry them all through one loop in one cell.
So with the module on, the first month’s funding ratio of a point in force at policy month
d reads the pricing path cold, back to issue, however the months after it are evaluated,
and an ascending sweep runs d + 16 cells deep: 40 on point 1, 136 on point 4, 904 on
point 8, and 1,478 on a point in force in its last covered month at issue age 0, against
18 on every committed point, and 15 on that one, with the module off. It needs a modelx
recursion limit of d + 15, 39 on point 1 and 135 on point 4. A point issued at or
after the valuation date, whose path starts in its issue month, sweeps 22 deep under a
limit of 21. The cold call’s bound is unchanged, 1,484 cells at the longest cover, so the
deepest stack is the same; only the depth of a typical point in force grows with its
duration.
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 VUL_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.
Cover is is_active(t), 0 ≤ duration_mth(t) < omega_mth(), where
omega_mth() = 12 × (omega_age − age_at_entry + 1) is VUL_US_S’s frame from issue, the
first month at attained age 122. Outside it, before issue and from t = proj_len() on,
every count, premium, withdrawal, charge, decrement rate, decrement, claim and cash flow is
zero and every flag false; only the two clocks, the inputs read on the valuation clock, the
loan account’s level credited rate, and the neutral 1.0 of the two lapse multipliers and
the funding ratio hold values there, and the month after the frame holds one exception
more, below. 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: prem_persistency,
prem_persistency_base, premium_pp, wd_pp, sum_assured_at, corridor_factor,
db_pp, db_pp_eom, coi_rate_guar, coi_rate, coi_pp, maint_fee_pp,
loan_rate_ann, surr_charge_rate, mort_rate, lapse_rate_base, pols_death,
pols_lapse and expenses are zero, and is_default false, before any table or rate is
read, and every other value is zero through them. lapse_rate_sc_mult is 1.0 there,
before it compares the policy month with the cliff, since a run-off of n years puts the
spike at policy month 12 n, which can be the month after the frame; and funding_ratio
is 1.0 before it computes the policy month the pricing path is read at. The scenario’s two
readers, gross_return_mth and inv_return_mth, take no guard, since an economic input
is one path for every point, and no formula reads them outside cover. Each table read at a
policy year or an attained age has one reader keyed by it, called inside cover only, so on
point 9, whose policy year is −2 at t = 0, no reader is asked for a policy year below 1
or an attained age below 45.
The end of the projection. The frame ends at omega_mth() because the mortality table
ends at attained age 121, not at an event of the contract, which never matures. With the
shipped table, whose annual rate is 1.0 from attained age 119, and a class factor and an
A/E of 1 or more, every life has died by the end of the first month at attained age 119:
point 8, valued in that month, loses its last 4.006e-10 of a policy at t = 0. With a
preferred class, an A/E below 1 or a table that stays below 1, lives survive the last
month, and VUL_US_S’s roll-forwards read them: check_av_roll_fwd() and av_change()
read the account value in force entering month t + 1, which in the last month is
t = proj_len(). So the two opening values read there, the count carried in
(pols_if_at(t, BEF_NB), and through it pols_if(t)) and the account value carried in
(av_pp_at(t, BEF_PREM)), are defined for 0 ≤ duration_mth(t) ≤ omega_mth(): in the
month after the frame they are the survivors of the last month and the account value they
carry, VUL_US_S’s own values there. Everything else is zero or false there, each
account’s opening balance included, since a loan account carried into the month would earn
a month’s credit past the frame’s end, and the expenses, which would otherwise fall on the
carried count. Nothing reads past it: av_change() and the three checks’ residual cells,
which read t + 1, are zero outside cover before they read it. At the shipped assumptions
the survivors at proj_len() are exactly 0.0 on every committed point. At an A/E of 0.56,
the rest as shipped, they are 3.88e-6 of a policy on the twin of point 1, 3.46e-6 on the
twin of point 3 and 5.44e-6 on the twin of point 4, each equal to VUL_US_S’s, and the
three checks close.
A lapse rate past 1. VUL_US_S’s annual lapse rate, the base rate times the cliff’s
spike times the dynamic multiplier, has no cap, and this model keeps it so. Data holds
each base rate to 0 to 1, but the spike, lapse_shock_mult, and the multiplier’s bound,
lapse_dyn_cap, are References. With both at 0 or more, the annual lapse rate is at most
max(1, lapse_shock_mult) × (lapse_dyn_cap with the behaviour module on, 1 with it off)
× the largest base rate, since the spike is 1 outside its month and the multiplier 1 with
the module off. It stays at most 1 while that product is at most 1: 0.06 as shipped, 0.12
with the module on and 0.36 under the tests’ splice. Past 1 the monthly rate
1 − (1 − q)^(1/12) is complex, and so is every count after it, in both models: with a
spike of 40, point 3’s rate is 1.2 in its cliff month, policy month 168. VUL_US_S’s
checks raise TypeError there, and so do this model’s, whose residuals are floats, so
that a complex residual, whose magnitude would pass, cannot. Compiled, the power is NaN
instead, and the checks fail rather than raise.
The opening state#
VUL_US_S opens its in-force points from three kinds of column, each subaccount, the fixed
option and the debt entering its first month, and takes the rest as they stand at the start
of a loan and at issue: the loan account equal to the debt std, and the face at issue.
Its points 1, 2 and 4 need no more, and their twins open the same way. A policy valued in
any month of its life needs all six state columns, each what VUL_US_S carries into that
month. Point 6, VUL_US_S’s in-force cell six months on, shows two of them, and each is
compared below with the same row read as VUL_US_S would open it:
la_pp_init. In six months the collateral has grown at the 1.0% credited to the loan account and the debt at the 1.05% charged in policy year 11, so point 6 holds 8,039.90 of collateral against a debt of 8,041.89. Read as the debt, asVUL_US_Sopens its loan account, the account value entering month 0 would be 86,250.89 for 86,248.90, 1.99 high, andnet_cf0.00496 lower in month 0 and 0.00487 lower in month 11.sa_pp_init_<i>andfa_pp_init. The two subaccounts and the fixed option hold 41,701.23, 26,052.83 and 10,454.95, each what its own returns have made of it: the subaccounts grow at the scenario’s return less their fund expenses and the M&E charge, the fixed option at the declared rate. Spread by the allocation, 50/30/20, the unloaned 78,209.01 would be 39,104.50, 23,462.70 and 15,641.80, the same total, and the account value would close month 0 16.12 lower and month 11 196.05 lower,net_cf0.040 and 0.473 higher.
No committed point withdraws, so none shows the face in force. It shows on
VUL_US_S’s point 3 changed to Option A and a withdrawal of $100 a month, at the shipped
assumptions. VUL_US_S takes the withdrawal in every month from issue and, on Option A,
cuts the face in proportion to it, as the variable-UL notes say: in the issue month $100
out of the 480.00 of account value the first net premium buys cuts the 500,000 by
104,166.67, and the withdrawals of months 0 to 12 leave a face of 174,445.82 entering
month 13:
sum_assured_init. Restated at month 13, the point opens with that face. Month 0’s withdrawal cuts it by 5,137.44 more, to 169,308.38, the death benefit of month 0, on which the cost of insurance is 19.83. Read as the face at issue, asVUL_US_Sopens every point, month 0’s cut would be 14,725.03 and the death benefit 485,274.97, with a cost of insurance of 57.58. The surrender charge is 8,357.14 either way, since it is quoted on the face at issue.
The two pins are not state: they are the worked example’s two lookups, applied in the one month it describes, and the generator leaves them blank on every row it restates.
Departures from VUL_US_S#
Each formula that opened at t = 0 now opens at t_entry(), from the opening state on a
point in force, and each cell that turns t into a policy year or an attained age answers
for the months outside cover. Of VUL_US_S’s 148 cells in Projection, 60 are unchanged,
36 have a new docstring only, most of them to say what t now counts, and 52 are
rewritten. None is removed or renamed, and 28 cells are new, 176 in all. Compiling then
changed how each cell reads its inputs and spells its codes, and no number: it replaced two
cells, subaccount_ids and coi_rate_scale, by the lineup’s size and a schedule number,
and added seven, 181 in all (The compiled model, below); of VUL_US_S’s cells it
changed the signature of two, claims and me_charge_pp, each now a total. The twin
identity exempts subaccount_ids and coi_rate_scale, each with its reason, compares
VUL_US_S’s claims(t, None) and me_charge_pp(t, None) with the totals, and reads each
of VUL_US_S’s subaccount ids at its position in the lineup: a cell of VUL_US_S’s that
this model lacked, or took other arguments, would fail it otherwise. VUL_US_S’s math
Reference is dropped. Of Data’s eleven, model_point_table is rewritten to check the
table as it reads it, scenario_table is formed from scenario_rows(), the scenario’s one
read, the same frame as VUL_US_S’s, and five readers have their read_csv call wrapped;
running in force added twelve cells, 23 in all, and the Reference future_horizon_mth,
120. Compiling added 42 cells, 65 in all, and the References np and
return_horizon_mth, 1,585, the last month the array of returns holds; it made three of
the checks ints, and widened the checks of the model point table and of the two age
tables. The cap on mortality,
min(q, 1.0), is VUL_US_S’s own, and no departure. Some departures come from compiling
rather than from the clock: proj_len’s new refusals, gross_return_mth’s past the
horizon and the last four rows below.
Cells |
|
|
Why |
|---|---|---|---|
|
|
|
|
|
a recursion from |
|
Policies in force at the valuation date open the count; new business joins it in its issue month |
|
|
the openings at |
Every chain one cell a month, since a compiled model runs it on the C stack; the loan account and the debt part once interest accrues |
|
|
|
The loan account is part of the account value, the debt is not |
|
the face at issue at |
|
A policy in force brings in the face its withdrawals have left |
|
the pricing path read at |
1.0 outside cover, before the policy month is computed; the fixed option credited at |
Before issue the policy month is negative, and the path, based at issue, would recurse without end. |
|
the table read in the cell, clamped to the extent of the key column as pandas reads it |
one reader keyed by the year or the age — |
No table is read at a year or an age the policy does not have, each is read once a year or an age, and a blank, text or fractional key, keys that repeat or leave a gap, a rate that is not a number, a lapse or mortality rate outside 0 to 1 and a premium persistency factor or a COI rate below 0 are refused by name, where |
|
the schedule’s row read in each |
|
The same numbers on any schedule, with no table read in a monthly cell; a blank charge, which |
|
the lineup, a list of ids, and the scenario as pandas reads them; a subaccount named by its id, its columns |
|
An id written |
|
branches on the text of |
branches on five decodes, |
No monthly cell compares text, and no projection cell calls a label accessor. The label accessors stay, for reporting, and a value no decode knows still raises |
|
the class factor and the COI scale, joined on the label accessors, the scale a Series sliced from the table by the point’s sex, class and issue age |
the class factor joined to the points in |
A blank factor, a missing value to |
|
the pin read from the model point in the cell, applied at |
the pin read once a point as a value and a flag, |
A monthly cell tests a flag rather than a missing value, and reads no model point column in its own formula |
|
unguarded: no |
zero or false outside cover, |
A future point’s months before issue have |
|
|
zero outside cover |
At |
|
the model point’s |
read once a point, by |
A monthly cell the accounts’ chains read reads no table |
|
|
|
Unit costs in valuation-date dollars |
|
|
the same condition on one relative residual a month, |
A residual a compiled model can type, and a failure that can be found by month |
|
the lapse term |
|
The surrender claim is the net cash value floored at 0, so once a loan exceeds the cash value |
|
|
|
The counts behind |
|
|
|
A compiled cell takes C numbers, and |
|
|
|
As for |
|
Python’s |
a loop over |
A compiled cell holds no generator. The same float as |
|
a malformed value or key met, if at all, only when a projection reaches it, a missing class, scenario or schedule as |
refused by name at the first read of the array, over the whole table: an issue age, a |
A compiled model holds numbers, not text, computes a NaN as silently as modelx, and holds each age table from age 0 (What it refuses, below) |
The other new cells of running in force are policy_count, t_entry, is_active,
pols_new_biz, the two new opening-state accessors, la_pp_init and sum_assured_init,
coi_rate_last_year, the extent of a point’s COI scale, and wd_pp_mth, the withdrawal
column read once a point; those of compiling are listed under What compiling changed, and
why, below.
Of the cells with a new docstring only, first_default_month and first_shortfall_month
keep VUL_US_S’s loops and return a month counted from the valuation date: point 7,
restated in the month its shortfall begins, is in shortfall from t = 0.
Of the cash flows, the change of clock moves the maintenance expense alone, and net_cf
with it, and only once inflation is switched on: it ships at 0. At 2.5% a year, point 4’s
expenses(t) is VUL_US_S’s divided by 1.025^10, about 1.280, at every t, and point
1’s by 1.025^2: both models step on their anniversaries. Point 6’s is VUL_US_S’s point
4’s divided by 1.025^10 for t = 0 … 5 and by 1.025^11 for t = 6 … 11, where its
policy year has stepped and the valuation year has not. Point 9 is VUL_US_S’s point 3
twenty-five months on in its other cash flows, its counts and its account value. Its
maintenance expense is 1.025^2 above VUL_US_S’s, and 1.025^3 in the last month of
each policy year, where the valuation year has stepped and the policy year has not.
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 a lineup
of nine subaccounts, and where the cap on mortality binds or a NaN reaches it. 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 variable_ul # in place, beside the model
python tools/build_sec_cy.py variable_ul --out /tmp/vul # elsewhere, with the CSVs
The tool exports the model to VUL_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 VUL_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/variable_ul") # the directory holding the build
from VUL_US_SEC_nomx_cy import mx_model as model
model.Projection[5].result_cf() # point 6, 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 = 5 after Projection.result_cf() leaves point
1’s frame cached, while point_id(), not yet computed, reads point 6’s label, and
Projection.expense_maint set to 90 once Projection[3] has computed point 4’s
expenses(12) leaves it at 6.0417, where an ItemSpace made after computes 7.2500. 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 three minutes with gcc, 170 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 144 of its 176 Projection cells as C numbers. Fifteen more took a timing or a
kind as text, or None for a kind or a subaccount, three were never called by the
reports and compiled as Python objects, and those 18 kept a dictionary for a cache; it
ran no faster than its own export, 279 ms a point on net_cf against 279, over the
committed points. The bodies of the typed cells still called pandas and Python: a
model_point() lookup for each attribute a formula reads, a .loc on a table for each
policy year’s persistency, lapse and COI rate, each attained age’s corridor factor and
mortality, each point’s class factor and surrender-charge schedule, a join on the
scenario’s text keys for each month’s return, a column named "alloc_" + str(i) for each
subaccount, the point’s COI scale sliced into a Series, pd.isna on the two pins, text
compared in every formula that branched on the death benefit option, the qualification
test or the premium pattern, a generator summed over the kinds in claims, and seven
summed over the lineup. 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[5]is point 6, 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.age_at_entry()[idx]). Compiled, the vector is a typed memoryview, and the read is a load from memory.Subaccounts by position.
VUL_US_Snames a subaccount by its id, lists the lineup’s ids insubaccount_ids()and reads a point’s allocation and opening value from the columnsalloc_<id>andsa_pp_init_<id>. Here a subaccount is its position in the lineup,i, from 0, in the order ofsubaccount_table.csv:subaccount_count()is the lineup’s size, which replacessubaccount_ids(), andDataholds the allocations and the opening values as tables by point and position,alloc()andsa_pp_init(), and the fund expenses as a vector by position,fund_expense_ann(). The ids are kept inData.subaccounts(), for the reports, soresult_av()names its columnssa1_bef_premand so on, asVUL_US_Sdoes. A position outside the lineup is refused, naming the point, by each of the four cells that read a subaccount’s input,alloc,fund_expense_ann,sa_pp_initandscenario_last_mth, so that no cell reads another point’s element or a column past the lineup.Text, decoded once. A C cell holds no text, so
Datadecodes each text column a formula branches on into 0/1 flags, for every point at once: the death benefit option intois_db_option_aandis_db_option_b, the qualification test intois_gpt, the premium pattern intois_level_premiumandis_single_premium, andhas_surr_chargeinto a flag of its own. Each decodes asVUL_US_Scompares the column, so a value none of the flags names is no flag, and the cell that branches on it raisesVUL_US_S’s message, asVUL_US_Sdoes. Each first-month pin is a float64 vector beside a 0/1 flag of whether the point gives one: the value is NaN where the pin is blank, asVUL_US_Sreads it and as the accessor returned at stageE, and the flag, never the value, decides, so no NaN reaches a formula.Tables indexed by integers. The persistency and lapse tables are held by policy year, and the corridor and mortality tables by attained age, padded from 0 so that the year or the age is the index. The COI scales, keyed by sex, class and issue age, are numbered from 1 in the order of those keys, each point carrying the number of its own,
coi_schedule(), and held by schedule and policy year incoi_rate_array, with the last policy year of each schedule beside it,coi_rate_last_years, read at the point’s schedule. The return scenarios, keyed by their id, are numbered the same way, each point carrying its own,scenario_index(), and held by scenario, subaccount position and month ingross_return_array, sized to the months a frame reads, with the first and last month of each scenario and subaccount beside it, so thatgross_return_mth(t, i)is one load atmin(t, last). The padding holds NaN, and nothing reads it: each table’s one reader refuses a policy year below 1, or a month before a scenario’s first or pastreturn_horizon_mth, naming the point, and reads an age outside the table at its nearest row, asVUL_US_Sdoes. The class factor and the surrender-charge schedule are one number a point, and each is joined to the points inData, which refuses a key the table lacks, naming every such point, sinceVUL_US_Sreads both on every projection of the point: the class factor in every month on the books, and the schedule in every month of a point with a charge. So is the return scenario, which every projection reads, at every subaccount, in its first month on the books. A point without a charge is never refused for its schedule, whichVUL_US_Snever reads; it reads its schedule’s two columns where the table holds its ID, as at stageE, and where the table does not,has_surr_charge_schedule()is 0 and both accessors raiseKeyError, naming the point, where their.locraised it at stageE. A point whose COI scale the table lacks is another matter: it reads the scale only while charges run, and a point valued or issued at or pastcharges_cease_agenever does, soVUL_US_Sprojects it. So it is schedule 0, with a last year of 0, andcoi_rate_last_yearrefuses it, naming it, where a rate is read.Codes. A timing or a kind, which
VUL_US_Sspells as text, is an int Reference named as the text: the count’s timingsBEF_NB = 0,BEF_DECR = 1andBEF_MAT = 2, the account value’sBEF_PREM = 3,BEF_WD = 4,BEF_FEE = 5,BEF_INV = 6,BEF_ME = 7andEOM = 8, andDEATH = 0,LAPSE = 1,MATURITY = 2andWITHDRAWAL = 3. A call reads as before, less the quotes:pols_if_at(t, BEF_DECR),sa_pp_at(t, i, BEF_FEE),claim_pp(t, DEATH). A string argument 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 two families of timing, the count’s and the account value’s, passed to different cells, are numbered as one,BEF_NBandBEF_DECRfirst, as in every SEC model, then the count’s third, then the account value’s in the order of their instants within the month,EOMlast, asUL_US_SECnumbers them, withBEF_ME, the one instant variable UL adds, in its place. So no two timings share a code, and a code of one family passed to the other’s cell,av_pp_at(t, BEF_NB), is refused asinvalid timingin both engines, where two families numbered from 0 would read it asBEF_PREMwithout a word. A cell compares a code with==alone, so that a text passed where a code is taken meets the cell’s own refusal in modelx too. TheProjectiondocstring’s Codes lists all thirteen.The two totals, split.
VUL_US_S’sclaims(t, kind=None)is one kind’s claims or, withNone, the two summed by a generator, and itsme_charge_pp(t, i=None)one subaccount’s M&E charge or, withNone, the lineup’s summed: neither a C parameter nor a C loop. Here the kinds are two cells,claims_deathandclaims_lapse, theresult_cfcolumns, andclaims(t)is their total,0.0 + death + lapse; and a subaccount’s M&E charge isme_charge_sa_pp(t, i), the name the family gives a subaccount’s share, andme_charge_pp(t)the lineup’s total, a loop from0.0(Departures from VUL_US_S, above).Loops for generators.
VUL_US_Ssums over the lineup withsum()of a generator in eight cells: the unloaned and the total account value,unloaned_av_pp_atandav_pp, the pricing path’s two,av_pricing_pp_atandav_pricing_pp, the M&E total, the investment income,inv_income_pp, the transfer to the general account,sa_transfer, and the account value at issue,av_pp_init, a loop since running in force. Each is a loop overrange(subaccount_count())from0.0, the terms inVUL_US_S’s order. On the shipped lineup of two it computesVUL_US_S’s float bit for bit: Python’ssum()of floats is compensated since 3.12, and the compensated sum of two terms, rounded, is their sum rounded once, which the loop computes. On a lineup of three or more the two can differ in the last bit: on 100,000 random lineups of three balances they differed 19,064 times. The fingerprint and the comparison of the compiled model with modelx compare this model with itself, so neither is affected, and the twin identity’s tolerance is far above a last bit;VUL_US_Sships two subaccounts, so no committed number moves.Two cells dropped.
subaccount_ids(), a list, andcoi_rate_scale(), the point’s COI scale as a Series, are gone,subaccount_count()andcoi_schedule()in their place. The twin identity exempts both, with the reason, and compares the COI rates incoi_rate_guarin every month and the lineup’s subaccounts at their positions.No Python call kept. No formula outside the reporting cells calls a Python builtin outside its refusals but
int,float,bool,abs,min,maxandrange, which Cython turns into C, all but oneint:lapse_shock_month’sintof the run-off, a float, is a Python int converted to a Clong long, exact below2**63and raisingOverflowErrorpast it, andDataholds the run-off below2**53(What it refuses, below). Sotests/us_registry.pyadmits none.surr_charge_ratedivides by the run-off as the float it is, whereVUL_US_Sdivides by itsint():Dataholds it to a whole number of years, which the float is exactly, so the quotient is the same float, and anint()there, held in a local, would keep a Python object in the cell. No cell is uncached, and none takes a float.Reporting cells stay Python.
model_point(), the label accessorssex(),rate_class(),db_option(),qual_test(),premium_type(),surr_charge_id()andscenario_id(), and the four reports return a table row, text and DataFrames, for a reader, forrun_sec.pyand for the comparison withVUL_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 not text: a blanksurr_charge_idon a point without a charge, which reads as NaN, or a column of numbers, ints, whichVUL_US_Sprojects, a numericscenario_id,sexorrate_classwritten so in both files, which joins as text does, and any other blank or numeric label, which the point’s first projection refuses. So each accessor compiles to a Python object, as the sample traces it (below), and returns what modelx returns. The three checks are reporting cells too, but they return a verdict, which compiles to a Cbint.
The Data docstring lists its vectors, arrays and counts, each with the column or file it
comes from: 13 vectors of int64 by point and 15 of float64; the allocations and the opening
values of the subaccounts, float64 by point and position; the lineup’s ids, int64, and
fund expenses, float64, by position; four float64 tables by policy year or attained age;
the COI scales by schedule and policy year, and their last years by schedule; the first
and last months of each scenario and subaccount, int64, and the returns by scenario,
subaccount and month, float64; and eleven int counts and extents, each a table’s check,
among them subaccount_count, the lineup’s, scenario_count, the return scenario’s, and
coi_schedules, the COI scale’s, which at stage E were a DataFrame and two Series. The
twelve readers stay Python, returning DataFrames and a path, and no Projection cell but
model_point() reads them. Every other cell of Projection, 169 of its 181, 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,586 by |
the 87 cells of |
a C array of 1,586 by 9 |
the 15 cells of |
a C array of 1,586 by 9 by 9 |
|
a C array of 1,465 by |
the pricing path, by the policy month from issue: eight cells of |
a C array of 124 by |
|
a C array of 123 by |
|
a C array of 9 by |
|
one |
the 44 cells without a parameter: the point’s label, numbers, decodes and flags, its opening state, its pins and their flags, its class factor, COI schedule and the scale’s last year, its scenario’s number, its surrender charge, run-off and cliff, the lineup’s size, the ends of its frame, the pricing rates, the first default and shortfall months, and the three checks |
a Python object |
the twelve 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 first switches the
behaviour module on, dyn_behavior_on, which ships off: off, no report reaches the
pricing path behind the funding ratio, the premium persistency scale or its reader. With
it on, it runs the four reports and the three checks on every committed point, which reach
every cell but these: model_point() and the seven label accessors, which only a reader
asks for; point_id(), which only a refusal names; inv_return_mth, the unit-value
factor the account chain forms inline; the default and shortfall tests and their searches;
and the pricing path’s three closes, sa_pricing_pp, fa_pricing_pp and av_pricing_pp,
which each opening timing forms itself. And of the cells they reach they leave some codes
uncalled: pols_if_at’s BEF_MAT, claims_from_av’s MATURITY, and the account cells’
timings no formula passes them. The sample calls those too, the monthly ones in every
month of the frame and the month after it, every account cell at every timing it takes,
and the pricing path at every policy month a point reads, from issue to its last month in
cover. It projects the committed points alone: the export it runs reads the CSVs of the
directory the build is made in, and the trace it needs is the committed points’, which are
what the tests project. The seven label accessors it calls once more, on a copy of the
table’s first point with every label blank, which it writes to a temporary directory and
reads by a second instance of the export, given the file’s absolute path as
model_point_file. That types them as Python objects, so that a blank or numeric label
returns what modelx returns rather than raising TypeError (What compiling changed, and
why). The committed points leave branches untaken: a withdrawal, a single premium, a
point without a surrender charge, the COI rate’s cap and the guaranteed bound binding,
mortality capped at 1, a first-month pin on a point issued at the valuation date, the
corridor pin alone. That still types every cell, because every branch of a cell returns
the one type its others return, a rate a float in every branch, and on points that take
those branches the compiled model computes modelx’s numbers (above). 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-forwards read and the compile
tests’ full sweep evaluates every monthly cell at; plus one because the index starts at
0, and one of headroom:
Parameters |
Size |
The largest argument |
|---|---|---|
|
1,586 |
1,584. The longest frame is a policy issued at the youngest issue age, 0, to the end of the projection at attained age 122, 122 policy years, and issued 120 months after the valuation date, the furthest ahead |
|
1,465 |
1,463, the policy month from issue of the last covered month at issue age 0, wherever the valuation date falls: the funding ratio reads the pricing path at |
|
1,586 or 1,465, by 9 |
the nine timings of the one numbering, |
|
1,586 or 1,465, by 9 by 9 |
the subaccounts’ positions by the timings, in |
|
9 |
8, the last position |
|
124 |
122, the policy year of the last covered month at issue age 0, read by the four readers by policy year inside cover alone, the pricing path’s among them |
|
123 |
121, |
proj_len() refuses a point issued below 0, issue_age_min, or above 85, issue_age_max,
the issue ages product-spec.md admits, one issued above omega_age, 121, and a lineup of
more than subaccount_max, 9, subaccounts, in modelx as compiled, and the projection ends
at attained age 122, so no report on a point the model projects runs past these caches.
issue_age_min, omega_age, subaccount_max and Data.future_horizon_mth are the
contract the sizes are derived from; issue_age_max sizes nothing, since every size rests
on the youngest issue age. Lower the minimum, or raise omega_age, the horizon or
subaccount_max, and a report runs past the caches in the compiled model alone: a frame of
more than 1,585 months, a pricing month past 1,464, a policy year past 123, an age past 122
or a tenth subaccount 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 ×
(omega_age − issue_age_min + 1) + the horizon + 2, m to 12 × (omega_age −
issue_age_min + 1) + 1, y to omega_age − issue_age_min + 3, a to omega_age + 2,
and the width and i to subaccount_max. Data.return_horizon_mth, 1,585, the last month
Data’s array of returns holds, is t’s last index, so that the array is no larger than
the months a frame reads, and it is raised with t. The shipped COI scale carries the
anchor cell alone, issue age 45, so a point at any other is refused today by its first COI
rate, naming it; an issue age of 0 is the contract’s, which an extended scale 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 nine powers: the monthly rates of both
decrements, 1 − (1 − q)^(1/12) in mort_rate_mth and lapse_rate_mth, the monthly
fixed-option, pricing and loan rates, (1 + i)^(1/12) − 1 in fixed_return_mth,
pricing_return_mth, pricing_fixed_return_mth, loan_rate_mth and loan_cr_rate_mth,
the premium persistency’s φ^(−δ) in prem_persistency, and expense inflation,
(1 + r)^(t // 12) in inflation_factor. Without cpow a
compiler with C99’s complex numbers, gcc among them, computes a power of two doubles 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 give (The
sample and the spec, above).
What a compiled run needs#
Memory, and the release. A compiled Projection ItemSpace is a C struct of 7,797,640
bytes, about 7.8 MB, the type’s basic size, which holds every cell’s cache, each beside a
flag array of its shape that marks what is computed. The two 3-D caches, sa_pp_at’s 1,586
by 9 by 9 and sa_pricing_pp_at’s 1,465 by 9 by 9, are about 1.5 and 1.4 MB of it with
their flags, and the 18 2-D caches about 3.0 MB more. That is 4.1 times UL_US_SEC’s, for
frames of 1,586 months against 1,358, nine subaccounts by nine timings where UL has none,
and the pricing path, which UL lacks. Making one costs time as well as memory: Python zeroes
the struct when it makes the ItemSpace, and making and releasing one, nothing computed, took
0.36 to 0.40 ms here, of the 2.5 ms a compiled point takes (Speed, below). 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, 504 compiled
points peaked at 3,610 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 account
value’s chain back to t_entry(), and with the behaviour module on the pricing path’s back
to issue, 1,484 cells deep in modelx, one cell a month and 21 more. Compiled with gcc, with
the module on, it runs on a thread of 352 KiB of stack and not of 344, and with it off on
344 and not 336, 232 to 243 bytes a level. 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. Until it has, the need is an
estimate: at the 325 to 433 bytes a level MSVC took on WholeLife_US_SEC’s chain, 1,484
levels need about 471 to 628 KiB, and at 1.3 to 2.0 times gcc’s frames, its ratio there, 450
to 705 KiB, inside 1 MiB by 1.45 times at the least, the thinnest margin of any model so
far. 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 a bounded time for each child rather than the
job’s hour. The export recurses in Python instead: the same call needs a recursion limit of
2,994 there with the module off and 2,984 with it on, and the four reports and the three
checks, which run in ascending t with the module on, need 1,834, the package’s import
among the frames they run under or not: a point in force reads the pricing path cold back to
issue in its first month, point 8, in force at policy month 888, the deepest. So
sample_sec.py sets 12,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 error itself propagates.
What
Datacannot decode, join or hold, when the array is first read, naming every point at fault, or the table and its lines: apoint_idthat is not a whole number; arate_classthe class factors lack,class_factor_table.csv has no factor for the rate_class of point_id [2, 6]; ascenario_idthe return scenario lacks, or one without a row for a subaccount of the lineup,scenario_table.csv has no returns for every subaccount of the lineup on the scenario_id of point_id [3]; and on a point thathas_surr_charge, asurr_charge_idthe schedules lack,surr_charge_table.csv has no schedule for the surr_charge_id of point_id [4], each of which has_surr_charge.VUL_US_Sfails every projection of such a point with aKeyError, and no projection of a point without a charge reads its schedule, so none is refused for it; on such a point whose ID the table lacks,surr_charge_rate_max()andsurr_charge_runoff_years()raiseKeyError,'point_id 7: surr_charge_table.csv has no schedule for its surr_charge_id', compiled as in modelx. And, before it is cast to int64, a number of2**53or more in size, which numpy would cast to the least int64 past int64: apoint_id, a model point’s issue age,model_point_table_sec.csv: age_at_entry must be below 2**53 in size; it is not at point_id [3], and aduration_mth, a policy issued2**63months on, and, on a point with a charge, a run-off of2**53years or more in size, whichVUL_US_Sprojects as a charge that never runs off. That one is not cast without a word:lapse_shock_month’s compiledintis exact below2**63and raisesOverflowErrorpast it, and the run-off is held to the bound every number read as an int is held to. A fractional issue age stays refused, as at stageE(The in-force interface, above), whereUL_US_SEC’s truncates. A key written as a float, a policy year9.0, is read by its value, asVUL_US_S’s lookups match it; a key written as text is not whole, and the table’s check refuses it.A negative age in
corridor_factors.csvormort_table.csv,corridor_factors.csv: age must be 0 or more; it is not on line [2], by the table’s check, which every reader of the table asks first: each is held from age 0, so that the age is the index. A refusalVUL_US_Slacks, which reads every attained age below a table’s first at that row, whatever the table’s ages. And a corridor factor below 0,corridor_factors.csv: corridor_factor must be a number, zero or more; it is not on line [2], as the corridor pin is held: one takes the death benefit past the option’s amount on an account value below 0, every check passing.A key beyond a table, by the one cell that reads it, naming the point, where
VUL_US_S’s lookup raisedKeyError: a policy year below 1,point_id 1: prem_persistency.csv has no factor for policy year 0, fromprem_persistency_py, and the same fromlapse_rate_base_pyandcoi_rate_guar_at, none of which a projection calls outside cover; a month before a scenario’s first, as on a path re-based to begin in a later point’s issue month,point_id 9: scenario_table.csv has no return for subaccount_id 1 at t 0, fromgross_return_mth, and a month past the horizon,point_id 1: scenario_table.csv is read to return_horizon_mth, 1585, so its scenario 2, in the order of the ids, has no return for subaccount_id 1 at t 1586, from the same cell, a call no frame makes, as on every month of a scenario that starts past it; the scenario is named by its number, since no projection cell reads the labelscenario_id(), even to refuse; a position outside the lineup,point_id 1: no subaccount at position 2 of the lineup of 2, fromalloc,fund_expense_ann,sa_pp_initandscenario_last_mth; and a point whose COI scale the table lacks,point_id 1: coi_rates.csv has no scale for the point's sex, rate_class and age_at_entry, fromcoi_rate_last_year, when its first rate is read.By
proj_len(), a point issued aboveomega_age, at or past the end of the projection, belowissue_age_minor aboveissue_age_max, and a lineup of more thansubaccount_maxsubaccounts, in that order:point_id 3: issue age 86 is above issue_age_max, 85.A timing or a kind a cell does not take,
ValueError("invalid timing")andValueError("invalid kind"), where the code is inside the cell’s cache: a code of the other family,av_pp_at(0, BEF_NB),pols_if_at(0, BEF_PREM),av_at(0, BEF_MAT), a timing the pricing path lacks,sa_pricing_pp_at(0, 0, BEF_WD), a kind a cell lacks,claim_pp(0, MATURITY),claims_from_av(0, WITHDRAWAL), and a code up to 8,claims_from_av(0, 8).
An argument outside a cache raises IndexError in the compiled model alone, as above:
net_cf(1586), which modelx answers with 0, the month being outside cover;
pols_if_at(0, 9) and claim_pp(0, 9), which modelx refuses as invalid timing and
invalid kind; alloc(9) and sa_pp_at(0, 9, BEF_PREM), which modelx refuses by the
subaccount’s guard; prem_persistency_py(124), which modelx reads at the table’s last
year, 0.80, and prem_persistency_py(-1), which modelx refuses, naming the year; and
corridor_factor_at(123) and corridor_factor_at(-1), which modelx reads at the table’s
nearest row, 1.00 and 2.50; and sa_pp(0, -1), a position below the lineup, which modelx
refuses by the subaccount’s guard. 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().
A Reference is a C variable of its value’s type: issue_age_min, issue_age_max,
subaccount_max, omega_age, charges_cease_age, loan_pref_year, the codes and idx
a long long, as Data.future_horizon_mth is, dyn_behavior_on a bint, and the rates
and amounts a double. Set past that type, it is converted when it is set, where modelx
keeps the value as given. A float set on an int Reference is truncated toward zero without
a word, omega_age = 121.7 reading 121 and issue_age_min = 0.5 reading 0, where modelx
computes with the float: omega_age = 121.0 makes omega_mth() a float there, and
result_cf() then fails. A text, a NaN, an infinity or an int beyond 64 bits is refused at
once, with TypeError, ValueError or OverflowError. An int set on a double
Reference reads as a float compiled, where modelx returns the int: lapse_shock_mult = 2
gives lapse_rate_sc_mult 2 in modelx and 2.0 compiled in the cliff month, where the cell
returns the Reference as it is. Each shipped Reference is a
value of its C type, so no shipped number differs. And a Reference set past its domain
computes as C computes, where modelx raises: an inflation_rate of 1e300 makes
inflation_factor(24) infinite compiled, where modelx’s power raises OverflowError.
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 VUL_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 every other
bound, each of which the compiled model computes as a comparison that keeps the value
unless the bound is smaller, or larger: a NaN mort_ae_factor, set as a Reference, makes
mort_rate(0) and net_cf(0) NaN in both. Data’s refusals of a value outside its range
keep any NaN from reaching them through the inputs. The annual lapse rate has no cap, in
VUL_US_S or here (Counts and timings, above): past 1, the monthly rate is complex in
modelx, and the three checks raise TypeError; compiled it is NaN, so are the counts after
it, and the three checks return False. With a spike of 40, point 3’s
lapse_rate_mth(168) is NaN compiled. No comparison of the two engines crosses that
domain.
Speed#
python tools/bench_sec_cy.py variable_ul 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,003 |
2.53 ms (15.21–17.02) |
3.15 ms (18.93–20.82) |
89 MB |
export |
603 |
34.9 ms (21.02–23.26) |
32.8 ms (19.75–22.60) |
89 MB |
modelx |
126 |
964 ms (121.5–126.6) |
1,021 ms (128.7–131.3) |
189 MB |
On net_cf the compiled model runs 13.8 times its export, and on result_cf, where
building the DataFrame takes much of its time, 10.4 times; it runs 381 and 324 times
modelx. A second run of the compiled model and the export straight after, under a 1-minute
load between 1.7 and 2.7, gave the compiled model 2.53 and 3.14 ms and the export 36.4
and 33.2 ms, 14.4 and 10.6 times. The modelx runs were made apart, one loop at a time, to
keep each under ten minutes. The compiled model takes about twice UL_US_SEC’s time a
point, 1.21 ms, for an ItemSpace four times the size, two subaccounts and the pricing path;
of its 2.53 ms, making and releasing the ItemSpace, which Python zeroes, takes about 0.4
ms. It runs more times its export than UL_US_SEC, 12.0, Term_US_SEC, 9.5, or
BasicTerm_SC on its own measure, 8.7. As it stood after running in force,
compiled the same way, the model ran no faster than its export (What compiling changed,
and why, above), and the compiled model runs about 110 times that build on the same
measure, 2.51 ms a point over the committed points against 279: the representation, not
the compiler, is the gain, and the export gained from it too, 35 ms a point against 279.
The release keeps a block flat: the compiled model’s peak grew by less than 0.1 MB over its
6,003 points, and without the collection after each release (--no-collect), 504 compiled
points peaked at 3,610 MB. Reading the ten files and building every Data vector and
array for those points took 0.12 s, and asking every point for its frame, the runner’s
first pass, 1.9 s, most of it making and releasing an ItemSpace a point.
Measured on 2026-11-13 on a machine shared with other work, under load: 4 CPUs (an Intel Xeon at 2.10 GHz), a 1-minute load average between 0.7 and 2.7 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. Each time is the fastest of three runs; under load the spread is wide, and the fastest run is the one to compare. The comparisons over the committed points, with the build as it stood after running in force, are the fastest of three rounds each, in one process an engine, and so is the cost of an ItemSpace, the fastest of five rounds of 1,000.
Tests#
The twin identity, in
tests/test_model_conventions.py: on point 3, issued at the valuation date, every cell ofVUL_US_S’s agrees at every argumentVUL_US_Sevaluates in its own sweep, but forpols_if_init,model_pointandresult_pols, whose meaning changed, andsubaccount_idsandcoi_rate_scale, a list and a Series, which this model replaced by the lineup’s size and a schedule number, and whose values the identity compares through the cells that read them in every month;VUL_US_S’sclaims(t, None)andme_charge_pp(t, None)are compared with the totalsclaims(t)andme_charge_pp(t), its kinds through theresult_cfcolumnsclaims_deathandclaims_lapse, and each of its subaccount ids at its position in the lineup. A cell this model lacked would fail it. The identity holds on any count, sinceVUL_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 in-force twins, in
tests/test_variable_ul_us_sec.py: points 1, 2 and 4 open withVUL_US_S’s own opening balances, the collateral at the debt and the face at issue, and each isVUL_US_S’s projection fromt = 0, in every report and every cell the two share, to 1e-9 relative with no absolute floor. So the goldenstests/test_variable_ul_us.pyasserts on point 1 — every row and column of the worked example’s month, from the opening balances to the end-of-month death benefit and net amount at risk, to the cent — hold here att = 0, the valuation month, with no number restated.The splice: each
VUL_US_Spoint restated in force at a month either side of its events continues the S projection from there, in its four reports, column by column, and in every other cell the two share, the subaccounts, the fixed option, the loan account, the debt and the face at every timing among them, and the pricing path atVUL_US_S’s own policy months, to 1e-9 relative with no absolute floor. It leaves out those the twin identity skips,VUL_US_S’s own opening values and frame, and the scenario’s id, since each row reads a copy of its own; the first default and shortfall months are asserted instead as the firstVUL_US_Sfinds at or after the row’s month, less that month. The months straddle the product’s events: the first anniversaries, the loan’s preferred rate, the lapse table’s last year, the surrender charge’s cliff and its one-month lapse spike, the month a shortfall begins, the attained age at which the splice’s charges cease, the corridor’s first binding and the last covered month, whoset = 1is the month the survivors are carried into. So are nine variants of S’s points, in a copy of S’s table that is never committed, each changing S’s columns only and each with input rows of its own, for branches S’s own points do not reach: withdrawals on either option, a single premium with no surrender charge, an Option B point funded past its face, a point on a second surrender-charge schedule with a loan, an issue age below the mortality and corridor tables’ first age, each first-month pin alone, so that neither’s flag stands in for the other’s, the COI pin set above the guaranteed rate that bounds it, and a withdrawal larger than the account value its first premium buys, whose cut takes the face past 0, where it is floored. Between them they carry both sexes and every class, and one COI scale stops short of its cover, so that its later years are read at its last.VUL_US_S’s in-force points 1, 2 and 4, and the variants in force 24 and 60 months, are splice cases too, at their own month 0. The References are set in both models to reach what the shipped values leave unreached: the behaviour module on, so that the pricing path, the funding ratio and the premium persistency scale are compared; the lapse spike at 3 times; an acquisition expense of $250; the mortality A/E at 0.56, which leaves survivors at the end of every frame; charges ceasing at attained age 100, inside every frame; and the declared rate at 2.5%, apart from the guaranteed 1.0%. The return scenario is a path that moves every month, and each restated or future row reads its own copy, re-based to its month.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 and every kind of valuation month, 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. One leg of the CI matrix sets it, so every CI run runs the full grid too. The tests that read the splice are one class, first in the module, whose models are closed before the committed model andVUL_US_Sare first read, so the module never holds both, and each splice row is released once it has been compared.Future new business: issued later than the valuation date, S point 3 and each new-business variant is the S projection moved on, cell by cell, the count at each of its timings among them but the count before new business in the issue month, which
VUL_US_S’s cell counts as in force; with zeros before issue in every report, no decrement rate evaluated there, and no scenario month read before issue.How it computes: each row the splice and the future business compare is first run on the books, its reports, its checks and then every monthly cell at every month from
t_entry()toproj_len() − 1, at every subaccount, timing and kind, as Phase 2’s sweep will run it, and is then scanned, before the comparison evaluates its cells atVUL_US_S’s keys: no cell has been called at a negative month, none evaluated fromt_entry()on has read a month before it, none evaluated at monththas read a month later thant + 1, and no cell without a month but the loops over the frame has read one keyed by a month. The sweep is what reaches the account value’s opening balance in a later point’s issue month, which no report reads, since the funding ratio returns there first. The pricing path, a projection made at issue and based there, is the one look-back allowed, and is held to the rest at its own policy months. On a fresh read of the committed model the policy clock is a closed form, every point’s reports run under a lowered recursion limit, which a recursion backward over the frame would exceed, and no projection cell has read a label accessor. And every chain is called cold, on a fresh read, at the shipped References, with the behaviour module on and at the longest cover: modelx’s stack trace counts no more than one cell a month back tot_entry(), or back to issue through the pricing path, and a fixed overhead, which a chain of two cells a month would exceed. With the module on, the twins of points 1 and 4 sweep in ascendingtunder a recursion limit of their policy month at the valuation date and that overhead, and the twin of point 3 and the row issued 25 months on under the module off’s.Counts, validation and regeneration: the roll-forward closes, the last month included,
BEF_MATis theBEF_DECRcount, andpols_if_atrefuses a timing it does not have;result_pols()isVUL_US_S’s, column for column, withpols_new_bizbeside it; multiplyingpolicy_countby 2.5, with every assumption that ships at zero switched on, multiplies every cash flow and moves no per-policy value; each malformed row is refused naming its point, by its own rule, and so is a projection of it; each assumption table with a malformed key, a policy year below 1 among them, or a value that is not a number, is refused naming its file, its column and its lines, and so is one with a lapse or mortality rate outside 0 to 1, or a class factor, a COI rate, a fund expense, a premium persistency factor or a surrender charge below 0, while the bounds of each range are read; adb_option,qual_testorpremium_typeno decode knows raisesVUL_US_S’s message; the horizon is a Reference, which at 0 refuses any future business, saying so, and refuses itself below 0, as the return scenario’s horizon does; a point at or past the end of the projection is refused byproj_len(); the edges of the interface are accepted, the keys of every keyed table written as floats among them; the committed table is whatVUL_US_Sgenerates, and each of its derived and future rows projects its S point’s reports from its month on; and the generator reads one opening column for each subaccount of the lineup, and every S point it issues later has both pins blank.The opening state and the rest: point 6 opens from its own collateral and its own subaccounts, and read as
VUL_US_Swould open it gives the numbers above; the face in force opens from its column; a row restated onWEas shipped reads the worked example’s month att = 0, and on a copy re-based to its month isVUL_US_S’s; expense inflation runs on the valuation clock, the fund returns and the declared rate are one number for every point in each month, each subaccount’s path repeating its own last month, the two ending apart, and a declared rate that moves leaves the pricing path where it was; with a current COI scale above the guaranteed one and a declared rate below the guaranteed 1.0%, point 4 isVUL_US_S’s in every cell, every current rate the guaranteed one and the fixed option and the pricing path credited at the floor; a check whose residual is not a number fails, the NaN sent through the M&E rate, a Reference; a lapse rate past 1 makes every check raise, in both models; each check decides asVUL_US_S’smath.isclosedoes where its sides fall below 1, a miss inside the absolute tolerance passing and one outside it failing; on a point whose loan comes to exceed its cash value the three checks hold whereVUL_US_S’s margin and net-view identities fail; acquisition falls on new business alone, per policy issued and not inflated; a StdTob point at an A/E of 1.0, whose product first passes 1 at attained age 113, 1.09495, isVUL_US_S’s in every cell, the capped months included, as new business and restated in force the month before the cap, the rate there is the float 1.0 in both models, every life in force dies in that month and nothing is in force after it; a NaN that reaches the cap stays NaN, sent through the class factor’s formula or the A/E, a Reference, and so does one that reaches a bound on the COI rate written second, the scale’s cap, the guaranteed rate over the current one and the pin’s; every monthly cell holds its value outside cover and reads no table there; the points of a block sum row by row; an extract without the generator’s three columns, relabelled, 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 VUL_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, a subaccount’s position for its id, and the split cells forclaims(t, kind)andme_charge_pp(t, i). Each point is named by its label, inpoint_id(), in a refusal and inrun_sec.py’s output.What compiling changed: the two totals are
VUL_US_S’s bit for bit, sign of a zero and type included,claims(t)itsclaims(t)andme_charge_pp(t)itsme_charge_pp(t), on its points’ twins in every month, and so are the kinds and each subaccount’s charge, and with both kinds, or both subaccounts’ charges, set to −0.0 in both models each total is 0.0, asVUL_US_S’ssumgives; a point issued belowissue_age_minor aboveissue_age_max, one to be issued aboveomega_ageand a lineup of more thansubaccount_maxsubaccounts are refused byproj_len(), naming the point, and the point issued at 86, one refused under anissue_age_minraised to 46 and the lineup of ten each project once the bound is moved past it; a read beyond a table and a position past the lineup are refused by the cell that reads it, naming the point, and a point without a COI scale where its first rate is read, which projects where no rate is read, with charges ceasing at its issue age; the scenarios are numbered by their ids whatever the file’s order; on a COI file of seven scales written out of their keys’ order, each scale’s lines reversed, each scale’s row of the array and its last year are the file’s, found by key, and S’s four points, given four of the scales, areVUL_US_S’s in every cell; a scenario month far past every frame adds nothing to the array of returns, which holds the months a frame reads, and a path run past them is held to them, a month past the horizon refused, naming the point and the scenario’s number, as is every month of a path that starts past it; the padding beyond each table’s extent is NaN; each size inspec_sec.pyis the one its comment derives from the model’s References, and the sample’s recursion limit the one its comment derives.Decoding, joins and values a bound reads: what
Datacannot decode or join, apoint_idthat is not whole or past2**53, an issue age or aduration_mthpast2**53, a class the class factors lack, a scenario the return scenario lacks or holds no row of a lineup subaccount for, a schedule the surrender charges lack or a run-off past2**53on a point with a charge, a negative age in an age table and a corridor factor below 0, is refused naming the points, the table or its lines, by theDatacell that first reads it and by a projection, the message naming every point at fault and no other; a point without a charge is not refused for its schedule, reads it where the table holds its ID, as at stageE, and raisesKeyErrorwhere it does not; each value a decode or a join names, written in another case or with a space beside it, is refused withVUL_US_S’s message or the join’s, asVUL_US_Scompares it exactly; 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 of No Python call kept, and the registry admits no other for this model; 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, 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_variable_ul_us_sec.py: the same comparison on the splice grid, the core by default and the full grid withUSLIB_SEC_FULL=1, variants included, four rows at a time; at the contract’s extremes, the longest frames from issue age 0, the oldest issue age and the bounds of its values, from a COI copy written out of its keys’ order, and on a lineup of nine subaccounts written out of their ids’ order; on labels that are not text and on keys written as floats, where everyDataarray is first held to the dtype it has on the keys as written, in modelx, in seconds; 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, and an argument past a cache raisesIndexError; on points without a charge, the two schedule accessors read the stageEvalues, and raiseKeyErroron an ID the table lacks, as modelx does, andData’s joins are modelx’s arrays; past a lapse rate of 1 its checks returnFalse; 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, one leg a product, a skip fails, whatever made it.
python -m pytest tests/test_variable_ul_us_sec.py -q
USLIB_SEC_FULL=1 python -m pytest tests/test_variable_ul_us_sec.py -q # the full grid
python -m pytest tests/test_model_conventions.py -q -k "[VUL_US_SEC]"
python -m pytest tests/test_compiled_conventions.py -q -k "[VUL_US_SEC]"
python -m pytest tests/test_variable_ul_us_sec.py -q -m cython # the compiled tests