In-Force Implementation Notes#
Status: Draft, 2026-11-01. Term_US_SEC is Term_US_S taught to project
from a valuation date. Besides policies issued at that date, it takes policies already in
force there 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
Term_US_Son another time axis, and it readsTerm_US_S’s assumption tables in place, every assumption unchanged: the contractual elements are sourced from a specimen policy [S6], and every behavioural and expense assumption is a std standardization. Replace them with company data before drawing any conclusion from the numbers.
Run it#
python products/term_life/run_sec.py # point 1: the anchor cell, issued at t = 0
python products/term_life/run_sec.py 4 # point 4: the anchor cell in force mid-ART
python products/term_life/run_sec.py --block # every model point, summed row by row
python products/term_life/run_sec.py 4 --cython # point 4 on the compiled model
--cython runs the compiled model and prints the same lines. The runner builds it beside
the model with the repository’s tools/build_sec_cy.py the first time, in about a minute,
and again whenever the model, sample_sec.py, spec_sec.py or the tool is newer than the
build, and says so on stderr. Nothing the build leaves there is committed, and
.gitignore covers it.
The first prints the twelve rows run.py prints for Term_US_S’s point 1, with the
policy counts behind them. Three lines to the same thing for point 4:
import modelx as mx
model = mx.read_model("products/term_life/Term_US_SEC")
model.Projection[3].result_cf() # point 4, the table's fourth row
Projection takes idx, the position of a point in the table, as basiclife/BasicTerm_SC
does: Projection[3] is point 4, and its point_id() says so. result_cf() has
Term_US_S’s columns — pols_if, premiums, claims, commissions, expenses,
premium_taxes, conv_credits and net_cf — with one row per month from the valuation
date, t = 0 … proj_len() − 1. result_pols() sets out the counts behind it on the same
rows: pols_if, pols_new_biz, then the month’s deaths, conversions and lapses in
processing order, and the expiries of the last covered month. result_cf_annual() sums
result_cf() into policy years, as in Term_US_S, and leaves out the months before
issue.
--block projects every point and releases its ItemSpace once its frame is read, so the
run holds the cells of one point at a time. Deleting it, del model.Projection[idx], is
not enough: an ItemSpace sits in reference cycles, which only Python’s cyclic collector
frees, so the runner collects after each release. It freezes everything alive
(gc.freeze()) once the model and its table are read, and again once it has asked every
point for its frame, so that each collection scans only what the block has made since.
It keeps the block’s sum as it goes, compensated as pandas sums a groupby, so that the
block is, bit for bit, the frames concatenated and summed by t, as below (The compiled
model has the measurements).
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 cover.duration_mth(t), the policy clock, counts the months the policy has been in force at timet:duration_mth(t) = duration_mth_init() + t, withduration_mth_init()read from the model point. It is the technical notes’ month index, and the contract runs on it:duration(t) = duration_mth(t) // 12,policy_year(t) = duration(t) + 1andage(t) = age_at_entry() + duration(t), as inTerm_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.
Point 4 is the anchor cell in force 126 months. At t = 0 it is in policy year 11, at
attained age 45, six months into its first ART year. Its next premium, policy year 12’s
$830, falls due at t = 6, its eleventh anniversary, and its frame has 594 rows,
t = 0 … 593. Point 6 is the anchor cell to be issued three months after the valuation
date: duration_mth(0) = −3, it is on the books from t_entry() = 3, rows 0 to 2 are
zeros, and its frame has 723 rows.
Read on the policy clock |
Read on the valuation clock |
|---|---|
the premium schedule and the months premiums fall due, the jump ratio, the shock lapse month, the lapse and commission scales, base mortality at the attained age, post-level-term mortality, the conversion window and credit, expiry at attained age 95 |
expense inflation, |
Expense inflation alone runs on t, so the maintenance charge is in valuation-date dollars,
for every point alike. Acquisition is a flat $300 per policy issued, charged in the issue
month and not inflated, as in basiclife/BasicTerm_SE.
Because row t is the same month for every point, the frames of a block line up and sum
row by row, which is what run_sec.py --block prints:
import pandas as pd
frames = [model.Projection[i].result_cf()
for i in range(len(model.Data.model_point_table()))]
block = pd.concat(frames).groupby(level="t").sum()
run_sec.py --block keeps one frame at a time, and adds each to a running sum with the
compensation pandas’ groupby sum carries, in the same order, so its block is this one’s
to the last bit, on the committed points and on 155 more (a naive running sum differs
from it in 851 of the committed points’ 5,784 values, by up to 3e-16 relative).
On a point issued at t = 0 the two clocks coincide, and the model computes what
Term_US_S computes, with one difference by design: acquisition is charged per policy
issued, where Term_US_S charges it once per model point, whatever the count. On
Term_US_S’s own points, which count one policy each, every cash flow and every count
agrees, and so does every other cell the two models share but two whose meaning changed:
pols_if_init(), now the count already in force at the valuation date, 0 for new
business, and model_point(), a row of another table.
The in-force interface#
The model point table is model_point_table_sec.csv. It carries Term_US_S’s columns, two
of them restated as the in-force interface under basiclife/BasicTerm_SE’s names:
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, 0 for a policy issued at the valuation date, |
Term’s only state variable is the in-force count, so these two columns are all it takes to
open a policy in force. Everything else the projection uses is fixed at issue, in
Term_US_S’s columns, or follows from the policy clock. The premium is read from the
guaranteed schedule by policy year, not solved, so no premium fixed at issue has to be
carried, and the jump ratio, the M(1) rule, the conversion window and the expiry month all
follow from columns fixed at issue.
|
|
Why |
|---|---|---|
|
|
The count, under BasicTerm_SE’s name. |
|
|
The policy clock, in months; the S column is dropped |
The columns carried over are read as Term_US_S reads them. For a policy in force, the
facts they record are still those at issue, the premium mode excepted:
Column |
Unit |
Measured at |
|---|---|---|
|
labels |
— |
|
years, age nearest birthday |
issue, not the valuation date: |
|
codes, as in |
issue |
|
dollars, level for the life of the policy |
issue |
|
|
the mode billed over the frame; its instalments fall on the policy clock |
|
a multiplier, blank for the notes’ rule |
an assumption, not a fact about the policy |
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:
both in-force columns are present;
no
point_idappears twice;policy_countis a number, zero or more, so not blank, text or infinite;duration_mthis a whole number of months;duration_mthis −120 or more. Future new business is written over a horizon,Data.future_horizon_mth, 120 months as shipped, so that no frame runs longer than cover from issue plus ten years. Set to 0, the Reference refuses future new business altogether.
A point whose cover had ended by the valuation date,
duration_mth ≥ 12 × (95 − age_at_entry), reads, but proj_len() refuses it, naming the
point: the end of cover is the product’s rule, not the table’s. So does a point the
contract does not issue, whose plan’s level period is below ten years,
Projection.policy_term_min, the shortest plan’s, as T5’s is, or whose issue age is
below 18, Projection.issue_age_min, the youngest every plan issues at
(product-spec.md). Data reads both as Term_US_S reads them, and
Term_US_S projects them as far as its tables go, but the compiled model’s caches are
sized from the contract (The compiled model, below). A loop over the block meets such a
row only when it reaches it, after projecting the points before it, so
run_sec.py --block asks every point for its frame before it projects any, and stops
before it prints anything.
The model points#
No row of model_point_table_sec.csv is typed by hand. Every one is generated from
Term_US_S and its table by tests/sec_support.py, from the Term_US_SEC entry in its
SEC_SPECS, and the tests regenerate the table and compare, so an edit to a Term_US_S
row reaches it or fails the suite. In the source repository,
python tools/gen_sec_points.py Term_US_SEC writes it.
Point |
Kind |
From |
At the valuation date |
|---|---|---|---|
1, 2 |
twin |
S points 1 and 2 |
issued at |
3 |
derived |
S point 2 at S month 12 |
in force at its first anniversary, the shock lapse 107 months ahead |
4 |
derived |
S point 1 at S month 126 |
midway through its first ART year |
5 |
derived |
S point 1 at S month 719 |
in its last month of cover: a one-row frame |
6 |
future |
S point 1, 3 months on |
to be issued at |
A derived row’s policy_count is the count Term_US_S carries into that month, its
pols_if(d), so the row continues the S projection from there: point 4 opens with 0.108385
policies. Its policy_id is the S row’s with the month appended, TL-000001-M126, and a
future row’s carries the months to issue, TL-000001-F3. Row t of a generated point is
month t + source_mth of its S point. All six are on the anchor configuration, T10 / M /
StdNT / band 1 / annual mode, because the specimen gives a guaranteed premium scale for
that cell alone [S6]; a point on any other plan, sex, class or band needs
premium_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 two
timings, basiclife/BasicTerm_SE’s, each an int Reference named as BasicTerm_SE’s
string, 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.
Any other timing raises. The survivors carried into month t are those of month t − 1’s
BEF_DECR count, which BEF_NB forms itself, as its own value at t − 1 plus that
month’s new business, exactly the sum BEF_DECR returns. So the chain of calls from
month t back to t_entry() is one cell a month, as deep as Term_US_S’s pols_if
chain. On a model just read, a cold net_cf in the last month of a 720-month frame runs
728 cells deep, against 726 in Term_US_S, the two more being the two timings pols_if
passes through, and at the longest frame the contract allows, issue age 18 and issued 120
months on, it runs 932 deep.
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 Term_US_S’s pols_if. BasicTerm_SE’s third timing,
"BEF_MAT", is not adopted, nor is its pols_if, which is the count before maturity:
here the policies expire at the end of the last covered month, as pols_maturity, where
Term_US_S’s worked example puts expiry. The roll-forward closes as
pols_if(t) − pols_if_at(t + 1, BEF_NB)
= pols_death(t) + pols_lapse(t) + pols_conv(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) < expiry_mth(), and outside it, before
issue and from expiry on, every count is zero, and so every cash flow. 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_due, premium_pp_ann, mort_rate_base, conv_elig and the
commission scale comm_rate are zero or false outside cover.
Departures from Term_US_S#
Each formula that tested t against a contractual event now tests the policy clock, and
each read of a contractual schedule at a month is a read at a policy year. Where
Term_US_S’s test would have stayed correct on the valuation clock, it moved anyway, so
that cover has one definition. Ten cells are new for running in force, and two more for
compiling, point_id and premium_schedule (The compiled model, below). None of
Term_US_S’s 52 is removed, which the twin identity asserts: a cell of Term_US_S’s that
this model lacked would fail it. One departure comes from neither the clock nor running in
force: the notes’ M(1) rule and the post-level-term grading write their bounds second, as
mort_rate writes its cap in both models, so that a NaN stays NaN; Term_US_S writes
them first (below).
Cells |
|
|
Why |
|---|---|---|---|
|
|
|
The policy clock, opened from the model point |
|
|
|
The frame starts at the valuation date. |
|
a recursion from |
|
Policies in force at the valuation date open the count; new business joins it in its issue month |
|
|
|
On the valuation clock, month |
|
the shock at |
at |
The shock is a policy month |
|
the final eligible year found by |
|
A question about the next policy year, asked by policy year rather than twelve months ahead |
|
acquisition, $300 once at |
|
A point already in force bears none, and one issued later bears it in its issue month, per policy issued and not inflated, as in |
|
|
the same formula, |
Unit costs in valuation-date dollars |
|
expiry at |
at |
One definition of cover, on the policy clock; |
|
unguarded: no |
zero or false outside cover, before any table or rate is read |
A policy year or an attained age the policy does not have is never looked up, and no scale reads a month before issue as a policy year |
|
|
|
A NaN stays NaN, as at the cap; the same float wherever the argument is a number (below) |
|
whole policy years |
the policy years in the frame, the months before issue left out |
An in-force point’s first row holds the rest of its current policy year, and its |
|
— |
new |
The counts behind |
Of the cash flows, the change of clock moves the maintenance expense alone, and net_cf
with it. A point in force carries that expense in valuation-date dollars, so point 4’s
expenses(t) is Term_US_S’s expenses(126 + t) divided by 1.02^(126/12), about 1.231.
Its pols_if, premiums, claims, commissions, premium_taxes and conv_credits are
Term_US_S’s from month 126 on. Point 6 is Term_US_S’s point 1 three months on in those
six columns too; its maintenance expense is 1.02^(3/12) above S’s, and its acquisition is
$300 exactly.
mort_rate caps the annual rate at 1, written min(q, 1.0), the product first and the
bound second, as Term_US_S writes it (below). Past 1 the monthly rate,
1 − (1 − q)^(1/12), has no real value. At 1 it is 1, so every policy in force at the
start of the first month the cap binds dies in that month, and none is in force after
it. On the shipped mortality and class tables the product passes 1 only after the level
period. At the issue ages product-spec.md admits, it first does so,
at the lowest M(1), in the tobacco class on the twenty-year plan issued at 65, its oldest
tobacco issue age: at attained age 94, the tenth PLT year, once M(1) passes 5.9152, which
the notes’ rule gives at a jump ratio past 9.9367. There a non-tobacco class needs an M(1)
above 8, the most the rule gives, so an override. The model does not refuse an older
issue age. Where the first PLT year falls at attained age 94, as on the ten-year plan
issued at 84, the product passes 1 there once M(1) passes 4.5652 in the tobacco class and
7.9891 in the standard non-tobacco class, the least M(1) that does so on any point the
model projects. At M(1) = 8 the anchor cell issued at 70 in the tobacco class passes 1 at
attained age 90, in policy year 21, as a test shows (Tests, below). No committed point
comes near it, nor any point of the splice grid.
The order of the cap’s arguments matters. Python’s min and the compiled cell alike keep
the first argument unless a later one compares smaller, and no comparison with NaN holds,
so min(1.0, q) is 1.0 where q is NaN: a blank class factor would read as certain death
in the first month, every count and cash flow finite. min(q, 1.0) is NaN there, in both
engines, and wherever q is a number it is the float min(1.0, q) is, 1.0 included, so
the order changes no number the model computes. The notes’ M(1) rule,
min(8.0, 1 + 0.55 × (J − 1)), and the floor of the post-level-term grading,
max(2.0, …), are written with their bounds second for the same reason, where
Term_US_S writes them with their bounds first, and are the same floats wherever their
arguments are numbers. An infinity is a number, though, and the cap reads an infinite
class factor as certain death in either order, so Data also refuses, by name, every
value a cap, a min or a max reads that is blank, text or infinite (What it refuses,
below): no NaN, and no infinity, reaches one.
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 55 points of the
splice grid, which take the branches they do not, on the contract’s two longest frames,
and on points where the cap on mortality binds. The compile tests hold it so on x86-64,
and to 1e-12 relative elsewhere, where no run has shown it yet.
Building it#
In the source repository:
python tools/build_sec_cy.py term_life # in place, beside the model
python tools/build_sec_cy.py term_life --out /tmp/term # elsewhere, with the CSVs
The tool exports the model to Term_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 Term_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/term_life") # the directory holding the build
from Term_US_SEC_nomx_cy import mx_model as model
model.Projection[3].result_cf() # point 4, 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 = 3 after Projection.result_cf() returns
point 1’s frame under point 4’s point_id(), and Data.future_horizon_mth lowered after
the table was read refuses nothing. Set every Reference on a model just imported, before
anything is computed, where modelx would recompute; a test holds the compiled model to
this.
A build takes about a minute with gcc, 53 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 53 of its 62 cells as C numbers and ran only 1.4 times its own export, 21.2 ms a
point on net_cf against 29.0, because the bodies of the typed cells still called pandas:
a model_point() lookup for each attribute, and a .loc on a table for each policy
year’s premium and each month’s mortality. 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[3]is point 4, 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.Text, decoded once. A C cell holds no text, so
Datadecodes each text column into the number it selects, for every point at once: the plan into the level period,policy_term; the premium mode into the months between instalments,prem_cycle, by whichmodal_factorselects the mode’s factor; the class into its mortality factor,class_factor; the face amount into itsband; and a blank M(1) override into a 0/1 flag beside a value of 0.0, so that no formula tests for NaN. Each decodes asTerm_US_Sreads the column, and what it cannot decode it refuses (below).Tables indexed by integers. The premium schedules, keyed by plan, sex, class and band, are numbered, each point carrying the number of its own,
premium_schedule, and held by schedule and policy year inpremium_rates_array. Base mortality ismort_table_array, padded from age 0 so that the index is the attained age. The shock-lapse buckets are three vectors and a count, whichshock_lapse_rateloops over. The padding holds NaN, and nothing reads it: the one cell that reads each table checks its key against the table’s extent first.Codes. A timing or a phase, which
Term_US_Sspells as text, is an int Reference named as the text:BEF_NB = 0andBEF_DECR = 1, andPRE_ISSUE = 0,LEVEL = 1,PLT = 2andEXPIRED = 3. A call reads as before, less the quotes:pols_if_at(t, BEF_DECR). A string argument or a string value would give the cell a dictionary for a cache, where a code indexes a C array, so codes are numbered from 0 without a gap, the timings in the order of their instants within the month.Reporting cells stay Python.
model_point(), the label accessorssex(),rate_class(),plan()andpremium_mode(), and the three reports return a table row, text and DataFrames, for a reader, forrun_sec.pyand for the comparison withTerm_US_S. No other cell calls them, so they cost the projection nothing. A label accessor returns its column as read, andDataaccepts a label that is blank, which pandas reads as NaN, or a number, which the point’s first projection refuses. So each of the four compiles to a Python object, as the sample traces it (below), and returns what modelx returns (precised at M26).
The Data docstring lists its 23 vectors, arrays, extents and counts, each with the column
or file it comes from. The six readers stay Python, returning DataFrames and a path, and no
Projection cell but model_point() reads them. Every other cell of Projection, 56 of
its 64, 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,046 by |
the 33 cells of |
a C array of 1,046 by 2 |
|
a C array of 79 by policy year |
|
a C array of 69 by PLT duration |
|
one |
the 19 other cells without a parameter: the point’s numbers, the ends of its frame, its factors, the jump ratio and the shock lapse rate |
a Python object |
the eight reporting cells |
The declarations the build generates, _mx_classes.pxd in the compiled package, are the
record of it, and none of Projection’s caches there is a dictionary.
The sample and the spec#
mx2cy types each cell from the values the sample run passes it and gets back, and a cell
the run never calls compiles as a Python object. So sample_sec.py runs the three reports
on every committed point, and then the eight cells no report reaches: model_point() and
the four label accessors, which only a reader asks for; band(), which no cell reads,
since Data bands the face itself; point_id(), which only a refusal names; and
phase(t), before issue, in cover and from the month cover ends, with the count
pols_if_at carries into that month. It runs the committed points alone: the export it
runs reads the CSVs of the directory the build is made in, which in place is the product
directory, so points of its own would have to be written there. The committed points
leave branches untaken: the semi-annual, quarterly and monthly modes, a twenty-year level
period, the conversion window’s age limit, cover that ends with the level period, the cap
on mortality. That still types every cell, because every branch of a cell returns the one
type its others return, a count a float in every branch, and on points that take those
branches the compiled model computes modelx’s numbers (above). The label accessors are
typed from more than the committed points: the sample also calls the four on a copy of the
first point with every label blank, written to a temporary directory and read by a second
instance of the export, so that each compiles to a Python object (M26). The sample also
raises the recursion limit, which modelx raises and its export does not (What a compiled
run needs, below).
spec_sec.py sizes each C-array cache, by the names of the cells’ parameters, and a
compiled cache raises IndexError for an argument outside it. So each size covers the
largest argument a cell is called with on a point the contract allows, in its frame and
in the month after it, t = proj_len(), which the roll-forward reads and the compile
tests’ full sweep evaluates every monthly cell at; plus one because the index starts at
0, and one of headroom where that leaves room:
Parameters |
Size |
The largest argument |
|---|---|---|
|
1,046 |
1,044. The longest frame is a policy issued at the youngest issue age, 18, covered to 95 for 77 policy years, and issued 120 months after the valuation date, the furthest ahead |
|
1,046 by 2 |
|
|
79 |
77, the last policy year; no cell reads one outside cover. The year after month |
|
69 |
68: PLT year 68, which |
proj_len() refuses a point issued below 18, issue_age_min, and one whose level period
is below ten years, policy_term_min, in modelx as compiled, and cover ends at
expiry_age, 95, so no report on a point the model projects runs past these caches.
Those three References and Data.future_horizon_mth are the contract the sizes are
derived from. Lower either minimum, or raise expiry_age or the horizon past 120 months,
and a report runs past the caches in the compiled model alone: a frame longer than 1,044
months, a policy year past 78 or a PLT year past 68 raises IndexError, naming nothing,
where modelx projects. Each needs the sizes derived again, as spec_sec.py derives them,
and a rebuild; a longer horizon, t raised to 12 × 77 + the horizon + 2.
Two compiler directives#
tools/build_sec_cy.py puts a line at the top of the module mx2cy translates, before it
compiles it: # cython: infer_types=True, cpow=True. Without infer_types, an integer
local such as n = policy_term() in lapse_rate stays a Python object, though the cell is
typed double, and so does the loop counter in shock_lapse_rate. Without cpow,
x ** y on two doubles is a complex power, which a compiler with C99’s complex numbers,
gcc among them, computes with cpow rather than pow. So 1 - (1 - q) ** (1 / 12), the
monthly rate of every decrement here, can differ from Python’s in its last bits: on the
splice grid’s 55 points, 240 compiled values differed from modelx’s without it, by up to
2.4e-15 relative, the first point 9’s mort_rate_mth(708), at q near 0.44. With both
directives, every value agrees bit for bit, and the compile tests hold each directive, by
the module’s first line and, on x86-64, by C4 itself. What they cost is C’s semantics,
which no formula here meets: a local assigned only from int literals is a C long, 32
bits on Windows, and an int raised to a negative int truncates. The tool’s docstring has
the detail.
On Linux and macOS the tool also compiles with -ffp-contract=off, after any flags the
interpreter or CFLAGS give. gcc fuses a * b + c into one fused multiply-add wherever
the target has the instruction, and clang within an expression: one rounding where Python
rounds twice. The default x86-64 target has none, but -march=native gives one on a
processor with FMA: built so here without the flag, the compiled model fused three
operations, and plt_mort_factor(10) came out 2.15 where modelx computes
2.1500000000000004. With it, the same build is modelx’s bit for bit. MSVC, on Windows,
emits no fused multiply-add for x64 without /arch:AVX2, which setuptools does not pass.
What a compiled run needs#
Memory, and the release. A compiled Projection ItemSpace is a C struct of 429,896
bytes, the type’s basic size, which holds every cell’s cache, and deleting it,
del model.Projection[idx], frees nothing by itself: an ItemSpace sits in reference
cycles, the list of roots it keeps among them, 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). On 600 compiled points, the committed table a
hundred times over, the runner as it is took 1.35 to 1.40 s, and after every release no
ItemSpace but the base was alive, counted among the objects the collector tracks, and
not frozen (gc.get_objects()); the process peaked at 71 MB. With the collection taken
out of the release, the frame pass left all 600 of its ItemSpaces alive, which the
runner’s second freeze then kept for good, and the projections up to 71 at a time; the
process peaked at 349 MB. And with the first freeze moved after the frame pass, each of
the frame pass’s collections scanned everything alive, pandas, numpy and the model, and
the run took 10.4 to 11.7 s, the same 71 MB. Two runs each, under load.
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: the deepest call the contract allows runs under a limit of 60. What it needs
is stack. That call, a cold net_cf in the last month of the longest frame, runs the count
chain back to t_entry(), 932 cells deep in modelx, one cell a month and 9 more, which a
test holds, and compiled with gcc it needs between 232 and 236 KiB. 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 export recurses in
Python instead: the same call needs a recursion limit of 1,881 there, and the three
reports, which run in ascending t, need 48, so sample_sec.py sets 10,000.
What it refuses#
The compiled model refuses what modelx refuses, with the same message. modelx raises its
FormulaError, which quotes the error; compiled, the ValueError itself propagates.
What
Datacannot decode or hold, when the vector is first read, naming every point at fault, or the schedule or the table: apoint_idthat is not a whole number, a plan whose yearsintcannot read, a premium mode other thanA,SA,QorM, a classclass_factor_table.csvlacks; a premium schedule whose policy years are not whole, leave a gap, repeat or start below 1; a mortality table with an age that is not whole, a gap, a repeated or negative age; a shock-lapse table with no bucket.Term_US_Smet each only when a projection reached it. A key written as a float, a policy year1.0, is read by its value, asTerm_US_S’s.locmatches it, and so are the keys each table’s extents are taken from: a key written as text is refused by the extents as by the array, so a projection, which reads an extent first, meets the table’s own refusal.A value a cap, a
minor amaxreads that is not a finite number, blank, text or infinite, when its array is first read, naming the file, the column and every line or point at fault, over the whole table, so that a value no point reads is refused as one that it reads is: a factor ofclass_factor_table.csv, by class,class_factor_table.csv: factor must be a finite number; it is not at rate_class ['PNT']; a rate ofmort_table.csv, by age; a premium ofpremium_rates.csv, which the jump ratio and so the M(1) rule read, by every schedule at fault and every policy year in it; anage_at_entry, whose attained age indexes the mortality table, and aplt_mort_factor_override, bypoint_id. A blank override is the notes’ rule, and is read so.Term_US_Smet each only when a projection reached it: it raised on text and on a blank or infinite age, read an infinite factor, base rate or M(1) override as certain death at its cap and a negative infinite M(1) override as its grading’s floor, 2.0, without a word, and projected NaN or an infinity from the rest.A key beyond a table, by the one cell that reads it, where
Term_US_S’s.locraisedKeyError:point_id 2: mort_table.csv has no rate at attained age 30, frommort_rate_base, andpoint_id 2: premium_rates.csv has no premium for policy year 61, frompremium_pp_ann_py.By
proj_len(), a point past its cover,point_id 5: duration_mth 720 is at or past the end of cover, policy month 720, and a point the contract does not issue:point_id 2: the plan's level period, 5 years, is below policy_term_min, 10, andpoint_id 6: issue age 17 is below issue_age_min, 18.
An argument outside a cache raises IndexError in the compiled model alone, as above:
net_cf(1046), which modelx answers with 0, the month being outside cover. An idx past
the last row is refused in both, with an IndexError at the first read of a vector, and
Projection[-1] reads every vector at its last element in both, so it is the table’s
last point, under that point’s own point_id().
An annual mortality above 1 is not refused but capped, in both: mort_rate caps the
product of the base rate, the class factor and M(d) at 1, as Term_US_S does
(Departures from Term_US_S, above). Uncapped, the monthly rate, 1 − (1 − q)^(1/12),
would be complex in modelx and NaN compiled, silently. Capped, both compute 1, and a
compile test holds the two equal on points where the cap binds, new business and in
force. A NaN product would stay NaN through the cap, in both, as it would through the
M(1) rule’s min and the grading’s max, each of which the compiled model computes as a
comparison that keeps the value unless the bound is smaller, or larger; Data’s refusals
of a value that is not a finite number keep any NaN from reaching them.
Speed#
python tools/bench_sec_cy.py term_life builds the model into a temporary directory 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,000 |
0.50 ms (2.98–3.20) |
1.26 ms (7.57–8.02) |
84 MB |
export |
600 |
4.7 ms (2.84–3.32) |
5.9 ms (3.53–4.04) |
84 MB |
modelx |
120 |
196 ms (23.5–26.0) |
223 ms (26.8–27.7) |
116 MB |
On net_cf the compiled model runs 9.5 times its export, and on result_cf, where
building the DataFrame takes most of its time, 4.7 times; it runs 394 and 177 times
modelx. A run earlier the same day, under a lighter load, between 0.9 and 1.4, gave the
compiled model 0.47 and 1.27 ms and the export 5.0 and 6.2 ms, 10.7 and 4.9 times.
BasicTerm_SC, timed on 2026-11-01 on its own measure, pv_net_cf() over 1,000 of its
points, ran 8.7 times its export. The release keeps a block flat: the compiled model’s
peak grew by less than 0.1 MB over its 6,000 points. Reading the five files and building
every Data vector and array for those points took 0.03 s, and asking every point for
its frame, the runner’s first pass, 0.08 s.
Measured on 2026-11-02 on a machine shared with other work, under load: 4 CPUs (an Intel Xeon at 2.10 GHz), a 1-minute load average between 1.6 and 3.0 as the runs started; Linux, Python 3.13.18 and gcc 13.3.0, with modelx 0.33.0, modelx-cython 0.1.0, Cython 3.3.0, numpy 2.5.3 and pandas 3.0.5. Under load the spread is wide, and the fastest run is the one to compare.
Tests#
The twin identity, in
tests/test_model_conventions.py: on points 1 and 2, every cell ofTerm_US_S’s agrees at every argumentTerm_US_Sevaluates in its own sweep, but forpols_if_initandmodel_point, and a cell this model lacked would fail it. SoTerm_US_S’s worked example, whichtests/test_term_life_us.pyasserts, money to the cent and the in-force to six decimals, holds here with no number restated. It holds because each S point counts one policy: on any other count, acquisition per policy issued would part fromTerm_US_S’s once per point, and the module asserts the count. The same suite holds the model to the conventions every_SECmodel meets: every frame starts att = 0,pols_ifis theBEF_DECRcount, new business enters once at itspolicy_count, nothing happens before issue, and the in-force columns are present.The splice, in
tests/test_term_life_us_sec.py: eachTerm_US_Spoint restated in force at months 1, 12, 119 (the shock), 120 (the first ART premium), 121 and 719 (the last) continues the S projection, in every cell the two share butproj_lenandresult_cf_annual, to 1e-9,Term_US_S’s text for a phase compared as the code of the same name. So do variants of S’s points, in a copy of S’s table that is never committed, each reaching what S’s own points cannot:the anchor cell issued at 65 and paying quarterly, restated at months 1, 47, 59 and 60: its conversion window, policy years 1 to 5, is closed by attained age 70 rather than by the level period, and its premium falls due every third month;
point 2 issued at 45 on a twenty-year plan and paying semi-annually, restated at months 238 to 241, either side of the shock and the first ART premium: the level period’s length, read by the shock month, the jump ratio and M(1). A copy of
premium_rates.csvcarries its T20 scale, T10’s moved on ten years;the anchor cell issued at 85 and paying monthly, restated at months 1, 118 and 119: cover ends with the level period, so the shock falls in the last covered month;
ten more, restated in their second month, each carrying a value the model decodes or joins its tables on that no shipped point carries: the female sex, each of the other three classes, and each side of every face-amount boundary, $249,999.99 and $250,000 and so on to $1,000,000. Each key has a premium schedule of its own in the copies, the anchor cell’s at a scale of its own, so that a point joined to the wrong schedule, or banded wrongly, reads another premium.
The comparison runs over S’s own frame.
Term_US_S’s jump ratio reads policy year 11 past the age-85 point’s frame, where this model’s cells answer that the month is outside cover, and such a read has no counterpart to compare. Inflation, the one input on the valuation clock, is set to 0 in both models, and conversion is switched on in both, at the notes’ std 1% a year and 2% in the final eligible year, because at the shipped zeros the conversion window is invisible to any comparison.Future new business: issued 1 and 12 months after the valuation date, each S point is the S projection moved on, with zeros before issue and no decrement rate evaluated there, and so is each of the first three variants issued a month on.
How it computes: on every row of the splice’s grid, after every report, no cell has been called at a negative month, and none evaluated at month
thas read a month later thant + 1. On a fresh read of the committed model,duration_mth(500)evaluatesduration_mthonce, because the policy clock is a closed form, and every point’s three reports run under modelx’s recursion limit lowered to 40, which a recursion backward over the frame, throught + 1, would exceed. And on a fresh read a coldnet_cfin the last month runs one cell a month back to issue, and at most 16 more, by modelx’s stack trace, on the committed twin and at the contract’s two longest frames, 728 and 932 cells, where a count chain of two cells a month, which gives the same numbers, would run twice as deep. No number shows any of the five, and the compiled model needs each (The compiled model, above).Counts, validation and regeneration: the roll-forward closes, and
pols_if_atrefuses a timing it does not have; doublingpolicy_countdoubles every cash flow and moves no per-policy value; each malformed row is refused naming its point, a duration of −121 among them; the horizon is a Reference, which at 2 refuses the point issued 3 months on and at 0 refuses any future business, saying so; a point past its cover, and one the contract does not issue, on a level period below ten years or issued below 18, is refused byproj_len(), a five-year plan with a schedule of its own projecting only oncepolicy_term_minis lowered, andrun_sec.py --blockrefuses such a point before printing anything; a zero count, durations written as floats and a policy issued 120 months on are accepted; and the committed table is whatTerm_US_Sgenerates.The clocks and the rest: point 4 pays policy year 12’s premium at
t = 6; expense inflation runs on the valuation clock at the shipped 2%, which only this test sees, since the splice sets the rate to 0; acquisition falls on new business alone; every guarded cell holds its value outside cover and reads no rate there; the points of a block sum row by row; an extract without the generator’s three columns projects the same numbers, and, labelled 106 down to 101 rather than by position, names each point by its label, inpoint_id(), in a refusal and inrun_sec.py’s output;run_sec.pyprints the model’s numbers, for point 4 and for the block; 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 cap: on the anchor cell issued at 70 in the tobacco class, with M(1) at 8.0 and a tobacco schedule, in copies of the tables, under the splice’s References, inflation at 0 and conversion on, the product of the base rate, the class factor and M(d) passes 1 from policy year 21, at attained age 90, to the end of cover. In both models
mort_rateandmort_rate_mthare the float 1.0 there; every policy in force at the start of that year’s first month dies in it, and none is in force after it; the reports hold finite floats; and every cell the two models share agrees, to 1e-9 relative with no absolute floor, at every argumentTerm_US_Sevaluates, the capped months and the reports included. So does the point restated in force the month before the cap, opened withTerm_US_S’s count and compared cell by cell as a splice row is. It loses every policy in the capped month, and the point in force five months into that year loses every policy in the first month it projects. And a NaN sent to the cap, to the M(1) rule’sminor to the grading’smax, through the formula of the cell that feeds it replaced by one returning NaN in a model read for the test, stays NaN at the bound and at each call after it that the test lists, the mortality and a count among them:mort_rateis NaN, not 1.0, where the class factor is NaN. (shock_lapse_ratereads the jump ratio through a comparison, which takes the last bucket for a NaN;Data’s refusals keep a NaN from it.)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 Term_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, and the codes for the text of a timing or a phase.Decoding: every value a decoded column can hold, each sex, class, plan and mode and each side of every face boundary, decodes as
Term_US_S’s own cells read it; a table whose keys are written as floats, policy years1.0and ages35.0, projects exactly the committed numbers, as it does inTerm_US_S; what cannot be decoded, a table with a gap, a blank policy year, a policy year or an age that is not whole, or a key written as text, and a key beyond a table, are each refused naming the point, the schedule or the table, a projection meeting the same refusal; and the padding beyond each table’s extent is NaN.Values a bound reads: a class factor, a base rate, a premium and an issue age written blank, as text or as an infinity, and an M(1) override written as text or as either infinity, are each refused naming the file, the column and every line or point at fault, by the
Datacell that first reads them and by a projection: one at a time, a factor of a class and a premium of a schedule no point carries among them, and two in one column, at two classes, two ages, two policy years, two schedules or two points; no other rule refuses the copy, every otherDatacell reading or meeting the same refusal.No pandas in
Projection(C5), intests/test_compiled_conventions.py, which holds what every_SECmodel meets once it compiles. Read from the formulas, with no compiler: no cell but the reporting ones refers to pandas, numpy or another module, reads a table with.locor the like, calls a reporting cell, holds text but in its docstring and its refusals, or holds a generator, a comprehension or a nested function; none calls anything but a cell, aDatavector and the builtins Cython turns into C,int,float,bool,abs,min,maxandrange, or builds a list, a dict, a set or a tuple; everyDatavector a formula reads is an int64 or float64 array, read by element; no cell is uncached, which modelx-cython would leave untyped; no cell shares its name with what a call with keywords calls anywhere in the model; 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_term_life_us_sec.py: the same comparison on the splice grid, variants included, on the contract’s two longest frames and on the points where the cap binds; the compiled model refuses what modelx refuses, with modelx’s message, on the extract labelled otherwise than by position too, and every value a bound reads that is not a finite number; the deepest call the contract allows runs cold on a 1 MiB stack and on the main thread; 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, a skip fails, whatever made it.
python -m pytest tests/test_term_life_us_sec.py -q
python -m pytest tests/test_model_conventions.py -q -k Term_US_SEC
python -m pytest tests/test_compiled_conventions.py -q -k Term_US_SEC
python -m pytest tests/test_term_life_us_sec.py -q -m cython # the compiled tests alone